Abbreviations, acronyms, and glossary

[FedericoTartarini]

First of all, I would like to congratulate you for the amazing work you have done and for releasing mystmd. It is amazing.

I identified what could be a missing functionality in mystmd which I think is super useful when writing scientific papers.

In LaTeX I make use of the glossary and the acronym packages. These packages are great since I can import them in the preamble. Then I can define the acronyms/nomenclature I want to use and then I can reference them in the text. See code snippet below. This has two great benefits:

1. The definition is spelled out the first time I reference the variable in the text, as per the journal requirement
2. I do not have to type a complex variable name each time I want to refer to the variable. I can use \ac{t} rather than having to write $t_{db}$

\usepackage[printonlyused]{acronym}

\begin{document}

\section*{Nomenclature}

\renewcommand{\baselinestretch}{0.75}\normalsize
    \begin{acronym}[longest]
    \acro{HTML}{Hypertext Markup Language}
    \acro{t}[$t_{db}$]{dry-bulb temperature \acroextra{[°C]}}
    \end{acronym}
\renewcommand{\baselinestretch}{1}\normalsize

In the text I can refer to the variable t using the command \ac{t}.

mystmd

Mystmd offers two solutions to this problem: abbreviations and glossaries. However, the issues that I identified are:

1. The variable name is not spelled out the first time is included in the body of the document, this is not an issue in the website version of the paper since the user can over the variable name but it is an issue in the PDF.
2. If I want to use a complex abbreviation name it is hard to reference it in the text.
3. Abbreviations are only shown in the text but I cannot list them in a Section called for example (Nomenclature or Abbreviations).

is there a way to implement the functionalities offered by the acronym package in myST? I may offer to help but I am not sure how to get start and implement this feature.

[agoose77]

MyST has support for first-time-long acronyms, but it is not yet exposed to the UI (c.f.
#536). We should certainly think about doing that, although the frontmatter is possibly not the place for it.

Being able to list all abbreviations seems like a useful feature! We could imagine an abbreviations directive that lists them:

```{abbreviations}
```

I'd be happy to help you get started in contributing to this, and I think there are some good up-front questions to think about:

• Should abbreviations look at the current file, or all files? (Right now, firstTimeLong acts per-file, not per-project). That makes sense to me.
• Should we be able to define abbreviations in a directive (i.e. can abbreviations define abbreviations?)

Pinging @fwkoch for some thoughts here.

[FedericoTartarini]

Thank you for your quick reply. Great to hear that MyST has support for first-time-long acronyms. I am not sure where it is the best place to implement this function but I think it is super useful to have it somewhere.

Each abbreviation should have:

• a key that we can reference in the text,
• a short version,
• a long version,
• a unit,
• ideally we may also want to be able to pass a plural.

I think that:

• abbreviations should only be defined once in the parent file and by default they could be first time long in each subfile. However, there should be a flag to disable that. When I write papers I like to separate the intro, method, results and discussions in different files so it is easier to collaborate and faster to compile the file in LaTeX but the fisrtTimeLong should only be defined when the variable is first introduced and not in every section. I know MyST is different from LaTeX and people here may not separate their documents in sub-files.
• I did not understand your second comment. Should we be able to define abbreviations in a directive (i.e. can abbreviations define abbreviations?)

I am taking some time off and I will be back at work on the 10th of June, but I am happy to look into it when I get back. I am not sure I have the necessary skills to implement this function but I can look into it.