# 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 package. 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 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 discovered 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
src={terms,abbrvs}% data in terms.bib and abbrvs.bib
]

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).

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.

The button runs the application identified in the neighbouring selector. In this case is selected. If I click on the 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.

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 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 and click on the 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 and click on the 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 and click on the button, and then select the tool to run the provided script to create all the glossary files, and then reselect and click on the 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.

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.

### TeXworks

To add a new tool to TeXworks, use the menu item to open the preferences window, and select the tab:

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 button, which opens the dialog, shown below:

• To add the makeglossaries Perl script:
1. Type MakeGlossaries in the area.
2. Click on the button to search for the makeglossaries 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.
3. There’s one required argument, which is the document’s base name (or job name). With TeXworks, this is identified by the placeholder $basename. To add an argument, click on the button (next to the list) and type $basename (followed by enter/return ⏎).
4. Uncheck the box. (The PDF file isn’t modified by this tool.)

• To add the makeglossaries-lite Lua script, follow the same process as above, but select makeglossaries-lite (or makeglossaries-lite.exe or makeglossaries-lite.lua). If you can’t find it, check your version of glossaries (it will be in the .log transcript file). If it’s older than version 4.16 (2016-10-12), then you need to update your version of glossaries.
• To add the makeglossariesgui Java application:
1. Install makeglossariesgui.
2. In TeXworks, open the dialog, as described above.
3. Type MakeGlossariesGUI in the area.
4. Unix-like users:
• Click on the button to search for the makeglossariesgui bash script, located in the bin sub-directory of the directory where you installed makeglossariesgui.
• Add the argument --batch
• Add the argument $basename Windows users: • Click on the button to search for the javaw.exe application. • Add the argument -jar • For the next argument, find the file makeglossariesgui.jar, which should be in the lib sub-directory of the folder where you installed makeglossariesgui, and add the full path name as the next argument. • Add the argument --batch • Add the argument $basename
5. Uncheck the box. (The PDF file isn’t modified by this tool.)
• To add the bib2gls Java application:
2. Install bib2gls. (It’s now contained in both TeX Live and MikTeX, so you should be able to use your TeX package manager to install it.)
3. In TeXworks, open the dialog, as described above.
4. Type Bib2Gls in the area.
5. Click on the button to search for the bib2gls 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 --group (optional).
7. Add the argument $basename (required). 8. Uncheck the box. (The PDF file isn’t modified by this tool.) You only need to configure the tools that you actually want to use. Here I’ve created the MakeGlossaries and Bib2Gls tools: 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 dialog, as described above. 4. Type Arara in the area. 5. Click on the 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 box is checked. (This tool will modify the PDF.)

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 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.

• makeglossaries or makeglossaries-lite:
1. In TeXmaker, select the menu item. This opens a window.
2. In the upper box add makeglossaries (this is the display name). Replace this with makeglossaries-lite if you prefer to use the Lua script.
3. In the lower box, add makeglossaries % (here the placeholder identifying the base name is the % symbol). Replace this with makeglossaries-lite % if you prefer to use the Lua script instead (but check that your version of the glossaries package includes it).
• bib2gls:
2. Use your TeX package manager to install bib2gls.
3. In TeXmaker, select the menu item. This opens a window.
4. In the upper box add bib2gls (the display name).
5. In the lower box, add bib2gls --group % (you may omit --group if you don’t need letter groups).
• arara:
2. Use your TeX package manager to install arara.
3. In TeXmaker, select the menu item. This opens a window.
4. In the upper box add arara (the display name).
5. In the lower box, add arara % (the command with placeholder).

### 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.

• makeglossaries or makeglossaries-lite:
1. Use the menu item . This should open the dialog.
2. Select the required profile you want to modify. For example, LaTeX => PDF and click on the tab:

3. Click on the new button and type in the name of the required tool (makeglossaries or makeglossaries-lite):

4. Click on the browse (…) button next to the executable field and search for makeglossaries.exe or makeglossaries-lite.exe. If you don’t have Perl and can’t find makeglossaries-lite.exe, check your version of the glossaries package and update it if it’s too old.
5. In the box, use the placeholder "%bm" to indicate the base name.
6. Click on when you’re done.
• bib2gls:
2. Use your TeX package manager to install bib2gls.
3. Use the menu item to open the dialog.
4. Select the required profile you want to modify. For example, LaTeX => PDF and click on the tab.
5. Click on the new button and type bib2gls.
6. Click on the browse (…) button next to the executable field and search for bib2gls.exe
7. In the box, use the placeholder "%bm" to indicate the base name. If you also want letter groups you need: --group "%bm" instead.
8. Click on when you’re done.
• To use arara with TeXnicCenter, you need to create a new output profile. There is more information about this in the TeXnicCenter manual. From the information on that page, it seems that you need to do the following (untested):
2. Use your TeX package manager to install arara.
3. Use the menu item to open the dialog.
4. Click on the button below the list.
5. Call the new profile ‘Arara’.
6. Make sure the box is checked, but set the to the path to the arara.exe file (for example, C:\Program Files\MikTeX 2.8\miktex\bin\arara.exe).
7. For the command line arguments, just have "%pm"
8. Leave the BibTeX and MakeIndex boxes unchecked.

### 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).

2. Use your TeX package manager to install arara.

### TeXShop

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

• An engine for makeglossaries and bib2gls:
1. If you want to use bib2gls, check you have Java installed (download Java) and use your TeX package manager to install bib2gls.
2. Create a file called glossaries.engine in the directory ~/Library/TeXShop/Engines that contains:
#!/bin/sh

PATH=/Library/TeX/texbin:/usr/local/bin:${PATH} bfname=${1%\.*}

pdflatex "$1" if grep -q "glsxtr@resource" "$bfname.aux"; then
bib2gls --group "$bfname" # hybrid if grep -q "@istfilename" "$bfname.aux"; then
pdflatex "$1" makeglossaries "$bfname"
fi

elif grep -q "@istfilename" "$bfname.aux"; then makeglossaries "$bfname"
fi

pdflatex "$1"  (replace pdflatex with xelatex etc, as appropriate). If you don’t plan on having a hybrid bib2gls+makeglossaries, you can omit the inner conditional. (There’s no need for a hybrid approach unless you have a particular xindy customization that can’t be reproduced with bib2gls, but you want the convenience of storing entry definitions in .bib files.) 3. Make this new file executable. In the terminal enter: cd ~/Library/TeXShop/Engines chmod u+x glossaries.engine  4. Select this engine from the list near the typeset button. • An engine for arara: 1. Check you have Java installed (download Java). 2. Use your TeX package manager to install arara. 3. Create a file called arara.engine in the directory ~/Library/TeXShop/Engines that contains: #!/bin/sh PATH=/Library/TeX/texbin:/usr/local/bin:${PATH}
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 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 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',
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.)