Thursday, September 19, 2013

maintaining glossaries

It used to be that scientists in the average took seven years to enter in a field and make a contribution, after which they would hit a ceiling. Their institution would then offer them a sabbatical that would allow them to either get to the next level through osmosis and synergy, or change the field.

The fastest way to get up to speed in a new field is to write a review of the field, complete with an exhaustive glossary. The latter is a way to get acquainted with the terminology so that communication can be unequivocal and effective.

LaTeX is a popular authoring system and it has the description environment for compiling glossaries. Since nobody is reading documents on dead trees anymore, today the description environment must be the destination of hyper-links, so in practice today the syntax has become a little convoluted.

A list item cannot be labeled, so a phantom section needs to be created as a landing spot. Since creating the hyper-links requires many characters, a macro must be created for each entry. With this we end up with two include files. The first has the terms in a syntax like

\item[photometry:]\phantomsection \label{glos:photometry} Measurement of quantities referring to radiation as evaluated according to a given spectral luminous efficiency function, e.g., $V(\lambda)$ or $V^{\prime}(\lambda)$.~\cite{vc12}

\item[Planck's law:]\phantomsection \label{glos:planklaw} Law giving the spectral concentration of radiance of a Planckian radiator as a function of wavelength and temperature. \cite{vc12} \begin{equation} L_{e,\lambda} (\lambda,T) = \frac{\partial L_e(\lambda,T)}{ \partial \lambda} = \frac{c_1}{ \pi} \frac{1}{\lambda^{5} (e^{c_2 \lambda T} -1 )} \label{eqn:planck} \end{equation} where \\ $L_e =$ radiance, \\ $\lambda =$ wavelength in vacuum, \\ $T = $ thermodynamic temperature, \\ $c_0 =$ velocity (speed) of light in vacuum, \\ $c_1 = 2 \pi h c_0^2$, \\ $c_2 = h c_0 / k$, \\ $h =$ Planck's constant, \\ $k =$ the Bolzmann constant.\\

and the second file has entries for the preamble like


\newcommand{\planklaw}{\index{Plank's Law}\hyperref[glos:planklaw]{Plank's Law}}

This is very tedious and we would like to have something better. Ideally, we would like to have something like Biber with a database utility like BibDesk. A Biber style program could then just insert the terms that are actually used in the document and create the hyper-links. This way the glossary will also serve as the index.

Today the closest thing is the glossaries program, which is based on an indexing program like makeidx. Unfortunately for now it works reliably only on simple glossaries that are English text only. It cannot handle Unicode, figures, tables, etc. glossaries can use the newer xindy indexing program, but this is not yet contemplated with the various engine scripts.

For now we can just see that a clean modern solution is on the horizon. For simple applications like lists of acronyms, you should definitively use glossaries instead of the description environment.