LaTeX2HTML Version 98.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 
http://www-math.mpce.mq.edu.au/texdev/LaTeX2HTML/docs/manual/
for more information and examples.

In particular see the pages:
 support.html , Snode1.html , Snode2.html , Snode3.html 
for instructions on how to install the program 
and 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/Snode2.html
or 
http://www-math.mpce.mq.edu.au/texdev/LaTeX2HTML/docs/manual/Snode2.html

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 5.003 (Perl5 Patch level 3) or higher.
------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

    o DBM or NDBM, the Unix DataBase Management system.
      Alternatively, Perl5's SDBM DataBase system.
------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      Do not care unless you get misconfiguration errors from LaTeX2HTML.

 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.
      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.
------^^^
    o 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).
    o The netpbm library (ftp://ftp.x.org/R5contrib/).
      Netpbm 1 March 1994 is recommended. Check with 'pnmcrop -version'.
      Some of the filters in those libraries are used during the postscript
      to image conversion.
    o If you want PNG images, you need pnmtopng (current version is 2.31).
      It is not part of netpbm and requires libpng (version 0.89c) and 
      libz (1.0.4). pnmtopng supports transparency and interlace mode.
      Hurray!!! Netscape 4.04 has been reported to grok PNG images!
------^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      That means your PNG option is not longer ahead of its time!

 3. Transparent inlined GIFs
   If you dislike the ugly white background color of the generated inlined
   images then the best thing you can do is 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.
   Get GIFTRANS 1.11.1 from (randomly chosen site):
   ftp://ftp.uni-stuttgart.de/pub/comm/infosystems/www/tools/imaging/giftrans/giftrans-1.11.1.tar.gz
   LaTeX2HTML now supports the shareware program giftool (by Home Pages, Inc.,
   version 1.0), too. It can also create interlaced GIFs.

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/Snode3.html
or 
http://www-math.mpce.mq.edu.au/texdev/LaTeX2HTML/docs/manual/Snode3.html

for more information. OS specific instructions for OS/2 users are at
http://www.erdw.ethz.ch/~bonk/l2h/l2h-note.html

To install LaTeX2HTML you MUST do the following: 

 1. Specify where Perl is on your system. 
   In each of the files latex2html, texexpand, pstoimg and 
   install-test and makemap, modify the first line saying where
   Perl is on your system. Additionally, you _must_ specify the PERL$
   variable at the beginning of the latex2html file. See the example
   inside the latex2html file.

   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 pathnames to any external utilities required
    by LaTeX2HTML are correct.
    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.
    Do this with ``chmod +x install-test''.
    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 the same file. 
    If you do a system installation for many users, only care for general
    aspects and let the user override them with $HOME/.latex2html-init.
----^^^

 Note that you must run install-test now (formerly you needn't).
 If you want to reconfigure LaTeX2HTML for GIF/PNG image generation
 or because some of the external tools changed the location, run
 configure-pstoimg.
-^^^^^^^^^^^^^^^^^

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.
   (This will also rule out many of the HTML3/HTML4 features!)
   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.
   However you *mustn't* upgrade LaTeX just to have the features, lots of
   documents do fine without them.
   You should not 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 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 and
   the HTTP daemon finds the icons under the $ICONSERVER URL.
   If $LATEX2HTMLDIR is something private for you, copy the icons to a
   global place, say /usr/local/lib/latex2html/icons, and set $ICONSERVER
   accordingly. Note that by setting $LOCAL_ICONS or using the
   -local_icons command line switch you can force LaTeX2HTML to copy the
   icons to the document directory, thus resulting in a self-contained
   document tree that can be dropped into any existing directory
   structure.

 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
***************

Please refer to the FAQ file that came with your 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!

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

Former Author:
  Ross Moore <ross@mpce.mq.edu.au>
  Mathematics Department
  Macquarie University, Sydney.

Most Recent Author:
  Jens Lippmann <lippmann@cdc.informatik.tu-darmstadt.de>
  Technische Universit"at Darmstadt.