"Fossies" - the Fresh Open Source Software Archive

Member "latex2html-2021.2/docs/features.tex" (1 Jul 2021, 85212 Bytes) of package /linux/www/latex2html-2021.2.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 \section{Special Features}
    2 \label{sec:fea}%
    3 \index{environments}\index{special features}
    4 \index{special considerations}\html{\\}\noindent
    5 This {section} describes major features available for processing
    6 documents using \latextohtml.
    7 Firstly the means whereby \latextohtml{} can be configured to produce output 
    8 for the \htmlref{different versions}{versions} of \texttt{HTML} 
    9 is discussed\latex{ in Section~\ref{versions}}.
   10 Following this is a description\latex{, in Section~\ref{internat},}
   11 of how to \htmlref{use languages}{internat} other than English. 
   12 The options available with the \htmlref{creation and reuse of images}{imgcon},
   13 are presented\latex{ in Section~\ref{imgcon}},
   14 for those situations where a textual representation is inadequate or undesirable.
   15 
   16 There are several strategies available for the \htmlref{presentation
   17 of mathematics}{maths} according to the desired version of \texttt{HTML}. 
   18 These are discussed in some detail\latex{, in Section~\ref{maths}}. 
   19 Environments such as \env{figure}, \env{table}, \env{tabular}
   20 and \env{minipage} have \htmlref{special features}{sec:figs}%
   21 \latex{ which are discussed in Section~\ref{sec:figs}}. 
   22 Other supported packages are \hyperref{listed}{listed in Table~}{}{styles}.
   23 
   24 
   25 \subsection{Variation with HTML Versions\label{versions}}%
   26 %\section{Variation with HTML Versions\label{versions}}%
   27 \index{HTML@\texttt{HTML}!an evolving standard}%
   28 \index{HTML@\texttt{HTML}!basic version, 2.0 }%
   29 \index{HTML@\texttt{HTML}!current version, 3.2 }%
   30 \index{HTML@\texttt{HTML}!future version, 4.0 }%
   31 \html{\\}\noindent
   32 The Hypertext Mark-up Language (\texttt{HTML}) is an evolving standard,
   33 with different versions supporting different features.  
   34 In order to make your documents viewable by the widest possible audience,
   35 you should use the most advanced \texttt{HTML} version with widely-accepted usage.
   36 
   37 \index{iso-latin1@ISO--Latin--1|see{\htmlref{character set}{IIIcharset}}}%
   38 \index{iso-8879@ISO--8879|see{\htmlref{character set}{IIIcharset}}}%
   39 \index{character set!ISO-8879@ISO--8879 (ISO--Latin--1)}%
   40 \index{HTML@\texttt{HTML}!interactive forms}%
   41 \index{HTML@\texttt{HTML}!image-maps}%
   42 
   43 \medskip\noindent
   44 Sometimes it is known that the audience, for which a specific document 
   45 is intended, has limited browser capabilities. 
   46 Or perhaps special extended capabilities are known to be available.
   47 The \latextohtml{} translation may be customised to suit the
   48 available functionality.
   49 
   50 \medskip\noindent
   51 Other \texttt{HTML} versions and extensions 
   52 supported by \latextohtml\ are described below.
   53 See the description of the \Cs{html\_version} command-line
   54 \hyperref[page]{option switch}{option switch, on page~}{}{cs_htmlversion}.
   55 %
   56 \begin{htmllist}\htmlitemmark{RedBall}
   57 %begin{latexonly}
   58 \addtolength{\leftskip}{15pt}
   59 %end{latexonly}
   60 \index{HTML@\texttt{HTML}!Version 2.0}%
   61 \item[Version 2.0\label{html20}]
   62 This provides only the functionality of the \texttt{HTML} 2.0 standard.
   63 There is little provision for aligning headings, paragraphs or images
   64 nor for super/sub-scripts to be generated. Images are created for tables 
   65 and other environments that use \HTMLtag{TABLE} tags with \HTMLiii;
   66 e.g. \env{eqnarray} and \env{equation} with equation numbering.
   67 
   68 \index{HTML@\texttt{HTML}!Version 2.1, now `i18n' extension}%
   69 \index{Unicode|see{\htmlref{character set}{IIIcharset}}}%
   70 \index{iso-10646@ISO--10646!Unicode}%
   71 \index{iso-10646@ISO--10646!|see{\htmlref{character set}{IIIcharset}}}%
   72 \index{iso-10646@ISO--10646!bidirectional languages}%
   73 \index{character set!ISO-10646@ISO--10646 (Unicode)}%
   74 \index{iso-8859-1@ISO--8859--1!no longer used}%
   75 \item[i18n (internationalised fonts) \strikeout{Version 2.1}]
   76 This extension (formerly known as \texttt{HTML} version 2.1)
   77 provides extensions for \htmlref{internationalisation}{internat}.
   78 Most importantly, the default character set is no longer ISO--8859--1 
   79 but {ISO--10646} (Unicode).
   80 This is a 16-bit character set and can thus display a much larger set of characters.
   81 There are also provisions for bidirectional languages 
   82 (e.g. in Arabic the text is written from right to left, 
   83 but numerals from left to right), and provisions in \texttt{HTML} 
   84 to determine the character set and the language used.
   85 
   86 Not all of the symbols are available in \TeX, \latextohtml, 
   87 or any browser yet available.  
   88 However the `\texttt{i18n}' extension to \latextohtml\ is in preparation
   89 for when such browsers do become available, and such characters
   90 will be required in Web-accessible documents. 
   91 
   92 
   93 \index{HTML@\texttt{HTML}!Version 3.0, \texttt{HTML-Math} model}%
   94 \index{HTML@\texttt{HTML}!Version 3.1, now `math' extension}%
   95 \index{Arena@\textsl{Arena}!math mark-up}\index{CERN!Arena@\textsl{Arena}}%
   96 \index{browser!Arena@\textsl{Arena}}%
   97 \item[math (\texttt{HTML3} model) \strikeout{Version 3.1}]
   98 This extension (formerly referred to as \texttt{HTML} version 3.1)
   99 adds support for the \htmladdnormallink{\texttt{HTML-Math} model}%
  100 {http://www.w3.org/MarkUp/html3/maths.html}, originally
  101 part of the proposed \texttt{HTML} 3.0 standard, see \htmlref{above}{html30}.
  102 The only available browser
  103 which can display this mark-up is \appl{Arena}.
  104 Originally developed by the \htmladdnormallink{World Wide Web Consortium}%
  105 {http://www.w3.org/Arena} as a test-bed browser,
  106 it is no longer supported by them.
  107 
  108 \index{mathematics!MathML}
  109 There has been a recent proposal for a Mathematical Markup Language
  110 (\htmladdnormallink{\texttt{MathML}}%
  111 {http://www.w3.org/pub/WWW/TR/WD-math-970515}) 
  112 from the W3C \htmladdnormallink{Math Working Group}%
  113 {http://www.w3.org/pub/WWW/Markup/Math/}. 
  114 This would suggest that the \texttt{HTML-Math} model is unlikely 
  115 ever to be adopted; better things being expected in the near future
  116 using \texttt{MathML}.
  117 
  118 See also \hyperref{another page}{Section~}{}{maths} for a discussion
  119 the the mechanisms available with \latextohtml{} for handling
  120 mathematical equations and expressions.
  121 \end{htmllist}
  122 
  123 
  124 
  125 
  126 \subsection{Internationalisation\label{internat}}%
  127 %\section{Internationalisation\label{internat}}%
  128 \index{languages}\index{extensions!languages}\html{\\}%
  129 A special variable \fn{\$LANGUAGE\_TITLES} 
  130 in the initialisation or configuration files determines the language 
  131 in which some section titles will appear. For example setting it to 
  132 \begin{quote}
  133 \begin{verbatim}
  134 $LANGUAGE_TITLES = 'french';
  135 \end{verbatim}
  136 \end{quote}
  137 will cause \latextohtml{} to produce ``Table des mati{\`e}res'' instead of
  138 ``Table of Contents''.
  139 Furthermore, the value of the \Lc{today} command is presented in a format
  140 customary in that language.
  141 
  142 \index{languages!french}\index{languages!english}\index{languages!german}%
  143 \index{languages!spanish}\index{languages!finnsh}%\index{languages!slovene}%
  144 \html{\\}%
  145 Languages currently supported are 
  146 \env{finnish}, \env{french}, \env{english}, \env{german}
  147  and \env{spanish}.
  148 It is trivial to add support for another language by creating a file
  149 in the \fn{styles/} subdirectory, 
  150 or by adding to the file \fn{latex2html.config}.
  151 As a guide, here is the entry for French titles:
  152 %begin{latexonly}
  153 \begin{small}
  154 %end{latexonly}
  155 \begin{verbatim}
  156 sub french_titles {
  157     $toc_title = "Table des mati\\`eres";
  158     $lof_title = "Liste des figures";
  159     $lot_title = "Liste des tableaux";
  160     $idx_title = "Index";
  161     $ref_title = "R\\'ef\\'erences";
  162     $bib_title = "R\\'ef\\'erences";
  163     $abs_title = "R\\'esum\\'e";
  164     $app_title = "Annexe";
  165     $pre_title = "Pr\\'eface";
  166     $fig_name = "Figure";
  167     $tab_name = "Tableau";
  168     $part_name = "Partie";
  169     $prf_name = "Preuve";
  170     $child_name = "Sous-sections";
  171     $info_title = "\\`Apropos de ce document...";
  172     @Month = ('', 'janvier', "f\\'evrier", 'mars', 'avril', 'mai',
  173               'juin', 'juillet', "ao\\^ut", 'septembre', 'octobre',
  174               'novembre', "d\\'ecembre");
  175     $GENERIC_WORDS = "a|au|aux|mais|ou|et|donc|or|ni|car|l|la|le|les"
  176         . "|c|ce|ces|un|une|d|de|du|des";
  177 }
  178 \end{verbatim}
  179 %begin{latexonly}
  180 \end{small}
  181 %end{latexonly}
  182 Notice how the backslash needs to be doubled, when a macro is needed
  183 (for accented characters, say).
  184 Also, the \texttt{\$GENERIC\_WORDS} are a list of short words to be excluded
  185 when filenames are specially requested to be created from section-headings.
  186 In order to provide full support for another language you may also
  187 replace the navigation buttons which come with \latextohtml{} 
  188 (by default in English) with your own. 
  189 As long as the new buttons have the same file-names as the old ones, 
  190 there should not be a problem.
  191 
  192 
  193 \subsubsection{Alternate Character Encodings\label{fontEncodings}}%
  194 %
  195 \index{extension!options}%
  196 \html{\\}%
  197 By default, \latextohtml\ assumes that input files are
  198 Unicode encoded with UTF8, and produces Unicode UTF8 output.
  199 
  200 \latextohtml\ can handle input files in other encodings,
  201 indicated by including the \texttt{inputenc}
  202 package in the source:
  203 %
  204 %begin{latexonly}
  205 \begin{small}
  206 %end{latexonly}
  207 \begin{verbatim}
  208  \usepackage[latin5]{inputenc}
  209 \end{verbatim}
  210 %begin{latexonly}
  211 \end{small}
  212 %end{latexonly}
  213 In this case, \latextohtml\ will produce output in the
  214 same encoding, and will indicate the encoding in the HTML
  215 headers.
  216 The input encodings that are recognised are listed in 
  217 \hyperref{the following table}{Table~}{}{tab_encodings}.
  218 
  219 \begin{table}
  220 \begin{center}
  221 \begin{tabular}{|>{\ttfamily}lcl|}%\hline
  222 \multicolumn{1}{c}{\textbf{extension}}
  223 &\multicolumn{1}{c}{\textbf{notes}}
  224 &\multicolumn{1}{c}{\textbf{encoding}}\\\hline
  225 unicode & (default)& ISO--10646 (Unicode)\\
  226 latin1 &  & ISO--8859--1 (ISO-Latin-1) \\
  227 latin2 &  & ISO--8859--2 (ISO-Latin-2) \\
  228 latin3 &  & ISO--8859--3 (ISO-Latin-3) \\
  229 latin4 &  & ISO--8859--4 (ISO-Latin-4) \\
  230 latin5 &  & ISO--8859--9 (ISO-Latin-5) \\
  231 latin6 &  & ISO--8859--10 (ISO-Latin-6)\\
  232 koi8-r &  & RFC 1489 (Russian) \\\hline
  233 \end{tabular}
  234 \caption{Supported Font-encodings\label{tab_encodings}}
  235 \end{center}
  236 \end{table}
  237 
  238 
  239 \subsubsection{Multi-lingual documents, using Images\label{multilang}}%
  240 %
  241 Some multi-lingual documents can be constructed, when all the languages
  242 can be presented using characters from a single font-encoding,
  243 as discussed in the \hyperref{previous section}{Section~}{}{fontEncodings}.
  244 
  245 Another way to present multiple languages within a Web document is to
  246 create images of individual letters, words, sentences, paragraphs
  247 or even larger portions of text, which cannot be displayed within
  248 the chosen font-encoding.
  249 This is a technique that is used with \IndicHTML, for presenting
  250 traditional Indic language scripts within Web pages.
  251 For these the \LaTeX\ source that is to be presented as an image
  252 needs special treatment using a ``pre-processor''. 
  253 For the special styles defined in \IndicHTML, running the preprocessor
  254 is fully automated, so that it becomes just another step 
  255 within the entire image-generation process.
  256 
  257 \medskip
  258 
  259 The technique of using images, can be used with \emph{any} font 
  260 whose glyphs can be typeset using \TeX{} or \LaTeX. 
  261 Using \TeX's \Lcs{font} command, a macro is defined to declare
  262 the special font required; 
  263 e.g. for Cyrillic characters, using the Univ. of Washington font:
  264 %begin{latexonly}
  265 \begin{small}
  266 %end{latexonly}
  267 \begin{verbatim}
  268  \font\wncyr = wncyr10
  269 \end{verbatim}
  270 %begin{latexonly}
  271 \end{small}
  272 %end{latexonly}
  273 
  274 \noindent
  275 Now use this font switch immediately surrounded by braces:
  276 %begin{latexonly}
  277 \begin{small}
  278 %end{latexonly}
  279 \begin{verbatim}
  280  published by {\wncyr Rus\-ski\char26\ \char23zyk}.
  281 \end{verbatim}
  282 %begin{latexonly}
  283 \end{small}
  284 %end{latexonly}
  285 to get:
  286 \begin{center}
  287  published by {\wncyr Rus\-ski\char26\ \char23zyk}.
  288 \end{center}
  289 
  290 
  291 \subsection{Mathematics\label{maths}}
  292 %\section{Mathematics\label{maths}}
  293 %
  294 There are various different ways in which \latextohtml{} can handle
  295 mathematical expressions and formulas:
  296 \begin{itemize}
  297 \item
  298 give a textual representation (``simple'' math);
  299 \item
  300 make an image of the complete formula or expression;
  301 \item
  302 combination of textual representation and images of
  303 sub-expressions;
  304 \item
  305 \texttt{SGML}-like representation built using abstract ``entities'';\\
  306 e.g. for the \texttt{HTML-Math} model, or for \texttt{MathML}.
  307 %
  308 \end{itemize}
  309 Which is the most appropriate normally depends on the context,
  310 or importance of the mathematics within the entire document.
  311 What \latextohtml{} will produce depends upon
  312 \begin{enumerate}
  313 \item 
  314 the version of \texttt{HTML} requested;
  315 \item
  316 whether or not the special `\texttt{math}' \htmlref{extension}{} has been loaded;
  317 \item
  318 whether the \Cs{no\_math} \htmlref{command-line option}{nomath}
  319 has been specified, or (equivalently) the \fn{\$NO\_SIMPLE\_MATH} 
  320 \htmlref{variable}{nomath} has been set in an initialisation file.
  321 \end{enumerate}
  322 %
  323 The strategies used to translate math expressions are summarised
  324 in \hyperref{the table below}{Table~}{}{mathconv3} for \texttt{HTML} 3.0+
  325 and \hyperref{the subsequent table}{Table~}{}{mathconv2} for \texttt{HTML} 2.0.
  326 
  327 \begin{table}[ht]
  328 \begin{center}
  329 \begin{tabular}{|c|c|p{6cm}|}
  330 \hline
  331 \textbf{`math'} & \textbf{switch} &\textbf{\hfill strategy adopted\hfill~}\\ \hline
  332  not loaded & \Cs{math} & textual representation where possible,\newline
  333   else image of whole expressions\\ \hline
  334  not loaded & --- & always generates an image of the whole\newline
  335  expression/environment\\ \hline
  336  loaded & --- &
  337 uses entities and \HTMLtag{MATH} tags; e.g. for \texttt{HTML-Math}
  338  (or \texttt{MathML} in future)\\ \hline
  339  loaded & \Cs{no\_math} & textual representation where possible,
  340  with~images~of sub-expressions \\ \hline
  341 \end{tabular}
  342 \caption{Mathematics translation strategies, 
  343  for \texttt{HTML} versions 3.0 and 3.2,\protect\newline
  344  using \protect\HTMLtag{SUP} and \protect\HTMLtag{SUB} tags
  345  and \protect\HTMLtag{TABLE}s}
  346 \label{mathconv3}
  347 \end{center}
  348 \end{table}
  349 
  350 The default behavior, with no command line options,
  351 is to generate images for all math expressions, which makes
  352 the appearance of all mathematical expressions consistent.
  353 This is what was used when creating\latex{ the \texttt{HTML} version of} 
  354 this manual. 
  355  
  356 \bigskip
  357 \noindent
  358 Since the \texttt{HTML} 2.0 standard does not include
  359 superscripts and subscripts, via the \HTMLtag{SUP} and \HTMLtag{SUB} tags,
  360 the options are more limited. In this case creating images of sub-expressions
  361 is not so attractive, since virtually the whole expression would
  362 consist of images in all but the simplest of cases.
  363 
  364 \begin{table}[hbt]
  365 \begin{center}
  366 \begin{tabular}{|c|c|p{6cm}|}\hline
  367 \textbf{`math'} & \textbf{switch} &\textbf{\hfill strategy adopted\hfill~}\\ \hline
  368  not loaded & --- & textual representation where possible,\newline
  369  else image of whole expressions\\ \hline
  370  not loaded & \Cs{no\_math} & always generates an image of\newline
  371 the whole expression or environment\\ \hline
  372  loaded & --- &
  373 entities and \HTMLtag{MATH} tags for~\texttt{HTML-Math}\\ \hline
  374  loaded & \Cs{no\_math} & always generates an image of the whole\newline
  375  expression or environment \\ \hline
  376 \end{tabular}
  377 \caption{Mathematics translation strategies,
  378 for \texttt{HTML} version 2.0\label{mathconv2}}
  379 \end{center}
  380 \end{table}
  381 \medskip \htmlrule
  382 \index{numbered equations}\index{equations!numbered}%
  383 \index{equations!right-justified}\html{\\}%
  384 
  385 \noindent
  386 Here are some examples of mathematical expressions and environments 
  387 processed by \latextohtml{} using different strategies. 
  388 They are automatically numbered \dots 
  389 \begin{equation}\label{eq:demo} 
  390  \Phi_{l+1,m,n} = \Bigl(\Phi+h\frac{\partial\Phi}{\partial x} +
  391  \frac{1}{2}h^2\frac{\partial^2\Phi}{\partial x^2} +
  392  \frac{1}{6}h^3\frac{\partial^3\Phi}{\partial x^3} + \,\ldots\,\Bigr)_{l,m,n}
  393 \end{equation}
  394 \dots\ with some gratuitously {\'a}c{\c c}{\"e}nted text in-between \dots
  395 %
  396 \index{equations!array}%
  397 \index{eqnarray@\env{eqnarray} environment!example}%
  398 %
  399 \begin{eqnarray}
  400 \frac{\Phi_{l+1,m,n}-2\Phi_{l,m,n}+\Phi_{l-1,m,n}}{h^{2}} +
  401 \frac{\Phi_{l,m+1,n}-2\Phi_{l,m,n}+\Phi_{l,m-1,n}}{h^{2}} \nonumber \\
  402 + \frac{\Phi_{l,m,n+1}-2\Phi_{l,m,n}+\Phi_{l,m,n-1}}{h^{2}} = -I_{l,m,n}(v)\;.
  403 \end{eqnarray}
  404 The latter example uses an \env{eqnarray} environment
  405 and the \Lc{nonumber} command to suppress
  406 the equation number on the upper line.
  407 
  408 The default image format is Scalable Vector Graphics (SVG),
  409 which looks crisp at all resolutions.  If bitmap image
  410 formats are used (PNG or GIF), various options are
  411 available to control antialiasing and the resolution
  412 of the images.  These options are discussed in the
  413 following sections.
  414 
  415 \index{image generation!using htmlimage@using \Lc{htmlimage}}
  416 
  417 For combinations of options that do not generate images for all
  418 math expressions, it is possible to control image generation
  419 at the level of individual expression.
  420 By inserting an \verb|\htmlimage{}| command into a \env{math},
  421 \env{equation} or \env{displaymath} environment, a single image
  422 will be created for the whole environment. For an \env{eqnarray}
  423 environment, this will lead to having a single separate image 
  424 for each of the aligned portions. 
  425 The argument to \Lc{htmlimage} need not be empty, but may contain
  426 information which is used to affect characteristics of the resulting
  427 image. An example of how this is used is given \htmlref{below}{ex:aalias},
  428 and a fuller discussion of the allowable options is given in
  429 \hyperref{the next section}{Section~}{}{imgcon}.
  430 
  431 
  432 \index{scale-factors!for math images}%
  433 \paragraph*{Scale-factors for Mathematics.\label{mathscales}}
  434 %
  435 For bitmap image formats (PNG or GIF, as opposed to SVG),
  436 the scale factor controls the image resolution.
  437 When a bitmap image 
  438 is made of a mathematical formula or expression,
  439 it is generally made at a larger size 
  440 than is normally required on a printed page.
  441 This is to compensate for the reduced resolution of a computer screen
  442 compared with laser-print.  
  443 The amount of this scaling is given by the
  444 value of a configuration variable \fn{\$MATH\_SCALE\_FACTOR},
  445 by default set to 1 in \fn{latex2html.config}. 
  446 A further variable \fn{\$DISP\_SCALE\_FACTOR} is used with
  447 `displayed math' equations and formulas.
  448 This value multiplies the \fn{\$MATH\_SCALE\_FACTOR} 
  449 to give the actual scaling to be used.
  450 The main purpose of this extra scaling is to allow some clarity in
  451 super/subscripts etc.
  452 
  453 
  454 \index{anti-aliasing!comparison}%
  455 \paragraph*{Anti-aliased Images.\label{ex:aalias}}
  456 \hyperref{Here are}{Figure~}{ shows}{eq:pics} the same equations
  457 as \htmlref{previously}{eq:demo}, this time as images of the 
  458 complete contents of the \env{equation} environment, 
  459 and complete aligned parts of rows in an \env{eqnarray}.
  460 \begin{latexonly}
  461 These are images, as they would appear if the \texttt{HTML} page
  462 were to be printed from the browser. A scaling of 60\% has been
  463 applied to counteract the combined effects of the \fn{\$MATH\_SCALE\_FACTOR} 
  464 of 1.4 and \fn{\$DISP\_SCALE\_FACTOR} of 1.2, 
  465 used for the \texttt{HTML} version of this manual. 
  466 \end{latexonly}
  467 For a comparison, the second group of images use anti-aliasing effects, 
  468 whereas the first image does not; a 600\,dpi printing is probably necessary
  469 to appreciate the difference in quality. Compare these images with those in
  470 \hyperref{a later section}{Section~}{}{printqual}.
  471 
  472 \begin{figure}[hb]
  473 \begin{makeimage}
  474 \end{makeimage}
  475 \begin{htmlonly}
  476 \begin{equation}
  477 \htmlimage{no_antialias}
  478 \Phi_{l+1,m,n} = \Bigl(\Phi+h\frac{\partial\Phi}{\partial x} +
  479 \frac{1}{2}h^2\frac{\partial^2\Phi}{\partial x^2} +
  480 \frac{1}{6}h^3\frac{\partial^3\Phi}{\partial x^3} + \,\ldots\,\Bigr)_{l,m,n}
  481 \end{equation}
  482 \begin{eqnarray}
  483 \htmlimage{}
  484 \frac{\Phi_{l+1,m,n}-2\Phi_{l,m,n}+\Phi_{l-1,m,n}}{h^{2}} +
  485 \frac{\Phi_{l,m+1,n}-2\Phi_{l,m,n}+\Phi_{l,m-1,n}}{h^{2}} \nonumber \\
  486 + \frac{\Phi_{l,m,n+1}-2\Phi_{l,m,n}+\Phi_{l,m,n-1}}{h^{2}} = -I_{l,m,n}(v)\;.
  487 \end{eqnarray}
  488 \end{htmlonly}
  489 %
  490 \begin{latexonly}
  491 \begin{equation}
  492  \setbox1=\hbox{\scalebox{.6}{\includegraphics{psfiles/eqn1}}}
  493  \lower.5\ht 1\box1
  494 \end{equation}
  495 \begin{eqnarray}
  496  \nonumber
  497  \setbox1=\hbox{\scalebox{.6}{\includegraphics{psfiles/eqarrA1}}}
  498  \lower.5\ht1 \box1&&\\
  499  \setbox1=\hbox{\scalebox{.6}{\includegraphics{psfiles/eqarrB1}}}
  500  \lower.5\ht1 \box1&&
  501 \end{eqnarray}
  502 \end{latexonly}
  503 \caption{Images of equation displays, at normal screen resolution}\label{eq:pics}
  504 \end{figure}
  505 
  506 \noindent
  507 These images of the whole environment were created 
  508 using the \Lc{htmlimage} command, to suppress the extended parsing 
  509 that usually occurs when the `\texttt{math}' extension is loaded; viz.
  510 %
  511 %begin{latexonly}
  512 \begin{small}
  513 %end{latexonly}
  514 \begin{verbatim}
  515 \begin{equation}
  516 \htmlimage{no_antialias}
  517 \Phi_{l+1,m,n} = \Bigl(\Phi+h\frac{\partial\Phi}{\partial x} +
  518 ...
  519 \end{equation}
  520 %
  521 \begin{eqnarray}
  522 \htmlimage{}
  523 \frac{\Phi_{l+1,m,n}-2\Phi_{l,m,n}+\Phi_{l-1,m,n}}{h^{2}} +
  524 ...
  525 \end{eqnarray}
  526 \end{verbatim}
  527 %begin{latexonly}
  528 \end{small}
  529 %end{latexonly}
  530 Further aspects of the options available when generating images 
  531 are discussed in \htmlref{the next section}{imgcon}, in particular 
  532 with regard to the quality of \htmlref{printed images}{printqual}.
  533 
  534 
  535 
  536 \index{mbox@\Lc{mbox} command with math!generates an image}%
  537 \paragraph*{The \Lc{mbox} command.}
  538 Another way to force an image to be created of a mathematical expression,
  539 when global settings are not such as to do this anyway, 
  540 is via the \Lc{mbox} command having math delimiters within its argument.
  541 
  542 Normally \Lc{mbox} is used to set a piece of ordinary text within a 
  543 mathematics environment. It is not usual to have math delimiters 
  544 \texttt{\$...\$} or \Lc{(}...\Lc{)} within the argument of an \Lc{mbox}. 
  545 Whereas earlier versions of \latextohtml{} simply ignored the \Lc{mbox} 
  546 command (treating its argument as normal text), 
  547 the presence of such delimiters now results in an image being
  548 generated of the \emph{entire contents} of the \Lc{mbox}.
  549 It is not necessary for there to be any actual mathematics inside
  550 the \Lc{mbox}'s contents;\html{\\}
  551 e.g. \verb|\mbox{...some text...${}$}|
  552 will cause an image to be created of the given text.
  553 
  554 
  555 \index{parbox@\Lc{parbox} command!generates an image}%
  556 \paragraph*{The \Lc{parbox} command.}
  557 The \Lc{parbox[}\Meta{align}\verb|]{|\Meta{width}\verb|}{|\Meta{text}\verb|}| 
  558 command also generates an image of its contents,
  559 except when used within a \env{tabular} environment, or other
  560 similar table-making environment.
  561 Here the important aspect is the width specified for the given
  562 piece of text, and any special line-breaks or alignments that
  563 this may imply. Hence to get the best effect, \LaTeX{} is used
  564 to typeset the complete \Lc{parbox}, with its specified width,
  565 alignment and contents, resulting in an image.
  566 
  567 
  568 \index{heqn.sty@\texttt{heqn.sty} style-file}%
  569 \index{package!heqn@\env{heqn}}\index{heqn@\env{heqn} package}%
  570 \index{eqnarray@\env{eqnarray} environment}%
  571 \index{equation@\env{equation} environment}\html{\\}%
  572 \paragraph*{The \env{heqn} package.}
  573 %
  574 If you need \texttt{HTML} 2.0 compatible Web pages,
  575 and have a document with a great many displayed equations, 
  576 then you might try using the \env{heqn} package.  
  577 Inclusion of the \fn{heqn.sty} file has absolutely
  578 no effect on the printed version of the article, 
  579 but it does change the way in which \latextohtml{} translates
  580 displayed equations and equation arrays.  
  581 It causes the equation numbers of the \env{equation}
  582 environment to be moved outside of the images themselves, 
  583 so that they become order-independent and hence recyclable.  
  584 Images that result from the \env{eqnarray} environment are also recyclable,
  585 so long as their equation numbers remain unchanged from the previous run.  
  586 
  587 \index{nonumber@\Lc{nonumber}}%
  588 \index{package!html@\env{html}}%
  589 \index{html@\env{html} package}\html{\\}%
  590 The \Lc{nonumber} command is recognised 
  591 in each line of the equation array, to suppress the equation number.
  592 A side-effect of this approach is that equation numbers will
  593 appear on the left side of the page.
  594 The \env{heqn} package requires the \env{html} package.%
  595 
  596 \smallskip\noindent
  597 Using \texttt{HTML} Version 3.2 the \env{heqn} package is quite redundant,
  598 since equation numbers are placed in a separate \HTMLtag{TABLE} cell
  599 to the mathematical expressions themselves.
  600 It is \emph{not} required and should \emph{not} be requested, since this will
  601 override some of the improved functionality already available.
  602 
  603 
  604 
  605 
  606 \subsection{Figures and Image Conversion\label{imgcon}%
  607 %\section{Figures and Image Conversion\label{imgcon}%
  608 \index{images@images\protect\label{IIIimages}}}%
  609 \tableofchildlinks*\htmlrule
  610 %
  611 \noindent
  612 \latextohtml{} converts equations, special accents, external \PS\ 
  613 files, and \LaTeX{}  environments it cannot directly translate into 
  614 inlined images. This section describes how it is possible to control
  615 the final appearance of such images. For purposes of discussion \dots
  616 \begin{itemize}
  617 \item
  618 ``small images'' \index{images!small images}\html{\\}%
  619 refers to inline math expressions, special accents and
  620 any other \LaTeX{} command which causes an image to be generated; while \dots 
  621 \item
  622 ``figures'' \index{images!figures}\html{\\}%
  623 applies to image-generating \LaTeX{} environments 
  624 (e.g. \env{makeimage}, \env{figure}, \env{table} (with \texttt{HTML} 2.0), 
  625  and displayed math environments when required to generate images, etc.).
  626 \end{itemize}
  627 
  628 \index{images!math scale-factor}%
  629 \index{images!display scale-factor}%
  630 \index{images!figure scale-factor}%
  631 \index{images!scale-factor, default 1}\html{\\}%
  632 \noindent
  633 These parameters apply only to bitmapped image types,
  634 and have no effect with the default SVG image type.
  635 The size of all ``small images'' depends on a configuration variable
  636 \fn{\$MATH\_SCALE\_FACTOR} which specifies how much to enlarge or 
  637 reduce them in relation to their original size in the \PS\  
  638 version of the document. 
  639 For example a scale-factor of 0.5 will make all images half as big, 
  640 while a scale-factor of 2 will make them twice as big.
  641 Larger scale-factors result in longer processing times and larger 
  642 intermediate image files. A scale-factor will only be effective 
  643 if it is greater than 0. 
  644 The configuration variable \fn{\$FIGURE\_SCALE\_FACTOR} performs
  645 a similar function for ``figures''. 
  646 Both of these variables are initially set to have value 1.
  647 
  648 A further variable \fn{\$DISP\_SCALE\_FACTOR} is used with
  649 `displayed math' equations and formulas;
  650 this value multiplies the \fn{\$MATH\_SCALE\_FACTOR} 
  651 to give the actual scaling used.
  652 Values greater than 1 can be used to counteract readability problems
  653 with bitmapped images.
  654 Accordingly this manual actually uses values of 1.4 and 1.2 respectively,
  655 for \fn{\$MATH\_SCALE\_FACTOR} and \fn{\$DISP\_SCALE\_FACTOR}.
  656 These go well with the browser's text-font set at 14\,pt. 
  657 The next larger size of 17\,pt is then used for the \HTMLtag{LARGE} tags
  658 in displayed equations.
  659 
  660 \index{images!extra scaling}%
  661 \index{images!improved print quality}%
  662 \index{extra scaling of images}\html{\\}%
  663 
  664 A further variable \fn{\$EXTRA\_IMAGE\_SCALE} allows images to be created
  665 at a larger size than intended for display. 
  666 The browser itself scales them down to the intended size, 
  667 but has the extra information available for a better quality print. 
  668 This feature is also available with single images. It is discussed, 
  669 with examples, \hyperref{on the next page}{in Section~}{}{printqual}.
  670 
  671 
  672 \index{htmlimage@\Lc{htmlimage}}%
  673 \index{html.sty@\texttt{html.sty} style-file}%
  674 \index{figures!fine control}%
  675 \paragraph*{\Lc{htmlimage\char123}\Meta{options}\texttt{\char125}\label{htmlimage}}
  676 %
  677 For finer control, several parameters affecting the conversion 
  678 of a single image can be controlled
  679 with the command \Lc{htmlimage}, which is defined in \fn{html.sty}.
  680 With version \textsc{v97.1} use of this command has been extended to allow
  681 it to control whether an image is generated or not
  682 for some environments,
  683 as well as specifying effects to be used when creating this image.
  684 
  685 If an \Lc{htmlimage} command appears within any environment
  686 for which creating an image is a possible strategy (though not usual,
  687 due to loading of extensions, say), then an image will indeed be
  688 created. Any effects requested in the \Meta{options} argument will be used.
  689 Having empty \Meta{options} still causes the image to be generated.
  690 
  691 This ability has been used within this manual, for example with the
  692 mathematics images in \hyperref{the previous section}{Figure~}{}{eq:pics}.
  693 
  694 \medskip\noindent
  695 The \Meta{options} argument is a string separated by commas.
  696 \index{images!options}\html{\\}% 
  697 Allowable options are:
  698 %
  699 \index{images!scale}%
  700 \index{figures!arbitrarily scaled}%
  701 \begin{itemize}
  702 \item \texttt{scale=}\Meta{scale-factor}\\
  703 allows control over the size of the final image.
  704 
  705 \index{images!external}\label{external}%
  706 \index{images!inlined by default}%
  707 \index{images!hypertext link}%
  708 \item \texttt{external}\\
  709 will cause the image not to be inlined; 
  710 instead it will be accessible via a hyperlink. 
  711 
  712 \index{thumbnail}\index{images!thumbnail}%
  713 \index{thumbnail!implies external}%
  714 \index{thumbnail!ignores scale-factors}%
  715 \label{thumbnail}%
  716 \item \texttt{thumbnail=}\Meta{scale-factor}\\
  717 will cause a small inlined image to be placed in the caption. 
  718 The size of the thumbnail depends on the \Meta{scale-factor},
  719 as a factor of the `natural size' of the image, ignoring
  720 any \fn{\$FIGURE\_SCALE\_FACTOR} or \fn{\$MATH\_SCALE\_FACTOR}, etc.
  721 which may be applicable to the full-sized version of the image. 
  722 Use of the `\texttt{thumbnail=}' option implies 
  723 the `\texttt{external}' option. 
  724 
  725 \index{images!image-map}%
  726 \index{images!server-side image-map}%
  727 %
  728 \item \texttt{map=}\Meta{server-side image-map URL}\\
  729 specifies that the image is to be made into an 
  730 active image-map.
  731 (See \hyperref{another section}{Section~}{}{ImageMaps} for more information.)
  732 
  733 \index{images!client-side image-map}\html{\\}%
  734 
  735 \item \texttt{usemap=}\Meta{client-side image-map URL}
  736 same as previous item, but with the image-map processed by the client.
  737 (See \hyperref{another section}{Section~}{}{ImageMaps} for more information.)
  738 
  739 \index{images!flip option}
  740 \index{figures!oriented}\index{tables!oriented}\html{\\}%
  741 
  742 \item \texttt{flip=}\Meta{flip\_option}\\
  743 specifies a change of orientation of the
  744 electronic image relative to the printed version.
  745 The \Meta{flip\_option} is any single command recognised by
  746 the \fn{pnmflip} graphics utility.
  747 The most useful of these include:
  748 \begin{itemize}
  749 %
  750 \item `\texttt{rotate90}' or `\texttt{r90}'~
  751 This will rotate the image clockwise by $90^\circ$.
  752 %
  753 \item `\texttt{rotate270}' or `\texttt{r270}'~
  754 This will rotate the image counterclockwise by $90^\circ$.
  755 %
  756 \item `\texttt{leftright}'~ 
  757 This will flip the image around a vertical axis of rotation.
  758 %
  759 \item `\texttt{topbottom}'~
  760 This will flip the image around a horizontal axis of rotation.
  761 \end{itemize}
  762 %
  763 \index{images!alignment}\index{equations!alignment}%
  764 \index{HTML@\texttt{HTML}!Version 3.0}%
  765 \item \texttt{align=}\Meta{alignment}\\
  766 specifies how the \env{figure} will be aligned.  
  767 The choices are:  
  768 `\texttt{top}', `\texttt{bottom}', `\texttt{middle}', `\texttt{left}', 
  769 `\texttt{right}' and `\texttt{center}'.
  770 
  771 The `\texttt{middle}' option specifies that the image is to be
  772 left-justified in the line, but centered vertically.  
  773 The `\texttt{center}' option specifies that it should also 
  774 be centered horizontally. 
  775 This option is valid only if the \texttt{HTML} version 
  776 is \texttt{3.0} or higher.
  777 The default alignment is `\texttt{bottom}'.%
  778 
  779 \index{images!transparent}%
  780 \index{transparent images!override defaults}%
  781 %
  782 \item \texttt{transparent}, \texttt{no\_transparent}
  783  or \texttt{notransparent}\\
  784 specify that a transparent background should (not) be used with this image,
  785 regardless of the normal behaviour for similar images.
  786 
  787 \index{images!anti-alias}%
  788 \index{anti-aliasing!override defaults}%
  789 \item \texttt{antialias}, \texttt{no\_antialias}
  790  or \texttt{noantialias}\\
  791 specify that anti-aliasing should (not) be used with this image,
  792 regardless of the normal behaviour for similar images.
  793 
  794 \index{images!extra scaling}%
  795 \item \texttt{extrascale=}\Meta{scale-factor}\\
  796 is used mainly used with a \Meta{scale-factor} of 1.5 or 2, when it is 
  797 important to get printed versions of the completed \texttt{HTML} pages. 
  798 The image is created scaled by the amount specified, but it is embedded 
  799 in the \texttt{HTML} page with attributes to the \HTMLtag{IMG} of
  800 \texttt{HEIGHT=...} and \texttt{WIDTH=...}, 
  801 indicating the \emph{unscaled} size. 
  802 A browser is supposed to display the image at the requested size
  803 by scaling the actual image to fit, 
  804 effectively imposing its own anti-aliasing.
  805 Some examples of this effect are show 
  806 \hyperref{here}{later, in Section~}{}{printqual}.
  807 This effect can be applied to all images in a document by setting
  808 the \fn{\$EXTRA\_IMAGE\_SCALE} \htmlref{variable}{ximagescale}.
  809 However it may be desirable to also turn off ``anti-aliasing''\index{anti-aliasing}, 
  810 as these effects serve similar purposes but need not work well together. 
  811 Furthermore different browsers may give results of different quality.
  812 It may be necessary to experiment a little,
  813 in order to find the combination that works best at your site.
  814 
  815 \index{images!specified width or height}%
  816 \item \texttt{height=}\Meta{dimen}\quad
  817  and\quad\texttt{width=}\Meta{dimen}\\
  818 are used to specify exactly the size to be occupied by the image
  819 on the \texttt{HTML} page. The value(s) given this way overrides
  820 the natural size of the image and forces the browser to shrink or
  821 stretch the image to fit the specified size.
  822 The \Meta{dimen} can be given as either (i) a number (of points);
  823 or (ii) with any of the units of $\mathrm{cm, mm, in, pt}$;
  824 or (iii) fraction of \Lc{hsize} or \Lc{textwidth},
  825 to become a percentage of the browser window's width,
  826 or of \Lc{vsize} or \Lc{textheight} for a percentage height.
  827 
  828 \noindent
  829 \textbf{Note:} images whose sizes are modified in this way may not 
  830 be acceptable for 
  831 \hyperref{image-recycling}{image-recycling, (see page~}{)}{recycling}. 
  832 Instead they may need to be generated afresh on each run of \latextohtml{} 
  833 through the same source document.
  834 %
  835 \end{itemize}
  836 
  837 \medskip\noindent
  838 In order to be effective the \Lc{htmlimage} command 
  839 and its options must be placed \emph{inside the environment} 
  840 on which it will operate.
  841 Environments for alignment and changing the font size do not
  842 generate images of their contents. Any \Lc{htmlimage}
  843 command may affect the surrounding environment instead;
  844 e.g. within a \env{table} or \env{figure} environment,
  845 but does not apply to a \env{minipage}.
  846 
  847 When the \Lc{htmlimage} command occurs in an inappropriate
  848 place, the following message is printed among the warnings
  849 at the end of processing. 
  850 The actual command is shown, with its argument; 
  851 also the environment name and identifying number, if there is one.
  852 %
  853 \begin{quote}
  854 \begin{small}
  855 \begin{verbatim}
  856 The command "\htmlimage" is only effective inside an environment 
  857 which may generate an image (e.g. "{figure}", "{equation}")
  858  center92: \htmlimage{ ... }
  859 \end{verbatim}
  860 \end{small}
  861 \end{quote}
  862 
  863 
  864 \subsubsection{An Embedded Image Example\index{images!embedded image}}%
  865 %\subsection{An Embedded Image Example\index{images!embedded image}}%
  866 %
  867 \index{thumbnail}\html{\\}%
  868 The effect of the \LaTeX{}  commands below can be seen in the
  869 \htmlref{thumbnail sketch of Figure}{fig:example} \ref{fig:example}.
  870 A~5\,pt border has also been added around the thumbnail, 
  871 using \Lc{htmlborder} \htmlref{command}{htmlborder}; 
  872 this gives a pseudo-3D effect in some browsers.
  873 %begin{latexonly}
  874 \begin{small}
  875 %end{latexonly}
  876 \begin{verbatim}
  877 \begin{figure}
  878     \htmlimage{thumbnail=0.5}
  879     \htmlborder{5}
  880     \centering \includegraphics[width=5in]{psfiles/figure}
  881     \latex{\addtocounter{footnote}{-1}}
  882     \caption{A sample figure showing part of a page generated by
  883        \latextohtml{} containing a customised navigation panel 
  884        (from the 
  885         CSEP project).}\label{fig:example}
  886 \end{figure}
  887 \end{verbatim}
  888 %begin{latexonly}
  889 \end{small}
  890 %end{latexonly}
  891 
  892 \index{figures}%
  893 \index{figure@\env{figure} environment}%
  894 \index{environment!figure@\env{figure}}%
  895 \index{Computer~Science~Education~Project!CSEP}% 
  896 \begin{figure}[hbt]
  897     \htmlimage{thumbnail=0.5}
  898     \htmlborder{5}
  899     \centering \includegraphics[width=5in]{psfiles/figure}
  900     \latex{\addtocounter{footnote}{-1}}%
  901     \caption{A sample figure showing part of a page generated by
  902        \protect\latextohtml{} containing a customised navigation panel 
  903        (from the 
  904         CSEP project).}\label{fig:example}
  905 \end{figure}
  906 
  907 
  908 \index{htmlimage@\Lc{htmlimage}!overrides configuration}%
  909 
  910 \noindent
  911 The \Lc{htmlimage} command is also often useful to cancel-out the
  912 effect of the configuration variable \fn{\$FIGURE\_SCALE\_FACTOR}.
  913 For example to avoid resizing a color screen snap despite 
  914 the value of \fn{\$FIGURE\_SCALE\_FACTOR} it is possible to 
  915 use \verb|\htmlimage{scale=0}|\,.
  916 
  917 
  918 \subsubsection{Image Sharing and Recycling\label{recycling}}%
  919 %\subsection{Image Sharing and Recycling\label{recycling}}%
  920 \index{images!recycling}\index{images!sharing}%
  921 It is not hard too see how reasonably sized papers,
  922 especially scientific articles, can require
  923 the use of many hundreds of external images.  For this reason,
  924 image sharing and recycling is of critical importance.
  925 In this context, ``sharing'' refers to the use of one
  926 image in more than one place in an article.  ``Recycling''
  927 refers to the use of an image left over from a previous
  928 run of \latextohtml.  Without this ability, every instance of an
  929 image would have to be regenerated each time even the
  930 slightest change were made to the document.
  931 
  932 \index{images!thumbnail}\index{thumbnail}%
  933 \index{images!small images}%
  934 \index{images!image-maps}%
  935 \index{images!order-sensitive}%
  936 \index{images!order-insensitive}%
  937 \index{equations!array}%
  938 \index{environment!\env{equation}}\index{environment!eqnarray@\env{eqnarray}}%
  939 \index{eqnarray@\env{eqnarray} environment}\html{\\}%
  940 %
  941 All types of images can be shared.  These include ``small images''
  942 and figures with or without \htmlref{thumbnails}{thumbnail}
  943 and \htmlref{image-maps}{ImageMaps}.
  944 Furthermore, most images can also be reused.  The only
  945 exception are those which are \emph{order-sensitive},
  946 meaning that their content depends upon their location.
  947 Examples of order-sensitive images are \env{equation} 
  948 and \env{eqnarray} environments, 
  949 when \Cs{html\_version 2.0} has been specified;
  950 this is because their figure numbers are part of the image.
  951 
  952 \index{figures!captions}%
  953 \index{tables!captions}\html{\\}%
  954 
  955 Figures and tables with captions, on the other hand, 
  956 are order-insensitive because the figure numbers 
  957 are not part of the image itself.%
  958 Similarly when \HTMLiii{} code is being produced, equation
  959 numbers are no longer part of the image.
  960 Instead they are placed in a separate cell of a \HTMLtag{TABLE}.
  961 So most images of mathematical formulas can be reused also.%
  962 
  963 
  964 \subsubsection{Quality of Printed Images\label{printqual}}
  965 %\subsection{Quality of Printed Images\label{printqual}}
  966 %
  967 %% \begin{htmlonly}
  968 Since it is often desirable to get a good quality print on paper
  969 directly from the browser, \hyperref{here are}{Figure~}{ shows}{eq:pics15} 
  970 the same equations as \hyperref[page]{earlier}{on page~}{}{eq:pics}.
  971 This time the `\texttt{extrascale=}' option has been used with a value of 1.5\,.
  972 More than twice the number of pixels are available, 
  973 for a cost of approximately 1.7 times the disk-space\footnote{This figure
  974 varies with the graphics format used, and the complexity of the actual image.}.
  975 
  976 %% \end{htmlonly}
  977 
  978 \begin{figure}[hb]
  979 %% \begin{htmlonly}
  980 %% \begin{makeimage}
  981 %% \end{makeimage}
  982 %% \begin{equation}
  983 %% \htmlimage{no_antialias,extrascale=1.5}
  984 %% \Phi_{l+1,m,n} = \Bigl(\Phi+h\frac{\partial\Phi}{\partial x} +
  985 %% \frac{1}{2}h^2\frac{\partial^2\Phi}{\partial x^2} +
  986 %% \frac{1}{6}h^3\frac{\partial^3\Phi}{\partial x^3} + \,\ldots\,\Bigr)_{l,m,n}
  987 %% \end{equation}
  988 %% \begin{eqnarray}
  989 %% \htmlimage{extrascale=1.5}
  990 %% \frac{\Phi_{l+1,m,n}-2\Phi_{l,m,n}+\Phi_{l-1,m,n}}{h^{2}} +
  991 %% \frac{\Phi_{l,m+1,n}-2\Phi_{l,m,n}+\Phi_{l,m-1,n}}{h^{2}} \nonumber \\
  992 %% + \frac{\Phi_{l,m,n+1}-2\Phi_{l,m,n}+\Phi_{l,m,n-1}}{h^{2}} = -I_{l,m,n}(v)
  993 %% \end{eqnarray}
  994 %% \end{htmlonly}
  995 %% %
  996 %% \begin{latexonly}
  997 \begin{equation}
  998  \hbox{\scalebox{.4}{\includegraphics{psfiles/eqn15}}}
  999 \end{equation}%
 1000 \begin{eqnarray}
 1001  \nonumber
 1002  \hbox{\scalebox{.4}{\includegraphics{psfiles/eqarrA15}}}
 1003  &&\\
 1004  \hbox{\scalebox{.4}{\includegraphics{psfiles/eqarrB15}}}
 1005  &&
 1006 \end{eqnarray}
 1007 %% \end{latexonly}
 1008 \caption{Displayed math environments with \emph{extra-scale} of 1.5}
 1009 \label{eq:pics15}%
 1010 \end{figure}
 1011 
 1012 %% \begin{latexonly}
 1013 \noindent
 1014 Since it is often desirable to get a good quality print on paper
 1015 directly from the browser, \hyperref{here are}{Figure~}{ shows}{eq:pics15}
 1016 the same equations as \hyperref[page]{earlier}{on page~}{}{eq:pics}.
 1017 This time the `\texttt{extrascale=1.5}' option has been used. This value of 1.5
 1018 means that more than twice the number of pixels are available,
 1019 for a cost of approximately 1.7 times the disk-space\footnote{This figure
 1020 varies with the graphics format used, and the complexity of the actual image.}.
 1021 %% \end{latexonly}
 1022 \noindent
 1023 On-screen these images appear slightly blurred or indistinct. 
 1024 However there can be marked improvement in the print quality,
 1025 when printed from some browsers; others may show no improvement at all. 
 1026 The ``anti-aliasing'' helps on-screen. In the printed version
 1027 jagged edges are indeed softened, but leave an overall fuzziness. 
 1028 
 1029 
 1030 \hyperref{Here are}{Figure~}{ shows}{eq:pics2} 
 1031 the same equations yet again; this time with `\texttt{extrascale=2.0}'.
 1032 Now there are 4~times the pixels at a cost of roughly 2.45~times the disk space.
 1033 Compared with the previous images (having 1.5~times extra-scaling), 
 1034 there is little difference in the on-screen images.
 1035 Printing at 300\,dpi shows only a marginal improvement;
 1036 but at 600\,dpi the results are most satisfying, especially when
 1037 scaled to be comparable with normal 10\,pt type\latex{, as here}.
 1038 
 1039 \begin{figure}[ht]
 1040 %% \begin{htmlonly}
 1041 %% \begin{makeimage}
 1042 %% \end{makeimage}
 1043 %% \begin{equation}
 1044 %% \htmlimage{no_antialias,extrascale=2}
 1045 %% \Phi_{l+1,m,n} = \Bigl(\Phi+h\frac{\partial\Phi}{\partial x} +
 1046 %% \frac{1}{2}h^2\frac{\partial^2\Phi}{\partial x^2} +
 1047 %% \frac{1}{6}h^3\frac{\partial^3\Phi}{\partial x^3} + \,\ldots\,\Bigr)_{l,m,n}
 1048 %% \end{equation}
 1049 %% \begin{eqnarray}
 1050 %% \htmlimage{extrascale=2}
 1051 %% \frac{\Phi_{l+1,m,n}-2\Phi_{l,m,n}+\Phi_{l-1,m,n}}{h^{2}} +
 1052 %% \frac{\Phi_{l,m+1,n}-2\Phi_{l,m,n}+\Phi_{l,m-1,n}}{h^{2}} \nonumber \\
 1053 %% + \frac{\Phi_{l,m,n+1}-2\Phi_{l,m,n}+\Phi_{l,m,n-1}}{h^{2}} = -I_{l,m,n}(v)\;.
 1054 %% \end{eqnarray}
 1055 %% \end{htmlonly}
 1056 %% %
 1057 %% \begin{latexonly}
 1058 \begin{equation}
 1059  \setbox1=\hbox{\scalebox{.3}{\includegraphics{psfiles/eqn2}}}
 1060  \lower.5\ht1 \box1
 1061 \end{equation}
 1062 \begin{eqnarray}
 1063  \nonumber
 1064  \setbox1=\hbox{\scalebox{.3}{\includegraphics{psfiles/eqarrA2}}}
 1065  \lower.5\ht1 \box1&&\\
 1066  \setbox1=\hbox{\scalebox{.3}{\includegraphics{psfiles/eqarrB2}}}
 1067  \lower.5\ht1 \box1&&
 1068 \end{eqnarray}
 1069 %% \end{latexonly}
 1070 \caption{Displayed math environments with \emph{extra-scale} of 2.0}
 1071 \label{eq:pics2}
 1072 \end{figure}
 1073 
 1074 
 1075 
 1076 \subsection{Figures, Tables and Arbitrary Images\label{sec:figs}}
 1077 %\section{Figures, Tables and Arbitrary Images\label{sec:figs}}
 1078 \index{tables}%
 1079 \index{environment!arbitrary}\index{arbitrary environments}\html{\\}% 
 1080 This section is to explain how the translator handles figures, tables
 1081 and other environments. 
 1082 Compare the paper with the online version.
 1083 
 1084 When the common version of \texttt{HTML} was only 2.0, then almost all
 1085 complicated environments were represented using images. However with
 1086 \texttt{HTML} 3.2, there is scope for sensible layout of tables,
 1087 and proper facilities for associating a caption with a figure or table.
 1088 To take advantage of this, the \env{figure} environment now has its
 1089 contents placed within \HTMLtag{TABLE} tags; any caption is placed
 1090 as its \HTMLtag{CAPTION}.
 1091 
 1092 For consistency with former practice, the contents of the \env{figure}
 1093 environment are usually represented by generating an image. 
 1094 This is frequently exactly what is required; but not always.
 1095 \hyperref[page]{In another section}{On page~}{}{makeimage} it is 
 1096 described how to use the \env{makeimage} environment,
 1097 defined in the \fn{html.sty} package, to determine just which parts (if any)
 1098 of a \env{figure} environment's contents should be made into images,
 1099 the remainder being treated as ordinary text, etc.
 1100 
 1101 \medskip
 1102 \index{table@\env{table} environment}%
 1103 \index{environment!table@\env{table}}\html{\\}%
 1104 \paragraph*{\env{table} and \env{tabular} environments.}
 1105 
 1106 Similarly the \env{makeimage} environment can be used within
 1107 a \env{table}, though usually this is used with a \env{tabular}
 1108 or other table-making environment, such as \env{tabbing} or
 1109 \env{longtable} or \env{supertabular}.
 1110 Here is a simple example, from the \LaTeX{} \htmlcite{`blue book'}{lamp:latex}.
 1111 
 1112 \begin{table}[hbt]
 1113 \begin{center}
 1114 \begin{tabular}{||l|lr||}   \hline
 1115 gnats   &       gram    &       \$13.65  \\ \cline{2-3}
 1116         &       each    &        .01    \\ \hline
 1117 gnu     &       stuffed &        92.50  
 1118                 \\  \cline{1-1} \cline{3-3}
 1119 emur    &               &       33.33   \\ \hline
 1120 armadillo       & frozen        &       8.99 \\ \hline
 1121 \end{tabular}
 1122 \caption{A sample table taken from \protect\cite{lamp:latex}%}
 1123 \index{table@\env{table} environment}%
 1124 \index{environment!table@\env{table}}}%
 1125 \label{tab}
 1126 \end{center}
 1127 \end{table}
 1128 
 1129 \begin{htmlonly}
 1130 When using \texttt{ -html\_version 2.0} to get code compatible
 1131 with the \texttt{HTML} 2.0 standard, an image is made of the
 1132 table, as follows:
 1133 %
 1134 \begin{table}[ht]
 1135 \begin{center}
 1136 \begin{makeimage}
 1137 \begin{tabular}{||l|lr||}   \hline
 1138 gnats   &       gram    &       \$13.65  \\ \cline{2-3}
 1139         &       each    &        .01    \\ \hline
 1140 gnu     &       stuffed &        92.50  
 1141                 \\  \cline{1-1} \cline{3-3}
 1142 emur    &               &       33.33   \\ \hline
 1143 armadillo       & frozen        &       8.99 \\ \hline
 1144 \end{tabular}
 1145 \end{makeimage}
 1146 \caption{Alternate view of the table from \protect\cite{lamp:latex}}
 1147 \label{tab:alt}
 1148 \end{center}
 1149 \end{table}
 1150 \end{htmlonly}
 1151 %
 1152 %begin{latexonly}
 1153 \noindent
 1154 Table~\ref{tab:alt} is a screen-shot of how the resulting table appears on-screen,
 1155 using a typical browser supporting \HTMLiii.
 1156 Here it is scaled down by 70\% to compensate for the 14\,pt fonts being used when
 1157 the screen-shot was taken.
 1158 %
 1159 \begin{table}[ht]
 1160 \begin{center}
 1161  \scalebox{.7}{\includegraphics{psfiles/table}}
 1162 \caption{Alternate view of the table from \protect\cite{lamp:latex}}
 1163 \label{tab:alt}
 1164 \end{center}
 1165 \end{table}
 1166 %end{latexonly}
 1167 
 1168 \medskip
 1169 \index{minipage@\env{minipage} environment}%
 1170 \index{environment!minipage@\env{minipage}}\html{\\}%
 1171 \paragraph*{\env{minipage} environments.}
 1172 
 1173 The special feature of \env{minipage} environments is in the
 1174 way \Lc{footnote} and \Lc{footnotemark} commands are handled. 
 1175 These are numbered separately from the rest of the footnotes
 1176 throughout the document, and the notes themselves are collected together 
 1177 to be displayed at the end of the \env{minipage}'s contents.
 1178 
 1179 \medskip
 1180 \begin{minipage}{.9\textwidth}
 1181 %begin{latexonly}
 1182 \renewcommand{\thempfootnote}{\alph{mpfootnote}}
 1183 %end{latexonly}
 1184 \begin{tabular}{|l|l|} \hline
 1185 \textbf{Variable} & \textbf{Meaning} \\ \hline
 1186 none      & none                   \\
 1187 Jacobi    & $m$-step Jacobi iteration\footnote[1]{one footnote} \\
 1188 SSOR      & $m$-step SSOR iteration\footnotemark[1] \\
 1189 IC        & Incomplete Cholesky factorization\footnote[2]{another footnote} \\
 1190 ILU       & Incomplete LU factorization\footnotemark[2] \\ \hline
 1191 \end{tabular}
 1192 \end{minipage}
 1193 
 1194 \bigskip\noindent
 1195 The code used for this example was as follows\footnote{%
 1196 Thanks to John Turner \Email{turner@lanl.gov} for this example, 
 1197 which was used in developing
 1198 code to handle \env{minipage} environments correctly.}
 1199 %begin{latexonly}
 1200 \begin{small}
 1201 %end{latexonly}
 1202 \begin{verbatim}
 1203 \begin{minipage}{.9\textwidth}
 1204 \renewcommand{\thempfootnote}{\alph{mpfootnote}}
 1205 \begin{tabular}{|l|l|} \hline
 1206 \textbf{Variable} & \textbf{Meaning} \\ \hline
 1207 none      & none                   \\
 1208 Jacobi    & $m$-step Jacobi iteration\footnote[1]{one footnote} \\
 1209 SSOR      & $m$-step SSOR iteration\footnotemark[1] \\
 1210 IC        & Incomplete Cholesky factorization\footnote[2]{another footnote} \\
 1211 ILU       & Incomplete LU factorization\footnotemark[2] \\ \hline
 1212 \end{tabular}
 1213 \end{minipage}
 1214 \end{verbatim}
 1215 %begin{latexonly}
 1216 \end{small}
 1217 %end{latexonly}
 1218 
 1219 \bigskip\noindent
 1220 \textbf{Warning: }
 1221 With some figures, especially when containing graphics imported using
 1222 \Lc{includegraphics} or other special macros, the background color
 1223 may come out as a shade of grey, rather than white or transparent.
 1224 This is due to a setting designed to enhance anti-aliasing of text
 1225 within images; e.g. for mathematics.
 1226 To alleviate this possible problem, the \Cs{white} command-line option
 1227 can be used, to ensure a white background for images of \env{figure}
 1228 environments. 
 1229 Alternatively, set the \fn{\$WHITE\_BACKGROUND} 
 1230 \hyperref{variable}{variable (see section }{)}{cs_white}.
 1231 
 1232 
 1233 \subsection{Document Classes and Options\label{sec:cls}}
 1234 \tableofchildlinks*
 1235 \index{document class}%
 1236 In general the standard \LaTeX{} document-classes: 
 1237 \texttt{article}, \texttt{report}, \texttt{book}, \texttt{letter}, \texttt{slides}
 1238 are translated by \latextohtml{} in the same way. 
 1239 Currently the only real difference is with the display of section-numbering,
 1240 when the \htmlref{\Cs{show\_section\_numbers}}{showsecnums} switch is used,
 1241 and when numbering of \htmlref{theorem-like environments}{theoremenvs} 
 1242 is linked to section-numbering.
 1243 
 1244 \index{document class!loads file@loads a \texttt{.perl} file}%
 1245 \index{document class!options}%
 1246 
 1247 These differences are achieved using a mechanism that automatically loads a file:
 1248 \fn{article.perl}, \fn{report.perl}, \fn{book.perl}, \fn{letter.perl}, \fn{slides.perl} 
 1249 according to the requested document-class. 
 1250 These files contain \Perl{} code and are located in the \fn{styles/} directory.
 1251 If a file of the same name exists in the working directory, this will be loaded
 1252 instead.
 1253 
 1254 Typically such files \texttt{\Meta{class}.perl} contain code to define subroutines 
 1255 or sets values for variables that will affect how certain translations are performed. 
 1256 There can be code that is executed only when specific class-options are specified
 1257 along with the chosen document-class.
 1258 For example, the \fn{foils.perl} implementation of \FoilTeX's \env{foils} class
 1259 defines code create a new sub-section for each `foil'.
 1260 It also has code which allows \latextohtml{} to ignore those of \FoilTeX's special 
 1261 formatting commands that have no relevance when constructing an \texttt{HTML} page.
 1262 
 1263 \medskip 
 1264 \index{document class!loads file}%
 1265 \index{class-option!loads file}%
 1266 
 1267 Any options given on the \Lc{documentclass} or \Lc{documentstyle} line
 1268 may also cause a file containing \Perl{} code to be loaded. 
 1269 Such a file is named \texttt{\Meta{option}.perl} for the appropriate \Meta{option}.
 1270 When such a file exists, in the local directory or in the \fn{styles/} directory,
 1271 it typically contains \Perl{} code to define subroutines or set values for variables 
 1272 that will affect how certain translations are performed.
 1273 There can be code that is executed only for specific document-classes.
 1274 
 1275 Since the files for class-options are loaded after those for the document-class,
 1276 it is possible for the \texttt{\Meta{option}.perl} file to contain code that overrides
 1277 settings made within the document-class file.
 1278 
 1279 \medskip\index{class-option!specific file}%
 1280 If a file named \texttt{\Meta{class}\_\Meta{option}.perl} happens to exist for
 1281 a given combination of document-class \Meta{class} and class-option \Meta{option},
 1282 then this will be loaded. 
 1283 When such a file exists, reading and executing its contents is done,
 1284 rather than executing any \Meta{class}\_\Meta{option} specific information
 1285 that may be contained in  \texttt{\Meta{class}.perl} or \texttt{\Meta{option}.perl}~.
 1286 
 1287 \medskip
 1288 Currently there are no special option or class-option files provided with 
 1289 the \latextohtml{} distribution. It is hoped that users will identify ways 
 1290 that specific features can be improved or adapted to specific classes of documents, 
 1291 and will write such files themselves, perhaps submitting them for general distribution.
 1292 
 1293 \bigskip
 1294 \textbf{Note: }
 1295 This mechanism for handling code specific to different document classes
 1296 and class-options is more general than that employed by \LaTeXe.
 1297 New options can be defined for document-classes generally, or for specific classes,
 1298 without the need to have corresponding \texttt{.sty} or \texttt{.clo} files.
 1299 \LaTeX{} simply notes the existence of unusupported options---processing is not
 1300 interrupted.  
 1301 
 1302 
 1303 
 1304 \subsection{Packages and Style-Files\label{sec:sty}}
 1305 %\section{Packages and Style-Files\label{sec:sty}}
 1306 \tableofchildlinks*
 1307 \index{support!for specific style-files}%
 1308 \index{support!for german language}\html{\\}%
 1309 %
 1310 Similar to the document-class mechanism described in
 1311 \hyperref{the previous section}{Section}{}{sec:cls},
 1312 \latextohtml{} provides a mechanism whereby the code to translate specific
 1313 packages and style-files is auto\-matic\-ally loaded, if such code is available.
 1314 For example, when use of a style such as \fn{german.sty} 
 1315 is detected in a \LaTeX{} source document, either by
 1316 \begin{itemize}
 1317 \item
 1318 a \Lc{usepackage} command of \LaTeXe;
 1319 \item
 1320 an option to the \Lc{documentstyle} command of \LaTeX\,2.09\,;
 1321 \item
 1322 an explicit \Lc{input} or \Lc{include} command;
 1323 \end{itemize}
 1324 the translator looks for a corresponding \texttt{.perl} file
 1325 having the same file-name prefix;
 1326 e.g. the file \fn{\$LATEX2HTMLDIR/styles/german.perl}.
 1327 If such a \texttt{.perl} file is found, 
 1328 then its code will be incorporated with the main script,
 1329 to be used as required. 
 1330 
 1331 \index{extensions!examples}\html{\\}%
 1332 
 1333 This mechanism helps to keep the core script smaller, as well as making
 1334 it easier for others to contribute and share solutions on  
 1335 how to translate specific style-files.
 1336 The current distribution includes the files to support the styles
 1337 listed in \hyperref{the table below}{Table~}{}{styles}.
 1338 These provide good examples of how you can create 
 1339 further extensions to \latextohtml.%
 1340 
 1341 \index{style-files}\index{packages}%
 1342 %\begin{htmlonly}
 1343 %\begin{table}
 1344 %\end{htmlonly}
 1345 \begin{center}
 1346 %\begin{tabular}{|c|p{3in}|}
 1347 \begin{longtable}{|c|l|}
 1348 \caption{Supported \protect\latextohtml\ packages and style-files.}
 1349 \\\hline
 1350 \endhead
 1351 \hline
 1352 \endfoot
 1353 \label{styles}
 1354 \texttt{.perl}~file &\hfill\textbf{Description}\hfill\hfill~\\\hline
 1355 \env{\bf alltt}\index{environment!alltt@\env{alltt}}\index{alltt@\env{alltt} environment}%
 1356  & Supports the \LaTeXe's \env{alltt} package.\label{alltt}\\
 1357 \env{\bf amsfonts}\index{package!AMSfonts@\env{amsfonts}}\index{AMS@\AmS-\LaTeX!amsfonts@\env{amsfonts} package}%
 1358  & provides recognition of the special \AmS\ font symbols.\label{amsfonts}\\
 1359 \env{\bf amsmath}\index{package!AMSmath@\env{amsmath}}\index{AMS@\AmS-\LaTeX!amsmath@\env{amsmath} package}%
 1360  & same as \fn{amstex.perl}.\label{amsmath}\\
 1361 \env{\bf amssymb}\index{package!AMSsymb@\env{amssymb}}\index{AMS@\AmS-\LaTeX!amssymb@\env{amssymb} package}%
 1362  & same as \fn{amsfonts.perl}.\label{amssymb}\\
 1363 \env{\bf amstex}\index{package!AMStex@\env{amstex}}\index{AMS@\AmS-\LaTeX!amstex@\env{amstex} package}%
 1364  & Supports much of the \AmS-\LaTeX{} package (not yet complete).\label{amstex}\\
 1365 \env{\bf babel}\index{package!babel@\env{babel}}\index{babel@\env{babel} package}%
 1366  & Interface to \fn{german.perl} via the \env{babel} package.\label{babel}\\
 1367 \env{\bf changebar}\index{package!changebar@\env{changebar}}\index{changebar@\env{changebar} package}%
 1368  & Provides rudimentary change-bar support.\label{changebar}\\
 1369 \env{\bf chemsym}\index{package!chemsym@\env{chemsym}}\index{chemsym@\env{chemsym} package}%
 1370  & defines the standard atomic symbols.\label{chemsym}\\
 1371 \env{\bf color}\index{package!color@\env{color}}\index{color@\env{color} package}%
 1372  & Causes colored text to be processed as ordinary text by \latextohtml.\label{color}\\
 1373 \env{\bf colordvi}\index{package!colordvi@\env{colordvi}}\index{color!colordvi@\env{colordvi} package}%
 1374  & supports the Crayola colors.\label{crayola}\\
 1375 \env{\bf enumerate}\index{package!enumerate@\env{enumerate}}\index{enumerate@\env{enumerate} package}%
 1376  & supports structured labels for \env{enumerate} environments.\label{enumerate}\\
 1377 \env{\bf epsbox}\index{package!epsbox@\env{epsbox}}\index{epsbox@\env{epsbox} package}%
 1378  & Processes embedded figures not enclosed in a \env{figure} environment.\label{epsbox}\\
 1379 \env{\bf epsfig}\index{package!epsfig@\env{epsfig}}\index{epsfig@\env{epsfig} package}%
 1380  & Processes embedded figures not enclosed in a \env{figure} environment.\label{epsfig}\\
 1381 \env{\bf finnish}\index{package!finnish@\env{finnish}}\index{finnish!finnish@\env{finnish} package}%
 1382  & Support for the Finnish language.\label{finnish}\\
 1383 \env{\bf floatfig}\index{package!floatfig@\env{floatfig}}\index{floatfig@\env{floatfig} package}%
 1384  & Processes floating figures.\label{floatfig}\\
 1385 \env{\bf floatflt}\index{package!floatflt@\env{floatflt}}\index{floatflt@\env{floatflt} package}%
 1386  & Processes floating figures and tables.\label{floatflt}\\
 1387 \env{\bf foils}\index{class!foils@\env{foils}}\index{foils@\env{foils} class}\index{FoilTeX@\FoilTeX}%
 1388  & Supports \FoilTeX{} system.\label{foils}\\
 1389 \env{\bf frames}\index{package!frames@\env{frames}}\index{frames@\env{frames} package}%
 1390  & Provides separate frames for navigation and footnotes.\label{frames}\\
 1391 \env{\bf francais}\index{package!francais@\env{francais}}\index{french!francais@\env{francais} package}%
 1392  & Support for the French language, same as \fn{french.perl}.\label{francais}\\
 1393 \env{\bf french}\index{package!french@\env{french}}\index{french@\env{french} package}%
 1394  & Support for the French language.\label{french}\\
 1395 \env{\bf german}\index{package!german@\env{german}}\index{german@\env{german} package}%
 1396  & Support for the German language.\label{german}\\
 1397 \env{\bf germanb}\index{package!germanb@\env{germanb}}\index{german!germanb@\env{germanb} package}%
 1398  & Support for the German language, same as \fn{german.perl}.\label{germanb}\\
 1399 \env{\bf graphics}\index{package!graphics@\env{graphics}}\index{graphics@\env{graphics} package}%
 1400  & Supports commands in the \env{graphics} package.\label{graphics}\\
 1401 \env{\bf graphicx}\index{package!graphicx@\env{graphicx}}\index{graphics!graphicx@\env{graphicx} package}%
 1402  & Supports the alternate syntax of graphics commands.\label{graphicx}\\
 1403 \env{\bf harvard}\index{package!harvard@\env{harvard}}\index{citations!harvard@\env{harvard} package}%
 1404  & Supports the \env{harvard} style of \htmlref{citation}{harvard} (same as fn{nharvard.perl}).\\
 1405 \env{\bf heqn}\index{package!heqn@\env{heqn}}\index{heqn@\env{heqn} package}%
 1406  & Alters the way displayed equations are processed.\label{heqn}\\
 1407 \env{\bf hthtml}\index{environment!hthtml@\env{hthtml}}\index{hthtml@\env{hthtml} environment}%
 1408  & gives an alternative syntax for specifying hyperlinks, etc.\label{hthtml}\\
 1409 \env{\bf htmllist}\index{environment!htmllist@\env{htmllist}}\index{htmllist@\env{htmllist} environment}%
 1410  & Provides support for \htmlref{fancy lists}{htmllist}.\\
 1411 \env{\bf justify}\index{package!justify@\env{justify}}\index{justify@\env{justify} package}%
 1412  & supports paragraph alignment---no longer needed.\\
 1413 \env{\bf latexsym}\index{package!latexsym@\env{latexsym}}\index{latexsym@\env{latexsym} package}%
 1414  & supports the \LaTeX{} symbol font.\label{latexsym}\\
 1415 \env{\bf lgrind}\index{package!lgrind@\env{lgrind}}\index{lgrind@\env{lgrind} package}%
 1416  & macros for nice layout of computer program code.\label{lgrind}\\
 1417 \env{\bf longtable}\index{package!longtable@\env{longtable}}%
 1418 \index{tables!longtable@longtable\env{longtable} package}%
 1419  & supports use of long tables, as a single table.\label{longtable}\\
 1420 \env{\bf makeidx}\index{package!makeidx@\env{makeidx}}\index{makeidx@\env{makeidx} package}%
 1421  & provides more sophisticated indexing.\label{makeidx}\\
 1422 \env{\bf multicol}\index{package!multicol@\env{multicol}}\index{columns!multicol@\env{multicol} package}%
 1423  & suppresses requests for multi-columns.\label{multicol}\\
 1424 \env{\bf natbib}\index{package!natbib@\env{natbib}}\index{citations!natbib@\env{natbib} package}%
 1425  & Supports many different styles for citations and bibliographies.\label{natbib}\\
 1426 \env{\bf nharvard}\index{package!nharvard@\env{nharvard}}\index{citations!nharvard@\env{nharvard} package}%
 1427  & Supports harvard-style citations, using \env{natbib}.\label{nharvard}\\
 1428 \env{\bf seminar}\index{package!seminar@\env{seminar}}\index{seminar@\env{seminar} package}%
 1429  & for creation of overhead-presentation slides.\label{seminar}\\
 1430 \env{\bf spanish}\index{package!spanish@\env{spanish}}\index{spanish@\env{spanish} package}%
 1431  & Support for the Spanish language.\label{spanish}\\
 1432 \env{\bf supertabular}\index{package!supertabular@\env{supertabular}}\index{tables!supertabular@\env{supertabular} package}%
 1433  & supports use super-tables, as an ordinary table.\label{supertabular}\\
 1434 \env{\bf texdefs}\index{package!texdefs@\env{texdefs}}\index{texdefs@\env{texdefs} package}%
 1435  & Supports some raw \TeX{} commands.\label{texdefs}\\
 1436 \env{\bf verbatim}\index{package!verbatim@\env{verbatim}}\index{verbatim@\env{verbatim} package}%
 1437  & Supports verbatim input of files.\label{verbatim}\\
 1438 \env{\bf verbatimfiles}\index{package!verbatimfiles@\env{verbatimfiles}}\index{verbatim!verbatimfiles@\env{verbatimfiles} package}%
 1439  & Supports verbatim input of files, also with line-numbering.\label{verbatimfiles}\\
 1440 \env{\bf wrapfig}\index{package!wrapfig@\env{wrapfig}}\index{figures!wrapfig@\env{wrapfig} package}%
 1441  & Supports wrapped figures.\label{wrapfig}\\
 1442 \env{\bf xspace}\index{package!xspace@\env{xspace}}\index{xspace@\env{xspace} package}%
 1443  & Supports use of the \env{xspace} package and \Lc{xspace} command.\label{xspace}\\
 1444 \env{\bf xy}\index{package!xypic@\protect\Xy-pic}\index{xypic@\protect\Xy-pic package}%
 1445 \index{graphics!xy@\protect\Xy-pic package}%
 1446  & Supports use of the \Xy-pic graphics package.\label{xypic}\\
 1447 %\hline
 1448 \end{longtable}
 1449 %\end{tabular}
 1450 \end{center}
 1451 %\begin{htmlonly}
 1452 %\end{table}
 1453 %\end{htmlonly}
 1454 %\end{table}
 1455 \index{extensions!require understanding@require understanding of \Perl{}}\html{\\}%
 1456 \noindent
 1457 The problem however, is that writing such extensions requires an understanding 
 1458 of \Perl{} programming and of the way the processing in \latextohtml{} is organised. 
 1459 Interfaces that are more ``user-friendly'' are being investigated.
 1460 Some of the techniques currently used are explained in 
 1461 \hyperref{a later section}{Section~}{}{sec:ext}.
 1462 
 1463 
 1464 \subsubsection{Fancy List-Markers\label{htmllist}}
 1465 %\subsection{Fancy List-Markers\label{htmllist}}
 1466 \index{htmllist@\env{htmllist} environment}%
 1467 \index{environment!htmllist@\env{htmllist}}%
 1468 %
 1469 An optional style-file \fn{htmllist.sty} has been provided which
 1470 produces fancier lists in the electronic version of the document%
 1471 \html{, }\htmlref{such as this}{listExample}.
 1472 This file defines a new \LaTeX{} environment \env{htmllist},
 1473 which causes a user-defined item-mark to be placed at each new
 1474 item of the list, and which causes the optional description
 1475 to be displayed in bold letters.
 1476 The filename prefix for the item-mark image can be given as an
 1477 optional parameter; see example below. The images distributed with
 1478 \latextohtml{} for this purpose are listed with the description
 1479 of the \verb|\htmlitemmark| command, which provides an alternative
 1480 means of choosing the item-mark, and allows the image to be changed
 1481 for different items in the list.
 1482 
 1483 \index{htmlitemmark@\Lc{htmlitemmark}}%
 1484 \index{htmllist@\env{htmllist}!prints as@prints as \env{description}}%
 1485 \index{htmllist@\env{htmllist}!item-marks}%
 1486 \index{environment!htmllist@\env{htmllist}}\html{\\}%
 1487 %
 1488 The mark is determined
 1489 by the \verb|\htmlitemmark{|\Meta{item-mark}\verb|}| command.  
 1490 This command accepts either a mnemonic name for the \Meta{item-mark}, 
 1491 from a list of icons established at installation, or the URL of a mark
 1492 not in the installation list. 
 1493 The command \Lc{htmlitemmark} must be used \emph{inside} the 
 1494 \env{htmllist} environment in order to be effective, 
 1495 and it may be used more than once to change the mark within the list.  
 1496 The item-marks supplied with \latextohtml{} are 
 1497 \texttt{BlueBall}, \texttt{RedBall}, \texttt{OrangeBall}, \texttt{GreenBall}, 
 1498 \texttt{PinkBall}, \texttt{PurpleBall}, \texttt{WhiteBall} and \texttt{YellowBall}.
 1499 The \env{htmllist} environment is identical to 
 1500 the \env{description} environment in the printed version.
 1501 
 1502 \index{htmllist@\env{htmllist}!example}%
 1503 
 1504 \noindent 
 1505 An example of its usage is:
 1506 %begin{latexonly}
 1507 \begin{small}
 1508 %end{latexonly}
 1509 \begin{verbatim}
 1510 \begin{htmllist}[WhiteBall]
 1511 \item[Item 1:] This will have a white ball.
 1512 \item[Item 2:] This will also have a white ball.
 1513 \htmlitemmark{RedBall}%
 1514 \item[Item 3:] This will have a red ball.
 1515 \end{htmllist}
 1516 \end{verbatim}
 1517 %begin{latexonly}
 1518 \end{small}
 1519 %end{latexonly}
 1520 
 1521 \noindent This will produce:\label{listExample}
 1522 \begin{htmllist}[WhiteBall]
 1523 %begin{latexonly}
 1524 \addtolength{\leftskip}{15pt}
 1525 %end{latexonly}
 1526 \item[Item 1:] This will have a white ball.
 1527 \item[Item 2:] This will also have a white ball.
 1528 \htmlitemmark{RedBall}%
 1529 \item[Item 3:] This will have a red ball.
 1530 \end{htmllist}
 1531 
 1532 \index{floatfig@\env{floatingfigure} environment}%
 1533 \index{wrapfig@\env{wrapfigure} environment}%
 1534 \index{environment!floatingfigure@\env{floatingfigure}}%
 1535 \index{environment!wrapfigure@\env{wrapfigure}}\html{\\}%
 1536 \noindent
 1537 One can also obtain \LaTeXe\ style-files \fn{floatfig.sty} and 
 1538 \fn{wrapfig.sty}, which provide support for the \env{floatingfigure}
 1539 and \env{wrapfigure} environments, respectively.  These environments
 1540 allow text to wrap around a figure in the printed version, 
 1541 but are treated exactly as an ordinary \env{figure}s in the electronic version.  
 1542 They are described in \hypercite{The \LaTeX{} Companion}%
 1543 {\emph{The \LaTeX{} Companion}}{}{goossens:latex}.%
 1544 
 1545 \subsubsection{Support for \FoilTeX\label{sec:foils}}
 1546 \index{foils@\env{foils} class}%
 1547 \index{FoilTeX@\FoilTeX} The \FoilTeX{} system presents some
 1548 additional problems for \latextohtml:
 1549 \begin{itemize}
 1550 \item It has additional commands like \Lc{foilhead} and
 1551   \Lc{rotatefoilhead}, that roughly correspond to sectioning commands,
 1552 \item The images are produced at the sizes suitable for large screen
 1553   presentation, but not for the HTML.
 1554 \end{itemize}
 1555 The package \fn{foils.perl} deals with these problems. It treats foils as
 1556 starred subsections and ignores \FoilTeX-specific commands that have no
 1557 meaning for HTML, like \Lc{LogoOn}. The header
 1558 \Lc{documentclass[}+\texttt{\it options}\verb+]{foils}+ in the
 1559 \fn{images.tex} file is substituted by the header
 1560 \Lc{documentclass[}\fn{\$FOILOPTIONS}\verb+]{+\fn{\$FOILCLASS}\verb+}+,
 1561 where the variables \fn{\$FOILOPTIONS} and \fn{\$FOILCLASS} can be set
 1562 in the configuration file (by default they are \texttt{'10pt'} and
 1563 \texttt{'article'} correspondingly).
 1564 A further variable \fn{\$FOILHEADLEVEL} holds the level of sectioning
 1565 at which a `foil' is to correspond; the default level is 4 (sub-section).
 1566 
 1567 The \LaTeX{} style file \fn{foilhtml.sty} in the \fn{texinputs/}
 1568 directory provides some additional features for \FoilTeX{}. It implements
 1569 structural markup commands like \Lc{section},
 1570 \Lc{tableofcontents} for foils. See the directory \fn{docs/foilhtml/} for
 1571 the details.
 1572 
 1573 
 1574 
 1575 \subsubsection{Indicating Differences between Document Versions\index{change-bars}}%
 1576 %\subsection{Indicating Differences between Document Versions\index{change-bars}}%
 1577 \latextohtml{} supports the \LaTeXe\ \fn{changebar.sty} package,
 1578 written by Johannes Braams \Email{JLBraams@cistron.nl}, for 
 1579 inserting \emph{change-bars} in a document in order to indicate 
 1580 differences from previous versions. This is a very primitive form of 
 1581 version control and there is much scope for improvement.
 1582 
 1583 \index{change-bars!different versions}% 
 1584 Within the \LaTeX{} version of this manual two thicknesses of change-bar 
 1585 have been used. Thicker bars indicate changes introduced with version \textsc{v97.1}\,,
 1586 while thinner bars indicate earlier additions since \textsc{v96.1}\,.\html{\\}
 1587 Within the \texttt{HTML} version the change-bars clearly indicate the 
 1588 different revisions with explicit numbering.%
 1589 Within the \texttt{HTML} version, the graphic icons representing
 1590 the changebars can be followed by some text indicating the new version.
 1591 This is used repeatedly throughout\latex{ the online version of}
 1592 this manual. It is achieved using the command 
 1593 \verb|\cbversion{|\Meta{version}\verb|}|, immediately following
 1594 the \verb|\begin{changebar}|. 
 1595 This sets a variable \fn{\$cb\_version} to be used both at the beginning
 1596 and end of the environment. The value of this variable is retained,
 1597 to be used with other \env{changebar} environments, unless changed explicitly
 1598 by another occurrence of \fn{\$cb\_version}.
 1599 
 1600 \smallskip\noindent
 1601 \textbf{Warning: }
 1602 \latextohtml{} will not correctly process \env{changebar} environments
 1603 that contain sectioning commands, even when the (sub)sections or
 1604 (sub)paragraphs are to occur on the same \texttt{HTML} page.
 1605 If this is required, use a separate \env{changebar} environment
 1606 within each (sub)section or (sub)paragraph.
 1607 
 1608 
 1609 
 1610 
 1611 \subsection{Indexing\label{index}\index{index|(}}%
 1612 %\section{Indexing\label{index}\index{index|(}}%
 1613 \index{index!section-names}%
 1614 \latextohtml{} automatically produces an Index consisting of the
 1615 arguments to all \Lc{index} commands encountered, if there are any.
 1616 A hyperlink is created to that point in the text where the 
 1617 \Lc{index} command occurred.
 1618 
 1619 More sophisticated indexing is available by loading the \env{makeidx} package.
 1620 Most of the features described in \cite[Appendix~A]{lamp:latex} become available.
 1621 This includes:
 1622 %
 1623 \begin{htmllist}\htmlitemmark{RedBall}%
 1624 \index{index!styled entries}%
 1625 \item 
 1626 [styled entries, using `\texttt{@}' : ]
 1627 Entries of the form \verb|\index{|\Meta{sort-key}\verb|@|\Meta{styled-text}\verb|}|
 1628 produce \Meta{styled-text} as the entry, but sorted according to \Meta{sort-key}.
 1629 
 1630 \index{index!hierarchical}%
 1631 \item 
 1632 [hierarchical entries, using `\texttt{!}' : ] 
 1633 Entries of the form
 1634 \verb|\index{|\Meta{item}\verb|!|\Meta{sub-item}\verb|}|
 1635 set the \Meta{sub-item} indented below the \Meta{item}.
 1636 Unlimited levels of hierarchy are possible, 
 1637 even though \LaTeX{} is limited to only 3 levels. 
 1638 The \Meta{sort-key}\verb|@|\Meta{styled-text} can be used at each level.
 1639 
 1640 \index{index!page-ranges}%
 1641 \item 
 1642 [explicit ranges, using `\texttt{|(}' and `\texttt{|)}' : ]
 1643 This is perhaps more useful in the \LaTeX{} version. 
 1644 In the \texttt{HTML} version these simply insert words ``from'' and ``to'',
 1645 respectively, prior to the hyperlink to where the index-entry occurs.
 1646 
 1647 \index{index!cross-link}%
 1648 \index{index!see@\texttt{\char124see}}%
 1649 \item 
 1650 [\texttt{|see\char123}\Meta{index-entry}\texttt{\char125} : ]
 1651 provides a textual reference to another indexed word or phrase, 
 1652 by inserting the word ``see''. 
 1653 This can be used in conjunction with \Lc{htmlref} to create a hyperlink
 1654 to the \Meta{index-entry}; viz.
 1655 \begin{verbatim}
 1656 \index{latexe@\LaTeXe |see{\htmlref{\LaTeX}{IIIlatex}}}
 1657 \end{verbatim}
 1658 where a \Lc{label} has been specified in some other index-entry, as follows:
 1659 \begin{verbatim}
 1660 \index{latex@\LaTeX\label{IIIlatex}}
 1661 \end{verbatim}
 1662 
 1663 \index{index!emph@\texttt{\char124emph}}%
 1664 \item [\texttt{|emph} : ]
 1665 \strikeout{is recognised but \emph{ignored}; 
 1666 other \texttt{|\Meta{command}} commands are \emph{not} processed by \latextohtml{},
 1667 with the following exception\dots} is handled correctly, by applying
 1668 \Lc{emph} to the text of the generated hyperlink.
 1669 
 1670 \index{index!style@\texttt{\char124}\Meta{style}}%
 1671 \item [\texttt{|}\Meta{style} : ]
 1672 where \Meta{style} is the name of \LaTeX{} style-changing command, 
 1673 without the initial `\Lc{}'; e.g. `\texttt{emph}', `\texttt{textbf}',
 1674 `\texttt{textit}', etc. The corresponding \LaTeX{} command is applied
 1675 to the text of the generated hyperlink.
 1676 
 1677 \index{index!blank lines}%
 1678 \index{index!alphabetization}%
 1679 \item [blank lines and alphabetization: ]
 1680 Having precisely a single space-character after the \verb+|+ 
 1681 (e.g. \verb+\index{A| }+) 
 1682 places a blank line before the index entry and omits the hyperlink.
 1683 This is used mainly for visual formatting; it allows a break before the entries
 1684 starting with each letter, say. Using a printable-key, as in \verb+\index{Q@Q, R| }+,
 1685 is appropriate when there are no indexed words starting with `Q', say.
 1686 
 1687 \index{index!quoted delimiters}%
 1688 \item [quoted delimiters: ]
 1689 The three special delimiters can be used within the printable portion,
 1690 if preceded by the double-quote character: \verb+"@+, \verb+"|+, \verb+"!+ 
 1691 and also \verb+""+ for the quote character itself. 
 1692 Also \verb|\"| produces an umlaut accent on the following character, 
 1693 when appropriate, else is ignored.
 1694 %
 1695 \end{htmllist}%
 1696 
 1697 \index{index!cross-link}%
 1698 \index{index!labelled entries}\html{\\}\noindent
 1699 %
 1700 Furthermore, the printable part of an index entry can contain \texttt{HTML}
 1701 anchors; that is, hyperlinks and/or \verb|\label{...}|s.
 1702 This allows index entries to contain cross-links to other entries, for example,
 1703 as well as allowing index-entries to be the target of hyperlinks from elsewhere
 1704 within the document. 
 1705 
 1706 The \htmlref{next section}{glossind} describes how this feature is used within this
 1707 manual to create a Glossary, containing a short description of all file-names,
 1708 configuration-variables and application software mentioned within the manual,
 1709 integrated with the Index. All occurrences of the technical names can be
 1710 easily found, starting from any other.
 1711 
 1712 \index{index!labelled entries}
 1713 
 1714 When a single item is indexed many times, it is sufficient 
 1715 to have a \Lc{label} command appearing within the printable portion 
 1716 of the first instance of an \verb|\index{...}| command for that item,
 1717 within a single document segment. 
 1718 
 1719 \medskip
 1720 
 1721 If the index-entries are in different segments of a segmented document, 
 1722 it is sufficient to have the  \verb|\index{...@...\label{...}}| appearing 
 1723 within that segment, in which the item is indexed, whose indexing information 
 1724 is loaded earliest via a \verb|\internal[index]{...}| command.
 1725 When in doubt, include one \verb|\index{...@...\label{...}}| per segment 
 1726 in which the item is indexed.
 1727 
 1728 \index{index!cross-link}%
 1729 \index{index!cross-link incorrect}
 1730 
 1731 For cross-links to work effectively within segmented documents,
 1732 the indexing command 
 1733 \verb|\index{...@...\label{...}}| \emph{must} occur earlier 
 1734 in the same segment than any use of 
 1735 \verb|\index{...@...\htmlref{...}{...}}| 
 1736 intended to create a link to that label. 
 1737 If the \Lc{label} occurs in a different segment,
 1738 then a \verb|\internal[index]{...}| command for that segment,
 1739 may be needed at the beginning of the segment with the \Lc{htmlref}\,.
 1740 When this is done incorrectly, the resulting link will be to the
 1741 segment where the indexed item occurred, 
 1742 rather than staying within the Index.
 1743 
 1744 \htmlrule
 1745 \index{index!section-names}%
 1746 \index{index!cumbersome}%
 1747 
 1748 \noindent
 1749 Since use of section-names, as the text for hyperlinks, can lead to a very long
 1750 and cumbersome Index, especially when single items have been indexed many times,
 1751 a further feature is provided to obtain a more compact Index.
 1752  
 1753 \index{index!codified links}\html{\\}%
 1754 Use of the command-line option \Cs{short\_index} causes a codified 
 1755 representation of the sectioning to be used, rather than the full section-name.
 1756 The differences are as follows.
 1757 %
 1758 \begin{itemize}
 1759 %
 1760 \item
 1761 For example, `\texttt{2.1}' means sub-node~\#1 of node~\#2, 
 1762 viewing the entire document as a tree-like structure. 
 1763 
 1764 \index{index!codified links!top-most node}%
 1765 \item
 1766 The top-most node is simply denoted `\verb|^|'.
 1767 
 1768 \index{segmentation!child-links}%
 1769 \index{segmentation!codified index}%
 1770 \item
 1771 With a \htmlref{segmented document}{Segmentation}, 
 1772 each segment is codified separately 
 1773 using the \htmlref{\Meta{prefix}}{prefix} supplied for that segment.
 1774 The Index includes a legend of these prefixes, 
 1775 each giving the title of the leading page from the segment,
 1776 as a hyperlink to the place on that page where its 
 1777 child-links are displayed.
 1778 
 1779 \index{index!codified links!for easier browsing}%
 1780 \item
 1781 Hyperlinks start on the same line as the index-key, 
 1782 rather than the next line, separated by `\texttt{|}'. 
 1783 This gives further compactification for easier browsing.
 1784 
 1785 \index{index!with prefix@with \Meta{prefix}}%
 1786 \item
 1787 If \Cs{prefix \Meta{prefix}} has been specified, then the \Meta{prefix}
 1788 is prepended to the codified form. This is most useful for segmented documents. 
 1789 Now the top-most node is indicated by the bare \Meta{prefix}.
 1790 \end{itemize}
 1791 %
 1792 These features can also be obtained by setting the variable \fn{\$SHORT\_INDEX}
 1793 to have value `\texttt{1}', in a configuration or initialisation file;
 1794 provided, of course, that the document loads the \env{makeidx} package.%
 1795 
 1796 \latex{\index{index|)}}
 1797 
 1798 
 1799 
 1800 \subsubsection{Integrated Glossary and Index\label{glossind}}%
 1801 %\subsection{Integrated Glossary and Index\label{glossind}}%
 1802 \index{index!integrated with Glossary}%
 1803 \index{Glossary!integrated with Index}%
 1804 
 1805 \noindent
 1806 A large number of different pieces of software are required to make
 1807 \latextohtml{} work effectively, as well as many files containing data or code 
 1808 to work with parts of this software. 
 1809 For this reason, a Glossary is included with this manual. 
 1810 It contains the names of all files, configuration variables, application software
 1811 and related technical terms, with a short description of what it is, or does,
 1812 and perhaps a URL for further reference. 
 1813 
 1814 \index{Glossary!printed version}%
 1815 \index{Glossary!HTML@\texttt{HTML} version}\html{\\}%
 1816 In the printed version each item in the Glossary is accompanied by the page-numbers
 1817 on which the item is mentioned, somewhat like in the Index. 
 1818 For the \texttt{HTML} version, each glossary-item contains a hyperlink to an
 1819 index-entry, which then has links to each occurrence.
 1820 These extra index-entries do not appear in the printed version; 
 1821 indeed they also contain a hyperlink back to the corresponding glossary-entry. 
 1822 
 1823 This feature is currently available only when using the \env{makeidx} package,
 1824 and needs also the \env{html} and \env{htmllist} packages.
 1825 It was developed for version 96.1f by Ross Moore,
 1826 incorporating an extensive revision of \fn{makeidx.perl}, as well as additions to
 1827 \latextohtml{} so that all aspects of indexing work correctly with segmented documents.
 1828 
 1829 \bigskip
 1830 \noindent
 1831 Since \LaTeX{} provides no guidelines for how a Glossary should be constructed,
 1832 the technique used here will be explained in detail, for both the printed and
 1833 \texttt{HTML} versions. 
 1834 
 1835 \begin{itemize}
 1836 \item
 1837 Firstly the \Lc{makeglossary} command, which is similar to \Lc{makeindex},
 1838 must appear in the document preamble, so that \LaTeX{} will record
 1839 uses of the \verb|\glossary{...}| command within a file \fn{manual.glo}.
 1840 
 1841 This command is redundant in the \texttt{HTML} version, so is given a trivial
 1842 definition which is ignored by \LaTeX{}.\par
 1843 
 1844 \item
 1845 Next, the words, phrases or technical terms to be included in the Glossary
 1846 are marked in the main text using the \Lc{glossary} command, used indirectly
 1847 via other macros. For example, file-names are inserted via 
 1848 \verb|\|\verb|fn{html.sty}|, \verb|\|\verb|fn{dvips}|,  \verb|\|\verb|appl{dvips}| etc. 
 1849 which both insert the text and create the glossary-entry; \textit{viz.}
 1850 %
 1851 %begin{latexonly}
 1852 \begin{small}
 1853 %end{latexonly}
 1854 \begin{verbatim}
 1855 \newcommand{\fn}[1]{\htmlref{\texttt{#1}}{GGG#1}\glossary{#1}}
 1856 \newcommand{\appl}[1]{\htmlref{\textsl{#1}}{GGG#1}%
 1857   \Glossary{#1}{\textsl{#1}}}
 1858 \end{verbatim}
 1859 %begin{latexonly}
 1860 \end{small}
 1861 %end{latexonly}
 1862 
 1863 \item
 1864 The expansions of \Lc{glossary}, and the slightly more general 
 1865 \Lc{Glossary}, are different for the printed and \texttt{HTML} versions.
 1866 For the \texttt{HTML} version the following definitions occur 
 1867 within an \env{htmlonly} environment:
 1868 %
 1869 %begin{latexonly}
 1870 \begin{small}
 1871 %end{latexonly}
 1872 \begin{verbatim}
 1873 \def\glossary#1{\index{#1@\texttt{#1} \label{III#1}%
 1874   \htmlref{(G)}{GGG#1}}}
 1875 \def\Glossary#1#2{\index{#1@{#2} \label{III#1}\htmlref{(G)}{GGG#1}}}
 1876 \def\makeglossary{}
 1877 \end{verbatim}
 1878 %begin{latexonly}
 1879 \end{small}
 1880 %end{latexonly}
 1881 %
 1882 \dots while in \LaTeX{} we need only:\quad
 1883 \verb|\newcommand\Glossary[2]{\glossary{#1@#2}}|~.
 1884 
 1885 Notice how the feature of \env{makeidx}, allowing the printable portion to
 1886 be separate from the sorting-key, is used to allow text-styles to be included within
 1887 both index-entries and glossary-entries. Indeed the purpose of \Lc{Glossary} is
 1888 to allow deviations from a fixed style, e.g. 
 1889 %
 1890 %begin{latexonly}
 1891 \begin{small}
 1892 %end{latexonly}
 1893 \begin{verbatim}
 1894 \newcommand{\MF}{\htmlref{\textsl{Metafont}}{GGGmetafont}%
 1895   \Glossary{metafont}{\textsl{Metafont}}}%
 1896 \end{verbatim}
 1897 %begin{latexonly}
 1898 \end{small}
 1899 %end{latexonly}
 1900 %
 1901 Also notice that in the \texttt{HTML} version an index-entry is created that
 1902 includes, within its printable portion, both a \Lc{label} and a hyperlink.
 1903 The former, having name \texttt{III...}, will ultimately reside on the Index page, 
 1904 while the latter will point to an anchor named \texttt{GGG...} on the Glossary page.
 1905 These names must be distinct from any other names used with \Lc{label}s 
 1906 elsewhere in the document, hence the use of prefixes \texttt{III} and \texttt{GGG}.
 1907 A short string `\texttt{(G)}' is used for the text of the hyperlink in the Index.
 1908 
 1909 \item
 1910 The text descriptions of the glossary-items are stored in a file 
 1911 called \fn{l2hfiles.dat}, with one description per line.
 1912 For the \texttt{HTML} version this file is actually read as input:
 1913 %
 1914 \begin{comment}
 1915 \begin{small}
 1916 \latex{\hskip15pt}\verb|\|\verb|begin{htmlonly}|%
 1917 \latex{\vskip-1.1\baselineskip\vskip-1.1\baselineskip\indentverb{15pt}}%
 1918 \begin{verbatim}
 1919 \section*{Glossary of variables and file-names\label{Glossary}}
 1920 \begin{htmllist}\htmlitemmark{OrangeBall}
 1921 \input l2hfiles.dat
 1922 \end{htmllist}
 1923 \end{verbatim}
 1924 \latex{\nobreak\vskip-1.1\baselineskip\nobreak\leavevmode\hskip15pt}%
 1925 \verb|\|\verb|end{htmlonly}|%
 1926 \end{small}%
 1927 \end{comment}
 1928 %
 1929 %begin{latexonly}
 1930 \begin{small}
 1931 %end{latexonly}
 1932 \begin{verbatim}
 1933 \section*{Glossary of variables and file-names\label{Glossary}}
 1934 \begin{htmllist}\htmlitemmark{OrangeBall}
 1935   \input l2hfiles.dat
 1936 \end{htmllist}
 1937 \end{verbatim}
 1938 %begin{latexonly}
 1939 \end{small}%
 1940 %end{latexonly}
 1941 
 1942 \noindent
 1943 For this reason alone it is desirable to have \fn{l2hfiles.dat} sorted alphabetically.\par
 1944 
 1945 \item
 1946 The mechanism used for the \LaTeX{} version also requires the file to be sorted
 1947 strictly alphabetically, according to the sort-keys associated to each glossary entry.
 1948 \newline
 1949 (This requirement could be relaxed, but only with a loss in efficiency; see below.)
 1950 
 1951 \LaTeX{} constructs its Glossary by running the \fn{makeindex} utility 
 1952 on the file \fn{manual.glo}, using the following command:
 1953 %
 1954 %begin{latexonly}
 1955 \begin{small}%
 1956 %end{latexonly}
 1957 \begin{verbatim}
 1958 makeindex -o manual.gls -s l2hglo.ist manual.glo
 1959 \end{verbatim}
 1960 %begin{latexonly}
 1961 \end{small}%
 1962 %end{latexonly}
 1963 %
 1964 Its output, which includes page numbering for an index, is stored in \fn{manual.gls}
 1965 and subsequently read by \LaTeX{} using:
 1966 
 1967 %begin{latexonly}
 1968 \begin{small}%
 1969 %end{latexonly}
 1970 \begin{verbatim}
 1971 \InputIfFileExists{manual.gls}{\clearpage\typeout{^^Jcreating Glossary...}}
 1972 {\typeout{^^JNo Glossary, since  manual.gls  could not be found.^^J}}
 1973 \end{verbatim}%
 1974 %begin{latexonly}
 1975 \end{small}%
 1976 %end{latexonly}
 1977 
 1978 \noindent
 1979 The configuration file \fn{l2hglo.ist} is included along with this manual.
 1980 It contains a portion that inserts tricky \TeX{} code at the beginning of \fn{manual.gls}.
 1981 This code extracts from \fn{l2hfiles.dat} that line corresponding to each glossary entry, 
 1982 then typesets it itemized within an environment called \env{theglossary}.
 1983 
 1984 %begin{latexonly}
 1985 \begin{small}%
 1986 %end{latexonly}
 1987 \begin{verbatim}
 1988 \newenvironment{theglossary}{\begin{list}{}{%
 1989   \setlength{\labelwidth}{20pt}%
 1990   \setlength{\leftmargin}{\labelwidth}%
 1991   \setlength\itemindent{-\labelwidth}%
 1992   \setlength\itemsep{0pt}\setlength\parsep{0pt}%
 1993   \rmfamily}}{\end{list}}
 1994 \end{verbatim}
 1995 %begin{latexonly}
 1996 \end{small}%
 1997 %end{latexonly}
 1998 %
 1999 Currently searching within \fn{l2hfiles.dat} is only done sequentially, stopping
 2000 at the end of the file. If an entry is not found then it is skipped and a message
 2001 printed to the log; the next entry will search from the top of the file.
 2002 If all entries are included and maintained in strict order, there will be no skipping 
 2003 and each line of \fn{l2hfiles.dat} is read exactly once.\par
 2004 
 2005 \item
 2006 Within \fn{l2hfiles.dat} the data lines look like:
 2007 %
 2008 %begin{latexonly}
 2009 \begin{small}%
 2010 %end{latexonly}
 2011 \begin{verbatim}
 2012 \item[\gn{french.perl}] adds \Perl{} code to be compatible with the ...
 2013 \item[\gn{\textsl  {ftp}}] `File Transfer Protocols', network ...
 2014 \item[\gn{german.perl}] adds \Perl{} code to be compatible with the ...
 2015 ...
 2016 \end{verbatim}
 2017 %begin{latexonly}
 2018 \end{small}%
 2019 %end{latexonly}
 2020 %
 2021 For the \LaTeX{} version the \verb|\item[\gn{...}]| is only used for pattern-matching, 
 2022 to find the correct data entry.
 2023 All typesetting is controlled from within \fn{manual.gls}.
 2024 
 2025 However the \texttt{HTML} version requires the following definition:
 2026 %
 2027 %begin{latexonly}
 2028 \begin{small}%
 2029 %end{latexonly}
 2030 \begin{verbatim}
 2031 \newcommand{\gn}[1]{\texttt{#1}\label{GGG#1}\htmlref{\^}{III#1}}%  
 2032 \end{verbatim}
 2033 %begin{latexonly}
 2034 \end{small}%
 2035 %end{latexonly}
 2036 %
 2037 which establishes the hyperlink to the Index, marked by `\verb|^|', 
 2038 and provides the \Lc{label} to create the target in the Glossary 
 2039 for any \verb|\glossary{...}| command having the corresponding argument.%
 2040 \end{itemize}