Using a list of acronyms after the appendix

[hochleitner]

I've had some requests on how to use a list of acronyms with our template. Especially for technical documents, this makes sense to have the long form of the acronym properly displayed the first time together with the short version and then just the short version from now on. And should you add another use of that acronym even before the first occurrence, this one becomes the long version, and you don't have to worry about inconsistencies.

Additionally, a list of acronyms in the back is sometimes required by the supervisor. These packages also do this.

I've tried a few packages: nomenctl, glossaries, acronyms - but they all rely on calling external tools such as makeindex, makeglossaries, which is cumbersome, error-prone to beginners and also not that easy with Overleaf.

So I resorted to acro, which does not have that requirement, is modern, has a clean syntax and just worked out of the box.

This code in the preamble,

\usepackage{acro}
\acsetup{
	first-style=long-short, % long-short|short-long|short|long|footnote
	subsequent-style=short, % long-short|short-long|short|long|footnote
	single=false, % set to "true" if an acronym that has only been used once should not be part of the list of acronyms
	make-links=true, % set to "true" to link acronyms with their entry in the list of acronyms
	list/display=used, % set to "all" to print all defined acronyms, no matter if they are referenced or not
	list/template=toc
}
\input{back/acronyms} % define your acronyms there

this code to define acronyms (this goes to back/acronyms.tex in this case)

\DeclareAcronym{jpg}{
	short=JPEG,
	long=Joint Photographic Experts Group,
	alt=JPG,
	sort=jpeg,
	tag=acro
}

\DeclareAcronym{ufo}{
	short=UFO,
	long=unidentified flying object,
	foreign=unbekanntes Flugobjekt,
	foreign-plural-form=unbekannte Flugobjekte,
	foreign-babel=ngerman,
	long-indefinite=an,
	tag=acro
}

% Nomenclature (tagged "nomencl")
\DeclareAcronym{pi}{
	short=\ensuremath{\pi},
	long=The ratio of a circle's circumference to its diameter,
	sort=pi,
	first-style=short,
	tag=nomencl
}

\DeclareAcronym{c}{
	short=\ensuremath{c},
	long=The speed of light in vacuum,
	sort=c,
	first-style=short,
	tag=nomencl
}

this one to reference the acronyms:

Werden viele Abkürzungen verwendet, empfiehlt sich das \texttt{acro} Package. Wird über \ac{jpg} geschreiben,
so wird der Begriff beim ersten Mal ausgeschrieben, wird \ac{jpg} nochmals verwendet, folgt die Abkürzung.

Selbiges mit \ac{ufo}, \ac{pi} oder \ac{c}.

and this one to print the list

\printacronyms
% If you want multiple lists, just split them by tag
%\printacronyms[include=acro]
%\printacronyms[include=nomencl,name=Nomenclature]

Is all it takes.

Back to the issue at hand:

Since \printacronyms will most likely be called in the back of our document (before or after the references), it will definitely appear after the appendices.

\printacronyms alone creates a chapter but does not add the list of acronyms to the TOC. For this you can set \printacronyms[heading=chapter] (option is also configurable in the \acsetup macro). This creates a chapter that also shows in the TOC but will inevitably be called "Anhang E: Abkürzungen."

How to best avoid this? My take was to add \backmatter after the appendices, so the bibliography and everything after that is technically not part of the appendix anymore. This removes the "Anhang E" part for the heading but on subsequent pages (if the list of acronyms spawns over multiple pages) still has the "Anhang E" in the header.

I solved this by modifying the \backmatter macro:

