Package nomencl. Version 2.2

Boris Veytsman

11/25/96

Contents

1 Introduction 1

2 Installation 2

3 Usage 2 3.1 The basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 3.2 The main command . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.3 Ordering of entries . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.4 Referencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

4 Customization 6

5 Bugs, limitations and notes 8

6 Legalese 10

List of Figures

1 A simple input . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2 The output of Fig. 1 . . . . . . . . . . . . . . . . . . . . . . . . . 4 3 The output of Fig. 1 if the options refeq and refpage are used . 5 4 Referencing Commands . . . . . . . . . . . . . . . . . . . . . . . 6 5 The output of Fig. 4 . . . . . . . . . . . . . . . . . . . . . . . . . 7 6 Grouping of entries . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7 The output of Fig. 6 . . . . . . . . . . . . . . . . . . . . . . . . . 9

1 Introduction

Some journals (e. g. AIChE Journal) require the authors to include lists of the used symbols in their articles. It seems that some universities require such lists in the theses.

Of course one can make such lists by hand. However it is tedious and errorprone. The package nomencl uses the powerful capabilities of the MakeIndex program to create these lists automatically. It provides versatile and easily customizable tools for creating nomenclatures in L^{A}TEX 2ε documents.

While the package was written mainly for creating nomenclatures, it can be also used for creating and customizing glossaries.

2 Installation

Before you install… You need TEX, L^{A}TEX 2ε (June 1995 release or later) and MakeIndex to use the package nomencl.

The installation is very simple. Put the file nomencl.sty where your store TEX-inputs files, and the file nomencl.ist where you store MakeIndex style files (.ist files). This file (nomencl.tex) provides the documentation.

3 Usage

3.1 The basics

The creation of the nomenclature list is very similar to the creation of an index [Lam94, Appendix A]. You need to:

• Put \usepackage[⟨options⟩]{nomencl} in the preamble of your document.

• Put \makeglossary in the preamble of your document.

• Issue the \nomenclature command (see Section 3.2) for each symbol you want to be included in the nomenclature list. The best place for this command is immediately after you introduce the symbol for the first time.

• Put \printglossary in the place you want to have your nomenclature list.

Now put your file through L^{A}TEX. The command \makeglossary will instruct L^{A}TEX to open the glossary file ⟨filename⟩.glo, where ⟨filename⟩ is the name of your TEX file (⟨filename⟩.tex) and to write there the information from your

\nomenclature command.

On the next step you must invoke MakeIndex. You should instruct MakeIndex to:

• use ⟨filename⟩.glo as your input file,

• use nomencl.ist as your “style” file,

• write output to the file ⟨filename⟩.gls.

How to do this depends on your implementation of MakeIndex. For most UNIX implementations you write something like

makeindex ⟨filename⟩.glo -s nomencl.ist -o ⟨filename⟩.gls

For DOS you use the same command line, with makeidx instead of makeindex. The situation for Macintosh is more complex because at the moment there exist several different implementation of MakeIndex with different interfaces. It is discussed in more detail in Section 5.

Now you have the file ⟨filename⟩.gls that contains your nomenclature list properly ordered. On the last step you invoke L^{A}TEX on your master file (⟨filename⟩.tex) once more. It will input your .gls file and process it accordingly to the current options. That’s all!

3.2 The main command

\nomenclature[⟨prefix⟩]{var}{description}

⟨prefix⟩ is used for fine tuning the ordering (see below)

⟨var⟩ is the variable you want to describe

⟨description⟩ is the actual description

Put this command immediately after the equation or text that introduces ⟨var⟩. Don’t forget to enclose math in ⟨var⟩ in $ signs^{1}. An example of the usage of the package is shown on Fig. 1 and Fig. 2.

3.3 Ordering of entries

