latex2html



LaTeX2HTML(1)               Debian GNU/Linux manual              LaTeX2HTML(1)




NAME

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


SYNOPSIS

       latex2html [options] [target [target ...]]


DESCRIPTION

       This  manual page explains the LaTeX2HTML utility, which is a Perl pro-
       gram that translates LaTeX document into HTML format. For  each  source
       file  given  as an argument the translator will create a directory con-
       taining the corresponding HTML files. For details and examples,  please
       consult the online html documentation, a copy of which should be avail-
       able        in        /usr/share/doc/latex2html/manual.ps.gz         or
       /usr/share/doc/latex2html/html/


CAVEAT

       This  documetation has been derived from the TeX manual, and may not be
       uptodate. Please refer to the online manual for authoritative  documen-
       tation.


Options controlling Titles, File-Names and Sectioning

       -t <top-page-title>
              Same  as  setting: $TITLE = <top-page-title> ; Name the document
              using this title.

       -short_extn
              Same as setting: $SHORTEXTN = 1; Use a filename prefix  of  .htm
              for  the  produced  HTML  files. This is particularly useful for
              creating pages to be stored on CD-ROM or other media, to be used
              with operating systems that require a 3-character extension.

       -long_titles <num>
              Same  as  setting: $LONG_TITLES = <num>; Instead of the standard
              names: node1.html, node2.html,... the filenames  for  each  HTML
              page  are  constructed from the first <num> words of the section
              heading for that page, separated by the ‘_’  character.   Commas
              and  common  short words (a an to by of and for the) are omitted
              from both title and word-count.  Warning: Use this  switch  with
              great  caution.  Currently there are no checks for uniqueness of
              names or overall length. Very long names can easily result  from
              using this feature.

       -custom_titles
              Same  as  setting:  $CUSTOM_TITLES  = 1; Instead of the standard
              names: node1.html, node2.html, ... the filenames for  each  HTML
              page   are  constructed  using  a  Perl  subroutine  named  cus-
              tom_title_hook . The user may define his/her own version of this
              subroutine,  within a .latex2html-init file say, to override the
              default (which uses the standard names). This  subroutine  takes
              the  section-heading as a parameter and must return the required
              name, or the empty string (default).

       -dir <output-directory>
              Same as setting: $DESTDIR = <output-directory>  ;  Redirect  the
              output  to the specified directory.  The default behaviour is to
              create (or reuse) a directory having the same name as the prefix
              of the document being processed.

       -no_subdir
              Same  as setting: $NO_SUBDIR = 1; Place the generated HTML files
              into the current directory. This overrides any $DESTDIR setting.

       -prefix <filename-prefix>
              Same  as  setting:  $PREFIX = <filename-prefix> ; The <filename-
              prefix> will be prepended to all .gif, .pl and .html files  pro-
              duced,  except  for  the  top-level .html file; it may include a
              (relative) directory path. This will enable multiple products of
              LaTeX2HTML to peacefully coexist in the same directory. However,
              do not attempt  to  simultaneously  run  multiple  instances  of
              LaTeX2HTML  using the same output directory, else various tempo-
              rary files will overwrite each other.

       -auto_prefix
              Same as setting: $AUTO_PREFIX =  1;  Constructs  the  prefix  as
              ‘<title>-’  to  be  prepended  to  all the files produced, where
              <title> is the name of the LaTeX file  being  processed.   (Note
              the ‘-’ in this prefix.)  This overrides any $PREFIX setting.

       -no_auto_link
              Same  as  setting:  $NO_AUTO_LINK = 1; If $NO_AUTO_LINK is empty
              and variables $LINKPOINT and $LINKNAME are defined appropriately
              (as  is  the default in the latex2html.config file), then a hard
              link to the main HTML page is produced, using the name  supplied
              in  $LINKNAME.   Typically this is index.html; on many systems a
              file of this name will be used, if it  exists,  when  a  browser
              tries  to  view a URL which points to a directory. On other sys-
              tems a different value for $LINKNAME may be  appropriate.  Typi-
              cally  $LINKPOINT  has  value  $FILE.html,  but this may also be
              changed to match whichever HTML page is to become the target  of
              the  automatic  link.   Use  of the -no_auto_link switch cancels
              this automatic linking facility, when not required for a partic-
              ular document.

       -split <num>
              Same  as  setting: $MAX_SPLIT_DEPTH = <num>; (default is 8) Stop
              splitting sections into separate files at this depth. Specifying
              -split  0  will put the entire document into a single HTML file.
              See below for the different levels of sectioning. Also  see  the
              next item for how to set a ‘‘relative’’ depth for splitting.

       -split +<num>
              Same  as  setting: $MAX_SPLIT_DEPTH = -<num>; (default is 8) The
              level at which to stop splitting sections is calculated  ‘‘rela-
              tive  to’’ the shallowest level of sectioning that occurs within
              the document. For example, if  the  document  contains  \section
              commands, but no \part or \chapter commands, then -split +1 will
              cause splitting at each \section but not at  any  deeper  level;
              whereas  -split  +2  or -split +3 also split down to \subsection
              and \subsubsection commands respectively. Specifying  -split  +0
              puts the entire document into a single HTML file.

       -link <num>
              Same  as  setting:  $MAX_LINK_DEPTH  = <num>; (default is 4) For
              each node, create links to child nodes down to this much  deeper
              than  the node’s sectioning-level.  Specifying -link 0 will show
              no links to child nodes from that page, -link 1 will  show  only
              the immediate descendents, etc.  A value at least as big as that
              of the -split <num> depth will produce a mini  table-of-contents
              (when  not empty) on each page, for the tree structure rooted at
              that node.  When the page has a sectioning-level less  than  the
              -split  depth, so that the a mini table-of-contents has links to
              other HTML pages, this table is located at  the  bottom  of  the
              page,  unless placed elsewhere using the \tableofchildlinks com-
              mand.  On pages having a sectioning-level  just  less  than  the
              -split  depth  the mini table-of-contents contains links to sub-
              sections etc. occurring on the same HTML page. Now the table  is
              located  at  the top of this page, unless placed elsewhere using
              the \tableofchildlinks command.

       -toc_depth <num>
              Same as setting: $TOC_DEPTH = <num>; (default is  4)  Sectioning
              levels down to <num> are to be included within the Table-of-Con-
              tents tree.

       -toc_stars
              Same as setting: $TOC_STARS =  1;  Sections  created  using  the
              starred-form  of sectioning commands are included within the Ta-
              ble-of-Contents. As with LaTeX, normally such sections  are  not
              listed.

       -show_section_numbers
              Same  as  setting:  $SHOW_SECTION_NUMBERS = 1; Show section num-
              bers. By default section numbers are not shown, so as to encour-
              age the use of particular sections as stand-alone documents.  In
              order to be shown, section titles must be unique  and  must  not
              contain inlined graphics.

       -unsegment
              Same as setting: $UNSEGMENT = 1; Treat a segmented document (see
              the section about document segmentation) like it were  not  seg-
              mented.  This  will cause the translator to concatenate all seg-
              ments and process them as a whole. You might find this useful to
              check  a  segmented document for consistency.  For all documents
              the sectioning levels referred to above are:
               0  document
               1  part
               2  chapter
               3  section
               4  subsection
               5  subsubsection
               6  paragraph
               7  subparagraph
               8  subsubparagraph

       These levels apply even when the document contains  no  sectioning  for
       the  shallower  levels; e.g. no \part or \chapter commands is most com-
       mon, especially when using LaTeXs article document-class.


