"Fossies" - the Fresh Open Source Software Archive

Member "latex2html-2021.2/docs/appendix.tex" (1 Jul 2021, 61375 Bytes) of package /linux/www/latex2html-2021.2.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 \section{Known Problems}
    2 \index{problems} \index{bugs}
    3 Here are some of the problems of the current version:
    4 \begin{htmllist}
    5 \htmlitemmark{PurpleBall}
    6 \item [Correctness and Efficiency\index{efficiency}]
    7 The translator cannot be guaranteed to perform as expected.
    8 Several aspects of the implementation need
    9 optimization and improvement.
   11 \item [Memory and Time Usage]
   12 Apart from possible bugs the translator 
   13 may place heavy demands on your resources.
   14 The memory that \latextohtml\ needs for translation ranges between
   15 8 - 10 Megabytes for simple documents and goes soon beyond
   16 30 Megabytes for more complicated documents.
   17 This depends upon the length of the document sections and the amount
   18 of self-defined commands.
   20 A resort for machines with small memory could be to choose
   21 document segmentation (Section \ref{Segmentation}).
   23 Memory usage also heavily depends on your Perl version.
   24 Perl4.036, Perl5.000, Perl5.001, and Perl5.002 are deprecated for
   25 the use with \latextohtml, some things really take too much memory
   26 with these versions.
   28 Large document sections also need notable more time to translate
   29 than smaller ones.
   30 The translation time mainly is determined by the
   31 number of figures, math equations, or tables.
   32 With an amount of more than a dozen, say, images to generate,
   33 \latextohtml\ will almost need all the time to work on the image
   34 conversion.
   35 This behaviour will vanish when you configure \latextohtml\ to
   36 work in EPS mode, available with the 96.2 release.
   38 \latextohtml\ usually finishes its job for an average 60 page
   39 document with a handful figures within several minutes.
   40 However, a 250 page manual with a large number of cross-references
   41 was reported to take on a Sparc4 the amount of 21 hours and 380
   42 Megabytes of memory.
   46 \item [Unrecognized Commands and Environments \index{unrecognized commands}]
   47 Unrecognized commands are ignored and any arguments are left in the
   48 text. Unrecognized environments are passed to LaTeX  and the result is
   49 included in the document as one or more inlined images.
   51 \item [Cross-references\index{cross-references}]
   52 References in environments that are passed to LaTeX  for processing
   53 (e.g. a \texttt{cite}, or a \texttt{ref} command), are not processed
   54 correctly.
   55 \texttt{label} commands are handled correctly.
   57 \item[Order-Sensitive Commands]
   58 Commands which affect global parameters during the translation,
   59 and are sensitive to the order in which they are processed may
   60 not be handled correctly. In particular, counter manipulation
   61 (e.g. \texttt{newcounter, setcounter, stepcounter}, etc) 
   62 commands may cause problems.
   64 \item [Index\index{index}]
   65 The translator generates its own index by saving the arguments  of 
   66 the \texttt{index} command. The contents of the \texttt{theindex}
   67 environment are ignored.
   69 \item[New Definitions\index{new definitions}]
   70 New definitions (\texttt{newcommand}, \texttt{newenvironment}, 
   71 \texttt{newtheorem} and \texttt{def}),
   72 will not work as expected if they are defined more than once.
   73 Only the last definition will be used throughout the document.
   75 \item [Scope of declarations and environments]
   76 If the scope of a declaration or environment crosses section
   77 boundaries, then the output may not be as expected, because each
   78 section is processed independently.
   80 \item [Math mode font size changes]  Math mode font changes
   81 made outside the math mode are not honored.  Thus the two equations
   82 in
   83 \begin{verbatim}
   84 $a_b$ and {\LARGE $a_b$}
   85 \end{verbatim}
   86 would come out looking the same.  The trick is to write
   87 \begin{verbatim}
   88 $a_b and $\mbox{\LARGE $a_b$}$.
   89 \end{verbatim}
   91 \end{htmllist}
   92 % do not remove this magic marker vv
   93 %%% START FAQ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   94 \section{Troubleshooting}
   95 \index{debugging} \index{problems} \index{fixes}
   96 Here are some curable symptoms:
   98 \begin{htmllist}
   99 \htmlitemmark{BlueBall}
  100 \item [Cannot run any of the Perl programs]
  101 If your Perl installation is such that Perl programs are not allowed 
  102 to run as shell scripts you may be unable to run  \fn{latex2html}, \fn{texexpand} \fn{pstogif}
  103 and  \fn{install-test}. In this case change the first line in each of these
  104 programs from
  105 \begin{verbatim}
  106 #!/usr/local/bin/perl
  107 \end{verbatim}
  109 \emph{to}
  111 \begin{verbatim}
  112 : # *-*-perl-*-*
  113     eval 'exec perl -S  $0 "$@"'
  114     if $running_under_some_shell; 
  115 \end{verbatim}
  118 \item [Cannot run any of the Perl programs \#2]\hfill\\
  119 They prompt sth. like \fn{Command not found}.
  121 Check the first line of the program.
  122 The path you see there must point to Perl!
  123 If you see eg. \verb|#!/usr/local/bin/perl|, type
  124 \begin{verbatim}
  125    which perl
  126 \end{verbatim}
  127 If they differ, adapt the first lines of any Perl script (currently
  128 \fn{pstoimg}, \fn{texexpand}, \fn{makemap}, and \fn{latex2html}),
  129 or talk to your system administrator to add a link to perl in
  130 \fn{/usr/local/bin} (this is recommended).
  133 \item [Cannot run \fn{latex2html}]\hfill\\
  134 \fn{latex2html} prompts sth. like \fn{di: Command not found} or
  135 \fn{di: not found}.
  137 You must have Perl installed to use \latextohtml, you can't run it
  138 by your shell.
  141 \item [\fn{latex2html} exits with one of these messages:]\hfill
  143 \begin{enumerate}
  144 \item \verb/no DBM on this machine.../,
  145 \item \verb/AnyDBM_File.pm did not return a true value.../,
  146 \item \verb/Can't locate AnyDBM_File.pm in @INC.../
  147 \end{enumerate}
  149 Perl is not installed properly.
  150 In particular, these errors occur when Perl binaries are installed
  151 without the Perl library, or when the Perl binaries or library
  152 is moved to another location after installation.
  153 The resort is to re-install Perl by running its configure script,
  154 invoking the Makefile, etc., or to get a complete Perl distribution
  155 with includes the Perl library.
  159 \item [It just stops] Check the style
  160 files that you are using. It is likely that you are using
  161 a style file which contains raw TeX commands. In such a case
  162 start \latextohtml{} with the option \texttt{-dont\_include \Meta{style file
  163 name}}. Alternatively, add the name of the style to the variable 
  164 \texttt{DONT\_INCLUDE} in your
  165 \fn{HOME/.latex2html-init} file. If you don't have such a file then
  166 create one and add the lines:
  167 \begin{verbatim}
  168 $DONT_INCLUDE = "$DONT_INCLUDE" . ":<style file name>";
  169 1;      # This must be the last line
  170 \end{verbatim}
  172 Another reason why \latextohtml{} might stop is that the LaTeX source
  173 file itself contains raw TeX commands. In this case you may 
  174 put such commands inside a 
  175 \hyperref{\texttt{latexonly}}{\texttt{latexonly (see Section }}{)}{sec:latexonly}
  176 environment.
  178 \item [Perl cannot parse the \fn{latex2html} script]
  179 Update your Perl to patch level 36. You can check which version of
  180 Perl you are using by invoking Perl with the \texttt{-v} option.
  181 Earlier versions of Perl than that shown above
  182 have caused problems due
  183 to tighter control over syntax.
  185 \item [It crashes (dumps core) as soon as it starts \label{perl}]
  186 Update your Perl 4 to patch level 36 or later (Perl 5).
  188 You can check which version of
  189 Perl you are using by invoking Perl with the \texttt{-v} option.
  192 While you wait for your technical support people to upgrade Perl
  193 you could try invoking Perl from within \latextohtml{} with 
  194 the \texttt{-d} (debug) option. Then, when \latextohtml{} starts, it will
  195 immediately fall into the Perl debugger. To continue just press 
  196 \texttt{c <CR>}.
  198 \item [\fn{dvips} complains about incorrect arguments \label{dvips}]
  199 Please use a version which supports the command line options \texttt{-M -S,
  200 -o and -i}. ``Recent'' versions at least after 5.516 do
  201 support them.
  203 \item [It gives an \texttt{Out of memory} message and dies] 
  204 If you are using version \latextohtml{} 0.7 or later try splitting your 
  205 source file into more than one files using the \LaTeX\ 
  206 commands \texttt{input} or \texttt{include}. 
  207 Also, use the \texttt{-no\_images} option.
  209 As a last resort you may consider increasing the virtual memory
  210 (swap space) of your machine. As an indication 
  211 of what you might be able to do on your machine,
  212 a very long book (about 1000 printed pages) required about 
  213 24MB of RAM and over 150MB of swap space to convert on a local Sun Sparc ELC
  214 running SunOS 4.1.3.
  216 \item [It gives ``dbm'' related error messages]
  217 \latextohtml{} 0.7 and later requires the
  218 Unix DataBase Management system (DBM or NDBM) in order to run.
  219 This is usually part of each Unix operating system but if you 
  220 don't have it then you may need to get it.
  222 \item [The \texttt{verb"ABC"} command doesn't work]
  223 This is a nasty bug. Please use any characters other than quotes eg
  224 \texttt{verb+ABC+}
  226 \item [Cannot get the ``tilde'' (\~{}) to show]
  227 The trick here is to use the command \verb|\~{}|. 
  229 Alternatively it is possible to use something like \\
  230 \begin{verbatim}
  231 \htmladdnormallink{mylink}%
  232   {\begin{rawhtml}http://host/~me/path/file.html\end{rawhtml}}
  233 \end{verbatim}
  235 or
  237 \verb|\htmladdnormallink{mylink}{http://host/\%7Eme/path/file.html}| 
  239 \textbf{Warning:} Some browsers may not be able to interpret the \verb|%7E|
  240 as a ``tilde'' character.
  242 \item [Macro definitions don't work correctly]
  243 As mentioned in other places plain TeX definitions cannot be
  244 converted.
  245 But you may also have problems even when using LaTeX definitions
  246 (with \texttt{newcommand} and \texttt{newenvironment}) if such definitions
  247 make use of {\it sectioning or verbatim} commands. These are 
  248 handled in a special way by \latextohtml{} and cannot be used in
  249 macro definitions. 
  251 In general the macro handling mechanism is inefficient and very
  252 fragile. Avoid using macros if possible.
  254 \item [\texttt{input} commands]
  255 There is a bug in the expansion of \texttt{input} commands which causes a problem
  256 when more than one \texttt{input} command appear on the same line.
  257 There is no quick fix other than suggesting that you 
  258 insert a newline after \texttt{input} commands in the source .tex files.
  260 \item [\texttt{input} commands in verbatim environments]
  261 These cause problems. There is no fix yet.
  263 \item [Optional arguments in description environments]
  264 If you have optional arguments for the \texttt{item} command in 
  265 a description environment containing nested ``]'' characters then 
  266 these may not show up correctly. To avoid the problem enclose them
  267 in \{\}'s eg \verb+\item[{[nested [angle [brackets] are ok]]}]+
  269 \item [LaTeX2HTML behaves differently even when you run it on the
  270 same file]
  272 If you notice any strange side-effects from previous runs of
  273 \latextohtml{} try using the option \texttt{-no\_reuse} and choose 
  274 \texttt{(d) } when prompted. This will 
  275 clear any intermediate files generated during previous runs.
  276 Note that this option will disable to image reuse mechanism.
  278 \item [Cannot convert postscript images which are included
  279 in the LaTeX file] \hfill \\
  280 It is likely that the macros you are using for including postscript
  281 files (e.g. \texttt{epsffile}) are not understood by \latextohtml.
  282 To avoid this problem enclose them in an environment which will
  283 be passed to LaTeX anyway e.g.
  284 \begin{verbatim}
  285 \begin{figure}
  286 \epsffile{<postscript file name>}
  287 \end{figure}
  288 \end{verbatim}
  290 Another reason why this might happen is that your shell 
  291 environment variable 
  292 \texttt{TEXINPUTS} is undefined. This is not always 
  293 fatal but if you have problems you can use full
  294 pathnames for included postscript files (even when the postscript
  295 files are in the same directory as the LaTeX source file).
  296 Alternatively try setting TEXINPUTS to ".::". 
  297 With some TeX and LaTeX installations setting TEXINPUTS to 
  298 ".::" may cause problems in the normal operation of LaTeX.
  299 If you get errors such as LaTeX complaining that it can no longer find
  300 any style files then you must set TEXINPUTS to 
  301 \verb|"<path to your LaTeX installation>:."|
  302 if you want to use both LaTeX and LaTeX2HTML.
  304 \item [Some of the inlined images are in the wrong places]
  305 This happens when any one of the inlined images is more than a page
  306 (paper page) long. This is sometimes the case with very large tables
  307 or large postscript images. In this case you can try specifying 
  308 a larger paper size (eg ``a3'', ``a2'' or even ``a0'') instead of
  309 the default (``a4'') using the LaTeX2HTML variable \fn{PAPERSIZE} 
  310 in the file \fn{latex2html.config}.
  312 Another reason why this may happen is that by default the \fn{dvips} program
  313 reverses the postscript pages it generates. If your \fn{dvips
  314 program}
  315 behaves in this way try changing the line
  316 \verb|$DVIPS = "dvips";| 
  318 to
  320 \verb|$DVIPS = "dvips -r0";|
  322 in the file \fn{latex2html.config}.
  324 \item [\textbf{Unacceptable quality of converted images}]
  325 Try changing the size of the image 
  326 (\hyperref{See image conversion}{See Section }{}{imgcon}).
  328 \item [The bibliographic references are missing]
  329 Run \texttt{latex} and then \texttt{bibtex} on the original source file in
  330 order to generate a \texttt{bbl} file. \latextohtml{} requires a \texttt{bbl}
  331 in order to generate the references.
  333 \item [The labels of figures, tables or equations are wrong]
  334 This can happen if you have used any figures, tables, equations or
  335 any counters inside conditional text i.e. in a \texttt{latexonly} 
  336 or a \texttt{htmlonly} environment. 
  338 \item [Problems after changing the configuration files]
  339 Please make sure that the last line in the configuration files 
  340 (ie \fn{.latex2html-init} and \fn{latex2html.congif}) is:
  341 \begin{verbatim}
  342 1;      # This is the last line
  343 \end{verbatim}
  344 This is a Perl quirk...
  346 \item [Problems when producing the DVI version \label{htmlsty}]
  347 If you are using any of the new LaTeX commands which are defined in 
  348 the \fn{html.sty} file make sure that 
  349 \fn{html.sty} file is included e.g. as one of the optional arguments to the 
  350 \texttt{documentstyle} command.
  352 Of course you also have to make sure that LaTeX knows where the html.sty
  353 file is, either by putting it in the same place as the other style files on
  354 your system, or by changing your TEXINPUTS shell environment variable\footnote{
  355 If don't know how to do either of these things, copy (or link) html.sty 
  356 to the directory of your LaTeX document...}.
  358 \item [Some of the fonts are translated incorrectly]
  359 There is a fault in way the LaTeX scoping rules have been 
  360 interpreted in \latextohtml. Consider this:
  361 \begin{verbatim}
  362 \ttfamily fixed-width font.
  363 \begin{something}
  364 nothing here
  365 \end{something}
  366 default font.
  367 \end{verbatim}
  368 When processed by \LaTeX, the effect of the \texttt{tt} command is
  369 delimited
  370 by the beginning of the environment ``something'' so that ``default font'' will
  371 appear in the default font. But \latextohtml{} will not recognize
  372 ``something'' as a delimiter and ``default font'' will appear in the
  373 wrong
  374 font. 
  376 To avoid this problem until it is fixed you may delimit the scope of
  377 some
  378 commands explicitly using \verb|{}|'s i.e.
  379 \begin{verbatim}
  380 \texttt{fixed-width font}.
  381 \begin{something}
  382 nothing here
  383 \end{something}
  384 default font.
  385 \end{verbatim}
  387 \item [Using \fn{Ghostscript 3.X} you can no
  388 longer generate inlined images for equations]
  389 If you have a version of \latextohtml{} later than 0.6.1, go to the
  390 \latextohtml{} directory and run \fn{install-test} again. This should 
  391 fix it.
  393 With earlier versions of \latextohtml{} you can fix it by 
  394 replacing the file \fn{pstoppm.ps} in the 
  395 \latextohtml{} directory with a newer one that accompanies 
  396 \fn{Ghostscript 3.X}. Alterhatively you can avoid using {\fn
  397 pstoppm.ps} 
  398 by changing the way \texttt{GS} is invoked in the file \fn{pstogif},
  399 using something like \\
  400 \verb/open (GS, "|$GS -q -sDEVICE=ppmraw  -sOutputFile=$base.ppm $base.ps");/
  402 \item [Cannot get it to generate inlined images]
  403 Try a small test file e.g.
  404 \begin{verbatim}
  405 % image-test.tex
  406 \documentstyle{article}
  407 \begin{document}
  408 Some text followed by \fbox{some more text in a box}.
  409 \end{document}
  410 \end{verbatim}
  412 You should see something like:
  413 \begin{verbatim}
  414 This is LaTeX2HTML Version  (Wed Dec 1 1993) by Nikos Drakos, 
  415 Computer Based Learning Unit, University of Leeds.
  417 OPENING /usr/cblelca/nikos/scripts/tex2html/tests/image-test.tex 
  419 Reading ....
  420 Translating ...0/1.....1/1......
  421 Generating images using latex ...
  422 This is TeX, C Version 3.14t3
  423 12222_images.tex
  424 LaTeX Version 2.09 <7 Dec 1989>
  427 Generating postscript images using dvips ...
  428 This is dvips 5.521 Copyright 1986, 1993 Radical Eye Software
  429 \end{verbatim}
  430 \begin{verbatim}
  431 ' TeX output 1993.12.03:1050' -> 12222_image
  432 (-> 12222_image001) <tex.pro>[1] 
  433 Initializing... done.
  434 Ghostscript 2.6.1 (5/28/93)
  435 Copyright (C) 1990-1993 Aladdin Enterprises, Menlo Park, CA.
  436   All rights reserved.
  437 Ghostscript comes with NO WARRANTY: see the file COPYING for details.
  438 GS>GS>Writing 12222_image001.ppm
  439 GS>pnmcrop: cropping 119 rows off the top
  440 pnmcrop: cropping 961 rows off the bottom
  441 pnmcrop: cropping 208 cols off the left
  442 pnmcrop: cropping 484 cols off the right
  444 Doing section links .....
  445 Done.
  446 \end{verbatim}
  449 If there is a problem somewhere during the conversion from postscript
  450 to GIF you can try to do it manually so that you can find out where
  451 the problem is. Here is one way to do it (Please use the \fn{pstoppm3.ps}
  452 file instead of \fn{pstoppm.ps} if your version of ghostscript is
  453 later than 3.0):
  455 \begin{verbatim}
  456 cblelca% latex image-test.tex
  457 This is TeX, C Version 3.14t3
  458 (image-test.tex
  459 LaTeX Version 2.09 <7 Dec 1989>
  460 (/usr/TeX/tex.lib/inputs//paper.sty
  461 Document Style `paper' <28 Nov 89>.
  462 (/usr/TeX/tex.lib/inputs//pap11.sty) (/usr/TeX/tex.lib/inputs/\-doublespace.sty)
  463 (/usr/TeX/tex.lib/inputs//smaller.sty)) (/usr/TeX/tex.lib/inputs\-/psfig.sty
  464 psfig/tex 1.9
  465 )
  466 No file image-test.aux.
  467 [1] (image-test.aux) )
  468 Output written on image-test.dvi (1 page, 652 bytes).
  469 Transcript written on image-test.log.
  470 cblelca% dvips -o image-test.ps image-test.dvi
  471 \end{verbatim}
  472 \begin{verbatim}
  473 This is dvips 5.519 Copyright 1986, 1993 Radical Eye Software
  474 ' TeX output 1993.11.12:1412' -> image-test.ps
  475 <tex.pro>. [1] 
  476 cblelca% gs -dNODISPLAY pstoppm.ps
  477 Initializing... done.
  478 Ghostscript 2.6.1 (5/28/93)
  479 Copyright (C) 1990-1993 Aladdin Enterprises, Menlo Park, CA.
  480   All rights reserved.
  481 Ghostscript comes with NO WARRANTY: see the file COPYING for details.
  482 GS>(image-test) ppm1run 
  483 Writing image-test.ppm
  484 GS>quit
  485 cblelca% pnmcrop image-test.ppm >image-test.crop.ppm
  486 pnmcrop: cropping 61 rows off the top
  487 pnmcrop: cropping 110 rows off the bottom
  488 pnmcrop: cropping 72 cols off the left
  489 pnmcrop: cropping 72 cols off the right
  490 cblelca% ppmtogif image-test.crop.ppm >image-test.gif
  491 \end{verbatim}
  493 \item [STILL cannot get it to generate inlined images for equations
  494 etc.]
  495 If you have no problems with the \fn{image-test.tex} file but you
  496 still cannot convert the images in some of your files 
  497 have a look in the directory of the generated
  498 HTML files for two files \fn{images.tex} and \fn{images.log}. Do you notice
  499 anything unusual in them? Copy \fn{images.tex} in the directory 
  500 of your original \LaTeX file and run \fn{latex} on \fn{images.tex}.
  501 Can you see any errors in \fn{images.log}? If yes can you fix
  502 \fn{images.tex} to get rid of the errors? After fixing {\fn
  503 images.tex}
  504 you can put it back in the directory of HTML files created by
  505 \latextohtml{} and run \latextohtml{} on the original document 
  506 using the option \texttt{-images\_only}. 
  508 If you get into a mess try running \latextohtml{} with the options
  509 \texttt{-no\_reuse} and \texttt{-no\_images} eg
  510 \begin{verbatim}
  511 cblipca% latex2html -no_reuse -no_images test.tex
  512 This is LaTeX2HTML Version 95 (Tue Nov 29 1994) by Nikos Drakos, 
  513 Computer Based Learning Unit, University of Leeds.
  515 OPENING /tmp_mnt/home/cblelca/nikos/tmp/test.tex 
  516 Cannot create directory /usr/cblelca/nikos/tmp/test: File exists
  517 (r) Reuse the images in the old directory OR
  518 (d) *** DELETE *** /usr/cblelca/nikos/tmp/test AND ITS CONTENTS OR
  519 (q) Quit ?
  520 :d
  522 Reading ...
  523 Processing macros ....+.
  524 Reading test.aux ......................
  525 Translating ...0/1........1/1.....
  526 Writing image file ...
  528 Doing section links .....
  530 *********** WARNINGS ***********
  532 If you are having problems displaying the correct images with Mosaic,
  533 try selecting "Flush Image Cache" from "Options" in the menu-bar 
  534 and then reload the HTML file.
  536 Done.
  537 \end{verbatim}
  539 Then try to have a look 
  540 in the file  \fn{images.tex} (as described earlier) and perhaps fix it.
  541 Once you are happy that \fn{images.tex} is OK run \latextohtml{}
  542 again with the option \texttt{-images\_only}.
  544 The options \texttt{no\_reuse, no\_images} and \texttt{images\_only}
  545 are available with \latextohtml{} version 0.7 or later.
  547 Some problems in displaying the correct inlined images,
  548 may be due to the image caching mechanisms of your browser.
  549 With some browsers a simple ``Reload Current Document'' will be enough
  550 to refresh the images but with others (eg Mosaic) you may need
  551 to request for the cache to be refreshed. With Mosaic try 
  552 selecting "Flush Image Cache" from "Options" in the menu-bar 
  553 and then reload the HTML file.
  556 \item [It cannot do slides, memos, etc, ...] 
  557 If you use \texttt{slitex} you can go a long way just by replacing 
  558 the \texttt{slides} argument of the \texttt{documentstyle} command with 
  559 something like \texttt{article} just before using \latextohtml.
  560 One problem may be that all your slides will end up in the  same HTML 
  561 file.
  562 If you use \fn{lslide.sty} you may get much better results.
  563 \end{htmllist}
  565 %%% END FAQ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  566 % do not remove this magic marker ^^
  568 \section{Support and More Information}
  570 A \htmladdnormallink{\latextohtml{} mailing list}{mailto:latex2html-request@tug.org} has been set up at the \TeX\ User Group. The
  571 \htmladdnormallinkfoot{\latextohtml{} mailing list
  572 archive}{http://www.tug.org/mailman/listinfo/latex2html/} is
  573 available.
  575 To join send a message to: \\
  576 \texttt{latex2html-request@tug.org}  \\
  577 with the contents \\
  578 \texttt{subscribe}
  580 To be removed from the list send a message to: \\
  581 \texttt{latex2html-request@tug.org}  \\
  582 with the contents \\
  583 \texttt{unsubscribe}.
  585 \section{General License Agreement and Lack of Warranty}
  586 This software is distributed in the hope that it will be useful
  587 but \textbf{without any warranty}. The author(s) do not accept responsibility 
  588 to anyone for the consequences of using it or for whether it serves 
  589 any particular purpose or works at all. No warranty is made about 
  590 the software or its performance. 
  592 Use and copying of this software and the preparation of derivative
  593 works based on this software are permitted, so long as the following
  594 conditions are met:
  595 \begin{itemize}
  596 \item The copyright notice and this entire notice are included intact
  597 and prominently carried on all copies and supporting documentation.
  598 \item No fees or compensation are charged for use, copies, or
  599 access to this software. You may charge a nominal
  600 distribution fee for the physical act of transferring a
  601 copy, but you may not charge for the program itself. 
  602 \item If you modify this software, you must cause the modified
  603 file(s) to carry prominent notices (a Change Log)
  604 describing the changes, who made the changes, and the date
  605 of those changes.
  606 \item  Any work distributed or published that in whole or in part
  607 contains or is a derivative of this software or any part 
  608 thereof is subject to the terms of this agreement. The 
  609 aggregation of another unrelated program with this software
  610 or its derivative on a volume of storage or distribution
  611 medium does not bring the other program under the scope
  612 of these terms.
  613 \end{itemize}
  615 This software is made available \textbf{as is}, and is distributed without 
  616 warranty of any kind, either expressed or implied.
  617 In no event will the author(s) or their institutions be liable to you
  618 for damages, including lost profits, lost monies, or other special,
  619 incidental or consequential damages arising out of or in connection
  620 with the use or inability to use (including but not limited to loss of
  621 data or data being rendered inaccurate or losses sustained by third
  622 parties or a failure of the program to operate as documented) the 
  623 program, even if you have been advised of the possibility of such
  624 damages, or for any claim by any other party, whether in an action of
  625 contract, negligence, or other tortious action.
  627 \index{copyright}
  628 The \latextohtml{} translator is written by Nikos Drakos, 
  629 Computer Based Learning Unit,  University of Leeds,  Leeds,  LS2 9JT.
  630 Copyright \copyright 1993, 1994, 1995. All rights reserved.
  632 \section{Credits}
  633 Several people have contributed suggestions, ideas, solutions, support
  634 and encouragement. Some of these are Roderick Williams, Ana Maria
  635 Paiva, Jamil Sawar and Andrew Cole here at the Computer Based Learning Unit.
  637 The idea of splitting \LaTeX\  files
  638 into more than one components linked with hyperlinks was first
  639 implemented in Perl by Toni Lantunen at CERN.
  640 Thanks to Robert Cailliau \Email{cailliau@cernnext.cern.ch}
  641 of the WorldWide Web Project also at CERN 
  642 for giving me access to the source code and documentation (although no
  643 part of the original design or the actual code has been used).
  645 Robert S. Thau \Email{rst@edu.mit.ai} has contributed the new version of
  646 \fn{texexpand}. Also, in order to translate the \emph{document 
  647 from hell} (!!!) he has extended the translator to handle \texttt{def}
  648 commands, nested math-mode commands, and has fixed several bugs.
  650 The \fn{pstogif} script 
  651 uses the \fn{pstoppm.ps} postscript program originally written by
  652 Phillip Conrad (Perfect Byte, Inc.) and modified by L. Peter Deutsch 
  653 (Aladdin Enterprises).
  655 The idea of using existing symbolic labels to provide cross-references
  656 between documents was first conceived during discussions with 
  657 Roderick Williams \Email{rodw@cbl.leeds.ac.uk}.
  658 Eric Carroll \Email{eric@ca.utoronto.utcc.enfm} suggested providing
  659 a command like \texttt{hyperref}. Franz Vojik
  660 \Email{vojik@de.tu-muenchen.informatik}
  661 provided the basic mechanism for handling foreign accents.
  662 The \texttt{-auto\_navigation} option was based on an idea by
  663 Todd \texttt{<little@com.dec.enet.nuts2u>}.
  664 Axel Belinfante \texttt{<Axel.Belinfante@cs.utwente.nl>} provided the
  665 code in the \fn{makeidx.perl} file as well as numerous suggestions
  666 and bug reports. 
  668 Verena Umar \Email{verena@edu.vanderbilt.cas.compsci} 
  669 (Computer Science
  670 Education Project) has been a very
  671 patient tester of some early versions of \latextohtml{}
  672 and many of the current features are a result of her 
  673 suggestions. 
  675 Thanks to (thanks to Ian Foster 
  676 \Email{itf@mcs.anl.gov} and Bob Olson \Email{olson@mcs.anl.gov}) at the
  677 Argonne National Labs for setting up the
  678 \latextohtml{} mailing list.
  680 Special credit is due Marcus Hennecke \Email{marcush@crc.ricoh.com}
  681 for his many extensive revisions, Mark Noworolski
  682 \Email{jmn@eecs.berkeley.edu} for coordinating V 95.3, 
  683 Sidik Isani \Email{isani@cfht.hawaii.edu}, for his improvement
  684 in GIF quality, and to Herb Swan \Email{dprhws@edp.Arco.com} for
  685 coordinating V 96.1 of \latextohtml.
  687 Many others, too many to mention, 
  688 have contributed bug reports, fixes, and other suggestions. Keep them coming!
  691 \section{Changes from Previous Versions}
  692 The previous versions of the
  693 translator and some patches
  694 are available. A detailed list of changes
  695 which includes full credits to all who have contributed 
  696 bug fixes or other code is also available with the
  697 \latextohtml{} distribution in the file \fn{Changes}.
  699 \subsection{Changes upto v96}
  700 \begin{htmllist}
  701 \htmlitemmark{GreenBall}
  702 \item[Tables and math support for HTML 3.0]
  703 Tables can now be specified in HTML, without having to generate a
  704 GIF image.  Code is also available for HTML 3.0 equations, but it is not
  705 currently turned on, since no browser can handle it (yet!)
  706 (Courtesy of Marcus Hennecke \Email{marcush@crc.ricoh.com})
  708 \item[Font generation at screen resolutions]
  709 The quality of equation bitmaps is greatly improved by enabling the
  710 \$PK\_GENERATION configuration variable.  When this is done
  711 METAFont will be invoked through \texttt{dvips} to generate fonts
  712 more suitable to screen viewing.  Ideally, this should be done
  713 by setting the \texttt{mode} switch to \texttt{dvips}, but unfortunately
  714 not all version of \texttt{dvips} support this option.  For those
  715 that don't, a \fn{.dvipsrc} file is supplied with this distribution.
  716 Sidik Isani (\Email{isani@cfht.hawaii.edu}) provided this 
  717 change.
  719 \item[Improved support for active image maps]
  720 Both server and client-side maps are supported.  Image maps can
  721 either be inline or external.  External maps can be associated
  722 with a thumbnail image.  A separate script \texttt{makemap} helps
  723 resolve external URLs in image maps.  (Herb Swan \Email{dprhws@edp.Arco.com})
  725 \item[Improved image sharing and recycling]
  726 The older version of image recycling often caused images to
  727 overwrite each other due to confusion in the bookkeeping.
  728 This has been fixed.  It is also no longer necessary to keep
  729 generating the same image which is being used repeatedly in a
  730 document.  Furthermore, images with thumbnails can now be
  731 recycled, as well as active image maps.  Only images of the
  732 correct size are recycled.  (Herb Swan)
  734 \item[Document segmentation]
  735 Large documents can now be divided into independently processed
  736 segments.  Additional command line switches provide intersegment
  737 navigation information, while automatically generated Perl
  738 files pass symbolic references and counter information
  739 between segments.  (Herb Swan, assisted by Michel Goossens
  740 \Email{Michel.Goossens@cern.ch})
  742 \item[Command parsing made more like \LaTeX's]
  743 Constructs like \verb|\hello2| are now treated as macro
  744 \texttt{hello} followed by argument `2', rather than as
  745 macro \texttt{hello2}.  Added \makeatletter and \makeatother
  746 commands.  (Marcus Hennecke)
  748 \item[Graceful termination upon interrupt]
  749 When \latextohtml\ is interrupted by a termination signal, all
  750 child tasks are also terminated.  This provides a more orderly
  751 shutdown than that offered by previous versions.  (Herb Swan)
  753 \item[Support for textual font size changes]
  754 HTML 2.1 support is now available fo ISO 10646
  755 \htmladdnormallink{Unicode}{ftp://dkuug.dk/i18n/ISO_10646}
  756 character sets by specifying \fn{-html\_version 2.1}.
  757 HTML 3.0 support is provided for textual font size changes
  758 (like \verb|<SMALL>|), used in conjunction wich a generated
  759 optional style sheet.  (Marcus Hennecke)
  761 \item[More inline math generated in \texttt{HTML}]  Small inline
  762 equations which can be typeset in \texttt{HTML} \textbf{are} typeset
  763 in \texttt{HTML}.  This further reduces the nuber of GIF files
  764 that need to be generated.
  766 \item[Hypertext references can now be external]  The commands
  767 \texttt{htmlref} and \texttt{hyperref} now accept labels defined
  768 in an external document if the internal reference is not found.
  769 (Herb Swan)
  771 \item[Additional style files are now available] These were
  772 provided by Herb Swan:
  773 \begin{htmllist}
  774 \htmlitemmark{YellowBall}
  775 \item[htmllist] Defines a fancier list environment\html{, such as this}.
  776 (It is the same as the \texttt{description} environment in the paper version.)
  778 \item[heqn] Redefines the \texttt{equation} environment so that
  779 equation numbers are handled in \texttt{HTML}.  This causes 
  780 equations in this environment to be recyclable.  It also causes
  781 equation arrays to be recyclable if their equation numbers do not
  782 change from the previous run.
  783 \item[floatfig] Provides support for this environment by making it
  784 look like an ordinary figure in the electronic version.
  785 \item[wrapfig] (Same comment as for \texttt{floatfig}).
  786 \item[graphics] Defines elements of the standard \LaTeX 2e 
  787 \texttt{graphics} package.
  788 \end{htmllist}
  790 \item[More support for \LaTeXe] Provided support for the
  791 \texttt{ensuremath} command.  The last \emph{option} to the \texttt{babel}
  792 package is interpreted as the \latextohtml{} language style file to load.
  793 User-defined commands and environments can now have an optional
  794 argument.  Stubs have been provided for \texttt{enlargethispage}
  795 and \texttt{suppressfloats}.  \LaTeXe packages \texttt{alltt,
  796 graphics, graphicx, color} and \texttt{epsfig} were
  797 provided.  This manual itself was transformed into standard
  798 \LaTeXe.  (Herb Swan and Michel Goossens)
  800 \item[Orientation manipulation for figures] The \texttt{flip=}
  801 option of \texttt{htmlimage} causes the program \texttt{pnmflip} to
  802 be called prior to the generation of the GIF file.  This allows
  803 the electronic version of the image to be oriented differently
  804 than the paper version.  (Herb Swan)
  806 \item[Better treatment of null images]  If for some reason an
  807 image produced a null GIF file, then no reference is made to that
  808 file and the program proceeds gracefully.  Furthermore, such null
  809 images do not need to be regenerated.  This would occur
  810 in \texttt{HTML} 3.0 images whose caption is enclosed in a \texttt{parbox},
  811 for example.  (Marcus Hennecke)
  813 \item[Independent control over top/bottom navigation panels]
  814 There are now separate subroutines to control the top and bottom
  815 navigation panels.  (Jens Krinke \Email{krinke@ips.cs.tu-bs.de}).
  817 \item[Labels, equations and images in section headings]
  818 All of these items are now permitted inside a section heading,
  819 and in the \verb|\title{}| command.
  820 However, the equations may not look very good because of the size
  821 difference.  (Herb Swan)
  823 \item[Other changes] The following other numerous changes are
  824 in no particular order:
  826 \begin{itemize}
  827 \item Fixed the treatment of \verb|@{}| expressions in HTML 3.0 tables.
  828 \item Made the \texttt{reuse} command line switch accept an option.
  829 \item Made the \texttt{.tex} filename suffix optional. (This will
  830 save a bit of typing!)
  831 \item Added a \fn{-debug} command line switch.
  832 \item Support unbreakable spaces (\~{}) and itallic correction.
  833 \item Fixed a bug in \fn{pstogif} which caused \fn{pnmquant} never
  834 to be called.
  835 \item The \verb|\special| \index{special command}
  836 command can now be used outside
  837 of a figure environment.  This is useful for specifying
  838 a PostScript prolog to \texttt{dvips}.
  839 \item Added the configuration variable \$TEXINPUTS to point
  840 to the path of \LaTeX\ style files that \latextohtml{} should interpret.
  841 \item Added the configuration variable \$DVIPS\_MODE to specify:
  842 \begin{enumerate}
  843 \item That \texttt{dvips} understands the \texttt{-mode} switch, and
  844 \item Which METAFont mode to use for dynamic font generation.
  845 \item The default output file prefix.
  846 \end{enumerate}
  847 \item Fixed up comment removal code to remove all comments during preprocessing.
  848 \item Make \texttt{\$LATEX2HTMLSTYLES} a path list (and support `\~{}' as 
  849 a way of specifying the home directory).
  850 \item Replace double dashes with a single dash.
  851 \item Removed extraneous spaces in comma separated citations.
  852 \item Changed encoded `\~{}' character to a real `\~{}' character at end of conversion
  853 \item Eliminated the spurious newline that was appended to macro
  854 expansions.
  855 \item Improved the error reporting of \texttt{install-test}.
  856 \item Remove whitespace from beginning of unnumbered section names.
  857 \item Add other language support for TOC, figures, tables, and
  858 \verb|\today|.
  859 \item Ignore \verb+"|+ and \verb+"-+ strings in \texttt{german} documents.
  860 \item Make \verb|\hrule| insert less vertical whitespace.
  861 \item Added an \verb|\htmlrule| \index{htmlrule}
  862 command to draw a horizontal rule, even within a figure caption.
  863 \item The \texttt{texexpand} program now ignores anything after the
  864 \begin{verbatim}
  865 \end{document}
  866 \end{verbatim}
  867 command, except when it is shielded by the \texttt{verbatim}
  868 environment.
  869 \item The optional caption argument is now the one which goes
  870         to the list of figures/tables, not the required argument.
  871 \item Added a \verb|\LaTeXe| command.
  872 \item Fixed bug in the treatment of the \verb|\circ| math symbol.
  873 \item A comment that appears on the first line of an included file
  874         is now properly removed.
  875 \item Added a call to \texttt{replace\_user\_references}, to allow
  876 style files to add new types of cross\-ref\-eren\-ces.
  877 \item Removed the expansion of \verb|`\\'| to \verb|`\\ '| in verbatim.
  878 \item Figure numbers now appear in captions enclosed in parboxes.
  879 \item All deferred warning messages are now correctly reported.
  880 \item The ``\texttt{scale=}'' option of \verb|\htmlimage| now works.
  881 \end{itemize}
  882 \end{htmllist}
  884 \subsection{Changes up to v95}
  885 \begin{htmllist}
  886 \htmlitemmark{RedBall}
  887 \item[\textbf{Much improved inlined equation baseline alignment!}]
  888 (Thanks to Mark Segal \Email{segal@spud.asd.sgi.com})
  889 Inlined equation bitmaps are now aligned correctly depending 
  890 on whether they contain subscripts, superscripts etc. 
  891 \item[\textbf{Support for internationalization}]
  892 (Thanks to Martin Boyer \Email{gamin@ireq-robot.hydro.qc.ca})
  893 A global variable \texttt{LANGUAGE\_TITLES} can now be used to change the
  894 language in which some section titles (eg ``Table of Contents'') are
  895 printed. It is also very easy to add support for more languages.
  896 \item[\textbf{Compatibility with Perl 5}]
  897 \item[\textbf{More efficient implementation}]
  898 There has been a major overhaul of the way the source text is parsed
  899 and analyzed in order to reduce the memory requirements of this
  900 process.
  902 This has been achieved by spawning off separate Unix processes to deal
  903 with each of the \texttt{input}'ed or \texttt{include}'d files. As each
  904 process
  905 terminates all the space that it used is reclaimed. 
  906 Asynchronous communication between processes takes place using 
  907 the Unix DataBase Management system (DBM or NDBM) 
  908 which should be present
  909 on your system.
  911 \textbf{To take advantage of these changes}, 
  912 it is necessary to split the source text 
  913 into more than one files which can be assembled using the \LaTeX
  914 \texttt{input} or \texttt{include} commands.
  917 \item[\textbf{``Off-line'' Image Generation}]
  919 Two new options \texttt{-no\_images} and \texttt{ -images\_only} allow
  920 ``off-line'' image conversion. The advantage of using these options is 
  921 that the translation can be allowed to finish even when there are
  922 problems with image conversion. In addition it may be possible to 
  923 fix manually any image conversion problems and then run \latextohtml{}
  924 again just to integrate the new images without having to translate
  925 the rest of the text. More instructions on how to do this are
  926 included in the ``Troubleshooting'' section of the \latextohtml{}
  927 manual.
  929 Can now use either the \fn{pbmplus} or the \fn{netpbm} libary.
  930 If \fn{netpbm} is used then it is no longer necessary to get and
  931 install \fn{giftrans} in order to generate transparent inlined 
  932 images.
  934 Also, a new option \texttt{map=\Meta{image map URL}} in the 
  935 command \texttt{htmlimage} can turn an included postscript image into an active
  936 image map.
  938 \item[\textbf{New options}] \hfill
  939 \begin{htmllist}
  940 \htmlitemmark{OrangeBall}
  941 \item [-no\_images]
  942 Do not attempt to produce any inlined images. 
  943 The missing images can be generated "off-line" by restarting \latextohtml{}
  944 with the option \texttt{-images\_only}.
  945 \item [-images\_only]
  946 Try and convert any inlined images that were left over from previous
  947 runs of \latextohtml. 
  948 \item [-no\_reuse]
  949 Do \textbf{not} reuse images generated during previous translations.
  950 (This will enable the initial interactive session during which the user is
  951 asked whether to reuse the old directory, delete its contents or quit)
  952 \item [-no\_subdir]
  953 Place the generated HTML files  in the 
  954 current directory. The default behaviour is to create (or reuse)
  955 another file directory.
  956 \item [-ps\_images]
  957 Use links to external postscript images rather than inlined GIF images.
  958 \end{htmllist}
  959 \item[\textbf{Several small changes and bug fixes}] \hfill
  960 \begin{itemize}
  961 \item It is no longer necessary to get \fn{Giftrans} if \fn{NETPBM}
  962 is available
  963 \item Fixed problems with support for \fn{german.sty}
  964 \item Fixed problems with multiple bibliographies. Each bibliography
  965 is now treated as a separate section.
  966 \item Added support for ``dotless i's and j's''.
  967 \item  Fixed to resolve figure and table numbers when captions contain
  968 accented characters.
  969 \item Added support for hierarchical indices with duplicate index keys
  970 \item Fixed problem with HTML encodings of ISO-LATIN1 characters   
  971 creeping into converted images of figures and tables.
  972 \item  Added new global variable \texttt{PAPERSIZE}
  973 to make it easier to change the default behavior when converting large images
  974 \item A new configuration variable (\texttt{TRANSPARENT\_IMAGES}) can be 
  975 used to stop any inlined images generated from "figure" environments
  976 from being transparent.
  977 \item Fixed problem which occurs when \fn{getcwd.pl} is not part of the
  978 Perl library.
  979 \item The option \texttt{-address ""} is now valid.
  980 \item Fixed a problem with tables of contents.
  981 \item Fixed problem with the use of the \texttt{finger} command when
  982 trying to find out the name of the user.
  983 \item Added some support for \texttt{tabbing} environments.
  984 \item HTML heading elements no longer contain other markup.
  985 \item Fixed problem with optional argument in citation commands
  986 \item Added some more support for LaTeX2e.
  987 \item Fixed problem with displayed equations forcing all the remaining
  988 equations to be displayed.
  989 \item Fixed bug with converting postscript images containing more than
  990 256 colors.
  991 \end{itemize}
  992 \end{htmllist}
  994 \subsection{Changes upto v0.6.2}
  996 \begin{htmllist}
  997 \htmlitemmark{RedBall}
  998 \item[\textbf{Image Conversion}] \hfill
  999 \begin{itemize}
 1000 \item The \fn{pstogif} script has been rewritten in Perl and it
 1001 now accepts more options for specifying color depth, scale factors
 1002 and pixel density.
 1003 \item LaTeX \texttt{figure} and other environments are now processed
 1004 in 24-bit color.
 1005 \item Figure and table captions are now converted into HTML
 1006 rather than becoming part of the inlined image. This means that 
 1007 any cross-references in the captions will become active.
 1008 \item It is now possible to control for each generated image:
 1009 \begin{itemize}
 1010 \item its size 
 1011 \item whether it should be inlined or left as an external image
 1012 \item if left as an external image whether it should be accessible
 1013 via a \htmlref{\textbf{generated thumbnail sketch}}{fig:example}
 1014 or a textual hypertext link
 1015 \end{itemize}
 1016 These options are available from a new LaTeX command defined in {\fn
 1017 html.sty} called \fn{htmlimage}. 
 1019 \item Equations and other inlined images are converted into
 1020 transparent GIFs rather than XBMs. \textbf{This makes it possible 
 1021 to reduced their storage requirements to about 1/6th of what was
 1022 previously required!}
 1023 \item The default size of equations and other small inlined 
 1024 images can be changed
 1025 by setting the variable \texttt{MATH\_SCALE\_FACTOR} in the
 1026 configuration files.
 1027 \item The default size of figures, tables, and other large
 1028 inlined images can be changed by setting the variable 
 1029 \texttt{FIGURE\_SCALE\_FACTOR} in the
 1030 configuration files.
 1032 \item Dvips is now called with the \texttt{-M} option which stops it
 1033 from invoking \texttt{METAFONT}.
 1034 \end{itemize}
 1036 \item[\textbf{Optimization}] \hfill
 1037 \begin{itemize}
 1038 \item Some effort has gone into reducing the amount of memory required
 1039 during conversion. \textbf{The impact of these changes can be very
 1040 significant}.
 1041 In particular, files
 1042 containing large numbers of LaTeX commands (eg \fn{.aux} or \texttt{.bib}) 
 1043 files are handled much better.
 1044 \end{itemize}
 1046 \item[\textbf{Backwards Incompatible Changes}] \hfill
 1047 \begin{itemize}
 1048 \item The option \texttt{-allbitmaps} has been removed. This is no
 1049 longer necessary as \latextohtml{} can now generate transparent
 1050 GIF images.
 1051 \item The definition of the command \texttt{htmladdnormallink} in the 
 1052 file \fn{html.sty} has changed and the URL will no longer appear
 1053 as a footnote in the paper (DVI) version. The translation of
 1054 this command into HTML is \textbf{not} affected. 
 1056 The previous functionality can be obtained with a new command
 1057 \texttt{htmladdnormallinkfoot} which will add the URL as a footnote
 1058 in the paper version.
 1059 \item The script \fn{pstoxbm} is no longer distributed as it is not
 1060 used.
 1062 \end{itemize}
 1064 \item[\textbf{Bug Fixes}] \hfill
 1065 \begin{itemize}
 1066 \item The \fn{install-test} script now recognizes version
 1067 numbers correctly and gives better warnings. It also makes
 1068 executable any scripts that need to be so. 
 1069 \item Stopped using the \texttt{nslookup} program to try and guess
 1070 e-mail addresses (they were used in signing each generated page). 
 1071 This has been replaced with a simple call 
 1072 to \texttt{finger}.
 1073 \item Fixed problem which could cause ``Parameter overflow'' in 
 1074 TeX during image conversion.
 1075 \item The \fn{texexpand} script has been changed extensively.
 1076 Some nasty looping problems are now avoided, and the tracking
 1077 down of included files has been improved.
 1078 \item Some reported incompatibilities with some Unix shells
 1079 (bash,OSF) have been fixed.
 1080 \item Displayed equations now appear correctly on separate
 1081 lines and are right justified.
 1082 \item Fixed bug with nested environments.
 1083 \item Fixed problem which caused the wrong numbers to be assigned
 1084 to sections with the same titles when the \texttt{-show\_section\_titles}
 1085 is used (thanks to Brian  Toonen \Email{toonen@mcs.anl.gov}).
 1086 \item Fixed problem with the \texttt{hyperref} command which
 1087 caused the wrong ``hyperized'' text to appear in the final document.
 1088 \item \texttt{item} optional arguments can now contain one level of
 1089 nesting eg \texttt{item[[First Choice]]}.
 1090 \item Fixed problems with the ``image caching and reuse'' mechanism 
 1091 which avoids converting images unnecessarily..
 1092 \end{itemize}
 1094 \item[\textbf{Other Changes}] \hfill
 1095 \begin{itemize}
 1096 \item LaTeX2HTML now generates \HTML{meta} HTML tags which can be used
 1097 by indexing scripts.
 1098 The information in the \HTML{meta} tags
 1099 contains
 1100 the title of each separate HTML file. 
 1101 \item A new configuration variable \texttt{DEBUG} can be used to preserve
 1102 intermediate files for debugging. 
 1103 \item Some problems with respect to compatibility with the HTML2.0 
 1104 standard have been addressed. No more ``unquoted attribute value literals''.
 1105 \item All the navigation icons are now ``lynx friendly''; their
 1106 \texttt{ALT} attribute now has a meaningful value.
 1107 \item A new LaTeX command \fn{htmlref} makes it a lot simpler
 1108 to create hypertext links intended only for the HTML version of
 1109 the document.
 1110 \item \fn{DVIPSK} is now recognized by the installation script
 1111 \item Added support for the \fn{changebar.sty} file by 
 1112 David B. Johnson (dbj@titan.rice.edu).
 1113 \item It is no longer necessary to add style file names into the 
 1114 \texttt{DONT\_INCLUDE} variable as \latextohtml{} now does not
 1115 attempt to translate file included files ending in \texttt{.sty}.
 1116 \item The small invisible bitmaps that used to mark anchors have been
 1117 replaced with the invisible character \verb|&#160;|.
 1118 \item It is no longer necessary to use full path names when
 1119 including external postscript files.
 1120 \item If a file \fn{.latex2html-init} is found in the ``current
 1121 directory'' then this will be loaded automatically after loading the
 1122 other default configuration files.
 1123 \item Changed the naming convention of generated HTML files. The
 1124 ``top'' document is \fn{<FILE>.html} as before but all other ``nodes''
 1125 are named \fn{nodeN.html} where \fn{N} is an integer. Also, the file
 1126 containing
 1127 the footnotes is now called \fn{footnode.html}.
 1128 \item A special extension to \latextohtml{} for those who use the 
 1129 Harvard style for references is included.
 1130 \end{itemize}
 1131 \end{htmllist}
 1134 \subsection{Changes upto v0.5.3}
 1135 \begin{itemize}
 1136 \item The files \fn{LATEX2HTMLDIR/styles/german.perl} and 
 1137 \fn{LATEX2HTMLDIR/styles/makeidx.perl} have been fixed
 1138 so that they are consistent with changes in the main script.
 1139 \item A problem with disappearing spaces after some equations
 1140 and other environments has been fixed.
 1141 \end{itemize}
 1142 \subsection{Changes upto v0.5.1}
 1143 \begin{htmllist}
 1144 \htmlitemmark{YellowBall}
 1145 \item[\textbf{Navigation Panel}]
 1146 The \hyperref{navigation panel}{navigation panel (see section
 1147 }{)}{sec:navpanel}
 1148 is now fully configurable and much better looking.
 1149 \item[\textbf{Automatic Signatures}]
 1150 The signatures at the bottom of each page are now constructed
 1151 using \fn{nslookup} (Thanks to Alberto Accomazzi
 1152 \Email{alberto@cfa.harvard.edu})
 1153 \item[\textbf{Numerous fixes including...}] \hfill
 1154 \begin{itemize}
 1155 \item ``dead'' \fn{next\_page} buttons when the \fn{-split} option
 1156 was used, and
 1157 \item internal \latextohtml{} markers appearing in section titles.
 1158 \end{itemize}
 1159 \end{htmllist}
 1161 \subsection{Changes upto v0.4}
 1162 \begin{htmllist}
 1163 \htmlitemmark{RedBall}
 1164 \item[\textbf{Accents and Special Characters}]
 1165 LaTeX accent commands, special characters and accent commands defined
 1166 in \fn{german.sty} are translated to equivalent ISO-LATIN-1
 1167 characters when that is possible (partly thanks to code supplied
 1168 by Franz Vojik \Email{vojik@de.tu-muenchen.informatik}).
 1169 \item[\textbf{Auto-loading of Style-Specific Code}]
 1170 The translator now supports a 
 1171 \hyperref{mechanism for including Perl code extensions}{mechanism for
 1172 including Perl code extensions (see Section }{)}{sec:sty}
 1173 which are specific to particular style files. 
 1176 This mechanism will help to keep the core script smaller as well as make
 1177 it easier for others to contribute and share solutions on  
 1178 how to translate specific style files. The current distribution includes the files
 1179 \fn{german.perl}, \fn{french.perl}, \fn{html.perl} and \fn{makeidx.perl}.
 1180 \item[\textbf{Installation and Testing}]
 1181 To make it easier to install the translator for more than one user
 1182 there is now a configuration file ({\fn
 1183 LATEX2HTMLDIR/latex2html.config}) which contains installation specific 
 1184 information and default values for the various options. 
 1185 This makes it unnecessary to have a \fn{HOME/.latex2html-init} for
 1186 each user.
 1187 If a user does have a  \fn{HOME/.latex2html-init} then this will be
 1188 loaded after {\fn
 1189 LATEX2HTMLDIR/latex2html.config}.
 1191 A new Perl script (\fn{install-test}) is now available with the distribution
 1192 which will install the translator, and then perform some tests on the
 1193 availability
 1194 of some external
 1195 programs giving, appropriate warnings.
 1196 \item[\textbf{Navigation Panel Extensions}]
 1197 The following new links have been added to the navigation panel which
 1198 appears in each page
 1199 (where this is appropriate):
 1200 \begin{itemize}
 1201 \item a link to the next ``logical'' page (this allows reading each
 1202 page in the same order as with a paper-based version - as opposed to
 1203 structure navigation)
 1204 \item a link to the previous ``logical'' page 
 1205 \item a link to the table of contents
 1206 \item a link to the index 
 1207 \end{itemize}
 1208 \item[\textbf{HTML Style File Extensions}]
 1209 The HTML style file \fn{html.sty} now includes definitions of new 
 1210 environments for:
 1211 \begin{htmllist}
 1212 \htmlitemmark{OrangeBall}
 1213 \item[Inclusion of Raw HTML]
 1214 A new LaTeX environment \texttt{rawhtml} allows
 1215 arbitrary
 1216 HTML tags to be included in a LaTeX document. This is useful for
 1217 taking
 1218 advantage of HTML+ features as they become available (e.g. interactive
 1219 forms).
 1220 The HTML commands are ignored when producing the DVI version of the
 1221 document.
 1222 \label{sec:cond}
 1223 \item[Conditional Text]
 1224 The new environments \texttt{latexonly} and \texttt{htmlonly} allow their
 1225 contents to appear only in final DVI or in the HTML version of a
 1226 document respectively. 
 1228 A new command \texttt{hyperref} can be used to specify the way in
 1229 which cross-references should be shown in the DVI version and the
 1230 HTML version of the document.
 1231 \end{htmllist}
 1232 \item[\textbf{Right Justification of Equations}]
 1233 The translator
 1234 adds enough whitespace at the beginning of each equation bitmap
 1235 to push it to the right-hand margin. The width of each line can be
 1236 set in the configuration file using the variable \texttt{LINE\_WIDTH}.
 1237 \item[\textbf{Inlined Images}]
 1238 All inlined images are now generated by calling \texttt{latex} and {\fn
 1239 dvips} only once
 1240 at the end of the conversion process (but each generated image still
 1241 has to be filtered individually). Also, a warning is given if an 
 1242 image cannot be converted.
 1243 \item[\textbf{Numeric Labels}]
 1244 The original (LaTeX generated) numeric labels are used instead of
 1245 the arrow navigation icon for cross-references where possible.
 1246 To do this the translator uses the information in the 
 1247 \fn{aux} file which is generated by \LaTeX. If the \fn{aux} file
 1248 is out of date a warning is given.
 1249 \item[\textbf{New Options}] \hfill
 1250 \begin{htmllist}
 1251 \htmlitemmark{RedBall}
 1252 \item[\texttt{-auto\_navigation}]
 1253 This puts a navigation panel 
 1254 at the top of each page as usual. But if the page exceeds a
 1255 user-settable  
 1256 number of words (the default is 450 words) 
 1257 then a navigation panel is also placed at the end of
 1258 the page. This option is active by default.
 1259 \item[\texttt{-index\_in\_navigation}]
 1260 Adds a link to the index in the navigation panel.
 1261 \item[\texttt{-contents\_in\_navigation}]
 1262 Adds a link to the table of contents in the navigation panel.
 1263 \item[\texttt{-next\_page\_in\_navigation}]
 1264 Adds a link to the next ``logical'' page in the navigation panel.
 1265 \item[\texttt{-previous\_page\_in\_navigation}]
 1266 Adds a link to the previous ``logical'' page in the navigation panel.
 1267 \item[\texttt{-bottom\_navigation}]
 1268 This puts a navigation panel at the bottom of each page.
 1269 \item[\texttt{-top\_navigation}]
 1270 This puts a navigation panel at the top of each page (the default).
 1271 \item[\texttt{-show\_section\_numbers}]
 1272 This allows each section (page) title to be numbered in the same 
 1273 way that it would be numbered by \LaTeX. This requires 
 1274 an up to date \fn{aux} file (generated by running \LaTeX) and that 
 1275 each title is unique. If the \fn{aux} file is not up to date then a 
 1276 warning is given.
 1277 Unfortunately if 
 1278 the title contains inlined images the numbering for that title will
 1279 be lost. 
 1280 \item[\texttt{-reuse}]
 1281 This allows images generated during previous invocations of
 1282 the translator to be ``reused'' without going through the initial 
 1283 interactive session. The same behavior is obtained by setting
 1284 the variable \texttt{REUSE} to 1 (the default) in the configuration file.
 1285 Note that images which may depend on contextual information (e.g. numerical
 1286 labels) cannot be reused and are always re-generated. 
 1287 \end{htmllist}
 1288 \item[\textbf{Bug Fixes and Minor Changes}] \hfill
 1289 \begin{itemize}
 1290 \item The links from the table of contents in single page documents (created using
 1291 the option \texttt{-split 0}) is now working as expected.
 1292 \item Newlines are translated to the \HTML{BR} tag.
 1293 \item Fixed some problems in dealing with new command macros.
 1294 \item \fn{texexpand} now respects commented \texttt{input} and 
 1295 \texttt{include} commands. Also (thanks to Franz Vojik
 1296 \Email{vojik@de.tu-muenchen.informatik}), it 
 1297 now looks in subdirectories when expanding
 1298 files.
 1299 \item The ALIGN attribute of inlined images is now BOTTOM instead of
 1300 TOP.
 1301 \item Fixed problem with the environment variable \texttt{TEXINPUTS}.
 1302 \item Added some support for optional user-defined labels (bullets) in
 1303 list environments.
 1304 \end{itemize}
 1305 \end{htmllist}
 1307 More details on all the changes are available in the file 
 1308 \fn{LATEX2HTMLDIR/Changes}.
 1310 \subsection{Changes upto v0.3.1}
 1311 These changes are mostly due to patches contributed by Robert S. Thau
 1312 \Email{rst@ai.mit.edu}:
 1313 \begin{itemize}
 1314 \item Nested environments with the same name are now dealt with
 1315 properly.
 1316 \item Commands that are passed to LaTeX for processing which have 
 1317 environments in their arguments (e.g. a \texttt{parbox} command which 
 1318 an \texttt{itemize} environment as an argument) are now
 1319 processed correctly. A general mechanism for users to 
 1320 specify the syntax of commands that should be passed to LaTeX 
 1321 is described in Page \pageref{pass}.
 1322 \item Fixed a problem with recognizing the \texttt{special} command.
 1323 \item Fixed bug in the generation of the index.
 1324 \end{itemize}
 1326 \subsection{Changes upto v0.3}
 1327 \begin{htmllist}
 1328 \htmlitemmark{YellowBall}
 1329 \item [\textbf{Image Recycling}]
 1330 Images for equations, tables, figures, special characters etc. generated by
 1331 the translator are recognized  during subsequent runs.
 1332 The user is then asked whether old images should be reused
 1333 (or whether the old images should be deleted and regenerated).
 1334 This offers tremendous improvements in speed after an initial
 1335 successful translation.
 1337 \item [\textbf{Cross-References Between (Local or Remote) Documents}]
 1338 Cross-references between 
 1339 two or more documents (possibly on remote locations) can be
 1340 established via symbolic labels
 1341 which are independent of the physical realization of these documents. 
 1343 Such cross-references will be maintained with a simple
 1344 re-translation\footnote{This is true for documents under the same
 1345 server but for remote documents a little more is required (see 
 1346 the \hyperref{example}{example in Section}{}{crossrefs})}
 1347 even after one or more of the documents have been broken into
 1348 different physical parts or moved.
 1350 The mechanism is based on the 
 1351 \hyperref{new commands}{new commands (see Section }{ )}{external}
 1352 \texttt{externallabels} and \texttt{externalref} which are an extension of the simple 
 1353 \texttt{label-ref} pairs. 
 1355 \item [\textbf{New Options}] \hfill
 1356 \begin{htmllist}
 1357 \htmlitemmark{GreenBall}
 1358 \item [\texttt{external\_images}] This provides hypertext links to where
 1359 generated images (for equations, tables, figures etc) are stored
 1360 externally. (The default is to ``inline'' generated images in the main body 
 1361 of the text.)
 1362 \item [\texttt{ascii\_mode}] This switches all the navigation icons to their
 1363 ascii equivalents. Also generated images are stored externally as with the 
 1364 \texttt{external\_images} option above. The \texttt{ascii\_mode} option
 1365 makes documents more portable as it allows them to be
 1366 viewed on browsers that do not support inlined images.
 1367 \end{htmllist}
 1368 \item [\textbf{Special Command Style File}] A style file \fn{html.sty}
 1369 is now included in the
 1370 distribution. This contains the definitions (syntax) of some 
 1371 special LaTeX commands mainly for providing external hypertext
 1372 links.
 1373 This should be included in LaTeX files that use the any 
 1374 \hyperref{hypermedia extensions}{hypermedia extensions (see Section}{ )}{special}.
 1376 \item [\textbf{Minor Changes and Bug Fixes}] \hfill
 1377 \begin{itemize}
 1378 \item Equations, equation arrays and theorems are now numbered
 1379 correctly even when they are individually passed to LaTeX for
 1380 processing.
 1381 \item Fixed problem with \texttt{label} commands appearing in section
 1382 headings.
 1383 \item Fixed problems with verbatim environments, bibliography items,
 1384   generated file names, the options \texttt{nolatex} and
 1385   \texttt{no\_navigation}, the \texttt{thanks command}, the name of an
 1386   HTML tag (\HTML{HEAD}),
 1387 \item The appearance of footnotes has been improved.
 1388 \item Some inconsistencies in the \fn{pstoxbm} and \fn{pstogif}
 1389  scripts have been fixed.  
 1390 \item Parts of the documentation have been rewritten, restructured and
 1391 some new sections have been added. 
 1392 \end{itemize}
 1393 \end{htmllist}
 1395 \textbf{The following were contributed by Robert S. Thau
 1396 \Email{rst@ai.mit.edu}:}
 1398 \begin{htmllist}
 1399 \htmlitemmark{WhiteBall}
 1400 \item [\textbf{New Texexpand}]
 1401 This fixes problems with the standard version and 
 1402 handles the inclusion of style files which need to processed by the 
 1403 translator. Appropriate modifications to the main script were also 
 1404 made to work with new version of \fn{texexpand}. 
 1406 \item [\textbf{Handling of Raw \TeX}]
 1407 Added support for simple raw TeX commands such as  
 1408 \texttt{special} and simple instances of \texttt{def}\footnote{Where
 1409 ``simple'' is defined roughly 
 1410 as ``they could have used \texttt{newcommand}, but didn't''.}. 
 1411 For the messier cases, 
 1412 the definition is scooped up and moved to the preamble.  This allows 
 1413 the translator to handle the simple, but nonstandard, postscript figure inclusion
 1414 macros as well as an awful lot of other stuff done with gratuitous 
 1415 \texttt{defs}.
 1416 \item [\textbf{More Options}] \hfill
 1417 \begin{htmllist}
 1418 \htmlitemmark{PinkBall}
 1419 \item [\texttt{dont\_include}]
 1420 This can be used  to specify style files that
 1421 should not be included in the translation.
 1422 \end{htmllist}
 1423 \item [\textbf{Other Changes}] \hfill
 1424 \begin{itemize} 
 1425 \item Added support for nested math mode expressions and general
 1426 list environments in order to handle \emph{the document from Hell!!!}.
 1427 \item Fixed problems in the translation of 
 1428 bibitems, the substitution of macro definitions, and the processing of
 1429 unrecognized commands in the preamble.
 1430 \end{itemize}
 1431 \end{htmllist}
 1432 \subsection{Changes upto v0.2}
 1433 \begin{itemize}
 1434 \item Added a command line option
 1435 to switch off the navigation links
 1436 at the top of each page.
 1437 \item The navigation icons are now part of the distribution.
 1438 \item Added a customizable separator between the main body of the text
 1439 in a page and the child links from that page.
 1440 \item The order of the navigation keywords at the top of each page is
 1441 the same as that of the navigation icons.
 1442 \item The arguments of \texttt{verbatim} environments are now translated
 1443 into fixed width fonts.
 1444 \item A warning is given if a \texttt{bbl} (bibliography) file is 
 1445 needed but not found.
 1446 \item The installation is now (mostly) done by setting variables in 
 1447 just one file.
 1448 \item The \fn{pstoxbm} script now uses environment variables
 1449 set in the initialization file.
 1450 \item Fixed bug in translating sequences of special HTML characters
 1451 (e.g. \&, $<$, etc.)
 1452 \item Fixed bug in the handling of the \verb|$$|-form of the dislay
 1453 math environment.
 1454 \item Fixed bug in the handling of the *-forms of environments.
 1455 \item Added sections on how to embed hyperlinks in a LaTeX document 
 1456 (see Page \pageref{sec:hyper}) and on how to extend the translator
 1457 (see Page \pageref{sec:extend}) in the documentation.
 1458 \end{itemize}
 1460 \subsection{Changes upto v0.1.1}
 1461 \begin{itemize}
 1462 \item Fixed bug about empty lines being inserted in environments that
 1463 cannot tolerate them (e.g. \texttt{math}).
 1464 \item Changed the format of inlined images coming back from LaTeX
 1465 from GIF to XBM. This looks better on grayscale and color monitors.
 1466 \item Fixed problem with commands being passed on to LaTeX  after
 1467 their
 1468 arguments had been translated (this affects the commands 
 1469 \texttt{psfig}, \texttt{fbox}, \texttt{framebox}, and \texttt{parbox}).
 1470 \end{itemize}