feat: Improve documentation on customizing the reference section

Author: nathanlesage

docs/en/editor/citations.md

@@ -162,42 +162,92 @@ Second, you can set specify a CSL style for a specific project. With your projec
 
 ## Customizing the List of References
 
-By default, Pandoc will simply append a list of references to the end of your documents without any decoration. Therefore, you need to perform a few housekeeping steps to ensure bibliographies are correctly rendered.
+By default, Pandoc will simply append a list of references to the end of your documents without any decoration. Therefore, you need to perform a few housekeeping steps to ensure bibliographies are properly rendered.
 
 ### Adding a Section Header
 
-The simplest solution to displaying the bibliography correctly is to end your document with a heading that is called “References,” “Bibliography,” or similar. While this may look a little off when looking at the document in Zettlr, this will ensure that the bibliography has an appropriate heading on export.
+The simplest task is to provide a section header for the list of references. The easiest way to do so is to append a heading called “References,” “Bibliography,” or similar to the end of your document. While this may look a little off when looking at the document in Zettlr, this will ensure that the bibliography has an appropriate heading on export. Since Pandoc will simply append the rendered bibliography to your document, this “lone” heading will then become the heading for your list of references upon export.
 
-To make this more explicit, notice that you can specify the precise location of where the references will be inserted with Pandoc's block syntax. By explicitly adding that block, you can visually indicate where the references will end up:
+However, this may become cumbersome quickly, as you create more and more files. It would be great if you could automate this process. Fortunately, you can do so.
+
+Instead of specifying the heading section everytime, you can provide a default name for each export profile. To do so, head into the [Assets Manager](../export/assets-manager.md), e.g., by pressing <kbd>Cmd/Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>,</kbd>. In the “Export” tab, select the profile you wish to provide a default reference section for, and add the following code:
+
+```yaml
+metadata:
+  reference-section-title: "References"
+```
+
+Customize “References” to your liking (e.g., “Bibliography,” or a translation thereof). If the profile already has the propery `metadata`, place the `reference-section-title` in there instead of duplicating the property. Ensure proper indentation.
+
+### Customizing the `reference-section-title` on a per-file basis
+
+Specifying the `reference-section-title` in an export profile has the benefit that you won't have to remember to add a heading anymore, but it will also mean that all your files will receive the default wording. What if you want certain files to have a different section header? Pandoc allows you to also provide this label using the [YAML frontmatter](./yaml-frontmatter.md). To do so, simply place the `reference-section-title` on its own line (not indented) within a file's YAML frontmatter. This will overwrite the default you have provided in the defaults file (hence the name!).
+
+!!! warning
+
+	The export profile overwrites the `reference-section-title` from the frontmatter. This means, if you specify `reference-section-title: Bibliography` in your frontmatter, but have placed a `reference-section-title: References` in the `metadata` property of your export profile, Pandoc will use the latter, and not the former. This is why Zettlr's built-in profiles do not ship with a default for `reference-section-title` built-in. For some use-cases, it may be easier to leave out the `reference-section-title` from the export profile entirely and specify it manually for each file. You can also use [Snippets](./snippets.md) to provide templates for various types of reports that come with the correct `reference-section-title`.
+
+### Specifying the Location of the List of References
+
+By default, Pandoc will append the rendered reference section to your document, which in almost all cases is sufficient. However, in some rare circumstances, this is not ideal. For example, imagine you are writing a report with a few appendices. Usually, you want the list of references to appear after the main body of the report, but before any of the appendices.
+
+!!! warning
+
+	If you explicitly specify the location of your references by placing a `#refs`-container, Pandoc will ignore your `reference-section-title`. In this case, you must specify the heading manually.
+
+To do so, you can tell Pandoc explicitly where to place the list of references. You do so by creating a container with the ID `#refs`. Pandoc recognizes this, and will place the bibliography into this container, instead of just appending the list. For example:
 
 ```markdown
+## Conclusion
+
+Some concluding thoughts ...
+
 ## References
 
 ::: {#refs}
 :::
+
+## Appendix A
+
+Some appendix information...
 ```
 
 Pandoc will replace the three-colon-curly-bracket construction with your list of references.
 
 !!! tip
 