The Greek letter σ turned out to be first in the nomenclature list on Fig.2 because the backslash in \sigma precedes any alphabetical character. Sometimes it is not what you want. Then you can use ⟨prefix⟩ to fine tune the ordering. The entries are ordered by MakeIndex according to the string ⟨prefix⟩⟨var⟩^{2}. By default the prefix is the letter ‘a’ ^{3}. To put the definition of σ at the end of the nomenclature list let us change the definiton of sigma on Fig. 1 to

     \nomenclature[g]{$\sigma$}{The total mass...}%

1I considered including $… $ in the definition of the nomenclature command, but then decided against it. In the way it is now you can use this package for producing glossaries of non-math terminology. Besides, you can use regular expression search for math in a more consistent way

2For TEXperts: the command nomenclature writes ⟨prefix⟩⟨var⟩@[⟨var⟩] ⟨description⟩ to the glossary file

3It is neccessary to precede the ‘symbol’ $ in ⟨var⟩ by an alphabetic letter because MakeIndex processes strings that begin with symbols in a special way, see [CH].

\documentclass{article}
\usepackage{nomencl}
\makeglossary
\begin{document}
\section*{Main equations}
\begin{equation}
  a=\frac{N}{A}
\end{equation}%
\nomenclature{$a$}{The number of angels per unit area}%
\nomenclature{$N$}{The number of angels per needle point}%
\nomenclature{$A$}{The area of the needle point}%
\begin{equation}
  \sigma = m a
\end{equation}%
\nomenclature{$\sigma$}{The total mass of angels per unit area}%
\nomenclature{$m$}{The mass of one angel}%
\printglossary
\end{document}

Figure 1: A simple input

Main equations

a = \frac{N}{A}  (1)
σ = ma  (2)

Nomenclature

σ The total mass of angels per unit area

A The area of the needle point

a The number of angels per unit area

m The mass of one angel

N The number of angels per needle point

Figure 2: The output of Fig. 1

Main equations

a = \frac{N}{A}  (1)
σ = ma  (2)

Nomenclature

σ The total mass of angels per unit area, see equation (2), page 1

A The area of the needle point, see equation (1), page 1

a The number of angels per unit area, see equation (1), page 1

m The mass of one angel, see equation (2), page 1

N The number of angels per needle point, see equation (1), page 1

Figure 3: The output of Fig. 1 if the options refeq and refpage are used

(‘g’ is from ‘Greek’). Since the letter ‘a’ precedes the letter ‘g’, the entry for σ will be put last. Note that MakeIndex will insert an extra amount of space (\indexspace) between the Roman and Greek letters (see Fig. 5). The more sophisticated use of ⟨prefix⟩ for customization of the output is described in Section 4 and illustrated by Fig. 6 and Fig. 7.

3.4 Referencing

Sometimes a reference to the equation or page where the symbol was introduced gives more information than the long definition. You can insert references manually using something like see equation (\protect\ref{MyEq}) in the ⟨description⟩. However, the package nomencl has various means to make this task easier.

First, you can use package options:

Package Options refeq, refpage, norefeq, norefpage

The option refeq appends to the description the phrase “, see equation (⟨eq⟩)”, where ⟨eq⟩ is the number of the last equation before the command \nomenclature. Analoguously the option refpage inserts the reference to the number of the page corresponding to the command \nomenclature. The options norefeq and norefpage are default. They do not produce the corresponding reference. Fig. 3 shows how the options refeq and refpage influence the output.

It seems that the package options refeq and refpage are useful while preparing the manuscript. They allow you to quickly find the \nomenclature command in the text. However in the final version you may want to reference only some entries. This can be done using a number of commands.

Mask  Meaning
Y The reference is included
N The reference is suppressed
O Determined by the package option

Table 1: Arguments of the nomref command

  \documentclass{article}
  \usepackage{nomencl}
  \makeglossary
  \begin{document}
  \section*{Main equations}
  \begin{equation}
    a=\frac{N}{A}
  \end{equation}%
  \nomenclature{$a$}{The number of angels per unit area\refeq}%
  \nomenclature{$N$}{The number of angels per needle point\refpage}%
  \nomenclature{$A$}{The area of the needle point\refeqpage}%
  \begin{equation}
    \sigma = m a
  \end{equation}%
  \nomenclature[g]{$\sigma$}{The total mass of angels per unit area}%
  \nomenclature{$m$}{The mass of one angel\nomref{N}{Y}}%
  \printglossary
  \end{document}