Options controlling Extensions and Special Features

       The switches described here govern the type of HTML code  that  can  be
       generated,  and  how to choose between the available options when there
       are alternative strategies for implementing portions of LaTeX code.

       -html_version (2.0|3.0|3.2)[,(math|i18n|table)]*
              Same as setting: $HTML_VERSION = ...  ; This specifies both  the
              HTML version to generate, and any extra (non-standard) HTML fea-
              tures that may be required.  The version number corresponds to a
              published  DTD  for  an  HTML  standard  (although 3.0 was never
              accepted and subsequently withdrawn). A corresponding Perl  file
              in  the  versions/ subdirectory is loaded; these files are named
              ‘html<num>.pl’.  Following the version number, a comma-separated
              list  of  extensions  can  be  given. Each corresponds to a file
              ‘<name>.pl’ also located in  the  versions/  subdirectory.  When
              such  a  file is loaded the resulting HTML code can no longer be
              expected to validate with the specified  DTD.  An  exception  is
              math  when  the -no_math switch is also used, which should still
              validate.  Currently, versions 2.0, 3.2 and 4.0  are  available.
              (and  also  2.1, 2.2, 3.0 and 3.1, for hoistorical reasons). The
              extensions i18n, tables, math correspond roughly to what used to
              be called versions ‘2.1’, ‘2.2’, ‘3.1’ respectively, in releases
              of LaTeX2HTML up to 1996. Now these  extensions  can  be  loaded
              with  any  of  ‘2.0’,  ‘3.2’ or ‘4.0’ as the specified standard.
              The  default  version  is  usually  set  to  be  ‘3.2’,   within
              latex2html.config.

       -no_tex_defs
              Same  as  setting: $TEXDEFS = 0; (default is 1) When $TEXDEFS is
              set (default) the file texdefs.perl will be read. This  provides
              code  to allow common TEX commands like \def, \newbox, \newdimen
              and others, to be recognised,  especially  within  the  document
              preamble.  In the case of \def, the definition may even be fully
              interpreted, but this requires the pattern-matching  to  be  not
              too complicated.  If $TEXDEFS is ‘0’ or empty, then texdefs.perl
              will not be loaded; the  translator  will  make  no  attempt  to
              interpret  any  raw  TEX  commands.  This feature is intended to
              enable sophisticated authors the ability to insert arbitrary TEX
              commands  in  environments  that are destined to be processed by
              LaTeX anyway; e.g. figures, theorems,  pictures,  etc.   However
              this should rarely be needed, as now there is better support for
              these types of environment. There are now other methods to spec-
              ify  which chunks of code are to be passed to LaTeX for explicit
              image-generation; see the discussion of the  makeimage  environ-
              ment.

       -external_file <filename>
              Same  as  setting:  $EXTERNAL_FILE  = <filename> ; Specifies the
              prefix of the .aux file that this  document  should  read.   The
              .aux  extension  will be appended to this prefix to get the com-
              plete filename, with directory path if needed.  This file  could
              contain necessary information regarding citations, figure, table
              and section numbers from LaTeX  and  perhaps  other  information
              also.  Use  of  this switch is vital for document segments, pro-
              cessed separately and linked to appear as if  generated  from  a
              single LaTeX document.

       -font_size <size>
              Same as setting: $FONT_SIZE = <size> ; This option provides bet-
              ter control over the font size of environments made into  images
              using  LaTeX.   <size>  must be one of the font sizes that LaTeX
              recognizes; i.e. ‘10pt’, ‘11pt’, ‘12pt’, etc. Default is ‘10pt’,
              or whatever option may have been specified on the \documentclass
              or \documentstyle line.  Whatever size is selected, it  will  be
              magnified  by  the  installation  variables  $MATH_SCALE_FACTOR,
              $FIGURE_SCALE_FACTOR  and  $DISP_SCALE_FACTOR  as   appropriate.
              Note:  This  switch provides no control over the size of text on
              the HTML pages. Such control is subject entirely to  the  user’s
              choices of settings for the browser windows.

       -scalable_fonts
              Same as setting: $SCALABLE_FONTS = 1; This is used when scalable
              fonts, such as PostScript versions of the TEX fonts, are  avail-
              able  for  image-generation.   It  has  the  effect  of  setting
              $PK_GENERATION to ‘1’, and $DVIPS_MODE to be  empty,  overriding
              any previous settings for these variables.

       -no_math
              Same  as  setting: $NO_SIMPLE_MATH = 1; Ordinarily simple mathe-
              matical expressions are set using the ordinary  text  font,  but
              italiced.  When  part  of  the expression can not be represented
              this way, an image is made of the whole formula. This is  called
              ‘‘simple math’’. When $NO_SIMPLE_MATH is set, then all mathemat-
              ics is made into images, whether simple or not.  However, if the
              math   extension  is  loaded,  using  the  -html_version  switch
              described earlier, then specifying  -no_math  produces  a  quite
              different effect. Now it is the special <MATH> tags and entities
              which are cancelled. In their place a sophisticated  scheme  for
              parsing  mathematical  expressions  is  used. Images are made of
              those  sub-parts  of  a  formula  which  cannot  be   adequately
              expressed  using  (italiced) text characters and <SUB> and <SUP>
              tags. See the subsection on mathematics for more details.

       -local_icons
              Same as setting: $LOCAL_ICONS = 1; A copy of each of  the  icons
              actually  used  within  the  document is placed in the directory
              along with the HTML files and generated images. This allows  the
              whole  document  to  be fully self-contained, within this direc-
              tory; otherwise the icons must  be  retrieved  from  a  (perhaps
              remote)  server.  The icons are normally copied from a subdirec-
              tory of the

              $LATEX2HTMLDIR,
               set within latex2html.config. An alternative set of  icons  can
              be  used  by specifying a (relative) directory path in $ALTERNA-
              TIVE_ICONS to where the customised images can be found.

       -init_file <file>
              Load the specified initialisation file. This Perl file  will  be
              loaded after loading $HOME/.latex2html-init, or .latex2html-init
              in the local directory, if either file exists. It is read at the
              time  the  switch  is processed, so the contents of the file may
              change any of the values of any of the variables that were  pre-
              viously  established,  as well as any default options. More than
              one   initialisation   file   can   be   read   in   this   way.
              [change_begin]98.1

       -no_fork
              Same  as  setting: $NOFORK = 1; When set this disables a feature
              in the early part of the processing whereby  some  memory-inten-
              sive  operations are performed by ‘forked’ child processes. Some
              single-task operating systems, such as DOS, do not support  this
              feature.  Having $NOFORK set then ensures that unnecessary file-
              handles that are needed with the forked processes, are not  con-
              sumed unnecessarily, perhaps resulting in a fatal Perl error.

       -iso_language <type>
              This  enables you to specify a different language type than ’EN’
              to be used in  the  DTD  entries  of  the  HTML  document,  e.g.
              ’EN.US’.  [change_end] 98.1

       -short_index
              Same  as  setting: $SHORT_INDEX = 1; Creates shorter Index list-
              ings, using codified links; this is fully  compatible  with  the
              makeidx package.

       -no_footnode
              Same  as setting: $NO_FOOTNODE = 1; Suppresses use of a separate
              file for footnotes; instead these are placed at  the  bottom  of
              the  HTML pages where the references occur.  When this option is
              used, it is frequently desirable to  change  the  style  of  the
              marker used to indicate the presence of a footnote. This is done
              as in LaTeX, using code such  as  follows.   \renewcommand{\the-
              footnote}{\arabic{footnote}}  All  the  styles  \arabic,  \alph,
              \roman, \Alph and \Roman are available.  [change_begin]98.1

       -numbered_footnotes
              Same as setting: $NUMBERED_FOOTNOTES = 1; If  this  is  set  you
              will  get  every  footnote  applied with a subsequent number, to
              ease readability.  [change_end] 98.1

       -address <author-address>
              Same as setting: $ADDRESS = <author-address> ;  Sign  each  page
              with  this  address.  See latex2html.config for an example using
              Perl code to automatically include  the  date.   A  user-defined
              Perl  subroutine  called &custom_address can be used instead, if
              defined; it takes the value of $ADDRESS as  a  parameter,  which
              may  be  used  or  ignored  as  desired.  At  the time when this
              subroutine will be called, variables named $depth, $title, $file
              hold  the  sectioning-level, title and filename of the HTML page
              being produced; $FILE holds the name of  the  filename  for  the
              title-page of the whole document.

       -info <string>
              Same  as  setting:  $INFO  =  <string>  ; Generate a new section
              ‘‘About this document’’ containing information about  the  docu-
              ment being translated. The default is to generate such a section
              with information on the original document, the  date,  the  user
              and  the translator. An empty string (or the value ‘0’) disables
              the creation of this extra section.  If a  non-empty  string  is
              given,  it  will  be  placed as the contents of the ‘‘About this
              document’’ page instead of the default information.


