1LaTeX2HTML(1)               Debian GNU/Linux manual              LaTeX2HTML(1)
2
3
4

NAME

6       latex2html - translate LaTeX files to HTML (HyperText Markup Language)
7

SYNOPSIS

9       latex2html [options] [target [target ...]]
10

DESCRIPTION

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

CAVEAT

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

Options controlling Titles, File-Names and Sectioning

26       -t <top-page-title>
27              Same  as  setting: $TITLE = <top-page-title> ; Name the document
28              using this title.
29
30       -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
36       -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
47       -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
57       -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
63       -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
67       -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
77       -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
83       -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
98       -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
105       -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
116       -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
134       -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
139       -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
145       -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
152       -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
169       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

Options controlling Extensions and Special Features

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
178       -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
200       -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
219       -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
230       -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
243       -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
250       -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
266       -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
275              $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
280       -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
290       -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
299       -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
304       -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
309       -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
319       -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
324       -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
336       -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

Switches controlling Image Generation

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
351       -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
358       -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
366       -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
371       -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
376       -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
381       -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
386       -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
390       -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
403       -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
410       -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
417       -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
425       -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
431       -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
440       -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
444       -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
449       -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

Switches controlling Navigation Panels

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
466       -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
472       -top_navigation
473              Same as setting: $TOP_NAVIGATION = 1; Put  navigation  links  at
474              the top of each page.
475
476       -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
480       -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
485       -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
489       -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
493       -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
497       -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

Switches for Linking to other documents

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
516       -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
521       -up_title <string>
522              Same as setting: $EXTERNAL_UP_TITLE =  <string>  ;  Specifies  a
523              title associated with this URL.
524
525       -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
530       -prev_title <string>
531              Same  as  setting: $EXTERNAL_PREV_TITLE = <string> ; Specifies a
532              title associated with this URL.
533
534       -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
538       -down_title <string>
539              Same  as  setting: $EXTERNAL_DOWN_TITLE = <string> ; Specifies a
540              title associated with this URL.
541
542       -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
547       -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
552       -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

Switches for Help and Tracing

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
568       -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
572       -h(elp)
573              Print out the list of all command-line options.
574
575       -v     Print the current version of LaTeX2HTML.
576
577       -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
584       -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
591       0.     No special tracing; as  for  versions  of  LaTeX2HTML  prior  to
592              V97.1.
593
594       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
598       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
603       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
608       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
614       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
620       6.     Show replacements of new commands, accents and wrapped commands.
621
622       7.     Trace  the  processing of commands in math mode; both before and
623              after.
624
625       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

Other Configuration Variables, without switches

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
645       $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
652       $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
657       $LATEX2HTMLSTYLES = $LATEX2HTMLDIR/styles ;
658              Read from the latex2html.config file by install-test, its  value
659              is checked to locate the styles/ directory.
660
661       $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
666       $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
671       $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
675       $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
679       $IMAGE_TYPE = '<image-type>';
680              Set  in latex2html.config, the currently supported <image-type>s
681              are: gif and png.
682
683       $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
699              $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
706              $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
711              $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
717       $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
727              $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
733              $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
739              $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
744       $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
757       $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
762       $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
770       $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
776       $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
783       $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
804       $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
811       $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
819       $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
823       $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
828       $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
832       $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
838       $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
845       $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
850       $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
855       $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
862       $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
867       $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
873       $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
883       $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
894       $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
898       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
907        $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

SEE ALSO

926       latex(1)
927

AUTHOR

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.
935
936
937
938Debian                           March 1 2000                    LaTeX2HTML(1)
Impressum