Login
Donate
You find LaTeX Community useful? Please donate! Learn why!
Who is Online
We have 94 guests and 2 members online| Glossaries, Nomenclature, Lists of Symbols and Acronyms |
|
|
|
| LaTeX - General |
| Written by Nicola Talbot |
| Wednesday, 18 March 2009 16:58 |
The glossaries package can be used to define terms, symbols and acronyms that can be used throughout a document. You can then use an indexing application to collate and sort the entries that have been used in the document. It is a highly versatile package, but it has a large manual that some beginners find daunting. This article is an introductory guide to help you get started.
What do I need installed?The latest version of the glossaries package (at the time of writing this) is version 1.19 and is available on CTAN. In addition, you also need to have the following packages installed: If you want to use any of the glossary styles that use the longtable environment, you will also need to have the longtable package installed, and if you want to use any of the glossary styles that use the supertabular environment, you will also need to have the supertabular package installed.The above packages are all distributed with MikTeX and TeX Live. In addition to the above LaTeX packages, you also need to have an indexing application installed to collate and sort the entries. The glossaries package is configured to work with makeindex or xindy. Makeindex is distributed with MikTeX, TeX Live and teTeX, so it should be readily available on your system. Xindy is distributed with TeX Live, so you might not have it installed if you use a different TeX distribution. There is a common misconception that you must have Perl installed to use the glossaries package. There is a Perl script called makeglossaries that acts as a convenient interface to makeindex or xindy, but it is not essential. This will be discussed in more detail below.
Getting StartedThe first thing that you need to do in your document is declare that you want to use the glossaries package:\usepackage{glossaries}
Note that if you want to use xindy instead of makeindex, you must add the xindy package option:
\usepackage[xindy]{glossaries}
However you will need to have xindy installed if you want to use this option.
If you are also using the hyperref package, you must load the glossaries package after the hyperref package:
\usepackage[colorlinks]{hyperref}
This is an exception to the general rule that the hyperref package should be loaded last.If you want your glossaries, list of symbols and list of acronyms to appear in the document's table of contents, you also need to use the toc package option: \usepackage[toc]{glossaries}
Defining a Term or SymbolTerms and symbols are defined using\newglossaryentry{label}{definition}
The first argument is a label that uniquely defines this entry.
It is best to use only characters that are not active in the label.
The second argument is a comma-separated list of key=value pairs. The most important keys are This article only covers the commonly used keys. See the section "Defining Glossary Entries" in the manual for a complete list.
For example: \newglossaryentry{culdesac}{name=cul-de-sac,description={passage
The above defines an entry whose label is culdesac.
It is generally best to define the terms in the preamble as they must be defined before they are used. Alternatively, you can put all your definitions in a separate file and input it using
\input{filename} or \loadglsentries{filename}Referencing TermsOnce a term has been defined using\newglossaryentry, it can be referenced using:
\gls{label}
Returning to the example above, I can reference it using:
\gls{culdesac}
If I want the first letter to be converted to upper case, I can do:
\Gls{culdesac}
or if I want the whole term to appear in capitals, I can do:
\GLS{culdesac}
The above commands also have optional arguments that aren't discussed in this article. For further information, see the section "Links to Glossary Entries" in the manual.
Let's put it together to make a simple document: \documentclass{article}
When I build this document (run it through LaTeX) I get the following warnings:
Package glossaries Warning: \makeglossaries hasn't been used,
These warnings can be ignored for the moment.
This produces a document that contains the following sentences: I used to live in a cul-de-sac. Cul-de-sac is another name for a no through road.It might be worth trying out this simple example to check that you have the required packages installed. (Check Installing things on a (La)TeX system if you're not sure how to install packages.) Plural FormsThe plural of a term can be obtained using\glspl{label}
The default behaviour is to append the letter "s" to the name to create the plural. In the above example, that would produce "cul-de-sacs" which is incorrect. The correct plural is "culs-de-sac". To fix this, I need to modify the definition:
\newglossaryentry{culdesac}{name=cul-de-sac,description={passage
As with the singular, I can also make the first letter of the plural form upper case:
\Glspl{culdesac}
or I can make the entire plural form appear in capitals:
\GLSpl{culdesac}
If your term has more than one plural, use the
plural key for the most commonly used plural together with \glspl{label} and use \glslink{label}{alternative plural} for the other plural.The sort keyLater on in this article, I will cover sorting the entries using an indexing application, but when you define an entry, you need to bear in mind that the indexing application may not know how to sort terms that contain LaTeX commands. Consider the following example:\newglossaryentry{pi}{name={\ensuremath{\pi}},description={ratio
This entry should ideally belong to the "p" group (that is, the group of terms whose first letter is a "p") however neither makeindex nor xindy will be able to sort this entry correctly as they can't interpret LaTeX code. Therefore, we need to tell the indexing application that this entry needs to be sorted according to "pi":
\newglossaryentry{pi}{name={\ensuremath{\pi}},sort=pi,
Note that in the above example I have used The ratio of the circumference of a circle to its diameter is given by \gls{pi}:
Accents and non-Latin charactersMakeindex is hard-coded for English, so you will need to use thesort key if the entry's name contains accented or non-Latin characters. For example:
\newglossaryentry{attache}{name=attach\'e,sort=attache,
Xindy was designed to overcome makeindex's inflexibility and has rules for various (but not all) languages, so if you are using xindy with the above example, you can just do:
\newglossaryentry{attache}{name=attach\'e,
or if you are using the inputenc package, you can just do:
\newglossaryentry{attache}{name=attaché,
Care must be taken when the first character has an accent or is a non-Latin character, regardless of whether you use makeindex or xindy. This character must be enclosed in braces if you want to use it with \newglossaryentry{elite}{name={\'e}lite,description={select
or if you are using the inputenc package:
\newglossaryentry{elite}{name={é}lite,description={select
Remember that if you are using makeindex, you also need to use the sort key:
\newglossaryentry{elite}{name={\'e}lite,description={select
Defining an entry with both a name and a symbolIt is also possible to define an entry that has both a name and a symbol. For example:\newglossaryentry{ohm}{name=ohm,symbol={\ensuremath{\Omega}},
I can reference the name as usual:
\gls{ohm}
or I can reference the symbol using:
\glssymbol{ohm}
AcronymsWhen you define a term, you can specify that it should appear differently on first use. You can use this facility to define acronyms. For example:\newglossaryentry{led}{name=LED,description={light-emitting
There is a shortcut command that is equivalent to the above:
\newacronym{led}{LED}{light-emitting diode}
The glossaries package provides other acronym formats, such as making the long form appear in a footnote on first use. These are covered in the section "Acronyms" in the manual.
You can then use the acronym in the same way as any other glossary term. For example: \gls{led}
If this is the first time you have used this entry, it will appear as
light-emitting diode (LED)otherwise it will appear as LED If you define the acronym using \acrlong{label}
and
\acrshort{label}
For example:
\acrlong{led}
will produce
light-emitting diodeand \acrshort{led}
will produce
LED If you feel that is far too much typing, you can enable the shortcuts using the \usepackage[shortcuts]{glossaries}
You can now use \acs instead of \acrshort and \acl instead of \acrlong.
Other acronym related commands are described in the manual. In addition to the section called "Acronyms", there is also a section that covers resetting and unsetting entries.
Multiple GlossariesYou may have as many glossaries, lists of symbols or lists of acronyms as you like in your document. The default is to just have one glossary. You can add a list of acronyms using theacronym package option:
\usepackage[acronym]{glossaries}
Any acronyms defined using \newacronym will automatically be added to the list of acronyms rather than the main glossary if the acronym package option is used. If you want an additional glossary, for example a list of symbols, you need to define it using:
\newglossary[log ext]{glossary label}{in-ext}{out-ext}{title}
The glossary label is a label that uniquely identifies this glossary. Again, it is best to use non-active characters such as alphanumerics (a-z,A-Z,0-9) in the label. The title is used as the section or chapter header for that glossary.
The remaining arguments specify the extensions for the files that contain the glossary information. The in-ext argument indicates the extension of the file that is created by the indexing application. This file is read in by the glossaries package's The first optional argument log ext is the extension for the indexing transcript file. This is only needed if you use the makeglossaries Perl script. You don't need to worry about it if you don't have Perl installed. There is a second optional argument to
\newglossary that isn't covered here. See the section "Defining New Glossaries" in the manual for further details.For example, suppose I want to create a list of symbols. I can define a glossary called "symbols" as follows: \newglossary{symbols}{sym}{sbl}{List of Symbols}
When I define an entry to go in this glossary, I need to use the type key to specify the glossary label. For example:
\newglossaryentry{pi}{type=symbols,name={\ensuremath{\pi}},sort=pi,
If the type key is omitted, the main glossary is assumed.
Using makeindex or xindySo far I have only covered how to define a term, symbol or acronym and how to use it in the document, but it is likely that you will also want a sorted list of these entries. This is where things start to get a bit complicated and is often a source of confusion for beginners.The first thing that you must do is add the command \makeglossaries
to your preamble. (This needs to come after any occurrence of \newglossary.)
The next step is to put the command \printglossaries
where you want your glossaries, lists of symbols or acronyms to appear. This will typically be either in your front matter (with the table of contents, list of figures etc) or back matter (with the bibliography etc).
If you want to rearrange your glossaries or have some in the front matter and some in the back matter, you can use
\printglossary which is described in the section "Displaying a glossary" in the manual.Here is an example document: \documentclass{article}
If we run this document through pdflatex, we get the following warnings (amongst others):
pdfTeX warning (dest): name{glo:ohm} has been referenced but do
These warnings are due to the fact that I have used the hyperref package, which creates hyperlinks from the terms to their definition in the relevant glossary, list of acronyms or list of symbols, but the targets don't exist yet. If you try this example and view the resulting PDF/DVI file, you will see that the glossaries haven't appeared yet. You may also notice that the terms generated by \gls and \glspl have all appeared in red. This is the default colour used by the hyperref package for internal links when used with the colorlinks option.
The next step is to use an indexing application to create the glossaries. Using makeglossariesThe easiest way of creating the glossaries is to use the makeglossaries Perl script that comes with the glossaries package. If you are using MikTeX, this will probably be located in C:\Program Files\MikTeX 2.7\scripts\glossaries. If you are using a Unix style system, it should be in the same location as makeindex (or there may be a symbolic link to it from that location).In order to use makeglossaries, you must have Perl installed. Don't be put off by this. There are a number of useful TeX related Perl scripts (such as epstopdf) so it really helps to have Perl, but if you are set against it for some reason, there are instructions below to help you access makeindex or xindy explicitly.
Makeglossaries, makeindex and xindy are all command line applications. There are several ways to access that type of application. I will first describe how to do this using the MSDOS command prompt. (Unix style users are more likely to be familiar with using a terminal, so I shall assume they can work out what to do from the MSDOS command prompt instructions.) Windows users can access the command prompt from the Start menu. It is usually in the Accessories folder. It should produce something that looks like: Next, you need to be in the same folder as your document. Let's suppose that my document is contained in the folder E:\My Documents\thesis. There are two things to note about this path name: it uses the E drive rather than the default C drive and the name contains a space. So I need to switch to the E drive by typing E:and then I need to specify the path by typing cd "E:\My Documents\thesis"Note that I have used double quotes around the path name because of the space character. These two steps are illustrated below: Next, I'm going to test if makeglossaries is working. To do this I'm just going to type makeglossariesThis can produce one of two responses:
makeglossaries myDoc Note that the file extension hasn't been used.
This should produce the following: added glossary type 'acronym' (alg,acr,acn)This means that the glossary, list of acronyms and list of symbols have been successfully created. You now need another LaTeX run to incorporate them into the document. If you view your document, it should now contain the glossary, list of acronyms and list of symbols. The numbers after each glossary entry indicate the page number on which that entry was used. The numbers are red because the hyperref package has been used, and they link to the corresponding page.
The list of symbols doesn't show the corresponding symbol for each entry. This is because the default style ignores the symbol. Try changing the package options to: \usepackage[acronym,toc,style=tree]{glossaries}
See the section "Glossary Styles" in the manual for a list of predefined styles.
Using makeindex and xindy explicitlyIf you don't have Perl installed you can run makeindex or xindy explicitly. Again, let's suppose that your document is called myDoc.tex. If you are using makeindex (you haven't used the makeindex -s myDoc.ist -t myDoc.glg -o myDoc.gls myDoc.gloThe list of acronyms is created by typing the following line into the command prompt: makeindex -s myDoc.ist -t myDoc.alg -o myDoc.acr myDoc.acnThe list of symbols is created by typing the following line into the command prompt: makeindex -s myDoc.ist -t myDoc.slg -o myDoc.sym myDoc.sbl Note that if your file name contains spaces (a bad idea), you must use double quotes around each file name. For example:
If you have decided to use xindy instead of makeindex (remember to use the makeindex -s "my Doc.ist" -t "my Doc.glg" -o "my Doc.gls" "my Doc.glo" xindy package option) then the main glossary is created by typing the following into the command prompt:
xindy -L english -I xindy -M myDoc -t myDoc.glg -o myDoc.gls myDoc.gloThe list of acronyms is created by typing the following line into the command prompt: xindy -L english -I xindy -M myDoc -t myDoc.alg -o myDoc.acr myDoc.acnThe list of symbols is created by typing the following line into the command prompt: xindy -L english -I xindy -M myDoc -t myDoc.slg -o myDoc.sym myDoc.sbl If you use makeindex when you should have used xindy, you will get an error message that looks something like:
All things considered, it's much easier to dispense with all of the above and just type
Scanning input file myDoc.glo...done (0 entries accepted, 4 rejected).If you use xindy when you should have used makeindex, you will get an error message that looks something like: ERROR: EVAL: variable |gLOSSARYENTRY{ATTACH'E?gLOSSARYENTRYFIELD{ATTACHE}{gLSNAMEFONT{ATTACH'E}}{PERSON| has no value
makeglossaries myDoc How many times do I need to build/LaTeX the document or use the indexing application?If you tried the example in the previous section, and followed all the instructions: build/LaTeX the document, run makeglossaries (or makeindex) and build/LaTeX the document, you may have noticed that the document still isn't complete and is still generating the warning message:pdfTeX warning (dest): name{glo:elite} has been referenced but d
This warning has resulted from the fact that one of the glossary entries (elite) has only been referenced in the glossary (in the description of elitism). This means that the first LaTeX run didn't encounter any reference to elite so it didn't write the relevant information to the external glossary file which means that it didn't end up in the glossary. Now that the glossary is present, we need another makeglossaries (or makeindex) run to add elite to the glossary. This in turn means that another LaTeX run is required to update the glossary section (and to add the glossary section headers to the table of contents). Once this has been done, the document should now be complete.
Incorporating makeglossaries into editorsSome editors, such as TeXnicCenter, allow you to specify external applications to run as a post-processor. My knowledge of front-ends is fairly limited (I tend to only use vi and make), but here are a few pointers:TeXnicCenterYou can add makeglossaries to the build profile of TeXnicCenter as follows:
WinEdtThere is a thread on comp.text.tex that discusses how to do use makeglossaries with WinEdt.Other EditorsIf you use another editor, I suggest you search the editor's documentation to find how to use makeindex. It's possible that you may be able to infer from that how to use makeglossaries. (Perhaps users who have already worked out how to do it for their preferred editor might like to add instructions as a comment to this article.) |








Comments
is there a command, please, to show the glossary entry in text (as with \gls{} command), point it to the Glossary (when created), but do not create a new page number and a new back-referencin g link? Page numbers and back-referencin g links (in the Glossary list) would be created and pointed only for the first use of \gls{} or the appropriate command.
Thank you very much for listening,
Zroutik
links in the text pointing to the Glossary list are very good. But many page numbers back-referencin g from the Glossary list to the text are a nice mess, IMO.
Thank you,
Zroutik
\newglossaryentr y{Hi}{description={This is an \gls{entry}},name={Hi}}
\newglossaryentr y{There}{description={There is a whole world out there.},name={Hi}}
Inside of a table cell, I want to use \gls{Hi}.
When it prints, I get "This is an ``gls --There''" inside of the table...
This entry appears fine in the \printglossaries and if I use it outside of a table.
Thanks
James
\newglossaryentr y{Hi}{description={This is an \gls{There}},name={Hi}}
\newglossaryentr y{There}{description={There is a whole world out there.},name={Hi}}
Thanks
James
it's better to post requests for help in the forum as you'll get a quicker response and more people are likely to see it. It's also helpful to provide a http://theoval.cmp.uea.ac.uk/~nlct/latex/minexample/" rel="nofollow" target="_blank">minimal working example that illustrates the problem.
Regards
Nicola Talbot
i am having a couple of problems with the definition of several glossaries. In particular, i have two separate input files. Where do i indicate this to the
\newglossary command?
i defined it this way:
\include{./acr/acr.tex}
\include{./acr/not.tex}
\newglossary{notacion}{gls}{glo}{Notaci\'on}
inside acr.tex i defined each entry, this way:
\newglossaryentr y{rz}{
type=\acronymtype,
and, inside not.tex, exactly the same way, except i didn't defined the type.
The output pdflates produces the same list (the one in acr.tex) two times. Any ideas what i am doing wrong?
thanks for the help