2 files changed, 1288 insertions, 0 deletions

diff --git a/textproc/latex2html/Makefile b/textproc/latex2html/Makefile
index 124a977dc7aa..48c3bdf1d957 100644
--- a/textproc/latex2html/Makefile
+++ b/textproc/latex2html/Makefile
@@ -7,6 +7,7 @@
 
 PORTNAME=	latex2html
 PORTVERSION=	99.2b8
+PORTREVISION=	1
 CATEGORIES=	textproc
 MASTER_SITES=	${MASTER_SITE_TEX_CTAN}
 MASTER_SITE_SUBDIR=	support/${PORTNAME}
@@ -30,6 +31,8 @@ CONFIGURE_ARGS=	--with-perl=${PERL} \
 		--disable-gif \
 		--libdir=${DATADIR}
 
+MAN1=	latex2html.1
+
 MSG_FILE=	${PKGDIR}/pkg-message
 PKGMESSAGE=	${WRKDIR}/pkg-message
 
@@ -52,6 +55,7 @@ patch-message:
 post-install: install-docs display-message
 
 install-docs:
+	${INSTALL_MAN} ${FILESDIR}/latex2html.1 ${MANPREFIX}/man/man1
 .if !defined(NOPORTDOCS)
 	@${MKDIR} ${DOCSDIR}
 .for file in ${DOC_FILES}