Switches controlling Image Generation

       These switches affect whether images are created at  all,  whether  old
       images  are  reused  on subsequent runs or new ones created afresh, and
       whether anti-aliasing effects are used within the images themselves.

       -ascii_mode
              Same as setting: $ASCII_MODE = $EXTERNAL_IMAGES =  1;  Use  only
              ASCII characters and do not include any images in the final out-
              put. With -ascii_mode the output of the translator can  be  used
              on  character-based browsers, such as lynx, which do not support
              inlined images (via the <IMG> tag).

       -nolatex
              Same as setting: $NOLATEX = 1; Disable the mechanism for passing
              unknown  environments  to  LaTeX  for  processing.  This  can be
              thought of as ‘‘draft mode’’ which allows faster translation  of
              the  basic  document  structure and text, without fancy figures,
              equations or tables.  (This option has been  superseded  by  the
              -no_images option, see below.)

       -external_images
              Same  as setting: $EXTERNAL_IMAGES = 1; Instead of including any
              generated images inside the document,  leave  them  outside  the
              document and provide hypertext links to them.

       -ps_images
              Same as setting: $PS_IMAGES = $EXTERNAL_IMAGES = 1; Use links to
              external PostScript files rather than inlined images in the cho-
              sen graphics format.

       -discard
              Same as setting: $DISCARD_PS = 1; The temporary PostScript files
              are discarded immediately after they have been  used  to  create
              the image in the desired graphics format.

       -no_images
              Same  as  setting: $NO_IMAGES = 1; Do not attempt to produce any
              inlined images. The missing images can be generated ‘‘off-line’’
              by restarting LaTeX2HTML with the option -images_only .

       -images_only
              Same  as  setting:  $IMAGES_ONLY = 1; Try to convert any inlined
              images that were left over from previous runs of LaTeX2HTML.

       -reuse <reuse_option>
              Same as setting: $REUSE = <reuse_option>; This switch  specifies
              the  extent  to  which image files are to be shared or recycled.
              There are three valid options: [*] 0 Do not ever share or  recy-
              cle  image  files.  This choice also invokes an interactive ses-
              sion prompting the user about what to do  about  a  pre-existing
              HTML  directory, if it exists.  [*] 1 Recycle image files from a
              previous run if they are available, but do not  share  identical
              images  that  must  be created in this run.  [*] 2 Recycle image
              files from a previous run and share identical images  from  this
              run.   This is the default.  A later section provides additional
              information about image-reuse.

       -no_reuse
              Same as setting: $REUSE = 0; Do not share or recycle images gen-
              erated  during  previous  translations.   This  is equivalent to
              -reuse 0 . (This will enable  the  initial  interactive  session
              during  which  the user is asked whether to reuse the old direc-
              tory, delete its contents or quit.)

       -antialias
              Same as setting: $ANTI_ALIAS = 1;  (Default  is  0.)   Generated
              images  of  figure  environments  and  external PostScript files
              should use anti-aliasing. By default anti-aliasing is  not  used
              with these images, since this may interfere with the contents of
              the images themselves.

       -antialias_text
              Same as setting: $ANTI_ALIAS_TEXT = 1; (Default is  1.)   Gener-
              ated  images of typeset material such as text, mathematical for-
              mulas, tables and the content of makeimage environments,  should
              use anti-aliasing effects.  The default is normally to use anti-
              aliasing for text, since the resulting images are  much  clearer
              on-screen. However the default may have been changed locally.

       -no_antialias
              Same  as  setting:  $ANTI_ALIAS  = 0; (Default is 0.)  Generated
              images of figure  environments  and  external  PostScript  files
              should  not  use  anti-aliasing  with  images,  though the local
              default may have been changed to use it.

       -no_antialias_text
              Same as setting: $ANTI_ALIAS_TEXT = 0; (Default is  1.)   Gener-
              ated  images  of  typeset  material should not use anti-aliasing
              effects.  Although  on-screen  images  of  text  are  definitely
              improved  using  anti-aliasing,  printed  images  can  be  badly
              blurred, even at 300dpi. Higher resolution printers  do  a  much
              better    job    with    the    resulting   grey-scale   images.
              [change_begin]98.1

       -white Same as setting: $WHITE_BACKGROUND = 1; (Default is 1.)  Ensures
              that  images  of  figure  environments  have a white background.
              Otherwise transparency effects may not work correctly.

       -no_white
              Same as setting: $WHITE_BACKGROUND = ; (Default is  1.)   Can-
              cels the requirement that figure environments have a white back-
              ground.

       -ldump Same as setting: $LATEX_DUMP = 1; (Default is 0.)  Use  this  if
              you  want to speed up image processing during the 2nd and subse-
              quent runs of LaTeX2HTML on the same  document.  The  translator
              now  produces  a LaTeX format-dump of the preamble to images.tex
              which is used on subsequent runs. This significantly reduces the
              startup time when LaTeX reads the images.tex file for image-gen-
              eration.  This process actually consumes additional time on  the
              first  run,  since  LaTeX  is called twice -- once to create the
              format-dump, then again to load and use it.  The  pay-off  comes
              with  the faster loading on subsequent runs. Approximately 1 Meg
              of disk space is consumed by the dump file.  [change_end] 98.1


