Installation and Further Support

Requirements

The translator makes use of several utilities all of which are freely available on most platforms.

You can choose between two ways to do the installation of the required tools: either go the convenient way and install binary distributions (no compilation required, just install out of the box), or get and compile a source code distribution. You will stick to the latter in case you have a special kind of operating system or want to make customisations prior to compilation such as applying source level patches. Windows users will probably want to read the section about installation on Windows.

For the best use of L^ATEX2HTML you want to get the latest versions of all the utilities that it uses. (It will still work with earlier versions, but some special effects may not be possible. The specific requirements are discussed below.)

• Perl version 5.003, or later (check with perl -v);
• L^ATEX, meaning L^ATEX2_e dated <1995/06/01>, or later;
• dvips or dvipsk, at version 5.58 or later;
• Ghostscript at version 4.02 or later;
• netpbm library of graphics utilities, version 1-MAR-94
  (check with pnmcrop -version ).
• pdftocairo, if you want to produce SVG images (available through the poppler-utils package)

More specific requirements for using L^ATEX2HTML depend on the kind of translation you would like to perform, as follows:

1. L^ATEX commands but without equations, figures, tables, etc.
   • Perl Note: L^ATEX2HTML requires Perl 5 to operate.

   • DBM or NDBM, the Unix DataBase Management system, or GDBM, the GNU database manager.

     Note: Some systems lack any DBM support. Perl 5 comes with its own database system SDBM, but it is sometimes not part of some Perl distributions.

     The installation script install-test will check that for you. If no database system is found, you will have to install Perl properly.

2. L^ATEX commands with equations, figures, tables, etc.
   As above plus ...
   • latex (version 2e recommended but 2.09 will work — with reduced ability to support styles and packages);
   • (version 5.516 or later) or dvipsk
     Version 5.62 or higher enhances the performance of image creation with a significant speed-up. See latex2html.config for this after you are done with the installation. Do not use the 'dvips -E' feature unless you have 5.62, else you will get broken images.
   • gs Ghostscript (version 4.03 or later); with the ppmraw device driver, or even better pnmraw. Upgrade to 5.10 or later if you want to go sure about seldom problems with 4.03 to avoid (yet unclarified).
   • The library of graphics utilities; netpbm dated 1 March 1994 is required, else part of the image creation process will fail.
     Check with: pnmcrop -version .

     Several of the filters in those libraries are used during the PostScript to GIF conversion.

   • If you want PNG images, you need pnmtopng (current version is 2.31). It is not part of netpbm and requires libpng-0.89c.tar.gz and libz (1.0.4) (or later versions). pnmtopng supports transparency and interlace mode.
     Netscape Navigator as well as MS IE do support inlined PNG images.

3. Segmentation of large documents
   If you wish to use this feature, you will have to upgrade your L^ATEX to L^ATEX2_e . Some other hyperlinking features also require L^ATEX2_e .

4. Transparent inlined images
   If you dislike the white background color of the generated inlined images then you should get either the netpbm library (instead of the older pbmplus) or install the giftrans filter by Andreas Ley <ley@rz.uni-karlsruhe.de>. L^ATEX2HTML now supports the shareware program giftool (by Home Pages, Inc., version 1.0), too. It can also create interlaced GIFs.

If Ghostscript or the netpbm library are not available, it is still possible to use the translator with the -no_images option.

If you intend to use any of the special features of the translator then you have to include the html.sty file in any L^ATEX documents that use them.

If only a character-based browser, such as lynx, is available, or if you want the generated documents to be more portable, then the translator can be used with the -ascii_mode option.

Installation on Windows

For Windows 95, 98, and NT you will either need a newer html Release 99.1 or higher, or if you like to try an older release get the Windows 97.1 port by Fabrice Popineau from ftp://ftp.ese-metz.fr/pub/TeX/win32. Meanwhile, all the operating system dependent issues are integrated into the main release, thanks to the cool work of Marek Rouchal.

To install the tools required to run the translator, perform the steps below. Thanks to Jens Berger (jberger@mail.zedat.fu-berlin.de) for providing this list!

• install WinZip;
• install TEX/L^ATEX2_e and dvips;
• install Perl;
  E.g. ActivePerl 509 or higher from http://www.activestate.com. Windows 95 users will also need DCOM, it is listed on that download page, too.
• install GhostScript;
  E.g. Aladdin GhostScript 5.50.
