glossaries使用

上一篇博客提到了glossaries，它是一个复杂的并且可以提供复杂的功能的缩写、符号表、术语表的宏包。本篇对其进行介绍。

\documentclass{article}
\usepackage{glossaries}
\setacronymstyle{long-short} % 设置术语表的显示方式
\newacronym{svm}{SVM}{support vector machine}
\begin{document}
First use: \gls{svm}. Second use: \gls{svm}.
\end{document}

这段代码中第二行引用了glossaries包，非常简单；

第三行设置了术语表的显示方式为先全称，后缩写，非常简单；这是在正文引用术语的显示方式，如本例中的这种显示方式，在术语第一次出现在文档中时，会显示描述+缩写名称，第二次出现时，只显示缩写。如下：

First use: support vector machine (SVM). Second use: SVM.

第四行定义了术语表的条目，引用的标签为svm，正文中就可以使用\gls{svm}引用该条目，缩写为SVM，描述或者说全称为support vector machine，比较简单。

第六行正文中使用\gls{svm}引用了缩写，非常简单。

上述例子可以直接编译运行。texstuido的编译方法为依次按F5、F9、F5；即先构建一次，在makeglossaries一次，再构建一次。

再给出一个可以直接复制粘贴编译的例子，复杂一点：

\documentclass{ctexbook}  
\usepackage{glossaries}
\usepackage{glossaries-extra}
\makeglossaries
\newglossaryentry{tm}{%
  name={Turing machine},
  description={A model of a machine that computes.  The model is simple
               but can compute anything any existing device can compute.
               It is the standard model used in Computer Science},
  }
\newglossaryentry{potato}{name={potato},plural={potatoes},
description={starchy tuber}}
\newglossaryentry{cabbage}{name={cabbage},description={vegetable with thick green or purple leaves}}
\newglossaryentry{trunip}{name={turnip},description={round pale root vegetable}}
\newglossaryentry{carrot}{name={carrot},description={orange root}}

%\setacronymstyle{long-short}%{long-sc-short} % 当引入了glossaries-extra包时，不能使用该命令，替代命令是\setabbreviationstyle{}，下面的\newacronym同理
%\newacronym{svm}{SVM}{support vector machine}
\setabbreviationstyle{long-short}
\newabbreviation{svm}{SVM}{support vector machine}

\begin{document}  
Everything begins with the definition of a \gls{tm}.  
  ...

First use: \gls{svm}. Second use: \gls{svm}.

Chop the \gls{cabbage}, \glspl{potato} and \glspl{carrot}.

%\printglossaries % 默认只列出正文中使用过的缩写符号
\printunsrtglossaries % 列出所有缩写符号
\end{document}

texstuido的编译方法为依次按F5、F9、F5；即先构建一次，在makeglossaries一次，再构建一次。

上述两个例子中一个使用了acronym，一个使用了glossary，还出现了abbreviation，其中acronym（首字母缩写词）和abbreviation（缩写）是一样的功能和显示方式，只是使用场合不同，代码中有注释。glossary是词汇表，没有缩写对应的全称。后面也会给出他们在文中的显示方式的区别。

glossaries-extra宏包提供了一些额外的格式和其他设置，建议使用。上例中，输出的缩写表如下图：

   

可以看出，缩写表是没有排序的，且列出了所有定义过但正文中没有使用的缩写，如果只需要列出使用的，根据代码中倒数第三行进行设置即可。如果需要对缩写表进行排序，方法很多，最简单但效率不高的方法是使用TeX自带的方法，只需要在前言区修改\makeglossaries命令为\makenoidxglossaries，并将输出列表的命令修改为\printnoidxglossaries即可。这是官方教程提供的方法，但是我自己调试时，使用这种方法时，在执行makeglossaries.exe命令时会报错，报错信息如下：

Process started: makeglossaries.exe "LGlo"

Your document has used \makenoidxglossaries You don't need makeindex or xindy. D:\texlive\2019\bin\win32\runscript.tlu:902: command failed with exit code 25: perl d:\texlive\2019\texmf-dist\scripts\glossaries\makeglossaries LGlo

Process exited with error(s)

但是构建输出结果是正确的，分析是因为使用TeX自带的功能就不需要makeindex或者xindy提供的功能，而makeglossaries.exe中继承了makeindex命令，因此报错，这是不影响pdf生成的，如果对该错误不爽，可以使用其他方式进行排序，如makeindex、xindy或者bib2gls。这里生成的缩写表如下：

