Enhancement to include a glossary of acronyms used

[kellijohnson-NOAA]

Thanks to @iantaylor-NOAA for first noting that we should have an option to create a glossary in #20. I have moved this to its own issue because I feel that the enhancement will take a while and I wanted to separate it from the lack of documentation about the glossaries package issue.

What are the main goals of the glossary that we want to facilitate (list all options below and eventually cross out the ones we think are bad ideas):

1. provide a list of acronyms and their long form because as @iantaylor-NOAA noted below " assessment docs [are] routinely 300 pages long and they are rarely read front to back so the first occurrence of any acronym is often far away in space and time from the subsequent occurrences. A list of acronyms is simple way to reduce confusion about those acronyms."
2. define acronyms
3. define terms used in the stock assessment such as maximum sustainable yield
4. alphabetize the list
5. bookdown issue
6. ...

What should the format of the glossary be, see Dickimaw Books for options

1. alphabetical
2. grouped
3. in order of use

There are a few routes we can take,

1. provide documentation for how to add a glossary
2. automatically include a glossary
3. make an option where users can specify if they want a glossary when the call draft().

I think for right now, I will just explore using a glossary in the lingcod assessment and then we can go from there.

[iantaylor-NOAA]

Thanks @kellijohnson-NOAA. I should have thought to add this as a separate issue to begin with. Experimenting with lingcod and going from there seems like a good plan.

My preference would be to initially just make an alphabetical list of acronyms as in https://www.dickimaw-books.com/gallery/index.php?label=acronym-nodesc. As noted in the README (thank you!), glossaries spells out the acronyms on first use. But these assessment docs routinely 300 pages long and they are rarely read front to back so the first occurrence of any acronym is often far away in space and time from the subsequent occurrences. A list of acronyms is simple way to reduce confusion about those acronyms.

I could imagine that a glossary like that used for Pacific Hake: https://github.com/pacific-hake/hake-assessment/blob/master/doc/appendix-glossary/appendix-glossary.rnw could be useful in the future, but I'm not sure that's worth the effort for this year.

[kellijohnson-NOAA]

• [ ] The first step towards making this functional is to fix the instructions 😆 because I am wrongly telling people to use just \gls{} and versions of that rather than \acr{} where the latter is for acronyms, i.e., things that don't need a definition only spelling out of the full words.
• [ ] Create a list of words that need a glossary and define them. Perhaps the Pacific Hake glossary could be used to start.
• [ ] Read the beginner manual for glossaries to understand better what the next steps are

[iantaylor-NOAA]

Bumping this issue and tagging @okenk and @brianlangseth-NOAA since Marlene asked about glossaries in the documents she just reviewed.

In the 2 years since I wrote "I'm not sure that's worth the effort for this year", the https://github.com/pfmc-assessments/sa4ss/commits/main/inst/rmarkdown/templates/sa/skeleton/sa4ss_glossaries.tex file has been created and expanded, but I'm not sure what it would take to use it to make a glossary ~file~ page [corrected after initial comment].

[kellijohnson-NOAA]

@iantaylor-NOAA what exactly was asked of you? Currently, all we have functionality for is acronyms. We do not have definitions of terms saved anywhere, which is what I think of when I hear glossary.

[iantaylor-NOAA]

The comment we got was "If not using an Acronyms Used in Assessment type page at the beginning, then the first instance of any acronym will need to be spelled out. I realize Exec Sum might be copied from other sections that already had it spelled. I believe these need to be spelled out here as first instance, for Alaska Fisheries Science Center (AFSC)/Northwest Fisheries Science Center (NWFSC)...." In reference to "AFSC/NWFSC West Coast Triennial Shelf Survey (Triennial Survey)" as created by \gls{s-tri}.

So good point about no definitions, which was what I also think of when I hear "glossary", so really I'm thinking of an Acronyms Used in Assessment page which would save folks from having to find the first appearance of any acronym.

[kellijohnson-NOAA]

@iantaylor-NOAA you can download a new version of the glossaries file which no longer uses nested acronyms and it will fix your issue.