\documentclass{article}

\usepackage{html}
\usepackage{hthtml}

\setlength{\textwidth}{6.6truein}\setlength{\oddsidemargin}{-.2truein}
\setlength{\evensidemargin}{-.2truein}\setlength{\textheight}{9truein}
\setlength{\topmargin}{-.4truein}\setlength{\headsep}{.2truein}
\setlength{\footskip}{.3truein}

\newcommand{\texlive}{{\TeX}live}
\setlength{\parskip}{.5\baselineskip}

\title{LaTeX2HTML-FU}
\author{Leon van Dommelen}

\begin{document}

\maketitle

\begin{abstract}
  This describes fixes to the {\latextohtml} program that allow it to
  produce professionally looking web pages from {\LaTeX} sources.
  These include both program fixes and work-arounds.  {\bf However,
    the software described on these pages is no longer supported.  To
    obtain the fixed up version of {\latextohtml} described here, go
    to:\\
    ~~~\hturl{http://www.eng.fsu.edu/~dommelen/l2h}.}
\end{abstract}

\tableofcontents

\section{Recent news}
\label{sec:recnews}

{\bf Note: The software described on these pages is no longer
  supported.  To obtain the fixed up version of {\latextohtml}
  described here, go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

I found a bug in the MS Windows/DOS installation scripts.  As far as I
see, with this bug, none of the scripts would work on XP, and
presumably later.  (The scripts checked for the existence of
directories by appending {\verb@\nul@} to them.  That simply does not
seem to work anymore on XP.  (Sep 12)

The easy linux install now also works if your home directory is not
/root.  Gee.  Current versions of Perl no longer support the multiline
matching used in {\latextohtml}.  Some minor fixes have therefor been
made to \htlink{latex2html.pin}{../zips/latex2html.pin}.  They are not
yet included in the Windows l2hfu3.exe, since they seem
inconsequential. (Nov 09).

As far as I know, everything works just fine. (Mar 08)

There is now an easy install package for Linux running on x86 (Intel)
machines.  (Sep 07).

{\latextohtml} should now no longer get confused between figures with
similar but different html code.  It will now also properly remake
figures that have changed in their back slashes or white space.
However, you will want to remake old documents from scratch, using the
{\verb@clrl2h all@} command to get rid of the old gif images.  (Old
images will no longer be recognized.)  (Sep 07).

Minor fixes for changes in the hyperref package.  (Sep 07).

Automated jpeg support is now available through setting {\verb@L2H_JPGQ@}.
(Late August 06)

The Wiz.  Allows you to change basic properties such as colors, font size,
headers and footers, etcetera, without delving into the details of
html, style sheets, init files, and gif conversions.  Just enter
{\lq\lq}wiz{\rq\rq}.
(Early August 06)

Style-sheet alignment.  This allows the use of a single set of web
pages for all browsers.  (Unless you are very picky.)  In particular,
the large vertical alignment errors that could occur with Internet
Explorer are gone.  And that in turn allowed me to greatly clean up
the user interface: just say {\verb@l2h@} and good web pages will be
made!  To get this new alignment you will have to install the latest
version of {\latextohtml}, then recreate your web pages from scratch.
(Early July 06)

The easy installation scripts now accomodate MiKTeX, fpTeX, and XEmTeX
installed in other than the default location, by prompting the user
for the location if needed.  There are now easy uninstall scripts
too. (Early June 06).

A dvips/ghostscript bug in new versions of {\TeX} that left
underlines below some formulae was fixed.  (April 06)


\section{Absence of Warranty, Presence of Copyrights, Licenses}
\label{sec:notices}

The {\latextohtml}-FU fixes, and the other software needed to run
\latextohtml, including {\latextohtml} itself, come with {\em absolutely
  no warranty}.

You cannot copy or share your installation with others.  Selling it is
illegal.

Except for my own stuff, {\em nothing else} is public domain, but
protected by copyright laws, licenses, and the occasional patent.  You
are responsible for reading, and abiding by, the legal notices in {\em
  every archive} involved in the installation.  I put the central
legal notices of the packages involved in directory
\verb@C:\l2hsup\copright@.

The file {\verb@l2hfu3.exe@} contains the full original {\latextohtml}
99.2 distribution, but when you run any of my installation scripts,
you will replace files in this distribution.  Run {\verb@l2hfu3.exe@}
in a temporary folder to obtain the unmodified distribution.

I am not aware of any patents that are still current on the netpbm
software involved.  Then again, I may be wrong.

Possibly, some netpbm software may require the source code to be
distributed with the binaries.  Only the source code I wrote myself is
included (in the \verb@C:\l2hsup\doc@ directory.) Sources or the netpbm
programs may be obtained from the
\htlink{netpbm homepage.}{http://netpbm.sourceforge.net/doc/}
I assume this satisfies the spirit of those pre-web requirements.
Otherwise let me know.

emTeX is a very good, but no longer maintained version of {\TeX}
written by Eberhard Mattes.  I may be violating the requirement to
distribute all files listed in {\verb@README.ENG@} in archive
{\verb@l2hmtx.exe@}, but again, the full source can be obtained from
\htlink{the {\TeX} Users Group}{http://www.tug.org}.
It is essential you do not redistribute the personal-use version
intended to work with {\latextohtml}.  There is also a
large number of packages written by a variety of authors included,
for which copyright notices can again be found at
\htlink{the {\TeX} Users Group}{http://www.tug.org}.

Tomas Rokicki wrote dvips, and Guido Sawade adapted it to emTeX.  I
made some small edits to the configuration files to get postscript
fonts to work.  The copyright situation is unknown to me.  Just don't
redistribute.

I think that summarizes all software involved, except the ones you
install yourself, such as perl and ghostscript.


\section{Lack of support}
\label{sec:support}

{\bf Note: The software described on these pages is no longer
  supported.  To obtain the fixed up version of {\latextohtml}
  described here, go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

The only support I can provide is with the {\latextohtml} fixes and
the scripts I added to it.  I cannot answer questions on normal
{\latextohtml} usage, since all I can do is the same as you can; look
in the
\htlink{online manual}{http://www.eng.fsu.edu/~dommelen/l2hman},
(a copy of which is in the docs subdirectory of your l2hsup folder),
and maybe refresh my memory about the various additional trouble shooting
solutions in the manual you are reading, which I wrote myself.  In fact, I
know very little about the inner workings of latex2html beyond what was
not working correctly in it.

However, bugs in my scripts and installation procedures I will fix
immediately.  The Windows scripts for emTeX, MiKTeX, fpTeX, and XEmTeX
should work out-of-the-box if you correctly installed a current
{\verb@perl.exe@} in {\verb@C:\Perl\bin@}, and a ghostscript
{\verb@gswin32c.exe@} somewhere below {\verb@C:\gs@}.  In particular,
you should be able to convert the given test cases into web pages.  If
they do not work as advertised, let me know and I will get it fixed
promptly.

Similarly, for other installations that the ones I tried, I will
clarify anything in the instructions that you may find unclear or
ambiguous.  I may be able to give you some suggestions too, but don't
be offended if I tell you to install MiKTeX, whic is is guaranteed to
work (with Windows) if it gets too much.  I do have an interest in
providing better installation instructions for other current operating
systems besides Sun Solaris.  (The Unix installation instructions are
tested only on Solaris.)  I do not have a Mac, but if you want to work
together to create a documented installation procedure for them, I am
willing.

If {\latextohtml} does not work correctly on some document, let me
know that too, with enough info so that I can reproduce the bug, and I
will try to find a fix or work-around.

To contact me with questions, e-mail me at l2h\_support@dommelen.net,
\htmailto{l2h\_support@dommelen.net}.  Put something meaningful in the
subject line, since, as you might guess, I get a lot of SPAM at this
publicly posted address.  If you leave the subject blank, I will
probably never see your message.


\section{Credits}

Countless authors have contibuted to \latextohtml.  The originating
author was Nikos Drakos, and in the later versions, Ross Moore took a
leading coordinating role.  Please see the
\htlink{online manual}{http://www.eng.fsu.edu/~dommelen/l2hman/}
for a proper review of all credits.

Netpbm is based on the Pbmplus package by Jef Poskanzer, first
distributed in 1988 and maintained by him until 1991. But the package
contains work by countless other authors, added since Jef's original
work. In fact, the name is derived from the fact that the work was
contributed by people all over the world via the Internet, when such
collaboration was still novel enough to merit naming the package after
it.
Bryan Henderson has been maintaining Netpbm since 1999. In addition to
packaging work by others, Bryan has also written a significant amount
of new material for the package.
For detailed credits of the pnm package, please see the
\htlink{netpbm homepage.}{http://netpbm.sourceforge.net/doc/}

Eberhard Mattes wrote the excellent {\TeX} implementation emTeX.  Of
course, {\TeX} itself was originated by Donald E.~Knuth, and {\LaTeX}
by Leslie Lamport, and countless others have contributed to these.

Dvips was written by Tomas Rokicki, and the emTeX implementation was
done by Guido Sawade.


\section{Introduction}
\label{sec:intro}

The {\latextohtml} program was written to convert {\LaTeX} into web
pages.  This program was written by a large number of authors, starting
with Nikos Drakos, as detailed in its
\htlink{official online manual}
{http://www-texdev.ics.mq.edu.au/l2h/docs/manual/}, written by
Drakos and Ross Moore.

{\latextohtml}-FU is my distribution, fixing many bugs
(described in Appendix \ref{appdx}), improving the appearances, and
simplifying installation and usage.  The result is a tool that can
reliably convert {\LaTeX} documents into professional looking web
pages.

{\bf Note: The software described on these pages is no longer
  supported.  To obtain the fixed up version {\latextohtml}-FU
  described here, go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

Such web pages provide a much more powerful document distribution
system than converting them into pdf, because
\begin{itemize}
\item the web pages can be browsed without downloading the full
  document;
\item the web pages are massively hyperlinked;
\item the web pages can use all the power of the web such as interactive
  forms, linked search engines, cgi-bin scripts, etcetera.
\end{itemize}



\section{Example Documents}
\label{sec:examples}

The web pages and images in the examples below were produced by
\latextohtml-FU from the latex source, with absolutely no manual
editing of the produced web pages or their images.

\begin{enumerate}
  
\item This document.  Not much of a challenge.
  
  However, I used the {\verb@wiz@}\rq s headers and footers option to
  put my name to the left in the top bar and the FAMU and FSU logos to
  the right in the bottom bar.  I swiped these logos from the college
  web site, but unfortunately, they were made against a white
  background, not blue like the default bottom bar.  So, I used the
  color scheme option of the wiz to change the color of the bottom bar
  to white.  This did however not give any visual separation between
  the bottom navigation buttons and the logos, so I used the headers
  and footers option to append the html code {\verb@<BR><HR>@} (line
  break and horizontal ruler) to the bottom left and right button
  rows.  (In Firefox, you can see that the two rulers miss each other
  by a pixel.  Maybe, someday I will create a separate template.html
  with a single ruler.)  For the rest, colors, font sizes, icons,
  etcetera are all {\latextohtml}-FU defaults.

  I process this document from Unix (where I keep it) using teTeX and
  {\verb@makel2h@}, which I personally continue to prefer over
  {\verb@l2h@}: it is less of a mess if the web pages are in a
  separate folder.  Processing takes a couple of minutes.

\item \htlink{Quantum Mechanics for Engineers}
  {http://www.eng.fsu.edu/~dommelen/quantum/}.
  Almost any section demonstrates the capability of {\latextohtml} to
  convert math, figures, and tables to a browser format, and to massively
  hyperlink it all.  A section like 
  \htlink{Heavier Atoms}
  {http://www.eng.fsu.edu/~dommelen/quantum/style_a/heavy.html}
  has a bit of everything.
  Section \htlink{Classical Motion}
  {http://www.eng.fsu.edu/~dommelen/quantum/style_a/classic.html}
  has some roll-over moving gif animations, implemented through the
  rawhtml environment.  The exercises in the earlier chapters like
  like \htlink{Motion in a Pipe (scroll up a bit)}
  {http://www.eng.fsu.edu/~dommelen/quantum/style_a/pipe.html\#sec:pipeh}
  have been hyperlinked to the answers in a separate solution manual.
  
  I also made a \htlink{colorized version of this document}
  {http://www.dommelen.net/quantum2/index.html}
  using the wiz.  (I am indepted to the
  \htlink{Anry Color Picker}{http://www.anryhome.com/} for suggesting
  a more pleasing color scheme than the blue/yellow I had initially
  come up with.)
  
  This is a larger document, with at the time of writing
  well over 1,000 printed pages, 7000
  different math images, 280 figures, 10 or so animations (using
  rawhtml inside the tex document,) a table of contents, an index,
  lists of figures and tables.  All not including the hyperlinked
  solution manual.
  
  The main problem I encountered in this document was that in the
  original document, I had put some figures as
  {\lq\lq}displaymath{\rq\rq} to prevent {\LaTeX} from moving them.
  (The {\lq\lq}h{\rq\rq} option of the {\LaTeX} figure environment
  does not mean put the figure {\lq\lq}here{\rq\rq}.  It means,
  please, please, put the figure here if you really cannot find a
  place that you think better of.)  Unfortunately, the figure quality
  produced by {\latextohtml} was completely unacceptable to me due to
  the failure of Ghostview to properly anti-alias embedded bitmaps.
  So I had to use the extrascale trick described in subsubsection
  \ref{sec:prest}, but that only works in figure environments, not
  displaymath ones.  So {\LaTeX} again started putting my figures
  where they should not be, (in the pdf version of the document,)
  requiring manual insertion of page breaks in the {\LaTeX} source.
  Eventually I discovered the {\lq\lq}H{\rq\rq} option of the float
  package to fix this.  You learn something new about {\LaTeX} every
  day.
  
  Versions of this document have been created using teTeX on Unix,
  using emTeX on an Windows XP machine, and using MiKTeX 2.5 final,
  with hyperref turned off as described in subsubsection
  \ref{sec:prhtmli}, on another Windows XP machine.  Earlier MiKTeX
  version (2.5 beta and 2.4), fpTeX, and XEmTeX were also successfully
  tested on this document.  Initial version were produced on Windows
  98, but I do not do that anymore because of the speed difference.
  Processing from scratch on my single processor Windows XP portable
  takes about 20 minutes, almost all of which goes into creating the
  2200 images.  Processing on the Unix cluster takes considerable
  longer, maybe twice, probably because the many thousands of files
  involved must be transferred over the network. Processing minor
  changes that do not require many images to be remade takes only a
  few minutes.
  
  The wiz was used to set the font size to 19px, ({\LaTeX} document
  font size was 12pt), to swap the textual {\lq\lq}next{\rq\rq} link
  to the right side of the page, and to set the web page splitting
  level to -2.  For the colorized versions, the wiz was also used to
  change the colors, generating the recolored navigation buttons
  automatically from the blue ones.  The background was set to FFF0A6,
  the bar colors to FF5500, and the title colors to 660000.  The text
  in the bars was separately set, using the individual properties item
  of the wiz, to FFF8D2, since I thought the default black too
  unimpressive.
  
  Since I wanted to add stuff to the format selection screen, (such as
  links to the colorized version,) I copied over {\verb@select.html@}
  from the {\verb@files@} subfolder of the {\verb@l2hsup@} folder to
  the {\verb@index.tex@} folder, renaming it {\verb@select0.html@},
  and made the additions to it manually.
  
  No document segmenting was used in this or any other example; I find
  that even a large document like this processes perfectly fine from a
  single {\LaTeX} source on all machines I tried.  However, an 1999
  version of {\LaTeX} crashed on the size of the document.

\item \htlink{A PhD Thesis}
  {http://www.eng.fsu.edu/~dommelen/papers/subram/}. The earlier
  chapters demonstrate again the capability to handle complex math
  displays, for example \htlink{section 2.2}
  {http://www.eng.fsu.edu/~dommelen/papers/subram/style_a/node16.html}
  (Firefox can be off by a pixel occasionally, press refresh.)
  Chapter 8 has a lot of figures, which I implemented as full-size
  thumbnails, for example \htlink{section 8.2.4}
  {http://www.eng.fsu.edu/~dommelen/papers/subram/style_a/node56.html}.
  Click a thumbnail and you get a double-size image to examine more
  closely.  In total about 250 printed pages, 474 different math
  images, and 70 figures.
  
  This was the thesis from hell, {\latextohtml}-wise.  Used a
  proprietary {\lq\lq}FSU\_DISS{\rq\rq} style that widely deviates
  from standard {\LaTeX} conventions.  The figures have been pushed
  together by trial and error from separate .eps fragments, big and
  small, using a mixture of {\verb@\special@}, {\verb@\vspace@}, and
  {\verb@\hspace@} commands, and paragraph breaks, all in a document
  with a nonstandard line spacing.  It had two abstracts, created
  using some special {\verb@\abstract@} command.  It included title
  pages, signature pages, and other required forms.
  
  Converting {\lq\lq}as is{\rq\rq} was hopeless, so I converted it to
  the standard {\LaTeX} {\lq\lq}book{\rq\rq} class for the web
  version.  That was a very quick process, but unfortunately, the book
  format has no abstract.  So I ended up turning the (single) abstract
  into a {\verb@\chapter*@}.  Not elegant, but it seemed the best I
  could do.
  
  I also put the contents, and lists of figures and tables at the end
  instead of at the start, where I found them distracting in the web
  pages.

  Another problem was that the {\lq\lq}FSU\_DISS{\rq\rq} style uses
  different line-spacings and fonts than the book class, (and I did
  not know which ones).  So, with the figures pushed together from
  fragments using paragraph breaks, various labels were not properly
  centered on their graphics in the book version.  Also, some bounding
  boxes did not include all of the figure.  One was even completely
  off the page.  This could be fixed by using the no-EPS version of
  {\latextohtml}, but that still left the labels in the wrong place.
  So, I ended up turning 14 of the 70 figures into proper single .eps
  files with the Ghostview procedure described in subsubsection
  \ref{sec:prfigs} (using the FSU\_DISS version of the document that
  had the right linebreaks.)

  One figure environment had two figures with separate captions.  I
  had to split it into two figure environments to keep {\latextohtml}
  from including the first caption in the image.  (I believe another
  way to handle these things may be through the htmlimage command, but
  I did not try.)
  
  Continued figures had the text {\lq\lq}continued{\rq\rq} in their
  figure environment.  I had to put this into a caption to prevent it
  from ending up as part of the image, and use a
  {\verb@\addtocounter{figure}{-1}@} in front of the figure
  environment to keep the figure number from increasing.
  
  I made the navigation icons manually with MS Paint, using the
  Monotype Corsiva font, and converted these bmps to gifs using the
  bmptogif script found in the {\verb@l2hsup@} folder.  I then swapped
  them in using the wiz.  Feel free to swipe them off the web page and
  swap them in with the wiz if you like them.  I also used the wiz to
  put the navigation icons at one side of the page, and the textual
  {\lq\lq}next{\rq\rq} link to the other side, which I think works
  pretty well.  A one point border was added around the bars to make
  them look less flat; the procedure is in subsubsection
  \ref{sec:prrbars}.  The font size was set using the wiz to 21px.  I
  overspecified the document font size as 13.2pt (true value in the
  {\LaTeX} source was 12pt,) since the math seemed a little bit bigger
  than the normal text to me.  (Maybe I shouldn't have?  The point is
  that math capitals are disproporionally big compared to math lower
  case, you cannot get both to match the browser font size.  Overall,
  I think the true value, as in the quantum text above, may be
  preferable.)
  
  In August, 2006, I used the newly enhanced jpeg support to replace
  the previous small gif figure thumbnails into full size jpegs, at a
  size that you can still download over a phone line.  I put a
\begin{verbatim}
\htmlimage{thumbnail=1,extrascale=3}{}
\end{verbatim}
or
\begin{verbatim}
\htmlimage{thumbnail=1}{}
\end{verbatim}
  command in each figure environment, depending on whether they
  contained a bitmap image like the color figures or just vector graphics
  like the plots.  Then I used the wiz to set the figure scale factor
  to 2.  The net effect is that the figures appear in the document
  as full size thumbnails, and if you click them, you get a double
  size image to study more closely.
  
  I got rid of the old gif figures using {\verb@clrl2h all@}, and
  set the jpeg quality to a high value using
\begin{verbatim}
set L2H_JPGQ=85
\end{verbatim}
  since I did not want to skimp on quality in someone else's thesis.
  (Unix users use {\verb@setenv@} instead of {\verb@set@} and a space
  instead of an equals sign.)  The jpegs are still much smaller than
  the corresponding gifs; some of the streamline gifs topped out at
  almost a megabyte!  Finally, I processed with {\verb@makel2h@}.

\item A
  \htlink{copy of the online manual}{http://www.eng.fsu.edu/~dommelen/l2hman}
  as written by Drakos and Ross Moore.  More an impressive demo of the
  capability of {\latextohtml} to automatically create hyperlinked
  \begin{itemize}
  \item table of contents,
  \item index,
  \item glossary,
  \item lists of figures and tables,
  \end{itemize}
  with not much contribution from my FU stuff.  Still, the FU version
  does fix a few problems in \htlink{the official version}
  {http://www-texdev.ics.mq.edu.au/l2h/docs/manual/}, as detailed in
  item \ref{offmanprob} in the resolved problems section.
  
  Note that this document is {\em not} a good example of how
  {\latextohtml}-FU normally handles math, (unlike the quantum
  mechanics text and the Ph.D.~thesis above.)  \htlink{Some math}
  {http://www.eng.fsu.edu/~dommelen/l2hman/style_a/node31.html}
  is build out
  of text and images, not just images, by loading the math extension.
  Supposedly, if you have the Century Schoolbook font installed, the
  math text and image symbols will be consistent, and download time
  will likely be reduced.  {\latextohtml}-FU assumes that few
  browsers have that font, so by default it does not load the math
  extension.  Also, some math looks fuzzy since it is oversized to
  allow higher quality printing.  {\latextohtml}-FU does not by
  default do that, it assumes that you will provide a pdf version for
  high quality printing instead.  {\latextohtml}-FU normally does a
  better job at aligning eqnarrays, but the math extension disables
  that, as well as some white space around the formulae.

  I also created a 
  \htlink{grey scale version}{http://www.eng.fsu.edu/~dommelen/l2hmang}.
  In this version, I
  used the wiz to swap back in the 3D icons that come with the
  original {\latextohtml} and to set the background color to the 75\% grey
  page color for which these
  icons were made.  I do think the grey backgound makes the document
  pleasurable to read on screen; I suspect it reduces eye strain.
  The title and bar colors were suggested by the Anry Color Picker.
  
  I did take some cosmetic liberties with the source document here.
  In particular, I used an {\verb@extrascale@} in the
  {\verb@htmlimage@} command to anti-alias the embedded image.  See
  subsubsection \ref{sec:prest} for more details.  If you compare
  \htlink{this figure}
  {http://www.eng.fsu.edu/~dommelen/l2hmang/style_a/node33.html} with
  the \htlink{version above}
  {http://www.eng.fsu.edu/~dommelen/l2hman/style_a/node33.html}, you
  will see that it does make a difference.  Also, normally
  {\latextohtml}-FU would expand the caption of the figure to at least
  75\% of the page width, but since the figure has been given a
  border, it cannot do that.  (Browsers would expand the border along
  with the caption.)  So I moved the figure to the side of the web
  page, again using the htmlimage command, to avoid all the empty
  blank space around it.  (It would have been even better if the
  figure would not have ended up next to nonwrappable verbatim text,
  but I could not help that.) I also replaced the pink and purple
  balls in the itemized lists with other colors since they clashed
  badly with the grey background.  I find that
  \htlink{white balls work quite well}
  {http://www.eng.fsu.edu/~dommelen/l2hmang/style_a/node66.html}.  And
  I updated the bibliography images.
  
  I included links to the setup files that are in the index.tex folder
  to get you started if you like this format.  However, you can easily
  create them yourself using the wiz and change whatever you like.
  Specify the background color as BFBFBF, the title color as 660000,
  the ruler colors as 3F3F3F, the bar backgrounds as 3F3F3F and
  foregrounds as BFBFBF, including the bar link colors.   Add a
  four point border around the bars as described in subsubsection
  \ref{sec:prrbars}.

  In addition, I recreated the
  \htlink{frames version}{http://www.eng.fsu.edu/~dommelen/l2hmanf}.
  This allowed me to test the frames generation
  mechanism (and fix a few bugs there too.)
  For example, you can \htlink{click on the index button}
  {http://www.eng.fsu.edu/~dommelen/l2hmanf/style_a/node18_id.html}
  and easily examine, say, the parts where figures are discussed.
  Also note the footnotes frame.
  See subsubsection \ref{sec:prmhf} if you want to put your own
  documents as frames like this.
  
  In processing the original segmented document, the provided
  makefiles did not work even under Unix, for which they were
  supposedly designed.  I made some attempts to try to figure them
  out, but just got hopelessly confused.  So I simply combined all
  document fragments together into a standard single {\LaTeX} source
  and processed that normally using {\verb@makel2h@}.  Needless to
  say, this 110 page document too processes just fine without
  segmenting.

\end{enumerate}

These case studies show that {\latextohtml}-FU can reliably process
proper {\LaTeX} documents into professionally looking, massively
hyperlinked web pages.  It is however not uncommon that some adjusting
of the {\LaTeX} document is needed, especially for nonstandard
{\LaTeX} usage.


\section{Installation}
\label{sec:inst}

{\bf Note: The software described on these pages is no longer
  supported.  Do NOT follow the instructions here. To obtain the fixed
  up version of {\latextohtml} described here, go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

This section describes how to install {\latextohtml} on Windows or Unix.

\subsection{Windows Installation}
\label{sec:swins}

{\bf Note: The software described on these pages is no longer
  supported.  Do NOT follow the instructions here. To obtain the fixed
  up version of {\latextohtml} described here, go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

Continued availability of this installation procedure will depend on
whether the various people who wrote the software involved complain
about this distribution procedure.

Note: a bug in the installation scripts for Windows XP and higher was
fixed Sep 2012.  It is not clear to me why nobody noted that bug,
including me.

\subsubsection{Required for Windows 95, 98, ME}

(Please skip this subsubsection if you have Windows NT or XP!)

You will need to edit the file {\verb@CONFIG.SYS@} in the top directory
of the {\verb@C:\@} disk to assure that you have reasonable resources
for DOS programs.  Before doing so, use Windows Explorer to put a
backup copy of your original {\verb@CONFIG.SYS@} file to another location,
in case something goes wrong.

Editing {\verb@CONFIG.SYS@} can be done with Notepad or a better editor,
but it must be done {\em very carefully}.  If you use Notepad, do
{\lq\lq}File{\rq\rq} / {\lq\lq}Open{\rq\rq}, and select {\lq\lq}All
Files{\rq\rq} behind {\lq\lq}Files of Type:{\rq\rq}, or you will never
see the {\verb@CONFIG.SYS@} file.  If {\verb@CONFIG.SYS@} does not yet
exist, just use {\lq\lq}File{\rq\rq}/{\lq\lq}New{\rq\rq} in Notepad
and save the new file as {\verb@CONFIG.SYS@} in the {\verb@C:\@} top
directory.  Your {\verb@CONFIG.SYS@} file should contain lines like:
\begin{verbatim}
SHELL=C:\WINDOWS\COMMAND.COM C:\WINDOWS\ /E:2048 /P
FILES=60
BUFFERS=30,0
STACKS=9,256
DOS=HIGH,UMB
\end{verbatim}
If you already have such lines (same first word), make sure that the
numbers are at least as big as shown above.  If you do not have such
lines, insert the lines as above, at the {\em end} of the CONFIG.SYS
file.  Carefully check that everything is fine, watching out for
typos, points instead of commas, semi-colons instead of colons,
slashes instead of backslashes, etcetera, (cut and paste from above is
recommended), then save.  If the file is new, be sure you save as
CONFIG.SYS in the {\verb@C:\@} folder.  If you use Notepad, select
{\lq\lq}All Files{\rq\rq} behind {\lq\lq}Save as Type{\rq\rq}, or it
may save it as CONFIG.SYS.TXT instead of as CONFIG.SYS.  You may want
to check it did not pull this trick on you anyway.  (If so, try
enclosing the name in double quotes when saving.)  Do not mess around
with other lines in the CONFIG.SYS file.  Later, when you are
confident that all works well, you might be able to reduce the various
values a bit by trial and error.

You will need to reboot now so that the new {\verb@CONFIG.SYS@} can be
made active.  Return to this point after the reboot.  If the reboot
produced problems, restore your original {\verb@CONFIG.SYS@} file and
consult someone familiar with CONFIG.SYS.
  

\subsubsection{Required for everybody}

Whether you want the easy install, or need to configure manually,
everybody needs to follow the steps below:

\begin{enumerate}
  
\item Log in with administrative privileges if you are on Windows NT
  or XP.

\item Install
  \htlink{ActiveState Perl}{http://www.activestate.com/Products/ActivePerl/}.
  Be sure to install to the default directory {\verb@C:\Perl@}.  File
  {\verb@perl.exe@} must be in directory \verb@C:\Perl\bin@.  Perl does
  not have to be added to your path: {\latextohtml-FU} will add it
  at run time if needed.
  
  Yes, some versions of TeX come with some limited perl, but they do
  not seem to work with {\latextohtml}; not enough packages.  The 50
  Mb for Active State perl is nowadays not a point, so just install
  it, OK?  You do not need to add Perl to your path during install
  unless you plan to use it yourself.  I do not.

  If you want to ignore this word of advice, Perl anywhere except at
  {\verb@C:\Perl\bin@} will require manual configuration.  Perl versions
  below version 5.002 will absolutely not work.  Use {\verb@perl -v@}
  to check.)
  
\item Install \htlink{Ghostscript}{http://www.cs.wisc.edu/~ghost/}.  I
  have version 8.14, at work we have 8.0.  Both work fine.  The manual
  lists 5.1 or later to avoid problems.  I recommend 8.14 since I know
  that that one works, and you must put it below {\verb@C:\gs@} like the
  installation should give as default.
  
  If you ignore this word of advice, Ghostscript anywhere except below
  {\verb@C:\gs@} will require manual install, or at least modification
  of \verb@C:\l2hsup\init.bat@.

\item Go to the \htlink{access page}{../zips/getdump.html}
  to get file {\verb@l2hfu3.exe@} (5 Mb).  Put it in the top folder
  of your {\verb@C:@} disk, below My Computer.
  
  {\em Note: this paragraph should be ignored.  By now emTeX is far
    out of date.  Just try MiKTeX instead.}  People without {\TeX}, or
  who have problem running their own {\TeX} with {\latextohtml} should
  also get \verb@l2hmtx.exe@, em{\TeX}, the best version of {\TeX}
  ever produced.  Lean and fast.  However, note that em{\TeX} is no
  longer being updated.  Also, if you need to add packages, you need
  to use the $5+3$ scheme to save any sty files with long names.  For
  example, to add the verbatimfiles package,
  {\verb@VERBAtimfiLES.sty@} would have to be copied to
  {\verb@C:\Emtex\Texinput\Latex2e\Etc@} as \verb@VERBALES.STY@.
  (Verbatimfiles is already installed, however, as is
  {\verb@subfiure.sty@} for the subfigure package.)

  Go to the \htlink{access page}{../zips/getdump.html} now to
  get {\verb@l2hfu3.exe@}.

\item Next you need to download a batch file to do the actual
  installation, depending on your version of {\TeX}.  Save this file
  again in the top folder of your {\verb@C:\@} drive by right-clicking
  the appropriate link below and selecting {\lq\lq}Save Target/Link
  As.{\rq\rq}  Select the batch file from the following list:

  \begin{itemize}
    
  \item {\em Note: this option is far out of date and should no longer
      be used.  Instead use one of the other options below.}  People
    who want to use {\em my} very old installation of em{\TeX} for
    {\latextohtml} should download
    \htlink{l2hinmtx}{../zips/scripts/l2hinmtx.bat}.  Don't forget you
    should already have downloaded both {\verb@l2hfu3.exe@} and
    {\verb@l2hmtx.exe@} in the previous step.  (Do not use this script
    with your own version of em{\TeX}, in that case use
    {\verb@l2hingen@} below instead.)  Note that emTeX is no longer
    compatible with current versions of LaTeX and limited to small
    documents.

  \item People with any version of MiKTeX should download
    \htlink{l2hinmkt}{../zips/scripts/l2hinmkt.bat}.
    I thank Prof.~Rogelio Alc\'antara for making me aware of the
    problems in MiKTeX 2.4, and with help fixing them.
    
    People with MiKTeX 2.5 downloaded late august 2006 or later please
    take note of the {\lq\lq}html{\rq\rq} package problem noted in
    subsubsection \ref{sec:prhtmli}.

  \item People with a recent version of fpTeX
    (now apparently superseded) should download
    \htlink{l2hinfpt}{../zips/scripts/l2hinfpt.bat}.

  \item People with a recent version of
    XEmTeX (as of April 2006) should download
    \htlink{l2hinxtx}{../zips/scripts/l2hinxtx.bat}.

  \item People with other variants or versions of {\TeX}, or who
    experience (unexpected) difficulties with the scripts above,
    should download \htlink{l2hingen}{../zips/scripts/l2hingen.bat}.
    This script will help you as much as possible, but you will probably
    still have to perform manual configuration, as detailed in the
    second subsubsection following.  Alternatively, you could elect to go
    the emTeX route above.  If you have a commercial version of TeX and
    are willing, we can work together to make an easy install script for that
    version of TeX.
    

  \end{itemize}

\end{enumerate}

Now in {\lq\lq}My Computer,{\rq\rq} open the {\verb@C:\@} drive and
double click the {\verb@l2hin....bat@} batch file you just loaded.
Follow the instructions on the screen.

If the batch file terminates with a request to try to process a
document, proceed to the next subsection.

If the batch file terminates in a message that installation failed,
see what else it says on the screen.  Contact me, section \ref{sec:support},
if you cannot figure out why it failed,
after writing down what it said last on the screen.

Alternatively, you can double-click {\verb@l2hfu3.exe@} to at least
install the {\latextohtml} files.  That should really be enough to
allow you to go to the second subsubsection following, manual
configuration.

Some other potential problems that I can think of:

\begin{itemize}
  
\item Problems with untested Windows versions.  I have not tested
  them, so I am just assuming that if 98 and XP work, everything in
  between will work, and that 95 and ME are no different from 98.  If
  you have other info, let me know.

\item Out of disk space, or files set to read-only.

\item No administrator privileges under NT or XP.

\item Files put in the wrong folder, not the top {\verb@C:\@} folder.

\end{itemize}


\subsubsection{Check installation}

You are now ready to process a simple test document and see whether
everything is OK.  (These instructions are also printed on your screen by
the installation script.)

Open the \verb@l2hsup@ folder on the \verb@C:@ disk in My Computer, then
\begin{itemize}
\item Windows 95 to ME users should double click the {\verb@Windows_98-ME@}
  icon.
\item Windows NT to XP users should double click the {\verb@Windows_XP@} icon.
\end{itemize}
This creates a command window for running latex2html.  (You may want to copy
the icon to the desktop for easier access in the future.)

You will now use this command window to convert a document to HTML.
That document is {\verb@index.tex@} in the subfolder {\verb@check@} of
the folder {\verb@l2hsup@} on the {\verb@C:\@} drive.  In the command
window, enter the following commands to do so:
\begin{verbatim}
c:
cd \l2hsup\check
latex index
latex index
l2h
\end{verbatim}
Enter a running title when asked. Watch the screen including top
window line.

Be sure the {\verb@latex@} commands correctly process the document.
That has nothing to do with {\latextohtml}, just whether your version
of {\TeX} is functioning correctly.  (With the exceptions noted in the
notes below.)  In the {\verb@l2h@} command, Perl may take a minute to
start up {\latextohtml} on an older Windows 98 machine.  The
{\verb@l2h@} command will complain about {\lq\lq}large{\rq\rq}, and
about having to make images of nonstandard accented characters, this
can be ignored.

To examine the created web pages, in {\lq\lq}My Computer{\rq\rq} open
the folder {\verb@l2hsup@}, then the subfolder {\verb@check@}, and
double click {\verb@index.html@}.  Check the web pages to ensure that
the math formulae and the figure are there.

If there are any problems, first check out the following additional
notes for the installation script you used:
\begin{itemize}
\item \htlink{emTeX}{../notes/notesmtx.html}
\item \htlink{fpTeX}{../notes/notesfpt.html}
\item \htlink{MiKTeX}{../notes/notesmkt.html}
\item \htlink{XEmTeX}{../notes/notesxtx.html}
\item \htlink{Other}{../notes/notesgen.html}
\end{itemize}
If that does not solve it, proceed to the next subsubsection.

However, if everything was OK,
proceed to section \ref{sec:usage}, {\lq\lq}Usage{\rq\rq}.


\subsubsection{Manually configure {\latextohtml}}

As you will see, the installation is not for the unsophisticated,
though easier than the original stand-alone \latextohtml.  And all I
can do is answer questions you may have on the installation
procedures, not on your operating system or version of TeX.  However,
if you have a commercial version of TeX, or another current system,
and want to work together to create an easy install procedure for that
TeX/operating system, contact me, section \ref{sec:support}, and we
will mess around until we find out how to do it.  If there is an
apparent problem in the installation procedure, I will fix it
immediately, e-mail me.  The same if you have hints or corrections to
the installation instructions that may make it easier for others.
Ways to deal with different {\LaTeX} implementations is one example.

I will try to be complete, in any case.  Read through all instructions
before doing anything.  Don't make changes in the procedure or you
will get in trouble.  Watch for typos doing the install.

\begin{enumerate}
  
\item Go into {\lq\lq}My Computer{\rq\rq}, and open the {\verb@C:\@}
  drive, then the {\verb@l2hsup@} folder in it.  (If you do not have the
  {\verb@l2hsup@} folder, it is back to the second last subsubsection.)
  
\item (You may want to examine a file called \verb@initbin.txt@ in
  this folder.  It is supposed to hold a pointer to your {\TeX}
  installation location.  If it does not, you may want to delete the
  file; most {\TeX} installations are already set up to work fine
  without such a pointer.)

\item Based on your version of Windows, double-click either the
  Windows\_98-ME or Windows\_XP icons to create a {\lq\lq}command
  window{\rq\rq}.  Enter the following in this window:
\begin{verbatim}
DOSKEY /INSERT
\end{verbatim}
  (This will allow you to correct typos with the arrow keys.)  Leave
  the window as is for now.

\item \label{lattest} The crucial thing is to get a file called
  {\verb@latexl2h.bat@} to function properly.  The l2hingen script you
  ran will have selected a best guess for this file.  The first thing
  is to try whether it works out of the box.
  
  To do so, in Windows Explorer, go into the subfolder \verb@test@ of
  {\verb@l2hsup@}.  Double click the file \verb@test.bat@ in that
  folder.  If all is well, it will run {\LaTeX} a couple of times.
  The second time there will be an undefined variable
  \verb@\alliswellthatendswell@.  This is intentional, just check that
  the {\LaTeX} identifies itself as {\lq\lq}LaTeX2e{\rq\rq} and hit
  return.  If execution ends in the message {\lq\lq}Test seems fine.
  Hit any key to continue...{\rq\rq}, and it ran 2e, with {\em no}
  cheating, you have finished the most tricky part of the
  installation.  Proceed with item \ref{latok}.
  
  If not, you will need to create {\verb@latexl2h.bat@} from scratch.  There
  should be a batch file {\verb@setmod.bat@} in folder
  {\verb@l2hsup@}; double click it to reset {\verb@latexl2h.bat@} to generic
  form.
  
  Now Right click the file {\verb@latexl2h.bat@} in the same folder,
  and select {\lq\lq}Edit.{\rq\rq} You will be changing this file to
  work on your system. Make the Notepad window wide enough.
  
  Leave Notepad alone too for now and go find the documentation that
  came with your version of {\LaTeX} 2e and find:
  \begin{enumerate}
  \item The DOS command to run {\LaTeX} 2e
  \item The way to set the TEXINPUTS (or TEXINPUT for some versions
    of {\TeX}) variable.
  \end{enumerate}
  
  Now if your system uses TEXINPUT instead of TEXINPUTS, at the
  indicated place REQUIRED CHECK, change the {\lq\lq}yes{\rq\rq} into
  {\lq\lq}no{\rq\rq}.

  Then, under REQUIRED MODIFICATION 1 you need to set TEXINPUTS correctly
  for your system, as detailed in your manual, but add to it the
  \verb@..;@ or \verb@;..@ next-higher directory.
  
  Examples of how to do this on various systems can be found in the files
  \verb@latexl2h.mtx@ for em{\TeX}, \verb@latexl2h.fpt@ for fp{\TeX},
  \verb@latexl2h.xtx@ for XEmTeX, and {\verb@latexl2h.mkt@} for MiKTeX.
  
  If you have MiKTeX 2.4, don't bother with TEXINPUTS at all, it will
  not help.  Instead just copy latexl2h.m24 into latexl2h.bat.  You
  also will need to append the miktex.ini file found in the subfolder
  \verb@local@ of subfolder \verb@m24@ of subfolder \verb@l2hmods@ of
  folder {\verb@l2hsup@} to your local miktex.ini file as described in
  the MiKTeX documentation.  (The \verb@l2hingen@ script should have already
  done all this for you, however.)

  Next, under REQUIRED MODIFICATION 2, you need to put the
  command to run latex on your machine, giving it arguments
  \verb@%1 %2 %3 %4 %5 %6 %7 %8 %9@ for technical reasons.
  
  After making the above modifications and saving the
  \verb@latex2lh.bat@ file (don't forget to save!), double click the
  file \verb@test.bat@ in the subfolder \verb@test@ of {\verb@l2hsup@}
  again and see whether it works now.  If execution ends in the
  message {\lq\lq}Test seems fine.  Hit any key to
  continue...{\rq\rq}, and it ran 2e and noticed the undefined string,
  proceed with item \ref{latok}
  
  If {\LaTeX} says it is LaTeX2e and correctly processes the file in
  Test 1, but Test 2 comes back with a message that the latex command
  may be a batch file, use Find from the Windows Start menu to find
  that batch file.  For example, if you used the command
  {\verb@latex2e@} to run \LaTeX, search for the file named
  {\lq\lq}latex2e.bat{\rq\rq}.  After finding it, open that file in
  Notepad.  The way to actually run {\LaTeX} should be inside.  Copy
  that over to latexl2h.bat instead of the batch file name.  If you
  are lucky, it also has the correct way to set TEXINPUT[S].  Just
  copy that over to latexl2h.bat too and append {\lq\lq};..{\rq\rq} or
  {\lq\lq}..;{\rq\rq} to it.  Save and go repeat the test.

  If you cannot find your documentation, you might try {\verb@latex@} or
  {\verb@latex2e@} for the command line.  (Of course followed by
  \verb@ %1 %2 %3 %4 %5 %6 %7 %8 %9@).  Or use Find in the Windows
  Start menu to search for likely candidate files (search for string
  {\lq\lq}latex{\rq\rq} or just {\lq\lq}tex{\rq\rq}, say.)  It should
  have a .exe, .com, or .bat file extension.  (If it has a .bat file
  extension, see above for what to do with that.)
  
  If you cannot find how to set TEXINPUTS, enter the following
  in the DOS window you opened up earlier:
\begin{verbatim}
set | find /i "TEXINPU"
\end{verbatim}
  If you then see a line like, maybe,
\begin{verbatim}
TEXINPUTS=c:\tex;c:\letters;c:\y&ytex\latex;c:\y&ytex\latex2e;.
\end{verbatim}
  you are in luck.  At the appropriate place under {\lq\lq}REM
  REQUIRED MODIFICATION 1{\rq\rq} in latexl2h.bat, add a line
\begin{verbatim}
set TEXINPUTS=c:\tex;c:\letters;c:\y&ytex\latex;c:\y&ytex\latex2e;.;..
\end{verbatim}
  In short, put {\lq\lq}set {\rq\rq} in front of the line and append
  {\lq\lq};..{\rq\rq} to it.  Save latexl2h.bat and repeat the test.
  
  If that does not work either, if you have Y\&YTeX, try the line
  above anyway.  If you have \texlive/ fp\TeX/\-te\TeX, you should
  try:
\begin{verbatim}
set TEXINPUTS=;.;..
\end{verbatim}
  
  If nothing works and you cannot pass the test according to
  requirements, restore {\verb@CONFIG.SYS@}, delete file folders
  \verb@l2h@, {\verb@l2hsup@}, and \verb@l2hins@ on the C:
  disk. Take out your MS Word documentation.  {\latextohtml} is not for
  you.  Most people are perfectly happy with the web pages produced by
  Bill Gates anyway.

\item \label{latok} Now you need to find how to run dvips on your
  system.  In the DOS window:
\begin{verbatim}
c:
cd \l2hsup\test
dvips32 -Ppdf -E index
\end{verbatim}
  If dvips(32) does not answer, try plain \verb@dvips@, which is correct for
  \texlive.  If that does not work, search for the files as before.
  If dvips answers but complains about the -E (eps files) option, you
  want to consider upgrading to version
  \htlink{5.8.3}{../zips/dvips583.zip}.  If dvips does not know the
  pdf printer, your formulae are not going to be as sharp as they
  could be.  Consider installing just the dvips part of \texlive.
  Yes, I know.  Otherwise leave out {\lq\lq}-Ppdf{\rq\rq}.
  Anyway, write down how to run dvips on a piece of paper.

\item You need to find out how to run the {\TeX} executable on your system.
  In the DOS window, try
\begin{verbatim}
tex index
\end{verbatim}
  If {\TeX} answers, and complains about the {\LaTeX}, all is OK; just
  enter {\verb@x@} to exit.  Otherwise, search for the
  executable.  It might be the same as the one that runs \LaTeX
  without the \verb@&latex@ or whatever.  On my system, it is
  \verb@tex386@, which is typical for emTeX.  If you
  cannot find it, just write down the same executable as used for
  {\LaTeX} for both {\TeX} and ini{\TeX} below and don't use the
  stupid -ldump option of \latextohtml.  It is {\em not} going to save
  any time anyway.

\item You need to figure out how to run ini{\TeX} on your system.
  In the DOS window, try
\begin{verbatim}
initex index
\end{verbatim}
  On my system, ini{\TeX} is run by adding a \verb@/i@
  behind the {\TeX} executable \verb@tex386@.  On some systems,
  that is \verb@ -ini @ instead.

\item You {\em do} need to find the way to run ghostscript
  on your system.  In the DOS window you opened earlier, type:
\begin{verbatim}
gswin32c
\end{verbatim}
  If ghostscript answers, just enter \verb@quit@.  The way to run
  ghostscript is {\lq\lq}gswin32c{\rq\rq}.  Otherwise, use Find in the
  Start menu to find the file named {\lq\lq}gswin32c.exe{\rq\rq}, and
  add the full path to the file.  (If you only have
  {\lq\lq}gswin32.exe{\rq\rq}, you must upgrade ghostscript.)  For
  example my gswin32c is in folder {\lq\lq}bin{\rq\rq} which is in
  folder {\lq\lq}gs8.14{\rq\rq} which is in folder {\lq\lq}gs{\rq\rq}
  on the C drive, so my way of running ghostscript is as
\begin{verbatim}
C:\gs\gs8.14\bin\gswin32c
\end{verbatim}
  Your version numbers are likely to be different.  Write down how to
  run ghostscript after you get it to work.
  
\item You need to find out how to run perl on your system.  In the DOS
  window, try:
\begin{verbatim}
perl -v
\end{verbatim}
  If perl answers, the command to run perl is {\verb@perl@} (without
  the {\lq\lq}-v{\rq\rq}).  On my system, it is\\ 
  \verb@C:\Perl\bin\perl.exe@.
  
\item Right-click the file \verb@config.bat@ in the
  \verb@l2hins@ (not {\verb@l2hsup@}) directory and select Edit.
  Find the line\\ {\verb@set PERL=C:\Perl\bin\perl.exe@} (or
  maybe just \verb@set PERL=perl@) and replace
  {\verb@C:\Perl\bin\perl.exe@} (or \verb@perl@) with the way to run
  perl on your system you just found.  Save.

\item \label{reinst} Edit the file \verb@prefs.pm@ in the
  \verb@l2hins@ directory using Notepad or better.  You want
  to make the minimum changes you can; {\em after} everything works
  correctly, you can always go back and play around.
  
  Do not touch the {\verb@$prefs{'TEXLIVE'} = 'no';@} line even if you
  have \texlive.
  
  Find the TEX line, starting with {\verb@$prefs{'TEX'}@} and put the
  way to run {\TeX} on your system between the single quotes behinf
  the equals sign.  Note that you need to double any backslashes in
  \verb@prefs.pm@.
  
  Change the \verb@INITEX@ line a few lines below correspondingly.
  (If, like on my system, you need to append \verb@/i@ or \verb@-ini@,
  {\em do not} do that here.  Instead open file {\verb@l2hconf.pin@}
  (not \verb@.pm@) and add the {\verb@/i@} behind {\verb.@INITEX@.} a
  few lines down in that file.  Return to \verb@prefs.pm@.)
  
  Change the value of TEXPATH, into the folder where you want the
  {\verb@\usepackage@} packages that come with {\latextohtml} to be
  put.  This can be any of the TEXINPUTS directories except the . or
  .. ones.  In the same place as {\lq\lq}article.cls{\rq\rq}, the
  article-style class file, would be a pretty sure bet.  Modern
  installation of {\TeX} tend to use something like
  {\verb@...\\texmf\\tex\\latex\\latex2html@}, the dots denoting
  possible higher directories, and the {\verb@latex2html@} folder
  to be added during the installation.

  Change the value of the DVIPS to what you found.
  
  If you found that the pdf printer did not work, remove {\verb@ -Ppdf@}
  from the DVIPSOPT pref.  In that case you may eventually want to
  experiment with the next three options to try to improve the quality
  of math images.

  If your dvips did not do eps, set EPS to 0 instead of 1.
  
  Change the GS ghostscript option.  Change all three, just to be
  safe.
  
  Save \verb@prefs.pm@.  Just doing a simple save should be OK.
  Otherwise, make sure to select {\lq\lq}All files{\rq\rq} when
  saving, or it may save it as \verb@prefs.pm.txt@.  If it still does.
  enclose \verb@prefs.pm@ between double quotes when saving.  It's
  Microsoft.
  
\item If you use EmTeX, which uses EMX/RSX, the warning message
  produced by RSX when dvips runs interferes with the installation
  procedure.  Use \verb@SET RSXOPT=-Re0@ to turn it off.

\item In the DOS window, do
\begin{verbatim}
c:
cd \l2hins
del config.log
config
\end{verbatim}
  If this terminates in an error message, try to solve it by making
  appropriate changes in file {\lq\lq}prefs.pm{\rq\rq}.  Repeat
  from \verb@del config.log@.
  
  If you get to the stage where it creates all files from
  {\lq\lq}cfgcache.pm{\rq\rq} to {\lq\lq}l2hconf.pm{\rq\rq}, carefully
  examine the log file {\lq\lq}config.log{\rq\rq} in the
  {\lq\lq}l2hins{\rq\rq} directory using Notepad or better.
  I have {\lq\lq}no{\rq\rq}s for kpsewhich, mktexlsr, and texhash,
  which em{\TeX} does not use.  If you get another {\lq\lq}no{\rq\rq},
  investigate before proceeding to the next item.
  
\item You are now ready to test for basic operation.  In the DOS box,
  enter:
\begin{verbatim}
test
\end{verbatim}
  If it freezes at some stage, have a look at what is in the
  {\verb@C:\Temp@} directory for a clue, and try hitting the Return
  key.  If it just complains about aux files, but tells you to view
  results with your browser, do so.  The web pages should look rough,
  but correct.  If not, I recommend pulling a lot on your hair.  One
  thing you could do if you have used all your hair, is to examine
  whatever is in the {\lq\lq}Temp{\rq\rq} folder on the C: disk.
  Latexl2h.bat that you modified earlier puts some error info there if
  errors occur.

\item If the test web pages are correct, in the DOS box, enter
\begin{verbatim}
install
\end{verbatim}
  This will create the folder {\lq\lq}l2h{\rq\rq} on the C: disk.

\item Get rid of the junk.  In the DOS box:
\begin{verbatim}
c:
cd \l2h
C:\l2hsup\var\deldir texinputs
\end{verbatim}

\item If you have an older DOS type {\TeX}, you might need to rename the
  {\verb@verbatimfiles.sty@} file, (use Windows Find to find the one in
  your TEXINPUTS path,) since its name is too long.  For emTeX, I have
  to rename it to verbales.sty.

\item If your dvips version supported the -E option, execuye the following
  command to create a non-eps option to deal with the
  occasional buggy figure, such as some figures using \verb@\special@.
\begin{verbatim}
C:\l2hsup\var\creaneps
\end{verbatim}
  which is the last thing to do.  You probably want to keep
  installation folder l2hins in case your system changes.

\end{enumerate}

If you have information that may be helpful to others for installing,
e-mail me, section \ref{sec:support}, including your flavor and
version of {\TeX} and I will add it to this document.

If there are errors in the installation procedure, please let me know;
I will correct them immediately.


\subsubsection{Uninstall}

This install does not make significant changes to your system.  The
scripts do not touch {\verb@config.sys@}, {\verb@autoexec.bat@}, or
the registry.  Simply deleting the folders {\verb@l2h@},
{\verb@l2hins@}, and {\verb@l2hsup@}, {\verb@l2hold@},
and {\verb@EMTEX@} and {\verb@texfonts@} if present, pretty much get
rid of it.

However, the better method is to double-click the
{\verb@uninstal.bat@} file in the {\verb@l2hsup@} folder on the C:
drive.  This will undo all changes, including remove the style files
the installation may have added to your TeX installation, and the bug
fixes performed for some versions of MiKTeX.  First make sure that you
have closed any DOS window that you may have used to test the
installation.

I find that Windows XP may keep open the {\verb@l2hsup@} window even after
the folder has disappeared.  It{\rq}s Microsoft.  Just check in the
{\verb@C:@} folder.  If the install was OK, but the folders are still
there, an earlier version was restored.  Just keep uninstalling until
the earlier versions run out.

What the uninstall script does beyond deleting the folders above can
be found in {\verb@uninsta2.txt@} in the {\verb@var@} subfolder.
Users familiar with DOS can examine this file by right-clicking it and
selecting {\lq\lq}Edit.{\rq\rq} The trouble with uninstall scripts is
that they are unaware of any relevant changes you may have made to
your system after you installed {\latextohtml}.  Is {\TeX} still there?
Have you removed or moved the style files yourself?  The script tries
to be robust in those matters, but there are limits.

Windows 98-ME users will want to restore their original
{\verb@CONFIG.SYS@} if they changed it.

If you also downloaded emTeX, there is an {\verb@uninstal.bat@} file
in the {\verb@EMTEX@} folder too.

Perl and Ghostscript have their own uninstall procedures.


\subsection{Unix Installation Instructions}
\label{sec:instux}

{\bf Note: The software described on these pages is no longer
  supported.  Do NOT follow the instructions here. To obtain the fixed
  up version of {\latextohtml} described here, go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

\subsubsection{Easy linux install}

Continued availability of this installation procedure will depend on
whether the various people who wrote the software involved complain
about this distribution procedure.

This install was found to work on Centos 4.4 with TeXlive 2007, Debian
Etch with teTeX, and Debian Lenny with TeXLive. It should work on
other linux versions running on x86 machines, but {\em not} on
non-Intel hardware.  On Lenny 5.0, 5/7/09, I found that I had to
install the libg2c0 g77 library, which is apparently no longer
automatically included.

Other versions of TeX should be OK as long as they have an TeXLive
compatible {\verb@latex@} command and process {\verb@TEXINPUTS@} the
same way.  You can also use the easy install as a basis for an
incompatible version of TeX and take it from there (i.e. then adjust
{\verb@latexl2h@} and {\verb@prefs.pm@} as described in the full
installation section and run {\verb@configure@} and the
{\verb@make@} commands.)

Preparation is to check that you have decent versions of
{\verb@ghostscript@}, 5.1 or later, and {\verb@/usr/bin/perl@}, 5.002
or higher.  In a terminal/xterm/console/command window, try
\begin{verbatim}
gs -version
perl -v
\end{verbatim}
If you do not yet have either program installed, your linux package
manager can do it.  You also need the
\htlink{Info-ZIP}{http://www.info-zip.org/} unzip utility or
equivalent.

For {\LaTeX} you should have the \htlink{epsf.sty}{../notes/epsf.sty}
and {\verb@hyperref@} packages installed.  If you do not yet have
them, \htlink{TUG}{http://www.tug.org/} has them in downloads/CTAN.
From the 2007 TeXlive DVD, you can instead install them using the
commands
\begin{verbatim}
sh install-pkg.sh --package=hyperref --nodoc --nosrc
sh install-pkg.sh --package=epsf --nodoc --nosrc
\end{verbatim}

Now go to the \htlink{access page}{../zips/getdumpl.html} to get file
{\verb@l2hlnx86.zip@} (4 Mb).  Put it in your HOME folder.

Open a terminal/xterm/console/command window and enter:
\begin{verbatim}
tcsh
cd ~
unzip l2hlnx86.zip
cd ~/l2h/l2hins
[read the absence-of-warranty, license, readme, FAQ, and manifests there]
cd ~/l2h/l2hsup/copright
[read all files there]
\end{verbatim}

To install the fixes, continue with:
\begin{verbatim}
source ~/l2h/l2hsup/init
~/l2h/l2hsup/l2hinstall
\end{verbatim}

Now check your installation on an example file.  Open a new
terminal/xterm/console/command window and enter:
\begin{verbatim}
tcsh
source ~/l2h/l2hsup/init
cd ~/l2h/l2hsup/check
latex index
latex index
\end{verbatim}
If the file does not process correctly under {\verb@latex@}, it has
nothing to do with {\latextohtml}, only with your {\LaTeX}
installation.  See section \ref{sec:prsty} for the most common
problems.  If the file does process correctly under {\verb@latex@},
make the web pages as follows:
\begin{verbatim}
l2h
\end{verbatim}
Examine them in your browser to ensure that the math formulae and the
figure are there.

Normal usage of {\latextohtml} is similar.  Put a copy of your LaTeX
document, renamed to {\verb@index.tex@} in a suitable folder of its
own, and add copies of all required figures and files to the same
folder.  Open a new terminal/xterm/console/command window and enter:
\begin{verbatim}
tcsh
source ~/l2h/l2hsup/init
cd folder_name_with_index.tex_in_it
latex index
latex index
l2h
\end{verbatim}

Now proceed to section \ref{sec:usage}, {\lq\lq}Usage{\rq\rq}.  Or if
your {\LaTeX} is incompatible with TeXlive, proceed to the full
installation section \ref{sec:uxins}, point \ref{lnxskip} and
following.

Uninstall: This install makes {\em zero} changes to your system.  If
you want to uninstall, simply delete the l2h directory in HOME and the
zip file, and it is completely gone.

To obtain the unmodified {\latextohtml} version 99.2 source, simply
unzip without using the l2hinstall script.  The unmodified sources are
in l2h/\-l2hins and can be compared to the fixed-up ones found
in l2h/\-l2hsup/\-l2hmods.


\subsubsection{Introduction to the full install}

{\bf Note: The software described on these pages is no longer
  supported.  Do NOT follow the instructions here. To obtain the fixed
  up version of {\latextohtml} described here, go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

As you will see, the installation is not for the unsophisticated,
though easier than the original stand-alone \latextohtml.  I am
assuming someone using Unix is a lot more sophisticated than a typical
Windows user.  If you are unexperienced in Unix, get someone to help
you.

As detailed in section \ref{sec:support}, support is limited.  I will
gladly explain anything that may be unclear in the installation
procedure below, and how it worked for me on Sun Solaris and Centos.
But I do not have access to other versions of Unix or Mac OS.  I also
never figured out Mac OS; it is all too far hidden away.  Maybe with
OS X, you could use either the DOS or the Unix scripts to run
latex2html, since it has a Unix engine and, I believe, a DOS emulator.
If you want to work with me to get this stuff working on non-Intel
linux or Mac OS X, I am willing.  Contact me, section
\ref{sec:support}.


\subsubsection{Prerequisites}
\label{prerequx}

Note that your Unix system needs to be set up to run perl on scripts
with a perl header line.  Apparently, some systems do not.  Complain.
But not to me.

Before you can install {\latextohtml} and the \latextohtml-FU fixes,
you need to have the following list of required programs already
installed, and running correctly.  If your installation is old,
upgrade to the latest version.  (If you ever run into trouble with one
of them, try the version I am using and see whether it resolves the
problem.)

Since I do not have system privileges on the Unix cluster that I use
(Sun Solaris), I am simply using the versions that are there, with the
noted exceptions.

\begin{itemize}
  
\item 
  The \htlink{Info-ZIP}{http://www.info-zip.org/}
    unzip utility must be in your path to install.  We have 5.32.  While
  messy, I guess you could follow the steps of the unzipit script (see
  below) manually on a Windows machine (binaries in the Windows 98
  section above) and transfer the files.  Typical installations of
  linux seem to have unzip already.
  
  There is really no need to do so, however, since there is a big set
  of ready-to-run binaries for almost any conceivable system
  \htlink{here}{http://www.info-zip.org/UnZip.html}.

  You should also have zip in your path for the makezip utility to
  work, though you can live without this utility.
  
\item \htlink{\LaTeX}{http://www.tug.org}.  I don't know why you are
  reading this if you do not have \LaTeX, but you probably want
  version 2e, from 6/95 or later.  {\LaTeX} 2.09 will work for simple
  documents, with limitations.
  
\item \htlink{Dvips}{http://www.tug.org}.  If you have \texlive, you
  should, reasonably speaking, already have it.  The later versions
  with the pdf {\lq\lq}printer{\rq\rq} are best, but those are only in
  \texlive and teTeX (which is as of 2007 considered obsolete).  You
  need at least version 5.62, or you will need to make changes to the
  installation procedure; see the official manual.
  
\item \htlink{Ghostscript}{http://www.cs.wisc.edu/~ghost/}.  We have
  version 8.0.  The manual lists 5.1 or later to avoid problems.
  
\item Perl.  As far as I know, any decent unix installation should
  come with a decent perl already installed.  Otherwise, have a look
  at \htlink{ActiveState Perl}
  {http://www.activestate.com/Products/ActivePerl/}. We are using perl
  v5.6.1, origin unknown, probably not Active State.  {\latextohtml}
  is all perl scripts, you cannot live without perl.  Below version
  5.002 will absolutely not work.  (Use {\verb@perl -v@} to check.)
 
\item
  The \htlink{Netpbm graphics utilities}{http://netpbm.sourceforge.net/doc/}.
  We seem to have netpbm version 1, dating from 1994!  That is {\em not}
  the version you want to have.  For one thing, you most definitely need the
  {\verb@pnmcolormap@} and {\verb@pnmremap@} programs, which do the reduction
  in number of colors that allow the gif images to be made of the formulae
  and figures.

  So, I created my own updates of the more
  essential binaries.  Below is a log of my inputs.  These are {\em not}
  installation instructions, just a basis for comparison.  For example,
  you may have to specify gmake instead of make.
  
  Also, you may want to install the l2h directory tree elsewhere than
  in your home directory.  For example, this would apply for a
  multi-user setup.
  
  I {\em do} however recommend that you try to install the same
  version of the utilities in the same way.  It is the only way to
  have some confidence that the installation will work correctly, and
  will still work correctly next year.  It may duplicate a few netpbm
  utilities in {\verb@/usr/local/bin@}, (16 of them, to be exact, all
  critical to {\latextohtml}), but they are very small files anyway.
  
  Versions that are too early will simply not work correctly.
  Versions that are later versions than when {\latextohtml} was
  written also do not work, since the program requires specific
  behavior, and netpbm is in a constant flux of change.  (As far as I
  know, the current version of netpbm at the time of this writing,
  2004-5, does work, but that is only because I fixed the problems.
  They {\em do not} work correctly with the official distribution.)
  
  You do not want to come back next year if someone upgraded netpbm in
  {\verb@/usr/local/bin@}, or just moved the files or libraries, and
  do this all again.

  For your convenience, a zipped version of the required version
  netpbm sources is \htlink{here}{../zips/netpbmux.zip}, and
  the jpeg library is \htlink{here}{../zips/jpegux.zip}.

  My netpbm install log follows now:

\begin{verbatim}

tcsh

mkdir $HOME/l2h
mkdir $HOME/l2h/l2hsup

mkdir $HOME/work
cd $HOME/work
[put the netpbmux.zip and jpegux.zip in this directory]

unzip jpegux
tar xvf jpegsrc.v6b.tar
cd jpeg-6b/
more install.doc
./configure
make
[lots of verbosity, but it produces the file]
cp libjpeg.a ~/l2h/l2hsup/
cd ..

unzip netpbmux
tar xvf netpbm-10.18.18.tar
cd netpbm-10.18.18/
more doc/INSTALL
./configure
Platform [?] ==> sun
gcc or cc [gcc] ==>
regular or merge [regular] ==>
static or shared [shared] ==> static
library filename or 'none' [libjpeg.so] ==> /home/e121/dommelen/l2h/l2hsup/libjpeg.a
JPEG header directory [default] ==> /home/e121/dommelen/work/jpeg-6b
library filename or 'none' [libtiff.so] ==> none
library filename or 'none' [libpng.so] ==> none
library filename or 'none' [libz.so] ==> none
Documentation URL [http://netpbm.sourceforge.net/doc/] ==> 
cd converter/other
make bmptopnm
make giftopnm
make jpegtopnm
make pnmtojpg
make pnmtops
mv anytopnm jpegtopnm giftopnm pnmtops ~/l2h/l2hsup
mv bmptopnm ~/l2h/l2hsup/bmptoppm
mv pnmtojpeg ~/l2h/l2hsup/ppmtojpeg
cd ../ppm
make ppmtobmp
make ppmtogif
mv ppmtobmp ppmtogif ~/l2h/l2hsup
cd ../../generator
make pbmmake
mv pbmmake ~/l2h/l2hsup/
cd ../editor
make pamflip
make pnmcat
make pnmcrop
make pnmflip
make pnmremap
mv pamflip pnmcat pnmcrop pnmflip pnmremap ~/l2h/l2hsup
cd ../other
make pnmcolormap
mv pnmcolormap ~/l2h/l2hsup/
cd ../analyzer
make pamfile
mv pamfile ~/l2h/l2hsup/pnmfile
\end{verbatim}

  I recommend that you back up the created binaries to a safe location
  to avoid having to do this again later if a disk crashes.

\item
  The \htlink{Gnu Fortran Compiler}{http://gcc.gnu.org/releases.html}.
  We have 3.3.2.
  
  (I really think it is quicker to install the compiler if you do not
  have it, than to adjust the Fortran files in the doc subdirectory to
  read and write files without new lines and record boundaries (fgetc
  and fputc in g77), and to accept command line parameters the same
  way as g77.  Though I guess it could be done; Watcom can do it using
  unformatted I/O with a declared recl of 1 and library functions.
  You could live without l2hnewer.f if you give up the convenience
  features.  Or use the script version if you have newer from texlive.
  L2hcrop.exe and l2hcomp.exe are the very core of {\latextohtml}-FU;
  without them, it is a pretty useless fix.)

\end{itemize}

\subsubsection{Installation}
\label{sec:uxins}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

Next, perform the following steps. Note that I am using tcsh, but feel
free to use csh instead.  Also, use your favorite editor if for some
weird reason it is not emacs.

\begin{enumerate}
  
\item You need to decide on a top directory for the {\latextohtml}
  files.  I use {\verb@$HOME/l2h@}, which I created using
  {\verb@mkdir@}.  You could just use {\verb@$HOME@}, for a single
  user setup.  For a multiuser setup, {\verb@/usr/local/l2h@}
  springs to mind.  In any case, enter:
\begin{verbatim}
tcsh  (or csh)
setenv L2HTOP $HOME/l2h   (or whatever)
mkdir $L2HTOP   (if you did not already)
cd $L2HTOP
mkdir l2hsup   (if you did not already)
mkdir l2hsup/unzip
mkdir temp
setenv PATH "$L2HTOP/l2hsup:$PATH"
rehash
cd l2hsup
\end{verbatim}
  Make sure that {\verb@L2HTOP/l2hsup@} is at the {\em start} of your
  path, or you may use the wrong netpbm files from /usr/local/bin or
  wherever instead of l2hsup.  This will interfere with the netpbm
  capabilities tests during the configuration, causing
  misconfiguration.
  
\item I recommend you put copies of the following 16 netpbm utilities
  into directory {\verb@l2hsup@}. (See subsection \ref{prerequx} on
  the recommended procedure to build them, but even if you decide to
  use preexisting ones in /usr/local/bin or wherever, I still
  recommend to put copies in {\verb@l2hsup@}, they are small):

  \begin{center}
    anytopnm
    bmptoppm
    giftopnm
    jpegtopnm
    pamflip
    pbmmake
    pnmcat
    pnmcolormap \\
    pnmcrop
    pnmfile
    pnmflip
    pnmremap
    pnmtops
    ppmtobmp
    ppmtogif
    ppmtojpeg
  \end{center}

\item You will now need to put various required files into the created
  {\lq\lq}unzip{\rq\rq} subdirectory.  Right click the next links to get
  your browser to save them as files.  Of course you need
  \latextohtml, and you need version 99.2.  Do not even think of
  trying another version.  For your convenience, I have a zipped
  version \htlink{here}{../zips/l2hins.zip}.  And you need my
  fixes, which are \htlink{here}{../zips/l2hsupux.zip}.
  Finally, you need a csh script {\lq\lq}unzipit{\rq\rq} to put
  various things into their right places.  It is
  \htlink{here}{../zips/unzipit}.  Make sure it is saved with name
  {\lq\lq}unzipit{\rq\rq}, not {\lq\lq}unzipit.htm{\rq\rq}; you may need to
  put it in quotes.

\item In tcsh,
\begin{verbatim}
cd unzip
chmod a+x unzipit
./unzipit
\end{verbatim}
  This will check your files and put various things in their right
  places.  If all goes well, it will say so.  If
  you see stars, something is wrong.  Any files missing or names
  mistyped?  Examine the unzipit script in emacs, if needed.

  Still in tcsh,
\begin{verbatim}
rehash
\end{verbatim}

\item \label{lnxskip} In tcsh,
\begin{verbatim}
cd $L2HTOP/l2hsup
emacs latexl2h      (or nedit latexl2h; may want to append & in X-windows.)
\end{verbatim}
  You need to add two lines to this file, at the places indicated in
  the file. First a line that adds {\lq\lq}..{\rq\rq} to TEXINPUTS.
  See your {\LaTeX} documentation on how to do this, If you use
  te{\TeX}/ {\texlive}, you might try the following line, which works
  fine on our te{\TeX} system (it is already in the script, just
  uncomment it:)
\begin{verbatim}
setenv TEXINPUTS :..:.   (or, see below, setenv TEXINPUTS :..:.:$L2HTOP)
\end{verbatim}
  Second you need to add a line that runs {\LaTeX} 2e on
  the parameters \$1...\$9, probably just
\begin{verbatim}
latex $1 $2 $3 $4 $5 $6 $7 $8 $9
\end{verbatim}
  See your {\LaTeX} documentation or the hints in the Windows 98 subsection
  if you run into trouble with these two lines.

\item in tcsh,
\begin{verbatim}
cd test
./test
\end{verbatim}
  If all is well, {\verb@test@} will run {\LaTeX} a couple of times.
  The second time there will be an undefined variable
  \verb@\alliswellthatendswell@.  This is intentional, just check that
  the {\LaTeX} identifies itself as {\lq\lq}LaTeX2e{\rq\rq} and enter
  {\lq\lq}x{\rq\rq}. If execution ends
  in the message {\lq\lq}Test seems fine.{\rq\rq}, and it ran 2e,
  proceed to the next item.  Otherwise, change script
  {\verb@latexl2h@} (not test) until it works as described.  Do not
  move {\verb@test2.tex@}.  See the Windows install section for more if
  needed.
  
  If {\LaTeX} 2e is {\em not} run using the command {\verb@latex@} on
  your system, on a piece of paper, write down the command that does
  run it.

\item Now you need to find how to run dvips on your
  system.  In tcsh:
\begin{verbatim}
dvips -Ppdf -E index > tmp.ps
\end{verbatim}
  You may need to specify an other command than {\verb@dvips@}.
  In that case, write it down on a piece of paper.
  If dvips answers but complains about the -E (eps files) option, you
  want to consider upgrading to version 5.8.3.  To see the current version
  number, use
\begin{verbatim}
dvips -v
\end{verbatim}
  If dvips does not know the pdf printer, your formulae are not going
  to be as sharp as they could be.  Consider installing just the dvips
  part of \texlive.  Yes, I know.  Otherwise leave out
  {\lq\lq}-Ppdf{\rq\rq}.

\item You need to find out how to run the {\TeX} executable on your system.
  In tcsh, try
\begin{verbatim}
tex index
\end{verbatim}
  If {\TeX} answers, and complains about the {\LaTeX}, all is OK; just
  enter {\verb@x@} to exit.  Otherwise, just write down the same
  executable as used for {\LaTeX} for both {\TeX} and ini{\TeX} below
  and don't use the stupid -ldump option of \latextohtml.  It is
  {\em{not}} going to save any time anyway.

\item You need to figure out how to run ini{\TeX} on your system.
  In tcsh, try
\begin{verbatim}
initex index
\end{verbatim}
  Write it down if not {\verb@initex@}.

\item You {\em do} need to find the way to run ghostscript
  on your system.  In tcsh, try
\begin{verbatim}
gs -version
\end{verbatim}
  If ghostscript answers, the way to run ghostscript is
  {\lq\lq}gs{\rq\rq}.  We have version 8.00.  Otherwise, write it down.
  
\item You need to find out how to run perl on your system.  In tcsh,
  try:
\begin{verbatim}
perl -v
\end{verbatim}
  If perl answers, the command to run perl is {\verb@perl@}.
  Otherwise write the correct command down.  We have version 5.6.1.
  Also check that it is a good perl, not the junky one that comes with
  some version of TeX:
\begin{verbatim}
where perl
which perl
\end{verbatim}
  {\verb@which perl@} should normally return {\verb@/usr/bin/perl@},
  not some TeX version of perl.  If necessary, reorder your PATH to
  move {\verb@/usr/bin@} in front of TeX directories.

\item In tcsh, do
\begin{verbatim}
cd ../doc
make
\end{verbatim}
  This compiles the fortran using g77.  There will be some warnings
  about possible uninitialized variables, but they are in fact
  correctly initialized.  Note that I have set the l2hcrop variable
  {\verb@bufdim@} in {\verb@l2hcrop.f@} to use 2 Mb of memory.  The
  intention is to avoid running the Netpbm utilities pnmcrop and pnmflip
  as much as possible, minimizing potential wrong-version problems.
  However, if this amount of memory use is a problem on your system,
  you can reduce the value by up to a factor 10 or so, and pnmcrop
  and pnmflip will take over for the bigger images.

\item In tcsh, do
\begin{verbatim}
cd subbin
make
cd ../dojpegs
make
cd ../../wzs
make
\end{verbatim}
  This creates other needed programs.

\item In tcsh, do
\begin{verbatim}
cd ../../l2hins
\end{verbatim}
Read the license and other important documents.

\item \label{reinstux} In tcsh, do
\begin{verbatim}
more INSTALL  (ignore whatever it says in this file, anyway)
emacs prefs.pm
\end{verbatim}
  You want to make the minimum changes you can; {\em after} everything
  works correctly, you can always go back and play around.

  Do not touch the {\$\verb@prefs{'TEXLIVE'} = 'no';@} line even if you
  have \texlive.
  
  Find the TEX line, starting with {\$\verb@prefs{'TEX'}@} and change
  {\verb@tex@} into the way to run the {\TeX} executable on your
  system you found earlier, if it was different from {\verb@tex@}.
  
  Change the INITEX line a few lines below correspondingly.  (If
  you need to append an option to the command, {\em do not} do
  that here.  Instead edit file {\verb@l2hconf.pin@} and add the
  option behind {\verb.@INITEX@.} a few lines down in that
  file.  Return to file \verb@prefs.pm@.)  File \verb@prefs.pm@
  cannot deal with multi-word commands.
  
  Set the value of TEXPATH into the folder where you want the
  {\verb@\usepackage@} packages that come with {\latextohtml} to be
  put.  This can be any of the TEXINPUTS directories except the . or
  .. ones.  In the same place as {\lq\lq}article.cls{\rq\rq}, the
  article-style class file, would be a pretty sure bet.  In teTeX, you
  may want to leave it blank and configure might figure it out by
  itself.  When in doubt, leave it {\$\verb@ENV{L2HTOP}@} and move
  the files from there to an appropriate directory in the search path
  after running the {\verb@install@} procedure.  I leave them in
  {\$\verb@ENV{L2HTOP}@}
  since I have no prileges to move files into system directories
  and set my TEXINPUTS to {:\$\verb@L2HTOP@} so that {\TeX}
  can find them.  Note that this means that the TEXINPUTS line in
  my {\verb@latexl2h@} file, as edited above, is really
\begin{verbatim}
setenv TEXINPUTS :..:.:$L2HTOP
\end{verbatim}

  Change the value of DVIPS to what you found.

  If you found that the pdf printer did not work, remove {\verb@ -Ppdf@}
  from the DVIPSOPT pref.  In that case you may eventually want to
  experiment with the next three options to try to improve the quality
  of math images.

  If your dvips did not do eps, set EPS to 0 instead of 1.
  
  Change the GS ghostscript option if different.  Change all three,
  just to be safe.
  
  Set TMPSPACE further down to the location where you want temporary
  files to be put.  These can be big.

  Save \verb@prefs.pm@.

\item In tcsh,
\begin{verbatim}
chmod a+x configure
./configure -help | more   (ignore whatever it says, anyway.)
rm config.log cfgcache.pm
./configure
\end{verbatim}
  If this terminates in an error message, try to solve it by making
  appropriate changes in file {\lq\lq}prefs.pm{\rq\rq}.  Repeat
  from \verb@rm config.log cfgcache.pm@.

  If your ghostscript is recent and it complains about {\verb@GS_LIB@},
  it may be ignorable.  Try {\verb@gs -h@} and see whether {\verb@gs@}
  can find the ppm device.
  
  If it gives an uninitialized string error combined with the note
  that it cannot do pict format, I ignore it since I do not use
  pict graphics.

  If you get to the stage where it creates {\lq\lq}cfgcache.pm{\rq\rq}
  to {\lq\lq}Makefile{\rq\rq}, carefully examine the log file
  {\lq\lq}config.log{\rq\rq}.  If you get {\lq\lq}no{\rq\rq}s,
  investigate before proceeding to the next item.

  Also examine {\lq\lq}cfgcache.pm{\rq\rq}.

\item In tcsh,
\begin{verbatim}
make
make check
\end{verbatim}

\item You are now ready to test for basic operation.  In the xterm window,
  enter:
\begin{verbatim}
make test
\end{verbatim}
  If it freezes at some stage, have a look at what is in the
  {\$\verb@L2HTOP/temp@} directory for a clue, and try hitting the
  Return key.  If it just complains about aux file l2htest, but tells
  you to view results with your browser, do so.  (You may need to
  browse down to the file, instead of using the given link.) The web
  pages should look rough, but correct.  If not, I recommend pulling a
  lot on your hair.  One thing you could do if you have used all your
  hair, is to examine whatever is in the {\$\verb@L2HTOP/temp@}
  directory.  Script {\verb@latexl2h@} that you modified earlier puts
  some error info there if errors occur.

  Carefully examine file {\verb@l2hconf.pm@} for problems.

\item If the test web pages are correct, in tcsh
\begin{verbatim}
make install
rehash
\end{verbatim}
  This will put the various {\latextohtml} files in the {\verb@l2h@}
  directory, and the style files in the {\TeX} path.

\item Get rid of the junk.  In tcsh
\begin{verbatim}
cd $L2HTOP
rm -r texinputs
\end{verbatim}
  
\item Move the various .sty files into the right locations in the
  {\TeX} search path, if it was not specified in prefs.pm.  Try
  running {\LaTeX} on a document with a {\verb@\usepackage{html}@} in
  the preamble; it should be able to find that package.  Otherwise try
  moving it in with the {\verb@article.cls@} file of LaTeX.  Or, for
  teTeX, you could leave them in {\$\verb@L2HTOP@} and tell the users
  in their .login or .[t]cshrc to set
\begin{verbatim}
setenv TEXINPUTS :$L2HTOP
\end{verbatim}
  In that case. you want to set
\begin{verbatim}
setenv TEXINPUTS :..:.:$L2HTOP
\end{verbatim}
  in file {\verb@l2hsup/latexl2h@}.  That is what I do, since I have
  no privileges to move things into the {\TeX} directory tree.  A good
  test file is {\$\verb@L2HTOP/l2hsup/check/index.tex@}.  If that file
  processes OK in {\LaTeX}, try converting it to html using the
  {\verb@l2h@} command.  If it does not process correctly in {\LaTeX},
  it is a problem in {\LaTeX}, not {\latextohtml}.  You may need to
  install packages or run {\verb@mktexlsr@}.

\item (If your dvips does not do eps, you can skip this item.)  You
  want to create an option to deal with the
  occasional buggy figure, such as some figures using \verb@\special@.
  Execute the command:
\begin{verbatim}
$L2HTOP/l2hsup/var/creaneps
\end{verbatim}
  
\item In a multiuser setup, remove directory {\verb@temp@} from
  {\$\verb@L2HTOP@}, and tell each user to create a directory
  {\verb@temp@} (case sensitive) in their HOME directory.  Also
  tell them to setenv L2HTOP and to prefix it to their PATH, and if
  necessary, to setenv TEXINPUTS.  Tell them the location of this
  document.

\item Unfortunately, the installation must be repeated from the
  {\verb@./configure@} stage if the physical location of
  {\$\verb@L2HTOP@} changes.  This is due to the fact that
  noninterpolated strings are used deep inside the numerous perl
  scripts.  If you leave l2hins as is, this will be easier.

\item You may want to delete the {\verb@.zip@} files from l2hsup/unzip
  and the jpeg and netpbm installation trees when all is well to
  recover disk space.
  
\end{enumerate}

If you have information that may be helpful to others for installing,
e-mail me, section \ref{sec:support}, including your flavor and
version of {\TeX} and I will add it to this document.

If there are errors in the installation procedure, please let me know;
I will correct them immediately.

\subsubsection{Warnings for Unix users}

Unix users should note the following differences in usage from Windows
ones:

\begin{itemize}
  
\item Before running {\verb@l2h@} for the first time, set the
  location of the {\latextohtml}-FU files and add the executables to
  your path with:
\begin{verbatim}
setenv L2HTOP $HOME/l2h
setenv PATH "$L2HTOP/l2hsup:$PATH"
rehash
\end{verbatim}
  (or substitute wherever the top of the directory tree is if not
  {\verb@l2h@} in the home directory.)  You probably want to put
  the first two commands in your {\verb@.login@} file, so that you do not
  have to do them manually each time you login to csh.  Make sure
  that {\verb@L2HTOP/l2hsup@} is {\em before} other parts of the path
  that may have netpbm files of the wrong version number.
  
\item For a multiuser setup, each individual user must have a
  directory called {\lq\lq}temp{\rq\rq} in the home directory for the
  log file to be put (and {\$\verb@L2HTOP@} should {\em not} have a a
  {\verb@temp@} directory.)
  
\item Substitute {\$\verb@L2HTOP/@} where Windows users have
  {\verb@C:\@} and forward slashes for backward ones.  But since you
  already have {\verb@L2HTOP/l2hsup@} in your path, you typically can
  omit this from commands.

\item You want to use {\verb@setenv@} instead of {\verb@set@},
  omit the equals sign, and quote the string, e.g.
\begin{verbatim}
setenv L2H_BROWSER c
\end{verbatim}

\item File {\verb@.latex2html-init@} is a hidden file on Unix.
  But it is there, just do {\verb@ls -a@}.
  
\item If {\verb@l2h@}, {\verb@makel2h@}, or the {\verb@wiz@} mess up
  your terminal (or xterm window), use the {\verb@l2hexe@},
  {\verb@makel2hexe@}, and {\verb@wizexe@} versions instead.  The exe
  versions do not try to use line editing, so will not mess with your
  terminal screen.  Correcting typos will be less convenient: no arrow
  keys.

\item L2h will make all files in the index.tex directory and below
  readable to world.

\end{itemize}

Have a look at manual.pdf and hthtml/index.html in the docs subfolder
of l2h.   Then proceed to usage section \ref{sec:usage}.



\section{Usage}
\label{sec:usage}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}



\subsection{{\LaTeX} file format}

Fairly standard format tends to work best.

Equation labels: do {\em not} put these on a line by themselves.  Put
them right behind the end of the actual equation and follow them by a
\% to avoid a blank line being inserted in the equation, causing the
conversion of the equation to an image to fail.

For new versions of {\LaTeX}, (or rather {\verb@hyperref@}), follow
{\verb@htmlimage@} commands by an empty pair of braces, like in
\begin{verbatim}
\htmlimage{extrascale=3}{}
\end{verbatim}

{\TeX} {\verb@\def@}s: assuming that {\latextohtml} does not process them,
put a second copy of the {\verb@\def@} inside an imagesonly environment.
(Requires the html package to be loaded.)

Captions: If you use an optional argument, make sure there is {\em no
linebreak between the ] and the \{.}  Or the caption will become part
of the image, probably with an incorrect figure number.  Try to keep
math out, and try to avoid captions with the same text save for the
math.  If the caption involves (even implicitly) {\verb@\html@} or
{\verb@\latexhtml@} commands, the correct figure number may not be
found.

Quotes: type left and right quotes as {\verb@{\lq}@} and
{\verb@{\rq}@}, or they will look poor.

Do not use {\verb@\hsize@} or {\verb@\textwidth@} in pictures, it will
not conform to your document.  Specify actual dimensions in
{\verb@pt@} or {\verb@in@}.

Watch for two figures or formulae with long identical starting text.
{\latextohtml} may not see the difference in the later text.  If
necessary, put a strut at the start of one of the two to ensure the
difference is noted.  (That should be fixed in the new versions.)

Input commands: note subsubsection \ref{sec:pinpt}.

{\verb@\framebox@} inside a picture environment: See subsubsection
\ref{sec:pfrb}.

For other problems, see the following listings.


\subsection{Elementary usage}

Normal operation proceeds as follows: Put (a copy of) your {\LaTeX}
document in a folder (i.e directory) by itself and rename it
{\verb@index.tex@}.  Add copies of the figures or whatever else there
may be.

In the command window obtained by double clicking the Windows\_XP or
Windows\_98-ME icon in the {\verb@l2hsup@} folder, (or in an xterm
window on Unix), {\verb@cd@} to the folder with your document. (In
Windows XP, you can get some help on the {\verb@cd@} command using
{\verb@help cd@} or {\verb@cd /?@}, on Unix, that is {\verb@man cd@}.)

{\verb@latex@} {\verb@index@} until there are no longer errors.  If
you want to provide an {\verb@index.pdf@} pdf version of the document,
to allow easy, high quality printing of the entire document, create
that now.  (If you do not know how to create one using your version of
TeX, try {\verb@makepdf@}.)

Then create the web pages using {\verb@l2h@}.  Load {\verb@index.html@}
in your browser to check the results.

Have a look at manual.pdf and hthtml/index.html in the docs subfolder
of l2h to see what is there.

Occasionally, clean out the folder Temp.

\subsection{The {\lq\lq}makel2h{\rq\rq} alternative}

{\verb@Makel2h@} is an alternative to the {\verb@l2h@} command that
puts the web pages in a subfolder.  This can be useful if you want to
keep the folder with {\verb@index.tex@} clean.  Also, it allows
you to make different web pages for different browsers.

That is important if you are picky about the best possible alignment
of the math images with descenders: different browsers are {\em not}
compatible in such alignment.  Internet Explorer is not compatible
with any of the Mosaic/ Netscape/ Mozilla/ Firefox line, early Firefox
is not compatible with later Firefox, etcetera.  To create different
pages for different browsers, you must use the {\verb@makel2h@}
command {\em instead of} {\verb@l2h@}.  Do not mix and match the two.
A typical processing sequence would be
\begin{verbatim}
latex index
latex index
set L2H_BROWSER=c
makel2h
set L2H_BROWSER=x
makel2h
set L2H_BROWSER=f
makel2h
\end{verbatim}
This will produce superbly aligned math for Firefox 1.5 and later
(and any other browsers that align images correctly, according to
agreed-upon international standards, but I know no other browsers like
that.)  It should also produce, on average, slightly better math
alignment in Internet Explorer, though I do not guarantee you will see
the difference, if there is one, or that it will be an improvement.
(But in any case, the new alignment for Internet Explorer,
{\verb@makel2h@} or {\verb@l2h@}, is a vast improvement over earlier
versions of {\latextohtml}.  No longer math hovering above the line.)
There will also be web pages for browsers that think the middle of the
lower case letter {\lq\lq}x{\rq\rq} is where the two lines cross
(unlike Internet Explorer, which thinks it is 2/3 of the way up.)

Remember that with {\verb@makel2h@}, eps figures must be either in the
same directory with the index.tex file, or you must give the full path
to the eps files in index.tex, all the way from the top of the disk.

\subsection{Changing the looks with the wiz}
\label{sec:wiz}

You can now make basic changes to headers, colors, font sizes, and
much more, of the web pages using the wiz.

To do so, cd to the folder with the index.tex whose web pages you want
to customize.  You must have run {\verb@(make)l2h@} at least once up
to the actual web page generation.  Then simply enter
{\lq\lq}{\verb@wiz@}{\rq\rq}.  The wiz is menu driven, so just select
what you want to do and provide data.

Note that in the majority of cases, you will need to remake the web
pages using {\verb@(make)l2h@} after running the wiz.  And if you have
changed the web page background color and your images now have visible
ghosting, you will also need to first remove the old images using
{\lq\lq}{\verb@clrl2h images@}{\rq\rq} before running
{\verb@(make)l2h@}.

The wiz is a quick and easy way to change the appearance of your web
pages without getting involved in the details of perl, html, style
sheets, and init files.  Though the latter is of course much more
powerful.


\subsection{Using jpeg images}
\label{sec:jpegs}

The original {\latextohtml} is set up to use gif images.  (At least as
installed under FU instructions; the original also supports png
images.)  There are good reasons to use gifs for formulae and line
graphs: they allow transparency and can be compact for such images.

However, for pictures, the most popular image format on the web is
jpeg (jpg).  The reasons are that while gifs only allow 256 different
colors in the image, jpegs allow millions.  In addition, jpegs are
usually much more compact, greatly speeding web page access over phone
lines.

The disadvantage of jpegs is that they lose some information in the
original picture, (but then, so do gifs if the original image has more
than 256 colors.)  For jpegs, that can show up, for example, as faint
artifacts in light regions.  Little is ideal in this world.

{\latextohtml}-FU has an added-on capability to create jpeg figures in
addition to gifs.  To activate this jpeg generation, do the following in
the Windows\_XP (or 98-ME) window:
\begin{verbatim}
set L2H_JPGQ=80
l2h  (or makel2h)
\end{verbatim}
or in a Unix command window, do
\begin{verbatim}
setenv L2H_JPGQ 80
l2h  (or makel2h)
\end{verbatim}
This will create jpeg duplicates of all gifs it makes with quality 80.
(Use 75 for smaller jpegs, or 85 for less ghosting.  Don't go over 90.
Don\rq t use percent.)  You will be asked whether you want to use the gif
or jpeg version of each image; look at them in a viewer (your browser
would do), and decide which one is best.

Jpegs are only made of images with more than 256 colors, or that have
an {\verb@\htmlimage{extrascale=...}{}@} within their figure
environment.  Also, if you want to have jpeg versions made of already
existing images, you will need to delete the corresponding gifs first
to force them to be remade.

Note that the {\verb@ppmtojpeg@} executable must be in
your path and with {\verb@ppmtogif@}.  This is true for the described
installations.

To turn of jpeg generation, in Windows do:
\begin{verbatim}
set L2H_JPGQ=
\end{verbatim}
and in Unix:
\begin{verbatim}
unsetenv L2H_JPGQ
\end{verbatim}
Note that existing jpegs will still continue to be used; simply delete
them if you want to get rid of them and rerun (make)l2h.



\section{Problem Shooting}
\label{sec:problem}


\subsection{What is LaTeX?}
\label{sec:prltx}

{\LaTeX} is a high-quality document preparation system that is particularly
powerful if you have a lot of math or cross-links in your document.
{\latextohtml} is an add-on program to convert these documents into web
pages instead of printed hard copies.

Of course, before you can use {\latextohtml}, you need to know how to
create documents in {\LaTeX} format.  There are books like that of
Leslie Lamport (see the bibliography of the original
\htlink{online manual}{http://www.eng.fsu.edu/~dommelen/l2hmang}).
A powerful free resource is the web page of the
\htlink{TeX Users Group}{http://www.tug.org}.
In my opinion, the current dominant free implementation of {\LaTeX} for Windows
is \htlink{MiKTeX}{http://www.miktex.org}.  It has a useful manual, and there
is an easy install script to add {\latextohtml}-FU to it.

But let me give a {\em really really} basic intro first if you are really
clueless about it all.
On MS Windows, download and install the emTeX/{\latextohtml}-FU bundle using
the easy install script;
on Unix, install TeXLive from the TeX Users Group and add {\latextohtml}-FU
according to instructions.  Also add the ghostview and perl programs.
Create a folder for your first document; avoid spaces
and points in the folder name, they are just trouble.  On Windows, you
might create a new folder {\verb@myfirsttry@} in the top {\verb@C:@} disk.
Open Windows Notepad, or your favorite Unix editor (pico, nedit, ...).
In it, type in the following text, case-sensitive, avoid typos, wrong brackets:

\begin{verbatim}
\documentclass{article}
\begin{document}
Hello world.
\end{document}
\end{verbatim}

Now save this to the folder {\verb@myfirsttry@} that you created, naming
the saved file {\verb@index.tex@}.  Windows users beware!  You have to
specify the name between double quotes as {\verb@"index.tex"@}, or
Notepad will save it as {\verb@index.tex.txt@} instead.  It\rq s Microsoft.

Now on Windows double-click the Windows\_XP (or 98-ME icon for older
Windows) in the {\lq\lq}l2hsup{\rq\rq} folder in the top {\verb@C:@}
drive, or on Unix open an xterm or telnet command window.  In the
created window, cd to the folder with the index.tex file you just
created (for example, in Windows use {\verb@cd \myfirsttry@}).  Enter
the following commands:

\begin{verbatim}
latex index
makepdf
\end{verbatim}

Then examine the created
pdf file {\verb@index.pdf@} in the folder {\verb@myfirstry@};
It should show the text {\lq\lq}Hello World{\rq\rq}, as shown
\htlink{here}{../basic1/index.pdf}.

To make web pages instead of a pdf file, use:
\begin{verbatim}
latex index
l2h
\end{verbatim}
and examine the created web page {\verb@index.html@}.
It should look like
\htlink{this}{../basic1/index.html}.

Like HTML, {\LaTeX} is a {\lq\lq}mark-up language{\rq\rq}, which means
that you type in formatting information instead of pick it from menus.
For example, a more realistic document would look like:

\begin{verbatim}
\documentclass{article}

\begin{document}

\title{My Second Document}
\author{J. Doe}
\maketitle

\section{Quadratic equations}
\label{sec:quad}

The general quadratic equation
\begin{equation}
  a x^2 + b x + c = 0  \label{eq:quad}
\end{equation}
has two solutions given by
\begin{equation}
  x_{1,2} = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}  \label{eq:quadsol}
\end{equation}

\section{Numerical solution}
\label{sec:numsol}

In section \ref{sec:quad}, we gave the solution of the quadratic
equation.  This solution can be put in a computer program as is, but
is then likely to suffer from round-off error problems.

The better way to do it is to find only one solution, call it $x_1$,
from the given formulae (\ref{eq:quadsol}), selecting $x_1$ as {\em
  the solution for which the two term in the top of the ratio have the
  same sign.}  Then compute the other solution from
\begin{equation}
  x_2 = \frac{c}{a x_1}  \label{eq:altsol}
\end{equation}

\end{document}
\end{verbatim}

Note that fractions and square root signs are obtained by typing them
in.  If you do a lot of math, you will find that this is actually much
quicker and more reliable than picking items from menus.  Also note
that I use mnemonics instead of actual section and equation numbers.
That avoids having to do do extensive renumberings in large documents
if you insert a new section or equation number somewhere, and it cuts
down tremendously on incorrect numbers.  {\latextohtml} likes the
equation labels to be following the math.  There seems to be a lot
of other typing involved, but a {\LaTeX}-aware editor like Emacs
will put it in for you.

Process as:
\begin{verbatim}
latex index
latex index
makepdf
l2h
\end{verbatim}
The pdf file so produced is
\htlink{here}{../basic2/index.pdf}
and the web pages are
\htlink{here}{../basic2/index.html}.

See the sources mentioned above to get more in depth info.
The FAQ on tug.org is especially useful.

\subsection{General}
\label{prgeneral}

If you get into trouble processing documents with {latextohtml}-FU,
the first thing you have to make sure of is that your index.tex file
processes correctly under latex (and dvips).  If not, everything stops
right there.

Browsers are buggy too.  Try hitting {\lq\lq}reload{\rq\rq} or
{\lq\lq}refresh{\rq\rq}.

If the document is correct, the next thing to ask is whether it is
fairly standard \LaTeX.  {\latextohtml} has extensive translation
capability, but there are very definite limits.  If necessary, create
a very standard form index.tex to convert into web pages.

If you made {\em elective} changes from my installation procedure,
however seemingly minor, repeat installation and don't.

Check the log file {\verb@C:\Temp\l2h.log@} (in the Temp directory of
the C: disk) for clues.  (For Unix users, the log file is in either
{\$\verb@L2HTOP/temp@} or {\$\verb@HOME/temp@}.)

If you specify {\lq\lq} -debug{\rq\rq} behind {\lq\lq}l2h{\rq\rq},
you will get much more error information on the screen and in
{\verb@C:\Temp\l2h.log@}.  It will also leave the ghostscript files in
a subdirectory of {\lq\lq}Temp{\rq\rq}, and their conversions.  You
can look at the .ps files using Ghostview, and at the pnm files using
an image viewer like CompuPic.  Alternatively, you can convert them to
.bmp using the Netpbm utilities you installed and look at them with
Paint.

To slow down the screen a bit, in the DOS window use:
\begin{verbatim}
set L2H_SLEEP=1
\end{verbatim}
(or 2) before running l2h.  Do {\em not} try output redirection.

If there were problems processing images.tex, see section
\ref{prfiggen} for more.

If you are familiar with Perl, try setting -d option behind perl.exe
and \$PERL in latex2html.bat and stepping with n, s, and r.

Unix users should make sure that the L2HTOP name is set and that
its l2hsup directory is in their PATH.  If not, use
\begin{verbatim}
setenv L2HTOP "$HOME/l2h" (or where the LaTeX2HTML files have been installed)
setenv PATH "$L2HTOP/l2hsup:$PATH"
rehash
\end{verbatim}
Make sure that {\verb@L2HTOP/l2hsup@} is {\em before} other parts of the path
that may have netpbm files of the wrong version number, or strange things
may happen.

If that does not solve it, the next subsections are some solutions to
various potential problems that I am aware of, sorted by type.

The \htlink{official online manual}
{http://www-texdev.ics.mq.edu.au/l2h/docs/manual/}
also has a list of known problems and solutions in Chapter 6
that you also want to read through.

You can also have a look at the sample documents in
section \ref{sec:examples} for examples.

Good luck.

\subsection{Problems not covered here}

The \htlink{official online manual}
{http://www-texdev.ics.mq.edu.au/l2h/docs/manual/}
also has a list of known problems and solutions in Chapter 6
that you should read through.

The manual list some sources of support for the official version of
{\latextohtml}.  I do not know how active they are.  There is a
\htlink{\TeX usergroup}{http://www.tug.org}, which includes a
very useful FAQ and much software.

E-mail me problems, section \ref{sec:support}, and I will add them to
the list.  If they are due to my stuff, or if they are important
enough to me, I will fix them or devise a work-around.


\subsection{Installation}
\label{prinst}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

All I know is in the respective installation section.  When people
send me corrections or additions, I add it there.  Or weird stuff
maybe here.


\subsection{Uninstall}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

See item \ref{lattest} of the installation instructions.


\subsection{Weird problems}
\label{prweird}

There are some potential problems that cause symptoms that are just
weird.  If you are baffled, try each of them and see whether it solves
the problem.  None of them can hurt:

\begin{enumerate}
  
\item You may be short on disk space.  Unfortunately, {\latextohtml}
  uses big temporary files, so you should have a fair amount of free
  space on your C: disk.  Right-click the C: disk in {\lq\lq}My
  Computer{\rq\rq} and select {\lq\lq}Properties{\rq\rq} to see
  available disk space.  While you are at it, check folder
  {\lq\lq}Temp{\rq\rq} and make sure there is no garbage from previous
  runs left.

\item DOS has a limited environment space.  If you see any message
  {\lq\lq}No environment space!{\rq\rq} flashing by, you are
  in trouble.  In the DOS window, enter the following:
\begin{verbatim}
command /e:3072
\end{verbatim}
  Now try again.  This will give you 3072 bytes of environment space,
  for this DOS window only.  (This goes at the expense of other DOS
  memory. You also lose additional memory from now having two copies
  of command.com running, so if you have to do this frequently,
  consider increasing the corresponding value in file CONFIG.SYS.)

\item Windows loses file handles, causing it to corrupt itself over
  time.  Especially if you get pop-up boxes that
  {\lq\lq}l2hcrop.exe{\rq\rq} has performed an illegal operation, do
  {\em not} contact the vendor.  It is reboot time.  Spend the time it
  takes to reboot by calling Bill Gates, preferably at 2 am Pacific,
  demanding a refund for Windows.
  
\item Unix users should make sure that the L2HTOP name is set and that
  its l2hsup directory is in their PATH.  If not, use
\begin{verbatim}
setenv L2HTOP "$HOME/l2h" (or where the LaTeX2HTML files have been installed)
setenv PATH "$L2HTOP/l2hsup:$PATH"
rehash
\end{verbatim}
  Make sure that {\verb@L2HTOP/l2hsup@} is {\em before} other parts of
  the path that may have netpbm files of the wrong version number, or
  strange things may happen.

\end{enumerate}

Browsers are buggy too.  Try hitting {\lq\lq}reload{\rq\rq} or
{\lq\lq}refresh{\rq\rq}.

For your comparison, I have full copies of my own Windows 98
\htlink{CONFIG.SYS}{../notes/config.txt} and
\htlink{AUTOEXEC.SYS}{../notes/autoexec.txt} files.  Do not use
such files on Windows XP.

The \htlink{official online manual}
{http://www-texdev.ics.mq.edu.au/l2h/docs/manual/}
includes some other potential problems.


\subsection{Freezing}
\label{prfreeze}

If the screen freezes, and there are notices on the screen that .tex
and .log files are being moved to the Temp folder, a problem occurred
in latexl2h.bat.  Examine the log files moved into the Temp folder for
the problem.  Also have a look at rb.err. Then hit Return.  L2h
should continue.

If the DOS window freezes solidly, see section \ref{prweird} on weird
problems.



\subsection{Abnormal termination}

See section \ref{prgeneral} on how to use the debug option and
the log file.

See section \ref{prweird} for random DOS problems.

Review the Installation section for potential installation problems.



\subsection{L2hcrop performs illegal operations}

No, it does not.  Reboot time.

If it still occurs, make sure the FILES value in CONFIG.SYS is big
enough.  L2hcrop opens three files.



\subsection{I do not want to use l2h/makel2h}
\label{prnoml}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.}

{\latextohtml} works normally, (or rather, as it should.)  Run as
\verb@C:\l2h\bin\latex2html@ or \\ \$\verb@L2HTOP/bin/latex2html@, using
options as in the manual in the \verb@C:\l2hsup\l2hdocs@ folder.

The orginal {\verb@.latex2html-init@} file that comes with the
unmodified {\latextohtml} can be found in the {\verb@l2h@}
directory under name {\verb@dot.latex2html-init@}.  Copy the file to
the directory with your {\verb@index.tex@} file and rename it to
{\verb@.latex2html-init@}; in other words, {\em remove} {\verb@dot@}.
(This will make the file invisible on Unix.)   {\latextohtml} has its
own style sheet {\verb@index.css@} hard-coded.

However, do make sure that {\verb@html4_0.pl@} is loaded.  Various
fixes have only been impemented for that version (and {\em not} for
the default {\verb@html3_2.pl@}.


\subsection{Missing/crashing packages/style files}
\label{sec:prsty}

The critical {\verb@html@} package (file
\htlink{html.sty}{../notes/html.sty}) should have been installed with
your installation.  If not, try putting a copy of it in with your
document.

You need to have the \htlink{epsf.sty}{../notes/epsf.sty} and
{\verb@hyperref@} packages installed in your version of {\TeX}.  If
you do not yet have them, \htlink{TUG} {http://www.tug.org/} has them
in downloads/CTAN.

However, as of 2005 or so, hyperref is no longer backward compatible
with the htmlimage command as described in the {\latextohtml} manual.
The solution is to follow every htmlimage command with an empty pair
of braces, {\verb@{}@}.

However, as of 2006 or so, hyperref is no longer backward comptable
with html.sty.  The solution is to load {\verb@hyperref@} before
{\verb@html.sty@}:
\begin{verbatim}
\usepackage[draft]{hyperref}
\usepackage{html}
\end{verbatim}

However, as of 2007 or so, hyperref needs package {\verb@kvoptions@},
and TeXlive 2007 does not seem to include {\verb@kvoptions@}.  You can
find the {\verb@kvoptions@} on \htlink{TUG}{http://www.tug.org/} in
downloads/CTAN.  (Or you can just put
\htlink{kvoptions.sty}{../notes/kvoptions.sty} in with your file.)

However, as of 2008 or so, ...


\subsection{Figure/table/sectional numbers are wrong}
\label{prnumbers}

The procedure that {\latextohtml} uses to determine the correct
section, figure, and table numbers can fail.  The results are
unsightly, with missing or wrong numbers.  I reduced its likelyhood
of this occurring very much, but nothing is perfect.

In particular, if you put HTML-only sort of stuff in a figure or table
caption or in a sectional title, (like a latexhtml, htmlcode or
htmlonly command), it will prevent its number to be found.  Latex2html
will then guess at the number.  To fix this, provide the optional
shorter caption or title, and leave out the html stuff from it.  (Do
not forget that there may no line break between ] and \{.)
  
I believe the above is nowadays enough to fix the problem.  But a few
older suggestions might still be useful.

Avoid discretionary hyphens in captions and section names.  Embedded
math or accents may also cause problems; try to rewrite it without.

Remove duplicate caption or section titles that give problems. For
example, if you have two sections called {\lq\lq}Introduction{\rq\rq},
rename one {\lq\lq}Introduction to ...{\rq\rq}

Examine the log file {\verb@C:\Temp\l2h.log@}; it often shows why
{\latextohtml} did not find the latex caption matching the html one.
Try rephrasing the part that does not match.

Or, if you are not afraid of a bit of Perl, edit file
{\verb@C:\l2h\bin\latex2html.bat@}, and find the string
{\lq\lq}leon: use brute force now{\rq\rq}.  The last-resort number
search is below it.  For example, the statement
{\$\verb@cap_key_s =~ s/\\'/&#233;/g;@} makes the latex
{\verb@\'@} match the html e-acute symbol.


\subsection{Shortened section titles are wrong.}

See the next item.


\subsection{Do not put a linebreak between ] and \{}

This will produce erroneous processing if done for the shorter version
of a caption or title or similar.  Break inside the brackets instead.



\subsection{\textbackslash [re]newcommand or \textbackslash def does not work}
\label{sec:prdefs}

If definitions do not work in image environments or similar, they may
be missing in images.tex. Try putting a copy of the definition in
an {\lq\lq}imagesonly{\rq\rq} environment.


\subsection{No \textbackslash input in \textbackslash [re]newcommand or \textbackslash def}
\label{sec:prindef}

Do not put a {\verb@\input@} or {\verb@\include@} command inside a
{\verb@\[re]newcommand@} or {\verb@\def@}.  It does not work properly.
(Yes, this is a bit of a pain.  But it is probably unavoidable.)

\subsection{Erroneous space behind one-character commands}

Yes.  For example, if you try to redefine a command like \\-, there
will be an erroneous space produced.  This author does not know how to
fix this.  However, \\0 through \\9 work correctly.  So if you need a
one-character, and/or nonalphabetic command, use these.


\subsection{Erroneous space at rawhtml}
\label{sec:prespvb}

The manual says that you need the linefeed behind the
{\verb@\begin{rawhtml}@} or before the {\verb@\end{rawhtml}@}.  But
that is not always needed.

See also subsection \ref{sec:presbim}.


\subsection{HTMLcode refuses a html tag}
\label{sec:prhtmlc}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, look at
  settings.pl, not .latex2html-init.}

{\verb@\HTMLcode@} only accepts tags from the corresponding official
HTML version.  For example, a NOBR tag, which prevents line breaking,
is not official, so refused.  To fix this, go into the
{\verb@versions@} subdirectory of the top {\latextohtml} directory.
Edit file {\verb@html4_0.pl@} or whatever is the version of html that
you have set in your {\verb@.latex2html-init@} file.  Add the tag to
either {\verb@closed_tags_list@} or {\verb@unclosed_tags_list@},
depending whether there is a closing tag.  For example, NOBR has a
closing tag /NOBR.

Instead you could try to use the {\verb@rawhtml@} environment.
Unfortunately that adds unwanted space before and after the tags.

\subsection{Figures, tables, and formulae}
\label{prfigs}


\subsubsection{General}
\label{prfiggen}

Problems with images (figures and mathematical formulae) are varied.
Images are made through the following steps:
\begin{itemize}

\item A file images.tex is created with the {\TeX} code
  for the figures extracted from index.tex.
  
\item This file is run through batch file latexl2h.bat you created.
  (If errors occurred, you should still find images.log in the Temp
  folder.  If not, you did not create latexl2h.bat correctly.  But if
  you did the test fairly, I do not know why not.)

\item The images.dvi file is run through dvips to create the
  postscript versions of the images.
  
\item Inside the subprogram pstoimg.bat of latex2html, the postscript
  versions are run through ghostscript to produce .ppm versions.
  
\item The .ppm version is run through program l2hcrop.exe to crop away
  undesirable parts.  (L2hcrop leaves a .log file for each image if
  the debug option is used.)  If the image is very large, l2hcrop.exe
  may run out of memory, and its task will be done by programs
  pnmcrop.exe and pnmflip.exe instead.  The log file will note that.
  (If l2hcrop returned an exit status 2560, it may be that the image
  given to it was completely empty, so it cropped everything.)

\item If there are too many colors for a .gif file, batch file
  ppmquant.bat is run to reduce them.  It runs pnmcolormap.exe
  and pnmremap.exe in sequence.

\item The final .ppm files are converted into .gif files
  by program ppmtogif.exe.
  
\item Latex2html includes references to these gifs in the web pages it
  makes.

\end{itemize}

Obviously, any of the above steps can cause problems.  Your best bet
is then to specify the debug option and examine the log file and
images as in section \ref{prgeneral}.

If there were problems processing images.tex, you can create a
temporary subfolder {\lq\lq}tmp{\rq\rq} in the same folder as
index.tex, move images.tex to that subfolder, and then process it
from the DOS window like:
\begin{verbatim}
C:
cd \My Documents\mydoc\tmp
C:\l2hsup\latexl2h images
\end{verbatim}
This should give you a better view of {\LaTeX} error messages and
problems.

Unix users should make sure that {\verb@L2HTOP/l2hsup@} is in their
PATH {\em before} other parts that may have netpbm files of the wrong
version number, or strange things may happen.  Their log file is
in either {\$\verb@L2HTOP/temp@} or {\$\verb@HOME/temp@}.

Note that some web graphics used through the graphics or graphicx
packages might conceivably not be converted correctly since ppmquant
no longer exists.  Solution if this would actually happen: convert the
figures to eps, or edit \verb@l2h/styles/graphics-support.perl@ and replace
ppmquant by an equivalent current utility.


\subsubsection{Images.tex has no header.}

See the next item.

\subsubsection{Make sure [re]newcommands are properly bracketed.}

If you have [re]newcommands in which the command name is not within
curly brackets, latex may eat it, but images.tex may not have
a documentclass line.  Of course, everything stops there.


\subsubsection{Do not put labels on empty lines}

Do not put labels of equations on otherwise empty lines.  It will
cause {\LaTeX} to shout a lot when it processes \verb@images.tex@.
The reason is that {\latextohtml} removes the label, leaving a blank line in
the formula.

It is recommended that you put the label immediately following the math
and hide the end-of-line by following it with a percent sign.
If not, you will get errors in images.log.


\subsubsection{Shortened figure captions are wrong.}

See the next item.

\subsubsection{Do not put a linebreak between ] and \{.}

This will produce erroneous processing if done for the shorter version
of a caption or title or similar.  Break inside the brackets instead.

\subsubsection{No figures or mathematics images are made at all}

This sounds like an installation problem.  Review the installation
procedure.

Review the general notes on images in subsection \ref{prfiggen}

See section \ref{prgeneral} on how to use the debug option and
the log file.

See section \ref{prweird} for random DOS problems.

\subsubsection{Randomness in image sizes}

When processing the images, {\latextohtml} uses its own page size.
So whitespace may be stretched differently.   To fix this, immediately
behind the {\verb@\begin{document}@} line, put
\begin{verbatim}
\latexhtml{}
{\setlength{\textheight}{606.5pt}\setlength{\textwidth}{405pt}
\setlength{\vsize}{606.5pt}\setlength{\hsize}{405pt}}
\end{verbatim}
Change the numbers according to your document text size.  Here 1pt
is 1/72 inch.

\subsubsection{Misaligned eps figures}

If you use emTeX, eps file names must be 8 characters or less (excluding
the .eps), or the bounding box will not be read.  Rename or add the
bounding box explicitly to the epsffile command.


\subsubsection{Problems with frameboxes in pictures}
\label{sec:pfrb}

{\latextohtml} does not know that frameboxes in pictures are different.

The following is cheating, but it works for me.  In the preamble. define:
\begin{verbatim}
\def\picfrbox(#1,#2){\framebox(#1,#2)}
\begin{imagesonly}
  \def\picfrbox(#1,#2){\framebox(#1,#2)}
\end{imagesonly}
\end{verbatim}
then use {\verb@\picfrbox@} instead of {\verb@\framebox@} in your pictures.

\subsubsection{Some figures are not being made (correctly)}
\label{sec:prfigs}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, you should edit
  settings.pl, not .latex2html-init.}

If you misspell {\lq\lq}transparent{\rq\rq} as {\lq\lq}transparant{\rq\rq}
inside {\verb@\htmlimage@}, the figure is going to fail.  Take it from me.

Do not use {\verb@\hsize@} or {\verb@\textwidth@} in pictures,
images.tex may not conform to your document.  Specify actual
dimensions in {\verb@pt@} or {\verb@in@}.

If a picture has too much empty space around it, it may cause a
problem if {\verb@\resizebox@} is used.  Try reducing the declared the
picture size to closer conform to the actual size.

Make sure {\verb@.eps@} files have proper bounding boxes.  Use
{\verb@ps2eps -l -B@}.  Don{\rq}t think commercial software puts out
correct postscript files; most do not.  If the bounding box is wrong,
the picture may only show up half or not at all.

In picture environments, a circle at the far left may show up as half
a circle, as only the center is considered as area that is written to.
To fix it up, put a tiny {\verb@\rule{.2pt}{.2pt}@} on the leftmost
perimeter point of the circle.

Plain {\TeX} {\verb@\def@} definitions in the preamble may not always be
correctly transferred to the {\verb@images.tex@} file, causing figures using
them to fail.  One fix to this bug is to add the line
\begin{verbatim}
$TEXDEFS=1;
\end{verbatim}
to your {\verb@.latex2html-init@} file.  Alternately, the
{\verb@-notex_defs@} command line option could be used with {\verb@(make)l2h@}.
(The {\verb@.latex2html-init@} file is hidden on Unix.)
More simply, add the definitions explicitly to {\verb@images.tex@} using
the {\verb@imagesonly@} environment.

Examine the images.log file and check that the figures can be found.
Note that image processing takes place in a subdirectory, so, for example
{\verb@\epsffile{myfigs/myfig.eps}@} would fail to find the
figure.  Use a complete path, or simply put the figures in with
{\verb@index.tex@} and get rid of {\verb@myfigs/@}.

If they are figures using {\verb@\special@} commands or other complex
graphics procedures, and your dvips supports the -E option, delete the bad
figures, if they were made at all, and try the following in the DOS
window:
\begin{verbatim}
set L2H_NOEPS=s
l2h  (or makel2h)
set L2H_NOEPS=
\end{verbatim}
This uses the non-eps version of latex2html, which may more robust.
(Unix users use setenv and unsetenv, with no equals signs.)  However,
I find this trick no longer works on at least some new versions of
{\TeX}; it will make things worse.  It works fine with the emTeX
version, though.  Sorry, I do not know why, the headers of the
postscript versions seem equivalent except for the dvips version
number and I am using the same gswin32c for both.  So, do not set
L2H\_NOEPS as the default!

Alternatively, and better, convert the figure into a proper eps file.
Copy index.tex to folder Temp, in the preamble set
{\verb@\pagestyle{empty}@}, and remove the caption(s) and any other
text and headers on the page(s) of the bad figure(s).  In the DOS
window:
\begin{verbatim}
c:
cd Temp
dvips -Ppdf -E -p XXX -n 1 -o index.ps index
\end{verbatim}
where XXX is the page number with a bad figure.  Load the generated
index.ps file into Ghostview, turning OFF "EPS Clip" under options.
From the {\lq\lq}File{\rq\rq} menu, select {\lq\lq}PS to EPS{\rq\rq}.
Use automatic bounding box, and save the file under name figpXXX.eps.
Open that file using Ghostview and check that it now has a proper
bounding box.  Move the file back to the original index.tex document
folder, and replace the specials garbage in index.tex there with
{\verb@\epsffile{figpXXX.eps}@} (if you use the epsf package.) Repeat
with the other bad figures.

Some additional items for the sophisticated: There are some perl
scripts in folder l2hsup that are supposed to do much the same thing
without ghostview.  If in DOS you
\begin{verbatim}
set L2H_PUTPS=1
\end{verbatim}
the postscript files generated by latex2html will be moved to the temp
folder for messing around with.  If you
\begin{verbatim}
set L2H_GETPNM=1
\end{verbatim}
pstoimg will import matching pnm files from the Temp folder, bypassing
normal conversions.


\subsubsection{LaTeX problems near htmlimage command}
\label{sec:prhtmli}

MiKTeX 2.5, and probably any other LaTeX loading the Aug 2006 hyperref
package, produces random cryptic errors in figure environments with an
htmlimage command in it, typically complaints about 'extra {\verb@}@}'
or 'Missing {\verb@\endcsname@} inserted.'  Some problems go beyond
the figure environment.

The problem appears to be incompatibility of the html package with the
new hyperref package loaded by MiKTeX 2.5.  To fix the problem, {\em before}
loading the html package, turn off hyperref using the line:
\begin{verbatim}
\usepackage[draft]{hyperref}
\end{verbatim}

If this is not possible for some reason, put an empty pair of brackets
behind the htmlimage command, for example:
\begin{verbatim}
\htmlimage{extrascale=3}{}
\end{verbatim}
It is in fact recommended that you use such an empty pair of braces
with recent versions of {\LaTeX} whether you have problems or not.


\subsubsection{Background color is shining through my figure}

Put {\verb@\htmlimage{notransparent}{}@} in the figure environment.  Do
not misspell this!

\subsubsection{Figure colors seem limited}

Gif files have only 256 different colors, unlike jpeg ones which have
16 million.  You can create jpeg versions of the figures.  Unfortunately,
jpeg files might have a bit of visible {\lq\lq}ghosting{\rq\rq}.
Little is ideal is this world.

\subsubsection{Figure file sizes are excessive}

Jpeg files are typically smaller than gif ones. Try using
them, with a {\verb@L2H_JPGQ@} of 75.

There are also utilities on the web that compress images to the maximum,
letting you see the effects while doing it.

\subsubsection{Ghosting around my formulae}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, the l2h menu
  should take care of this.  And edit settings.pl, not
  .latex2html-init.}

If you change the background color from white, this is likely to
happen.  You need to get ghostscript to use a different background
color in its anti-aliasing, by changing the pagecolor in the
preamble of index.tex or in .latex2html-init (set {\verb@WHITE_BACKGROUND@}
to 0 and the {\verb@LATEX_COLOR@} to appropriate RGB fractions.)
(The {\verb@.latex2html-init@} file is hidden on Unix.)

Delete the bad images and remake.


\subsubsection{Erroneous space before inline math}
\label{sec:presbim}

If you have inline math with inline math inside it (like in a mbox),
latex2html puts a comment in front of it that introduces an
additional space.

To fix that, go into the latex2html script.  Inside sub
{\verb@replace_verbatim_marks@}, find
\begin{verbatim}
s!$verbatim_mark(\w*[vV]erbatim\*?|tex2html_code)(\d+)#\n?!$tmp=$verbatim{$2};
$tmp.(($tmp =~/\n\s*$/s)? '':"\n")!eg;
\end{verbatim}
Get rid of the {\verb@\n@} inside the double quotes.


\subsubsection{Missing added whitespace, maybe in eqnarrays}

At the image state, there is no way for {\latextohtml} to know about
whitespace that extends beyond the area with ink on it.  Ignore it,
rewrite it not to have leading or trailing whitespace, or if it is a
real problem, put a tiny dot (ruler) in front or behind the whitespace
to extend the area with ink on it.


\subsubsection{Missing lines in formula on Firefox/Mozilla}

A browser problem.  Press refresh.

\subsubsection{Incomplete or missing lines or text in figures}
\label{sec:prest}

This is really a Ghostscript problem.  Ghostscript does not anti-alias
embedded bit maps in the postscript files it processes.  Delete the
bad gif file.  Inside the figure environment of the bad figure, put
the command {\verb@\htmlimage{extrascale=3}{}@}.  (Make sure that you are
using the html package.) Rerun l2h or makel2h.

Unfortunately, this only works for figure environments.  If you are
using displaymath to force a figure in a given place (What is this
with {\LaTeX} changing [h] into [ht]??  If a user with a brain says
[h], some stupid program with none should not second-guess that), you
will need to use figures and strategically placed {\verb@\newpage@}
commands instead.  Or use the float package and specify the figure
location as {\lq\lq}[H]{\rq\rq}.

\subsubsection{I changed the latex of a figure/formula and it is not remade}

The first step is to press {\lq\lq}Refresh{\rq\rq} or
{\lq\lq}Reload{\rq\rq} on your browser, to check that you are really
see the latest version and not a cache one.  Also, in Mozilla, use
{\lq\lq}Edit{\rq\rq} / {\lq\lq}Preferences{\rq\rq} / click on the plus
sign in front of {\lq\lq}Advanced{\rq\rq}, select
{\lq\lq}Cache{\rq\rq}, and select {\lq\lq}Every time I view the
page{\rq\rq}.

{\em The following problem no longer exists for versions of {\latextohtml}-FU
downloaded after Sep.~20, 2007.  For older version only:}
Unfortunately, {\latextohtml} is not very observant about changes in
figures and math.  Just delete the image (use
{\lq\lq}Properties{\rq\rq} or {\lq\lq}View Image{\rq\rq} in your
browser to find its name).  It will be remade according to the new
latex code next application of l2h or makel2h.


\subsubsection{Figures and/or formulae are all mixed up}

The first step is to press {\lq\lq}Refresh{\rq\rq} or
{\lq\lq}Reload{\rq\rq} on your browser, to check that you are really
see the latest version and not a cache one.  Also, in Mozilla, use
{\lq\lq}Edit{\rq\rq} / {\lq\lq}Preferences{\rq\rq} / click on the plus
sign in front of {\lq\lq}Advanced{\rq\rq}, select
{\lq\lq}Cache{\rq\rq}, and select {\lq\lq}Every time I view the
page{\rq\rq}.

Sometimes, latex2html gets all mixed up about what image goes where.
The only thing to do then is {\verb@clrl2h all@}
(keep the user-modifiable files!) and start from scratch.

{\em The following problem no longer exists for versions of {\latextohtml}-FU
downloaded after Sep.~20, 2007.  For older version only:}
Two formula or figures starting with the same long {\LaTeX} string may be
considered equal even though the {\LaTeX} is eventually different.
Put a {\verb@\strut@} at the start of one of the formulae to make
them different.


\subsubsection{Bars below or to the left of images}

Pestilential critters.

If a sidebar occurs for a figure or formulae in which you do tricky
things like lowering and raising items, or where you write outside of
bounds in a picture, putting a suitably sized
{\verb@\rule[..]{..}{0pt}@} strut at the start may help.  The idea is
to make the formatter recognize what the size of the image really is.

I had a sidebar in a big {\verb@makeimage@} that could be fixed by
moving a renew of {\verb@arraystretch@} outside, in front, of it.

Otherwise, make sure you have the latest and greatest version of the
alignment bar fixes, posted Sep 8, 2006 or later.

If so, to have me fix this, e-mail me the corresponding:
\begin{itemize}
\item {\verb@index.tex@} file, cut down to just a single example of the
  math that creates an image with an extra bar.
\item {\verb@.latex2html-init@} file (hidden on unix)
\item {\verb@index.css@} (the one in the folder with the web pages if using
  makel2h)
\item The version of {\TeX} you are using with {\latextohtml}
\end{itemize}

To try to fix it yourself, edit {\verb@C:\l2hsup\doc\l2hcrop.f@} and
try increasing the {\verb@barthb@} and {\verb@barths@} values a unit.
Recompile {\verb@l2hcrop @}with g77 according to instructions in the
file.

Make sure, in l2h.log, that GraphicsAlphaBits is not used by Ghostscript in
processing the images.


\subsubsection{Incorrect figure numbers}

See section \ref{prnumbers}


\subsubsection{A caption has become part of the image}

Do not use two captions in the same figure environment.  Use two
figure environments.  Or combine the two captions into one.

If you use an optional argument to the caption, make sure there is
{\em no linebreak between the ] and the \{.}  Or the caption will
become part of the image, probably with an incorrect figure number.
Try to keep math out, and try to avoid captions with the same text
save for the math.  If the caption involves (even implicitly)
{\verb@\html@} or {\verb@\latexhtml@} commands, the correct figure
number may not be found.


\subsubsection{Text has become part of the image}

It will.  To avoid this, put the text in a caption, and use
{\verb@\addtocounter{figure}{-1}@} in front of the figure
environment.

Or live with the text being graphics.

You may be able to play around with the makeimage command described in
the {\latextohtml} manual.


\subsubsection{Images not correctly aligned in Explorer}

This issue is obsolete.
Using the {\lq\lq}e{\rq\rq} browser,
Internet Explorer changes the vertical positioning of inline images if
there are other images in the same line.  Since that depends on the
browser width setting, there is nothing {\latextohtml} can do.

However, nowadays L2H\_BROWSER is by default {\lq\lq}a{\rq\rq}, which
has little alignment error.  Switching to {\lq\lq}x{\rq\rq} {\em may}
improve alignment even more.


\subsubsection{I do not know how to include my figure in latex}

The best way to include figures is as .eps files, typically using the
epsf package.  Unfortunately, much graphics software does not,
or not correctly, produce .eps files.  Use your netpbm files to convert
from the existing picture format to .pnm, and then to eps.

If your figure is a Windows .bmp, as produced by MS Paint, you can use
{\verb@C:\l2hsup\bmptoeps@}.  (It will tell you how to use it when called.)

If {\verb@latex@} processes the figure correctly, consider using
{\verb@dvips@} to create an eps file of it, by putting the figure by
itself on a page with an empty page style.  Use the {\verb@-p@} and
{\verb@-n@} options of {\verb@dvips@} to select the page.


\subsubsection{Problems with \textbackslash includegraphics}

The {\latextohtml} version of {\verb@\includegraphics@}
is old and has problems:
\begin{itemize}
\item It ignores the {\verb@\DefineGraphicsExtensions@} command.
\item If it finds a jpg image, it does not resize it.  This will
  produce poor quality, as browsers (at the time of writing) do not
  properly antialias images that they rescale.
\end{itemize}

You can force the {\verb@\includegraphics@} command to be processed
by {\LaTeX} instead of {\latextohtml} by including the following
text in your {\verb@settings.pl@} or {\verb@.latex2html-init@}
file:
\begin{verbatim}
&::process_commands_in_tex (<<_RAW_ARG_CMDS_);
fbox # {}
framebox # [] # [] # {}
includegraphics # [] # [] # {}
_RAW_ARG_CMDS_
\end{verbatim}


\subsubsection{How do I move figures to the side of the web page?}

Inside the figure environment, use a command like
\begin{verbatim}
\htmlimage{align=left}{}                (normal image, left aligned)
\htmlimage{thumbnail=0.5,align=right}{} (thumbnail of the image, at the right)
\end{verbatim}
Be sure to use lower case.

Put the figure at a place where there is some following text to flow
around it, not right at the end of the web page.


\subsubsection{How do I include animations and rollovers?}

Use the {\lq\lq}rawhtml{\rq\rq} environment.  \htlink{Quantum
  Mechanics for Engineers}
{http://www.eng.fsu.edu/~dommelen/research/nano/quantum/} has examples
of animations, activated by a roll-over, in the sections on wave
packets and following (search for {\lq\lq}animation{\rq\rq}).

(The animation themselves were made using a Fortran program to
generate the curve data, a plotting program to convert them into
postscript curves, the netpbm libraries to convert them into pnm,
l2hcrop.exe to crop them to the frame, l2hcomp.exe to compress them in
size, ppmquant to reduce the colors to 256, netpbm to convert them
into gifs, and {\lq\lq}gifsicle{\rq\rq} to combine them into a moving
gif.  But all that has nothing to do with {\latextohtml}.)

The navigation panels are not readily modified to include rollovers.
You would have to go into the perl, I think.


\subsection{Lists}
\label{prlists}

\subsubsection{general}
\label{prlistsgen}

If you try to customize lists such as itemize, enumerate, and list,
maybe decrease the font size of the entire list or so, you will find
it does not work.  While you are encapsulating the list in your font
size or whatever, {\latextohtml} unencapsulates the list just as
quickly.  This is obviously deliberately, though the reason is
unknown.

The only solution I have is to put in the html yourself.  To create
quoted small, bold, italic lists in the preamble define:
\begin{verbatim}
\def\listsheader{
\latexhtml{\begin{quote}\small\bf\em}{
\begin{rawhtml}
<blockquote><small class="small"><b><em>
\end{rawhtml}
}}
\def\listsfooter{
\latexhtml{\end{quote}}{
\begin{rawhtml}
</em></b></small></blockquote>
\end{rawhtml}
}}
\end{verbatim}
Feel free to leave out some of the blockquote, small, b, or em
{\verb@<...>@} tags if you like your tables less garish.   But do
not change indentation or line breaks, they must be as shown.

Then in your document, use them as:
\begin{verbatim}
\listsheader
\begin{itemize}
  \item Item a.
  \item Item b.
\end{itemize}
\listsfooter
\end{verbatim}

Also {\latextohtml} may not reset counters to zero if you define a
list and use it a second time.  The following works:
\begin{verbatim}
% questions list environment
\newenvironment{questions}[1]
{\setcounter{enumiv}{0}\listbeg\centerline{\bf #1 Review Questions}
 \begin{list}{{\bf \arabic{enumiv}}}{\usecounter{enumiv}
 \settowidth{\labelwidth}{{\bf 99}}
 \setlength{\leftmargin}{\labelwidth}\addtolength{\leftmargin}{\labelsep}}}
{\end{list}\listend}
\end{verbatim}
Note the explicitly added {\verb@\setcounter{enumiv}{0}@} before the list.

\subsubsection{Counters}
\label{prlistscnt}

If you define new counters, {\latextohtml} puts their definition twice
in the images.tex file, leading to nasty error messages.  It will not
hurt anything, but if it drives you crazy like it does me, don't define
new counters but simply use {\verb@enumiv@}.

\subsubsection{Description environments}
\label{prlistdesc}

In description environments, the index key is put in bold case just
like in {\LaTeX}, but on a line by itself.  If you do not like that,
you can enter the following HTML style information using the
{\verb@rawhtml@} environment:
\begin{verbatim}
<STYLE TYPE='text/css'>
DT {float: left; margin: 0px 0px 0px 0px}
DD {margin: 0px 0px 0px 45px}
</STYLE>
\end{verbatim}
If you put this in your {\verb@index.css@} file instead, leave out the
two {\verb@STYLE@} lines.  Do note that this will mess up your index
unless you use the {\verb@short_index@} option.  The margins are in
order top, right, bottom, left.

\subsubsection{Keys on separate lines in bibliography, index lists}

The item keys in the bibliography and index are by default put in
separate lines.  To fix, use the {\verb@short_index@} option and
redefine the style of the HTML DT element as described in the previous
subsubsection.


\subsubsection{Adding blank lines in enumerate environments}
\label{prlistenum}

To automatically add blank lines 25 px high in the HTML enumerate
environments, you can enter the following HTML style information using
the {\verb@rawhtml@} environment:
\begin{verbatim}
<STYLE TYPE='text/css'>
OL LI {margin: 0px 0px 25px 0px}
</STYLE>
\end{verbatim}
If you put this in your {\verb@index.css@} file instead, leave out the
two {\verb@STYLE@} lines.  The margins are in order top, right,
bottom, left.

It may be noted that {\latextohtml} seems to respect blank lines
between entries put in the list environment, but not the enumerate
one.  In any case, try that first.


\subsection{How do I change the navigation icons}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, use the second
  l2h menu to change the icons.  Create a theme to make the icons
  generally available.  Do not edit .latex2html-init, edit
  settings.pl.}

Use {\verb@C:\l2hsup\giftobmp next@} to turn the {\lq\lq}next{\rq\rq}
icon next.gif into bitmap next.bmp.  Load that in MS Paint and edit
away.  (If you change the icon size using attributes, you must also
edit the .latex2html-init file to put in the new size;
the {\verb@.latex2html-init@} file is hidden on Unix.)

After completion, use {\verb@C:\l2hsup\bmptogif next FFFFFF@} to
convert back, making the color white\\ (FFFFFF) transparent.

It is not a good idea to use {\lq\lq}New{\rq\rq} in MS Paint instead
of {\verb@C:\l2hsup\giftobmp@}, since Paint will mess up your colors
on saving.

To make changed icons available to all future documents, use the DOS
commands
\begin{verbatim}
c:
cd \l2hsup
xcopy iconsby myicons
\end{verbatim}
and answer {\lq\lq}D{\rq\rq} when prompted.  Now edit the icons in
subfolder {\lq\lq}myicons{\rq\rq} of folder {\lq\lq}l2hsup{\rq\rq} at
will.  They can be included in future documents by editing
.latex2html-init in subfolder {\lq\lq}files{\rq\rq} of folder
{\lq\lq}l2hsup{\rq\rq}.
(The {\verb@.latex2html-init@} file is hidden on Unix.)


\subsection{How do I add my logo?}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, you must edit
  settings.pl, not .latex2html-init.  And you can insert your image
  directly from index.tex.}

The easiest is to do it with the wiz.  Also use it to change the bar
colors to match your logo.  But if you need special customizations,
here is the manual process.

Edit file {\verb@.latex2html-init@}, (hidden on Unix), in the
{\verb@files@} subdirectory of the {\verb@l2hsup@} directory and
locate the line
\begin{verbatim}
"<TD><TABLE WIDTH=\"100\%" BORDER=0 CELLPADDING=2 CELLSPACING=0><TR>\n" .
\end{verbatim}
This line exists at two locations; the first is for the header, the second
for the footer.  Immediately behind the line, add a line
\begin{verbatim}
"<TD COLSPAN=3 ALIGN=\"aaa\"><IMG SRC=\"uuu\"></TD></TR><TR>\n" .
\end{verbatim}
substituting for {\lq\lq}aaa{\rq\rq}
the desired alignment, {\verb@left@}, {\verb@middle@}, or {\verb@right@},
and substituting for {\lq\lq}uuu{\rq\rq} the url of the image, e.g,
{\verb@mylogo.jpg@}.  Don't forget the trailing point.

To make the logo clickable, use instead
\begin{verbatim}
"<TD COLSPAN=3 ALIGN=\"aaa\"><A HREF=\"ccc\"><IMG\n" .
" SRC=\"uuu\" BORDER=0></A></TD></TR><TR>" .
\end{verbatim}
substituting for {\lq\lq}ccc{\rq\rq} the desired target url, e.g.
{\verb@http://www.mycompany.com@}.  Don't forget the trailing points.

You may need to also play around with the {\verb@TD.runner@} colors in
file {\verb@index.css@} to get it to match your logo's text and
background colors.

To make the changes retroactive for existing documents, make the same
changes to {\verb@.latex2html-init@} in the directory with the
{\verb@index.tex@} file and {\verb@index.css@} in the directory with
the web pages.  Putting the image itself in the directory with the
{\verb@index.tex@} file is strongly recommended, in case somebody
decides to move a centrally located image file.


\subsection{How do I change the running bars?}
\label{sec:prrbars}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, you must edit
  settings.pl, not .latex2html-init. And try the second l2h menu
  first.}

Most changes are best made with the wiz, but here is some more.

To add a border around the bars, copy files {\verb@template.html@}
and {\verb@select.html@} in the {\verb@files@} subfolder of
{\verb@l2hsup@} over to the folder with your {\verb@index.tex@}
file, renaming {\verb@select.html@} into {\verb@select0.html@}.
Edit these files and find the
\begin{verbatim}
BORDER="0" CELLPADDING="0"
\end{verbatim}
{\verb@TABLE@} tag pairs (two occurences per file).  Change the border
value from zero to the desired border size in pixels, say 5.
Run the wiz and select {\lq\lq}change headers and footers{\rq\rq}.
No changes need to be made, they just must be rebuild.  Rerun (make)l2h.

Other changes to the HTML code can be made similarly, within reason.
If the changes you make are too big for the wiz to implement, the
actual code that is used is in file {\verb@.latex2html-init@}.

If the style changes that the wiz can do are not sufficient,
edit index.css (current document) and/or index.css in subfolder
{\lq\lq}files{\rq\rq} of folder {\lq\lq}l2hsup{\rq\rq} (future
documents) and change the values of TD.runner(b) to change bar colors,
font, etcetera.  Change the a.runner(b) values to change the
appearance of active links in the bars.  (B stands for bottom.)

Remake the web pages with (make)l2h.

\subsection{Colors}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, use the second
  l2h menu for this.}

\subsubsection{How do I change the background color from white}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, you must edit
  settings.pl, not .latex2html-init. And try the second l2h menu
  first.}

(Without using the wiz, that is.)

Edit .latex2html-init in the folder of the current document and/or
.latex2html-init in subfolder {\lq\lq}files{\rq\rq} of folder
{\lq\lq}l2hsup{\rq\rq} (for future documents) and set
{\verb@WHITE_BACKGROUND@} to zero and the desired color, in RGB
fractions, in {\verb@LATEX_COLOR@}.
(The {\verb@.latex2html-init@} files are hidden on Unix.)

Also edit index.css (current document) and/or index.css in subfolder
{\lq\lq}files{\rq\rq} of folder {\lq\lq}l2hsup{\rq\rq} (future
documents).  Put in the desired color in the BODY style.

Editing index.css and then reloading a web page in that directory is a
good way to experiment with possible background colors.

Existing images not made on the correct background color should be
deleted so that they can be remade on the right color, or ghosting
will result.

As far as your figures are concerned, they should be at least one of
the following:
\begin{itemize}
\item Figures already made with the correct background color.
\item Postscript figures using vector drawing only (no bitmaps).
\item Figures never anti-aliased.
\end{itemize}
Otherwise, if you rely on transparancy to change the background color,
you will either end up with ghosting or with aliasing errors.
The only way around that is to make the figures nontransparent, using\\
{\verb@\htmlimage{notransparent}{}@} in the figure environment.  This will
show the background color of the figures on which they were created.

Before running l2h or makel2h, in the DOS box enter:
\begin{verbatim}
set TRANSPARENT_COLOR=#123456
\end{verbatim}
where 123456 is the hex specification of your background color.


\subsubsection{How do I give each page a separate color}

I do not know an automatic way of doing that.  Given time, you could
start your document with section one, in the right background color as
described above.  Process.  Add section two to index.tex, and process
giving it the right background color (ignoring that web page one will
now also assume that color.)  Repeat until all sections have been
added.  Now edit index.css and remove the background-color line from the
BODY tag.  Edit index.html and each node...html and change
{\verb@<BODY >@} into {\verb@<BODY BGCOLOR="#CCCCCC">@}, where CCCCCC
is the desired color of that page.

Try to ensure that images from one page are not being used on another,
or they will show ghosting on the later pages.  Maybe put in a small strut
of varying vertical size?

To correct an error, reprocess in the color of the corrected web page
and repeat the editing of the html files.


\subsubsection{How do I specify colors}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, you must edit
  settings.pl, not .latex2html-init. And try the second l2h menu
  first.}

In {\LaTeX}'s rgb model, (also used near the end in .latex2html-init,)
you specify the amount of red, green, and blue, separated by commas.
Each is on a scale from 0 to 1, so \{0.23, 0.23, 0\} is 23\% red, 23\%
green, no blue: in other words, a dark yellow.

In HTML, and in index.css, you scale these numbers up by a factor 255,
so in the example above you get 59, 59, 0.  Each is then converted in
a two {\lq\lq}digit{\rq\rq} hex number as follows: divide by 16 to
find the first digit; the division remainder is the second.  For
example 59/16=3.68, so the first digit is 3.  The second digit is 59 -
3$\times$16=11.  Now the hex system takes digit 10 to be
{\lq\lq}A{\rq\rq}, digit 11 to be {\lq\lq}B{\rq\rq}, etcetera, until
15 is {\lq\lq}F{\rq\rq}.  So 59 is 3B and the full example color
specification is 3B3B00.

Remember that 000000 is black (all colors off) and FFFFFF is white
(all digits to the max.)  Also remember that the color in html is
preceeded by \#, e.g. \#FFFFFF for white.


\subsection{I must have frames}
\label{sec:prmhf}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular, selecting the
  original\_frames theme will give frames.  And you must edit
  settings.pl, not .latex2html-init.}

For your dose of prison bars, follow the
\htlink{example of the manual}{http://www.eng.fsu.edu/~dommelen/l2hmanf}.
Note that you will not see much frames unless you click on the contents
or index buttons.

Use {\verb@clrl2h all@} in the folder with your
{\verb@index.tex@} file to clean up any old web pages you may have made.
Then download the
{\verb@.latex2html-init@} file, (this is a hidden file on Unix,) and
the {\verb@index.css@} file and put them in with your document.
Run {\verb@latex index@} and {\verb@l2h@} or {\verb@makel2h@} to process.

Frames are {\em not} compatible with the wiz.   In particular,
you will need to edit {\verb@.latex2html-init@} to change colors.
Font sizes and styles can still be changed with the wiz, though.


\subsection{Text conversion problems}
\label{prtext}


\subsubsection{Incorrectly processed environments}

Rewrite index.tex to use more standard {\LaTeX}.  Or use the
htmlonly/latexonly environment described in the manual.



\subsubsection{Html package crashes while latexing index.tex}

The Proceedings of the Royal Society style does not define
{\verb@\paragraph@}, causing the html package to crash.
I used {\verb@\newcommand{\paragraph}{\subsubsection}@}
before loading html.


\subsubsection{Addcontentsline is not supported}

No.  But by default the titles of starred chapters and sections are
added to the contents web page, so try to make use of that.  You might
be able to do some tricks with {\verb@\htmlonly@} (see the manual)
too.


\subsubsection{Numbering changes are ignored}

This may not be as bad as it sounds.  Check the output.

Otherwise, try to avoid the need to explicitly change chapter numbers
or whatever.


\subsubsection{Line spacing is not consistent}

This happens if there are inline images, especially big ones, and more
for Internet Explorer than Mozilla.  It is due to the need for
additional whitespace around the images to get them at the right
height in the line.

Relatively small images with a vertical ink-region center about
half-way the letter {\lq\lq}a{\rq\rq} are least susceptible.

Consider turning big inline mathematics into displaymath.



\subsubsection{Lousy quotes}

Use {\verb@{\lq}@} for left quotes, {\verb@{\rq}@} for right ones.


\subsubsection{Accented characters not vertically aligned}

Some accented characters are unknown to {\latextohtml} and
represented by images.  To get the character to align well,
put it in an mbox in a math environment.  For example, use
{\verb@$\mbox{\.p}$@} instead of {\verb@\.p@}.


\subsubsection{I want different whitespace}

Play around with index.css.


\subsubsection{I want a different font}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  For one, you must change
  settings.pl, not .latex2html-init.  And try the second l2h menu
  first.}

To change the font size of the current document, edit the {\verb@index.css@}
file in the directory of the web pages and set the desire body font
size.  Do not put a blank before {\lq\lq}px{\rq\rq}.  You
also want to change the sizes of the headings H1 through H6, captions,
small and large styles,
table cells, and verbatim stuff correspondingly.

In addition, edit the file {\verb@.latex2html-init@} in the directory
with the {\verb@index.tex@} file and change the value of
{\$\verb@MATH_SCALE_FACTOR@} according to the formula given there.
(The {\verb@.latex2html-init@} file is hidden on Unix.)

Delete all images in the directory with the web pages and rerun
{\verb@l2h@} or 
{\verb@makel2h@}.  Repeat for the web page directory of the second
browser, if any, copying the index.css file over from the first.

To make the changes apply to future documents, instead edit
{\verb@index.css@} and {\verb@.latex2html-init@} in the directory
{\verb@C:\l2hsup\files@}.

Note that if you make the font size much less than 15px, subscripts
may become ink splots, and at about 8px, ordinary text becomes splots.

The vertical alignment of inline images is computed based on data for
the Arial font family.  If you select a body font that is very
different from Arial, you might have to play games with the
scaling factor used to compute font size in {\verb@C:\l2h\bin\pstoimg@}.
Alternatively, you can force the font size being passed to l2hcrop directly
by setting the environment variable {\verb@L2H_FONT_SIZE@} equal to
the desired font size in px.

\subsubsection{Problems with the verb command}

The online manual notes that double quotes should not be used as
terminators of verbs.

\subsubsection{Problems with tildes}

If you are using tildes in a url, you probably want to use the
hthtml package instead.  Documentation is in the docs directory of l2h.

The online manual notes to use {\verb@\~{}@} to put in tildes.


\subsubsection{Definitions run out of bounds}

{\latextohtml} is not very strong on redefinitions.  Try to contain
them within an environment or within curly braces.  Or just redefine
the variable back to the original value after the need for the change
is gone.

In general, encapsulating redefinitions within math environments or
other environments send to {\LaTeX} for processing seems to keep them
out of the main loop.


\subsubsection{Font changes run over}

The end of an environment may not end a font change as it does in
{\LaTeX}.  Simply put additional curly brackets around the font
change and its text.


\subsubsection{Math mode font changes}

The online manual notes that the font change in {\verb@{\LARGE $a_b$}@}
does not work, since the surrounding text is not included in math
processing.  So, put it inside the math: {\verb@{$\mbox{\LARGE $a_b$}$}@}.


\subsubsection{Optional arguments in description environments}

The manual notes that you may sometimes need to enclose the argument
in the square brackets also with curly brackets.



\subsection{Problems with the index}
\label{sec:pidx}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  For one, you must change
  settings.pl, not .latex2html-init.}

In {\latextohtml} the index keys are sorted case-insensitive.  Worse,
if you have say an entry with sort key {\lq\lq}D{\rq\rq} followed by
one with sort key {\lq\lq}d,{\rq\rq} the two entries end up as a
single entry {\lq\lq}d{\rq\rq}.  Since the index coding is a mess, the
only solution I have is to index the second entry as, say,
{\verb=\index{d-@d|...}=}.

The {\verb@short_index@} option, or {\$\verb@SHORT_INDEX = 1;@} in
{\verb@.latex2html-init@}, is highly recommended if you use section
numbers.

You might want a blank line in front of each starting letter, (to
visually separate different starting letters in the index).  The
standard way is to use {\verb@\index{D| }@}.  But that does not work
for me, as this D is put inside an HTML DT tag even using SHORT\_INDEX.
I float the DT tags (labels) in my style sheet to get them on the same
line as the DD data (descriptions) of description environments.
However, {\verb=\index{D@\HTMLcode{BR}D|...}=} does work.  But you
must of course have entries for each capital letter.

If you want an index entry refering to a sectioning title, put the
index command on the same line as the sectioning command.
Alternatively, end the sectioning command with a percent sign and put
the index command on the next line.  If you have more than one index
command for the same title, make sure to put them all on the same
line.  Do not break this line, even using a percent sign to comment
away to line break.  For some reason, that does not work.

Unlike {\LaTeX}, {\latextohtml} bolds the entries in the index.  That
may be a problem, for example if you use bold for vectors.  I also
think it is ugly.  If you do not like it, go into the
{\verb@latex2html@} script, find {\verb@sub@} {\verb@add_idx@} and
remove {\verb@<STRONG>@} and {\verb@</STRONG>@} from the second line.



\subsection{Problems with the bibliography}
\label{sec:pbib}

Ntabib's {\verb@\citeindextrue@} does not work correctly in l2hfu and
versions of l2h up to and including 1.1.  This will be fixed in the
next version of l2h, still to be posted at the time of writing, Sep.~1
2013.

If you want links from the bibliography entries to where they are
cited in the text, note that {latextohtml} does {\em not} implement
the hyperref package.  So it does not implement its backref option.
However, such links will be made using {\verb@\citeindextrue@} when
fixed.



\subsection{Problems with \textbackslash input commands}
\label{sec:pinpt}

Do not put two {\verb@\input{...}@} commands on the same line.
{\latextohtml} will not read the second file.

Somehow, {\latextohtml} confuses {\verb@\input{...}@} with
{\verb@\begin{...}@}, so make sure that your input file names do not
look anything like latex environments.  You will see [the start of]
all your input file names show up in the "unrecognized commands"
listing at the end.  They will have been faithfully read, however.
To cut down on the error messages, try starting each input file name with
a z.


\subsection{Image alignment}


\subsubsection{I must know about image alignment}

Once upon a time, on a world far, far, away from you and me, the wise
men of the entire world came together to establish how web pages
should understand the words of their designers.  They talked much, and
thought many deep thoughts, about what the designer would mean with
saying that an image should be aligned in the middle of the line,
vertically speaking.  And their thoughts allowed them to conclude that
aligning with the middle of the line clearly should be understood to
mean, aligning with the {\em bottom} of the line, rather than the
middle of it.  And so it was done.

But a small band of malcontents thought their browsers might grab a
bigger audience if it would align the middle of images with the
middle of the line, instead of its bottom.  And so they did it.
And so they grabbed pretty much all of the audience.

Still, not everybody was happy.  A very rich, but not very bright, kid
noticed that everyone was having a good time with browsers, and that
he did not have any piece of the action, having been unaware that
something was up earlier.  He thought long about how he could get in
on the action, which did not help.  He designed his own browser, but
it was not very good, since he did not understand well where the
middle of a line is supposed to be, and people did not like it.  And he
became very angry and decided to use his riches to give away his
browser for free.  He hired thugs to ensure that even people who did
not want his browser got one for free or by force.  And he paid for
vast amounts of web pages to be created with poor formatting. This was
really pretty clever, if you think of it, since while it did not improve
his browser's appearance, it made other browsers look bad too.
So people no longer bothered with the browsers that were not free.

And in this way the rich little kid made web pages mediocre for
everyone with his browser, which was a pretty good feeling.  But it
got pretty boring soon, so the rich little kid went on to spread
mediocrity elsewhere.

And new, more interesting browsers were then created by people who
still liked their images to be centered in the middle of the line.
And some poor kids got all excited about improving the new browsers.
And one of them noticed the words the wise men had spoken many years
ago.  She saw it all.  {\lq\lq}Aligning images in the middle of the
line means aligning them to the bottom of the line!{\rq\rq},  she
exclaimed to her friends, {\lq\lq}The wise men have decreed it!{\rq\rq}

And so it came about that half a score of years after the wise men
had spoken, their words of wisdom were finally heard and adhered to.
And it was established all over that world that the middle is the
bottom.  Just like for people.


\subsubsection{I mean, of course, understand all those browsers}

Ahem.  I now see what you mean.  Since the capabilties of HTML, even
its derivatives, in producing good math formulae, are abysmal,
{\latextohtml} uses {\LaTeX} to create proper formulae, and then
converts them to images.  A great idea, but of course, those images
have to be put in the right place in the web page.  No big deal if
they are displayed formulae, but tricky if the math appears in the
middle of a sentence. Horizontally speaking, it is still not much of a
problem; browsers simply put them in the place where{\latextohtml}
says to put them.

The difficulty is the vertical position of the image compared to the
surrounding line.  For a math symbol such as $\alpha$ this is not much
of a problem; when properly directed, the browser will align the
bottom of $\alpha$ with the bottom of the line.  Or rather, with the
{\lq\lq}baseline{\rq\rq}; the bottom of letters such as a, b, and c,
that don't have appendages sticking down.  Definitely, bottom
alignment with the baseline is not a problem.  (Except under some
conditions for Internet Explorer, which is another story.)

While $\alpha$ is OK, where should the browser put an image of the
letter $\beta$, descending below the baseline?  The browser does not
understand the meaning of the image, and so has no clue what part of
it should be at the height of the baseline if it is not the
bottom. The original {\latextohtml} cleverly solved this conundrum by
adding enough blank space so that if the image is properly {\em centered}
vertically (instead of bottom-aligned), the image will be
at the right height in the line.

Unfortunately, browsers do not manage to properly center images
vertically in the line.  The way to do it was specified in
international standards, but they were ignored by all browsers I have
seen.

My own initial take on the matter was that of a realist; I just
measured where the various leading browsers {\em did} put the image
vertically, and then sized the image so that it would end up at about
the right height.  Which was a significant improvement.

Yet there was a difficulty.  The practical standard of where to
vertically center images was set by Mosaic and Netscape.  Yet, when
Microsoft entered the browser market with Internet Explorer, they did
not just ignore the internationally agrred upon standards, like
everyone else, they also ignored the reigning standard established by
Mosaic and Netscape.  I have the suspicion that the real reason was
that the Microsoft software designers did not really know where the
baselines of their lines were.  It appears that they only kept track
of where the overall highest and lowest points in their lines were,
and that they averaged the two to get some sort of approximate
{\lq\lq}baseline{\rq\rq}.  Of course, for very large images, the
highest and lowest points are the image itself, and those images are
aligned with {\em their own center,} a singular problem that led
Mircrosoft to a {\lq\lq}baseline{\rq\rq} that is the center of the
image.  Gee, just like the international standard stipulate!
Unfortunately, this is only true for very large images.  Realistically,
if the image is at the right height in Internet Explorer, it is not
in Mosaic, Netscape, Mozilla, or Firefox, and vice versa.

So I set things to create middle-aligned images of two different
sizes, one for Explorer, and one for the rest of the world.  Not
ideal, but it seemed the best I could do.  Then Firefox 1.5 threw a
monkey wrench into that idea too, by deciding out-of-the-blue to
suddenly follow the international standards.  A good idea, but much,
much, too late in my view.  I had now ended up with the need of sizing
math images {\em three} different ways.

It got me to think about style sheet alignment.  Style sheets are a
later development in HTML, specifying in greater detail the visual
appearance of web pages.  In other words, style sheets appeared when
browser designers might have developed a vague clue what was going on
and might have gotten some of it right.  And indeed, it turns out that
style sheet alignment is much more uniform among browsers than the
normal version.  Enough to create a single size of images and have them
OK for all browsers.

In fact, the international standard for style sheet aligment is very
clear: the center of the image must be aligned with the center of the
lower case letter {\lq\lq}x{\rq\rq}.  True, Internet Explorer thinks
the middle of the letter x is two third of the way up, instead of
where the lines cross; they probably got confused with the capital
letter X. But still, the differences between browsers remain small if
you average them.  So, I switched back to one type of images for all,
though you can still generate the other versions if you want alignment to
be more precise.


\subsubsection{So, how about all those browsers??}

{\bf Note: Much of what is in this section is outdated.  For current
  software and its usage instructions go to either
  \hturl{http://www.eng.fsu.edu/~dommelen/l2h} or
  \hturl{http://www.dommelen.net/l2h}.  In particular,
  only the a-style is currently still supported.}

Right.  So, as explained in the last section, optimal vertical alignment 
of math images requires different size images for different browsers.
The following sizings are available:

\begin{description}
  
\item[m] (Mosaic) Math images are sized to properly align vertically
  when viewed in Mosaic, Netscape, Mozilla, and early-version Firefox
  browsers.  Their market share is small, except maybe early Firefox.
  
\item[e] (Explorer, obsolete) Math images are sized to properly align
  vertically when viewed in Internet Explorer, but only if {\em they
    are the only image in the line.} If there is, say, a big
  bottom-aligned image in the same line, the image will hover way
  above the line it is supposed to be part of.  Remember what I told
  you the previous subsubsection?  Explorer takes the baseline as the
  middle between the highest and the lowest point of the line (without
  putting the text there.)  A big image can raise that way up.  For
  that reason, the {\lq\lq}e{\rq\rq} alignment is obsolete.  If you
  have to size for explorer, use the advanced (a) or explorer (x)
  style sheet alignments below.
  
\item[c] (Correct) Math images are sized for their middle to align
  with the baseline.  This is how it should be.  But only late
  versions of Firefox do it.  (1.0 does not, 1.5 does.)
  
\item[g] (Generic, obsolete) Used to be an average of m and e, now an
  average of c and e.

\item[a] (Advanced)  This is a style-sheet based alignment.  Reasonably
  accurate for most browsers.  At the default font size of 15 pixels,
  more accurate for Internet Explorer than x below!  In general,
  an average of x and f below, with an alignment that is not likely
  to be much more than a pixel too high or low for whatever browser.
  
\item[x] (Explorer) This is also an style-sheet based alignment, but
  optimized for Internet Explorer.  Note that IE seems to perform all
  alignment computations in integer arithmetic, producing large
  rounding errors (frequently, when the font size goes {\em up}, the
  center of the line goes {\em down} according to IE.)

\item[f] (Firefox) Another style-sheet alignment.  This one optimized
  for the Mosaic/ Netscape/ Mozilla/ Firefox line.  Works better at the
  default font size of 15 pixels than a.  Unfortunately, browsers in this
  line have a random variation of about a pixel in vertical image alignment
  that cannot be removed.

\end{description}


\newpage
\appendix

\section{Problems resolved in LaTeX2HTML}
\label{appdx}

Here is a list of problems I found in {\latextohtml} 99.2 and
corresponding FU fixes.

\begin{enumerate}


\item
{\it Problem:} It crashes, requiring a Ctrl-Alt-Del removal of the
DOS box, and fairly soon a complete reboot.

{\it Reason:} DOS has only very marginal redirection capabilities.
pstoimg.bat does three redirections to reduce screen output.  Each of
them by itself is enough to crash the DOS box.

{\it Solution:} I removed all three.  My l2hcrop does less output anyway.


\item
{\it Problem:} Commands executed through batch files, such as {\LaTeX}, crash

{\it Reason:} Perl does not pass the parameters to batch files.
{\LaTeX} cannot process images.tex if it does not know the file name.

{\it Solution:}  Create a Gnu 77 Fortran program rb.exe, (for run bat), 
and run all batch files through that executable.


\item
{\it Problem:} Batch files do not return error status.

{\it Reason:} DOS.

{\it Solution:} Make a batch file, latexl2h.bat, that returns a pointer,
{\verb@C:\Temp\rb.err@}, if an error occurs, and then make rb.exe
return an error status to Perl.


\item
{\it Problem:} Messages go off the screen before they can be read.

{\it Reason:} DOS boxes do not have a buffer, and output redirection of
stderr would be very difficult even without all the other redirection
already there.

{\it Solution:}  Create a log file {\verb@C:\Temp\l2h.log@} and copy
all the output, of at least in latex2html.bat, pstoimg.bat, and texexpand.bat,
to that file.  Allow an environment variable {\verb@L2H_SLEEP@} to be
set with a delay.  (Note that reading from the keyboard tends to fail
with all the input redirection being done.)


\item
{\it Problem:} There is a roughly 95\% chance that the program does
not work even with the crashes removed.

{\it Reason:} It tries to accomodate every possible version and
variation of about 30 different external utilities not under the
authors' control.

{\it Solution:}  Specify specific version numbers for the netpbm utilities
in a constant state of flux.  Ignore alternate possibilities to
freely available programs, and specify the latest version of the
more consistent ghostscript, dvips, and perl utilities.


\item
{\it Problem:} Netpbm 10.18 has compatibility problems, including with the
vital pnmcrop, which does not work correctly in latex2html.

{\it Reason:} latex2html was written a long time ago.

{\it Solution:} Switch to the earliest I could find, Netpbm 10.6.


\item
{\it Problem:}  Various utilities in netpbm 10.6 do not work properly,
such as the jpeg ones.

{\it Reason:} It is an old version.

{\it Solution:} Get those from the last version, 10.18.


\item
{\it Problem:} Anytopnm is a unix shell script.

{\it Reason:} Netpbm was not really designed for Windows.

{\it Solution:} Substitute a batch file as a crude fix.


\item
{\it Problem:} Some Netpbm utilities miss the .exe file extension.

{\it Reason:} Seems to be an indication that they are obsolete.

{\it Solution:} Rename them.


\item
{\it Problem:} Gifs turn out with horrible, completely wrong colors.

{\it Reason:} A known bug in PPMQUANT.

{\it Solution:} Substitute a batch file that runs pnmmap and pnmremap
instead.


\item
{\it Problem:} Latex2html.bat fails renaming existing images, to be
reused, back from .old to .gif.

{\it Reason:}  DOS cannot keep up with the amount of files being renamed.

{\it Solution:} On failure, put in a one second delay, and then try again.


\item
{\it Problem:} The installation procedure insists on a html checker.

{\it Reason:} Beats me.

{\it Solution:}  Provide a fake one, chckhtml.bat, doing nothing.
You can always put one in there, following the lines of latexl2h.bat.


\item
{\it Problem:} Insists on making png instead of gif images if png is enabled.

{\it Reason:} Beats me.

{\it Solution:} Change prefs.pm to get rid of png completely.


\item
{\it Problem:} You get an address in your web pages even if you blank
out the variable.

{\it Reason:} Whatever you set address to, it is redefined in latex2html.bat.

{\it Solution:} Change latex2html to not set address if it is already
defined.


\item
{\it Problem:} The configuration procedure cannot handle required switches
and arguments of executables.

{\it Reason:} The authors did not put it in.

{\it Solution:} Put suitable switches and parameters in the pin files.


\item
{\it Problem:} Seems to be an aliasing problem.  Text is varying thickness.

{\it Reason:} Page color is set to grey scale in l2hconf.

{\it Solution:} Set page color to the more general white.


\item
{\it Problem:} The -E dvips option is set twice, once unconditionally
in l2hconf.

{\it Reason:} A new line after a comment symbol.

{\it Solution:}  Remove the new line.


\item
{\it Problem:} Almost all latex2html web pages on the net have missing
icons, including a number of old ones of my own.

{\it Reason:} An insane idea to have the icons placed on some central
location on the web server, rather than safely with each document.
You have to be a system administrator yourself to trust they will keep
these icons safe for eternity.  If these system administrators are
still working here next year, and still remember what the icons were
for in the first place, and are willing to figure out whether someone
is still using them instead of simply deleting and waiting for
complaints, that is.

{\it Solution:}  Set the local icons option as default.


\item
{\it Problem:} HTML 3.2 is used.

{\it Reason:} For historical reasons, it says.

{\it Solution:} Use HTML 4.


\item
{\it Problem:} Web pages drive you crazy with some having a navigation
panel at their bottom  and some not.

{\it Reason:} Beats me.

{\it Solution:} Set default options to enable bottom panels on all pages.


\item
{\it Problem:} You cannot just click the forward and backward icons to
scroll through the web pages.  Also, part of the upcoming section name
is lost.  The order of the icons is counter-intuitive.  Navigation
panels visually dominate the web page.

{\it Reason:} Putting section names between the icons causes them to
flip back and forth from one page to the next.  With all the text,
there is not enough space for full titles.

{\it Solution:} Get rid of the text except that of the upcoming
section, and put that behind the icons.  Put them in an intuitive order.
Move the navigation panel formatting to .latex2html-init to make it
easier to customize.


\item
{\it Problem:} Navigation icons look unimpressive and dominatingly big.

{\it Reason:} Beats me.

{\it Solution:} Remade the icons.  Still not very impressive, but better.
Added some support for people to make their own.


\item
{\it Problem:} There is no utility to make figures with MS Paint and convert
them to eps.

{\it Reason:} Authors do not use MS Paint?

{\it Solution:} Add bmptopnm.exe from netpbm and create a batch file
bmptoeps.bat.


\item
{\it Problem:} Usage is not very user-friendly.

{\it Reason:} Not designed that way.

{\it Solution:} Provide a batch file makel2h.bat to do the
usage overhead and a utility l2hnewer.exe to check file dates.


\item
{\it Problem:} The manual is not easy to process and the segmented
document you are asked to produced cannot be created.

{\it Reasons:} Use of special style files, some with file names over
8 characters long.  Use of a makefile, which simply does not work,
for one reason since DOS batch files do not return error codes.

Addition: the two poorly documented makefiles do not work under Unix,
either.  Half the manual is not processed.

The \htlink{official online manual}
{http://www-texdev.ics.mq.edu.au/l2h/docs/manual/} is not that great either.
For example, what to make from figure 3?

{\it Solution:} Provide the processed manual in pdf form, and the
hthtml page in html form and just zip the rest.


\item
{\it Problem:} Style file verbatimfiles.sty does not work since its name
is more than eight characters.  The same for changebar.sty.

{\it Reason:} No acount is taken of older TeX versions.

{\it Solution:} Make a note to the users to rename it.


\item
{\it Problem:} Installation creates weird error messages if an
executable is missing.

{\it Reason:} Beats me.

{\it Solution:} Make sure none is missing.


\item
{\it Problem:} Inline mathematics is a completely different font size
than the rest.  On some pages on the web, it is three times bigger.

{\it Reason:} The font sizes are not fixed, depending on options
and user browser setting.

{\it Solution:} If you represent math by images, you no longer have a
choice about font size.  So, set the chosen font size for the nonmath
to the same fixed size using style sheets.  (Note however that web page
readers may set their browser to ignore style sheet font sizes.  That
is up to them.  Their math will still be the same size.)


\item
{\it Problem:} Inline images are not aligned correctly vertically.

{\it Reasons:}
Mozilla and Internet Explorer do not vertically align images
at the same height.
Also, for both browsers, image alignment depends on font size.
Raised images are not correctly aligned by the latex2html
pnmcrop procedure.
If there is more than one image in the same line,
Internet Explorer will mess up the alignment of one because of the
presence of the other.

{\it Solutions:}
Provide separate web pages for Mozilla and Internet Explorer.
Provide an older version of pnmcrop instead of the latest which
does not work correctly.
Provide a program, l2hcrop.exe, that crops more reliably.
Fix the font size, and make l2hcrop compute the correct
alignment for that font size.
L2hcrop will correctly crop raised images.
The IE problem with multiple images in the same line cannot be
resolved, but l2hcrop minimizes it by cropping the mages to the
minimum size required.


\item
{\it Problem:} Weird black bars show up below or to the left of
math images.

{\it Reasons:} Sometimes latex2html produces alignment bars that are
too short.  In that case, pnmcrop will leave this artifact in the
image.  In
addition, pnmcrop may be a wrong, too recent, version.

{\it Solution:} Use l2hcrop, and make it check and correct for the
possibility that the alignment bars are too short.  Ensure a compatible
version of pnmcrop for the rare case that l2hcrop runs out of memory.


\item
{\it Problem:} Line spacing is widely varying from one line to the next.

{\it Reason:}  The whitespace put in to vertically align images.

{\it Solution:} Let l2hcrop cut the images to the smallest size possible
to minimize the problem.


\item
{\it Problem:} Figures have incomplete characters and missing lines.

{\it Reason:} Ghostscript does not anti-alias embedded bitmaps.

{\it Solution:} Apropriate the extrascale option, ignored by latex2html
for figures, to let ghostscript oversize the figures, then provide
l2hcomp.exe to put them back to size with proper anti-aliasing.


\item
{\it Problem:} Excessive white space around formulae.

{\it Reason:} Apparently the authors want to simulate mathsurround,
even if it just looks funny on a screen with much less real estate
than a printed page.

{\it Solution:} Class the whitespace, and use style sheets to get rid
of it.


\item {\it Problem:} Navigation panels are not easily customized
  beyond simple changes.

{\it Reason:} Icons are hard coded, even with their links and file names.

{\it Solution:} None.


\item
{\it Problem:} Left quotes look lousy.

{\it Reason:} Seems to be intentional, probably a bug fix for
something else.

{\it Solution:} Tell users to use {\verb@{\lq}@} and {\verb@{\rq}@}.


\item
{\it Problem:} Creating 500 images is very slow.

{\it Reason:} Well, what do you expect.

{\it Solution:} L2hcrop provides a partial solution, because
one invocation of l2hcrop replaces about four invocations of pnmcrop,
one of pnmquant, as well potentially a pnmflip one. Also, l2hcrop reads
the image file only once, keeping it in memory. The
\htlink{Quantum Mechanics for Engineers}
  {http://www.eng.fsu.edu/~dommelen/research/nano/quantum/}
web pages, with well over 500 images, take 15 minutes
to create, per browser, on my four or five year old Windows 98 laptop.

I do find that it runs many times more slowly (though correctly) on my
desktop at work, also a 98, but with 128 Mb memory instead of 256, and
slower disks.  Neither disk or memory is the problem, however.  The
problem is that the processor is maxed out to 100\% while running.  It
however, is virtually the same processor as my laptop's.  If anyone
can solve this complete mystery for me..?


\item
{\it Problem:} Images are not always remade.

{\it Reason:} The algorithm ignores changes in spaces, as well as
missing backslashes and brackets that you correct.

{\it Solution:} Warn the user to delete the image.  Also note to try
browser refresh.


\item
{\it Problem:}  In debug mode, intermediate images are not kept as promised.

{\it Reason:} They are named by process ID.  DOS reuses process IDs.

{\it Solution:} Use time instead of process id for the name.


\item
{\it Problem:} Ridiculous long HTML name tags for section starts.

{\it Reason:} I don't know.

{\it Solution:} None.


\item
{\it Problem:} Somehow, the document, part, chapter, and section
titles are all set the exact same way, and in the same font size.

{\it Reason:} They are all converted into classless H1 tags, because
really important divisions such as subparagraph need their own
tag, and html has only 6.

{\it Solution:} Let subparagraph suffer.


\item
{\it Problem:} The style file is {\em hardcoded} in latex2html, and
incomplete.

{\it Reason:} Beats me.

{\it Solution:} Let makel2h move in a style file before latex2html
gets the chance.


\item
{\it Problem:} Small images are not being created.

{\it Reason:} ppmtogif crashes trying to interlace gifs that are only
3 pixels or so high.

{\it Solution:}  Let l2hcrop return a warning if the image is less than
16 pixels high, and turn off interlace if it is.


\item
{\it Problem:} Images.tex tends to fail to process.

{\it Reason:} It is pushed in a subdirectory.  I don't know why
this file could not be processed in the original directory and then
moved down, but anyway.

{\it Solution:} Warn the users more clearly about .. in texinputs,
providing a test for it, and about not having relative path names.
Pause the screen if latex returns a warning on images.tex and copy
the files to the Temp directory for examination.


\item
{\it Problem:} Html.sty does not account for the possibility that
paragraph is not defined.

{\it Reason:} Beats me.

{\it Solution:} Warn the user.


\item
{\it Problem:} Sections/figures/tables are not correctly numbered.

{\it Reason:} The numbers are retrieved from latex for the
given title.  Unfortunately,
Latex and html do not always agree on what is the title.

{\it Solution:} (1) Added a last resort search that first removes
embedded mathematics from the titles, that makes the tex and html
agree on the \&, (very common in legends because of references), and
that prints to the log file to show why the search fails, if it still
does.  (2) If this last resort fails too, increment the previous
number by one, which works most of the time.  Warn the user, anyway.
Also add a warning to problem shooting  not to use discretionary hyphens,
they cannot be fixed without also affecting true hyphens.


\item
{\it Problem:} It tries to process {\verb@\input{abstract}@} as
{\verb@\begin{abstract}@}, making a mess.

{\it Reason:} Unknown.  It does input the file.

{\it Solution:}  Warn the user to not make input file names look like
environments.


\item
{\it Problem:}  Addcontentsline is not supported.

{\it Reason:} Don't know.

{\it Fix:} Set default to have starred section titles go to toc.


\item
{\it Problem:} Resetting section numbers does not work.

{\it Reason:} Unknown.

{\it Solution:} None.
(This does not seem
to be much of a problem since it gets its numbers from latex anyway.)


\item
{\it Problem:} Thumbnails are not cropped.

{\it Reason:} The crop option is not passed to pstoming.

{\it Solution:}  Add it.


\item
{\it Problem:} Captions of figures have each word on a separate line.

{\it Reason:} The figure and caption are put in a html table.  The browsers
then make the table as wide as the figure, which can be very small.

{\it Solution:} Specify the table to be 65\% of the page width.


\item
{\it Problem:} Code is very hard to figure out.

{\it Reason:} Perl asks for messy code, and not providing full
comments in the code does not help.  The code is also full of adhoc
fixes, not just mine.

{\it Solution:} None.


\item
{\it Problem:} Figure environments with two captions are made into
a single image.

{\it Reason:}  That is how it is.

{\it Solution:} Warn the user to split it into two figure environments.


\item
{\it Problem:} Text in figure environments ends up as part of the figure.

{\it Reason:} Yes.

{\it Solution:} Warn the user to put it in a caption, or live with it.


\item
{\it Problem:} Pnmflip does not work.

{\it Reason:} It is a unix script running Perl running pamflip.

{\it Solution:} Provide the earlier netpbm utility for Windows, include
pamflip in Unix.


\item
{\it Problem:} Config.pl searches through directories in the wrong order.

{\it Reason:} Seems to be subroutine that removes duplicate entries.

{\it Solution:} Removed.


\item
{\it Problem:} Two files in versions/ had crashing perl.

{\it Reason:} Unknown

{\it Solution:} Commented out the lines, which should not be needed anyway.


\item
{\it Problem:} {\latextohtml} is not able to correctly process its
own manual, using the versions required by the manual.  Weird marks
are put behind various equation.

{\it Reason:} A sharp is missing in the end of equation marker
in versions/math.pl, so these markers stay in.  How was the manual
on the web made??

{\it Solution:} Added the sharp.


\item
\label{offmanprob}
{\it Problem:}  The \htlink{official online {\latextohtml} manual}
{http://www-texdev.ics.mq.edu.au/l2h/docs/manual/} has figure 3
messed up (wrong image is displayed).  The same for figure 1.
This is unfortunate since these figures were supposed to make specific
points. Its table of figures is in the wrong order.
The Installation and Further Support section is out of date compared to
the manual accompanying the distribution.  For example, the
Windows instructions are missing.  (But the ones in the distribution
are not right either.)  The graphic could have been anti-aliased
a bit.  The pictures in the bibliography are external
references and have, of course, long disappeared.  So have most of
the links in the exemplary documents section.

{\it Reason:} Unknown.

{\it Solution:} The \htlink{{\latextohtml}-FU remake}
{http://www.eng.fsu.edu/~dommelen/l2hman} fixes some of the problems.
Nothing can be done about links that have disappeared.


\item
{\it Problem:} The frame version overwrites the user's definition of
the navigation buttons.

{\it Reason:} Incorrect perl.

{\it Solution:} Renamed the subroutine not to overwrite the user's.


\item
{\it Problem:} The frames do not disappear even when completely leaving
the document.

{\it Reason:} The Up link out of the document is loaded into a frame.

{\it Solution:} Maintain the external link at {\verb@TARGET="_top"@} 


\item
{\it Problem:} Config fails under Windows XP.

{\it Reason:} Windows XP returns a bit set instead of a bit-cleared status.

{\it Solution:} Took out the status test.


\item
{\it Problem:} Defs with arguments to complex are not added to the preamble.

{\it Reason:} Unknown.

{\it Solution:} Added a note to the problem solving section to unset TEXDEFS.


\item
{\it Problem:} Error message that PPMQUANT cannot be found if the graphics
or graphicx packages are loaded.

{\it Reason:} graphics\_support.perl wants it, but the true version
no longer exists.

{\it Solution:} It seems unlikely to be of much importance unless you
include non eps graphics.  I just added a note in the graphics problem
solving section.


\item
{\it Problem:} MiKTeX 2.4 cannot find the input files.

{\it Reason:} The authors of MiKTeX 2.4 lost the entire environment,
including TEXINPUTS.  They plan to fix it in 2.5, out some time in summer
2006.

{\it Solution:} Install script l2hinm24 creates a local miktex.ini
that points dvips to the files.  Latexl2h.m24 (.bat) uses a command
line option to do the same with latex.


\item
{\it Problem:} Newer TeX versions leave underlines below some
formulae.  I am grateful to Prof.~Rogelio Alc\'antara for pointing
this out and helping me get it fixed.

{\it Reason:} Another alignment bar bug.  Probably due to the newer dvips.
Ghostscript produces a sidebar that is too long.

{\it Solution:} Fixed that one too in l2hcrop.


\item
{\it Problem:} MiKTeX 2.5, beta 7 or earlier, cannot find the input files.

{\it Reason:} While TeX was fixed, dvips was not.  This was fixed in beta 8.

{\it Solution:} Install script l2hinmkt appends to dvips.ini
in the main config directory for the earlier versions of 2.5.


\item
{\it Problem:} Firefox 1.5 image alignment is incorrect.

{\it Reason:} Firefox seems to have switched to w3c recommended alignment.

{\it Solution:}  Added this cropping too to l2hcrop.  Made it the default
instead of the Mozilla alignment.


\item
{\it Problem:}  I found my implementation of NOEPS on Windows was 
excessive (only two files were truly different, and I created an
entire new directory), and it was simply wrong on Unix.

{\it Reason:} My stupidity and/or lack of careful examination of the
differences.

{\it Solution:} Both versions of the two files are now provided in a
single {\latextohtml} directory, and l2h and makel2h swap in the
appropriate versions.


\item
{\it Problem:} The NOEPS option does not work correctly with newer versions
of TeX like MiKTeX.

{\it Reason:} Unknown.  I am guessing an internal difference between
dvips 5.83 and 5.85.  Pstoimg.bat cannot find the page dimensions in
the new version.  But they are there the same way.

{\it Solution:} NOEPS is only used as a fix for problem figures. Noted
that it does not work in new versions of TeX in the corresponding problem
shooting subsubsection.  The other, better, solution will have to be used.
A solution of the pstoimg problem goes on the wishlist.


\item
{\it Problem:} {\latextohtml} arbitrarily removes all attributes from
empty table cells.

{\it Reason:} Unknown.

{\it Solution:} Curse.  Put in a few \&nbsp;s.


\item
{\it Problem:} {\latextohtml} loses \$TITLE on its way to the navigation
panels.

{\it Reason:} Unknown.

{\it Solution:} Curse.  Copy it over into \$RUNNING\_TITLE.

\item
{\it Problem:} Jpegs are no longer created.

{\it Reason:} A test that ppmtojpeg was an executable file.  Sometime
after Shankar\rq s thesis, I took out the path from the executables.

{\it Solution:} Drop this test.  When installed according to
instructions, ppmtojpeg is there.  Otherwise, do not use L2H\_JPGQ.


\item
{\it Problem:} Thumbnails are not anti-aliased.

{\it Reason:} I guess it did not seem important to me at the time.

{\it Solution:} Added.


\item
{\it Problem:} Jpegs of thumbnails are not correctly processed.

{\it Reason:} I did not think that thumbnail entries in images.pl would be
different.

{\it Solution:} Fixed.


\item
{\it Problem:} Floating point numbers are not correctly read by the wiz.

{\it Reason:} I am teaching math??

{\it Solution:} Fixed.


\item
{\it Problem:} Eqnarrays alignment is lousy in html 3.2, marginal in html 4.0.

{\it Reason:} This is an html table limitation.  Html 4.0 used a
dirty trick to improve things a bit.

{\it Solution:} Put in a better dirty trick.


\item
{\it Problem:} Left or right align in the htmlimage command does not do
what you would normally want it to do.

{\it Reason:} The obvious reason is that it is applied to the image itself,
not to the table containing it.  Whether there is a deeper reason for this??

{\it Solution:} Copied it to the containing table, if align=right or
align=left is specified in htmlimage in lower case, with no quotes.
If that is interfering with something I do not know about, just change
case.


\item
{\it Problem:} Return of the dreaded underlines!!

{\it Reason:} The alignment bar thickness for larger magnifications
increases beyond the limits used in l2hcrop.

{\it Solution:}  Made the bar thicknesses fontsize dependent.


\item
{\it Problem:} {\latextohtml} will not remake figures or equations that
change by whitespace, braces, or backslashes, and will put the wrong
figures where the latex source code of two figures is the same for the
first 80 or so characters.

{\it Reason:} By design, {\latextohtml} only looks at the first 80
characters of the latex source code of a figure or equation to see
whether it is different from another.  In addition, while doing so it
will completely ignore all whitespace, braces, backslashes and more.
(Look at the keys in an images.pl file to see what I mean.)

{\it Solution:}  As of Sep.~2007, the keys now include a 32 bit CRC check
sum of the {\em entire} latex source code of the figure or equation.


\item
{\it Problem:} Excessive whitespace behind {\verb@eqnarray*@}
environments.
  
{\it Reason:} For reasons unknown to mankind, these environments were
terminated by three line breaks and additionally three blank
paragraphs!

{\it Solution:}  Eliminated two breaks and two empty paragraphs.


\item
{\it Problem:} Natbib's {\verb@\citeindextrue@} does not make any links
to in-text citations, just to items in the bibliography.

{\it Reason:} In natbib.perl, someone has disabled links to in text
citations, "if desired", unconditionally.  Apparently, disabling them
is always desirable in the view of this person.

{\it Solution:}  Killed off the line that killed of the links.


\item
{\it Problem:} Natbib's {\verb@\citeindextrue@} does not work with
numerical references.

{\it Reason:} In natbib.perl, someone turned it off for numerical references.

{\it Solution:}  Killed off the code that turned it off.  If
{\verb@\citeindextrue@} works for LaTeX, it should also work for
{\latextohtml}.  (However, the references in the index will show
authors and year, rather than authors and citation number.)

\item
{\it Problem:} Figures and math images have inconsistent sizes,
or overful boxes occur.

{\it Reason:} {\latextohtml} makes just a guess at {\verb@\textwidth@}
and {\verb@\textheight@}.  So they are inconsistent with the document.

{\it Solution:} Latex2html now takes these values, in pt, from
{\verb@$TEXTWIDTH@} and {\verb@$TEXTHEIGHT@} if set in
.latex2html-init.

\item {\it Problem:} Odd-byte CJK strings of plain latex or pdflatex
  sources got junk appended at the end, like say {\verb@\end{CJK}@}.

{\it Reason:} CJK.perl assumed the input encoding is in pairs of
bytes, which is untrue for UTF-8.

{\it Solution:} Skipped the relevant pre-pre-processing if
\${\verb@CJK_AUTO_CHARSET@} is set to UTF-8.  {\latextohtml} seems to
handle it fine by itself.

\item {\it Problem:} {\latextohtml} stops working with Perl error messages.

{\it Reason:} Like linux developers, Perl developers hate backward
compatibility.  Their motto, too, is \lq\lq{}if it works, fix it.\rq\rq{}

{\it Solution:} Removed {\verb@defined@} commands, added backslashes,
changed substitution command modifiers, etcetera.

\item {\it Problem:} Weird strings show up in figures and mathematics
  processed by Perl version 5.22.

{\it Reason:} Like linux developers, Perl developers hate backward
compatibility.  Their motto, too, is \lq\lq{}if it works, fix it.\rq\rq{}

{\it Solution:} Found a regexp using a {\verb@\G@} anchor in
{\verb@latex2html@} that removes comments but no longer worked
correctly under Perl 5.22 (without error messages being generated).
Rewrote the regexp to be far less convoluted, making it work again.

\end{enumerate}


\section{History of l2hfu}

Jan 6, 05.  Version 1.  Files installed on Unix and Windows 98 without
problems.

Jan 7, 05.  Directory protections were not set to allow outside access
in Unix.  The H5 and H6 heading styles were not obvious enough.

Jan 10, 05.  The font size can now be set without losing correct
vertical image alignments.  Also, the default font is now 15 px, not
19.  Installed the distribution from scratch on Unix and Windows 98
without problems.

Jan 11, 05.  html.pl bug fix added.

May 11, 05.  Updated section on animations. Reposted.

Aug 23, 05.  Added {\lq\lq}I do not want to use makel2h{\rq\rq} subsection.

April 23, 06.  Created easy-install scripts for MiKTeX 2.4, fpTeX and
XEmTeX, and simplified full install.  Fixed another alignment bar bug
using l2hcrop.

June 12, 06.  Improved the scripts to accomodate nonstandard TeX
locations, fix a new bug in MikTeX 2.5 up to beta 7, and added
uninstall scripts.  Added notes about epsf.sty.  Added support
for Firefox 1.5 image alignment and made it the default.

June 30, 06.  Added style alignment, and a much simpler interface to
use it.  Just say l2h and the web pages are created.  Style alignment
allows much better alignment of images in Internet Explorer and
a single set of web pages for all browsers.  Added clrl2h.

July 13, 06.  Fixed the no-eps variant, which was incorrect on Unix
and overkill on Windows.  The l2hs directory is gone.  The templates
in folder {\lq\lq}files{\rq\rq} are now simply called index.css and
.latex2html-init, like the target, which simplifies the idea and makes
them wiz ready.

Aug 17, 06.  Added the wiz, redid various sample web pages.  Added a
{\lq\lq}What is LaTeX{\rq\rq} subsection to the problem shooting section.

Aug 23, 06.  Added improved jpeg support.

Aug 28, 06.  Improved eqnarray alignment.  Must be using html 4.0.
Other small improvements based on redoing Shankar's thesis.
Some minor wiz changes.

Sep 4, 06.  The left align and right align of htmlimage now actually do
something for figures.

Sep 8, 06.  Made the bug fixes in l2hcrop fontsize dependent.
Rewrote the corresponding problem shooting subsubsection.

Sep 20, 07.  Easy install version for linux.  Finally fixed the
annoying figure identification deficiencies.

Mar 22. 08.  The excess white space behind {\verb@eqnarray*@}
environments has been eliminated.  For the rest, everything works fine
for me, so I try to leave things alone.

Nov 11, 09.  The easy linux install now also works if your home
directory is not /root.  Gee.  Current versions of Perl no longer
support the multiline matching used in {\latextohtml}.  Some minor
fixes have therefor been made to
\htlink{latex2html.pin}{../zips/latex2html.pin}.  They are not yet
included in the Windows l2hfu3.exe, since they seem inconsequential.

Dec 2, 09.  The init script now will not crash even if you do not have
TEXINPUTS already set.  Curses.

Oct 29, 2012.  If there is a linebreak between the ] and the \{
of a caption or section title, separating the shortened
version from the longer one, the caption or section title will
be erroneous.  I put in a warning not to do that.

Jun 20, 2013.  Added the {\verb@<nobr>@} tag to {\verb@html4_0.pl@}.  While
unofficial, this tag is widely supported and very useful.

Jun 20, 2013.  Removed erroneous space around math comments,
like in {\verb@$...\mbox{...$...$...}...$@} constructs.

Jun 20, 2013.  Perl no longer accepts the {\$\verb@*@} multiline
command, so I removed it.  Put in various {\verb@/m@} modifiers
instead.  I hope I got that right.

Jun 20, 2013.  Tweaked the l2hcrop alignment for 20 px fontsize a bit.

Jun 20, 2013.  Perl no longer accepts the {\verb@defined %@} construct.
So I removed the {\verb@defined@}.

Jun 20, 2013.  Removed the ugly bolding of index entries.

Jun 20, 2013.  Removed a problem with labels in equations.  Equations
with labels had errors in images.tex unless the label was on the same
line as part of the equation and terminated by a percent.  The problem
is that the label was removed and a blank line put in instead.  Blank
lines produce nasty errors inside equations.  I replaced the blank
line by a space.  Now errors only occur if the label is both on a line
by itself {\em{and}} not followed by a percent.  So if you always put
a percent behind labels in equations, or never put them on a line by
themselves, there is no problem.

Jun 20, 2013.  \latextohtml now supports xelatex with pdf images.
That allows international support.  Note that pdflatex does not
work correctly, even with pdf images.  For one, there is a problem
with {\verb@\resizebox@} in  {\verb@images.tex@}.

Jun 20, 2013.  \latextohtml now supports folders with spaces in their names,
(except during rebuilds).

Jun 20, 2013.  Simplified installation of \latextohtml.

Jun 20, 2013.  \latextohtml options can now be set in the index.tex file.

Jun 20, 2013.  Streamlined the process of setting font size and page color
by reading them out of index.css.

Jun 20, 2013. Added the required content type tag to the web pages
if latex2html produced none.  Made the default encoding UTF-8.

Jun 20, 2013.  makewebpages.bat now checks for constructs in the tex sources
that cause problems for \latextohtml.

Jun 20, 2013. Created a new shell l2h to process latex documents.
It includes hyphenation and web page clean up.

Jun 20, 2013. Problem: in the frames version, browsers would
unexpectedly open a new tab when clicking on certain links.  Reason:
The links referred to a target "main" that did not necessarily exist.
Solution: changed target into "\_parent".  Note: If you load the
contents in a full frame, instead of the side bar, a new tab will
still open.  That is unavoidable if the contents works in the side
bar.  And it can be considered a feature: you can keep a full size
contents always open in a separate tab.

Mar 5, 2018.  Perl version 5.22 no longer correctly evaluated a
{\verb@\G@} regexp in latex2html that removed comments.  The regexp
was rewritten.  Some no longer supported and deprecated constructs
were also fixed.

Problems whose fix will be posted later: Natbib's
{\verb@\citeindextrue@} did not work correctly and has been fixed.
Variables textheight and textwidth can now be set explicitly in
.latex2html-init.  CJK strings for plain latex or pdflatex sources got
junk appended at the end, like say {\verb@\end{CJK}@}.

\setlength{\parskip}{.0\baselineskip}

\newpage

\tableofcontents

\end{document}
