
   
                                Troubleshooting
                                       
         Here are some curable symptoms:
   
   * _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 and install-test. 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;

   * _Cannot run any of the Perl programs #2_
          
          They prompt sth. like Command not found.
          
          Check the first line of the program. The path you see there
          must point to Perl! If you see eg. #!/usr/local/bin/perl, type
          
   which perl

   If they differ, adapt the first lines of any Perl script (currently
          pstoimg, texexpand, makemap, and latex2html), or talk to your
          system administrator to add a link to perl in /usr/local/bin
          (this is recommended).
          
   * _Cannot run latex2html_
          
          latex2html prompts sth. like di: Command not found or di: not
          found.
          
          You must have Perl installed to use LaTeX2HTML, you can't run
          it by your shell.
          
   * _latex2html exits with one of these messages:_
          
         1. no DBM on this machine...,
         2. AnyDBM_File.pm did not return a true value...,
         3. Can't locate AnyDBM_File.pm in @INC...
            
          Perl is not installed properly. In particular, these errors
          occur when Perl binaries are installed without the Perl
          library, or when the Perl binaries or library is moved to
          another location after installation. The resort is to
          re-install Perl by running its configure script, invoking the
          Makefile, etc., or to get a complete Perl distribution with
          includes the Perl library.
          
   * _Trouble with the images in my LaTeX2HTML Manual_
          If you have installed the PBM tools beforehand, there could
          sth. went wrong and the tools won't work. This problem is known
          yet to HP users only. Since the PBM tools are a bit awkward to
          install on HP-UX, try to download compiled binaries somewhere.
          A possible location is http://hpux.csc.liv.ac.uk/, in
          
          [1]http://hpux.csc.liv.ac.uk/hppd/hpux/X11/Graphics/netpbm-1mar
          94/ .
          
   * _Don't know how to compile the PBM tools on HP-UX_
          Since the PBM tools are a bit awkward to install on HP-UX, try
          to download compiled binaries somewhere. A possible location is
          http://hpux.csc.liv.ac.uk/, in
          
          [2]http://hpux.csc.liv.ac.uk/hppd/hpux/X11/Graphics/netpbm-1mar
          94/ .
          
   * _Only two HTML files produced with no contents_
          LaTeX2HTML did only produce a main page with links to
          node1.html, which contains nothing of your document.
          
          This is mainly related to Linux users. Perl needs to invoke the
          csh to perform globbing (eg. to locate TMP_* files). On Linux,
          there's usually the tcsh linked to csh, but this is often
          missing. To fix this, you need to follow several steps:
          
         1. Check for the tcsh, and install it if you don't have it. Take
            it from (randomly chosen site follows):
            [3]file://ftp.cs.uni-sb.de/pub/systems/shells/tcsh/tcsh-6.06.
            tgz
            but it is surely part of some Linux distribution for your PC,
            so you won't really need to compile it.
         2. Link the tcsh to csh. Eg. say ln -s /usr/local/bin/tcsh
            /bin/csh, or whereever you have your tcsh.
         3. If LaTeX2HTML still fails, say perl -e 'print $INC[1]'. This
            should prompt the directory where the Perl library resides.
            Step into this directory, and say grep full_csh Config.pm.
            The right hand value tells you where Perl wants the csh. Link
            the tcsh to this place.
            
   * _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 LaTeX2HTML 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.
          
   * _It just stops_
          Check the style files that you are using. It is likely that you
          are using a style file which contains raw TeX commands. In such
          a case start LaTeX2HTML with the option -dont_include <_style
          file name_>. Alternatively, add the name of the style to the
          variable DONT_INCLUDE in your HOME/.latex2html-init file. If
          you don't have such a file then create one and add the lines:
          