Switches controlling Navigation Panels

       The following switches govern whether to include one or more navigation
       panels  on  each HTML page, also which buttons to include within such a
       panel.

       -no_navigation
              Same as setting: $NO_NAVIGATION = 1; Disable the  mechanism  for
              putting  navigation links in each page.  This overrides any set-
              tings of the $TOP_NAVIGATION, $BOTTOM_NAVIGATION and $AUTO_NAVI-
              GATION variables.

       -top_navigation
              Same  as  setting:  $TOP_NAVIGATION = 1; Put navigation links at
              the top of each page.

       -bottom_navigation
              Same as setting: $BOTTOM_NAVIGATION = 1; Put navigation links at
              the bottom of each page as well as the top.

       -auto_navigation
              Same  as  setting: $AUTO_NAVIGATION = 1; Put navigation links at
              the top of each page. Also put one at the bottom of the page, if
              the page exceeds $WORDS_IN_PAGE number of words (default = 450).

       -next_page_in_navigation
              Same as setting: $NEXT_PAGE_IN_NAVIGATION = 1; Put a link to the
              next logical page in the navigation panel.

       -previous_page_in_navigation
              Same as setting: $PREVIOUS_PAGE_IN_NAVIGATION = 1; Put a link to
              the previous logical page in the navigation panel.

       -contents_in_navigation
              Same as setting: $CONTENTS_IN_NAVIGATION = 1; Put a link to  the
              table-of-contents in the navigation panel if there is one.

       -index_in_navigation
              Same  as  setting:  $INDEX_IN_NAVIGATION  = 1; Put a link to the
              index-page in the navigation panel if there is an index.


