Glosarios y nomenclatura

Todas las normas para autores incluyen la misma frase: desarrolla una abreviatura la primera vez que aparece y usa después la forma corta. A mano es una regla casi imposible de cumplir. Mueve una sección y «la primera vez» se mueve con ella; pasa por alto el sitio que importaba y un revisor lo encontrará. El paquete glossaries de LaTeX, y su sucesor glossaries-extra, entregan esa regla a la máquina. Cada término o abreviatura se define una vez en el preámbulo y en el cuerpo se escribe \gls{key}: el primer uso se desarrolla solo y, de paso, solo los términos realmente empleados aparecen, ordenados, en el glosario final. Esta página recorre el camino completo —definir entradas, \newacronym, ejecutar makeglossaries, \printglossary— y despeja de antemano las cuatro maneras de acabar con un glosario en blanco, tres de las cuales ni siquiera producen un aviso.

Definir una vez, llamar en cualquier sitio: newglossaryentry y gls

En el preámbulo escribe \newglossaryentry{key}{name=..., description=...} y en el cuerpo llámalo con \gls{key}. El primer argumento, key, es una etiqueta que inventas; name es lo que se imprime y description la explicación que figurará en el glosario. Lo que conviene retener es que \gls hace dos cosas a la vez: inserta el name donde lo escribiste y, al mismo tiempo, escribe en un archivo auxiliar una nota que dice que ese término pertenece al glosario. Por eso un término definido pero nunca llamado con \gls no aparece en absoluto. Listar solo los términos usados es el diseño, no un defecto.

Las variantes solo se distinguen por las letras iniciales del comando. Al comienzo de una frase, \Gls{key}; en plural, \glspl{key}; para ambas cosas, \Glspl{key}. El plural generado automáticamente es únicamente name más una «s», de modo que una forma irregular como matrices debe indicarse con la clave plural. Si la forma usada en el texto corriente debe diferir del nombre mostrado, fija text; coloca un símbolo asociado en la clave symbol y llámalo con \glssymbol{key}; inserta solo la explicación con \glsdesc{key}. Si una descripción abarca varios párrafos, recurre a \longnewglossaryentry. Y llamar a una key inexistente detiene la compilación con ! Package glossaries Error: Glossary entry ... has not been defined.: que una errata no pase desapercibida es aquí una virtud.

\usepackage{glossaries}
\makeglossaries              % opens the glossary files -- required

\newglossaryentry{set}{%
  name={set},
  description={a collection of distinct objects}%
}
\newglossaryentry{matrix}{%
  name={matrix},
  plural={matrices},      % irregular plural, spelled out
  description={a rectangular array of numbers}%
}

\begin{document}
\Gls{set} theory studies a \gls{set}; linear algebra studies \glspl{matrix}.
\printglossaries
\end{document}

Dejar las abreviaturas a la máquina: newacronym y la expansión inicial

Se define con \newacronym{key}{short}{long} y después basta con escribir \gls{key}. short es la abreviatura, por ejemplo SVM, y long la forma completa, support vector machine. Escribe dos veces el mismo \gls{svm} y la salida dice «support vector machine (SVM)» la primera vez y «SVM» todas las demás. Aquí es donde la máquina asume la regla que ningún autor cumple a mano: la marca de primer uso se sigue entrada por entrada y según el orden de procesamiento, de modo que al mover una sección la expansión se mueve con ella. Reordena el manuscrito y nada se contradice.

Cuando quieras que un término vuelva a desarrollarse a partir de cierto punto —un capítulo pensado para leerse solo, por ejemplo—, usa \glsreset{key}, o \glsresetall para todas las entradas a la vez. Para reunir las abreviaturas en una lista propia, carga el paquete como \usepackage[acronym]{glossaries}: tendrás dos listas independientes, un glosario y una lista de acrónimos, cada una con su juego de archivos auxiliares. Y cuando glossaries-extra también está cargado, \newacronym pasa a ser un alias de \newabbreviation con category=acronym: si empiezas de cero, escribir directamente \newabbreviation te da acceso inmediato a toda la gama de estilos de abreviatura.

\usepackage[acronym]{glossaries}   % a second, separate list
\makeglossaries

\newacronym{svm}{SVM}{support vector machine}

\begin{document}
\gls{svm} is a classifier.   % -> support vector machine (SVM)
Another \gls{svm} follows.   % -> SVM

\glsreset{svm}               % start a chapter that must stand alone
\gls{svm} again in full.     % -> support vector machine (SVM)

\printglossary[type=main,title={Glossary}]
\printglossary[type=\acronymtype,title={Acronyms}]
\end{document}

La compilación: makeglossaries convierte el .glo en .gls

LaTeX se limita a registrar los términos; ni los ordena ni les da formato. En la primera pasada, \makeglossaries emite un archivo .ist —el archivo de estilo con las reglas de ordenación— y cada término alcanzado por \gls se acumula en el .glo. Inserta aquí el programa externo makeglossaries y enseña sus cartas: imprime makeindex -s mydoc.ist -t mydoc.glg -o mydoc.gls mydoc.glo. Es exactamente el mismo makeindex que construye un índice analítico. Una vez existe el .gls ordenado, otra pasada de LaTeX lo lee.