$DONT_INCLUDE = "$DONT_INCLUDE" . ":<style file name>";
1;      # This must be the last line

          Another reason why LaTeX2HTML might stop is that the LaTeX
          source file itself contains raw TeX commands. In this case you
          may put such commands inside a [4]latexonly environment.
          
   * _Perl cannot parse the latex2html script_
          Update your Perl to patch level 36. You can check which version
          of Perl you are using by invoking Perl with the -v option.
          Earlier versions of Perl than that shown above have caused
          problems due to tighter control over syntax.
          
   * _It crashes (dumps core) as soon as it starts  _
          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.
          
          While you wait for your technical support people to upgrade
          Perl you could try invoking Perl from within LaTeX2HTML with
          the -d (debug) option. Then, when LaTeX2HTML starts, it will
          immediately fall into the Perl debugger. To continue just press
          c <CR>.
          
   * _dvips complains about incorrect arguments  _
          Please use a version which supports the command line options -M
          -S, -o and -i. ``Recent'' versions at least after 5.516 do
          support them.
          
   * _It gives an Out of memory message and dies_
          If you are using version LaTeX2HTML 0.7 or later 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.
          
   * _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. [5]Use Archie to find one.
          
   * _The verb"ABC" command doesn't work_
          This is a nasty bug. Please use any characters other than
          quotes eg verb+ABC+
          
   * _Cannot get the ``tilde'' (~) to show_
          The trick here is to use the command \~{}.
          
          Alternatively it is possible to use something like
          