Figure 4: Referencing Commands

\refeq, \refpage, \refeqpage

If any of these commands is included at the end of ⟨description⟩, the correponding reference is included in the nomenclature. Warning: dont’t use both commands \refeq and refpage in the same description—use \refeqpage instead!

Even more powerful command is

\nomref{EqMask}{PageMask}

Each of the arguments can have one of the values (case-sensitive!) Y, N, O with obvious meanings (see Table 1).

For example, the commands \refeq, \refpage and \refeqpage are defined as

\nomref{Y}{O}, \nomref{O}{Y} and \nomref{Y}{Y} correspondingly.

An example of using these commands is shown on Fig. 4 and Fig. 5.

4 Customization

To customize the package you can redefine its commands and environments using \renewcommand and \renewenvironment. The basic commands are listed

a = \frac{N}{A}  (1)
σ = ma  (2)

Nomenclature

A The area of the needle point, see equation (1), page 1

a The number of angels per unit area, see equation (1)

m The mass of one angel, page 1

N The number of angels per needle point, page 1

σ The total mass of angels per unit area

Figure 5: The output of Fig. 4

here.

The default prefix in the \nomenclature command is determined by the

\nomprefix command.

The phrases that reference equations and pages are determined by the com-

mands \eqdeclaration and \pagedeclaration. Both these commands have

