List of Acronyms one single page

[espinielli]

I am using this extension for a Quarto website and when I insert the following configuration in the _quarto.yml

filters:
  - acronyms
acronyms:
  loa_title: "List of Acronyms"
  include_unused: false
  insert_loa: "end"
  insert_links: true
  id_prefix: "acronyms_"
  sorting: "alphabetical"
  non_existing: "key"
  style: "long-short"
  fromfile:
    - media/acronyms.yml

I get a "List of Acronyms" for every .qmd file. I reduced the issue by adding the above config only on the pages needing it, but I would like to know whether it would be possible to further reduce the "List of Acronyms" sections by just having one single page for all acronyms used in the website. Just asking... Thanks a lot in advance!

[rchaput]

The problem is that Quarto renders each document independently, so the acronyms extension does not even know that you are building a website with several pages. For each page, acronyms is called with a "fresh state".

One way to reduce the problem would be to:

• Print the List of Acronyms only on a dedicated page

filters:
  - acronyms
acronyms:
  include_unused: true
  insert_loa: "end"
  loa_title: "List of Acronyms"
  sorting: "alphabetical"
  fromfile:
    - media/acronyms.yml

Note the include_unused: true, because on this specific page, no acronym will be considered "used" (they do not appear anywhere), so we must force them to be printed in the LoA anyway.

• Then, on each page, disable the List of Acronyms and the links:

filters:
  - acronyms
acronyms:
  insert_loa: false
  insert_links: false
  non_existing: "key"
  style: "long-short"
  fromfile:
    - media/acronyms.yml

Unfortunately, we must disable the links because acronyms would not know that the LoA exists on a different page, and I am pretty sure the link would not work between different pages. Again, this is due to Quarto rendering each document separately.

To solve this, I would need to tap into Quarto's cross-section references mechanism, and I am not sure how it works.

[espinielli]

For a book, a single place where to place acronyms is surely needed. No idea too where to look for how to do it...

[rchaput]

I absolutely agree with you. At the very least, having the choice between a single list of acronyms and one list per chapter/section/whatever...

In Quarto's current version, I do not think we can automate this, or get the full features (cf. my answer above). However, Quarto plans to re-create the cross-ref system in v1.4 or v1.5 (see https://github.com/quarto-dev/quarto-cli/issues/4944 ; https://quarto.org/docs/prerelease/1.4/crossref.html ; https://quarto.org/docs/prerelease/1.4/lua_changes.html ), maybe we will be able to use custom cross-refs (similar to figures and tables) for acronyms. That would greatly simplify the linking between several chapters/sections.

In the meantime, I will add a small example in the documentation on how to best use acronyms in a multi-document context (although it may not work perfectly).

[rchaput]

I have published an article on the documentation website describing how to use acronyms in a multi-document project, such as a book or website; this includes your use-case of having a single List of Acronyms.

You can follow the instructions at: https://rchaput.github.io/acronyms/advanced/multi_document.html

I'm leaving this issue open until I can properly implement all features, especially cross-reference links (waiting for Quarto updates to do so).