\documentstyle[twoside]{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}
\version{Version 1.0}
\file{GloTeX}
\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}

\pagenumbering{roman}
\tableofcontents

\pagenumbering{arabic}

\makeheading

\section{Why Automate Glossaries?}

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 used 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}

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}
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 a foreign DCL command, and should be set up as
\begin{verbatim}
     $ glo*tex :== $TeX:GloTeX
\end{verbatim}
It 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.  It 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 a document
style which already defines the {\tt theglossary} environment --- using the {\tt
Special} keyword tells \GloTeX\ not to include commands in its output file to
redefine these commands for you. 

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, if you do not include the
qualifier, no glossary will be produced, because there is no other way for 
\GloTeX\ to know where your definitions are to be found.  

\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 by 
deliberately omitting the {\tt /GLOSSARY} qualifier.
\end{note}

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

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 (and it's necessary to use \GloTeX) 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 We assume that your document {\tt myfile.tex} uses the standard \LaTeX\
{\tt article} document style. 
\item We also assume that you are using definitions from two sources ---
a local glossary of application specific terms, and a public glossary of 
computer terms.  The computer glossary is located in the {\tt Doc:} area.
\end{enumerate}

Then, the command line
\begin{verbatim}
     $ glotex myfile /STYLE=Article -
     $_    /GLOSSARY=(myglos,Doc: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 a modified {\tt description} environment 
in which the item is formatted in a {\tt 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
\input{glotex.gls}

\input{glotex.ind}
\end{document}