\makeatletter
\g@addto@macro{\backmatter}{
	\renewcommand{\chaptermark}[1]{%
		\markboth{#1}{}%
	}    
}
\makeatother

This removes the appendix letter from the header, and all is well. This should allow to add stuff after the appendices and not have it count as an actual appendix.

@imagingbook, can we put the bibliography in the \backmatter and add the modification to hgb.sty so that the template is ready for things like a list of acronyms? Or do you see any breaking changes in this?

I would then create a wiki page about working with acronyms unless you want this fully integrated into our template document?

If you want to test this: I've created a working example in the acro-test branch.

[imagingbook]

Pls. give me some time to look at this (too busy). My ad-hoc emotion is that not every desirable feature should be included in the core setup to avoid bloating. As you say the Wiki might be a good place eventually ...

[hochleitner]

No disagreement here. The acro stuff doesn't necessarily have to go into the document. But - and this is the core question of the issue - we should probably prepare our document with the backmatter so that people can easily add stuff in the back (such as a list of acronyms, a list of images, etc.) without them being treated as an appendix chapter. This happens regularly, and people either have difficulties changing this ("help! why is the list of figures shown as appendix E!?") or do not notice it at all (which is probably even worse).

[imagingbook]

Understood. More flexibility is always a bonus ...

[imagingbook]

Thanks for the effort, I finally found time to play with this. I made a few changes to HgbThesisTutorial (branch acro-test) but did not finish, since I feel this needs some basic decisions. My main points are:

• I am not sure if \backmatter breaks anything, but I guess we should be OK.
• I moved the backmatter-patch to hgb.sty as suggested. However, it does not solve the (wrong) propagation of header entries. This needs more checking.
• I moved acronyms.tex to the top-level directory, I feel it should not be in back.
• The acronyms should definitely be listed before the references, which should come last - I moved it forward.
• The listing should definitely show up in the TOC. I used \acrolistnameto automatically insert the right TOC name.
• The available templates for output formatting are all deficient (actually they are terrible). I made a preliminary template based on description (which is what should be used to accommodate listings over multiple pages) which looks closer to anything acceptable, but still needs polishing.

Personally I feel that the whole setup is over-engineered and (for our purpose) could be made a lot simpler without any external packages.
@hochleitner : Pls. look at the current state and let me know what you think.

[hochleitner]

Thanks, I had time to check it out. Definitely like the template better but I do think that a simple description list could also suffice. I don't think that the page number is actually required (but it is solved quite nice since it doesn't stupidly print every page but will use things like "2 f.").

The problem with the regular description template is that our template reduces the vertical space for lists which also affects description lists and thus makes these really ugly in this context.

I don't necessarily think that using the ´acro´ page in our template is overengineered as acronyms are a part of almost every thesis and if this helps using them correctly, I'm happy. Plus in other programs (e.g., KWM) a list of acronyms along with a list of figures is required by most supervisors.

I suggest the following:

• If you feel this could have a permanent place in the package and thus in the example document (s), I think we should include it in the style files with all the setup and a possible template, so it's ready to use and hiding all the setup parts.
• If you don't like it, then we'll leave it here and I'll use the information to create a step-by-step wiki entry on how to use it (including an improved template). I'd keep the \backmatter aspect in the main documents though because I feel that this is semantically more correct anyway.

Your choice. I'll implement it accordingly.

[hochleitner]

One other thing: the reason why I actually included the list of acronyms as a chapter and not a chapter* was that the TOC entry corresponds to the correct heading.

With chapter*, even though it shows the correct page number in the TOC, the link points to the "Foo" chapter you added.

If you put \addcontentsline{toc}{chapter}{\acrolistname} after the \printacronyms the page anchor is correct but the page number is off.

I wasn't quite able to solve this. Probably a hyperref issue?

[hochleitner]

I updated the wiki with some information on how to get the various lists of figures, tables, listings and also acronyms. I used the current status as a basis. Should you decide to include it more deeply into the style files, I will adapt the article.

[imagingbook]

The problem with the regular description template is that our template reduces the vertical space for lists which also affects description lists and thus makes these really ugly in this context.

I think the built-in description template looks OK (including the vertical spacing). However, I dislike the stretched dot-fill and can't figure out why this happens at all. (The plain examples from the acro repo don't show any dotfill at all.)

TOC problem: list/heading=chapter in combination with \printacronyms only seems to work just fine.

I just pushed an update with a minimal setup I could live with. It contains a new style file 'hgbacro.sty' to be used optionally, automatically loads acronyms.tex (too bad this must happen in the preamble) and defines \PrintAcronyms as a wrapper for \printacronyms (just in case we need to change itd behavior later). The modified output template is included but hidden from the user. Hope I haven't overlooked anything ....

@hochleitner Let me know what you think.

[imagingbook]

So things to explain in the Wiki should become a lot simpler:

Edit acronyms.tex and

\usepackage{hgbacro}
...
\backmatter
\PrintAcronyms

