-' 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 and 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 = " <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. -- cgit v1.2.3

From 62f0eed75606a0c15108a9ce9931282a30d0961f Mon Sep 17 00:00:00 2001 From: Ying-Chieh Liao Date: Tue, 17 Sep 2002 16:44:15 +0000 Subject: add manpage (grab from Debian) PR: 35249 Submitted by: Fred --- textproc/latex2html/Makefile | 4 + textproc/latex2html/files/latex2html.1 | 1284 ++++++++++++++++++++++++++++++++ 2 files changed, 1288 insertions(+) create mode 100644 textproc/latex2html/files/latex2html.1 (limited to 'textproc/latex2html') 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 +.\" +.\" 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 +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 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 and 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 = " <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. -- cgit v1.2.3