-    This also means that you can embed your list of references at any point in your document. You could, e.g., add appendices after the `{#refs}`-block.
+    This also implies that you can provide the list of references multiple times. Pandoc will place the list of references into any container with the ID `#refs`. You can read more on placing the bibliography in the [Pandoc manual](https://pandoc.org/MANUAL.html#placement-of-the-bibliography).
 
-### Setting a Section Header in the YAML Frontmatter
+### Formatting the List of References
+
+Most of the formatting of the list of references will be derived from the specific citation style that you use. These citation styles will, for example, specify whether the list of references should use a hanging indent, how much the entries should be spaced, and more. However, often, these provided formatting rules are very spacious, and sometimes you need to make the layout of the reference section tighter. To do so, you effectively have two common routes available.
 
-If you do not want to always specify the section title manually, you can also automate this process. In your file’s [YAML frontmatter](./yaml-frontmatter.md), you can add a property `reference-section-title: Bibliography`. Replace “Bibliography” with whatever the title should be called.
+The first one is to override the basic styling of the list. You do so by providing certain attributes to the `#refs`-container (meaning that to format the list of references, you will have to explicitly specify the location of the list of references). This is only sparsely documented by Pandoc, and support is somewhat lackluster, but you can provide the following attributes:
+
+```md
+:::{#refs .hanging-indent entry-spacing="0" line-spacing="2"}
+:::
+```
+
+The class `hanging-indent` will forcefully enable a hanging indent even for citation styles that do not prescribe it. It is automatically added when the citation style demands it.
+
+The attributes `entry-spacing` and `line-spacing` respectively determine how much space there should be between individual entries, and lines. They are provided in percentage points, where `1` equals 100%. So, an entry-spacing of `0` will ensure that the individual entries are back-to-back, while an entry-spacing of `2` will mean that there are two lines of distance between each entry.
 
 !!! note
 
-    You can read more on placing the bibliography in the [Pandoc manual](https://pandoc.org/MANUAL.html#placement-of-the-bibliography).
+	Support for these formatting rules is not fully clear. Some citation styles and some export profiles appear to be impervious to changing the line-spacing. Use these with caution. To better control formatting, continue reading.
 
-### Formatting the List of References
+The second route to adjust the formatting of the list of references is to directly overwrite the styles. This gives you more control over the list of references, but depending on how you do it, you may restrict yourself to only a single export target. For example, to change how the references are displayed in HTML, you will need to use CSS. To change how they are displayed in PDF files, you will need to use LaTeX directives (or Typst or tectonic directives, depending on which engine you utilize).
+
+When you use CSS, you can target some CSS classes:
 
-When you add citations to your files, you sometimes need to adjust how they will be displayed on export. While exporting to Word or LibreOffice allows you to fine-tune your references afterward, this is not possible if you export to PDF.
+* `.references`, `.csl-bib-body`: These classes are applied to the surrounding container of each list of references.
+* `.hanging-indent`: This class is also appended to the container, either if the CSL style requires it, or if you explicitly specified it.
+* `.csl-entry`: This class is applied to an individual entry, and allows you to change properties of the individual entries.
 
-Thus, you may need to add a few style directives to your file. Here we describe how to change the appearance of PDF files. To change the appearance of HTML exports, you can use CSS.
+***
 
-LaTeX uses lengths to determine the overall measurements of the exported PDF. These lengths are normally set globally, but they can be changed for different parts of document. One of these lengths is `parindent`, which controls the hanging indent of all paragraphs.
+LaTeX, on the other hand, uses lengths to determine the overall measurements of the exported PDF. These lengths are normally set globally, but they can be changed for different parts of document. One of these lengths is `parindent`, which controls the hanging indent of all paragraphs.
 
 Whenever you use the command `\setlength` LaTeX will overwrite the specified length from wherever it encounters this command until you use `\setlength` again. Since the references section is formatted using paragraphs like the rest of the document, they will be formatted in this default style. To re-format the list of references, you should overwrite these just before the list of references.