pdflatex mydoc       # writes mydoc.glo (and mydoc.ist)
makeglossaries mydoc # sorts it: no file extension here
pdflatex mydoc       # reads mydoc.gls, prints the glossary

# what makeglossaries actually runs, once per glossary type:
#   makeindex -s mydoc.ist -t mydoc.glg -o mydoc.gls mydoc.glo
#   makeindex -s mydoc.ist -t mydoc.alg -o mydoc.acr mydoc.acn

Dos glosarios significan dos juegos de archivos. El glosario por defecto va de .glo a .gls, con un registro .glg; al añadir la opción acronym, la lista de acrónimos usa .acn hacia .acr (registro .alg), y makeglossaries llama a makeindex dos veces. Justamente esa tarea —saber cuántas listas hay y ejecutar la herramienta ese número de veces— es la razón de interponer makeglossaries en lugar de teclear makeindex uno mismo. El script está escrito en Perl, así que donde falta Perl —algo habitual en Windows— se llama a makeglossaries-lite: el mismo trabajo, implementado como makeglossaries-lite.lua y ejecutado por texlua.

Cuando el glosario sale en blanco: cuatro causas, tres de ellas mudas

La causa más frecuente es olvidar ejecutar makeglossaries, y ese fallo apenas deja pistas. Sin .gls, el glosario no aparece en absoluto, encabezado incluido: no queda un marco vacío, sencillamente no se compone nada ahí. Ni error ni aviso, solo una línea enterrada en el registro que dice No file mydoc.gls. Es exactamente la trampa de olvidar makeindex para un índice, y está bien disfrazada: \gls se expande correctamente desde la primera pasada, así que mientras solo mires el cuerpo del PDF todo parece funcionar.

• Nunca se ejecutó makeglossaries. Sin .gls, faltan el glosario y su encabezado. Ningún aviso; el registro solo contiene No file mydoc.gls.
• Falta \makeglossaries en el preámbulo. El archivo de salida ni siquiera se abre, no se crea ni un .glo y otra vez no se imprime nada. Ningún aviso.
• Se definió un término pero nunca se llamó con \gls. Las entradas sin usar no se registran, así que no se listan. Es intencionado: un término destinado al glosario debe aparecer al menos una vez en el cuerpo.
• El único fallo que sí se comunica es el contrario. Con \makeglossaries presente pero \printglossary olvidado obtienes Package glossaries Warning: No \printglossary or \printglossaries found. (Remove \makeglossaries if you dont want any glossaries.) This document will not have a glossary.

Otra combinación falla sin decir palabra. Si usas hyperref, carga glossaries después de hyperref: una de las pocas excepciones al consejo habitual de que hyperref va al final. La propia guía para principiantes del paquete lo dice explícitamente, y equivocarse de orden no produce ningún aviso: los enlaces y los números de página del glosario se rompen en silencio. Colócalos así.

\usepackage[colorlinks]{hyperref}
\usepackage{glossaries}   % after hyperref, not before
\makeglossaries

% put the glossary into the table of contents as well:
% \usepackage[toc]{glossaries}

Imprimirlo: título, tipo y entrada en el índice con printglossary

\printglossaries emite todas las listas que hayas preparado; \printglossary emite una. La elección depende de si necesitas opciones: para dar a cada lista su propio título o estilo, pásalas, como en \printglossary[type=main, title={Glosario}]; si no, basta la única línea \printglossaries. La palabra del encabezado reside en \glossaryname y se sustituye con \renewcommand.

Esos encabezados no llevan número, así que por defecto no llegan al índice. Cargar el paquete como \usepackage[toc]{glossaries} los sitúa allí automáticamente, lo que resulta más fiable que alinear un \addcontentsline por glosario. El aspecto en sí se cambia con \setglossarystyle{...}: list (el valor por defecto) se apoya en un entorno description, altlist pone el término en una línea propia y sangra la explicación debajo, y la familia long compone todo como una tabla. Cuanto más largas sean las descripciones, más rentables resultan altlist y los estilos long en legibilidad.

La configuración moderna: glossaries-extra y bib2gls

La primera versión de glossaries lleva fecha de 16 de mayo de 2007; Nicola Talbot la publicó como sucesora del antiguo paquete glossary. La misma autora sacó después glossaries-extra en 2015 y bib2gls en 2017. La combinación toma su idea directamente de la gestión bibliográfica: los términos viven en un archivo .bib, y bib2gls selecciona solo los realmente empleados en el cuerpo, los ordena y los incorpora, exactamente el papel que biber desempeña con las obras citadas. La selección y la ordenación, antes competencia de makeindex o xindy, quedan en manos de un único programa.

