\documentstyle[glo_idx,oldlfont]{pamphlet}
\def\GloTeX{Glo\TeX}  \def\BibTeX{B{\sc ib}\TeX}  \def\IdxTeX{Idx\TeX}
\pagestyle{headings}
\makeindex  \makeglossary

\begin{document}
%\coverstyle{userguide}
\title{\GloTeX\ Program}
\author{R L Aurbach}
\authorfacts{CR\&DS MIS Group \\ Monsanto Company \\ 800 N. Lindbergh Blvd. \\
St. Louis, MO 63167 \\ (314)--694--5453}
\version{Version 1.1}
\file{GloTeX}
\date{August 27, 1986}
\begin{thetitle}
\begin{abstract}
The \GloTeX\ program is used to automate the generation of a Glossary in a
\LaTeX\ document.  It uses the {\tt .glo} file generated by the
\verb~\makeglossary~ command and one or more Glossary Definition Database Files
to create a file which is \verb~\input~ in the document to generate the
Glossary. 
\end{abstract}
\end{thetitle}
\makeheading
\section{Why Automate Glossaries?}\index{#\GloTeX}
Several programs already exist to augment the capabilities of \LaTeX\ to produce
better documents --- \BibTeX\ supports the formatting and maintenance of 
bibliographies, \IdxTeX\ automates the generation of an Index, etc.  Why is a
program needed to automate the generation of Glossaries?  There are several
reasons:\index{\GloTeX>{\em raison d'\^{e}tre}}
\begin{enumerate}
\item Consider how you might actually make a glossary in a real document.
\index{\GloTeX>{\em raison d'\^{e}tre}>Make writing easier}
    \begin{itemize} 
    \item As you write the document, you come across words or phrases which
    should be included in a glossary.  You jot them down on paper somewhere.
    \item When the document is nearly finished, you take your list of terms,
    alphabetize it, and write definitions for each one.
    \item Then you write these definitions into your document and complete it.
    \end{itemize}

Think how much easier it would be if you could completely automate documents
with glossaries:
    \begin{itemize}
    \item As you write the document and come across a word or phrase to be
    included in the glossary, you place a simple \verb+\glossary+ command into
    the document.
    \item You format the document with \LaTeX\ and use \GloTeX\ to build the
    glossary.  The \GloTeX\ program will tell you about any terms you haven't
    yet defined.
    \item The definitions go into an external database, rather than directly
    into the document.  This means that you can use them again in another 
    document without retyping them.
    \end{itemize}

So \GloTeX\ can be used to make the generation of a document which contains a
glossary easier.


\item \index{\GloTeX>{\em raison d'\^{e}tre}>Re-use definitions}
Suppose you are writing a series of documents about related topics and
you decide that each should have a glossary.  You could carefully write the
definitions for each term into each document.

But, wouldn't it be easier to write the definitions only once and pull those
definitions which are needed into each document?  If you often write about a
certain topic, wouldn't it be easier to create a {\bf database} of definitions
of those terms you commonly use?

\GloTeX\ helps you maintain a database of definitions for inclusion in 
glossaries.  It supports the use of multiple definition files in a single 
document, so you can keep definitions for different terms in different places.
For example, if you are writing about an application program, you might want
to have one glossary of computer terms and another which describes the
vocabulary appropriate to that application.

\item \index{\GloTeX>{\em raison d'\^{e}tre}>Complete a partial implementation}
The standard \LaTeX\ document styles already support the most important
features needed to automate glossaries --- the \verb+\makeglossary+ and
\verb+\glossary+ commands.  Before \GloTeX, there was nothing available to 
allow you to take advantage of these \LaTeX\ features.

\end{enumerate}

\section{Building a Glossary --- Step by Step}\index{#Building a Glossary}

To automate the generation of a Glossary, here is what you do: 

\begin{itemize}
\item \index{Building a Glossary>\verb+\makeglossary+}
In the preamble of your document, include the command 
\verb+\makeglossary+.  This will cause a file to be generated when you run
\LaTeX\ which has the same filename as your \LaTeX\ file and the file type
{\tt .glo}.

\item \index{Building a Glossary>\verb+\glossary+}
In your document, for every word or phrase which you wish to appear in
the glossary, include a \verb+\glossary+ command.  The command format is
\begin{verbatim}
     \glossary{label}
\end{verbatim}
where ``label\glossary{label}'' is an identifier which is compared with the
contents of the Glossary Definition File to locate the correct definition.
This will be discussed in more detail later.

\item \index{Building a Glossary>Create {\tt .gdf} File}\glossary{gdf-file}
\index{Building a Glossary&Glossary Definition File}
If the definitions you wish to include are not already in a Glossary
Definition File, create the appropriate file.  This is discussed below.

\item \index{Building a Glossary>Create {\tt .glo} File}\glossary{glo-file}
Run \LaTeX\ on you document.  This produces the {\tt .glo} file. 

\item \index{Building a Glossary>Create {\tt .gls} File}\glossary{gls-file}
Run \GloTeX\ on the {\tt .glo} file, specifying the name of one or more
Glossary Definition Files from which definitions are to be drawn.  \GloTeX\ will
produce a file which has the same filename as you \LaTeX\ file, but with the
file type {\tt .gls}.

\item \index{Building a Glossary>Include in Source File}
In your document, insert an \verb+\input+ command, such as
\begin{verbatim}
     \input{myfile.gls}
\end{verbatim}
to include the {\tt .gls} file in your document at the appropriate place. 

\item \index{Building a Glossary>Generate Final Document}
Run \LaTeX\ twice.  The second time is needed to get the Table of Contents
entry for the Glossary to appear properly.

\end{itemize}


\section{Command Syntax}\glossary{glotex}\index{#Command Syntax}

The \GloTeX\ program is run as a foreign DCL command.\footnote{On the Monsanto
BB1T VAXcluster, the GloTeX symbol is defined by issuing the CRLSETUP command.}

The \GloTeX\ program is run using a command line of the form

\begin{verbatim}
    $ glotex  file [/STYLE={Article | Report | Special}] 
                                          [/GLOSSARY=(def1[,def2[,...]])]
\end{verbatim}

The ``file'' parameter \index{Command Syntax>File Parameter}
is required.  It is the name of the {\tt .glo} file
which is \GloTeX 's input file.  If you don't specify an input file, \GloTeX\
will prompt you for one.  You need not specify the {\tt .glo} file type.  The
default file specification for the input file is file type {\tt .glo} in your
current default directory.

The {\tt /STYLE} qualifier \index{Command Syntax>{\tt /STYLE} Qualifier}
is optional.  It describes how you wish \GloTeX\ to
format the glossary it builds.  There are three possibilities: 
\begin{infomap}
\item[Article] \index{Command Syntax>{\tt /STYLE} Qualifier>{\tt Article} 
keyword} The {\tt Article} keyword is used if your document uses the 
standard \LaTeX\ {\tt article} document style or any other section oriented
style.  If you specify this keyword, then the glossary is built as a regular,
numbered section in your document.  It will appear in your Table of Contents
automatically.
\item[Report]  \index{Command Syntax>{\tt /STYLE} Qualifier>{\tt Report}
keyword}  The {\tt Report} keyword is used if your document uses the 
standard \LaTeX\ {\tt report} or {\tt book} document styles or any other
chapter oriented style.  If you specify this keyword, then the glossary is built
as an unnumbered chapter in your document.  It will appear in your Table of
Contents automatically.
\item[Special] \index{Command Syntax>{\tt /STYLE} Qualifier>{\tt Special}
keyword}  The {\tt Special} keyword is used if your document uses any of
the Monsanto CR\&DS document styles ({\tt pamphlet}, {\tt manual}, or 
{\tt memo}).  They already define commands to format the glossary
appropriately --- using the {\tt Special} keyword tells \GloTeX\ not to include
commands in its output file to redefine these commands for you.

In section-oriented Monsanto CR\&DS document styles, the glossary is formatted
as a numbered section.  In the chapter-oriented {\tt manual} document style, the
glossary is an unnumbered chapter, with page numbers of the form 

``\mbox{Glossary--nn}''.

If you do not include the {\tt /STYLE} qualifier, {\tt Special} is assumed.
\end{infomap}

The {\tt /GLOSSARY} qualifier \index{Command Syntax>{\tt /GLOSSARY} Qualifier}
is used to specify the list of Glossary Definition
Files which \GloTeX\ will search to find the definitions you wish to include.
You may include as many files as you wish --- \GloTeX\ will search them in the
order you specify.  For each file, \GloTeX\ will look for a file with the file
type {\tt .gdf} in your current default directory, unless you override the
defaults.

The {\tt /GLOSSARY} qualifier is optional.  However, you must use it unless
you are using a Monsanto CR\&DS document style, because there is no other way
for \GloTeX\ to know where your definitions are to be found.\footnote{If you use
a Monsanto CR\&DS document style, special commands are available to allow you to
build the glossary definition file specifications into your document. They are
described later.}

\begin{note}
\GloTeX\ prints a list of all those labels which are present in your input file,
but for which it can't find any definition.  This report is output both on your
terminal and to a Glossary Log File ({\tt .glg} file).\glossary{glg-file}

You can use this feature to make a list of terms needing definition.

\end{note}

\section{Building a Glossary --- More Detail}\index{#Building a Glossary}

This section discusses the steps needed to build a Glossary in more detail.
In this section, we assume that the source file for your document is named
{\tt myfile.tex}.

\begin{infomap}

\item[{\tt makeglossary}\\Command] 
\index{Building a Glossary>\verb+\makeglossary+} 
\LaTeX\ creates a list of those terms to be included in the Glossary in a file
named (in this example) {\tt myfile.glo}. This file is not created
automatically.  If you want one, you must include the \verb+\makeglossary+
command in your document.

The \verb+\makeglossary+ command must be placed in the preamble of your source 
file --- that is, between the \verb+\documentstyle+ command and the
\verb+\begin{document}+ command.

\item[{\tt glossary}\\Command] \index{Building a Glossary>\verb+\glossary+}
When you come across a word or phrase in your document which you would like to
define in the Glossary, insert a \verb+\glossary+ command in your source file.
The format of this command is 
\begin{verbatim}
     \glossary{label}
\end{verbatim}
where ``label'' is an identifier you assign to this word or phrase.  This
identifier is used to locate the definition in a Glossary Definition File which
you wish to be included.  That is, if ``label'' matches the identifier belonging
to a definition in the database, then that definition will be included in the	
Glossary.

For example, in this document, the entry \verb+\glossary{glo-file}+ 
\glossary{glo-file} appears.  As you can see by examining the glossary, there
is a definition for the term ``{\tt glo} File'', which was generated as a
result of this reference.

\item[Generating the\\{\tt glo} File] 
\index{Building a Glossary>Create {\tt .glo} File}
Having prepared your document, the next step is to run it through \LaTeX.  This
will generate a file {\tt myfile.glo} which contains the collected information
from the \verb+\glossary+ commands which you placed in your document.

\item[Building the\\{\tt gls} File] 
\index{Building a Glossary>Create {\tt .gls} File}
The next step is to use the \GloTeX\ program to generate the glossary
information, using the {\tt myfile.glo} file and the appropriate Glossary
Definition Files.

In our example, we will make several assumptions.  
\begin{enumerate}
\item Lets assume that your document {\tt myfile.tex} uses the standard \LaTeX\
{\tt article} document style. 
\item Lets also assume that you are using definitions from three sources ---
a local glossary of application specific terms, a public glossary of 
biological terms, and a public glossary of computer terms.  The biological
glossary is assumed to be located in the {\tt GenLocDoc:} area, while the
computer glossary is located in the {\tt CRL\_Documentation:} area.
\end{enumerate}

Then, the command line
\begin{verbatim}
     $ glotex myfile /STYLE=Article -
     $_    /GLOSSARY=(myglos,GenLocDoc:BioDefs,-
     $_              Crl_Documentation:EDPDefs)
\end{verbatim}
will process the {\tt myfile.glo} file, using the three specified Glossary
Definition Files, and produce the file {\tt myfile.gls}, formatted appropriately
for the standard \LaTeX\ {\tt article} document style.

\item[Including the\\{\tt gls} File] 
\index{Building a Glossary>Include in Source File}
Normally, a Glossary is placed in the document at the end, just before the
index.  Most people place the Glossary {\bf before} the Bibliography, if both
exist in the document, but that is a matter of personal choice.

In any case, once you decide where to put the Glossary, it is merely necessary
to add the command
\begin{verbatim}
     \input{myfile.gls}
\end{verbatim}
in the appropriate place.

\item[Generate the\\Final Document]\index{Building a Glossary>Generate Final Document}
Now you are ready to generate the final document.  To do this, run \LaTeX\ on
the document twice.  The first time you run \LaTeX, the Glossary will be
included in your document and a reference will be made to include a Table of
Contents entry for it.  The second time you run \LaTeX, the Table of Contents
will be updated to include an entry for the Glossary. 

\end{infomap}

\section{Glossary Definition Files}
\glossary{gdf}\glossary{label}\glossary{item}\glossary{definition}
\index{#Glossary Definition File}\index{#{\tt gdf} file}

A Glossary Definition File is a text file which contains one or more definitions
of words or phrases (an ``entry'') in a special, defined format.  A Glossary
Definition File is also called a {\tt .gdf} file, because the default file type
for these files is {\tt .gdf}.

A entry in a {\tt .gdf} file has three parts.
\begin{infomap}
\item[label]  \index{Glossary Definition File>Label}
The {\em label\/} is an identifier used to associate a particular
definition with a particular \verb+\glossary+ command from the document. 

The label is a {\bf case sensitive} string.  If the label of an entry in the
{\tt .gdf} file matches a label specified in a \verb+\glossary+ command exactly
(character for character, including any whitespace characters), then the
term will be included in the Glossary.

\item[item] \index{Glossary Definition File>Item}
The {\em item\/} is the word or phrase being defined by the entry.
Visually, the item appears on the left-hand portion of the page, separated from
the definition.

Glossary entries are formatted in an {\tt infomap} environment,\footnote{for
those familiar with the CR\&DS Extensions to \LaTeX.}  a special variation of
the {\tt description} environment.\footnote{If you specify /STYLE:ARTICLE or
/STYLE:REPORT in your command line, \GloTeX\ will automatically include in its
output file the commands needed to define this new environment.}  In an {\tt
infomap} environment, the item is placed in a \verb+\parbox+.  If the item is
too long for the space allotted it, it will be typeset in multiple lines.  You
can often help this process along by careful inclusion of \verb+\\+ commands in
the item to control where the lines are split.

The default formatting in an item is {\bf boldface}.  Other possibilities are
available, however.  In this document, for example, the item ``glo File'' was
entered as ``\verb+{\tt glo} File+''.  Notice that the term appears in the
correct alphabetical order, in spite of the presence of the special formatting
characters.

\item[definition]  \index{Glossary Definition File>Definition}
The definition is the body of the glossary entry.  It 
consists of as much normal \LaTeX\ source as you wish --- multiple paragraphs,
lists, etc., are all supported.  However, experience has shown that a
glossary entry which is two or three sentences long is normally plenty.  Very
long entries lose their effectiveness with the reader.

\end{infomap}

The format of an entry in a {\tt .gdf} file is
\index{Glossary Definition File>Format}
\begin{verbatim}
     @entry{label, item} definition
     definition (continued...)
\end{verbatim}

A new entry in the file begins with ``{\tt @entry}'' in lower case, and as the
first characters on a new line.  The {\tt @entry} command takes two arguments
--- the label and the item strings.  The item string is optional --- if it is
not specified, then the label string will be used as the item string as well.

The definition may begin on the {\tt @entry} line, although that is not
required.  All text is considered as definition, beginning with the first
character after the closing brace of the {\tt @entry} command up to the
next {\tt @entry} command or the end of the file.

As an example, below is a portion of the {\tt .gdf} file used to generate the
Glossary of this document. \index{Glossary Definition File>Example}

\begin{verbatim}
     @entry{glo-file, {\tt glo} File} The {\tt .glo} file is
     produced by \LaTeX\ and contains a list of labels for
     terms to be included in the Glossary.  It is one of the
     inputs to \GloTeX. 

     @entry{item} An {\em item\/} is the word or term to be 
     defined in the glossary.
\end{verbatim}

	
\appendix
\section{\LaTeX\ Extensions Which Support Glossaries}

Standard \LaTeX\ document styles define the \verb+\makeglossary+ and
\verb+\glossary+ commands described above.  If you are using standard
\LaTeX\ document styles, these are the only commands available to you.

If you use one of the CR\&DS document styles ({\tt pamphlet}, {\tt manual}, or
{\tt memo}), then additional commands are defined which make glossary generation
even nicer.\footnote{This section is only relevant at sites which use the 
Monsanto CR\&DS special document styles.  It should be ignored otherwise.}

\begin{infomap}

\item[{\tt theglossary}\\Environment]
\index{New Glossary Commands>{\tt theglossary} Environment}
The {\tt theglossary} environment is
the context for a glossary.  That is, a glossary begins with the
\verb+\begin{theglossary}+ command and ends with the \verb+\end{theglossary}+
command.  Each CR\&DS document style defines this environment so that the
formatting of the Glossary is appropriate to the document.  When you specify
{\tt /STYLE = Article} or {\tt /STYLE = Report}, \GloTeX\ includes in the 
{\tt .gls} file the necessary commands to define this environment for you.
\item[{\tt glossaryfile}\\Command]  
\index{New Glossary Commands>{\tt glossaryfile} Command}
The \verb+\glossaryfile+ command is used
to specify one or more {\tt .gdf} files to be used to locate definitions.
The format of the command is
\begin{verbatim}
     \glossaryfile{filelist}
\end{verbatim}
where filelist is either a single file specification or a list of file
specifications, separated by commas.

You may specify more than one \verb+\glossaryfile+ command if you wish.  The
{\tt .gdf} files you specify are searched in the following order:
\begin{enumerate}
\item Any {\tt .gdf} files specified on the command line using the {\tt 
/GLOSSARY} qualifier are searched in the order specified.
\item Any {\tt .gdf} files specified in the first \verb+\glossaryfile+ command
in the source document are searched in the order specified.
\item Addition {\tt .gdf} files are searched in order as specified by additional
\verb+\glossaryfile+ commands.
\end{enumerate}

\item[{\tt insertglossary}\\Command]  
\index{New Glossary Commands>{\tt insertglossary} Command}
The \verb+\insertglossary+ command is
used to place a glossary at a particular place in the document.  It is
equivalent to issuing the \verb+\input{myfile.gls}+ command, where {\tt myfile}
is the name of the source document.

\end{infomap}

\input{glotex.gls}

\input{glotex.ind}

\input{idxtex.mnd}

\tableofcontents

\end{document}
%