Sunday, September 20, 2009

Acronyms and LaTeX

Computer geeks like acronyms, especially three-letter acronyms (TLAs). To give you an impression: I'm working in the area of MDD. Actually, OMG calls it MDA, Stuart Kent MDE, and others MDSD. In short, models, such as UML or EMF models, are transformed into other models or code by M2M- or M2T-transformations, such as QVT or ATL. Writing a thesis in that area is really hard, since you have to keep an eye on all that TLAs. So I've looked for a LaTeX package doing the job for me, and what I found is a package called acronym by Tobias Oetiker. I really like the simplicity of this package, this is why I decided to use that instead of other alternative solutions.

Install acronym

Surprisingly, it was already installed with my tex installation (gwTeX), but it requires a packages called suffix, which was not. The later is contained in a bundle called bigfoot. Here are the CTAN locations of acronym and bigfoot: In order to install a package from the files available at CTAN, you usually have to
  • download the zip or all the files from CTAN
  • unzip them (or put them into a folder) and put the folder somewhere tex can find it, e.g. into $HOMETEXMF (i.e. ~/library/texmf/tex)
  • run the installer via latex *.ins, in that case latex bigfoot.tex
Now you are ready to use acronym. It is quite simple: simply include the package via
\usepackage{acronym}
Instead of simply writing the acronym in your text, you now have to write \ac{..} (or, in case of a plural, \acp{..}). You have to add a new environment with a list of all the acronyms and their long form with

\begin{acronym}
\arcro{..}{...}
\end{acronym}
The first time an acronym is used, \ac prints the long form with the acronym in brakets. There are also some other commands available, see the acronym documentation for details.

Add list of acronyms to table of contents

Unfortunately, there is no command available for adding an entry to the table of contents. I have written my own command for that, which creates an entry similar to the list of figures. You have to add the following code somewhere in your preamble:

\@ifundefined{listofacronymsname}{\newcommand{\listofacronymsname}{Acronyms}}{}
\@ifundefined{chapter}{%
\newcommand{\listofacronyms}{%
\section*{\listofacronymsname}%
\addcontentsline{toc}{section}{\listofacronymsname}%
\label{sec:acronyms}%
\markboth{\listofacronymsname}{\listofacronymsname}%
}}{%
\newcommand{\listofacronyms}{%
\chapter*{\listofacronymsname}%
\addcontentsline{toc}{chapter}{\listofacronymsname}%
\label{sec:acronyms}%
\markboth{\listofacronymsname}{\listofacronymsname}%
}}
It defines two commands:
\listofacronymsname
defines the name of the heading used for the list of acronyms. It is "Acronyms" by default, but you can change that with \renewcommand, as demonstrated below.
\listofacronyms
creates a heading and a section or chapter definition (depending on the document class), which is also added to the table of contents. A label "sec:acronyms" is added as well.
(Update 2012-05-21: \markboth adjusts the header accordingly, see mrunix thread)

Put it all together

Let's put it all together. Firstly, we use the package and define the \listofacronyms command:

\usepackage[printonlyused,smaller]{acronym}     % acronyms ac
\@ifundefined{listofacronymsname}{\newcommand{\listofacronymsname}{Acronyms}}{}
...
I have added some parameters to only list the used acronyms and use a slightly smaller font. Secondly, we create a new file "acronyms.text" with a list of the acronyms, which makes it easier to maintain. This is how my file looks like:

\renewcommand{\listofacronymsname}{Abkürzungsverzeichnis} % german title
\listofacronyms

% \acro{acronym}[shortname]{fullname}
% inside fullname: \acroextra{} -- not in text, only in description list
\begin{acronym}
\acro{EMF}{Eclipse Modeling Framework \cite{EMF}}
\acro{GEF}{Graphical Editing Framework \cite{GEF}}
\acro{MDD}{Model Driven Development}
\acro{MDA}{Model Driven Architecture}
\acro{UML}{Unified Modeling Language}
...
\end{acronym}
The acronyms are not sorted automatically, I use SubEthaEdit for sorting the acronyms from time to time, but I guess there are several editors which can do that. This file has to be included in your main latex source document, e.g.,

\begin{appendix}
\input{acronyms}
\end{appendix}
Last but not least, we have to use the acronym commands in the text, just like that:

I'm working in the area of \ac{MDD}. Actually, \ac{OMG} calls it \ac{MDA}, Stuart Kent \ac{MDE}. In short, models, such as \ac{UML} or \ac{EMF} models, ...
You do not have to look for the first usage of an acronym anymore, acronym is doing that for you. If you forget to define an acronym, you will see that in the generated output as acronym creates a bold placeholder in that case. If you do not want to printed the list of acronyms, you can use acronym just as described before, you only have to add a package option nolist (i.e. \usepackage[nolist]{acronym}). This is especially useful in combination with the option footnote, as in that case the description of the acronym is printed as a footnote and not in the text (and one can find the definitions by scanning the footnotes, which is ok for shorter texts). Thank you very much, Tobias Oetiker, for writing that package!

No comments: