##
Installing LATEX2`HTML`

To install LATEX2`HTML` you MUST do the following:

1. 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;

2. Copy the files to the destination directory.
   Copy the contents of the `texinputs/` directory to a place where they will be found by LATEX, or set up your `TEXINPUTS` variable to point to that directory.

3. 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.

4. If you like so, copy or move the `latex2html` executable script to some location outside the `$LATEX2HTMLDIR` directory.

5. 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 LATEX2`HTML` 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 LATEX2`HTML` work correctly on your system:

- To use the new LATEX commands which are defined in `html.sty`:
  Make sure that LATEX 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 LATEX source file.

  The environment variable `TEXINPUTS` is not to be confused with the LATEX2`HTML` installation variable `$TEXINPUTS` described next.

- There is an installation variable in `latex2html.config` called `$TEXINPUTS`, which tells LATEX2`HTML` where to look for LATEX style-files to process. It can also affect the input-path of LATEX when called by LATEX2`HTML`, 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 LATEX2`HTML` 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 LATEX 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 LATEX2`HTML` is invoked.

  > Warning: This initialization file is incompatible with any version of LATEX2`HTML` 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 LATEX2`HTML` 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 LATEX2`HTML`.

- To make your own local copy of the LATEX2`HTML` 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 LATEX2`HTML` 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 LATEX2`HTML`, 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 LATEX2`HTML` 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

- LATEX2`HTML` 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, LATEX, LATEX2`HTML` and related programs. Consult the TUG Web pages at `http://www.tug.org/`.
  99.1