Merge pull request #180 from pabaillon/patch-5

Update installing-latex.md

docs/fr/core/assets-manager.md

@@ -0,0 +1,40 @@
+# Assets Manager
+
+Zettlr 2.0 a introduit un nouveau gestionnaire d'assets qui vous permet de gérer tous les assets statiques qui sont stockés sous forme de fichiers dans votre répertoire de données utilisateur. Parmi ceux-ci figurent les nouveaux fichiers par défaut, votre CSS personnalisé et des extraits. Bien qu'il soit possible de modifier ces fichiers en externe, le gestionnaire d'assets vous offre un moyen complet de le faire depuis l'application elle-même.
+
+![The assets manager](../img/assets_manager.png)
+
+You pouvez accéder au gestionnaire d'Assets via "Zettlr -> Assets Manager" (macOS) ou "Fichier -> Preferences -> Gérer les Assets" (Windows/Linux).
+
+Le gestionnaire d'Assets vous permet d'éditer vos fichiers en utilisant la coloration syntaxique correcte et le rend plus facile que les éditeurs externes. Pour voir ce que vous pouvez modifier et comment le faire de manière productive, consultez les parties correspondantes de la documentation :
+
+* [Defaults files](defaults-files.md)
+* [Custom CSS](custom-css.md)
+* [Snippets](snippets.md)
+
+> The assets manager replaces the old PDF preferences dialog. The new assets manager gives you not just all the settings of the PDF preferences dialog, but many more.
+
+## How to Adapt the PDF Preferences
+
+Since 2.0, there is no dedicated PDF Preferences dialog anymore. Rather, you can now fine tune those settings which were present in that dialog along side a magnitude of more settings. To simply restore the old PDF preferences and then adapt them, you can easily copy the following snippet into the `variables`-section of the exporting defaults file for PDF documents:
+
+```yaml
+# Omitted content of the defaults file ...
+variables:
+ # mainfont and sansfont work for the default pdf-engine "xelatex"
+ # Should you choose to use pdflatex, you can set the font using the property
+ # "fontfamily". For more information, see https://pandoc.org/MANUAL.html#fonts
+ mainfont: "Times New Roman"
+ sansfont: "Arial"
+ linestretch: 1.3 # 1.3 means 130% linespacing
+ papersize: a4 # Can also be a5, letter, legal, etc.
+ margin-left: 2cm
+ margin-right: 2cm
+ margin-top: 2cm
+ margin-bottom: 2cm
+# Further omitted content ...
+```
+
+All variables that you can set here are [documented in the Pandoc manual](https://pandoc.org/MANUAL.html#variables).
+
+> Tip: You can define every variable also within the YAML frontmatter of any file. The only difference is that there you simply use the properties *without* nesting them under `variables`.

docs/fr/core/defaults-files.md

@@ -0,0 +1,81 @@
+# Fichiers par défaut
+
+Les fichiers par défaut sont un moyen de définir des valeurs par défaut pour de nombreuses variables que Pandoc utilise en interne pour faciliter vos importations et vos exportations. Les fichiers par défaut ressemblent à [YAML frontmatters](yaml-frontmatter.md), mais sont plus puissants et s'appliquent à tous vos fichiers au lieu d'un seul.
+
+Auparavant, Zettlr utilisait les fichiers par défaut en interne, mais Zettlr 2.0 vous donne enfin la possibilité de modifier ces fichiers vous-même.
+
+> La modification de ces fichiers peut être un peu délicate, alors attendez-vous à exporter un fichier de test plusieurs fois avant de le faire correctement. C'est un processus d'essai et d'erreur. Cependant, Zettlr est livré avec des paramètres par défaut, donc si vous n'avez pas d'exigences particulières, vous pouvez laisser ces fichiers tels quels.
+
+## Que sont les fichiers par défaut?
+
+Les fichiers par défaut sont des fichiers YAML qui contiennent des propriétés pouvant être utilisées pour contrôler le comportement de Pandoc pour un format d'exportation ou d'importation donné. Ils résident dans votre dossier de données utilisateur et ont le format `<import/export>.<writer/reader>.yaml`, où import/export fait référence à l'endroit où le fichier sera utilisé et writer/reader fait référence au format utilisé.
+
+Zettlr a besoin de certains fichiers par défaut, car pour chaque exportation ou importation, il transmettra l'un de ces fichiers à Pandoc. Ainsi, à chaque démarrage, Zettlr vérifiera l'existence des fichiers requis et les créera si nécessaire.
+
+> La documentation complète sur ce que vous pouvez faire avec les fichiers par défaut se trouve dans le [Manuel Pandoc](https://pandoc.org/MANUAL.html#default-files). Assurez-vous de vous référer à ce manuel lorsque vous modifiez les fichiers par défaut.
+
+## Requirements for Defaults Files
+
+The defaults files as used by Zettlr have a certain set of requirements which you must keep in mind when editing them. First, you should never change the `writer` and `reader` properties except for adding markdown extensions (see info box below). These properties can be set because you could, in theory, use a default file for several conversion strategies. However, since Zettlr allows you to export and import a certain set of files, it is smarter to offer you a range of defaults files where these properties are fixed. If you, for example, exchange a writer and a reader property, Pandoc might complain.
+
+Next, whenever Zettlr imports or exports a file, it will read in the corresponding defaults file and modify it in specific ways. In general, Zettlr will try to only amend the properties you define in a defaults file instead of replacing them. For example, Zettlr will check if you have already defined a bibliography in there, and add your main library to that array so that those citation libraries you have already defined will not be lost. The input and output files, however, will be replaced internally, so defining a few files in there will have no effect.
+
+Other than that, however, you are free to do whatever you need to the defaults files in order to adapt the imports and exports to your liking.
+
+> We mentioned that you should not change the `writer` or `reader` properties. However, there is a certain leverage. Pandoc supports Markdown extensions (i.e. for smart quotes, emojis, etc.). These are specified by adding them after the `reader` or `writer` properties using `+`-signs. So if you require extensions to the standard Markdown reader, you can of course add these to the `reader` or `writer` properties. Example: `reader: markdown+definition_lists+mmd_title_block+bracketed_spans+fenced_divs`. This will still use the same reader, but configure it (in this example) to additionally use definition lists, multi-markdown title blocks, bracketed spans, and fenced divs.
+
+## Which Variable Overwrites Which?
+
+The last question you might be interested to know about is the way all the different variables you can define to control Pandoc interfere with each other. It is paramount to understand how Pandoc determines the final and effective set of parameters which it will then use to facilitate your import or export. In below's graphic, you can see how each import or export is being done.
+
+![Pandoc's internal Variable Resolution](../img/pandoc_variable_resolution.png)
+
+First, Pandoc will load its own internal defaults which are hard-coded into the binary (and which are the reason why you do not have to define _all_ variables every time).
+
+Second, Pandoc will load in the defaults file Zettlr provides it with. Every variable defined in there will replace the default inside Pandoc's configuration.
+
+Third, Pandoc will parse the YAML frontmatter(s) of the file(s) you are currently trying to import or export. These variables can replace those set by the defaults files, but usually not all. You may notice that defaults files can contain a metadata field, and any value in there can generally be replaced by a YAML frontmatter property. Please see the documentation on [YAML frontmatters](yaml-frontmatter.md) for more information.
+
+**Example**: Let us assume you have defined a `title` for all your Word exports in the defaults file for Docx. If you do not use any frontmatter, this variable will be used for each and every export to Docx. But if you specify the `title` property inside a YAML frontmatter, this file – when exported to Docx – will have its own title set.
+
+> One common use-case for defining variables inside a defaults file which you could also define on the level of YAML frontmatters would be the `lang`-property. By default, Pandoc sets the language of each import and each export to `en-US`, yielding US-American number delimiters and quotes. If you regularly export into, say, French, it might make sense to set the `lang` property directly in your defaults files to `fr` so that files are being exported using that locale by default. Then you can still overwrite the property to something different within individual files by setting the corresponding YAML frontmatter variable.
+
+## How To Customize Exports
+
+The defaults files are a very powerful, but at the same time very complex way of customizing your exports. In this section we want to give you a heads up of how to use defaults files to the fullest extent.
+
+> This section is still work in progress.
+
+### Preliminaries
+
+Pandoc contains a powerful **templating-system** to customize your exports. Within the default templates Pandoc provides (and uses, if you do not explicitly provide a custom template), you will find statements such as `$for(hyperrefoptions)$,$hyperrefoptions$$endfor$`. In this case, `hyperrefoptions` is a variable that you can set. Depending on the template, different variables are available. You can find a comprehensive list of all variables used in the default templates [here](https://pandoc.org/MANUAL.html#variables).
+
+### Setting Variables
+
+The default variables can sometimes be undesirable (Pandoc sets U.S. Letter as the default papersize, which is undesirable in other parts of the world; Zettlr changes this default to DIN A4, which also might not suit everyone), so you can set them to different values. There are two general ways of doing this:
+
+1. The YAML frontmatter of a file
+2. The corresponding defaults file
+
+If you were to change, say, the papersize variable only for a specific file, you can simply add that variable with the corresponding value as a top-level property. Example:
+
+```yaml
+---
+title: Document title
+author: John Doe
+papersize: legal
+---
+```
+
+This would set the papersize to "legal". Note that in the default template, the word `paper` is already set, so if you are somewhat familiar with LaTeX, `a4paper` would not work since in the template it would become `a4paperpaper` which is not a correct value.
+
+The second way to change a variable is to change it for every single export (unless overwritten by a frontmatter, that is). This you can do in the defaults file, but please note that in defaults files you have to put those variables under a special section called `variables`. Example:
+
+```yaml
+# ... snip ...
+variables:
+ papersize: legal
+# ... snip ...
+```
+
+You can also make use of this templating system yourself. If you want to write a custom template, you can add statements such as `$if(myvariable)$$myvariable$$endif$` and insert the variable `myvariable` into any frontmatter or defaults file, and it will be replaced with whatever value you set it to.

docs/fr/core/snippets.md

@@ -0,0 +1,76 @@
+# Extraits
+
+Depuis la version 2.0, Zettlr est livré avec un système complet d'extraits et de modèles. Cela vous permet de définir certains morceaux de texte que vous avez tendance à écrire plus souvent, et également d'insérer des variables dynamiques. Le système lui-même est basé sur la syntaxe TextMate et en tant que tel, dans une certaine mesure, interopérable avec les extraits que vous possédez déjà pour TextMate ou d'autres systèmes prenant en charge cette syntaxe, tels que VisualStudio Code.
+
+
+## Gestion de vos extraits
+
+You can manage your snippets using the [assets manager](./assets-manager.md).
+
+À gauche, vous pouvez trouver une liste de tous les extraits ; initialement, il sera vide. Vous pouvez ajouter un nouvel extrait en cliquant sur le bouton "+" en bas de la liste. Il sera initialement nommé "snippet-X" (où X est un nombre). Si vous sélectionnez un extrait, l'éditeur d'extraits affichera le contenu du fichier dans l'éditeur et le nom dans le champ de texte au-dessus.
+
+Après avoir apporté des modifications à l'extrait de code, assurez-vous de cliquer sur "Enregistrer" ou d'appuyer sur `Cmd/Ctrl+S` pour conserver vos modifications. Pour renommer un extrait, tapez simplement le nouveau nom dans le champ de texte du nom au-dessus de l'éditeur d'extraits et cliquez sur le bouton.
+
+> Notez que le nom de votre extrait ne peut contenir que les lettres A à Z, des chiffres, des traits d'union et des traits de soulignement. En effet, le nom de l'extrait de code sera utilisé pour la saisie semi-automatique dans l'éditeur. Si vous tapez d'autres lettres, elles seront remplacées par un trait d'union.
+
+Enfin, l'éditeur prend en charge la coloration syntaxique spéciale qui vous aide à écrire vos extraits. Les variables qui ne sont pas prises en charge seront marquées en rouge afin que vous voyiez immédiatement qu'il pourrait y avoir une erreur.
+
+> Vos extraits sont en fait des fichiers qui résident dans un répertoire au sein de vos données d'application. Veuillez vous référer au [manuel d'installation](../install.md) pour connaître l'emplacement précis de ce dossier. Les fichiers d'extraits suivent toujours le modèle `<nom>.tpl.md`, où `<nom>` fait référence au nom que vous donnez aux extraits dans l'interface graphique. Cela peut être utile à des fins de sauvegarde ou de partage.
+
+
+## La syntaxe des extraits
+Les extraits suivent la syntaxe de TextMate qui peut être facilement résumée :
+
+* `$[1-9]`: By typing a dollar sign followed by a number, you add a tabstop. After you inserted a snippet, this will allow you to guide your tabs according to the numbers (so repeatedly typing `Tab` will move through these by number ascending).
+* `$0`: The zero is a special tabstop. It's not the first tabstop, but the last one. If you omit this, the cursor will end up after the inserted snippet, but by placing this somewhere in the text, you can control this behaviour.
+* `${[0-9]:[.]}`: By surrounding the tabstop with curly brackets and adding a colon, you can define some text that will be placed by default at this position. As soon as you get to the specified tabstop, this text will be selected. You can either leave it in place by simply pressing `Tab` again, or easily overwrite it. Example: `${5:Some text}` would result in the text "Some text" to be placed at tabstop number five, which will be selected when you get there by pressing `Tab`.
+* `$[A-Z_]`: If you use Latin characters instead of numbers, you define a variable that can be replaced when you insert a snippet. Variables consist only of uppercase characters and underscores. If you make a typo, you can spot this because the variable will be coloured red.
+* `${[A-Z_]:[.]}`: Just like with tabstops, you can define default text for variables, which will be inserted if the variable cannot be inserted (e.g. the `CLIPBOARD` variable can be empty if no text is in the clipboard).
+
+Enfin, les variables disponibles sont :
+
+* `CURRENT_YEAR`: The current year (4 digits)
+* `CURRENT_YEAR_SHORT`: The abridged current year (2 digits)
+* `CURRENT_MONTH`: The current month (2 digits)
+* `CURRENT_MONTH_NAME`: The full name of the month (localised according to your app settings)
+* `CURRENT_MONTH_NAME_SHORT`: The short month name (localised according to your app settings)
+* `CURRENT_DATE`: The current day of the month (2 digits)
+* `CURRENT_HOUR` The current hour (24 hour format; 2 digits)
+* `CURRENT_MINUTE`: The current minute (2 digits)
+* `CURRENT_SECOND` The current second (2 digits)
+* `CURRENT_SECONDS_UNIX`: The current unix timestamp in seconds
+* `UUID`: A UUID version 4
+* `CLIPBOARD`: The contents of your clipboard (text only)
+* `ZKN_ID`: Generate a Zettelkasten ID (according to your pattern)
+* `CURRENT_ID`: Holds the currently assigned Zettelkasten ID to the file
+* `FILENAME`: Holds the filename of the current file
+* `DIRECTORY`: Holds the directory path for the current file
+* `EXTENSION`: Holds the file extension for the current file
+
+## Travailler avec vos extraits
+
+Après avoir créé vos extraits de code, vous pouvez les utiliser avec la syntaxe de saisie semi-automatique connue. Vous pouvez activer la saisie semi-automatique des extraits en tapant deux-points (`:`), ce qui ouvrira une liste avec vos extraits disponibles. Vous pouvez rechercher un extrait en tapant quelques caractères de son nom. Étant donné que les noms d'extraits de code ne peuvent pas contenir d'espaces, les deux-points sont un moyen simple d'activer ceci : si vous ne souhaitez pas insérer d'extrait de code, tapez simplement un espace (ou tout caractère non alphanumérique) pour refermer la liste déroulante.
+
+Après avoir sélectionné un extrait, Zettlr insérera d'abord l'extrait, puis remplacera toutes les variables selon la syntaxe décrite ci-dessus. Ensuite, il créera des marqueurs de texte indiquant la position de tous les tabulations et activera une nouvelle configuration de clavier temporaire qui remappera deux touches : `Tab` et `Esc`. Chaque fois que vous appuyez sur `Tab`, Zettlr passera au tabstop suivant. Si vous souhaitez arrêter prématurément la tabulation dans ces tabulations, vous pouvez appuyer sur "Échap". Le keymap sera supprimé et vos touches `Tab` et `Esc` fonctionneront normalement lorsque tous les tabstops ont été atteints ou lorsque vous appuyez sur `Esc`.
+
+## Un extrait pour commencer
+
+Si vous êtes intéressé par ce que les extraits peuvent faire, copiez et collez simplement ce qui suit dans un nouvel extrait. Essaye le!
+
+
+
+```markdown
+---
+title: "${1:Enter a Title}"
+date: $CURRENT_YEAR-$CURRENT_MONTH-$CURRENT_DATE
+author: ${2:Enter your name}
+id: $ZKN_ID
+---
+
+# ${1:Enter a Title}
+
+$0
+```
+Voici à quoi cela ressemble après avoir complété automatiquement le nom de l'extrait de code. Vous pouvez clairement voir que les tabstops restants sont colorés afin qu'ils soient facilement discernables.
+
+![An example snippet in autocomplete mode](../img/snippets_example.png)