Smile for the Camera: a new cybercrime short story ebook.

Incorporating makeglossaries or makeglossaries-lite or bib2gls into the document build

There are a number of webpages that describe how to build your glossary when using the glossaries or glossaries-extra packages. This page is an attempt to collate the scattered information (some of which is no longer available), but note that some information may now be out-of-date and I don’t have all the software to test the instructions, but hopefully this is enough to give you a general idea of what needs to be done.

Glossary

It seems appropriate for a page about glossaries to have a glossary, so here it is. Some of this may sound obvious to veterans, but new LaTeX users who don’t have a computer programming background can get bewildered by terms that are casually thrown about by experts. (Some of this is simplified.) You can skip to the next section if you prefer.

Application

A piece of software that instructs your computer to perform certain tasks. These tasks may include reading information from existing files or writing information to files (either creating new files or modifying existing files). These file reading and writing operations are often referred to as I/O (input/output) where input refers to reading and output refers to writing.

GUI (graphical user interface)

A GUI application is one that has a window with interactive elements, such as menus and buttons. A front-end is an example of a GUI application.

Non-GUI or Batch

A batch application is one that doesn’t show any graphical elements. It can quietly run in the background without showing any visible sign (although it may display transcript text if run in a terminal or command prompt). LaTeX (latex, pdflatex, xelatex, lualatex) is an example of a non-GUI application.

Call (or Run or Execute) an Application

This is when an application, such as LaTeX, is started in response to some action, where the action may be triggered by clicking on a button or by typing instructions in a terminal or command prompt.

Front-End

A GUI application that allows you to conveniently edit your LaTeX (.tex) documents, and provides buttons or menu items that help you to build the document. These buttons work by calling a batch application, which needs to be installed separately. So, for example, it’s not enough just to install the front-end, but you must also install a TeX distribution.

The front-end may also have an integrated PDF viewer or it may rely on a general PDF viewer, which you will also need to install (although most computers these days are likely to have one pre-installed since PDF is a common document format).

Compiled Application

An application that has all its instructions stored in computer code. This makes it quick to start up and run, because the instructions don’t need to be translated, but, since each operating system and architecture has its own specific code, you can only run the application on a matching computer. Examples of compiled applications include LaTeX (latex, pdflatex, xelatex, lualatex) and makeindex.

When you install the application, it’s important to install the version that was created for your operating system. If the person who created the application doesn’t use your operating system, then you have to rely on someone else who does to try porting the code (or do it yourself). Otherwise you can’t use the application. This can lead to disappointment if you hear about a brand-new application that you want to use, only to discover that it doesn’t run on your computer.

Interpreted Application (Script)

An application that has its instructions stored in human-readable form. In order to run it on your computer, you need an interpreter to convert the instructions into computer code, so you also need to have the interpreter installed. For example, xindy is a Perl script.

This means that you not only need to install xindy in order to use it, you also need to install Perl. However, once you have installed the interpreter, you can install other scripts written in the same language. If the person who created the application doesn’t use your operating system, there’s a chance that the application might work on your computer as long as you have the interpreter installed. However, there’s also a chance that it might not work if the person who created the application has used native instructions that aren’t understood by your computer.

Perl

An interpreted language. Unix-like systems typically have Perl pre-installed. Windows users may want to read MiKTeX and Perl scripts (and one Python script).

Java

Java is a programming language that’s designed to be portable. An application written in Java is compiled so that all its instructions are written in Java bytecode. As with an interpreted application, the Java application needs an interpreter (in this case, the Java Virtual Machine or Runtime Environment) to translate the bytecode into the computer’s native code. Since the language is designed for portability, it shouldn’t matter if the person who created the application is unfamiliar with your operating system. A Java application should run on any system that has the Java Runtime Environment installed (but you will need to make sure that your Java installation is sufficiently up-to-date as old versions of Java may not support new applications).

Example Documents

There are three methods provided by the base glossaries package and two more provided by the glossaries-extra extension package. A summary of the pros and cons of each method can be found in Table 1.1 of the glossaries user manual.

There are also two hybrid methods available with glossaries-extra (option 1 with option 2 or 3, or option 4 with option 2 or 3) that aren’t included here. In general, they are best avoided unless there’s a pressing reason to use them.

Here are five simple example documents that use each method:

  1. Sorting and collating is performed by TeX (inefficient): 
    \documentclass{article}

\usepackage[acronym,symbols]{glossaries}

\makenoidxglossaries

% define entry in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}

% define entry in 'acronym' glossary:
\newacronym{ex}{EX}{example}

% define entry in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a function of $x$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} function \gls{fx}.

