summaryrefslogtreecommitdiff
path: root/indexing/glo+idxtex/glotex.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /indexing/glo+idxtex/glotex.tex
Initial commit
Diffstat (limited to 'indexing/glo+idxtex/glotex.tex')
-rw-r--r--indexing/glo+idxtex/glotex.tex445
1 files changed, 445 insertions, 0 deletions
diff --git a/indexing/glo+idxtex/glotex.tex b/indexing/glo+idxtex/glotex.tex
new file mode 100644
index 0000000000..5efe5c13fe
--- /dev/null
+++ b/indexing/glo+idxtex/glotex.tex
@@ -0,0 +1,445 @@
+\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}
+%