[hochleitner]

So, I finally did test your adaptions; thanks for making things more compact.

Concerning the dot-fill: why do you suggest using the narrower version? \acrodotfill resembles the stretched version from the TOC - is it not appropriate for the TOA as well?

But if you prefer the regular dot fill, I implemented it using pages/fill={\dotfill} in the acsetup section. That way, \acrodotfill is used but takes \dotfill to render the actual dots. This is necessary because if you supply display=none to avoid showing the page numbers, the \acrodotfill respects that and does not print the dots, whereas if \dotfill is used, the dots stay there, which is most likely not desired.

If you have further suggestions or changes, let me know. Otherwise, I'd go ahead and set up a PR to merge changes back into main. This would include hgbacro.sty and acronyms.tex. I'd then update the wiki with simple instructions. Are you sure you want to keep acronyms.tex on the top-level and not move it (hide it) in a sub-folder?

[imagingbook]

Weird, I had not noticed the stretched dotfill in the TOC so far -- I don't like it but in this case we just use the default. Consequently our special template is not needed any longer, so I removed it. I think the current setup is sufficiently simple. I also moved the short note from 'Einleitung' to the 'LaTeX' chapter, leaving a reminder that details are still missing (@hochleitner please add).
Yes, I prefer to leave acronyms.tex at the top level.
We'll also need to mention the hgbacro.sty in the CTAN description and test with Overleaf.

[hochleitner]

I'll remove the short section about acronyms again and put it in the wiki only because if we leave it in we have to include hgbacro.sty permanently (I'm okay with that though if you want that).

You know what, I'll leave the short section in the example document and add hgbacro.sty to hgbthesis.cls so it's included by default for theses. I've had some requests recently how to handle acronyms and I think it might be a good idea, to have it in there permanently so people know how to use it. I might not add the list of acronyms and leave that to the wiki.

I'll update the manual and all the necessary docs and submit a PR once everything is done.

[hochleitner]

I updated everything and created PR #128.

hgbacro.sty in included in hgbthesis.cls but not the report and article classes. I've tested it with Overleaf - no issues here.
The wiki is also updated.

[imagingbook]

My impression is that we are somehow stuck in the middle: the setup in the tutorial is not complete and we still need the Wiki to explain it. Right now everything looks like a "strong recommendation" to use acronyms in this way, which is too much and not my preference.
Shouldn't we step back, remove the additional style file (and acronyms.tex) and describe everything (which is not much) exclusively in the Wiki? (There may be similar extension topics coming.)

[hochleitner]

I'm a bit confused right now. The initial wiki article was exactly that: how to get acronyms working with our template, how to include the acro package, set it up meaningfully and how to print a list of acronyms. Which was fine in my opinion.

You then created the hgbacro.sty as an optional component, which was also okay for me to use optionally. But when you mentioned that you moved the parts to the tutorial and asked me to add additional details, that gave me the strong impression you wanted these things to be mentioned in the tutorial and therefore more tightly integrated which is why I went that way.

I don't think that the section in the tutorial is incomplete though. It mentions everything needed based on the assumption that you primarily use the provided acronym functionality to typeset acronyms consistently throughout the document. There's no list of acronyms generated per default, same as for images and tables. But if one needs it, it's just one command in the preamble.
There is the coupling with acronyms.tex, which throws a warning if it isn't there but that's also the case for documents that have no references. And if you don't want to use the acronym functionality at all, there are no negative implications on that end.

But of course, I can still adapt it - nothing has happened as #128 is not merged yet, so by all means, let me know your preferred way of handling the whole thing and I'll update it that way.

[imagingbook]

Sorry for the unintended confusion (done in a haste and warm weather). I had introduced hgbacro.sty under the assumption that much more customization would be needed which should not be transparent to the user. Now we are practically back to a standard acro setup which I think does not warrant a separate .sty file any longer. And you were right that we wanted to keep the acronyms topic outside the tutorial from the beginning (adding that section was a misunderstanding on my side) and use the (wonderful) Wiki only.
I am happy to fix this if you like and let's talk on the phone to avoid more waste of time ...

[hochleitner]

A description of how a list of acronyms can be included is now contained in the wiki. The issue is hereby resolved.