\printnoidxglossary % default: type=main
\printnoidxglossary[type=acronym]
\printnoidxglossary[type=symbols]
\end{document}

    The build process is simple in this case. It just requires two LaTeX calls. If you use this method, you don’t need to read further unless you’re interested in switching (although you might want to have a look at the glossaries performance page).

  2. Sorting and collating is performed by makeindex: 
    \documentclass{article}

\usepackage[acronym,symbols]{glossaries}

\makeglossaries

% define entry in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}

% define entry in 'acronym' glossary:
\newacronym{ex}{EX}{example}

% define entry in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a function of $x$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} function \gls{fx}.

\printglossary % default: type=main
\printglossary[type=acronym]
\printglossary[type=symbols]
\end{document}

    The build process now needs to call LaTeX, then makeindex three times (once per each glossary), then LaTeX, so read on if you don’t know how to do this.

  3. Sorting and collating is performed by xindy: 
    \documentclass{article}

\usepackage[xindy,acronym,symbols]{glossaries}

\makeglossaries

% define entry in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}

% define entry in 'acronym' glossary:
\newacronym{ex}{EX}{example}

% define entry in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a function of $x$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} function \gls{fx}.

\printglossary % default: type=main
\printglossary[type=acronym]
\printglossary[type=symbols]
\end{document}

    The build process now needs to call LaTeX, then xindy three times (once per each glossary), then LaTeX, so read on if you don’t know how to do this.

  4. Sorting and collating is performed by bib2gls. This is more complicated because now the glossary entries are defined in one or more .bib files. For example, suppose the file terms.bib contains: 
    @entry{sample,
  name = {sample},
  description = {an example}
}

    and the file abbrvs.bib contains:

    @abbreviation{ex,
  short = {EX},
  long = {example}
}

    and the file syms.bib contains:

    @symbol{fx,
  name = {\ensuremath{f(x)}},
  description = {a function of $x$}
}

    then the document now looks like:

    \documentclass{article}

\usepackage[record,abbreviations,symbols]{glossaries-extra}

% @entry defaults to type=main
% @abbreviation defaults to type=abbreviations
\GlsXtrLoadResources[
 src={terms,abbrvs}% data in terms.bib and abbrvs.bib
]

\GlsXtrLoadResources[
 src=syms,% data in syms.bib
 type=symbols% put these entries in the symbols list
]

\begin{document}
A \gls{sample} document with an \gls{ex} function \gls{fx}.

\printunsrtglossary % default: type=main
\printunsrtglossary[type=abbreviations]
\printunsrtglossary[type=symbols]
\end{document}

    The build process now needs to call LaTeX, then bib2gls (once, not per glossary), then LaTeX, so read on if you don’t know how to do this.

  5. No sorting or collating: 
    \documentclass{article}

\usepackage[abbreviations,symbols]{glossaries-extra}

% define entry in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}

% define entry in 'abbreviations' glossary:
\newabbreviation{ex}{EX}{example}

% define entry in 'symbols' glossary:
\glsxtrnewsymbol
 [description={a function of $x$}]
 {fx}{\ensuremath{f(x)}}

\begin{document}
A \gls{sample} document with an \gls{ex} function \gls{fx}.

\printunsrtglossary % default: type=main
\printunsrtglossary[type=abbreviations]
\printunsrtglossary[type=symbols]
\end{document}

    This is the simplest method of all, but there’s no sorting or indexing, which means that every entry that’s been defined in the document will be listed in the relevant glossary (even if it hasn’t been referenced), and the list will follow the order of definition. The build process just consists of one LaTeX call. If you are using this method, you just need to make sure that you have reasonably up-to-date versions of glossaries and glossaries-extra. You don’t need to read the rest of this page (but you might be interested in reading glossaries-extra and bib2gls: an introductory guide [PDF]).

Each of these examples contains three glossaries: the main (default) list, identified by the label main, a list of acronyms/abbreviations, identified by the label acronym for the first three examples and identified by the label abbreviations in the last two examples, and a list of symbols, identified by the label symbols.

The main glossary is defined by default. The acronym glossary is defined by the acronym package option (acronyms is a synonym for acronym=true but still uses the label acronym to identify the glossary). The symbols glossary is defined by the symbols package option. The abbreviations glossary is defined by glossaries-extra’s abbreviations package option (which is unavailable for just the base glossaries package).

Each glossary is displayed using the appropriate \print…glossary command. The different methods are described below.

Option 1 (‘noidx’)

