1LaTeX2HTML(1) Debian GNU/Linux manual LaTeX2HTML(1)
2
6 latex2html - translate LaTeX files to HTML (HyperText Markup Language)
7
9 latex2html [options] [target [target ...]]
10
12 This manual page explains the LaTeX2HTML utility, which is a Perl pro‐
13 gram that translates LaTeX document into HTML format. For each source
14 file given as an argument the translator will create a directory con‐
15 taining the corresponding HTML files. For details and examples, please
16 consult the online html documentation, a copy of which should be avail‐
17 able in /usr/share/doc/latex2html/manual.ps.gz or
18 /usr/share/doc/latex2html/html/
19
21 This documetation has been derived from the TeX manual, and may not be
22 uptodate. Please refer to the online manual for authoritative documen‐
23 tation.
24
26 -t <top-page-title>
27 Same as setting: $TITLE = <top-page-title> ; Name the document
28 using this title.
29 -short_extn
31 Same as setting: $SHORTEXTN = 1; Use a filename prefix of .htm
32 for the produced HTML files. This is particularly useful for
33 creating pages to be stored on CD-ROM or other media, to be used
34 with operating systems that require a 3-character extension.
35 -long_titles <num>
37 Same as setting: $LONG_TITLES = <num>; Instead of the standard
38 names: node1.html, node2.html,... the filenames for each HTML
39 page are constructed from the first <num> words of the section
40 heading for that page, separated by the `_' character. Commas
41 and common short words (a an to by of and for the) are omitted
42 from both title and word-count. Warning: Use this switch with
43 great caution. Currently there are no checks for uniqueness of
44 names or overall length. Very long names can easily result from
45 using this feature.
46 -custom_titles
48 Same as setting: $CUSTOM_TITLES = 1; Instead of the standard
49 names: node1.html, node2.html, ... the filenames for each HTML
50 page are constructed using a Perl subroutine named cus‐
51 tom_title_hook . The user may define his/her own version of this
52 subroutine, within a .latex2html-init file say, to override the
53 default (which uses the standard names). This subroutine takes
54 the section-heading as a parameter and must return the required
55 name, or the empty string (default).
56 -dir <output-directory>
58 Same as setting: $DESTDIR = <output-directory> ; Redirect the
59 output to the specified directory. The default behaviour is to
60 create (or reuse) a directory having the same name as the prefix
61 of the document being processed.
62 -no_subdir
64 Same as setting: $NO_SUBDIR = 1; Place the generated HTML files
65 into the current directory. This overrides any $DESTDIR setting.
66 -prefix <filename-prefix>
68 Same as setting: $PREFIX = <filename-prefix> ; The <filename-
69 prefix> will be prepended to all .gif, .pl and .html files pro‐
70 duced, except for the top-level .html file; it may include a
71 (relative) directory path. This will enable multiple products of
72 LaTeX2HTML to peacefully coexist in the same directory. However,
73 do not attempt to simultaneously run multiple instances of
74 LaTeX2HTML using the same output directory, else various tempo‐
75 rary files will overwrite each other.
76 -auto_prefix
78 Same as setting: $AUTO_PREFIX = 1; Constructs the prefix as
79 `<title>-' to be prepended to all the files produced, where
80 <title> is the name of the LaTeX file being processed. (Note
81 the `-' in this prefix.) This overrides any $PREFIX setting.
82 -no_auto_link
84 Same as setting: $NO_AUTO_LINK = 1; If $NO_AUTO_LINK is empty
85 and variables $LINKPOINT and $LINKNAME are defined appropriately
86 (as is the default in the latex2html.config file), then a hard
87 link to the main HTML page is produced, using the name supplied
88 in $LINKNAME. Typically this is index.html; on many systems a
89 file of this name will be used, if it exists, when a browser
90 tries to view a URL which points to a directory. On other sys‐
91 tems a different value for $LINKNAME may be appropriate. Typi‐
92 cally $LINKPOINT has value $FILE.html, but this may also be
93 changed to match whichever HTML page is to become the target of
94 the automatic link. Use of the -no_auto_link switch cancels
95 this automatic linking facility, when not required for a partic‐
96 ular document.
97 -split <num>
99 Same as setting: $MAX_SPLIT_DEPTH = <num>; (default is 8) Stop
100 splitting sections into separate files at this depth. Specifying
101 -split 0 will put the entire document into a single HTML file.
102 See below for the different levels of sectioning. Also see the
103 next item for how to set a ``relative'' depth for splitting.
104 -split +<num>
106 Same as setting: $MAX_SPLIT_DEPTH = -<num>; (default is 8) The
107 level at which to stop splitting sections is calculated ``rela‐
108 tive to'' the shallowest level of sectioning that occurs within
109 the document. For example, if the document contains \section
110 commands, but no \part or \chapter commands, then -split +1 will
111 cause splitting at each \section but not at any deeper level;
112 whereas -split +2 or -split +3 also split down to \subsection
113 and \subsubsection commands respectively. Specifying -split +0
114 puts the entire document into a single HTML file.
115 -link <num>
117 Same as setting: $MAX_LINK_DEPTH = <num>; (default is 4) For
118 each node, create links to child nodes down to this much deeper
119 than the node's sectioning-level. Specifying -link 0 will show
120 no links to child nodes from that page, -link 1 will show only
121 the immediate descendents, etc. A value at least as big as that
122 of the -split <num> depth will produce a mini table-of-contents
123 (when not empty) on each page, for the tree structure rooted at
124 that node. When the page has a sectioning-level less than the
125 -split depth, so that the a mini table-of-contents has links to
126 other HTML pages, this table is located at the bottom of the
127 page, unless placed elsewhere using the \tableofchildlinks com‐
128 mand. On pages having a sectioning-level just less than the
129 -split depth the mini table-of-contents contains links to sub‐
130 sections etc. occurring on the same HTML page. Now the table is
131 located at the top of this page, unless placed elsewhere using
132 the \tableofchildlinks command.
133 -toc_depth <num>
135 Same as setting: $TOC_DEPTH = <num>; (default is 4) Sectioning
136 levels down to <num> are to be included within the Table-of-Con‐
137 tents tree.
138 -toc_stars
140 Same as setting: $TOC_STARS = 1; Sections created using the
141 starred-form of sectioning commands are included within the Ta‐
142 ble-of-Contents. As with LaTeX, normally such sections are not
143 listed.
144 -show_section_numbers
146 Same as setting: $SHOW_SECTION_NUMBERS = 1; Show section num‐
147 bers. By default section numbers are not shown, so as to encour‐
148 age the use of particular sections as stand-alone documents. In
149 order to be shown, section titles must be unique and must not
150 contain inlined graphics.
151 -unsegment
153 Same as setting: $UNSEGMENT = 1; Treat a segmented document (see
154 the section about document segmentation) like it were not seg‐
155 mented. This will cause the translator to concatenate all seg‐
156 ments and process them as a whole. You might find this useful to
157 check a segmented document for consistency. For all documents
158 the sectioning levels referred to above are:
159 0 document
160 1 part
161 2 chapter
162 3 section
163 4 subsection
164 5 subsubsection
165 6 paragraph
166 7 subparagraph
167 8 subsubparagraph
168 These levels apply even when the document contains no sectioning for
170 the shallower levels; e.g. no \part or \chapter commands is most com‐
171 mon, especially when using LaTeX's article document-class.
172
174 The switches described here govern the type of HTML code that can be
175 generated, and how to choose between the available options when there
176 are alternative strategies for implementing portions of LaTeX code.
177 -html_version (2.0|3.0|3.2)[,(math|i18n|table)]*
179 Same as setting: $HTML_VERSION = ... ; This specifies both the
180 HTML version to generate, and any extra (non-standard) HTML fea‐
181 tures that may be required. The version number corresponds to a
182 published DTD for an HTML standard (although 3.0 was never
183 accepted and subsequently withdrawn). A corresponding Perl file
184 in the versions/ subdirectory is loaded; these files are named
185 `html<num>.pl'. Following the version number, a comma-separated
186 list of extensions can be given. Each corresponds to a file
187 `<name>.pl' also located in the versions/ subdirectory. When
188 such a file is loaded the resulting HTML code can no longer be
189 expected to validate with the specified DTD. An exception is
190 math when the -no_math switch is also used, which should still
191 validate. Currently, versions 2.0, 3.2 and 4.0 are available.
192 (and also 2.1, 2.2, 3.0 and 3.1, for hoistorical reasons). The
193 extensions i18n, tables, math correspond roughly to what used to
194 be called versions `2.1', `2.2', `3.1' respectively, in releases
195 of LaTeX2HTML up to 1996. Now these extensions can be loaded
196 with any of `2.0', `3.2' or `4.0' as the specified standard.
197 The default version is usually set to be `3.2', within
198 latex2html.config.
199 -no_tex_defs
201 Same as setting: $TEXDEFS = 0; (default is 1) When $TEXDEFS is
202 set (default) the file texdefs.perl will be read. This provides
203 code to allow common TEX commands like \def, \newbox, \newdimen
204 and others, to be recognised, especially within the document
205 preamble. In the case of \def, the definition may even be fully
206 interpreted, but this requires the pattern-matching to be not
207 too complicated. If $TEXDEFS is `0' or empty, then texdefs.perl
208 will not be loaded; the translator will make no attempt to
209 interpret any raw TEX commands. This feature is intended to
210 enable sophisticated authors the ability to insert arbitrary TEX
211 commands in environments that are destined to be processed by
212 LaTeX anyway; e.g. figures, theorems, pictures, etc. However
213 this should rarely be needed, as now there is better support for
214 these types of environment. There are now other methods to spec‐
215 ify which chunks of code are to be passed to LaTeX for explicit
216 image-generation; see the discussion of the makeimage environ‐
217 ment.
218 -external_file <filename>
220 Same as setting: $EXTERNAL_FILE = <filename> ; Specifies the
221 prefix of the .aux file that this document should read. The
222 .aux extension will be appended to this prefix to get the com‐
223 plete filename, with directory path if needed. This file could
224 contain necessary information regarding citations, figure, table
225 and section numbers from LaTeX and perhaps other information
226 also. Use of this switch is vital for document segments, pro‐
227 cessed separately and linked to appear as if generated from a
228 single LaTeX document.
229 -font_size <size>
231 Same as setting: $FONT_SIZE = <size> ; This option provides bet‐
232 ter control over the font size of environments made into images
233 using LaTeX. <size> must be one of the font sizes that LaTeX
234 recognizes; i.e. `10pt', `11pt', `12pt', etc. Default is `10pt',
235 or whatever option may have been specified on the \documentclass
236 or \documentstyle line. Whatever size is selected, it will be
237 magnified by the installation variables $MATH_SCALE_FACTOR,
238 $FIGURE_SCALE_FACTOR and $DISP_SCALE_FACTOR as appropriate.
239 Note: This switch provides no control over the size of text on
240 the HTML pages. Such control is subject entirely to the user's
241 choices of settings for the browser windows.
242 -scalable_fonts
244 Same as setting: $SCALABLE_FONTS = 1; This is used when scalable
245 fonts, such as PostScript versions of the TEX fonts, are avail‐
246 able for image-generation. It has the effect of setting
247 $PK_GENERATION to `1', and $DVIPS_MODE to be empty, overriding
248 any previous settings for these variables.
249 -no_math
251 Same as setting: $NO_SIMPLE_MATH = 1; Ordinarily simple mathe‐
252 matical expressions are set using the ordinary text font, but
253 italiced. When part of the expression can not be represented
254 this way, an image is made of the whole formula. This is called
255 ``simple math''. When $NO_SIMPLE_MATH is set, then all mathemat‐
256 ics is made into images, whether simple or not. However, if the
257 math extension is loaded, using the -html_version switch
258 described earlier, then specifying -no_math produces a quite
259 different effect. Now it is the special <MATH> tags and entities
260 which are cancelled. In their place a sophisticated scheme for
261 parsing mathematical expressions is used. Images are made of
262 those sub-parts of a formula which cannot be adequately
263 expressed using (italiced) text characters and <SUB> and <SUP>
264 tags. See the subsection on mathematics for more details.
265 -local_icons
267 Same as setting: $LOCAL_ICONS = 1; A copy of each of the icons
268 actually used within the document is placed in the directory
269 along with the HTML files and generated images. This allows the
270 whole document to be fully self-contained, within this direc‐
271 tory; otherwise the icons must be retrieved from a (perhaps
272 remote) server. The icons are normally copied from a subdirec‐
273 tory of the
274 $LATEX2HTMLDIR,
276 set within latex2html.config. An alternative set of icons can
277 be used by specifying a (relative) directory path in $ALTERNA‐
278 TIVE_ICONS to where the customised images can be found.
279 -init_file <file>
281 Load the specified initialisation file. This Perl file will be
282 loaded after loading $HOME/.latex2html-init, or .latex2html-init
283 in the local directory, if either file exists. It is read at the
284 time the switch is processed, so the contents of the file may
285 change any of the values of any of the variables that were pre‐
286 viously established, as well as any default options. More than
287 one initialisation file can be read in this way.
288 [change_begin]98.1
289 -no_fork
291 Same as setting: $NOFORK = 1; When set this disables a feature
292 in the early part of the processing whereby some memory-inten‐
293 sive operations are performed by `forked' child processes. Some
294 single-task operating systems, such as DOS, do not support this
295 feature. Having $NOFORK set then ensures that unnecessary file-
296 handles that are needed with the forked processes, are not con‐
297 sumed unnecessarily, perhaps resulting in a fatal Perl error.
298 -iso_language <type>
300 This enables you to specify a different language type than 'EN'
301 to be used in the DTD entries of the HTML document, e.g.
302 'EN.US'. [change_end] 98.1
303 -short_index
305 Same as setting: $SHORT_INDEX = 1; Creates shorter Index list‐
306 ings, using codified links; this is fully compatible with the
307 makeidx package.
308 -no_footnode
310 Same as setting: $NO_FOOTNODE = 1; Suppresses use of a separate
311 file for footnotes; instead these are placed at the bottom of
312 the HTML pages where the references occur. When this option is
313 used, it is frequently desirable to change the style of the
314 marker used to indicate the presence of a footnote. This is done
315 as in LaTeX, using code such as follows. \renewcommand{\the‐
316 footnote}{\arabic{footnote}} All the styles \arabic, \alph,
317 \roman, \Alph and \Roman are available. [change_begin]98.1
318 -numbered_footnotes
320 Same as setting: $NUMBERED_FOOTNOTES = 1; If this is set you
321 will get every footnote applied with a subsequent number, to
322 ease readability. [change_end] 98.1
323 -address <author-address>
325 Same as setting: $ADDRESS = <author-address> ; Sign each page
326 with this address. See latex2html.config for an example using
327 Perl code to automatically include the date. A user-defined
328 Perl subroutine called &custom_address can be used instead, if
329 defined; it takes the value of $ADDRESS as a parameter, which
330 may be used or ignored as desired. At the time when this subrou‐
331 tine will be called, variables named $depth, $title, $file hold
332 the sectioning-level, title and filename of the HTML page being
333 produced; $FILE holds the name of the filename for the title-
334 page of the whole document.
335 -info <string>
337 Same as setting: $INFO = <string> ; Generate a new section
338 ``About this document'' containing information about the docu‐
339 ment being translated. The default is to generate such a section
340 with information on the original document, the date, the user
341 and the translator. An empty string (or the value `0') disables
342 the creation of this extra section. If a non-empty string is
343 given, it will be placed as the contents of the ``About this
344 document'' page instead of the default information.
345
347 These switches affect whether images are created at all, whether old
348 images are reused on subsequent runs or new ones created afresh, and
349 whether anti-aliasing effects are used within the images themselves.
350 -ascii_mode
352 Same as setting: $ASCII_MODE = $EXTERNAL_IMAGES = 1; Use only
353 ASCII characters and do not include any images in the final out‐
354 put. With -ascii_mode the output of the translator can be used
355 on character-based browsers, such as lynx, which do not support
356 inlined images (via the <IMG> tag).
357 -nolatex
359 Same as setting: $NOLATEX = 1; Disable the mechanism for passing
360 unknown environments to LaTeX for processing. This can be
361 thought of as ``draft mode'' which allows faster translation of
362 the basic document structure and text, without fancy figures,
363 equations or tables. (This option has been superseded by the
364 -no_images option, see below.)
365 -external_images
367 Same as setting: $EXTERNAL_IMAGES = 1; Instead of including any
368 generated images inside the document, leave them outside the
369 document and provide hypertext links to them.
370 -ps_images
372 Same as setting: $PS_IMAGES = $EXTERNAL_IMAGES = 1; Use links to
373 external PostScript files rather than inlined images in the cho‐
374 sen graphics format.
375 -discard
377 Same as setting: $DISCARD_PS = 1; The temporary PostScript files
378 are discarded immediately after they have been used to create
379 the image in the desired graphics format.
380 -no_images
382 Same as setting: $NO_IMAGES = 1; Do not attempt to produce any
383 inlined images. The missing images can be generated ``off-line''
384 by restarting LaTeX2HTML with the option -images_only .
385 -images_only
387 Same as setting: $IMAGES_ONLY = 1; Try to convert any inlined
388 images that were left over from previous runs of LaTeX2HTML.
389 -reuse <reuse_option>
391 Same as setting: $REUSE = <reuse_option>; This switch specifies
392 the extent to which image files are to be shared or recycled.
393 There are three valid options: [*] 0 Do not ever share or recy‐
394 cle image files. This choice also invokes an interactive ses‐
395 sion prompting the user about what to do about a pre-existing
396 HTML directory, if it exists. [*] 1 Recycle image files from a
397 previous run if they are available, but do not share identical
398 images that must be created in this run. [*] 2 Recycle image
399 files from a previous run and share identical images from this
400 run. This is the default. A later section provides additional
401 information about image-reuse.
402 -no_reuse
404 Same as setting: $REUSE = 0; Do not share or recycle images gen‐
405 erated during previous translations. This is equivalent to -re‐
406 use 0 . (This will enable the initial interactive session during
407 which the user is asked whether to reuse the old directory,
408 delete its contents or quit.)
409 -antialias
411 Same as setting: $ANTI_ALIAS = 1; (Default is 0.) Generated
412 images of figure environments and external PostScript files
413 should use anti-aliasing. By default anti-aliasing is not used
414 with these images, since this may interfere with the contents of
415 the images themselves.
416 -antialias_text
418 Same as setting: $ANTI_ALIAS_TEXT = 1; (Default is 1.) Gener‐
419 ated images of typeset material such as text, mathematical for‐
420 mulas, tables and the content of makeimage environments, should
421 use anti-aliasing effects. The default is normally to use anti-
422 aliasing for text, since the resulting images are much clearer
423 on-screen. However the default may have been changed locally.
424 -no_antialias
426 Same as setting: $ANTI_ALIAS = 0; (Default is 0.) Generated
427 images of figure environments and external PostScript files
428 should not use anti-aliasing with images, though the local
429 default may have been changed to use it.
430 -no_antialias_text
432 Same as setting: $ANTI_ALIAS_TEXT = 0; (Default is 1.) Gener‐
433 ated images of typeset material should not use anti-aliasing
434 effects. Although on-screen images of text are definitely
435 improved using anti-aliasing, printed images can be badly
436 blurred, even at 300dpi. Higher resolution printers do a much
437 better job with the resulting grey-scale images.
438 [change_begin]98.1
439 -white Same as setting: $WHITE_BACKGROUND = 1; (Default is 1.) Ensures
441 that images of figure environments have a white background.
442 Otherwise transparency effects may not work correctly.
443 -no_white
445 Same as setting: $WHITE_BACKGROUND = ''; (Default is 1.) Can‐
446 cels the requirement that figure environments have a white back‐
447 ground.
448 -ldump Same as setting: $LATEX_DUMP = 1; (Default is 0.) Use this if
450 you want to speed up image processing during the 2nd and subse‐
451 quent runs of LaTeX2HTML on the same document. The translator
452 now produces a LaTeX format-dump of the preamble to images.tex
453 which is used on subsequent runs. This significantly reduces the
454 startup time when LaTeX reads the images.tex file for image-gen‐
455 eration. This process actually consumes additional time on the
456 first run, since LaTeX is called twice -- once to create the
457 format-dump, then again to load and use it. The pay-off comes
458 with the faster loading on subsequent runs. Approximately 1 Meg
459 of disk space is consumed by the dump file. [change_end] 98.1
460
462 The following switches govern whether to include one or more navigation
463 panels on each HTML page, also which buttons to include within such a
464 panel.
465 -no_navigation
467 Same as setting: $NO_NAVIGATION = 1; Disable the mechanism for
468 putting navigation links in each page. This overrides any set‐
469 tings of the $TOP_NAVIGATION, $BOTTOM_NAVIGATION and $AUTO_NAVI‐
470 GATION variables.
471 -top_navigation
473 Same as setting: $TOP_NAVIGATION = 1; Put navigation links at
474 the top of each page.
475 -bottom_navigation
477 Same as setting: $BOTTOM_NAVIGATION = 1; Put navigation links at
478 the bottom of each page as well as the top.
479 -auto_navigation
481 Same as setting: $AUTO_NAVIGATION = 1; Put navigation links at
482 the top of each page. Also put one at the bottom of the page, if
483 the page exceeds $WORDS_IN_PAGE number of words (default = 450).
484 -next_page_in_navigation
486 Same as setting: $NEXT_PAGE_IN_NAVIGATION = 1; Put a link to the
487 next logical page in the navigation panel.
488 -previous_page_in_navigation
490 Same as setting: $PREVIOUS_PAGE_IN_NAVIGATION = 1; Put a link to
491 the previous logical page in the navigation panel.
492 -contents_in_navigation
494 Same as setting: $CONTENTS_IN_NAVIGATION = 1; Put a link to the
495 table-of-contents in the navigation panel if there is one.
496 -index_in_navigation
498 Same as setting: $INDEX_IN_NAVIGATION = 1; Put a link to the
499 index-page in the navigation panel if there is an index.
500
502 When processing a single stand-alone document, the switches described
503 in this section should not be needed at all, since the automatically
504 generated navigation panels, described on the previous page should gen‐
505 erate all the required navigation links. However if a document is to be
506 regarded as part of a much larger document, then links from its first
507 and final pages, to locations in other parts of the larger (virtual)
508 document, need to be provided explicitly for some of the buttons in the
509 navigation panel. The following switches allow for such links to other
510 documents, by providing the title and URL for navigation panel hyper‐
511 links. In particular, the ``Document Segmentation'' feature necessarily
512 makes great use of these switches. It is usual for the text and targets
513 of these navigation hyperlinks to be recorded in a Makefile, to avoid
514 tedious typing of long command-lines having many switches.
515 -up_url <URL>
517 Same as setting: $EXTERNAL_UP_LINK = <URL> ; Specifies a univer‐
518 sal resource locator (URL) to associate with the ``UP'' button
519 in the navigation panel(s).
520 -up_title <string>
522 Same as setting: $EXTERNAL_UP_TITLE = <string> ; Specifies a
523 title associated with this URL.
524 -prev_url <URL>
526 Same as setting: $EXTERNAL_PREV_LINK = <URL> ; Specifies a URL
527 to associate with the ``PREVIOUS'' button in the navigation
528 panel(s).
529 -prev_title <string>
531 Same as setting: $EXTERNAL_PREV_TITLE = <string> ; Specifies a
532 title associated with this URL.
533 -down_url <URL>
535 Same as setting: $EXTERNAL_DOWN_LINK = <URL> ; Specifies a URL
536 for the ``NEXT'' button in the navigation panel(s).
537 -down_title <string>
539 Same as setting: $EXTERNAL_DOWN_TITLE = <string> ; Specifies a
540 title associated with this URL.
541 -contents <URL>
543 Same as setting: $EXTERNAL_CONTENTS = <URL> ; Specifies a URL
544 for the ``CONTENTS'' button, for document segments that would
545 not otherwise have one.
546 -index <URL>
548 Same as setting: $EXTERNAL_INDEX = <URL> ; Specifies a URL for
549 the ``INDEX'' button, for document segments that otherwise would
550 not have an index.
551 -biblio <URL>
553 Same as setting: $EXTERNAL_BIBLIO = <URL> ; Specifies the URL
554 for the bibliography page to be used, when not explicitly part
555 of the document itself. Warning: On some systems it is diffi‐
556 cult to give text-strings <string> containing space characters,
557 on the command-line or via a Makefile. One way to overcome this
558 is to use the corresponding variable. Another way is to replace
559 the spaces with underscores (_).
560
562 The first two of the following switches are self-explanatory. When
563 problems arise in processing a document, the switches -debug and -ver‐
564 bosity will each cause LaTeX2HTML to generate more output to the
565 screen. These extra messages should help to locate the cause of the
566 problem.
567 -tmp <path>
569 Define a temporary directory to use for image generation. If
570 <path> is 0, the standard temporary directory /tmp is used.
571 -h(elp)
573 Print out the list of all command-line options.
574 -v Print the current version of LaTeX2HTML.
576 -debug Same as setting: $DEBUG = 1; Run in debug-mode, displaying mes‐
578 sages and/or diagnostic information about files read, and utili‐
579 ties called by LaTeX2HTML. Shows any messages produced by these
580 calls. More extensive diagnostics, from the Perl debugger, can
581 be obtained by appending the string `-w-' to the 1st line of the
582 latex2html (and other) Perl script(s).
583 -verbosity <num>
585 Same as setting: $VERBOSITY = <num>; Display messages revealing
586 certain aspects of the processing performed by LaTeX2HTML on the
587 provided input file(s). The <num> parameter can be an integer in
588 the range 0 to 8. Each higher value adds to the messages pro‐
589 duced.
590 0. No special tracing; as for versions of LaTeX2HTML prior to
592 V97.1.
593 1. (This is the default.) Show section-headings and the correspond‐
595 ing HTML file names, and indicators that major stages in the
596 processing have been completed.
597 2. Print environment names and identifier numbers, and new theorem-
599 types. Show warnings as they occur, and indicators for more
600 stages of processing. Print names of files for storing auxiliary
601 data arrays.
602 3. Print command names as they are encountered and processed; also
604 any unknown commands encountered while pre-processing. Show
605 names of new commands, environments, theorems, counters and
606 counter-dependencies, for each document partition.
607 4. Indicate command-substitution the pre-process of math-environ‐
609 ments. Print the contents of unknown environments for processing
610 in LaTeX, both before and after reverting to LaTeX source. Show
611 all operations affecting the values of counters. Also show
612 links, labels and sectioning keys, at the stages of processing.
613 5. Detail the processing in the document preamble. Show substitu‐
615 tions of new environments. Show the contents of all recognised
616 environments, both before and after processing. Show the
617 cached/encoded information for the image keys, allowing two
618 images to be tested for equality.
619 6. Show replacements of new commands, accents and wrapped commands.
621 7. Trace the processing of commands in math mode; both before and
623 after.
624 8. Trace the processing of all commands, both before and after.
626 The command-line option sets an initial value only. During pro‐
627 cessing the value of $VERBOSITY can be set dynamically using the
628 \htmltracing{...} command, whose argument is the desired value,
629 or by using the more general \HTMLset command as follows:
630 \HTMLset{VERBOSITY}{<num>}.
631
633 The configuration variables described here do not warrant having a com‐
634 mand-line switch to assign values. Either they represent aspects of
635 LaTeX2HTML that are specific to the local site, or they govern proper‐
636 ties that should apply to all documents, rather than something that
637 typically would change for the different documents within a particular
638 sub-directory. Normally these variables have their value set within
639 the latex2html.config file. In the following listing the defaults are
640 shown, as the lines of Perl code used to establish these values. If a
641 different value is required, then these can be assigned from a local
642 .latex2html-init initialisation file, without affecting the defaults
643 for other users, or documents processed from other directories.
644 $dd holds the string to be used in file-names to delimit directo‐
646 ries; it is set internally to `/', unless the variable has
647 already been given a value within latex2html.config . Note:
648 This value cannot be set within a .latex2html-init initialisa‐
649 tion file, since its value needs to be known in order to find
650 such a file.
651 $LATEX2HTMLDIR
653 Read by the install-test script from latex2html.config, its
654 value is inserted into the latex2html Perl script as part of the
655 installation process.
656 $LATEX2HTMLSTYLES = $LATEX2HTMLDIR/styles ;
658 Read from the latex2html.config file by install-test, its value
659 is checked to locate the styles/ directory.
660 $LATEX2HTMLVERSIONS = $LATEX2HTMLDIR/versions ;
662 The value of this variable should be set within latex2html.con‐
663 fig to specify the directory path where the version and exten‐
664 sion files can be found.
665 $ALTERNATIVE_ICONS = '';
667 This may contain the (relative) directory path to a set of cus‐
668 tomised icons to be used in conjunction with the -local_icons
669 switch.
670 $TEXEXPAND = $LATEX2HTMLDIR/texexpand ;
672 Read by the install-test Perl script from latex2html.config, its
673 value is used to locate the texexpand Perl script.
674 $PSTOIMG = $LATEX2HTMLDIR/pstoimg ;
676 Read by the install-test Perl script from latex2html.config, its
677 value is used to locate the pstoimg Perl script.
678 $IMAGE_TYPE = '<image-type>';
680 Set in latex2html.config, the currently supported <image-type>s
681 are: gif and png.
682 $DVIPS = 'dvips';
684 Read from latex2html.config by install-test, its value is
685 checked to locate the dvips program or script. There could be
686 several reasons to change the value here: o add a switch
687 -P<printer> to load a specific configuration-file; e.g. to use a
688 specific set of PostScript fonts, for improved image-generation.
689 o to prepend a path to a different version of dvips than nor‐
690 mally available as the system default (e.g. the printing
691 requirements are different). o to append debugging switches, in
692 case of poor quality images; one can see which paths are being
693 searched for fonts and other resources. o to prepend commands
694 for setting path variables that dvips may need in order to
695 locate fonts or other resources. If automatic generation of
696 fonts is required, using Metafont, the following configuration
697 variables are important.
698 $PK_GENERATION = 1;
700 This variable must be set, to initiate font-generation;
701 otherwise fonts will be scaled from existing resources on
702 the local system. In particular this variable must not
703 be set, if one wishes to use PostScript fonts or other
704 scalable font resources (see the -scalable_fonts switch).
705 $DVIPS_MODE = 'toshiba';
707 The mode given here must be available in the modes.mf
708 file, located with the Metafont resource files, perhaps
709 in the misc/ subdirectory.
710 $METAFONT_DPI = 180;
712 The required resolution, in dots-per-inch, should be
713 listed specifically within the MakeTeXPK script, called
714 by dvips to invoke Metafont with the correct parameters
715 for the required fonts.
716 $LATEX = 'latex';
718 Read from latex2html.config by install-test, its value is
719 checked to locate the latex program or script. If LaTeX is hav‐
720 ing trouble finding style-files and/or packages, then the
721 default command can be prepended with other commands to set
722 environment variables intended to resolve these difficulties;
723 e.g. $LATEX = 'setenv TEXINPUTS <path to search> ; latex' .
724 There are several variables to help control exactly which files
725 are read by LaTeX2HTML and by LaTeX when processing images:
726 $TEXINPUTS
728 This is normally set from the environment variable of the
729 same name. If difficulties occur so that styles and pack‐
730 ages are not being found, then extra paths can be speci‐
731 fied here, to resolve these difficulties.
732 $DONT_INCLUDE
734 This provides a list of filenames and extensions to not
735 include, even if requested to do so by an \input or
736 \include command. (Consult latex2html.config for the
737 default list.)
738 $DO_INCLUDE = '';
740 List of exceptions within the $DONT_INCLUDE list. These
741 files are to be read if requested by an \input or
742 \include command.
743 $ICONSERVER = '<URL>';
745 This is used to specify a URL to find the standard icons, as
746 used for the navigation buttons. Names for the specific images
747 size, as well as size information, can be found in
748 latex2html.config. The icons themselves can be replaced by cus‐
749 tomised versions, provided this information is correctly updated
750 and the location of the customised images specified as the value
751 of $ICONSERVER. When the -local_icons switch is used, so that a
752 copy of the icons is placed with the HTML files and other gener‐
753 ated images, the value of $ICONSERVER is not needed within the
754 HTML files themselves. However it is needed to find the original
755 icons to be copied to the local directory.
756 $NAV_BORDER = <num>;
758 The value given here results in a border, measured in points,
759 around each icon. A value of `0' is common, to maintain strict
760 alignment of inactive and active buttons in the control panels.
761 $LINKNAME = '"index.$EXTN"';
763 This is used when the $NO_AUTO_LINK variable is empty, to allow
764 a URL to the working directory to be sufficient to reach the
765 main page of the completed document. It specifies the name of
766 the HTML file which will be automatically linked to the direc‐
767 tory name. The value of $EXTN is .html unless $SHORTEXTN is
768 set, in which case it is .htm .
769 $LINKPOINT = '"$FILE$EXTN"';
771 This specifies the name of the HTML file to be duplicated, or
772 symbolically linked, with the name specified in $LINKNAME. At
773 the appropriate time the value of $FILE is the document name,
774 which usually coincides with the name of the working directory.
775 $CHARSET = 'iso_8859_1';
777 This specifies the character set used within the HTML pages pro‐
778 duced by LaTeX2HTML. If no value is set in a configuration or
779 initialisation file, the default value will be assumed. The low‐
780 ercase form $charset is also recognised, but this is overridden
781 by the uppercase form.
782 $ACCENT_IMAGES = 'large';
784 Accented characters that are not part of the ISO-Latin fonts can
785 be generated by making an image using LaTeX. This variable con‐
786 tains a (comma-separated) list of LaTeX commands for setting the
787 style to be used when these images are made. If the value of
788 this variable is empty then the accent is simply ignored, using
789 an un-accented font character (not an image) instead. Within
790 the color.perl package, the following variables are used to
791 identify the names of files containing specifications for named
792 colors. Files having these names are provided, in the
793 $LATEX2HTMLSTYLES directory, but they could be moved elsewhere,
794 or replaced by alternative files having different names. In
795 such a case the values of these variables should be altered
796 accordingly.
797 $RGBCOLORFILE = 'rgb.txt';
798 $CRAYOLAFILE = 'crayola.txt'; The following variables may well
799 be altered from the system defaults, but this is best done using
800 a local .latex2html-init initialisation file, for overall con‐
801 sistency of style within documents located at the same site, or
802 sites in close proximity.
803 $default_language = 'english';
805 This establishes which language code is to be placed within the
806 <!DOCTYPE ... > tag that may appear at the beginning of the HTML
807 pages produced. Loading a package for an alternative language
808 can be expected to change the value of this variable. See also
809 the $TITLES_LANGUAGE variable, described next.
810 $TITLES_LANGUAGE = 'english';
812 This variable is used to specify the actual strings used for
813 standard document sections, such as ``Contents'', ``Refer‐
814 ences'', ``Table of Contents'', etc. Support for French and
815 German titles is available in corresponding packages. Loading
816 such a package will normally alter the value of this variable,
817 as well as the $default_language variable described above.
818 $WORDS_IN_NAVIGATION_PANEL_TITLES = 4;
820 Specifies how many words to use from section titles, within the
821 textual hyperlinks which accompany the navigation buttons.
822 $WORDS_IN_PAGE = 450;
824 Specifies the minimum page length required before a navigation
825 panel is placed at the bottom of a page, when the $AUTO_NAVIGA‐
826 TION variable is set.
827 $CHILDLINE = <BR><HR>;
829 This gives the HTML code to be placed between the child-links
830 table and the ordinary contents of the page on which it occurs.
831 $NETSCAPE_HTML = 0;
833 When set, this variable specifies that HTML code may be present
834 which does not conform to any official standard. This restricts
835 the contents of any <!DOCTYPE ... > tag which may be placed at
836 the beginning of the HTML pages produced.
837 $BODYTEXT = '';
839 The value of this variable is used within the <BODY ... > tag;
840 e.g. to set text and/or background colors. It's value is over‐
841 ridden by the \bodytext command, and can be added-to or parts
842 changed using the \htmlbody command or \color and \pagecolor
843 from the color package.
844 $INTERLACE = 1;
846 When set, interlaced images should be produced. This requires
847 graphics utilities to be available to perform the interlacing
848 operation.
849 $TRANSPARENT_FIGURES = 1;
851 When set, the background of images should be made transparent;
852 otherwise it is white. This requires graphics utilities to be
853 available which can specify the color to be made transparent.
854 $FIGURE_SCALE_FACTOR = 1.6;
856 Scale factor applied to all images of figure and other environ‐
857 ments, when being made into an image. Note that this does not
858 apply to recognised mathematics environments, which instead use
859 the contents of $MATH_SCALE_FACTOR and $DISP_SCALE_FACTOR to
860 specify scaling.
861 $MATH_SCALE_FACTOR = 1.6;
863 Scale factor applied to all images of mathematics, both inline
864 and displayed. A value of 1.4 is a good alternative, with anti-
865 aliased images.
866 $DISP_SCALE_FACTOR = 1;
868 Extra scale factor applied to images of displayed math environ‐
869 ments. When set, this value multiplies $MATH_SCALE_FACTOR to
870 give the total scaling. A value of `1.2' is a good choice to
871 accompany $MATH_SCALE_FACTOR = 1.4;.
872 $EXTRA_IMAGE_SCALE
874 This may hold an extra scale factor that can be applied to all
875 generated images. When set, it specifies that a scaling of
876 $EXTRA_IMAGE_SCALE be applied when images are created, but to
877 have their height and width recorded as the un-scaled size. This
878 is to coax browsers into scaling the (usually larger) images to
879 fit the desired size; when printed a better quality can be
880 obtained. Values of `1.5' and `2' give good print quality at
881 600dpi.
882 $PAPERSIZE = 'a5';
884 Specifies the size of a page for typesetting figures or dis‐
885 played math, when an image is to be generated. This affects the
886 lengths of lines of text within images. Since images of text or
887 mathematics should use larger sizes than when printed, else
888 clarity is lost at screen resolutions, then a smaller paper-size
889 is generally advisable. This is especially so if both the
890 $MATH_SCALE_FACTOR and $DISP_SCALE_FACTOR scaling factors are
891 being used, else some images may become excessively large,
892 including a lot of blank space.
893 $LINE_WIDTH = 500;
895 Formerly specified the width of an image, when the contents were
896 to be right- or center-justified. (No longer used.)
897 The following variables are used to access the utilities required dur‐
899 ing image-generation. File and program locations on the local system
900 are established by the configure-pstoimg Perl script and stored within
901 $LATEX2HTMLDIR/local.pm as Perl code, to be read by pstoimg when
902 required. After running the configure-pstoimg Perl script it should
903 not be necessary to alter the values obtained. Those shown below are
904 what happens on the author's system; they are for illustration only and
905 do not represent default values.
906 $GS_LIB = '/usr/local/share/ghostscript/4.02';
908 $PNMCAT = '/usr/local/bin/pnmcat';
909 $PPMQUANT = '/usr/local/bin/ppmquant';
910 $PNMFLIP = '/usr/local/bin/pnmflip';
911 $PPMTOGIF = '/usr/local/bin/ppmtogif';
912 $HOWTO_TRANSPARENT_GIF = 'netpbm';
913 $GS_DEVICE = 'pnmraw';
914 $GS = '/usr/local/bin/gs';
915 $PNMFILE = '/usr/local/bin/pnmfile';
916 $HOWTO_INTERLACE_GIF = 'netpbm';
917 $PBMMAKE = '/usr/local/bin/pbmmake';
918 $PNMCROP = '/usr/local/bin/pnmcrop';
919 $TMP = '/usr/var/tmp'; The following variables are no longer needed,
920 having been replaced by the more specific information obtained using
921 the Perl script configure-pstoimg.
922 $USENETPBM = 1;
923 $PBMPLUSDIR = '/usr/local/bin';
924
926 latex(1)
927
929 Nikos Drakos, Computer Based Learning Unit, University of Leeds
930 <nikos@cbl.leeds.ac.uk>. Several people have contributed suggestions,
931 ideas, solutions, support and encouragement. The current maintainer is
932 Ross Moore. This manual page was written by Manoj Srivastava <sri‐
933 vasta@debian.org>, for the Debian GNU/Linux system, based on the LaTeX
934 documentation accompanying the program.
935Debian March 1 2000 LaTeX2HTML(1)