Switches for Linking to other documents

       When processing a single stand-alone document, the  switches  described
       in  this  section  should not be needed at all, since the automatically
       generated navigation panels, described on the previous page should gen-
       erate all the required navigation links. However if a document is to be
       regarded as part of a much larger document, then links from  its  first
       and  final  pages,  to locations in other parts of the larger (virtual)
       document, need to be provided explicitly for some of the buttons in the
       navigation panel.  The following switches allow for such links to other
       documents, by providing the title and URL for navigation  panel  hyper-
       links. In particular, the ‘‘Document Segmentation’’ feature necessarily
       makes great use of these switches. It is usual for the text and targets
       of  these  navigation hyperlinks to be recorded in a Makefile, to avoid
       tedious typing of long command-lines having many switches.

       -up_url <URL>
              Same as setting: $EXTERNAL_UP_LINK = <URL> ; Specifies a univer-
              sal  resource  locator (URL) to associate with the ‘‘UP’’ button
              in the navigation panel(s).

       -up_title <string>
              Same as setting: $EXTERNAL_UP_TITLE =  <string>  ;  Specifies  a
              title associated with this URL.

       -prev_url <URL>
              Same  as  setting: $EXTERNAL_PREV_LINK = <URL> ; Specifies a URL
              to associate with the  ‘‘PREVIOUS’’  button  in  the  navigation
              panel(s).

       -prev_title <string>
              Same  as  setting: $EXTERNAL_PREV_TITLE = <string> ; Specifies a
              title associated with this URL.

       -down_url <URL>
              Same as setting: $EXTERNAL_DOWN_LINK = <URL> ; Specifies  a  URL
              for the ‘‘NEXT’’ button in the navigation panel(s).

       -down_title <string>
              Same  as  setting: $EXTERNAL_DOWN_TITLE = <string> ; Specifies a
              title associated with this URL.

       -contents <URL>
              Same as setting: $EXTERNAL_CONTENTS = <URL> ;  Specifies  a  URL
              for  the  ‘‘CONTENTS’’  button, for document segments that would
              not otherwise have one.

       -index <URL>
              Same as setting: $EXTERNAL_INDEX = <URL> ; Specifies a  URL  for
              the ‘‘INDEX’’ button, for document segments that otherwise would
              not have an index.

       -biblio <URL>
              Same as setting: $EXTERNAL_BIBLIO = <URL> ;  Specifies  the  URL
              for  the  bibliography page to be used, when not explicitly part
              of the document itself.  Warning: On some systems it  is  diffi-
              cult  to give text-strings <string> containing space characters,
              on the command-line or via a Makefile. One way to overcome  this
              is  to use the corresponding variable. Another way is to replace
              the spaces with underscores (_).