缩写表中的项时根据首字母进行分组的，如果不需要分组之间的间隙，需要在引入glossaries包时设置如下：

\usepackage[nogroupskip]{glossaries}

还可以显示分组的名称，设置为

\usepackage[style=indexgroup]{glossaries}

输出结果如下：

如果不想在缩写表项之后显示页码，可以添加nonumberlist选项。

如果不想显示缩写表项描述之后的.符号，可以添加nopostdot选项。实例如下：

\usepackage[nonumberlist,nopostdot]{glossaries}

在正文中引用缩写表中的词条是，一般使用\gls{}，\glspl{}，\Gls{}，\Glspl{}，\glssymbol{}，\gls*{}等，其中带 * 的命令表示删掉正文引用和缩写表中对应词条的超链接。

将缩写表入口与主文档分开

我们希望我们的主tex文档结构清晰易读，需要把缩写表相关的控制编写放入其他文档中，我们可以使用bib2gls工具。该工具是集成在texlive中的，下面是一个例子。

主文件LGlo.tex文件内容如下：

\documentclass{ctexbook}  
\usepackage[automake,nogroupskip,style=indexgroup]{glossaries}
\usepackage[record]{glossaries-extra} % record使可以在.bib文件中给出缩写表信息。
%\makeglossaries % 添加 record 后，不需要且不能添加该命令
%\makenoidxglossaries % 添加 record 后，不需要且不能添加该命令
\GlsXtrLoadResources[src={entries}]


%\setacronymstyle{long-short}%{long-sc-short} % 当引入了glossaries-extra包时，不能使用该命令，替代命令是\setabbreviationstyle{}，下面的\newacronym同理
%\newacronym{svm}{SVM}{support vector machine}
\setabbreviationstyle{long-short}
\newabbreviation{svm}{SVM}{support vector machine}

\begin{document}  
	Everything begins with the definition of a \gls{tm}.  
	...
	
	First use: \gls{svm}. Second use: \gls{svm}.
	
	Chop the \gls{cabbage}, \glspl{potato} and \glspl{carrot}.
	
	where is \gls{fishage}
	
%	\printglossaries % 默认只列出正文中使用过的缩写符号
	\printunsrtglossaries % 列出所有缩写符号
%	\printnoidxglossaries
\end{document}

该文件第六行调用了一个entries的文件，在其中编写了缩写表的entry，对应硬盘中的文件为同目录下的entries.tex。entries.tex文件内容如下：

% Encoding: UTF-8

@entry{set,
	name={set},
	description={a collection of objects}
}
@entry{emptyset,
	name={\ensuremath{\emptyset}},
	description={the empty set}
}
@entry{fishage,
	name={Fish Age},
	description={A common name for the Devonian geologic period
		spanning from the end of the Silurian Period to
		the beginning of the Carboniferous Period.
		This age was known for its remarkable variety of
		fish species.}
}
@entry{elite,
	name={{é}lite},
	description={select group or class}
}
@entry{tm,
	name={Turing machine},
	description={A model of a machine that computes.  The model is simple
	but can compute anything any existing device can compute.
	It is the standard model used in Computer Science}
}
@entry{potato,
	name={potato},
	plural={potatoes},
	description={starchy tuber}
}
@entry{cabbage,
	name={cabbage},
	description={vegetable with thick green or purple leaves}
}
@entry{trunip,
	name={turnip},
	description={round pale root vegetable}
}
@entry{carrot,
	name={carrot},
	description={orange root}
}

编译方法：在texstudio中首先按F5构建一次，输出pdf文档中的缩写应该都是 ? 因为没有找到缩写表的entry。然后在从菜单中选择Tools->Open Terminal，输入 bib2gls LGlo 。其中LGlo是主文件不含后缀的文件名。会生成LGlo.glg文件。如下图：

然后再次按F5构建并预览，正常输出结果如下：

使用bib2gls工具时，需要安装java运行环境，因为我自己的电脑上安装过IDEA，我直接把IDEA的java.exe目录添加到系统的环境变量中了，可以运行的。要是电脑上没有安装过java开发环境的话，可以去java官网下载java的运行环境jre或者开发环境jdk都可以。

在使用这种方法时，貌似输出的缩写表中只有正文中出现的缩写项。