The first example uses \printnoidxglossary[type=label]. This command must be enabled with \makenoidxglossaries in the preamble. All the indexing information (that identifies which entries have been referenced in the document and the corresponding location) is contained in the .aux file. Since glossaries may occur at the start of the document, this means that two LaTeX calls are required to ensure that the glossaries are displayed.

Options 2 and 3 (‘makeglossaries’)

Examples 2 and 3 use \printglossary[type=label], which requires \makeglossaries in the preamble. This works by writing the indexing information to an external file for each glossary. (The files are opened by \makeglossaries.) After the first LaTeX run, these files should now be present along with other temporary files, such as the .aux file. For example, entries in the main glossary have their indexing information written to a file with the extension .glo. If the document is called test.tex then in the case of example 2, LaTeX creates a file called test.glo that contains:

\glossaryentry{sample?\glossentry{sample}|setentrycounter[]{page}\glsnumberformat}{1}

whereas in the case of example 3, the file test.glo contains:

(indexentry :tkey (("sample" "\\glossentry{sample}") ) :locref "{}{1}" :attr "pageglsnumberformat" )

This is the same information, but it uses a different syntax. Example 2 uses makeindex syntax, and example 3 uses xindy syntax. Both makeindex and xindy are indexing applications. They read a file containing indexing information (consisting of the sort value, e.g. sample, actual value, e.g. \glossentry{sample}, and location, e.g. page 1) and create a file containing LaTeX code that can be input in the document on the next LaTeX run. In the case of the main glossary, the file needs to have the extension .gls. This file is then input by \printglossary[type=main]. If the .gls file doesn’t exist, then the glossary can’t be displayed.

In the case of example 2, the .gls file is created by running makeindex with the options -s test.ist (the custom style file created by the preamble command \makeglossaries), -o test.gls (the output file, which is input by \printglossary[type=main]), -t test.glg (the transcript file, in case anything goes wrong) and the input file test.glo (which contains all the indexing information for the main glossary).

The image below shows example 2 in TeXworks.

image of texworks showing example 2 document

The typeset button runs the application identified in the neighbouring selector. In this case pdfLaTeX is selected. If I click on the typeset button then TeXworks calls the pdflatex application with the current filename (test.tex) as the argument. This opens the PDF viewer and displays the document (shown below), but there’s no glossary yet.

image of texworks showing PDF of example 2 document (glossary missing)

The next step is tricky. I need to run makeindex to create the associated glossary file. The TeXworks selector has a MakeIndex option, but this is for creating indexes (for example, with the makeidx package). I need to run makeindex with appropriate options for each glossary.

I can add a new tool to the selector that calls makeindex with the options:

-s basename.ist -o basename.gls -t basename.glg basename.glo

(basename is the document file name without the extension and is identified by a placeholder when creating a new tool.)

Once I’ve created this tool, I can then select it and click on the typeset button, which will run makeindex and create the .gls file required by \printglossary[type=main].

The problem is that this only creates the file for the first (main) glossary. The other two glossaries are still missing their required files. So I would then need to add a new tool to create the file for the acronym glossary, which requires makeindex run with the arguments:

-s basename.ist -o basename.acr -t basename.alg basename.acn

and I need to add a new tool to create the file for the symbols glossary:

-s basename.ist -o basename.sls -t basename.slg basename.slo

If I switch to glossaries-extra and use the abbreviations glossary, I need yet another tool, which requires makeindex run with the arguments:

-s basename.ist -o basename.gls-abr -t basename.glg-abr basename.glo-abr

If I add more glossaries, I need yet more tools, and if I decide to switch from makeindex to xindy, then all those tools will need reconfiguring to run xindy instead (with a different set of arguments).

This makes a very complicated build process where I have to select pdfLaTeX and click on the typeset button, and then select the tool to run makeindex on the main glossary file, and then select the tool to run makeindex on the acronym glossary file, and then select the tool to run makeindex on the symbols glossary file, before I can finally reselect pdfLaTeX and click on the typeset button to create the completed document.

This process has to be done every time the document is edited.

To simplify this process, the glossaries package provides two scripts that run makeindex or xindy the required number of times with the appropriate arguments. Both scripts search the .aux file for the command:

\@istfilename{style file}

For example 2, where the document is called test.tex, the test.aux file contains:

\@istfilename{test.ist}

The extension indicates whether makeindex (.ist) or xindy (.xdy) is needed. The .aux file also provides all the file extensions. In this case:

\@newglossary{main}{glg}{gls}{glo}
\@newglossary{acronym}{alg}{acr}{acn}
\@newglossary{symbols}{slg}{sls}{slo}

So now, instead of having one tool for each glossary, you only need one tool to run the script, that in turn will run makeindex or xindy the required number of times.

