Installing LATEX2HTML

Installing L^ATEX2`HTML`

To install L^ATEX2HTML you MUST do the following:

Specify where Perl is on your system.
In each of the files latex2html, texexpand, pstoimg, install-test and makemap, modify the first line saying where Perl is on your system.

Some system administrators do not allow Perl programs to run as shell scripts. This means that you may not be able to run any of the above programs. In this case change the first line in each of these programs from
#!/usr/local/bin/perl
to:
```
# *-*-perl-*-*
    eval 'exec perl -S  $0 "$@"'
    if $running_under_some_shell;
```
Copy the files to the destination directory.
Copy the contents of the texinputs/ directory to a place where they will be found by L^ATEX, or set up your TEXINPUTS variable to point to that directory.
Run install-test.
This Perl script will make some changes in the latex2html file and then check whether the path-names to any external utilities required by latex2html are correct. It will not actually install the external utilities. install-test asks you whether to configure for GIF or PNG image generation. Finally it creates the file local.pm which houses pathnames for the external utilities determined earlier.

You might need to make install-test executable before using it.
Use chmod +x install-test to do this.

You may also need to make the files pstogif, texexpand, configure-pstoimg and latex2html executable if install-test fails to do it for you.
If you like so, copy or move the latex2html executable script to some location outside the $LATEX2HTMLDIR directory.
You might want to edit latex2html.config to reflect your needs. Read the instructions about $ICONSERVER carefully to make sure your HTML documents will be displayed right via the Web server.
While you're at it you may want to change some of the default options in this file.
If you do a system installation for many users, only cope with general aspects; let the user override these with $HOME/.latex2html-init.

Note that you must run install-test now; formerly you could manage without. If you want to reconfigure L^ATEX2HTML for GIF/PNG image generation, or because some of the external tools changed the location, simply rerun configure-pstoimg.

This is usually enough for the main installation, but you may also want to do some of the following, to ensure that advanced features of L^ATEX2HTML work correctly on your system:

To use the new L^ATEX commands which are defined in html.sty:
Make sure that L^ATEX knows where the html.sty file is, either by putting it in the same place as the other style-files on your system, or by changing your TEXINPUTS shell environment variable, or by copying html.sty into the same directory as your L^ATEX source file.
The environment variable TEXINPUTS is not to be confused with the L^ATEX2HTML installation variable $TEXINPUTS described next.
There is an installation variable in latex2html.config called $TEXINPUTS, which tells L^ATEX2HTML where to look for L^ATEX style-files to process. It can also affect the input-path of L^ATEX when called by L^ATEX2HTML, unless the command latex is really a script which overwrites the $TEXINPUTS variable prior to calling the real latex. This variable is overridden by the environment variable of the same name if it is set.
The installation variable $PK_GENERATION specifies which fonts are used in the generation of mathematical equations. A value of ``0'' causes the same fonts to be used as those for the default printer. Because they were designed for a printer of much greater resolution than the screen, equations will generally appear to be of a lower quality than is otherwise possible. To cause L^ATEX2HTML to dynamically generate fonts that are designed specifically for the screen, you should specify a value of ``1'' for this variable. If you do, then check to see whether your version of dvips supports the command-line option -mode . If it does, then also set the installation variable $DVIPS_MODE to a low resolution entry from modes.mf, such as toshiba.
It may also be necessary to edit the MakeTeXPK script, to recognise this mode at the appropriate resolution.
If you have PostScript fonts available for use with L^ATEX and dvips then you can probably ignore the above complications and simply set $PK_GENERATION to ``0'' and $DVIPS_MODE to "" (the empty string). You must also make sure that gs has the locations of the fonts recorded in its gs_fonts.ps file. This should already be the case where GS-Preview is installed as the viewer for .dvi-files, using the PostScript fonts.
If dvips does not support the -mode switch, then leave $DVIPS_MODE undefined, and verify that the .dvipsrc file points to the correct screen device and its resolution.
The installation variable $AUTO_PREFIX allows the filename-prefix to be automatically set to the base filename-prefix of the document being translated. This can be especially useful for multiple-segment documents.
The makemap script also has a configuration variable $SERVER, which must be set to either CERN or NCSA, depending on the type of Web-server you are using.
To set up different initialization files:
For a ``per user'' initialization file, copy the file dot.latex2html-init in the home directory of any user that wants it, modify it according to her preferences and rename it as .latex2html-init. At runtime, both the latex2html.config file and $HOME/.latex2html-init file will be loaded, but the latter will take precedence.