如果在第二步调用bib2gls时报错D:\texlive\2019\bin\win32\runscript.tlu:902: command failed with exit code 3:
java.exe -jar d:\texlive\2019\texmf-dist\scripts\bib2gls\bib2gls.jar LGlo，则注意检查*.bib文件中是否有某一项缺少 , 号。

当使用record方式（也就是bib2gls方式）构建缩写表的时候，一定需要注意的是record必须时引入glossaries-extra包的第一个设置项，即

\usepackage[record,% 使用bib2gls，且record必须是第一个
abbreviations,
symbols,
numbers
]{glossaries-extra}

，如果写作\usepackage[symbols,record]{glossaries-extra}就会报错，写为\usepackage[record,symbols]{glossaries-extra}则可以正常编译。这里顺序写错了会报错如下：

TeX capacity exceeded, sorry [parameter stack size=10000]. \RequirePackage

报错的信息莫名其妙，完全看不出来是哪里的问题，这里坑了我好久。官方说明文档也没有指出这点，偶然发现是顺序影响导致的。

测试发现\GlsXtrLoadResources命令只能使用一个，多个会报错：

Package glossaries Error: Glossary type `symbols' has not been defined. {vegetable with thick green or purple leaves}

缩写术语表的显示格式控制

如果需要修改缩写表的标签显示字体，可以使用命令：

\renewcommand * {\glsnamefont}[1]{\textmd{#1}}

重新定义glsnamefont。

其他可以修改术语表显示方式的命令有：

\usepackage[nopostdot]{glossaries}  % 不显示description后的英文标点符号 . 。

\usepackage[postdot]{glossaries-extra} % 功能同上

\usepackage[nonumberlist]{glossaries} % 不显示页码链接

\usepackage[style=index]{glossaries} % 设置显示格式为index

\setglossarystyle{index} % 功能同上

\usepackage{glossary-mcols} % 和下一行命令同时使用
\setglossarystyle{mcolindex} % 这两条命令提供了一种特殊的缩写表格式，显示如下图：

\usepackage[stylemods={mcols},style=mcolindex]{glossaries-extra} % 功能同上两条命令，但是该命令在glossaries-extra宏包存在其他设置项时，容易因为设置项顺序报错，所以还是使用上面两条命令比较好。后面不在给出设置项设置格式的命令。

\setglossarystyle{altlist} % 另外一种缩写表格式，如下图所示：

这个格式相对来说比较好看，适合大部分情况。

\setglossarystyle{long4col} % 这个格式适用于描述说明较短，带有表示符号的情况。如果描述太长，会把符号那一栏顶到屏幕外面去。输出如下：

\setglossarystyle{tree} % 这个格式会显示entry中的symbol关键字项，适合有符号的那种缩写表，大部分适用于数学相关文档。相较于上面那个格式，适用于长描述。输出如下：

glossary和abbreviation的区别

这两个都会在文中的glossaries中输出自己的条目，但是在文中引用时，glossary只会显示名字，而abbreviation会显示缩写和全程，如svm的显示为SVM（Support Vector Machine）。可以把glossary的entry卸载bib文件中，同时把abbreviation的条目定义写在主tex文档中，编译可以通过，不过不建议这么做。最好的方式是把二者都写在.bib文档中，但他们的入口格式不同，分别如下：

@abbreviation{fishage,
	symbol={Y},               % 这个关键字在使用【显示symbol的样式，如tree】时会显示在glossaries列表中
	short={fa},               % 必须关键字
	long={the age of a fish}, % 必须关键字
	description={A common name for the Devonian geologic period
	spanning from the end of the Silurian Period to
	the beginning of the Carboniferous Period.
	This age was known for its remarkable variety of
	fish species}             % 这个关键字会显示在glossaries列表中
}
@entry{tm,
	name={Turing machine},    % 必须关键字
	symbols={T},
	description={A model of a machine that computes.}
}

@abbreviation对应tex文档中的\newabbreviation[longplural={diagonal matrices}]{dm}{DM}{diagonal matrix}，一般来讲，abbreviation定义中有short和long两个关键字，分别对应缩写和全写，这两个定义会显示在生成的pdf文档正文中。而@entry{}对应tex文档中的\newglossaryentry{<label>}{name=<>,sort=<>,description=<>}，在正文中引用时，只会显示name。

多缩写表情况

如果一个文档中需要多个缩写表、术语表或者符号表，这种情况太复杂了，先不看了，有需要再说。