Siglas e listas de símbolos

Um esboço com glossaries-extra, ou uma lista feita à mão quando isso basta.

Siglas e listas de símbolos

Documentos longos acumulam abreviações, e as convenções sobre elas são rígidas. Uma sigla aparece por extenso no primeiro uso e abreviada depois, e uma tese geralmente precisa de uma lista de abreviaturas nos elementos pré-textuais. Manter isso à mão falha de um jeito previsível. Você reordena dois capítulos, o primeiro uso muda de lugar e, de repente, “ML” aparece três páginas antes de “aprendizado de máquina (ML)”. O pacote glossaries-extra controla o primeiro uso para você.

O caminho automatizado

\usepackage[acronym]{glossaries-extra}
\makeglossaries
\newacronym{ml}{ML}{machine learning}

A opção acronym ativa o suporte a siglas, e \makeglossaries liga o mecanismo que coleta as entradas durante a compilação. Cada \newacronym recebe três argumentos: uma chave que você digitará no texto, a forma curta e a forma longa. Defina todas no preâmbulo ou em um arquivo separado que você inclui com \input, para que fiquem em um só lugar.

No corpo do texto, você nunca digita a sigla em si:

\gls{ml} on first use expands; later uses stay short.
\printglossaries

O primeiro \gls{ml} do documento imprime “aprendizado de máquina (ML)”, e todos os seguintes imprimem apenas “ML”. Como o pacote controla o uso, e não a posição no código-fonte, a expansão acompanha o primeiro uso para onde quer que a reorganização o leve. \printglossaries imprime a lista de abreviaturas coletada onde você a colocar, normalmente depois do sumário. Outros comandos cuidam da gramática: \glspl para o plural e \Gls para o início de frase em maiúscula.

O porém está na compilação. Entre uma passada e outra do LaTeX, o auxiliar makeglossaries precisa rodar para ordenar e formatar as entradas, senão \printglossaries não produz nada, sem avisar. Configurações completas com latexmk fazem isso automaticamente. Pipelines mais simples podem não fazer, e o glossaries-extra oferece uma alternativa para eles. Se a sua lista teima em não aparecer, a execução do auxiliar que faltou é a primeira suspeita, bem antes de um erro no seu documento.

O caminho feito à mão

Para uma lista simples de símbolos, um ambiente description mantido à mão costuma bastar:

\section*{Notation}
\begin{description}
\item[$\eta$] learning rate
\item[$\theta$] model parameters
\end{description}

Cada \item[...] imprime o argumento entre colchetes como um rótulo em negrito, seguido da explicação, que é exatamente o formato de uma lista de notação. Não há controle de primeiro uso, mas uma lista de símbolos raramente precisa disso; os símbolos são definidos onde aparecem pela primeira vez na matemática, de qualquer forma.

O conselho honesto é adequar a ferramenta à escala. Um artigo com cinco siglas é mais fácil de gerenciar à mão. Uma tese de 200 páginas com quarenta, não, e nesse caso o pacote compensa o custo de configuração muitas vezes. A lição sobre listas trata do ambiente description com mais detalhes.

Voltar para Formato longo