• install the NetPBM tools library from ftp://ftp.ese-metz.fr/pub/TeX/win32/.
• unpack L^ATEX2HTML, e.g. under C:\TEXMF\LATEX2HTML;
• check that the path to GSWIN32C.EXE is added to the PATH variable in your AUTOEXEC.BAT;
• with L^ATEX2HTML 99.1 or higher, edit l2hconf.pin, then run CONFIG.BAT to install the translator;
  with older releases, edit LATEX2HTML.CONFIG and run

    cd c:\texmf\latex2html
    perl install-test
  

  from within a DOS box.
• you might want to write a small .BAT file in your L^ATEX2HTML directory:

    perl c:\texmf\latex2html\latex2html %1 %2 %3 >> l2h.log
    

  %1 is the name of the .TEX file, %2 and %3 are optional arguments to the translator such as -"-split 3" .
  Note that if you want more than two arguments you will need to supply more parameters to the .BAT file.
• run it with a test document test.tex:

     l2h test
  

  Maybe you will need to run L^ATEX before this, too!

Getting L^ATEX2HTML

L^ATEX2HTML is available through the Fedora, Debian, and Ubuntu package managers for Linux, and the macports package manager for MacOS.

Releases of L^ATEX2HTML may also be obtained at https://www.github.com/latex2html/latex2html/releases ,

Finally there is the L^ATEX2HTML developers' source repository, at https://www.github.com/latex2html/latex2html/ .
The files to be found here are the most up-to-date with current developments, but they cannot be guaranteed to be fully reliable. New features may be still under development and not yet sufficiently tested for release. A daily updated compressed archive of the developers' work may be downloaded from https://www.github.com/latex2html/latex2html/archive/master.zip .

Having obtained a compressed tar version, save it into a file latex2html-2019.tar.gz say, then extract its contents with

% gzip -d latex2html-2019.tar.gz
% tar xvf latex2html-2019.tar

You should then have the following:

• README file;
• Changes index with latest changes;
• Changes.detailed (no longer supplied);
• latex2html Perl script;
• texexpand Perl script⁴;
• latex2html.config configuration file;
• install-test Perl script, for installation and testing;
• dot.latex2html-init sample initialisation file;
• texinputs/ subdirectory, containing various L^ATEX style-files;
• versions/ subdirectory, containing code for specific HTML versions;
• makemap Perl script;
• example/ subdirectory, containing the segmentation example, described in detail in a later section;
• .dvipsrc file;
• pstogif Perl script (no longer supplied);
• pstoimg Perl script for image conversion (replaces pstogif);
• configure-pstoimg Perl script for installation;
• local.pm Perl input file;
• icons.gif/ subdirectory, containing icons in GIF format;
• icons.png/ subdirectory, containing icons in PNG format;
• makeseg Perl script and examples to handle segmented documents via a generated Makefile, see makeseg.tex;
• docs/foilhtml/ contains L^ATEX package and Perl implementation by Boris Veytsman, to support FoilTeX to HTML translation;
• IndicTeX-HTML/ package that contains Perl and L^ATEX code for translating IndicTEX documents (see README file);
• docs/ subdirectory, containing the files needed to create a version of this manual;
• styles/ subdirectory, containing Perl code for handling some style-files;
• tests/ contains some test documents for L^ATEX2HTML.

Installing L^ATEX2HTML

To install L^ATEX2HTML 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 L^ATEX, 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 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.

• 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<sup>A</sup>TEX2HTML, 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 https://www.latex2html.org/

• L^ATEX2HTML is actively supported by the international TEX Users Group (http://www.tug.org). All users are encouraged to join http://www.tug.org, 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/.

Getting Support and More Information

A L^ATEX2HTML mailing list is managed by the international TEX User Group (http://www.tug.org).

This mailing used was originally established at the Argonne National Labs, where it was based for several years. (Thanks to Ian Foster and Bob Olson, and others.) Since February 1999, it has been run by http://www.tug.org, thanks to Art Ogawa and Ross Moore.

To join send a message to: <latex2html-request@tug.org >
with the contents:   subscribe

To be removed from the list send a message to: <latex2html-request@tug.org >
with the contents:   unsubscribe

The mailing list also has a searchable online archive. It is recommended to start with this, to become familiar with the topics actually discussed, and to search for articles related to your own interests.

Enjoy!