This means that the build process is now simplified to: select pdfLaTeX and click on the typeset button, and then select the tool to run the provided script to create all the glossary files, and then reselect pdfLaTeX and click on the typeset button to create the completed document.

Both scripts provided by the glossaries package are written in an interpreted language. This means that although I wrote the code on a 64bit Linux computer, you can run the scripts on Windows, Mac etc as long as you have the appropriate interpreter installed. (If I had used a compiled language, then the application would only be available to other 64bit Linux users.)

The first script is called makeglossaries (to match the corresponding \makeglossaries command) and is written in Perl, which means you need the Perl interpreter installed to run it. TeX distributions for Windows provide this application as makeglossaries.exe, but it still requires Perl.

The second script is called makeglossaries-lite.lua and is written in Lua. TeX distributions on Unix-like systems create a symbolic link without the .lua extension, and TeX distributions on Windows provide the application as makeglossaries-lite.exe. Regardless of the operating system, you need to have a Lua interpreter installed in order to run this application. Fortunately, modern TeX distributions that are shipped with LuaTeX automatically include a Lua interpreter (called texlua).

Both scripts take the .aux file as the argument. The .aux extension may be omitted. This makes it much simpler to provide a tool for your front-end to run the script.

The makeglossaries Perl script is the better of the two because it provides some additional diagnostics if things go wrong. Some of xindy’s error messages are a bit cryptic, so makeglossaries checks for common problems and tries to explain what’s happened. This script can also recognise common babel language names and can convert them to the corresponding settings when using xindy.

The makeglossaries-lite Lua script is provided for users who can’t work out how to install the Perl interpreter. This script was only added to glossaries version 4.16, so if you have an old version of glossaries, you’ll need to update it if you want to use this option. It doesn’t have the diagnostic functions of the Perl alternative, and doesn’t recognise babel language names. However, if you choose to use makeglossaries-lite because you can’t work out how to install Perl, then you can’t use xindy, because that’s also a Perl script.

There is also a Java alternative called makeglossariesgui that has both a batch mode and a GUI mode. So instead of running:

makeglossaries basename

you can run:

makeglossariesgui --batch basename

The GUI mode has better diagnostics as it also checks the .log file for common problems. So you may find it useful if things go wrong with your glossaries and you can’t work out the cause. The makeglossariesgui application isn’t provided with the glossaries package, and must be installed separately if required.

So, if you use \makeglossaries in your document, you can use the makeglossaries Perl script, or the makeglossaries-lite Lua script or the makeglossariesgui application to generate all the files needed by each of your \printglossary commands. The section Adding a New Tool describes how to add your preferred application to your front-end.

Installing MakeGlossariesGUI

If you want to use makeglossariesgui, you need to install it. (It’s distributed separately from the glossaries package and isn’t in the TeX distributions.) It’s a Java application, so make sure you have Java installed first. (Download Java.)

To install makeglossariesgui:

  1. Download makeglossariesgui-installer.jar. You may be given the opportunity to run it at the same time as downloading it, in which case you can do so. If successful, go to step 4. Otherwise, save the makeglossariesgui-installer.jar file to your downloads directory and go to the next step.
  2. Go to your downloads directory and run the installer. Depending on your operating system, you may be able to double-click on the makeglossariesgui-installer.jar file or you may be able to open the context menu (for example, with a right mouse click) and use ‘Open with Java’ (if available). If successful, go to step 4. Otherwise, go to the next step.
  3. Open a terminal or command prompt and change to the download directory: 
    cd path to download directory
    (where path to download directory is the path name of the download directory, for example ~/Downloads or C:\Users\username\Downloads). Then enter the command: 
    java -jar makeglossariesgui-installer.jar
  4. Check that it’s installed correctly by running it in GUI mode.

Option 4 (‘bib2gls’)

Example 4 uses the glossaries-extra extension package, with the record option, one or more instances of \GlsXtrLoadResources and \printunsrtglossary.

The \printunsrtglossary command works by iterating over all defined entries that have been assigned to the glossary (identified by the type key). In this case, the entries are defined in .bib files. The record package option sets up the document for use with bib2gls. The \GlsXtrLoadResources command writes information to the .aux file indicating which entries are needed. After the .aux file has been created, the bib2gls application reads the .aux file, fetches the data from the .bib files, sorts the data and then creates a file (with the extension .glstex) that contains the LaTeX code required to define the entries (using commands like \newabbreviation). The .glstex file is input by \GlsXtrLoadResources, so on the next LaTeX run the required entries are all defined and can be listed by \printunsrtglossary. You can find out more information in glossaries-extra and bib2gls: an introductory guide [PDF].

