diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /indexing/glo+idxtex/glotex.tex |
Initial commit
Diffstat (limited to 'indexing/glo+idxtex/glotex.tex')
-rw-r--r-- | indexing/glo+idxtex/glotex.tex | 445 |
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} +% |