Added an example for multi-document projects

As per issue #11, the default configuration of acronyms does not work
very well on multi-document projects, especially websites and books.
This is vastly due to the way Quarto renders each file separately,
but can be mitigated by adjusting acronyms' configuration.

This new documentation page demonstrates two different setups for such
multi-document projects: one with a single List of Acronyms, and one
with a separate list on each page.

In addition, refactored the previous `advanced_usage.qmd` article into
a new folder ("Advanced usage" in the menu), and splitted the sections
into separate articles in this folder. This is because the "Advanced"
articles can become quite long, and would not be very readable on the
same page.

docs/_quarto.yml

@@ -23,8 +23,10 @@ website:
         menu:
           - articles/options.qmd
           - articles/styles.qmd
-          - text: -------
-          - articles/advanced_usage.qmd
+      - text: Advanced usage
+        menu:
+          - advanced/external_file.qmd
+          - advanced/multi_document.qmd
     right:
       - text: Source Code
         href: https://github.com/rchaput/acronyms

docs/articles/advanced_usage.qmd → docs/advanced/external_file.qmd

@@ -1,15 +1,18 @@
 ---
-title: "Advanced usage"
+title: "Defining acronyms in external file(s)"
 description: >
-  Learn additional tips on how to best use **acronyms**.
+  Learn how to define acronyms in one or several external files, which can
+  be reused throughout documents or projects (rather than directly in the
+  YAML metadata).
 ---
 
-## Defining acronyms in external file(s)
 
 Whereas defining acronyms directly in the YAML metadata is the most
 straightforward way, **acronyms** also support reading definitions
 from one (or several) pseudo-YAML file.
 
+## Referring to an external definition file in a Quarto document
+
 To do so, simply specify the file path in the `fromfile` attribute of
 the YAML metadata.
 This behaviour is particularly useful if you want to define acronyms
@@ -45,6 +48,8 @@ In our examples, we thus assume that the `acronyms.yml` (respectively,
 `acronyms1.yml` and `acronyms2.yml`) live in the same folder as the qmd
 document.
 