one argument—the number of the equation or the page. For example, if you put in the preamble of your document the following lines:

     \renewcommand{\eqdeclaration}[1]{%
     , as the brilliant equation (#1) states}

your document will proudly announce how good you are.

The title of the nomenclature section is determined by the command \nomname.

By default it is \section*{Nomenclature}.

The format of the nomenclature list itself is determined by the environment theglossary. By default it is a simple description environment with \nomname in the beginning. Using the powerful list capabilities of L^{A}TEX 2ε (see [Lam94]) you can format it virtually in any way.

An additional possibility of formatting the output is provided by the grouping feature of MakeIndex. MakeIndex separates the entries that begin with the same letter into groups^{4}. At the beginning of each group it inserts the group header, and between the groups it inserts the amount of vertical space \indexspace. The file \nomencl.ist determines the group header as the command \nomgroup{Letter}, where ⟨Letter⟩ is the first letter of all the entries of

4Non-letter symbols are lumped together in the same group. The grouping is caseinsensitive.

  \documentclass{article}
  \usepackage{nomencl}
  \usepackage{ifthen}
  \makeglossary
  \renewcommand{\nomgroup}[1]{%
          \ifthenelse{\equal{#1}{A}}{%
                  \item \emph{Roman letters}}{%
                  \ifthenelse{\equal{#1}{G}}{%
                          \item \emph{Greek letters}}{}}{}}
  \begin{document}
  \section*{Main equations}
  \begin{equation}
    a=\frac{N}{A}
  \end{equation}%
  \nomenclature{$a$}{The number of angels per unit area}%
  \nomenclature{$N$}{The number of angels per needle point}%
  \nomenclature{$A$}{The area of the needle point}%
  \begin{equation}
    \sigma = m a
  \end{equation}%
  \nomenclature[g]{$\sigma$}{The total mass of angels per unit area}%
  \nomenclature{$m$}{The mass of one angel}%
  \printglossary
  \end{document}

Figure 6: Grouping of entries

the group (upper case). By default this command produces nothing. However it can be redefined to do something nice. For example, suppose that we precede all Greek letters by the prefix [g]. Then we will have two groups: Roman letters that begin with the default prefix ‘a’ and Greek letters that begin with the prefix ‘g’. Now we can request the command \nomgroup{A} to produce the subtitle Roman letters and the command \nomgroup{G} to produce the subtitle Greek letters. An example of such grouping is shown on Fig. 6. In the same manner you can group together subscripts, special symbols, etc.

nomencl.cfg

If you have some customization commands that you use consistently in many documents, put them in the file nomencl.cfg. If this file exists in your search path, it is read by the nomencl package.

5 Bugs, limitations and notes

I tested the package with L^{A}TEX 2ε and amsmath option on MS-DOS (gTEX), Macintosh (OzTEX) and Unix (Ultrix 4.4 and Linux 2.0.0, teTEX). Interesting enough, the most trouble-free environment is gTEX—thanks to Dr. Young for a very stable and sound suite of programs. I don’t have emTEX on my computers,

a = \frac{N}{A}  (1)
σ = ma  (2)

Nomenclature

Roman letters

A The area of the needle point

a The number of angels per unit area

m The mass of one angel

N The number of angels per needle point

Greek letters

σ The total mass of angels per unit area

Figure 7: The output of Fig. 6

so I cannot test the package for this environment. Please inform me about any problems here.

On Unix it seems that the search path for .ist files is not defined by kpathsea. You can define it by the environment variable INDEXSTYLE. Issue a command equivalent to

     setenv INDEXSTYLE ⟨path⟩ (csh)
     INDEXSTYLE=⟨path⟩; export INDEXSTYLE (sh)

On Macintosh there are two different implementations of MakeIndex. The older one is MacMakeindex by Johny Tolliver. For this implementation you choose output and style files from the Config menu and the input file from the File menu. Unfortunately this implementation cannot handle index entries longer than about 80 letters. It makes it almost useless for glossary handling.

A newer implementation is MakeIndex Fat by Rick Zaccone. It works for Power Mac and 680x0 and has no limit for the length of the entries. The interface of older versions (around 1.1) was very limited:

1. The input file ought to have the extension .idx

2. The output file was always called foo.ind where foo was the filename of the .idx file

3. The style file ought to be called foo.ist where foo was the filename of the .idx file and it ought to be in the same folder as the foo.idx file Newer versions (2.13 and later) are more flexible. Therefore if you use this package and Rick’s program on Macintosh, either upgrade your MakeIndex or you need to:

1. Copy the file nomencl.ist to the folder where your main L^{A}TEX file resides and rename it ⟨filename⟩.ist, where ⟨filename⟩ is the name of your L^{A}TEX file.

2. After L^{A}TEXing rename the file ⟨filename⟩.glo to ⟨filename⟩.idx and execute MakeIndex.

3. Rename the file ⟨filename⟩.ind to ⟨filename⟩.gls and execute L^{A}TEX once more.

Some limitations of nomencl:

1. Since the symbol ‘@’ has a special meaning for MakeIndex, precede it by the quote character (\ by nomencl.ist default). The package does not provide pages contracting (see [CH]). If you need such feature, you probably need an index instead of glossary.

2. The arguments of the \nomenclature commands are moving. Protect the fragile commands!

3. The handling of Greek letters is far from perfect but can be improved by the judicious use of the optional argument of the \nomenclature command.

Feel free to report bugs and suggestions to boris@plmsc.psu.edu. You can

find new version of the package at http://planck.plmsc.psu.edu/~boris.

6 Legalese

The package nomencl is provided “as is” and comes with absolutely no warranty. It is covered by the same license as the current L^{A}TEX 2ε package (see the files legal.txt and modguide.tex in the L^{A}TEX 2ε distribution).

\begin{matrix}c \\ ◯ \end{matrix}Boris Veytsman, 1996

References

[CH] P. Cheng and M. A. Harrison. Index preparation and processing.

        CTAN, ind.tex.

[Lam94] L. Lamport. L^{A}TEX: a document preparation system. Addison-Wesley Publishing Company, Reading, Ma; Menlo Park, Ca; New York; Don Mills, Ontario; Workingham, England; Amsterdam; Bonn; Sydney; Syngapore; Tokyo; Madrid; San Juan; Milan; Paris, 2 edition, 1994.