LaTeX2HTML Version 96.1 : README

Contents
********

Overview
Pointers to the User Manual
Requirements
Installation
Support and More Information

Overview
********

The translator: 

 o breaks up a document into one or more components as specified by
   the user, 
 o provides optional iconic navigation panels on every page which
   contain links to other parts of the document,  
 o handles inlined equations, right-justified
   numbered equations, tables, or figures and any arbitrary environment, 
 o can produce output suitable for browsers that support inlined images
   or character based browsers (as specified by the user), 
 o handles definitions of new commands, environments, and theorems
   even when these are defined in external style files, 
 o handles footnotes, tables of contents, lists of figures and tables,
   bibliographies, and can generate an  index, 
 o translates cross-references into hyperlinks and extends the
   LaTeX cross-referencing mechanism to work not just
   within a document but between documents which may reside in
   remote locations, 
 o translates accent and special character
   commands to the equivalent ISO-LATIN-1
   character set where possible, 
 o recognizes hypertext links (to multimedia resources or arbitrary
   internet services such as sound/video/ftp/http/news) and links which
   invoke arbitrary program scripts, all expressed as
   LaTeX commands, 
 o recognizes conditional text which is intended only for the hypertext
   version, or only for the paper (DVI) version, 
 o can include raw HTML in a LaTeX document (e.g. in order to specify
   interactive forms), 
 o can deal sensibly at least with the Common LaTeX
   commands summarized at the back of the LaTeX blue
   book [1], 
 o will try and translate any document with embedded
   LaTeX commands irrespective of whether it is
   complete or syntactically legal. 

Pointers to the User Manual
***************************

The LaTeX2HTML program includes its own manual page. 
The manual page can be viewed by saying %nroff -man latex2html.  

See the online documentation at 
http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/
or the doc/latex2html.tex file for more information and examples.

See below on how to make your own local copy of the manual in HTML.

Requirements
************

Please consult the section "Requirements" of the online manual at
http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/
for more information as well as *active* links to any utilities
that you may require. You may use Archie to find the source code 
of any utilities you might need. Archie is at 
http://hoohoo.ncsa.uiuc.edu/cgi-bin/archie.html

The requirements for using LaTeX2HTML depend on the kind of
translation it is asked to perform as follows: 

 1. LaTeX commands but without equations, figures, tables, etc. 
    o Perl (version 4.0 - RCSfile: perl.c,v - Revision: 4.0.1.8 -
      Date: 1993/02/05 19:39:30 - Patch level: 36) 

      Warning: You really DO need Perl at patch level 36 or later
      Versions of LaTeX2HTML earlier than 0.7a4 work *only* with 
      Perl 4 at patch level 36. Later versions of  LaTeX2HTML work 
      both with Perl 4 at patch level 36 and Perl 5. *No* version 
      of LaTeX2HTML will work with Perl 4 at earlier patch levels.

    o DBM or NDBM, the Unix DataBase Management system.

 2. LaTeX commands with equations, figures, tables, etc. 
   As above plus 
    o latex (version 2e recommended but 2.09 acceptable), 
    o dvips (version 5.516 or later) or dvipsk. 
    o gs (Ghostscript version 2.6.1 or later), with the ppmraw
      device driver. 
    o The pbmplus OR netpbm library. Some of the filters in
      those libraries are used during the postscript to GIF conversion.

 3. Transparent inlined images
   If you dislike the ugly white background color of the generated inlined
   images then you should get either get the netpbm library (instead of
   the older pbmplus) OR install the giftrans filter by Andreas Ley
   <ley@rz.uni-karlsruhe.de>. Version 1.10.2 is known to work without
   problems but later versions should also be OK.
   Transparent image translation is done quickest if NETPBM *and*
   GIFTRANS is installed.
   Get GIFTRANS 1.11.1 from (randomly chosen site):
   ftp://gigaserv.uni-paderborn.de/ftp/disk4/unix/infosys/www/tools/imaging/giftrans/giftrans-1.11.1.tar.gz


