Using the glossaries package in Latex and Linux, Kile

I was recently frustrated by the limitations of the acronym and glossary packages: I wanted to have something that joined the functionality of both together. Luckily, I found that with the glossaries package, which actually states that it is the replacement for the now-obsolete glossary package.

In order to make this tutorial, I have used the following resources, which you may also find useful: the CTAN glossaries page; the glossaries INSTALL file; (one, two) links from the latex community pages; and a page from the Cambridge Uni Engineering Department. These instructions work for Ubuntu Karmic Koala: please modify where necessary for your system.

Installing glossaries

Note for Windows users: While the makeglossaries command is a perl script for Unix users, there is also a .bat version of the file for Windows users. However, I don’t know how to set up MIKTex or equivalent to use this package. Feel free to add a comment if you can add information about this step.

  1. Get and unzip the glossaries package. I downloaded it from here. Though you can download the source and compile, I found it much easier to simply download the tex directory structure (tds) zip file.  Unfortunately, the texlive-latex-extra package available on ubuntu or kubuntu does not contain the glossaries package – it only contains glossary and acronym. I unzipped the contents of the zip file into a directory called “texmf” in my home directory. You’ll also want to run “texhash ~/texmf/” to update the latex database, according to the INSTALL instructions.
  2. (Optionally) get the xfor package. If your system is like mine, after you’ve installed the glossaries package latex will complain that it doesn’t have the xfor package (which also is not available via apt-get in Ubuntu). Download this package from here.
  3. Open the glossaries zip as root in a nautilus window, terminal window, or equivalent. You’ll be copying the contents to various locations in the root directory structure, and will need root access to do this.
  4. Find the location of your root texmf directory. In Karmic, this is /usr/share/texmf/, though it may be in another location on your system.
  5. Copy the contents of the tex and doc directories from the glossaries zip into the matching directory structure in your texmf directory. For me, this meant copying the “doc/latex/glossaries” subdirectory in the zip file to “/usr/share/texmf/doc/latex/”, and the same for the tex directory (copy “tex/latex/glossaries” subdirectory in the zip file to “/usr/share/texmf/tex/latex/”). In theory, you can also copy the scripts/ directory in the same way, but I did step 6 instead, as this is what was suggested in the INSTALL document.
  6. Update the master latex database. Simply run the command “sudo mktexlsr”
  7. Add the location of your scripts/glossaries directory to your $PATH. This gives programs access to makeglossaries, the perl script you will be using (if you’re in linux/unix). If you followed my default instructions in step 1, this location will be “/home/yourname/texmf/scripts/glossaries”.
  8. Test the installation. Change into the directory you created in step 1, into the “doc/latex/glossaries/samples/” subdirectory. There, run “latex minimalgls”. If you get an error about xfor, please see step 9. Otherwise, run “makeglossaries” and then “latex minimalgls” again. If everything works, the package is set up for command-line use. You may wish to modify your Kile setup to use glossaries – go to step 10 if this is the case.
  9. Set up the xfor package. Run steps 3-6 again, but with the xfor.tds.zip file instead of the glossaries zip file. This package is simpler than glossaries, and does not contain a scripts/ subdirectory, so you will not need to do step 7. After installation, try running step 8 again: everything should work.
  10. Setting up Kile. Though I’m using Ubuntu, I find the Kubuntu latex editor Kile to be my favourite (just “sudo apt-get install kile” on Ubuntu). To set up Kile for using glossaries, you need to add another build tool that runs makeglossaries.
    1. Go to Settings -> Configure Kile
    2. Select the “Build” choice, which is a submenu of “Tools” on the left-hand menu.
    3. This brings up a “Select a Tool” pane and a “Choose a configuration for the tool …” pane.
    4. Click on the “New” button at the bottom of the “Select a Tool” pane.
    5. Type in a descriptive name for the tool such as “MakeGlossaries”, and click “Next”.
    6. The next prompt will be to select the default behaviour (or class) of the tool. I based MakeGlossaries on MakeIndex, as they both run in similar ways. Click “Finish” to finish.
    7. For some reason for me, Kile wasn’t initially picking up my changes in my $PATH, so in the General tab of the “Choose a configuration for the tool MakeGlossaries” pane, I put the full path plus the name of the “makeglossaries” script in the “Command” field. You may only need to put in “makeglossaries”.
    8. In the “Options” field of the same tab and pane as step 7, just put in ‘%S’.
    9. Change the selected tab from “General” to “Menu”. In the “Add tool to Build menu:” field, select “Compile” from the pull-down menu. This allows it to appear in the quick compile menu in the main editor window.
    10. I didn’t change any other options. Press “OK” in the main Settings window.
    11. You should now be able to access MakeGlossaries within Kile. Remember, you have to run latex (e.g. PDFLatex) as normal first, to generate the initial file; then run MakeGlossaries; then run PDFLatex or similar again.