diff --git a/textproc/latex2html/files/latex2html.1 b/textproc/latex2html/files/latex2html.1
new file mode 100644
index 000000000000..70762a6d5edc
--- /dev/null
+++ b/textproc/latex2html/files/latex2html.1
@@ -0,0 +1,1284 @@
+\" Hey, Emacs! This is an -*- nroff -*- source file.
+.\" Copyright (c) 1997 Manoj Srivastava <srivasta@debian.org>
+.\"
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, write to the Free
+.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
+.\" USA.
+.\"
+.\"
+.\"    $Id: latex2html.1,v 1.2 2000/03/04 07:55:13 srivasta Exp $
+.\"
+.TH LaTeX2HTML 1 "March 1 2000" "Debian" "Debian GNU/Linux manual"
+.SH NAME
+latex2html \- translate LaTeX files to HTML (HyperText Markup Language)
+.SH SYNOPSIS
+.B latex2html
+.I [options]
+\&[target [target ...]]
+.SH DESCRIPTION
+This manual page explains the
+.B "LaTeX2HTML"
+utility, which is a 
+.B Perl 
+program that translates
+.B LaTeX
+document into 
+.B HTML 
+format. For each source file given as an argument
+the translator will create a directory containing the corresponding
+HTML files. For details and examples, please consult the online html
+documentation, a copy of which should be available in
+.I /usr/share/doc/latex2html/manual.ps.gz
+or
+.I /usr/share/doc/latex2html/html/
+.SH CAVEAT
+This documetation has been derived from the TeX manual, and may not be
+uptodate. Please refer to the online manual for authoritative
+documentation.
+.UN file://localhost/doc/latex2html/html/
+.SH Options controlling Titles, File-Names and Sectioning
+.TP
+.B -t <top-page-title>
+Same as setting:
+.I $TITLE = "<top-page-title>";
+Name the document using this title.
+.TP
+.B -short_extn
+Same as setting:
+.I $SHORTEXTN = 1;
+Use a filename prefix of .htm for the produced 
+.B 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.
+.TP
+.B -long_titles <num>
+Same as setting:
+.I $LONG_TITLES = <num>;
+Instead of the standard names: node1.html, node2.html,... the filenames
+for each 
+.B 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.
+.TP
+.B -custom_titles
+Same as setting:
+.I $CUSTOM_TITLES = 1;
+Instead of the standard names: node1.html, node2.html, ... the
+filenames for each 
+.B HTML 
+page are constructed using a 
+.B Perl 
+subroutine
+named custom_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).
+.TP
+.B -dir <output-directory>
+Same as setting:
+.I $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.
+.TP
+.B -no_subdir
+Same as setting:
+.I $NO_SUBDIR = 1;
+Place the generated 
+.B HTML 
+files into the current directory. This
+overrides any 
+.I $DESTDIR 
+setting.
+.TP
+.B -prefix <filename-prefix>
+Same as setting:
+.I $PREFIX = "<filename-prefix>";
+The <filename-prefix> will be prepended to all .gif, .pl and .html
+files produced, except for the top-level .html file; it may include a
+(relative) directory path. This will enable multiple products of
+.B LaTeX2HTML 
+to peacefully coexist in the same directory. However, do not
+attempt to simultaneously run multiple instances of 
+.B LaTeX2HTML 
+using
+the same output directory, else various temporary files will overwrite
+each other.
+.TP
+.B -auto_prefix
+Same as setting:
+.I $AUTO_PREFIX = 1;
+Constructs the prefix as `<title>-' to be prepended to all the files
+produced, where <title> is the name of the 
+.B LaTeX 
+file being processed.
+(Note the `-' in this prefix.)
+This overrides any 
+.I $PREFIX 
+setting.
+.TP
+.B -no_auto_link
+Same as setting:
+.I $NO_AUTO_LINK = 1;
+If $NO_AUTO_LINK is empty and variables 
+.I $LINKPOINT 
+and 
+.I $LINKNAME 
+are
+defined appropriately (as is the default in the latex2html.config
+file), then a hard link to the main 
+.B HTML 
+page is produced, using the
+name supplied in 
+.I $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 systems a
+different value for 
+.I $LINKNAME 
+may be appropriate. Typically 
+.I $LINKPOINT
+has 
+value 
+.I $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 particular document.
+.TP
+.B -split <num>
+Same as setting:
+.I $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 
+.B HTML 
+file. See
+below for the different levels of sectioning. Also see the next item
+for how to set a ``relative'' depth for splitting.
+.TP
+.B -split +<num>
+Same as setting:
+.I $MAX_SPLIT_DEPTH = -<num>; (default is 8)
+The level at which to stop splitting sections is calculated ``relative
+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 
+.B HTML 
+file.
+.TP
+.B -link <num>
+Same as setting:
+.I $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 
+.B HTML 
+pages, this
+table is located at the bottom of the page, unless placed elsewhere
+using the \\tableofchildlinks command.
+On pages having a sectioning-level just less than the -split depth the
+mini table-of-contents contains links to subsections etc. occurring on
+the same 
+.B HTML 
+page. Now the table is located at the top of this page,
+unless placed elsewhere using the \\tableofchildlinks command.
+.TP
+.B -toc_depth <num>
+Same as setting:
+.I $TOC_DEPTH = <num>; (default is 4)
+Sectioning levels down to <num> are to be included within the
+Table-of-Contents tree.
+.TP
+.B -toc_stars
+Same as setting:
+.I $TOC_STARS = 1;
+Sections created using the starred-form of sectioning commands are
+included within the Table-of-Contents. As with 
+.B LaTeX, 
+normally such
+sections are not listed.
+.TP
+.B -show_section_numbers
+Same as setting:
+.I $SHOW_SECTION_NUMBERS = 1;
+Show section numbers. By default section numbers are not shown, so as
+to encourage 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.
+.TP
+.B -unsegment
+Same as setting:
+.I $UNSEGMENT = 1;
+Treat a segmented document (see the section about document
+segmentation) like it were not segmented. This will cause the
+translator to concatenate all segments 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:
+.RS 
+ 0  document
+ 1  part
+ 2  chapter
+ 3  section
+ 4  subsection
+ 5  subsubsection
+ 6  paragraph
+ 7  subparagraph
+ 8  subsubparagraph
+.RE
+.P
+These levels apply even when the document contains no sectioning for the
+shallower levels; e.g. no \\part or \\chapter commands is most common,
+especially when using 
+.B LaTeX's 
+article document-class.
+.SH Options controlling Extensions and Special Features
+The switches described here govern the type of 
+.B HTML 
+code that can be
+generated, and how to choose between the available options when there are
+alternative strategies for implementing portions of 
+.B LaTeX 
+code.
+.TP
+.B -html_version (2.0|3.0|3.2)[,(math|i18n|table)]*
+Same as setting:
+.I $HTML_VERSION = "... ";
+This specifies both the 
+.B HTML 
+version to generate, and any extra
+(non-standard) 
+.B HTML 
+features that may be required.
+The version number corresponds to a published DTD for an 
+.B HTML 
+standard
+(although 3.0 was never accepted and subsequently withdrawn). A
+corresponding 
+.B 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 
+.B 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.
+.TP
+.B -no_tex_defs
+Same as setting:
+.I $TEXDEFS = 0; (default is 1)
+When 
+.I $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 
+.I $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 
+.B 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 specify
+which chunks of code are to be passed to 
+.B LaTeX 
+for explicit
+image-generation; see the discussion of the makeimage environment.
+.TP
+.B -external_file <filename>
+Same as setting:
+.I $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 complete
+filename, with directory path if needed.
+This file could contain necessary information regarding citations,
+figure, table and section numbers from 
+.B LaTeX 
+and perhaps other
+information also. Use of this switch is vital for document segments,
+processed separately and linked to appear as if generated from a single
+LaTeX document.
+.TP
+.B -font_size <size>
+Same as setting:
+.I $FONT_SIZE = "<size>";
+This option provides better control over the font size of environments
+made into images using 
+.B LaTeX. 
+<size> must be one of the font sizes that
+.B 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 
+.I $MATH_SCALE_FACTOR, 
+.I $FIGURE_SCALE_FACTOR 
+and
+.I $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.
+.TP
+.B -scalable_fonts
+Same as setting:
+.I $SCALABLE_FONTS = 1;
+This is used when scalable fonts, such as PostScript versions of the
+TEX fonts, are available for image-generation.
+It has the effect of setting 
+.I $PK_GENERATION 
+to `1', and 
+.I $DVIPS_MODE 
+to
+be empty, overriding any previous settings for these variables.
+.TP
+.B -no_math
+Same as setting:
+.I $NO_SIMPLE_MATH = 1;
+Ordinarily simple mathematical 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 
+.I $NO_SIMPLE_MATH 
+is set, then all
+mathematics 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.
+.TP
+.B -local_icons
+Same as setting:
+.I $LOCAL_ICONS = 1;
+A copy of each of the icons actually used within the document is placed
+in the directory along with the 
+.B HTML 
+files and generated images. This
+allows the whole document to be fully self-contained, within this
+directory; otherwise the icons must be retrieved from a (perhaps
+remote) server.
+The icons are normally copied from a subdirectory of the
+
+.B $LATEX2HTMLDIR,
+ set within latex2html.config. An alternative set of
+icons can be used by specifying a (relative) directory path in
+$ALTERNATIVE_ICONS to where the customised images can be found.
+.TP
+.B -init_file <file>
+Load the specified initialisation file. This 
+.B Perl 
+file will be loaded
+after loading 
+.I $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 previously established, as well as any
+default options. More than one initialisation file can be read in this
+way.
+[change_begin]98.1
+.TP
+.B -no_fork
+Same as setting:
+.I $NOFORK = 1;
+When set this disables a feature in the early part of the processing
+whereby some memory-intensive operations are performed by `forked'
+child processes. Some single-task operating systems, such as DOS, do
+not support this feature. Having 
+.I $NOFORK 
+set then ensures that
+unnecessary file-handles that are needed with the forked processes, are
+not consumed unnecessarily, perhaps resulting in a fatal 
+.B Perl 
+error.
+.TP
+.B -iso_language <type>
+This enables you to specify a different language type than 'EN' to be
+used in the DTD entries of the 
+.B HTML 
+document, e.g. 'EN.US'.
+[change_end] 98.1
+.TP
+.B -short_index
+Same as setting:
+.I $SHORT_INDEX = 1;
+Creates shorter Index listings, using codified links; this is fully
+compatible with the makeidx package.
+.TP
+.B -no_footnode
+Same as setting:
+.I $NO_FOOTNODE = 1;
+Suppresses use of a separate file for footnotes; instead these are
+placed at the bottom of the 
+.B 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 
+.B LaTeX, 
+using code such as follows.
+\\renewcommand{\\thefootnote}{\\arabic{footnote}}
+All the styles \\arabic, \\alph, \\roman, \\Alph and \\Roman are available.
+[change_begin]98.1
+.TP
+.B -numbered_footnotes
+Same as setting:
+.I $NUMBERED_FOOTNOTES = 1;
+If this is set you will get every footnote applied with a subsequent
+number, to ease readability.
+[change_end] 98.1
+.TP
+.B -address <author-address>
+Same as setting:
+.I $ADDRESS = "<author-address>";
+Sign each page with this address.
+See latex2html.config for an example using 
+.B Perl 
+code to automatically
+include the date.
+A user-defined 
+.B Perl 
+subroutine called &custom_address can be used
+instead, if defined; it takes the value of 
+.I $ADDRESS 
+as a parameter,
+which may be used or ignored as desired. At the time when this
+subroutine will be called, variables named $depth, 
+.I $title, 
+.I $file 
+hold
+the sectioning-level, title and filename of the 
+.B HTML 
+page being
+produced; 
+.I $FILE 
+holds the name of the filename for the title-page of
+the whole document.
+.TP
+.B -info <string>
+Same as setting:
+.I $INFO = "<string>";
+Generate a new section ``About this document'' containing information
+about the document 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.
+.SH 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.
+.TP
+.B -ascii_mode
+Same as setting:
+.I $ASCII_MODE = $EXTERNAL_IMAGES = 1;
+Use only ASCII characters and do not include any images in the final
+output. 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).
+.TP
+.B -nolatex
+Same as setting:
+.I $NOLATEX = 1;
+Disable the mechanism for passing unknown environments to 
+.B 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.)
+.TP
+.B -external_images
+Same as setting:
+.I $EXTERNAL_IMAGES = 1;
+Instead of including any generated images inside the document, leave
+them outside the document and provide hypertext links to them.
+.TP
+.B -ps_images
+Same as setting:
+.I $PS_IMAGES = $EXTERNAL_IMAGES = 1;
+Use links to external PostScript files rather than inlined images in
+the chosen graphics format.
+.TP
+.B -discard
+Same as setting:
+.I $DISCARD_PS = 1;
+The temporary PostScript files are discarded immediately after they
+have been used to create the image in the desired graphics format.
+.TP
+.B -no_images
+Same as setting:
+.I $NO_IMAGES = 1;
+Do not attempt to produce any inlined images. The missing images can be
+generated ``off-line'' by restarting 
+.B LaTeX2HTML 
+with the option
+-images_only .
+.TP
+.B -images_only
+Same as setting:
+.I $IMAGES_ONLY = 1;
+Try to convert any inlined images that were left over from previous
+runs of 
+.B LaTeX2HTML.
+.TP
+.B -reuse <reuse_option>
+Same as setting:
+.I $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 recycle image files.
+This choice also invokes an interactive session prompting the user
+about what to do about a pre-existing 
+.B 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.
+.TP
+.B -no_reuse
+Same as setting:
+.I $REUSE = 0;
+Do not share or recycle images generated 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 directory, delete its contents or quit.)
+.TP
+.B -antialias
+Same as setting:
+.I $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.
+.TP
+.B -antialias_text
+Same as setting:
+.I $ANTI_ALIAS_TEXT = 1; (Default is 1.)
+Generated images of typeset material such as text, mathematical
+formulas, 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.
+.TP
+.B -no_antialias
+Same as setting:
+.I $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.
+.TP
+.B -no_antialias_text
+Same as setting:
+.I $ANTI_ALIAS_TEXT = 0; (Default is 1.)
+Generated 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
+.TP
+.B -white
+Same as setting:
+.I $WHITE_BACKGROUND = 1; (Default is 1.)
+Ensures that images of figure environments have a white background.
+Otherwise transparency effects may not work correctly.
+.TP
+.B -no_white
+Same as setting:
+.I $WHITE_BACKGROUND = ''; (Default is 1.)
+Cancels the requirement that figure environments have a white
+background.
+.TP
+.B -ldump
+Same as setting:
+.I $LATEX_DUMP = 1; (Default is 0.)
+Use this if you want to speed up image processing during the 2nd and
+subsequent runs of 
+.B LaTeX2HTML 
+on the same document. The translator now
+produces a 
+.B LaTeX 
+format-dump of the preamble to images.tex which is
+used on subsequent runs. This significantly reduces the startup time
+when 
+.B LaTeX 
+reads the images.tex file for image-generation.
+This process actually consumes additional time on the first run, since
+.B 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
+.SH Switches controlling Navigation Panels
+The following switches govern whether to include one or more navigation
+panels on each 
+.B HTML 
+page, also which buttons to include within such a panel.
+.TP
+.B -no_navigation
+Same as setting:
+.I $NO_NAVIGATION = 1;
+Disable the mechanism for putting navigation links in each page.
+This overrides any settings of the 
+.I $TOP_NAVIGATION, 
+.I $BOTTOM_NAVIGATION
+and 
+.I $AUTO_NAVIGATION 
+variables.
+.TP
+.B -top_navigation
+Same as setting:
+.I $TOP_NAVIGATION = 1;
+Put navigation links at the top of each page.
+.TP
+.B -bottom_navigation
+Same as setting:
+.I $BOTTOM_NAVIGATION = 1;
+Put navigation links at the bottom of each page as well as the top.
+.TP
+.B -auto_navigation
+Same as setting:
+.I $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 
+.I $WORDS_IN_PAGE 
+number of words
+(default = 450).
+.TP
+.B -next_page_in_navigation
+Same as setting:
+.I $NEXT_PAGE_IN_NAVIGATION = 1;
+Put a link to the next logical page in the navigation panel.
+.TP
+.B -previous_page_in_navigation
+Same as setting:
+.I $PREVIOUS_PAGE_IN_NAVIGATION = 1;
+Put a link to the previous logical page in the navigation panel.
+.TP
+.B -contents_in_navigation
+Same as setting:
+.I $CONTENTS_IN_NAVIGATION = 1;
+Put a link to the table-of-contents in the navigation panel if there is
+one.
+.TP
+.B -index_in_navigation
+Same as setting:
+.I $INDEX_IN_NAVIGATION = 1;
+Put a link to the index-page in the navigation panel if there is an
+index.
+.SH 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 generate 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 hyperlinks. 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.
+.TP
+.B -up_url <URL>
+Same as setting:
+.I $EXTERNAL_UP_LINK = "<URL>";
+Specifies a universal resource locator (URL) to associate with the
+``UP'' button in the navigation panel(s).
+.TP
+.B -up_title <string>
+Same as setting:
+.I $EXTERNAL_UP_TITLE = "<string>";
+Specifies a title associated with this URL.
+.TP
+.B -prev_url <URL>
+Same as setting:
+.I $EXTERNAL_PREV_LINK = "<URL>";
+Specifies a URL to associate with the ``PREVIOUS'' button in the
+navigation panel(s).
+.TP
+.B -prev_title <string>
+Same as setting:
+.I $EXTERNAL_PREV_TITLE = "<string>";
+Specifies a title associated with this URL.
+.TP
+.B -down_url <URL>
+Same as setting:
+.I $EXTERNAL_DOWN_LINK = "<URL>";
+Specifies a URL for the ``NEXT'' button in the navigation panel(s).
+.TP
+.B -down_title <string>
+Same as setting:
+.I $EXTERNAL_DOWN_TITLE = "<string>";
+Specifies a title associated with this URL.
+.TP
+.B -contents <URL>
+Same as setting:
+.I $EXTERNAL_CONTENTS = "<URL>";
+Specifies a URL for the ``CONTENTS'' button, for document segments that
+would not otherwise have one.
+.TP
+.B -index <URL>
+Same as setting:
+.I $EXTERNAL_INDEX = "<URL>";
+Specifies a URL for the ``INDEX'' button, for document segments that
+otherwise would not have an index.
+.TP
+.B -biblio <URL>
+Same as setting:
+.I $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 difficult 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 (_).
+.SH 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 -verbosity will each
+cause 
+.B LaTeX2HTML 
+to generate more output to the screen. These extra messages
+should help to locate the cause of the problem.
+.TP
+.B -tmp <path>
+Define a temporary directory to use for image generation. If <path> is
+0, the standard temporary directory /tmp is used.
+.TP
+.B -h(elp)
+Print out the list of all command-line options.
+.TP
+.B -v
+Print the current version of 
+.B LaTeX2HTML.
+.TP
+.B -debug
+Same as setting:
+.I $DEBUG = 1;
+Run in debug-mode, displaying messages and/or diagnostic information
+about files read, and utilities called by 
+.B LaTeX2HTML.
+Shows any
+messages produced by these calls.
+More extensive diagnostics, from the 
+.B Perl 
+debugger, can be obtained by
+appending the string `-w-' to the 1st line of the latex2html (and
+other) 
+.B Perl 
+script(s).
+.TP
+.B -verbosity <num>
+Same as setting:
+.I $VERBOSITY = <num>;
+Display messages revealing certain aspects of the processing performed
+by 
+.B 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
+produced.
+.TP
+0.   
+No special tracing; as for versions of 
+.B LaTeX2HTML 
+prior to V97.1.
+.TP
+1.   
+(This is the default.) Show section-headings and the corresponding
+HTML file names, and indicators that major stages in the
+processing have been completed.
+.TP
+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.
+.TP
+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.
+.TP
+4.   
+Indicate command-substitution the pre-process of
+math-environments. Print the contents of unknown environments for
+processing in 
+.B LaTeX, 
+both before and after reverting to 
+.B LaTeX
+source. Show all operations affecting the values of counters. Also
+show links, labels and sectioning keys, at the stages of
+processing.
+.TP
+5.   
+Detail the processing in the document preamble. Show substitutions
+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.
+.TP
+6.   
+Show replacements of new commands, accents and wrapped commands.
+.TP
+7.   
+Trace the processing of commands in math mode; both before and
+after.
+.TP
+8.   
+Trace the processing of all commands, both before and after.
+The command-line option sets an initial value only. During processing
+the value of 
+.I $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>}.
+.SH Other Configuration Variables, without switches
+The configuration variables described here do not warrant having a
+command-line switch to assign values. Either they represent aspects of
+.B LaTeX2HTML 
+that are specific to the local site, or they govern properties
+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.
+.TP
+.B $dd
+holds the string to be used in file-names to delimit directories; 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 initialisation
+file, since its value needs to be known in order to find such a file.
+.TP
+.B $LATEX2HTMLDIR
+Read by the install-test script from latex2html.config, its value is
+inserted into the latex2html 
+.B Perl 
+script as part of the installation
+process.
+.TP
+.B $LATEX2HTMLSTYLES = "$LATEX2HTMLDIR/styles";
+Read from the latex2html.config file by install-test, its value is
+checked to locate the styles/ directory.
+.TP
+.B $LATEX2HTMLVERSIONS = "$LATEX2HTMLDIR/versions";
+The value of this variable should be set within latex2html.config to
+specify the directory path where the version and extension files can be
+found.
+.TP
+.B $ALTERNATIVE_ICONS = '';
+This may contain the (relative) directory path to a set of customised
+icons to be used in conjunction with the -local_icons switch.
+.TP
+.B $TEXEXPAND = "$LATEX2HTMLDIR/texexpand";
+Read by the install-test 
+.B Perl 
+script from latex2html.config, its value
+is used to locate the texexpand 
+.B Perl 
+script.
+.TP
+.B $PSTOIMG = "$LATEX2HTMLDIR/pstoimg";
+Read by the install-test 
+.B Perl 
+script from latex2html.config, its value
+is used to locate the pstoimg 
+.B Perl 
+script.
+.TP
+.B $IMAGE_TYPE = '<image-type>';
+Set in latex2html.config, the currently supported <image-type>s are:
+gif and png.
+.TP
+.B $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 normally
+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.
+.RS
+.TP
+.B $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).
+.TP
+.B $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.
+.TP
+.B $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.
+.RE
+.TP
+.B $LATEX = 'latex';
+Read from latex2html.config by install-test, its value is checked to
+locate the latex program or script.
+If 
+.B LaTeX 
+is having 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. 
+.I $LATEX = 'setenv TEXINPUTS <path to search> ; latex' .
+There are several variables to help control exactly which files are
+read by 
+.B LaTeX2HTML 
+and by 
+.B LaTeX 
+when processing images:
+.RS
+.TP
+.B $TEXINPUTS
+This is normally set from the environment variable of the same
+name. If difficulties occur so that styles and packages are not
+being found, then extra paths can be specified here, to resolve
+these difficulties.
+.TP
+.B $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.)
+.TP
+.B $DO_INCLUDE = '';
+List of exceptions within the 
+.I $DONT_INCLUDE 
+list. These files are
+to be read if requested by an \\input or \\include command.
+.RE
+.TP
+.B $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
+customised 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 
+.B HTML 
+files and other generated images, the value of
+$ICONSERVER is not needed within the 
+.B HTML 
+files themselves. However it
+is needed to find the original icons to be copied to the local
+directory.
+.TP
+.B $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.
+.TP
+.B $LINKNAME = '"index.$EXTN"';
+This is used when the 
+.I $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 
+.B HTML 
+file which will
+be automatically linked to the directory name.
+The value of 
+.I $EXTN 
+is .html unless 
+.I $SHORTEXTN 
+is set, in which case it
+is .htm .
+.TP
+.B $LINKPOINT = '"$FILE$EXTN"';
+This specifies the name of the 
+.B HTML 
+file to be duplicated, or
+symbolically linked, with the name specified in 
+.I $LINKNAME.
+At 
+the appropriate time the value of 
+.I $FILE 
+is the document name, which
+usually coincides with the name of the working directory.
+.TP
+.B $CHARSET = 'iso_8859_1';
+This specifies the character set used within the 
+.B HTML 
+pages produced by
+.B LaTeX2HTML.
+If no value is set in a configuration or initialisation
+file, the default value will be assumed. The lowercase form 
+.I $charset 
+is
+also recognised, but this is overridden by the uppercase form.
+.TP
+.B $ACCENT_IMAGES = 'large';
+Accented characters that are not part of the ISO-Latin fonts can be
+generated by making an image using 
+.B LaTeX. 
+This variable contains a
+(comma-separated) list of 
+.B 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 
+.I $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 consistency of style within documents located at the same site, or
+sites in close proximity.
+.TP
+.B $default_language = 'english';
+This establishes which language code is to be placed within the
+<!DOCTYPE ... > tag that may appear at the beginning of the 
+.B HTML 
+pages
+produced. Loading a package for an alternative language can be expected
+to change the value of this variable.
+See also the 
+.I $TITLES_LANGUAGE 
+variable, described next.
+.TP
+.B $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. Loading such a package will normally alter the value of this
+variable, as well as the 
+.I $default_language 
+variable described above.
+.TP
+.B $WORDS_IN_NAVIGATION_PANEL_TITLES = 4;
+Specifies how many words to use from section titles, within the textual
+hyperlinks which accompany the navigation buttons.
+.TP
+.B $WORDS_IN_PAGE = 450;
+Specifies the minimum page length required before a navigation panel is
+placed at the bottom of a page, when the 
+.I $AUTO_NAVIGATION 
+variable is
+set.
+.TP
+.B $CHILDLINE = "<BR><HR>\\n";
+This gives the 
+.B HTML 
+code to be placed between the child-links table and
+the ordinary contents of the page on which it occurs.
+.TP
+.B $NETSCAPE_HTML = 0;
+When set, this variable specifies that 
+.B 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.
+.TP
+.B $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 overridden by the \\bodytext command, and can be added-to
+or parts changed using the \\htmlbody command or \\color and \\pagecolor
+from the color package.
+.TP
+.B $INTERLACE = 1;
+When set, interlaced images should be produced.
+This requires graphics utilities to be available to perform the
+interlacing operation.
+.TP
+.B $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.
+.TP
+.B $FIGURE_SCALE_FACTOR = 1.6;
+Scale factor applied to all images of figure and other environments,
+when being made into an image.
+Note that this does not apply to recognised mathematics environments,
+which instead use the contents of 
+.I $MATH_SCALE_FACTOR 
+and
+$DISP_SCALE_FACTOR to specify scaling.
+.TP
+.B $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.
+.TP
+.B $DISP_SCALE_FACTOR = 1;
+Extra scale factor applied to images of displayed math environments.
+When set, this value multiplies 
+.I $MATH_SCALE_FACTOR 
+to give the total
+scaling. A value of `1.2' is a good choice to accompany
+$MATH_SCALE_FACTOR = 1.4;.
+.TP
+.B $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 
+.I $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.
+.TP
+.B $PAPERSIZE = 'a5';
+Specifies the size of a page for typesetting figures or displayed 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 
+.I $DISP_SCALE_FACTOR 
+scaling factors are being
+used, else some images may become excessively large, including a lot of
+blank space.
+.TP
+.B $LINE_WIDTH = 500;
+Formerly specified the width of an image, when the contents were to be
+right- or center-justified. (No longer used.)
+.PP
+The following variables are used to access the utilities required during
+image-generation. File and program locations on the local system are
+established by the configure-pstoimg 
+.B Perl 
+script and stored within
+.I $LATEX2HTMLDIR/local.pm 
+as 
+.B 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.
+.PP
+ $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';
+.SH "SEE ALSO"
+.BR latex (1)
+.SH 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 Manoj Srivastava <srivasta@debian.org>,
+for the Debian GNU/Linux system, based on the LaTeX documentation
+accompanying the program.