As with \makeglossaries, this requires adding a new tool in your document build process. In this case, bib2gls. The required argument is the .aux file (again, the .aux extension may be omitted). If you want letter groups in your glossary, you will also need to add the optional --group argument. The section Adding a New Tool describes how to add bib2gls to your front-end. Since bib2gls is a Java application, you will also need to ensure that you have the Java Virtual Machine installed.

Option 5 (‘unsrt’)

Example 5 also uses \printunsrtglossary, but it doesn’t use \GlsXtrLoadResources. Instead, the entries are defined in the preamble and \printunsrtglossary simply lists all defined entries in the given glossary (identified by type) in the order of definition. This option doesn’t require any external tools.

Adding a New Tool

TeXworks

To add a new tool to TeXworks, use the Edit -> Preferences menu item to open the preferences window, and select the Typesetting tab:

image of Typesetting tab in texworks preferences window

This has two list areas. The top shows the paths (directories/folders) that contain applications that you might want to use. The bottom shows the tools that are currently available. To add a new tool, click on the bottom + (add) button, which opens the Tool Configuration dialog, shown below:

tool configuration dialog window

You only need to configure the tools that you actually want to use. Here I’ve created the MakeGlossaries and Bib2Gls tools:

TeXworks preferences window

I’ve also added arara, which is a convenient tool for automation. As with bib2gls, you can install arara using your TeX package manager. To add arara as a TeXworks tool:

  1. Make sure you have Java installed. (Download Java.)
  2. Install arara using your TeX package manager.
  3. In TeXworks, open the Tool Configuration dialog, as described above.
  4. Type Arara in the Name area.
  5. Click on the Browse… button to search for the arara application (either with or without the .exe extension, depending on your operating system). This will typically be in the same directory as the other TeX-related applications if you installed it with your TeX package manager.
  6. Add the argument $basename.
  7. Make sure the View PDF after running box is checked. (This tool will modify the PDF.)

    tool configuration dialog window setup for arara

Now you just need to put special comments in your document source code to tell arara what to do. For example, to run pdflatex, followed by the makeglossaries Perl script, followed by pdflatex again: 

% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex

Now you just need to select the Arara tool and just click the typeset button once to create the completed document.

Note that arara version 3.0 supports the makeglossaries Perl script, but you need version 4.0 for makeglossaries-lite and bib2gls support.

TeXmaker

I don’t have TeXmaker installed. These instructions are from Using Texmaker with glossaries on Windows.

TeXnicCenter

This information is very old. The interface may have changed.

If you want to use the makeglossaries Perl script, make sure you have Perl installed. If you can’t work out how to install it or you don’t want to install it, use the makeglossaries-lite Lua script instead.

WinEdt (arara)

I don’t have WinEdt, but it seems that WinEdt has support for arara, so I recommend using arara. Arara version 3.0 has a makeglossaries rule (which runs the makeglossaries script, so you need Perl installed). Arara version 4.0 comes with a makeglossarieslite rule, which runs the makeglossaries-lite Lua script and a bib2gls rule, which runs the bib2gls application (which will need installing through your TeX package manager).

  1. Make sure you have Java installed. (Download Java.)
  2. Use your TeX package manager to install arara.
  3. Follow the WinEdt instructions, which includes download links.
  4. Add the appropriate comments to your document, as described below.

TeXShop

This is a modification from the answer to Adding a new engine in TeXShop.

TeXStudio

This information was obtained from the questions How to configure TexStudio editor to use glossaries package with makeglossaries and xindy or how to configure TexStudio to use arara? and Has anyone managed to use \glossaries with TeXstudio on Windows? on TeX on StackExchange.

makeglossaries

There should already be a command for makeglossaries, but to check that it’s configured correctly:

  1. Go to Options -> Configure TeXstudio.
  2. Click on Commands
  3. Go to the Makeglossary row and check that the box next to it contains: 
    makeglossaries %
    If you don’t have Perl installed and need to use makeglossaries-lite instead, change this to: 
    makeglossaries-lite %
  4. Click on Build (below Commands) and click on the Show Advanced Options checkbox at the bottom of the window.
  5. Replace the Build & View option so that instead of 
    txs:///compile | txs:///view
    it’s now: 
    txs:///compile | txs:///makeglossaries | txs:///compile | txs:///view
  6. Click OK.

bib2gls