+## Content of the definition file(s)
+
 The content of such files must be as following:
 
 ```yaml
@@ -65,17 +70,19 @@ However, only the metadata and more specifically the `acronyms.keys` field
 is used. No other option is taken into account. The eventual document
 body is ignored as well.
 
+## Loading order for acronyms
+
 The acronyms are read in the following order:
 
 1. Acronyms in the `acronyms.key` field of the source qmd document, in
    sequential order.
 2. Acronyms in each of the `acronyms.fromfile` files.
-  a. Files are read in sequential order.
-  b. Acronyms inside each file are also read in sequential order.
+    a. Files are read in sequential order.
+    b. Acronyms inside each file are also read in sequential order.
 
 This order is meaningful in 2 cases:
 
 - When a duplicate key is found, the behaviour (`keep` or `replace`)
-depends on the order in which acronyms are read.
+  depends on the order in which acronyms are read.
 - When the `initial` sorting is used, the List Of Acronyms displays
-acronyms in the same order as they were defined.
+  acronyms in the same order as they were defined.

docs/advanced/multi_document.qmd

@@ -0,0 +1,245 @@
+---
+title: "Using acronyms in a multi-document project"
+description: >
+  Learn how to use acronyms in several documents, for example a website or
+  book; how to control where the List of Acronyms appear, which acronyms
+  appear on which pages, etc.
+---
+
+
+Because Quarto renders each document separately, the **acronyms** extension
+does not know that your project is a multi-document one. This means that, by
+default, the rendering might not correspond to what you expect for a book
+or a website.
+
+This vignette describes how to configure **acronyms** for several use-cases,
+such as using a single List of Acronyms, or one for each chapter, etc.
+
+*Note:* Future versions of Quarto might offer new mechanisms that **acronyms**
+will be able to leverage, bringing new features to multi-document projects.
+Until then, some functionalities might not work, or require additional
+(manual) setup.
+
+## Using a single List of Acronyms
+
+The "classic" setup for a book or website is to have a single List of Acronyms
+(LoA), and have various acronyms usages throughout the documents.
+
+To achieve this, the LoA must be configured on the desired page (for example,
+the index page), and **acronyms** must be configured on each page.
+The following code blocks show the required configuration, for each of the
+project files:
+
+- `_quarto.yml`: defining the section order (to illustrate), and loading the
+  **acronyms** filter (to avoid having to add it on each page).
+
+```yaml
+project:
+  type: book
+book:
+  title: "Test book"
+  chapters:
+    - index.qmd
+    - chap1.qmd
+    - chap2.qmd
+filters:
+  - acronyms
+acronyms:
+  fromfile: acronyms.yml
+```
+
+The **acronyms** filter may also be loaded individually on desired pages, if
+it should not be enabled for some of them.
+
+- `acronyms.yml`: defining the various acronyms in an external file, to
+  simplify re-usability.
+
+```yaml
+---
+acronyms:
+  keys:
+    - shortname: acr1
+      longname: first acronym
+    - shortname: acr2
+      longname: second acronym
+---
+```
+
+See [external_file.qmd] for a detailed explanation; this file is not required
+(acronyms could be defined in each document), but greatly simplifies the setup
+and avoids potential errors.
+
+- `index.qmd`: defining the LoA in the first page; it must be set to include
+  all acronyms, even those unused, since the acronyms usages will appear on
+  other pages.
+
+```markdown
+---
+acronyms:
+  include_unused: true
+  insert_loa: false
+  insert_links: false
+---
+
+\printacronyms
+
+Home page; place here any title, or introduction...
+```
+
+The `\printacronyms` paragraph must be placed where you want the List of
+Acronyms to be shown; in this example, we put it at the beginning of the
+index page, but it could be elsewhere (after an introduction, in the last
+page, ...).
+
+*Missing feature:* the `insert_links` option must be set to `false`, because
+**acronyms** will not be able to create links between different documents.
+This could change in future versions of Quarto.
+
+- `chap1.qmd`: the first chapter; you may name this file as you want, we
+  simply reuse the name defined in `_quarto.yml`. In this file, we must setup
+  **acronyms** to *not* create a LoA.
+
+```markdown
+---
+acronyms:
+  insert_loa: false
+  insert_links: false
+---
+
+# 1st chapter
+
+This paragraph mentions \acr{acr1} for the first time.
+
+And now, in this paragraph, \acr{acr1} is in short form.
+```
+
+Note that, as mentioned previously, links are unfortunately disabled.
+If the option `insert_links` is set to `true` on this page, the acronyms will
+be provided with a link, but the link itself will not work, because the LoA
+will not be found on the same page.
+
+- `chap2.qmd`: the second chapter, just like the previous file. Again, the
+  name can be different.
+
+```markdown
+---
+acronyms:
+  insert_loa: false
+  insert_links: false
+---
+
+# 2nd chapter
+
+This paragraph mentions \acr{acr2} for the first time.
+
+And now, in this paragraph, \acr{acr2} is in short form.
+
+However, \acr{acr1} should be again in long form.
+```
+
+*Missing feature:* because a completely new instance of **acronyms** is launched
+by Quarto for each separate page, it "forgets" which acronyms have already
+been used. As described in this 2nd file, acronym *acr1* will be printed in the
+long form again, even though it was already shown in the previous chapter.
+
+
+## Using separate List of Acronyms in each page
+
+When creating a separate List of Acronyms (LoA) in each page, it should be
+configured to be printed at an appropriate location, and with an appropriate
+header.
+
+By default, the LoA would appear as the first element, which would make it the
+chapter title in a website. Instead, we want the chapter title to be the first
+element; ideally, the LoA should also be a 2nd level heading (a section rather
+than a chapter). In this example, we will also make it an unnumbered header.
+
+- `_quarto.yml`: just like the previous example, we simply load configure the
+  book, and load the **acronyms** filter.
+
+```yaml
+project:
+  type: book
+book:
+  title: "Test book"
+  chapters:
+    - index.qmd
+    - chap1.qmd
+    - chap2.qmd
+filters:
+  - acronyms
+acronyms:
+  fromfile: acronyms.yml
+```
+
+- `acronyms.yml`: defining the various acronyms in an external file, to
+simplify re-usability.
+
+```yaml
+---
+acronyms:
+  keys:
+    - shortname: acr1
+      longname: first acronym
+    - shortname: acr2
+      longname: second acronym
+---
+```
+
+- `index.qmd`: if no acronyms are used on this page, we must disable the
+  LoA creation.
+
+```markdown
+---
+acronyms:
+  insert_loa: false
+---
+
+Home page; place here any title, or introduction...
+```
+
+- `chap1.qmd`: the first chapter; you may name this file as you want. In this
+  file, we put the LoA at the beginning of the document, just below the chapter
+  title. The LoA title must be set to `""` so that we can configure it
+  manually.
+
+```markdown
+---
+acronyms:
+  insert_loa: false
+  loa_title: ""
+---
+
+# 1st chapter
+
+## List of Acronyms {.unnumbered}
+
+\printacronyms
+
+This paragraph mentions \acr{acr1} for the first time.
+
+And now, in this paragraph, \acr{acr1} is in short form.
+```
+
+- `chap2.qmd`: the second chapter, just like the previous file. Again, the
+  name can be different. In this file, we put the LoA at the end.
+
+```markdown
+---
+acronyms:
+  insert_loa: false
+  loa_title: ""
+---
+
+# 2nd chapter
+
+This paragraph mentions \acr{acr2} for the first time.
+
+And now, in this paragraph, \acr{acr2} is in short form.
+
+However, \acr{acr1} should be again in long form.
+
+## List of Acronyms {.unnumbered}
+
+\printacronyms
+```