You can also set up a ``per directory'' initialization file by copying a version of .latex2html-init in each directory you would like it to be effective. An initialization file /X/Y/Z/.latex2html-init will take precedence over all other initialization files if /X/Y/Z is the ``current directory'' when L^ATEX2HTML is invoked.

Warning: This initialization file is incompatible with any version of L^ATEX2HTML prior to V96.1. Users must either update this file in their home directory, or delete it altogether.
To make your own local copies of the L^ATEX2HTML icons:
Please copy the icons/ subdirectory to a place under your WWW tree where they can be served by your server. Then modify the value of the $ICONSERVER variable in latex2html.config accordingly. Alternatively, a local copy of the icons can be included within the subdirectory containing your completed HTML documents. This is most easily done using the -local_icons command-line switch, or by setting $LOCAL_ICONS to ``1'' in latex2html.config or within an initialization file, as described above.

Warnings: If you cannot do that, bear in mind that these icons will have to travel from Livermore, California!!! Also note that several more icons were added in V96.1 that were not present in earlier versions of L^ATEX2HTML.
To make your own local copy of the L^ATEX2HTML documentation:
This will also be a good test of your installation. Firstly, to obtain the .dvi version for printing, from within the docs/ directory it is sufficient to type:
make manual.dvi
This initiates the following sequence of commands:
```
latex manual.tex
makeindex -s l2hidx.ist manual.idx
makeindex -s l2hglo.ist -o manual.gls manual.glo
latex manual.tex
latex manual.tex
```
...in which the two configuration files l2hidx.ist and l2hglo.ist for the makeindex program, are used to create the index and glossary respectively. The 2nd run of latex is needed to assimilate references, etc. and include the index and glossary.

(In case makeindex is not available, a copy of its outputs manual.ind and manual.gls are included in the docs/ subdirectory, along with manual.aux.)
The 3rd run of latex is needed to adjust page-numbering for the Index and Glossary within the Table-of-Contents.
Next, the HTML version is obtained by typing:
make manual.html
This initiates a series of calls to L^ATEX2HTML on the separate segments of the manual; the full manual is thus created as a ``segmented document'' (see a later section). The whole process may take quite some time, as each segment needs to be processed at least twice, to collect the cross-references from other segments.

The files necessary for correct typesetting of the manual to be found within the docs/ subdirectory. They are as follows:
- style-files: l2hman.sty, html.sty, htmllist.sty, justify.sty,
  changebar.sty and url.sty
- inputs: changes.tex, credits.tex, features.tex, hypextra.tex,
  licence.tex, manhtml.tex, manual.tex, overview.tex,
  problems.tex, support.tex and userman.tex
- sub-directory: psfiles/ containing PostScript graphics used in the printed version of this manual
- images of small curved arrows: up.gif, dn.gif
- filename data: l2hfiles.dat
- auxiliaries: manual.aux, manual.ind, manual.gls
The last three can be derived from the others, but are included for convenience.
To get a printed version of the `Changes' section:
Due to the burgeoning size of the Changes file with successive revisions of L^ATEX2HTML, the `Changes' section is no longer supported for the manual. Please refer to text file Changes instead which is part of the distribution.
To join the community of L^ATEX2HTML users:
More information on a mailing list, discussion archives, bug reporting forms and more is available at http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html

^99.1
L^ATEX2HTML is actively supported by the international TEX Users Group (TUG). All users are encouraged to join TUG, to keep up-to-date with the latest development in TEX, L^ATEX, L^ATEX2HTML and related programs. Consult the TUG Web pages at http://www.tug.org/.
^99.1