If you only intend using bib2gls and not makeglossaries, then just adapt the above method and replace makeglossaries (or makeglossaries-lite) in step 3 with bib2gls. Otherwise, you need to additionally set up a command to run bib2gls:

  1. Go to Options -> Configure TeXstudio.
  2. Click on Build
  3. Under User Commands click Add
  4. In the first field type: 
    user0:Bib2Gls
    (the number following user may be different, each user command must have a different number) and in the second field type: 
    bib2gls %
    (you may need to fill in the full path to bib2gls.exe). The % character is a placeholder representing the filename without the extension. You may need to add other options, for example -g to enable letter groups: 
    bib2gls -g %
  5. You may need to change the Build & View setting to ensure that bib2gls is automatically run, as described in the previous section.
  6. Click OK.

arara

This is much like the above:

  1. Go to Options -> Configure TeXstudio.
  2. Click on Build
  3. Under User Commands click Add
  4. In the first field type: 
    user1:Arara
    (the number following user may be different, each user command must have a different number) and in the second field type: 
    arara %
    (you may need to fill in the full path to arara.exe). The % character is a placeholder representing the filename without the extension. You can add other options, such as -v for verbose mode or -l to create an arara log file.
  5. To use arara in the quick build, it may be easiest, if possible, to change the default compiler to Arara instead of PdfLaTeX. (Alternatively, you can call arara through the Tools -> User -> Arara menu item.)
  6. Click OK.

Overleaf (latexmk)

Overleaf apparently uses latexmk to build documents. You can create a custom .latexmk file in your project directory if required. At the time of writing, Overleaf doesn’t support bib2gls, so you’re limited to the indexing options that are provided with the base glossaries package or the no-sort option 5.

Automated Build Tools

There are some useful tools that try to work out which applications are needed to create a completed document and run them for you. The makeglossaries and makeglossaries-lite scripts are actually a partial example of this: they read the .aux file to determine which indexing application to use.

The bash script in the TeXShop section is an example of a conditional build where the .aux file is checked for the existence of glsxtr@resource and @istfilename, which indicate whether or not bib2gls or makeglossaries needs to be run.

Arara

Arara has already been mentioned above. It’s a Java application, and it works by searching the document source (.tex) file for comments in the form:

% arara: rule

where rule must match a file called rule.yaml that’s in Arara’s rule directory.

Here’s a very simple document:

% arara: pdflatex
\documentclass{article}
\begin{document}
Hello world!
\end{document}

The first line tells Arara to run pdflatex on the document.

Arara version 3.0 has a rule called makeglossaries that instructs Arara to run the makeglossaries Perl script. Here’s the modified version of an earlier example:

% arara: pdflatex
% arara: makeglossaries
% arara: pdflatex
\documentclass{article}

\usepackage[acronym,symbols]{glossaries}

\makeglossaries

% define entry in default 'main' glossary:
\newglossaryentry{sample}{name={sample},description={an example}}

% define entry in 'acronym' glossary:
\newacronym{ex}{EX}{example}

% define entry in 'symbols' glossary:
\newglossaryentry{fx}{name={\ensuremath{f(x)}},
 description={a function of $x$},
 type=symbols
}

\begin{document}
A \gls{sample} document with an \gls{ex} function \gls{fx}.

\printglossary % default: type=main
\printglossary[type=acronym]
\printglossary[type=symbols]
\end{document}

The first three lines instruct Arara to run pdflatex, followed by the makeglossaries script, followed by pdflatex again. Remember that this needs Perl installed.

If you need makeglossaries-lite instead, either upgrade to Arara version 4.0 or, with version 3.0, create a file called makeglossarieslite.yaml that contains:

!config
# MakeGlossariesLite rule for arara version 3.0
identifier: makeglossarieslite
name: MakeGlossariesLite
command: <arara> makeglossaries-lite @{options} "@{getBasename(file)}"
arguments:
- identifier: options
  flag: <arara> @{parameters.options}

(Don’t use this with version 4.0. The rule syntax has changed in version 4.0.)

Arara version 4.0 has a new rule called makeglossarieslite that instructs Arara to run the makeglossaries-lite Lua script, and a new rule bib2gls that instructs Arara to run bib2gls. (Remember that if you want to use bib2gls you need to install it through your TeX package manager.)

This makes it much easier to fine-tune the document build by listing the rules in the source code. As long as the applications that you need have an associated rule, all you now need to do is incorporate arara into your front-end as described in the Adding a New Tool section.

If you share your document with a colleague who doesn’t use arara, then the comments are ignored, but they provide a convenient list at the start of the file to let them know what needs to be used to build the document.

With arara version 4.0, you can now use conditionals. For example, makeglossaries only needs to be run if the .aux file contains \@istfilename, and bib2gls only needs to be run if the .aux file contains \glsxtr@resource, so here’s a conditional use: 

