next up previous contents index
Next: Support and More Information Up: The LaTeX2HTML Translator Previous: Known Problems

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;

*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 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. 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 (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 variablegif.

*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 (use Archie to find this or any other style files).


next up previous contents index
Next: Support and More Information Up: The LaTeX2HTML Translator Previous: Known Problems

Leon Kos
Tue Mar 19 09:29:01 MET 1996