Automatically run makeindex from within a LaTeX-document with \write18

Screenshot of a typical nomenclature section as made with the nomencl package. Title is customized in German in this example.In my ever growing list of LaTeX-tips I have for a while recommended a LaTeX package called nomenclature which I use frequently. Up to now for this to work an extra and customized run of a program called „makeindex“ was necessary during the LaTeX-compilation process. Comparable to executing „bibtex“ for building the bibliography this causes the generation for additional files, containing the nomenclature entries before those are compiled into the LaTeX output file. Now I found a nice way to make LaTeX execute some windows command line commands from within LaTeX code. This makes not only nomenclature more compatible. makeindex can be called from the LaTeX files itself and nobody else needs to care a lot about how to compile the documents any more. It is said to run for anyone who has installed current versions of MiKTeX or TeX live as their LaTeX-distribution.

Shortly on the nomenclature package

The package nomenclature allows you to add a two columned list of „nomenclature“, the first of which can be filled with entries, letters, words, math expressions, the second column being filled with explanations. The list is automatically sorted alphabetically and each entry gets a link to the place in the document where you declare the explanation, e.g. its first occurence respectively the corresponding equation.

The problem up to now

I was never satisfied that I had to customize the LaTeX and even the makeindex execution settings to get this otherwise very nice package running. I think a program should run as much as possible ‚out of the box‘. And I am working on some LaTeX documents collaboratively with colleages. I do not consider it polite to give them a LaTeX document and force them to go through my LaTeX header before they can at least compile it whithout using the standard settings. MiKTeX is said to have the own, convenient execution mode „TeXify“, respectively „LaTeXify“ preconfigured to now only run bibtex, which I think really many people use, but also makeindex. But in my case for MikTeX 2.8 this was not the case. However, even if it is in your case, you still would need to modify the execution parameters for makeindex to match the needs of the package nomenclature, which again makes it less convenient and less easy to work with.

The \write18 command

So how did I finally solve the problem? The best solution would be to embed into the LaTeX document how it should be compiled, even which programs (like bibtex, makeindex) to run in it when compiling. There is a hidden, nice feature in LaTeX. With the command \write18 it can execute code on the command line, which is written and called from within LaTeX files (more details on \write18).
You are right if you say this is a severe security flaw. Consider it to be even a bit worse than the well known security issues of e.g. Microsoft Office documents, containing Visual Basic for Applications code, opening wide doors for evil crackers.
Well, this is the reason why the functionality is by default turned of. You could turn it on manually by calling the latex compiler with the parameter. Still this would mean a security issue, but it would be in your hands to consider a file save enough. I guess, most LaTeX users would handle it more carefully than e.g. the large majority of Microsoft Word users. MiKTeX (from the current version 2.8 on) and TeX live (from the 2009 release), two of the most widespread LaTeX distributions have chosen a way, which is much more convenient for everyone’s everyday usage. They chose a number of commands which they consider save! With this move they in principle allow security issues in those programs to intrude the security level of latex itself, but not more.
Therefore now the commands bibtex, bibtex8, epstopdf, epspdf, fc-match, kpsewhich, makeindex, ps2pdf, pstopdf, rpdfcrop can be accessed by using the \write18 command in LaTeX.

Application to the nomenclature package

Now back to running the nomenclature package „automatically“ on any computer running MiKTeX or TeX live. My LaTeX header, concerning this package, looks as follows. Particularly it is important in which order the commands are called in the file, as LaTeX locks certain files also for further processing while they are open. Please refer to the comments in this LaTeX source code snippet.


%% Load the package nomenclature
% Add \nomenclature{$A$}{A is just a letter.} anywhere in your document
% and create a nomenclature list with \printnomenclature where you want it to appear.
% The options:
% refpage for each entry in the list print the page on which the \nomenclature command is placed
% refeq for each entry in the list concerning a \nomenclature command directly after an equation print the respective equation's number in the list
\usepackage[refpage,refeq]{nomencl}

%% Utilize the LaTeX \write18 command to execute code as if from the windows command line. Therefore first define a customized command
\def\execute{%
\begingroup
\catcode`\%=12
\catcode`\\=12
\executeaux}
\def\executeaux#1{\immediate\write18{#1}\endgroup}

%% With this customized command execute the necessary command to run makeindex with the necessary parameters for the nomenclature package
% During the first run of LaTeX by the package nomenclature a file, called YOURLATEXFILEMAME.nlo is generated.
% During the second run of LaTeX, with this line makeindex generates a YOURLATEXFILENAME.nls of that.
\execute{makeindex YOURLATEXFILEMAME.nlo -s nomencl.ist -o YOURLATEXFILENAME.nls}

%% The next commands during the first run of LaTex writes the .nlo file.
% Do not change the order! Otherwise the file will be open aleady and the now first of the two commands fails silently!
\makenomenclature

How often to compile

Please also remember that now changes in the nomenclature are showing up as soon as you compiled 3 times after the last change.

  1. During the first run, the package writes a list of nomenclature entries into a .nlo file,
  2. during the second run, makeindex finds that file and compiles it to a .nls file
  3. and in the third run LaTeX with the help of the package nomenclature packs the content of the .nls file into the output file of your document.

So in principle the same procedure is going on as when you are compiling a bibliography with bibtex.

This short article does of course not cover the full capabilities of the package \nomenclature. For more details, please refer to its good manual.