Switches for Help and Tracing

       The first two of the  following  switches  are  self-explanatory.  When
       problems  arise in processing a document, the switches -debug and -ver-
       bosity will each cause  LaTeX2HTML  to  generate  more  output  to  the
       screen.  These  extra  messages  should help to locate the cause of the
       problem.

       -tmp <path>
              Define a temporary directory to use  for  image  generation.  If
              <path> is 0, the standard temporary directory /tmp is used.

       -h(elp)
              Print out the list of all command-line options.

       -v     Print the current version of LaTeX2HTML.

       -debug Same  as setting: $DEBUG = 1; Run in debug-mode, displaying mes-
              sages and/or diagnostic information about files read, and utili-
              ties called by LaTeX2HTML.  Shows any messages produced by these
              calls.  More extensive diagnostics, from the Perl debugger,  can
              be obtained by appending the string ‘-w-’ to the 1st line of the
              latex2html (and other) Perl script(s).

       -verbosity <num>
              Same as setting: $VERBOSITY = <num>; Display messages  revealing
              certain aspects of the processing performed by LaTeX2HTML on the
              provided input file(s). The <num> parameter can be an integer in
              the  range  0  to 8. Each higher value adds to the messages pro-
              duced.

       0.     No special tracing; as  for  versions  of  LaTeX2HTML  prior  to
              V97.1.

       1.     (This is the default.) Show section-headings and the correspond-
              ing HTML file names, and indicators that  major  stages  in  the
              processing have been completed.

       2.     Print environment names and identifier numbers, and new theorem-
              types. Show warnings as they  occur,  and  indicators  for  more
              stages of processing. Print names of files for storing auxiliary
              data arrays.

       3.     Print command names as they are encountered and processed;  also
              any  unknown  commands  encountered  while  pre-processing. Show
              names of new  commands,  environments,  theorems,  counters  and
              counter-dependencies, for each document partition.

       4.     Indicate  command-substitution  the pre-process of math-environ-
              ments. Print the contents of unknown environments for processing
              in  LaTeX, both before and after reverting to LaTeX source. Show
              all operations affecting  the  values  of  counters.  Also  show
              links,  labels and sectioning keys, at the stages of processing.

       5.     Detail the processing in the document preamble.  Show  substitu-
              tions  of  new environments. Show the contents of all recognised
              environments,  both  before  and  after  processing.  Show   the
              cached/encoded  information  for  the  image  keys, allowing two
              images to be tested for equality.

       6.     Show replacements of new commands, accents and wrapped commands.

       7.     Trace  the  processing of commands in math mode; both before and
              after.

       8.     Trace the processing of all commands,  both  before  and  after.
              The  command-line option sets an initial value only. During pro-
              cessing the value of $VERBOSITY can be set dynamically using the
              \htmltracing{...}  command, whose argument is the desired value,
              or by using  the  more  general  \HTMLset  command  as  follows:
              \HTMLset{VERBOSITY}{<num>}.