\htmladdnormallink{mylink}%
  {\begin{rawhtml}http://host/~me/path/file.html\end{rawhtml}}

          or
          
          \htmladdnormallink{mylink}{http://host/\%7Eme/path/file.html}
          
          _Warning:_ Some browsers may not be able to interpret the %7E
          as a ``tilde'' character.
          
   * _Macro definitions don't work correctly_
          As mentioned in other places plain TeX definitions cannot be
          converted. But you may also have problems even when using LaTeX
          definitions (with newcommand and newenvironment) if such
          definitions make use of _sectioning or verbatim_ commands.
          These are handled in a special way by LaTeX2HTML and cannot be
          used in macro definitions.
          
          In general the macro handling mechanism is inefficient and very
          fragile. Avoid using macros if possible.
          
   * _input commands_
          There is a bug in the expansion of input commands which causes
          a problem when more than one input command appear on the same
          line. There is no quick fix other than suggesting that you
          insert a newline after input commands in the source .tex files.
          
   * _input commands in verbatim environments_
          These cause problems. There is no fix yet.
          
   * _Optional arguments in description environments_
          If you have optional arguments for the item command in a
          description environment containing nested ``]'' characters then
          these may not show up correctly. To avoid the problem enclose
          them in {}'s eg \item[{[nested [angle [brackets] are ok]]}]
          
   * _LaTeX2HTML behaves differently even when you run it on the same
          file_
          If you notice any strange side-effects from previous runs of
          LaTeX2HTML try using the option -no_reuse and choose (d) when
          prompted. This will clear any intermediate files generated
          during previous runs. Note that this option will disable to
          image reuse mechanism.
          
   * _Cannot convert postscript images which are included in the LaTeX
          file_
          
          It is likely that the macros you are using for including
          postscript files (e.g. epsffile) are not understood by
          LaTeX2HTML. To avoid this problem enclose them in an
          environment which will be passed to LaTeX anyway e.g.
          
\begin{figure}
\epsffile{<postscript file name>}
\end{figure}

          Another reason why 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 ".::". With some TeX and LaTeX
          installations setting TEXINPUTS to ".::" may cause problems in
          the normal operation of LaTeX. If you get errors such as LaTeX
          complaining that it can no longer find any style files then you
          must set TEXINPUTS to "<path to your LaTeX installation>:." if
          you want to use both LaTeX and LaTeX2HTML.
          
   * _Some of the inlined images are in the wrong places_
          This happens when any one of the inlined images is more than a
          page (paper page) long. This is sometimes the case with very
          large tables or large postscript images. In this case you can
          try specifying a larger paper size (eg ``a3'', ``a2'' or even
          ``a0'') instead of the default (``a4'') using the LaTeX2HTML
          variable PAPERSIZE in the file latex2html.config.
          
          Another reason why this may happen is that by default the dvips
          program reverses the postscript pages it generates. If your
          dvips program behaves in this way try changing the line $DVIPS
          = "dvips";
          
          to
          
          $DVIPS = "dvips -r0";
          
          in the file latex2html.config.
          
   * _Unacceptable quality of converted images_
          Try changing the size of the image ([6]See image conversion).
          
   * _The bibliographic references are missing_
          Run latex and then bibtex on the original source file in order
          to generate a bbl file. LaTeX2HTML requires a bbl in order to
          generate the references.
          
   * _The labels of figures, tables or equations are wrong_
          This can happen if you have used any figures, tables, equations
          or any counters inside conditional text i.e. in a latexonly or
          a htmlonly environment.
          
   * _Problems after changing the configuration files_
          Please make sure that the last line in the configuration files
          (ie .latex2html-init and latex2html.congif) is:
          
1;      # This is the last line

   This is a Perl quirk...
          
   * _Problems when producing the DVI version  _
          If you are using any of the new LaTeX commands which are
          defined in the html.sty file make sure that html.sty file is
          included e.g. as one of the optional arguments to the
          documentstyle command.
          
          Of course you also have to 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[7][+].
          
   * _Some of the fonts are translated incorrectly_
          There is a fault in way the LaTeX scoping rules have been
          interpreted in LaTeX2HTML. Consider this:
          
\ttfamily fixed-width font.
\begin{something}
nothing here
\end{something}
default font.

   When processed by LaTeX, the effect of the tt command is delimited by
          the beginning of the environment ``something'' so that
          ``default font'' will appear in the default font. But
          LaTeX2HTML will not recognize ``something'' as a delimiter and
          ``default font'' will appear in the wrong font.
          
          To avoid this problem until it is fixed you may delimit the
          scope of some commands explicitly using {}'s i.e.
          
\texttt{fixed-width font}.
\begin{something}
nothing here
\end{something}
default font.

   * _Using Ghostscript 3.X you can no longer generate inlined images for
          equations_
          If you have a version of LaTeX2HTML later than 0.6.1, go to the
          LaTeX2HTML directory and run install-test again. This should
          fix it.
          
          With earlier versions of LaTeX2HTML you can fix it by replacing
          the file pstoppm.ps in the LaTeX2HTML directory with a newer
          one that accompanies Ghostscript 3.X. Alterhatively you can
          avoid using pstoppm.ps by changing the way GS is invoked in the
          file pstogif, using something like
          open (GS, "|$GS -q -sDEVICE=ppmraw -sOutputFile=$base.ppm
          $base.ps");
          
   * _Cannot get it to generate inlined images_
          Try a small test file e.g.
          
% image-test.tex
\documentstyle{article}
\begin{document}
Some text followed by \fbox{some more text in a box}.
\end{document}

          You should see something like:
          
This is LaTeX2HTML Version  (Wed Dec 1 1993) by Nikos Drakos,
Computer Based Learning Unit, University of Leeds.

OPENING /usr/cblelca/nikos/scripts/tex2html/tests/image-test.tex

Reading ....
Translating ...0/1.....1/1......
Generating images using latex ...
This is TeX, C Version 3.14t3
12222_images.tex
LaTeX Version 2.09 <7 Dec 1989>


Generating postscript images using dvips ...
This is dvips 5.521 Copyright 1986, 1993 Radical Eye Software
' TeX output 1993.12.03:1050' -> 12222_image
(-> 12222_image001) <tex.pro>[1]
Initializing... done.
Ghostscript 2.6.1 (5/28/93)
Copyright (C) 1990-1993 Aladdin Enterprises, Menlo Park, CA.
  All rights reserved.
Ghostscript comes with NO WARRANTY: see the file COPYING for details.
GS>GS>Writing 12222_image001.ppm
GS>pnmcrop: cropping 119 rows off the top
pnmcrop: cropping 961 rows off the bottom
pnmcrop: cropping 208 cols off the left
pnmcrop: cropping 484 cols off the right

Doing section links .....
Done.

          If there is a problem somewhere during the conversion from
          postscript to GIF you can try to do it manually so that you can
          find out where the problem is. Here is one way to do it (Please
          use the pstoppm3.ps file instead of pstoppm.ps if your version
          of ghostscript is later than 3.0):
          
cblelca% latex image-test.tex
This is TeX, C Version 3.14t3
(image-test.tex
LaTeX Version 2.09 <7 Dec 1989>
(/usr/TeX/tex.lib/inputs//paper.sty
Document Style `paper' <28 Nov 89>.
(/usr/TeX/tex.lib/inputs//pap11.sty) (/usr/TeX/tex.lib/inputs/\-doublespace.sty
)
(/usr/TeX/tex.lib/inputs//smaller.sty)) (/usr/TeX/tex.lib/inputs\-/psfig.sty
psfig/tex 1.9
)
No file image-test.aux.
[1] (image-test.aux) )
Output written on image-test.dvi (1 page, 652 bytes).
Transcript written on image-test.log.
cblelca% dvips -o image-test.ps image-test.dvi
This is dvips 5.519 Copyright 1986, 1993 Radical Eye Software
' TeX output 1993.11.12:1412' -> image-test.ps
<tex.pro>. [1]
cblelca% gs -dNODISPLAY pstoppm.ps
Initializing... done.
Ghostscript 2.6.1 (5/28/93)
Copyright (C) 1990-1993 Aladdin Enterprises, Menlo Park, CA.
  All rights reserved.
Ghostscript comes with NO WARRANTY: see the file COPYING for details.
GS>(image-test) ppm1run
Writing image-test.ppm
GS>quit
cblelca% pnmcrop image-test.ppm >image-test.crop.ppm
pnmcrop: cropping 61 rows off the top
pnmcrop: cropping 110 rows off the bottom
pnmcrop: cropping 72 cols off the left
pnmcrop: cropping 72 cols off the right
cblelca% ppmtogif image-test.crop.ppm >image-test.gif

   * _STILL cannot get it to generate inlined images for equations etc._
          If you have no problems with the image-test.tex file but you
          still cannot convert the images in some of your files have a
          look in the directory of the generated HTML files for two files
          images.tex and images.log. Do you notice anything unusual in
          them? Copy images.tex in the directory of your original
          LaTeXfile and run latex on images.tex. Can you see any errors
          in images.log? If yes can you fix images.tex to get rid of the
          errors? After fixing images.tex you can put it back in the
          directory of HTML files created by LaTeX2HTML and run
          LaTeX2HTML on the original document using the option
          -images_only.
          
          If you get into a mess try running LaTeX2HTML with the options
          -no_reuse and -no_images eg
          
cblipca% latex2html -no_reuse -no_images test.tex
This is LaTeX2HTML Version 95 (Tue Nov 29 1994) by Nikos Drakos,
Computer Based Learning Unit, University of Leeds.

OPENING /tmp_mnt/home/cblelca/nikos/tmp/test.tex
Cannot create directory /usr/cblelca/nikos/tmp/test: File exists
(r) Reuse the images in the old directory OR
(d) *** DELETE *** /usr/cblelca/nikos/tmp/test AND ITS CONTENTS OR
(q) Quit ?
:d

Reading ...
Processing macros ....+.
Reading test.aux ......................
Translating ...0/1........1/1.....
Writing image file ...

Doing section links .....

*********** WARNINGS ***********

If you are having problems displaying the correct images with Mosaic,
try selecting "Flush Image Cache" from "Options" in the menu-bar
and then reload the HTML file.

Done.

          Then try to have a look in the file images.tex (as described
          earlier) and perhaps fix it. Once you are happy that images.tex
          is OK run LaTeX2HTML again with the option -images_only.
          
          The options no_reuse, no_images and images_only are available
          with LaTeX2HTML version 0.7 or later.
          
          Some problems in displaying the correct inlined images, may be
          due to the image caching mechanisms of your browser. With some
          browsers a simple ``Reload Current Document'' will be enough to
          refresh the images but with others (eg Mosaic) you may need to
          request for the cache to be refreshed. With Mosaic try
          selecting "Flush Image Cache" from "Options" in the menu-bar
          and then reload the HTML file.
          
   * _It cannot do slides, memos, etc, ..._
          If you use slitex you can go a long way just by replacing the
          slides argument of the documentstyle command with something
          like article just before using LaTeX2HTML. One problem may be
          that all your slides will end up in the same HTML file. If you
          use lslide.sty you may get much better results ([8]use Archie
          to find this or any other style files).
          
   ...variable
          If don't know how to do either of these things, copy (or link)
          html.sty to the directory of your LaTeX document...
          

   
     _________________________________________________________________
                                      
   
    _Jens Lippmann
    12/24/1996_

References

   1. http://hpux.csc.liv.ac.uk/hppd/hpux/X11/Graphics/netpbm-1mar94/
   2. http://hpux.csc.liv.ac.uk/hppd/hpux/X11/Graphics/netpbm-1mar94/
   3. file://ftp.cs.uni-sb.de/pub/systems/shells/tcsh/tcsh-6.06.tgz
   4. file://localhost/home/lippmann/latex2html/user/tmp/faq.html#seclatexonly
   5. http://www.pvv.unit.no/archie/
   6. file://localhost/home/lippmann/latex2html/user/tmp/faq.html#imgcon
   7. file://localhost/home/lippmann/latex2html/user/tmp/faq.html#161
   8. http://www.pvv.unit.no/archie/
