###
Integrated Glossary and Index

A large number of different pieces of software are required to make LATEX2`HTML` 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 LATEX2`HTML` so that all aspects of indexing work correctly with segmented documents.

Since LATEX 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 LATEX 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 LATEX.

- 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 LATEX 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 `\label`s 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 LATEX 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.)

  LATEX 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 LATEX 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 LATEX 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.