Description: Separately provided man pages This patch includes man pages for latex2html and texexpand which are provided by Debian in spite of latex2html providing own versions of those. Debian is providing them for several years now and they still seem to be more extensive than the native ones. So we will keep them until the upstream versions can replace them safely. Author: Roland Stigge --- /dev/null +++ latex2html-2008-debian1/texexpand.1 @@ -0,0 +1,388 @@ +.rn '' }` +.de Sh +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp +.if t .sp .5v +.if n .sp +.. +.de Ip +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.de Vb +.ft CW +.nf +.ne \\$1 +.. +.de Ve +.ft R + +.fi +.. +.ie n \{\ +.ds -- \(*W- +.ds PI pi +.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +.ds L" "" +.ds R" "" +.ds M" """ +.ds S" """ +.ds N" """"" +.ds T" """"" +.ds L' ' +.ds R' ' +.ds M' ' +.ds S' ' +.ds N' ' +.ds T' ' +'br\} +.el\{\ +.ds -- \(em\| +.tr \*(Tr +.ds L" `` +.ds R" '' +.ds M" `` +.ds S" '' +.ds N" `` +.ds T" '' +.ds L' ` +.ds R' ' +.ds M' ` +.ds S' ' +.ds N' ` +.ds T' ' +.ds PI \(*p +'br\} +.\" If the F register is turned on, we'll generate +.\" index entries out stderr for the following things: +.\" TH Title +.\" SH Header +.\" Sh Subsection +.\" Ip Item +.\" X<> Xref (embedded +.\" Of course, you have to process the output yourself +.\" in some meaninful fashion. +.if \nF \{ +.de IX +.tm Index:\\$1\t\\n%\t"\\$2" +.. +.nr % 0 +.rr F +.\} +.TH TEXEXPAND 1 "perl 5.005, patch 03" "29/Jan/2000" "User Contributed Perl Documentation" +.UC +.if n .hy 0 +.if n .na +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.de CQ \" put $1 in typewriter font +.ft CW +'if n "\c +'if t \\&\\$1\c +'if n \\&\\$1\c +'if n \&" +\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 +'.ft R +.. +.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2 +. \" AM - accent mark definitions +.bd B 3 +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds ? ? +. ds ! ! +. ds / +. ds q +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10' +. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#] +.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u' +.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u' +.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#] +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +.ds oe o\h'-(\w'o'u*4/10)'e +.ds Oe O\h'-(\w'O'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds v \h'-1'\o'\(aa\(ga' +. ds _ \h'-1'^ +. ds . \h'-1'. +. ds 3 3 +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +. ds oe oe +. ds Oe OE +.\} +.rm #[ #] #H #V #F C +.SH "NAME" +texexpand \- expand \einput and \einclude statements in a TeX file +.SH "DESCRIPTION" +General translation mechanism: +.PP +The main program latex2html calls texexpand with the document name +in order to expand some of its \einput and \einclude statements, here +also called \*(L'merging\*(R', and to write a list of sensitized style, class, +input, or include file names. +When texexpand has finished, all is contained in one file, TMP_foo. +(assumed foo.tex is the name of the document to translate). +.PP +In this version, texexpand cares for following environments +that may span include files / section boundaries: +a) \ebegin{comment} +b) \f(CW%begin\fR{comment} +c) \ebegin{any} introduced with \eexcludecomment +d) \f(CW%begin\fR{any} +e) \ebegin{verbatim} +f) \ebegin{latexonly} +g) \f(CW%begin\fR{latexonly} +.PP +e) \- g) prevent texexpand from expanding input files, but the environment +content goes fully into the output file. +.PP +Together with each merging of \einput etc. there are so-called %%%texexpand +markers accompanying the boundary. +.PP +When latex2html reads in the output file, it uses these markers to write +each part to a separate file, and process them further. +.Sh "Detailed technical notes:" +1. \f(CW%begin\fR{latexonly} and \f(CW%end\fR{latexonly} have to be on a separate line. +Anything between these tags (including the tags) is discarded. +.PP +2. \ebegin{latexonly} and \eend{latexonly} have to be on a separate line. +Anything between these tags (including the tags) is not expanded. +.PP +3. [%\e]begin{"to exclude"} and [%\e]end{"to exclude"} have to be on a +separate line. +Anything between these tags (including the tags) is discarded. +.PP +4. \ebegin{verbatim/verbatim*} and \eend{verbatim/verbatim*} have to be +on a separate line. +Anything between these tags (including the tags) is not expanded. +.PP +5. The scope of any such tags may extend over several files. +The opening tag for latexonly may occur on a different include level +than the closing tag. +The opening tag for verbatim/"to exclude\*(R" must occur within the same +file than the closing tag. +.PP +6. Warnings are printed when the document has been parsed and open +tags remain. +.PP +7. When in a \*(L"to exclude"/verbatim environment, texexpand won't recognize +\s-1ANY\s0 command except the corresponding closing tag. +There cannot be any nested constructions. +This behaviour is identical to that of LaTeX. +.PP +8. \ebegin{latexonly},\eend{latexonly} may be nested, whereas +\f(CW%begin\fR{latexonly},%end{latexonly} may not be nested. +.PP +9. A \*(L"%\*(R" tag cannot close a \*(L"\e\*(R" tag, and vice versa. +.PP +10. Every \e\fIdocument\fR\|(class|style), \eusepackage, \einput and \einclude command +has to be on a separate line. +.PP +11. Everything behind a `%\*(R' that isn't preceded by a `\e\*(R' is regarded as +a comment, i.e. it is printed but not interpreted. +.PP +12. If any command listed in 10. is preceded by an occurence of `\everb\*(R' or +`\elatex\*(R' then it is \s-1NOT\s0 interpreted. This crashes on lines like this: +blah blah \everb+foo foo+ \einput{bar} % bar won't be loaded! +.PP +13. Packages provided via \eusepackage are handled the same way as +`options\*(R' in \e\fIdocument\fR\|(class|style), i.e. they are included when +\-auto_exclude is off, the package isn't in \f(CW@dont_include\fR *\s-1OR\s0* the +package is in \f(CW@do_include\fR (new). They are added to the style file +together with their options if the file itself hasn't been merged. +\edocumentclass[options]{class} searches for every option.clo, +\edocumentstyle[options]{style} searches for every option.sty. +\eusepackage[options]{packages} searches for every package.sty. +.PP +14. Each texinputs directory is searched for input files/styles. If it +ends in `//\*(R', the whole subdirectory tree is searched. +.PP +15. \einput / \einclude merge the given file (if found under the given +name or with .tex extension) if its basename is in \f(CW@do_include\fR or if it +isn't in \f(CW@dont_include\fR or if the given filename doesn't end in +\&.sty/.clo/.cls when \-auto_exclude is set. +.Sh "Notes" +Recognizes \edocumentclass, \edocumentstyle, \eusepackage, \eRequirePackage, +\ebegin{verbatim}...\eend{verbatim}, \f(CW%begin\fR{latexonly}...%end{latexonly}, +\ebegin{latexonly}...\eend{latexonly}, \einput, \einclude, \everb, \elatex +\eendinput, \eend{document} +\eincludecomment, \eexcludecomment +\ebegin{"to exclude"}, \eend{"to exclude"} +\f(CW%begin\fR{"to exclude"}, \f(CW%end\fR{"to exclude"} +.SH "The gory Details" +Include and parse a file. +This routine is recursive, see also &process_input_include_file, +&process_document_header, and &process_package_cmd. +.PP +Two global flags control the states of texexpand. + o \f(CW$active\fR is true if we should interprete the lines to expand +files, check for packages, etc. + o \f(CW$mute\fR is true if we should prevent the lines from going into the out file. +.PP +We have three general states of texexpand: + 1) interprete the lines and pass them to the out file +This is the normal case. Corresponding: \f(CW$active\fR true, \f(CW$mute\fR false +.PP +.Vb 3 +\& 2) interprete minimal and suppress them +\&This is when parsing inside a comment environment, which +\&also would retain its body from LaTeX. => $active false, $mute true +.Ve +.Vb 4 +\& 3) interprete minimal and pass the lines to the out file +\&This is inside a verbatim or latexonly environment. +\&The line of course must be at least interpreted to determine the closing tag. +\&=> $active false, $mute false +.Ve +Any environment may extend over several include files. +Any environement except verbatim and latexonly may have its +opening or closing tag on different input levels. +The comment and verbatim environments cannot be nested, as +is with LaTeX. +We must at least parse verbatim/comment environments in +latexonly environments, to catch fake latexonly tags. +.PP +The work scheme: +Five functions influence texexpand's behavior. +o &process_file opens the given file and parses the non-comment part in +order to set \f(CW$active\fR and \f(CW$mute\fR (see above). +It calls &interprete to interprete the non-comment content and either +continues with the next line of its file or terminates if &interprete +detected the \eend{document} or an \eendinput. +.PP +o &interprete handles some LaTeX tags with respect to the three states +controlled by \f(CW$active\fR and \f(CW$mute\fR. +Regarding to \einput|include, \e\fIdocument\fR\|(class|style), and +\e(use|Require)package the functions &process_input_include_file, +&process_document_header, and &process_package_cmd are called respectively. +.PP +o These three functions check if the file name or option files are enabled +or disabled for merging (via TEXE_DO_INCLUDE or TEXE_DONT_INCLUDE). +Any file that is to include will be \*(L'merged\*(R' into the current file, i.e. +the function &process_file is called at this place in time (recursively). +This will stop interpretation at the current line in file, start with the +new file to process and continues with the next line as soon as the new +file is interpreted to its end. +.PP +The call tree (noweb+xy.sty would be handy here): +.PP +.Vb 13 +\& main +\& | +\& v +\& +->process_file +\& | | +\& | v +\& | interprete (with respect to the current line, one of that three) +\& | | | | +\& | v v v +\& | process_input_include_file process_document_header process_package_cmd +\& | | | | +\& | v v v +\& +----+---------------------------+------------------------+ +.Ve +Bugs: +o Since the latexonly environment is not parsed, its contents +might introduce environments which are not recognized. +.PP +o The closing tag for latexonly is not found if hidden inside +an input file. +.PP +o One environment tag per line, yet! +.PP +o If I would have to design test cases for this beast I would +immediately desintegrate into a logic cloud. +.PP +Notes: +.PP +o Ok, I designed test cases for it. +Please refer to test \*(L'expand\*(R' of the regression test suite +in the developers\*(R' module of the l2h repository. +.PP +o \-unsegment feature: +In this (rare) case, the user wants to translate a segmented document +not in segments but in a whole (for testing, say). +We enable this by recognizing the \esegment command in &interprete, +causing the segment file to be treated like \einput but loosing the first +lines prior to \estartdocument (incl.), as controlled via \f(CW$segmentfile\fR. +On how to segment a document you are best guided by section +``Document Segmentation'\*(R' of the LaTeX2HTML manual. +.SH "CAVEATS" +This utility is automatically configured and built to work on the +local setup. If this setup changes (e.g. some of the external commands +are moved), the script has be be reconfigured. +.SH "Authors" +.PP +.Vb 8 +\& Based on texexpand by Robert Thau, MIT AI lab, including modifications by +\& Franz Vojik +\& Nikos Drakos +\& Sebastian Rahtz +\& Maximilian Ott +\& Martin Boyer +\& Herbert Swan +\& Jens Lippmann +.Ve + +.rn }` '' --- /dev/null +++ latex2html-2008-debian1/latex2html.1 @@ -0,0 +1,1294 @@ +.\" Hey, Emacs! This is an -*- nroff -*- source file. +.\" Copyright (c) 1997 Manoj Srivastava +.\" +.\" 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 documentation has been derived from the TeX manual, and may not be +up to date. Please refer to the online manual for authoritative +documentation. +.SH Options controlling Titles, File-Names and Sectioning +.TP +.B -t +Same as setting: +.I $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 +Same as setting: +.I $LONG_TITLES = ; +Instead of the standard names: node1.html, node2.html,... the filenames +for each +.B HTML +page are constructed from the first 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 +Same as setting: +.I $DESTDIR = ""; +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 +Same as setting: +.I $PREFIX = ""; +The 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 `-' 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 descendants, 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 historical 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 italicized. 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 canceled. 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 (italicized) 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: +.RS +.RS +.P +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. +.P +to prepend a path to a different version of dvips than normally +available as the system default (e.g. the printing requirements +are different). +.P +to append debugging switches, in case of poor quality images; +one can see which paths are being searched for fonts and other +resources. +.P +to prepend commands for setting path variables that dvips may need +in order to locate fonts or other resources. +.RE +.P +If automatic generation of fonts is required, using Metafont, the +following configuration variables are important. +.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. +.P +Within the color.perl package, the following two 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. +.P +.B $RGBCOLORFILE = 'rgb.txt'; +.P +.B $CRAYOLAFILE = 'crayola.txt'; +.P +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 = \(dq<BR><HR>\\\\n\(dq; +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 by Manoj Srivastava <srivasta@debian.org>, +for the Debian GNU/Linux system, based on the LaTeX documentation +accompanying the program.