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, pstoimg 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 L^ATEX2HTML files can be found.

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

It just stops.

Check the style files that you are using. It is possible that you are using a style file which contains raw TEX commands. In such a case start L^ATEX2HTML 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 L^ATEX2HTML might stop is that the L^ATEX source file itself contains raw TEX commands. In this case you may put such commands inside a latexonly environment.

^97.1
The $VERBOSITY variable can be used to create tracing messages, which may help to locate which command or environment was being processed when everything stopped.
^97.1

  
^97.1

It appears to be doing nothing. 

Perhaps the processor has fallen into an unending loop. Usually there will be a bad definition, or other faulty source code, which has caused this. The $VERBOSITY variablecan be set to generate tracing messages, which may help to locate which command or environment is being processed repeatedly. Try setting a value of `3'; e.g. using the commandline switch -verbosity 3 . This will print command and environment names, as thaey are processed. It should soon become apparent where any such looping occurs.

It just fills the endlessly with dots.

No `perhaps' here; the processor has definitely fallen into an unending loop. See the previous item for how to detect which command or environment is causing the problem.
^97.1

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 L^ATEX2HTML with the -d (debug) option. Then when L^ATEX2HTML starts, it will immediately fall into the Perl debugger. To continue just press `c<CR>'. (This option is available only if the local version of Perl was specially compiled to allow it.)

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 L^ATEX2HTML 0.7 or later try splitting your source file into more than one file, using the L^ATEX commands \input or \include. Also, try using the -no_images option.

^97.1
Perhaps the processor has fallen into an infinite loop. Usually there will be a bad definition, or other faulty source code, which has caused this. See an earlier problem for how to set the $VERBOSITY variable to help locate the bad code leading to this memory exhaustion.
^97.1
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.
^97.1
Much of this memory would have been consumed during image-generation. This part of the processing is much more efficient in V97.1.
^97.1

It gives ``dbm'' related error messages:

L^ATEX2HTML 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 to find one.

^97.1
This can happen when an image is being created from a large piece of L^ATEX source code. The image-reuse mechanism uses the code itself to construct a database key. If too long, the key is invalid and may crash DBM or NDBM. (In fact this error should no longer occur in V97.1, so please advise the L^ATEX2HTML developers if you get error messages of this kind.)
The message should contain the name of environment which caused the problem, along with an identifying number; e.g. eqnarray268. To find which exact piece of code this represents, run L^ATEX2HTML again, using the -debug switch. Then look at the files in the working directory named TMP-part1, TMP-part2, etc. Use the unix grep command: grep 268 <dir>/TMP-* to find that number in these files. This should enable you to locate exactly where the problem occurs.

One solution may be to wrap the whole environment within \begin{makeimage} and \end{makeimage}. This will still cause the image to be created, but uses just the environment name and number as the database key.
^97.1

The \verb"ABC" command doesn't work:

This is a nasty bug. Please use any character other than quotes; e.g. \verb+ABC+.

Cannot get the ``tilde'' (~) to show:

The trick here is to use the command \~{}.
Alternatively try using something like: mylink ">mylink . 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, not all plain TEX \def-initions can be converted. But you may also have problems even when using L^ATEX definitions (with \newcommand and \newenvironment) if such definitions make use of sectioning or \verbatim commands. These are handled in a special way by L^ATEX2HTML and cannot be used in macro definitions.

In general the macro handling mechanism is inefficient and very fragile. Avoid using macros if possible.
^97.1
A greater range of macros definitions can now be handled, especially if appropriate declarations are added to an initialization file.
^97.1

\input commands:

There is a bug in the expansion of \input commands which causes a problem when more than one \input command appears on the same line. There is no quick fix other than suggesting that you put each \input command on a line by itself, in the L^ATEX source files.

\input commands in verbatim environments:

These cause problems; there's no fix yet. Try using either the verbatim or the verbatimfiles package.

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;
e.g. \item[{[nested [angle [brackets] are ok]]}]

L^ATEX2HTML behaves differently even when you run it on the same file:

 
If you notice any strange side-effects from previous runs of L^ATEX2HTML, 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 the image-reuse mechanism.

Cannot convert PostScript images which are included in the L^ATEX file:

 
It is likely that the macros you are using for including PostScript files (e.g. \epsffile) are not understood by L^ATEX2HTML. To avoid this problem enclose them in an environment which will be passed to L^ATEX anyway; e.g.

\begin{figure}
\epsffile{<PostScript file name>}
\end{figure}

Another reason why this might happen is that your shell environment variable TEXINPUTS may be undefined. This is not always fatal but if you have problems you can use full path-names for included PostScript files (even when the PostScript files are in the same directory as the L^ATEX source file). Alternatively try setting TEXINPUTS to `.::'. With some TEX and L<sup>A</sup>TEX installations setting TEXINPUTS to `.::' may cause problems in the normal operation of L^ATEX. If you get errors such as L^ATEX 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 L^ATEX and L^ATEX2HTML.

Some of the inlined images are in the wrong places:

There are several known ways that this may occur.

• Perhaps 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 (e.g. `a4', `a3' or even `a0') instead of the default (`a5') using the L^ATEX2HTML variable $PAPERSIZE in the file latex2html.config.
  This reason for the error should no longer occur with V97.1. Please report it on the mailing-list, if it does.
• More likely is that some inappropriate L^ATEX code has caused an error, resulting in an extra page (or pages) being generated. Examine the images.log file, to see if it reports any L^ATEX errors.
• A much rarer reason 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";
  within the file latex2html.config.
• Yet another reason for images appearing out of place, especially while developing a document, is that the browser's image cache is providing out-of-date versions rather than getting the latest version afresh. When this occurs there will often be images stretched or shrunk to fit the wrong sized imaging area; this symptom is browser-dependent. Flushing the cache, then reloading the HTML document, should clear up the problem.

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. L^ATEX2HTML may need the .bbl file 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 (i.e. .latex2html-init and latex2html.config) 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 L^ATEX commands which are defined in the html.sty file make sure that html.sty is included; e.g. as one of the optional arguments to the \documentclass command.

Of course you also have to 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³.

Some of the fonts are translated incorrectly:

There is a fault in way the L^ATEX scoping rules have been interpreted in L^ATEX2HTML. Consider this:

\ttfamily fixed-width font.
\begin{something}
nothing here
\end{something}
default font.

When processed by L^ATEX, 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 L^ATEX2HTML will not recognise ``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 it no longer generates inlined images for equations:

If you have a version of L^ATEX2HTML later than 0.6.1, go to the L^ATEX2HTML directory and run install-test again. This should fix it.

With earlier versions of L^ATEX2HTML you can fix it by replacing the file pstoppm.ps in the L^ATEX2HTML directory with a newer one that accompanies Ghostscript 3.x.
Alternatively 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 an image-format then 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 L^ATEX file 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 L^ATEX2HTML and run L^ATEX2HTML on the original document using the option -images_only .

If you get into a mess try running L^ATEX2HTML with the options -no_reuse and -no_images ; e.g.

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 L^ATEX2HTML again with the option -images_only . The options -no_reuse , -no_images and -images_only are available with L^ATEX2HTML 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 (e.g. 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 \documentclass command with something like {article} just before using L^ATEX2HTML. 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 to find this or any other style files).

 

Footnotes

...variable³

If don't know how to do either of these things, copy (or link) html.sty to the directory of your L^ATEX document.