## "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}
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)
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}.
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
111 {http://www.w3.org/pub/WWW/TR/WD-math-970515})
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
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
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
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}%
708 \item \texttt{external}\\
709 will cause the image not to be inlined;
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.
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.
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 %% 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 %% 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 %% 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 %% 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
1230 \hyperref{variable}{variable (see section }{)}{cs_white}.
1231
1232
1233 \subsection{Document Classes and Options\label{sec:cls}}
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}
1243
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
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
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}}
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
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
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
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
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
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
1765 \item
1766 The top-most node is simply denoted \verb|^|'.
1767
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
1778
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}