% arara: pdflatex
% arara: bib2gls if found("aux", "glsxtr@resource")
% arara: makeglossaries if found("aux", "@istfilename")
% arara: pdflatex

Here’s a hybrid bib2gls+makeglossaries test:

% arara: pdflatex
% arara: bib2gls if found("aux", "glsxtr@resource")
% arara: pdflatex if found("aux", "glsxtr@resource") && found("aux", "@istfilename")
% arara: makeglossaries if found("aux", "@istfilename")
% arara: pdflatex

latexmk

latexmk is a Perl script, so you need to have Perl installed in order to use it.

latexmk works by checking for certain file extensions and determining if they are missing or require updating (by comparing their last modification date with a dependent file).

Unfortunately, this method of comparing files rather than scanning a file for a particular string (such as \@istfilename in the .aux file) makes it harder to determine whether or not makeglossaries or bib2gls needs to be run.

The recommended method is to add custom dependencies for each glossary and run makeindex or xindy as required. This means makeglossaries isn’t actually called, so you don’t get the useful diagnostics when things go wrong and you can’t pick up document settings which may require adjusting the arguments. For example, switching from makeindex to xindy, switching language (if you have one document in, say, German, and another in, say, English).

The main glossary has the .glo file created by LaTeX and this is used to create the .gls file, which is input by \printglossary[type=main], so you need to create a file called .latexmk that contains: 

add_cus_dep('glo', 'gls', 0, 'makeglossary');

sub makeglossary{
  system( "makeindex -s \"$_[0].ist\" -t \"$_[0].glg\" -o \"$_[0].gls\" \"$_[0].glo\"" );
}

Similarly for the acronym glossary:

add_cus_dep('acn', 'acr', 0, 'makeacronym');

sub makeacronym{
  system( "makeindex -s \"$_[0].ist\" -t \"$_[0].alg\" -o \"$_[0].acr\" \"$_[0].acn\"" );
}

and for the symbols glossary:

add_cus_dep('slo', 'sls', 0, 'makesymbols');

sub makesymbols{
  system( "makeindex -s \"$_[0].ist\" -t \"$_[0].slg\" -o \"$_[0].sls\" \"$_[0].slo\"" );
}

If you switch to glossaries-extra and the abbreviations option, then you need:

add_cus_dep('glo-abr', 'gls-abr', 0, 'makeabbreviations');

sub makeabbreviations{
  system( "makeindex -s \"$_[0].ist\" -t \"$_[0].glg-abr\" -o \"$_[0].gls-abr\" \"$_[0].glo-abr\"" );
}

If you switch from makeindex to xindy, then you need to change all those system calls to use xindy, with the arguments changed as appropriate. For example: for the main glossary:

sub makeglossary{
  system( "xindy -L english -C utf8 -I xindy -M \"$_[0]\" -t \"$_[0].glg\" -o \"$_[0].gls\" \"$_[0].glo\"" );
}

Similarly for all the other glossaries.

I don’t know how to incorporate bib2gls into latexmk. One of bib2gls’s advantages over the \makeglossaries approach is that it doesn’t require any write registers since all the information is written in the .aux file. With bib2gls, the additional files are the .glg transcript file and a .glstex file per \GlsXtrLoadResources.

For example, the earlier makeindex test document has three glossaries, where each glossary has three associated files (input, output and transcript) and all glossaries share a style file. So that document ends up with 1 (aux) + 1 (log) + 1 (ist) + 3 (main) + 3 (acronym) + 3 (symbols) = 12 associated temporary files.

The analogous bib2gls example, which produces the same document (aside from the substitution of Abbreviations in place of Acronyms in the second glossary title) ends up with 1 (aux) + 1 (log) + 1 (glg) + 2 (glstex) = 5 associated temporary files.

This means that an automated method that relies on file extension to determine which application to run, can’t detect if bib2gls is required.

make

Makefiles suffer from a similar problem to latexmk in that they rely on file dependencies. I’ve used different approaches over the years, but with arara version 4.0’s ability to include conditionals, I’m starting to switch over to using arara. For example, if the file is called, say, test.tex then my Makefile has:

test.pdf	: test.tex
		arara test

The Makefile used in bib2gls’s test directory uses a different approach:

test.pdf	: test.glstex
		pdflatex test

test.glstex	: test.tex $(DEPS) test-entries.bib
		pdflatex test
		$(BIB2GLS) test

This is mainly because when I’m testing I sometimes just want to run make test.glstex rather than create the completed PDF.

Debugging

The makeglossaries Perl script searches the transcript files for known problems and will report them. Consider the following example (contained in the file missing-sort.tex):

