\documentclass{ltxguide}

\usepackage{ifthen,shortvrb}
\usepackage{nomencl}
\newcommand{\nomencl}{\textsf{nomencl}}
\newcommand{\MI}{\textsl{MakeIndex}}
\MakeShortVerb{\|}

%
% These macros are from D. P. Carlisle's grfguide.tex
%
\renewcommand\star{{\ttfamily*}}
\providecommand\marg[1]{{\ttfamily\char`\{}{\em#1\/}{\ttfamily\char`\}}}
\providecommand\oarg[1]{{\ttfamily[}{\em#1\/}{\ttfamily]}}
\providecommand\parg[1]{{\ttfamily(}{\em#1\/}{\ttfamily)}}

\newcommand{\meta}[1]{$\langle${\em#1\/}$\rangle$}

\begin{document}
\title{Package \nomencl.\\
Version 2.2}
\author{Boris Veytsman}
\date{11/25/96}
\maketitle
\tableofcontents
\listoffigures
%\listoftables

\section{Introduction}
Some journals (e. g. \emph{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
error-prone. The package \nomencl\ uses the powerful capabilities of the
\MI\ program to create these lists automatically.  It provides 
versatile and easily customizable tools for creating nomenclatures in
\LaTeXe\ documents.

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

\section{Installation}
\emph{Before you install\dots} You need \TeX, \LaTeXe\ (June 1995
release or later) and \MI\ 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 \MI\ style files (|.ist| files). This file (|nomencl.tex|)
provides the documentation.

\section{Usage}
\subsection{The basics}
The creation of the nomenclature list is very similar to the creation of
an index \cite[Appendix A]{Lamport94}. You need to:
\begin{itemize}
\item Put |\usepackage|\oarg{options}\marg{nomencl} in the preamble of
  your document.
  
\item Put |\makeglossary| in the preamble of your document.
  
\item Issue the |\nomenclature| command (see Section~\ref{S:nomencl})
  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.
  
\item Put |\printglossary| in the place you want to have your
  nomenclature list.
\end{itemize}

Now put your file through \LaTeX. The command |\makeglossary| will
instruct \LaTeX\ to open the glossary file \meta{filename}|.glo|,
where \meta{filename} is the name of your \TeX\ file
(\meta{filename}|.tex|) and to write there the information from your
|\nomenclature| command.

On the next step you must invoke \MI. You should instruct \MI\ to:
\begin{itemize}
\item use \meta{filename}|.glo| as your input file,
\item use |nomencl.ist| as your ``style'' file,
\item write output to the file \meta{filename}|.gls|.
\end{itemize}
How to do this depends on your implementation of \MI. For most UNIX
implementations you write something like
\begin{decl}
  |makeindex| \meta{filename}|.glo -s nomencl.ist -o|
  \meta{filename}|.gls|
\end{decl}
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 \MI\ with
different interfaces. It is discussed in more detail in
Section~\ref{sec:bugs}.

Now you have the file \meta{filename}|.gls| that contains your
nomenclature list properly ordered. On the last step you invoke
\LaTeX\ on your master file (\meta{filename}|.tex|) once more. It will
input your |.gls| file and process it accordingly to the current
options. That's all!

\subsection{The main command}\label{S:nomencl}
\begin{decl}
  |\nomenclature|\oarg{prefix}\marg{var}\marg{description}
\end{decl}
\begin{description}
\item[\meta{prefix}] is used for fine tuning the ordering (see below)
\item[\meta{var}] is the variable you want to describe
\item[\meta{description}] is the actual description
\end{description}
Put this command immediately after the equation or text that
introduces \meta{var}. Don't forget to enclose math in \meta{var} in
|$| signs\footnote{I considered including \$\dots\$ 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}. An example of the usage of the
package is shown on Fig.~\ref{F:SimpleInput} and
Fig.~\ref{F:SimpleOutput}.

\begin{figure}[tbp]
  \begin{center}
    \begin{minipage}{0.95\textwidth}
\begin{verbatim}
\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}
\end{verbatim}
    \end{minipage}
  \end{center}
  \caption{A simple input}
  \label{F:SimpleInput}
\end{figure}

\begin{figure}
  \begin{center}
    \begin{minipage}{0.6\textwidth}
      \section*{Main equations}
      \begin{equation}
        a=\frac{N}{A}
      \end{equation}
      \begin{equation}
        \sigma = m a
      \end{equation}
      
      \begin{theglossary} 
        \nomgroup{A}
      \item [$\sigma $] The total mass of angels per unit
        area\NomEquation {2}\NomPage  1 
      \item [$A$] The area of the needle point\NomEquation {1}\NomPage  1
      \item [$a$] The number of angels per unit area\NomEquation {1}\NomPage 1
      \item [$m$] The mass of one angel\NomEquation {2}\NomPage  1
      \item [$N$] The number of angels per needle point\NomEquation
        {1}\NomPage 1
      \end{theglossary}
    \end{minipage}
  \end{center}
  \caption{The output of Fig.~\protect\ref{F:SimpleInput}}
  \label{F:SimpleOutput}
\end{figure}

\subsection{Ordering of entries}

The Greek letter $\sigma$ turned out to be first in the nomenclature
list on Fig.\ref{F:SimpleOutput} because the backslash in |\sigma|
precedes any alphabetical character. Sometimes it is not what you
want.  Then you can use \meta{prefix} to fine tune the ordering. The
entries are ordered by \MI\ according to the string
\meta{prefix}\meta{var}\footnote{ For \TeX perts: the command
  |nomenclature| writes \meta{prefix}\meta{var}|@|\oarg{var}
  \meta{description} to the glossary file}.  By default the prefix is
the letter `a' \footnote{ It is neccessary to precede the `symbol' \$
  in \meta{var} by an alphabetic letter because \MI\ processes strings
  that begin with symbols in a special way, see \protect\cite{MI}.  }.
To put the definition of $\sigma$ at the end of the nomenclature list
let us change the definiton of $sigma$ on Fig.~\ref{F:SimpleInput} to
\begin{quote}
  \begin{minipage}{0.8\textwidth}
\begin{verbatim}
\nomenclature[g]{$\sigma$}{The total mass...}%
\end{verbatim}
  \end{minipage}
\end{quote}
(`g' is from `Greek'). Since the letter `a' precedes the letter `g', the
entry for $\sigma$ will be put last. Note that \MI\ will insert an
extra amount of space (|\indexspace|) between the Roman and Greek
letters (see Fig.~\ref{F:CommandsOutput}). The more sophisticated use
of \meta{prefix} for customization of the output is described in
Section~\ref{S:Cust} and illustrated by Fig.~\ref{F:GroupInput} and
Fig.~\ref{F:GroupOutput}.


\subsection{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 \meta{description}.
However, the package
|nomencl| has various means to make this task easier.

First, you can use package options:
\begin{decl}
  Package Options |refeq|, |refpage|, |norefeq|, |norefpage|
\end{decl}
The option |refeq| appends to the description the phrase ``, see
equation (\meta{eq})'', where \meta{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.~\ref{F:OptionsOutput} shows how the options |refeq| and |refpage|
influence the output.

\begin{figure}
  \setcounter{equation}{0}
  \begin{center}
    \begin{minipage}{0.9\textwidth}
      \section*{Main equations}
      \begin{equation}
        a=\frac{N}{A}
      \end{equation}
      \begin{equation}
        \sigma = m a
      \end{equation}
      \begin{theglossary} 
        \nomgroup{A}
      \item [$\sigma $] The total mass of angels per unit
        area\eqdeclaration {2}\pagedeclaration  1 
      \item [$A$] The area of the needle point\eqdeclaration
        {1}\pagedeclaration  1 
      \item [$a$] The number of angels per unit area\eqdeclaration
        {1}\pagedeclaration 1
      \item [$m$] The mass of one angel\eqdeclaration
        {2}\pagedeclaration 1
      \item [$N$] The number of angels per needle point\eqdeclaration
        {1}\pagedeclaration 1
      \end{theglossary}  
    \end{minipage}
  \end{center}
  \caption{The output of Fig.~\protect\ref{F:SimpleInput} if the options
    \texttt{refeq} and \texttt{refpage} are used}
  \label{F:OptionsOutput}
\end{figure}

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 \emph{some} entries. This can be done using
a number of commands.
\begin{decl}
  |\refeq|, |\refpage|, |\refeqpage|
\end{decl}
If any of these commands is included at the end of \meta{description},
the correponding reference is included in the nomenclature.
\emph{Warning:} dont't use both commands |\refeq| and |refpage| in the
same description---use |\refeqpage| instead!

Even more powerful command is 
\begin{decl}
  |\nomref|\marg{EqMask}\marg{PageMask}
\end{decl}

Each of the arguments can have one of the  values
(case-sensitive!) |Y|, |N|, |O| with obvious meanings (see
Table~\ref{T:Mask}).
\begin{table}
  \begin{center}
    \begin{tabular}{cl}
      \hline
      Mask & \multicolumn{1}{c}{Meaning}\\
      \hline
      Y & The reference is included\\
      N & The reference is suppressed\\
      O & Determined by the package option\\
      \hline
    \end{tabular}
  \end{center}
  \caption{Arguments of the \texttt{nomref} command}
  \label{T:Mask}
\end{table}

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.~\ref{F:CommandsInput} and Fig.~\ref{F:CommandsOutput}. 

\begin{figure}[tbp]
  \begin{center}
    \begin{minipage}{0.95\textwidth}
\begin{verbatim}
\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}
\end{verbatim}
    \end{minipage}
  \end{center}
  \caption{Referencing Commands}
  \label{F:CommandsInput}
\end{figure}

\begin{figure}
  \begin{center}
    \setcounter{equation}{0}
    \begin{minipage}{0.9\textwidth}
      \section*{Main equations}
      \begin{equation}
        a=\frac{N}{A}
      \end{equation}
      \begin{equation}
        \sigma = m a
      \end{equation}
      
      \begin{theglossary} 
        \nomgroup{A}
      \item [$A$] The area of the needle point\refeqpage \NomEquation
        {1}\NomPage 1
      \item [$a$] The number of angels per unit area\refeq
        \NomEquation {1}\NomPage 1
      \item [$m$] The mass of one angel\nomref {N}{Y}\NomEquation
        {2}\NomPage 1
      \item [$N$] The number of angels per needle point\refpage
        \NomEquation {1}\NomPage 1
        \indexspace
        \nomgroup{G}
      \item [$\sigma $] The total mass of angels per unit
        area\NomEquation {2}\NomPage 1        
      \end{theglossary}              
    \end{minipage}
  \end{center}
  \caption{The output of Fig.~\protect\ref{F:CommandsInput}}
  \label{F:CommandsOutput}
\end{figure}


\section{Customization}\label{S:Cust}

To customize the package you can redefine its commands and environments
using |\renewcommand| and |\renewenvironment|. The basic commands are
listed 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
commands |\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:
\begin{quote}
  \begin{minipage}{0.8\textwidth}
\begin{verbatim}
\renewcommand{\eqdeclaration}[1]{%
, as the brilliant equation (#1) states}
\end{verbatim}
  \end{minipage}
\end{quote}
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 \LaTeXe\ (see \cite{Lamport94}) you can format
it virtually in any way.

An additional possibility of formatting the output is provided by the
grouping feature of \MI. \MI\ separates the entries that begin with
the same letter into \emph{groups}\footnote{Non-letter symbols are
  lumped together in the same group. The grouping is
  case-insensitive.}. At the beginning of each group it inserts the
\emph{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|\marg{Letter}, where
\meta{Letter} is the first letter of all the entries of 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 \emph{Roman letters} and the
command |\nomgroup{G}| to produce the subtitle \emph{Greek letters}.
An example of such grouping is shown on Fig.~\ref{F:GroupInput}. In
the same manner you can group together subscripts, special symbols,
etc.
 
\begin{figure}[tbp]
  \begin{center}
    \begin{minipage}{0.95\textwidth}
\begin{verbatim}
\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}
\end{verbatim}
    \end{minipage}
  \end{center}
  \caption{Grouping of entries}
  \label{F:GroupInput}
\end{figure}

\begin{figure}
  \begin{center}
    \setcounter{equation}{0}
    \begin{minipage}{0.6\textwidth}
      \renewcommand{\nomgroup}[1]{%
        \ifthenelse{\equal{#1}{A}}{%
        \item \emph{Roman letters}}{%
          \ifthenelse{\equal{#1}{G}}{%
          \item \emph{Greek letters}}{}}{}}
      \section*{Main equations}
      \begin{equation}
        a=\frac{N}{A}
      \end{equation}
      \begin{equation}
        \sigma = m a
      \end{equation}
      \begin{theglossary} 
        \nomgroup{A}
      \item [$A$] The area of the needle point \NomEquation
        {1}\NomPage 1
      \item [$a$] The number of angels per unit area \NomEquation
        {1}\NomPage 1
      \item [$m$] The mass of one angel\NomEquation {2}\NomPage 1
      \item [$N$] The number of angels per needle point \NomEquation
        {1}\NomPage 1  
        \indexspace
        \nomgroup{G}
      \item [$\sigma $] The total mass of angels per unit
        area\NomEquation {2}\NomPage 1
      \end{theglossary}              
    \end{minipage}
  \end{center}
  \caption{The output of Fig.~\protect\ref{F:GroupInput}}
  \label{F:GroupOutput}
\end{figure}


\begin{decl}
  |nomencl.cfg|
\end{decl}
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.

\section{Bugs, limitations and notes}\label{sec:bugs}

I tested the package with \LaTeXe\ and |amsmath| option on MS-DOS
(g\TeX), Macintosh (Oz\TeX) and Unix (Ultrix 4.4 and Linux 2.0.0,
te\TeX).  Interesting enough, the most trouble-free environment is
g\TeX---thanks to Dr.  Young for a very stable and sound suite of
programs.  I don't have em\TeX\ on my computers, 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
\begin{quote}
  |setenv INDEXSTYLE| \meta{path} (csh)\\
  |INDEXSTYLE=|\meta{path}|; export INDEXSTYLE| (sh)
\end{quote}

On Macintosh there are two different implementations of \MI.  The older 
one is \textsl{MacMakeindex} by Johny Tolliver.  For this implementation 
you choose output and style files from the \textsf{Config} menu and the 
input file from the \textsf{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 \textsl{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:
\begin{enumerate} 
\item The input file \emph{ought to} have the extension |.idx|
\item The output file was always called |foo.ind| where |foo| was the
  filename of the |.idx| file
\item 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
\end{enumerate}
Newer versions (2.13 and later) are more flexible.  Therefore if you
use this package and Rick's program on Macintosh, either upgrade your
\MI\ or you need to:
\begin{enumerate}
\item Copy the file |nomencl.ist| to the folder where your main
  \LaTeX\ file resides and rename it \meta{filename}|.ist|, where
  \meta{filename} is the name of your \LaTeX\ file.
 
\item After \LaTeX ing rename the file \meta{filename}|.glo| to
  \meta{filename}|.idx| and execute \MI.
 
\item Rename the file \meta{filename}|.ind| to \meta{filename}|.gls|
  and execute \LaTeX\ once more.
\end{enumerate}
 
 
Some limitations of \nomencl:
\begin{enumerate}
  
\item Since the symbol `@' has a special meaning for \MI, precede it
  by the quote character (|\| by |nomencl.ist| default). The package
  does \emph{not} provide pages contracting (see \cite{MI}). If you
  need such feature, you probably need an index instead of glossary.
  
\item The arguments of the |\nomenclature| commands are moving.
  Protect the fragile commands!
  
\item 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.

\end{enumerate}

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


\section{Legalese}

The package |nomencl| is provided ``as is'' and comes with absolutely
no warranty. It is covered by the same license as the current \LaTeXe\ 
package (see the files |legal.txt| and |modguide.tex| in the \LaTeXe\ 
distribution).

\copyright Boris Veytsman, 1996


 



\begin{thebibliography}{Lam94}

\bibitem[CH]{MI}
P.~Cheng and M.~A. Harrison.
\newblock Index preparation and processing.
\newblock {CTAN}, \texttt{ind.tex}.

\bibitem[Lam94]{Lamport94}
L.~Lamport.
\newblock {\em {\LaTeX}: a document preparation system}.
\newblock 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.

\end{thebibliography}


\end{document}