Because by default the translator makes use of inlined images in the final
HTML output, it would be better to have a viewer which supports the <IMG>
tag, such as NCSA Mosaic. If only a character based browser is available or
if you want the generated documents to be more portable then the translator
can be used with the -ascii_mode option. 

If ghostscript or the pbmplus (or 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 LaTeX documents that
use them. 

Installation
************

Please consult the section "Installing LaTeX2HTML" of the online manual at
http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/
for more information.

To install LaTeX2HTML you MUST do the following: 

 1. Specify where Perl is on your system. 
   In each of the files latex2html, texexpand, pstogif and 
   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. Specify where the external utilities are on your system. 
   In the file latex2html.config give the correct pathnames for
   some directories (the LaTeX2HTML directory and the pbmplus or 
   netpbm library) and some executables (latex, dvips, gs).
   Note that it is possible to use LaTeX2HTML even if you don't have
   some of the external programs. While you're at it you may want to
   change some of the default options in the same file. 

 3. Run install-test. 
   This Perl script will make some changes in the latex2html file and
   then check whether the pathnames to any external utilities
   (specified during the previous step) are correct. It will not actually
   install the external utilities. 

   If for any reason you have trouble running install-test do not
   despair. Most of what it does is to do with checking your installation
   rather than actually installing anything. To do a manual installation just
   change the variable LATEX2HTMLDIR in the beginning of the file 
   latex2html to point to the directory where the LaTeX2HTML files
   can be found. 

This is enough for the main installation but you may also want to do some of
the following: 

 o 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 in the same directory as as your LaTeX source file. 

 o If you are a LaTeX 2.09 user, you will not be able to use
   the document segmentation feature, or the optional arguments to
   \htmladdimg, until you upgrade to LaTeX2e.
   To determine which version you have, type just 'latex'.
   If it prompts with '(C version 6.1)', you have LaTeX2e. Anyway, if you're
   not sure, ask the people who installed it.
   Alas, you *mustn't* upgrade LaTeX just to have the features, lots of
   documents do fine without them.
   You should try to translate manual.tex with LaTeX 2.09. Instead,
   invoke LaTeX2HTML with manual.tex directly.

 o On some systems, the command ``latex'' is really a shell script which sets
   some environment variables and calls the real LaTeX. If this is so, make
   sure that this shell script has '.' and '..' set for TEXINPUTS.
   This environment variable is not to be confused with the LaTeX2HTML
   installation variable $TEXINPUTS described next.

 o The installation variable HTML_VERSION in latex2html.config causes
   LaTeX2HTML to generate table in HTML and supports textual font
   size changes if it is set to 3.0.  Otherwise, tables will be
   processes in LaTeX and come out as GIF files.

 o There is an installation variable in latex2html.config
   called $TEXINPUTS, which tells LaTeX2HTML where to
   look for LaTeX input files to process. This variable is
   appended to the TEXINPUTS environment variable to make sure the
   translator finds all your files.

 o 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 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 possible.  To cause LaTeX2HTML 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'.
   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.

 o On certain Linux systems it is necessary to uncomment the line
   "use GDBM_File" in the latex2html and install-test scripts, to define
   the interface to the database management routines.

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

 o To set up different initialisation files: 
   For a ``per user'' initialisation 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'' initialisation file by copying a
   version of .latex2html-init in each directory you would like it
   to be effective. An initialisation file 
   /X/Y/Z/.latex2html-init will take precedence over all
   other initialisation files if /X/Y/Z is the ``current directory'' when 
   LaTeX2HTML is invoked. 

 o To find the LaTeX2HTML icons:
   The LaTeX2HTML icons are fetched through $ICONSERVER. This variable
   should point to a global place in your system, thus, by default, set
   to $LATEX2HTMLDIR/icons. The icons are loaded very quickly this way.
   Make sure they can be read by your HTTP daemon, ie. set the directory
   world-wide readable/executable and the icons world-wide readable.
   If $LATEX2HTMLDIR is something private for you, copy the icons to a
   global place, say /usr/local/lib/latex2html/icons, and set $ICONSERVER
   accordingly. 

 o To make your own local copy of the LaTeX2HTML documentation: 
   This will also be a good test of your installation. To do it run
   LaTeX2HTML on the file doc/manual.tex. You will get better results if
   you run LaTeX first on the same file in order to create some auxiliary
   files. 

Troubleshooting
***************

 o Cannot run any of the Perl programs
   -----------------------------------
   If your Perl installation is such that Perl programs are not allowed 
   to run as shell scripts you may be unable to run latex2html, texexpand,
   pstogif, install-test. In this case change the first line in each of
   these programs from

   #!/usr/local/bin/perl
   \end{verbatim}

   to

   \begin{verbatim}
   : # *-*-perl-*-*
   eval 'exec perl -S  $0 "$@"'
   if $running_under_some_shell; 

 o The install-test script gives uninformative error messages
   ----------------------------------------------------------
   If for any reason you have trouble running install-test,
   do not despair. Most of what it does is to do with checking
   your installation rather than actually installing anything.
   To do a manual installation just change the variable
   LATEX2HTMLDIR in the beginning of the file latex2html
   to point to the directory where the latextohtml files can be found.

   Also, make sure that the files pstogif, texexpand and latex2html
   are executable, and if necessary use the Unix chmod command to make
   them executable.

 o It crashes (dumps core) as soon as it starts perl
   -------------------------------------------------
   Update your Perl 4 to patch level 36 or later (Perl 5).
   You can check which version of Perl you are using by invoking Perl
   with the -v option.

 o It produces "out of memory" errors on reasonable small documents
   ----------------------------------------------------------------
   It has been reported that Perl 5.001 or later makes more efficient
   use of memory than perl 4.036.  Upgrade to Perl 5, and see whether
   that helps.

   Try splitting your source file into more than one files using the
   latex commands input or include. Also, use the -no_images option.

   As a last resort you may consider increasing the virtual memory
   (swap space) of your machine. As an indication 
   of what you might be able to do on your machine,
   a very long book (about 1000 printed pages) required about 
   24MB of RAM and over 150MB of swap space to convert on a local
   Sun Sparc ELC running SunOS 4.1.3.

 o It gives ``dbm'' related error messages.
   ----------------------------------------
   LaTeX2HTML 0.7 and later requires the Unix DataBase Management system
   (DBM or NDBM) in order to run.  This is usually part of each Unix
   operating system but if you don't have it then you may need to get it.
   On Linux systems, it may be necessary to uncomment the line,

   use GDBM_File;

   in the files, latex2html and install-test.

 o Cannot convert postscript images
   --------------------------------

   This might happen is that your shell environment variable 
   TEXINPUTS} is undefined. This is not always 
   fatal but if you have problems you can use full
   pathnames for included postscript files (even when the postscript
   files are in the same directory as the LaTeX source file).
   Alternatively try setting TEXINPUTS to ".:..:". 

A more extensive troubleshooting guide is found in the latex
documentation included with this distribution.


Support and More Information
****************************

Announcements, discussion archives, bug reporting forms and
more are kept at the LaTeX2HTML home at 
http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html. 

A LaTeX2HTML mailing list has been set up at the Argonne National Labs
(thanks to Ian Foster <itf@mcs.anl.gov> and Bob Olson
<olson@mcs.anl.gov>). 

To join send a message to: 
            latex2html-request@mcs.anl.gov 
with the contents 
            subscribe 

To be removed from the list send a message to: 
           latex2html-request@mcs.anl.gov 
with the contents 
           unsubscribe

The mailing list also has a searchable online archive, see
http://www.rosat.mpe-garching.mpg.de/mailing-lists/LaTeX2HTML/


Enjoy.

Author:
  Nikos Drakos <nikos@cbl.leeds.ac.uk>
  Computer Based Learning Unit
  University of Leeds.

Last Author:
  Jens Lippmann <lippmann@cdc.informatik.th-darmstadt.de>
  Technische Universit"at Darmstadt.