La clave es la opción record. Cargar \usepackage[record]{glossaries-extra} desactiva la indexación mediante makeindex o xindy y escribe en su lugar líneas como \glsxtr@record{set}{}{page}{glsnumberformat}{1} en el .aux. bib2gls las lee y devuelve al .glstex solo las entradas necesarias. Por este diseño, es normal que en la primera pasada aún no haya nada definido, y por eso glossaries-extra rebaja una entrada indefinida de error a aviso. Una columna de Package glossaries-extra Warning: Glossary entry ... has not been defined en la primera pasada es lo esperado. El glossaries simple detiene la compilación en la misma situación, y ambas decisiones son coherentes con su diseño.

@entry{set,
  name = {set},
  description = {a collection of distinct objects}
}

@abbreviation{svm,
  short = {SVM},
  long  = {support vector machine}
}

@symbol{sigma,
  name = {\ensuremath{\sigma}},
  description = {standard deviation}
}

\usepackage[record]{glossaries-extra}
\GlsXtrLoadResources[src={terms}]   % terms.bib, without the extension

\begin{document}
\gls{set} and \gls{svm} are used here.
\printunsrtglossary                 % already sorted by bib2gls
\end{document}

Lo que escribes en el documento apenas cambia. El .bib se carga con \GlsXtrLoadResources[src={terms}] —src es el nombre de archivo sin extensión— y los términos se siguen llamando con \gls{set}. Lo que difiere es el comando de impresión: como bib2gls ya ha ordenado, se usa \printunsrtglossary (unsrt por unsorted, es decir «emitir tal cual»). En la compilación, bib2gls sustituye a makeglossaries; --group añade encabezados por grupos de letras, y pdflatex puede dar paso a xelatex o lualatex. Una salvedad de instalación: bib2gls está escrito en Java y por tanto necesita un entorno de ejecución Java, al menos Java 8. El comando de TeX Live es un script de shell que lanza un .jar, así que en una máquina sin Java te enteras en cuanto lo ejecutas.

pdflatex mydoc
bib2gls --group mydoc   # reads mydoc.aux, writes mydoc.glstex
pdflatex mydoc

Solo una lista de símbolos: nomencl

Para una tabla de símbolos al principio de un artículo podrías usar glossaries, pero el ligero nomencl llega con menos piezas móviles. Pon \usepackage{nomencl} y \makenomenclature en el preámbulo, marca cada símbolo donde aparece por primera vez con \nomenclature{$g$}{gravitational acceleration} y escribe \printnomenclature donde corresponda la lista. Los símbolos son matemáticas, así que envuélvelos en $...$. La compilación vuelve a tomar prestado makeindex: \makenomenclature produce un .nlo, el estilo incluido nomencl.ist lo ordena en un .nls, y otra pasada de LaTeX lo lee.

pdflatex mydoc
makeindex mydoc.nlo -s nomencl.ist -o mydoc.nls
pdflatex mydoc

La ordenación trabaja sobre la entrada del símbolo, carácter a carácter. Escribe $\sigma$ y la clave de ordenación es la cadena $\sigma$, donde el dólar y la barra inversa preceden a todas las letras del alfabeto. Al probarlo, σ queda por delante de g y de m. De ahí el argumento opcional, que aporta tu propia clave: en \nomenclature[g-sigma]{$\sigma$}{...} lo que se ordena es g-sigma mientras que lo que se imprime es el símbolo. Y ya puestos: termina con % la línea anterior a un \nomenclature, porque un espacio perdido alrededor del símbolo desbarata la ordenación.

\usepackage{nomencl}
\makenomenclature
\renewcommand{\nomname}{List of Symbols}
% \usepackage[intoc]{nomencl}  % also list it in the contents

\begin{document}
Let $g$ be gravity.%
\nomenclature{$g$}{gravitational acceleration}%
A mass $m$ feels $F = mg$.%
\nomenclature{$m$}{mass of the object}%
\nomenclature[g-sigma]{$\sigma$}{stress}% sort key, not the symbol

\printnomenclature
\end{document}

El encabezado es por defecto el inglés «Nomenclature» y se sustituye con \renewcommand{\nomname}{...}. Para incluirlo en el índice, carga \usepackage[intoc]{nomencl}. También hay opciones que anotan cada entrada automáticamente: refpage añade «, page n» y refeq añade «, see equation (n)». Y si quieres separar constantes físicas de variables, redefinir \nomgroup a partir del primer carácter de la clave de ordenación que acabas de ver divide la lista en subgrupos con encabezados propios.

• Para un glosario de términos y abreviaturas, glossaries. Expansión inicial, plurales y mayúsculas quedan resueltos.
• ¿Proyecto nuevo? glossaries-extra con bib2gls. Los términos viven en un .bib y \printunsrtglossary emite los que has usado; solo confirma que hay Java disponible.
• Para una lista solo de símbolos matemáticos, nomencl. Marca con \nomenclature, ejecuta makeindex una vez y listo.
• Todos exigen una pasada adicional. Intercala el programa externo (makeglossaries / bib2gls / makeindex) y vuelve a ejecutar LaTeX. Si lo olvidas, nadie te reñirá.