Good luck, and I hope this helps people!

Tips on using glossaries

I usually keep all of my acronyms/glossary entries read by the glossaries file in a glossaries-file.tex or similar, and use “\include” to pass it to my main tex file. The links I posted at the top of this tutorial contain a number of useful examples, and included below are my favorites from those locations as well as a few of my own.

Note on usage within your document: Please note that to reference these entries, use \gls{entrylabel} for both referencing an acronym or a glossary entry. Further, to access the plural version of either, use \glspl{entrylabel}. By default, you do NOT need to put in a plural form of an acronym: latex will add an “s” to the expanded form and to the short form when you reference the acronym with \glspl{TLA} rather than \gls{TLA}.

A plain glossary entry that is not also an acronym. The first “sample” is the label used to reference this entry. The second “name={sample}” is the name of the glossary entry, as viewed once the glossary is compiled. The description is the actual definition for the glossary entry:

\newglossaryentry{sample}{name={sample},description={a sample entry}}

A plain acronym entry that is not also a glossary entry. The TLA acronym below illustrates the very basic acronym form. The “aca” example after it illustrates how to add non-normal plurals to the short and long form of the acronym. Then, again, the first instance of “aca” is the label with which to reference the acronym, and the second instance is the name as viewed in the compiled document. The final {} section is the expanded form of the acronym:

\newacronym[]{TLA}{TLA}{Three-letter acronym}
\newacronym[\glsshortpluralkey=cas,\glslongpluralkey=contrivedacronyms]{aca}{aca}{a contrived acronym}

Using an acronym within the glossary definition of a glossary entry. If you wish to make use of an acronym within the glossary definition, and have that acronym indexed properly within the glossary as well as the main text, here is what you do. First, make the acronym. Note that there is nothing special about this acronym:

\newacronym[]{DL}{DL}{Description Logics}

Second, make a normal glossary entry, and reference the acronym as normal. No special work necessary! Please also note that you can put in \cite references within a glossary entry with no problem at all:

\newglossaryentry{TBox}{name={TBox},description={This component of a \gls{DL}-based ontology describes
"intensional knowledge", or knowledge about the problem domain in general. The "T" in TBox could,
therefore, mean "Terminology" or "Taxonomy". It is considered to be unchanging
knowledge~\cite[pg. 12]{2003Description}. Deductions, or \textit{logical implications},
for TBoxes can be done by verifying that a generic relationship follows logically
from TBox declarations~\cite[pg. 14]{2003Description}.}}

Using an acronym as the name of a glossary entry. You sometimes want to use a defined acronym as the name for a glossary entry – this allows you to create a definition for an acronym. In this case, build your acronym as follows. Note that you need to add a “description” field to the square brackets:

\newacronym[description={\glslink{pos}{Part of Speech}}]{POS}{POS}{Part Of Speech}

Then, reference the acronym in the glossary entry as follows (notice the different label for this entry):

\newglossaryentry{pos}{name=\glslink{POS}{Part Of Speech},text=Part of Speech,
description={``Part of Speech''Description}}

Good luck, and have fun. 🙂

Advertisements

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s