[l2h] Various bugs and workarounds for v99.1 under Linux

[Julius Smith]

Here is a report on a few bugs and work-arounds after shaking out a few things using l2h-99.1 on a new Linux system.  The only thing that's requiring time-consuming workarounds is the extremely fragile caption-matching logic (which makes figure numbers disappear when there is any math or font-setting commands in the caption).

-------------------------------------------------------

File redirection fails in &syswait() under Windows NT:

I never resolved failing file indirection via ">" as in
&syswait("... texexpand ... > file ") under Windows NT.  After
spending a few hours and several email messages on the problem, the
easiest workaround for me was to move all l2h work to my Linux system.
I know others have gotten l2h working under NT, but some other
reports indicate that headbutts are common.  Since l2h
leverages UNIX tools so heavily, it appears NT is a second-class
platform for l2h work.  Maybe Windows 2003 will run on top of
Linux, in which case I'll try again!  :-)

I will now report a few problems using l2h 99.1
under Red Hat Linux 6.0 (Intel hardware):

-------------------------------------------------------

Manual bug: "$ACCENT_IMAGES = 'large';" doesn't work:

       $ACCENT_IMAGES = 'large';

should be something more like

       $ACCENT_IMAGES = 'simplemathrm';

Also, why is this variable not defined by default?  It seems to me it
should be added to latex2html.config with a line or two of
explanation.

-------------------------------------------------------

Can't safely modify DESTDIR in latex2html.config:

I tried:

# -dir
#$DESTDIR = '';          # Put the result in this directory 
$DESTDIR = 'HTML';

However, this breaks section linking when compiling the l2h manual.
Files like Ointernals.pl are written to manual/, while files like
node1.html are written to HTML.  l2h then later complains that it
can't find Ointernals.pl, etc.

-------------------------------------------------------

Pattern-matching failures in figure \caption s:

The first document below converts to HTML correctly, while the
following three do not.  The failure in each case is that the figure
number is lost in the caption.

\documentclass{article}
\begin{document}
\begin{figure}
	The figure.
	\caption{A winning caption.}
\end{figure}
\end{document}

\documentclass{article}
\begin{document}
\begin{figure}
	The figure.
	\caption{A losing caption with $math\; in\; it$.}
\end{figure}
\end{document}

\documentclass{article}
\begin{document}
\begin{figure}
	The figure.
	\caption{A losing caption with a discretionary hy\-phen in it.}
\end{figure}
\end{document}

\documentclass{article}
\begin{document}
\begin{figure}
        The figure.
	\caption{\small A caption with a font size set in it.}
\end{figure}
\end{document}

I don't understand why caption recognition for associating figure
numbers is so fragile.  Perhaps there's a good reason for this, but
perhaps there's another possible approach to this function?  Missing
figure numbers is a recurring source of headbutts for a lot of people.
It is very common to want to include a little math or change something
about the font in a figure caption.

-------------------------------------------------------
Manual bug:

The figure caption recognition for figure numberse should be at least
documented.

I didn't obtain simple failing cases as above, but I also had
figure-number failures with captions that started with a newline or a
quoted newline and which were passed in as a macro argument. For
example,

       \doFigure{theLabel}{theFigure.eps}{%
The caption.}

or
       
       \doFigure{theLabel}{theFigure.eps}{
The very long caption.}
       
These failures would not occur in the small test example I constructed
above.

-------------------------------------------------------
Cannot define a figure macro before starting the document:

Below, the first form works and the second does not.  It fails in a
complicated way as if the macro definition is being processed as an
actual invocation with literal arguments #1, #2, and #3.

\documentclass{article}
\newcommand{\doFigure}[3]{
	\begin{figure}
	        #2
		\caption{#3}
		\label{#1}
	\end{figure}
}
\begin{document}
\doFigure{theLabel}{theFigure}{theCaption}
\end{document}


\documentclass{article}
\begin{document}
\newcommand{\doFigure}[3]{
	\begin{figure}
	        #2
		\caption{#3}
		\label{#1}
	\end{figure}
}
\doFigure{theLabel}{theFigure}{theCaption}
\end{document}

-------------------------------------------------------

Last but not least, I should add that I'm getting great results after
finding the needed workarounds.  L2h is truly an awesome perl script!  

     "Latex2html is so improbable, that if it did not exist, the
     possibility would not be worth discussing."

---------------------------------------------------------
Julius Smith <jos@w3k.org>