Other Configuration Variables, without switches

       The configuration variables described here do not warrant having a com-
       mand-line switch to assign values. Either  they  represent  aspects  of
       LaTeX2HTML  that are specific to the local site, or they govern proper-
       ties that should apply to all documents,  rather  than  something  that
       typically  would change for the different documents within a particular
       sub-directory.  Normally these variables have their  value  set  within
       the  latex2html.config  file. In the following listing the defaults are
       shown, as the lines of Perl code used to establish these values.  If  a
       different  value  is  required, then these can be assigned from a local
       .latex2html-init initialisation file, without  affecting  the  defaults
       for other users, or documents processed from other directories.

       $dd    holds  the  string  to be used in file-names to delimit directo-
              ries; it is set internally  to  ‘/’,  unless  the  variable  has
              already  been  given  a  value within latex2html.config .  Note:
              This value cannot be set within a  .latex2html-init  initialisa-
              tion  file,  since  its value needs to be known in order to find
              such a file.

       $LATEX2HTMLDIR
              Read by the  install-test  script  from  latex2html.config,  its
              value is inserted into the latex2html Perl script as part of the
              installation process.

       $LATEX2HTMLSTYLES = $LATEX2HTMLDIR/styles ;
              Read from the latex2html.config file by install-test, its  value
              is checked to locate the styles/ directory.

       $LATEX2HTMLVERSIONS = $LATEX2HTMLDIR/versions ;
              The  value of this variable should be set within latex2html.con-
              fig to specify the directory path where the version  and  exten-
              sion files can be found.

       $ALTERNATIVE_ICONS = ;
              This  may contain the (relative) directory path to a set of cus-
              tomised icons to be used in conjunction  with  the  -local_icons
              switch.

       $TEXEXPAND = $LATEX2HTMLDIR/texexpand ;
              Read by the install-test Perl script from latex2html.config, its
              value is used to locate the texexpand Perl script.

       $PSTOIMG = $LATEX2HTMLDIR/pstoimg ;
              Read by the install-test Perl script from latex2html.config, its
              value is used to locate the pstoimg Perl script.

       $IMAGE_TYPE = <image-type>;
              Set  in latex2html.config, the currently supported <image-type>s
              are: gif and png.

       $DVIPS = dvips;
              Read  from  latex2html.config  by  install-test,  its  value  is
              checked  to  locate the dvips program or script.  There could be
              several reasons to  change  the  value  here:  o  add  a  switch
              -P<printer> to load a specific configuration-file; e.g. to use a
              specific set of PostScript fonts, for improved image-generation.
              o  to  prepend  a path to a different version of dvips than nor-
              mally  available  as  the  system  default  (e.g.  the  printing
              requirements are different).  o to append debugging switches, in
              case of poor quality images; one can see which paths  are  being
              searched  for  fonts and other resources.  o to prepend commands
              for setting path variables that  dvips  may  need  in  order  to
              locate  fonts  or  other  resources.  If automatic generation of
              fonts is required, using Metafont, the  following  configuration
              variables are important.

              $PK_GENERATION = 1;
                     This  variable  must be set, to initiate font-generation;
                     otherwise fonts will be scaled from existing resources on
                     the  local  system.  In particular this variable must not
                     be set, if one wishes to use PostScript  fonts  or  other
                     scalable font resources (see the -scalable_fonts switch).

              $DVIPS_MODE = toshiba;
                     The mode given here must be  available  in  the  modes.mf
                     file,  located  with the Metafont resource files, perhaps
                     in the misc/ subdirectory.

              $METAFONT_DPI = 180;
                     The required  resolution,  in  dots-per-inch,  should  be
                     listed  specifically  within the MakeTeXPK script, called
                     by dvips to invoke Metafont with the  correct  parameters
                     for the required fonts.

       $LATEX = latex;
              Read  from  latex2html.config  by  install-test,  its  value  is
              checked to locate the latex program or script.  If LaTeX is hav-
              ing  trouble  finding  style-files  and/or  packages,  then  the
              default command can be prepended  with  other  commands  to  set
              environment  variables  intended  to resolve these difficulties;
              e.g.  $LATEX = setenv TEXINPUTS <path to  search>  ;  latex  .
              There  are several variables to help control exactly which files
              are read by LaTeX2HTML and by LaTeX when processing images:

              $TEXINPUTS
                     This is normally set from the environment variable of the
                     same name. If difficulties occur so that styles and pack-
                     ages are not being found, then extra paths can be  speci-
                     fied here, to resolve these difficulties.

              $DONT_INCLUDE
                     This  provides  a list of filenames and extensions to not
                     include, even if requested to  do  so  by  an  \input  or
                     \include  command.   (Consult  latex2html.config  for the
                     default list.)

              $DO_INCLUDE = ;
                     List of exceptions within the $DONT_INCLUDE  list.  These
                     files  are  to  be  read  if  requested  by  an \input or
                     \include command.

       $ICONSERVER = <URL>;
              This is used to specify a URL to find  the  standard  icons,  as
              used  for the navigation buttons.  Names for the specific images
              size,  as  well  as  size   information,   can   be   found   in
              latex2html.config.  The icons themselves can be replaced by cus-
              tomised versions, provided this information is correctly updated
              and the location of the customised images specified as the value
              of $ICONSERVER.  When the -local_icons switch is used, so that a
              copy of the icons is placed with the HTML files and other gener-
              ated images, the value of $ICONSERVER is not needed  within  the
              HTML files themselves. However it is needed to find the original
              icons to be copied to the local directory.

       $NAV_BORDER = <num>;
              The value given here results in a border,  measured  in  points,
              around  each icon.  A value of ‘0’ is common, to maintain strict
              alignment of inactive and active buttons in the control  panels.

       $LINKNAME = "index.$EXTN";
              This  is used when the $NO_AUTO_LINK variable is empty, to allow
              a URL to the working directory to be  sufficient  to  reach  the
              main  page  of  the completed document. It specifies the name of
              the HTML file which will be automatically linked to  the  direc-
              tory  name.   The  value  of $EXTN is .html unless $SHORTEXTN is
              set, in which case it is .htm .

       $LINKPOINT = "$FILE$EXTN";
              This specifies the name of the HTML file to  be  duplicated,  or
              symbolically  linked,  with the name specified in $LINKNAME.  At
              the appropriate time the value of $FILE is  the  document  name,
              which  usually coincides with the name of the working directory.

       $CHARSET = iso_8859_1;
              This specifies the character set used within the HTML pages pro-
              duced  by  LaTeX2HTML.  If no value is set in a configuration or
              initialisation file, the default value will be assumed. The low-
              ercase  form $charset is also recognised, but this is overridden
              by the uppercase form.

       $ACCENT_IMAGES = large;
              Accented characters that are not part of the ISO-Latin fonts can
              be generated by making an image using LaTeX.  This variable con-
              tains a (comma-separated) list of LaTeX commands for setting the
              style  to  be  used  when these images are made. If the value of
              this variable is empty then the accent is simply ignored,  using
              an  un-accented  font  character (not an image) instead.  Within
              the color.perl package, the  following  variables  are  used  to
              identify  the names of files containing specifications for named
              colors.  Files  having  these  names  are   provided,   in   the
              $LATEX2HTMLSTYLES  directory, but they could be moved elsewhere,
              or replaced by alternative files  having  different  names.   In
              such  a  case  the  values  of these variables should be altered
              accordingly.
               $RGBCOLORFILE = ’rgb.txt’;
               $CRAYOLAFILE = ’crayola.txt’; The following variables may  well
              be altered from the system defaults, but this is best done using
              a local .latex2html-init initialisation file, for  overall  con-
              sistency  of style within documents located at the same site, or
              sites in close proximity.

       $default_language = english;
              This establishes which language code is to be placed within  the
              <!DOCTYPE ... > tag that may appear at the beginning of the HTML
              pages produced. Loading a package for  an  alternative  language
              can  be expected to change the value of this variable.  See also
              the $TITLES_LANGUAGE variable, described next.

       $TITLES_LANGUAGE = english;
              This variable is used to specify the  actual  strings  used  for
              standard    document    sections,    such    as    ‘‘Contents’’,
              ‘‘References’’, ‘‘Table of Contents’’, etc.  Support for  French
              and  German titles is available in corresponding packages. Load-
              ing such a package will normally alter the value of  this  vari-
              able, as well as the $default_language variable described above.

       $WORDS_IN_NAVIGATION_PANEL_TITLES = 4;
              Specifies how many words to use from section titles, within  the
              textual hyperlinks which accompany the navigation buttons.

       $WORDS_IN_PAGE = 450;
              Specifies  the  minimum page length required before a navigation
              panel is placed at the bottom of a page, when the  $AUTO_NAVIGA-
              TION variable is set.

       $CHILDLINE = <BR><HR>;
              This  gives  the  HTML code to be placed between the child-links
              table and the ordinary contents of the page on which it  occurs.

       $NETSCAPE_HTML = 0;
              When  set, this variable specifies that HTML code may be present
              which does not conform to any official standard. This  restricts
              the  contents  of any <!DOCTYPE ... > tag which may be placed at
              the beginning of the HTML pages produced.

       $BODYTEXT = ;
              The value of this variable is used within the <BODY ...  >  tag;
              e.g.  to set text and/or background colors.  It’s value is over-
              ridden by the \bodytext command, and can be  added-to  or  parts
              changed  using  the  \htmlbody  command or \color and \pagecolor
              from the color package.

       $INTERLACE = 1;
              When set, interlaced images should be produced.   This  requires
              graphics  utilities  to  be available to perform the interlacing
              operation.

       $TRANSPARENT_FIGURES = 1;
              When set, the background of images should be  made  transparent;
              otherwise  it  is white.  This requires graphics utilities to be
              available which can specify the color to be made transparent.

       $FIGURE_SCALE_FACTOR = 1.6;
              Scale factor applied to all images of figure and other  environ-
              ments,  when  being made into an image.  Note that this does not
              apply to recognised mathematics environments, which instead  use
              the  contents  of  $MATH_SCALE_FACTOR  and $DISP_SCALE_FACTOR to
              specify scaling.

       $MATH_SCALE_FACTOR = 1.6;
              Scale factor applied to all images of mathematics,  both  inline
              and  displayed. A value of 1.4 is a good alternative, with anti-
              aliased images.

       $DISP_SCALE_FACTOR = 1;
              Extra scale factor applied to images of displayed math  environ-
              ments.   When  set,  this value multiplies $MATH_SCALE_FACTOR to
              give the total scaling. A value of ‘1.2’ is  a  good  choice  to
              accompany $MATH_SCALE_FACTOR = 1.4;.

       $EXTRA_IMAGE_SCALE
              This  may  hold an extra scale factor that can be applied to all
              generated images.  When set, it  specifies  that  a  scaling  of
              $EXTRA_IMAGE_SCALE  be  applied  when images are created, but to
              have their height and width recorded as the un-scaled size. This
              is  to coax browsers into scaling the (usually larger) images to
              fit the desired size; when  printed  a  better  quality  can  be
              obtained.  Values  of  ‘1.5’  and ‘2’ give good print quality at
              600dpi.

       $PAPERSIZE = a5;
              Specifies the size of a page for  typesetting  figures  or  dis-
              played math, when an image is to be generated.  This affects the
              lengths of lines of text within images. Since images of text  or
              mathematics  should  use  larger  sizes  than when printed, else
              clarity is lost at screen resolutions, then a smaller paper-size
              is  generally  advisable.  This  is  especially  so  if both the
              $MATH_SCALE_FACTOR and $DISP_SCALE_FACTOR  scaling  factors  are
              being  used,  else  some  images  may  become excessively large,
              including a lot of blank space.

       $LINE_WIDTH = 500;
              Formerly specified the width of an image, when the contents were
              to be right- or center-justified. (No longer used.)

       The  following variables are used to access the utilities required dur-
       ing image-generation. File and program locations on  the  local  system
       are  established by the configure-pstoimg Perl script and stored within
       $LATEX2HTMLDIR/local.pm as Perl  code,  to  be  read  by  pstoimg  when
       required.   After  running  the configure-pstoimg Perl script it should
       not be necessary to alter the values obtained. Those  shown  below  are
       what happens on the author’s system; they are for illustration only and
       do not represent default values.

        $GS_LIB = ’/usr/local/share/ghostscript/4.02’;
        $PNMCAT = ’/usr/local/bin/pnmcat’;
        $PPMQUANT = ’/usr/local/bin/ppmquant’;
        $PNMFLIP = ’/usr/local/bin/pnmflip’;
        $PPMTOGIF = ’/usr/local/bin/ppmtogif’;
        $HOWTO_TRANSPARENT_GIF = ’netpbm’;
        $GS_DEVICE = ’pnmraw’;
        $GS = ’/usr/local/bin/gs’;
        $PNMFILE = ’/usr/local/bin/pnmfile’;
        $HOWTO_INTERLACE_GIF = ’netpbm’;
        $PBMMAKE = ’/usr/local/bin/pbmmake’;
        $PNMCROP = ’/usr/local/bin/pnmcrop’;
        $TMP = ’/usr/var/tmp’; The following variables are no  longer  needed,
       having  been  replaced  by the more specific information obtained using
       the Perl script configure-pstoimg.
        $USENETPBM = 1;
        $PBMPLUSDIR = ’/usr/local/bin’;


SEE ALSO

       latex(1)


AUTHOR

       Nikos Drakos,   Computer  Based  Learning  Unit,  University  of  Leeds
       <nikos@cbl.leeds.ac.uk>.  Several  people have contributed suggestions,
       ideas, solutions, support and encouragement.  The current maintainer is
       Ross  Moore.   This  manual  page was written by Manoj Srivastava <sri-
       vasta@debian.org>, for the Debian GNU/Linux system, based on the  LaTeX
       documentation accompanying the program.



Debian                           March 1 2000                    LaTeX2HTML(1)

Man(1) output converted with man2html