Integrated Glossary and Index

A large number of different pieces of software are required to make L^ATEX2HTML work effectively, as well as many files containing data or code to work with parts of this software. For this reason, a Glossary is included with this manual. It contains the names of all files, configuration variables, application software and related technical terms, with a short description of what it is, or does, and perhaps a URL for further reference.

In the printed version each item in the Glossary is accompanied by the page-numbers on which the item is mentioned, somewhat like in the Index. For the HTML version, each glossary-item contains a hyperlink to an index-entry, which then has links to each occurrence. These extra index-entries do not appear in the printed version; indeed they also contain a hyperlink back to the corresponding glossary-entry.

This feature is currently available only when using the makeidx package, and needs also the html and htmllist packages. It was developed for version 96.1f by Ross Moore, incorporating an extensive revision of makeidx.perl, as well as additions to L^ATEX2HTML so that all aspects of indexing work correctly with segmented documents.

Since L^ATEX provides no guidelines for how a Glossary should be constructed, the technique used here will be explained in detail, for both the printed and HTML versions.

• Firstly the \makeglossary command, which is similar to \makeindex, must appear in the document preamble, so that L^ATEX will record uses of the \glossary{...} command within a file manual.glo.

  This command is redundant in the HTML version, so is given a trivial definition which is ignored by L^ATEX .

• Next, the words, phrases or technical terms to be included in the Glossary are marked in the main text using the \glossary command, used indirectly via other macros. For example, file-names are inserted via \fn{html.sty}, \fn{dvips}, \appl{dvips} etc. which both insert the text and create the glossary-entry; viz.

  \newcommand{\fn}[1]{\htmlref{\texttt{#1}}{GGG#1}\glossary{#1}}
  \newcommand{\appl}[1]{\htmlref{\textsl{#1}}{GGG#1}%
    \Glossary{#1}{\textsl{#1}}}
  

• The expansions of \glossary, and the slightly more general \Glossary, are different for the printed and HTML versions. For the HTML version the following definitions occur within an htmlonly environment:

  \def\glossary#1{\index{#1@\texttt{#1} \label{III#1}%
    \htmlref{(G)}{GGG#1}}}
  \def\Glossary#1#2{\index{#1@{#2} \label{III#1}\htmlref{(G)}{GGG#1}}}
  \def\makeglossary{}
  

  ...while in L^ATEX we need only:     \newcommand\Glossary[2]{\glossary{#1@#2}} .

  Notice how the feature of makeidx, allowing the printable portion to be separate from the sorting-key, is used to allow text-styles to be included within both index-entries and glossary-entries. Indeed the purpose of \Glossary is to allow deviations from a fixed style, e.g.

  \newcommand{\MF}{\htmlref{\textsl{Metafont}}{GGGmetafont}%
    \Glossary{metafont}{\textsl{Metafont}}}%
  

  Also notice that in the HTML version an index-entry is created that includes, within its printable portion, both a \label and a hyperlink. The former, having name III..., will ultimately reside on the Index page, while the latter will point to an anchor named GGG... on the Glossary page. These names must be distinct from any other names used with \labels elsewhere in the document, hence the use of prefixes III and GGG. A short string `(G)' is used for the text of the hyperlink in the Index.

• The text descriptions of the glossary-items are stored in a file called l2hfiles.dat, with one description per line. For the HTML version this file is actually read as input:\end{htmlonly}

  \section*{Glossary of variables and file-names\label{Glossary}}
  \begin{htmllist}\htmlitemmark{OrangeBall}
    \input l2hfiles.dat
  \end{htmllist}
  

  For this reason alone it is desirable to have l2hfiles.dat sorted alphabetically.

• The mechanism used for the L^ATEX version also requires the file to be sorted strictly alphabetically, according to the sort-keys associated to each glossary entry.
  (This requirement could be relaxed, but only with a loss in efficiency; see below.)

  L^ATEX constructs its Glossary by running the makeindex utility on the file manual.glo, using the following command:

  makeindex -o manual.gls -s l2hglo.ist manual.glo
  

  Its output, which includes page numbering for an index, is stored in manual.gls and subsequently read by L^ATEX using:

  \InputIfFileExists{manual.gls}{\clearpage\typeout{^^Jcreating Glossary...}}
  {\typeout{^^JNo Glossary, since  manual.gls  could not be found.^^J}}
  

  The configuration file l2hglo.ist is included along with this manual. It contains a portion that inserts tricky TEX code at the beginning of manual.gls. This code extracts from l2hfiles.dat that line corresponding to each glossary entry, then typesets it itemized within an environment called theglossary.

  \newenvironment{theglossary}{\begin{list}{}{%
    \setlength{\labelwidth}{20pt}%
    \setlength{\leftmargin}{\labelwidth}%
    \setlength\itemindent{-\labelwidth}%
    \setlength\itemsep{0pt}\setlength\parsep{0pt}%
    \rmfamily}}{\end{list}}
  

  Currently searching within l2hfiles.dat is only done sequentially, stopping at the end of the file. If an entry is not found then it is skipped and a message printed to the log; the next entry will search from the top of the file. If all entries are included and maintained in strict order, there will be no skipping and each line of l2hfiles.dat is read exactly once.

• Within l2hfiles.dat the data lines look like:

  \item[\gn{french.perl}] adds \Perl{} code to be compatible with the ...
  \item[\gn{\textsl  {ftp}}] `File Transfer Protocols', network ...
  \item[\gn{german.perl}] adds \Perl{} code to be compatible with the ...
  ...
  

  For the L^ATEX version the \item[\gn{...}] is only used for pattern-matching, to find the correct data entry. All typesetting is controlled from within manual.gls.

  However the HTML version requires the following definition:

  \newcommand{\gn}[1]{\texttt{#1}\label{GGG#1}\htmlref{\^}{III#1}}%  
  

  which establishes the hyperlink to the Index, marked by `^', and provides the \label to create the target in the Glossary for any \glossary{...} command having the corresponding argument.