\documentclass{article}

\usepackage[utf8]{inputenc}
\usepackage[xindy]{glossaries}

\makeglossaries

\newglossaryentry{sample}{name={sample},
 description={an example}}

\newglossaryentry{S}{name={\S},
 description={section symbol}}

\newglossaryentry{alpha}{name={\ensuremath{\alpha}},
 description={alpha}}

\newglossaryentry{beta}{name={$\beta$},text={\beta},
 description={beta}}

\begin{document}
Test: \gls{sample}, \gls{S}, $\gls{alpha}$, $\gls{beta}$.

\printglossaries

\end{document}

This requires xindy but if I run: 

xindy -L english -C utf8 -I xindy -M missing-sort -t missing-sort.glg -o missing-sort.gls missing-sort.glo

I get a confusing warning message:

WARNING: Would replace complete index key by empty string,
         ignoring
         #<ordrule-regexp: '\\[a-zA-Z@]+ *' => '' :again NIL :only-at-start NIL>

and a confusing error message:

ERROR: CHAR: index 0 should be less than the length of the string

The document doesn’t contain the glossary because the xindy call failed.

If I use makeglossaries instead of a direct call to xindy I get more information: 

Possible cause of problem:

Sort key required for entries only containing command names.
Attempting to determine which entries have problem sort keys.
Parsing 'missing-sort.glo'
3 problematic entries found:

Label: 'beta'. Sort value : '$\\beta $'
(Try adding sort={beta} to the definition.)
Label: 'alpha'. Sort value : '\\ensuremath {\\alpha }'
(Try adding sort={alpha} to the definition.)
Label: 'S'. Sort value : 'S'
(Try adding sort={S} to the definition.)

The warning and error message are recognised by makeglossaries and it tells you the possible cause of the problem and suggests a possible solution. (These diagnostic messages are appended to xindy’s transcript file by makeglossaries.)

The makeglossaries-lite Lua script doesn’t provide this diagnostic information, and you just get the xindy warning and error messages.

The makeglossariesgui application provides greater debugging support in its default GUI mode.

The video below shows the .aux file from the above example being opened in makeglossariesgui. This is searched for the information needed to determine which indexing application is required and which glossaries have been defined. As with the makeglossaries Perl script, makeglossariesgui determines that xindy is required and runs it. The Diagnostics tab provides information about the problem (in more detail than the terse makeglossaries messages):

Xindy won’t accept the sort value \S (for entry S) as it’s treated as an empty string. This is because xindy ignores (La)TeX commands within the sort field, so once all commands have been stripped from \S the sort field becomes empty. You will need to explicitly set the sort field using the sort key in the entry definition. Alternatively, you may prefer to use \glsxtrnewsymbol provided by the symbols package option with glossaries-extra to define symbols (which uses the label as the sort value) or consider using bib2gls instead of xindy.

In the General tab, you can click on the ‘Details’ link to view the list of entries for a particular glossary. The problematic sort values are shown in red. These need to be changed to values that will be accepted by xindy.

You can also use makeglossariesgui to test if makeglossaries and makeglossaries-lite have been installed correctly. (You need at least makeglossariesgui version 2.1 for this.)

The ‘makeglossaries’ family of applications (makeglossaries, makeglossaries-lite and makeglossariesgui) are only for documents that use \makeglossaries and \printglossary. They don’t support the other methods, but they do warn if they detect that you should be using bib2gls instead. For example, makeglossaries will report:

Found \glsxtr@resource in 'test.aux',
but not found \@istfilename.
You need to run bib2gls not makeglossaries.

makeglossaries-lite has a similar message:

No \@istfilename found but found \glsxtr@resource.
You need to run bib2gls not makeglossaries-lite.

makeglossariesgui will report the error:

This document requires bib2gls not makeindex or xindy.

In GUI mode, the diagnostics panel goes into further detail.

It seems you've used \GlsXtrLoadResources (or \glsxtrresourcefile), which means you need to run 
bib2gls -g test
(you may omit the -g switch if you don't require letter groups) and then rerun LaTeX. You don't need makeindex or xindy for this document.

(where the document file is called test.tex). It also checks if bib2gls is installed and includes instructions on how to build the document:

Found /usr/local/texlive/default/bin/x86_64-linux/bib2gls

bib2gls is needed to create the missing file 'test.glstex' to resolve undefined entry warnings. (Only one bib2gls call is required to create all .glstex files for the document if you have multiple resource sets.)

The complete build process is:

pdflatex test
bib2gls -g test
pdflatex test

(The -g switch may be omitted if you don't require letter groups.)

image of makeglossariegui's diagnostics panel