## "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.
10
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.
19
20 A resort for machines with small memory could be to choose
21 document segmentation (Section \ref{Segmentation}).
22
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.
27
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.
37
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.
43
44
45
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.
50
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.
56
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.
63
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.
68
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.
74
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.
79
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} 90 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: 97 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} 108 109 \emph{to} 110 111 \begin{verbatim} 112 : # *-*-perl-*-* 113 eval 'exec perl -S$0 "$@"' 114 if$running_under_some_shell;
115 \end{verbatim}
116
117
118 \item [Cannot run any of the Perl programs \#2]\hfill\\
120
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}),
130 \fn{/usr/local/bin} (this is recommended).
131
132
133 \item [Cannot run \fn{latex2html}]\hfill\\
136
137 You must have Perl installed to use \latextohtml, you can't run it
139
140
141 \item [\fn{latex2html} exits with one of these messages:]\hfill
142
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}
148
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.
156
157
158
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}
171
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.
177
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.
184
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).
187
188 You can check which version of
189 Perl you are using by invoking Perl with the \texttt{-v} option.
190
191
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>}.
197
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.
202
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.
208
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,
213 24MB of RAM and over 150MB of swap space to convert on a local Sun Sparc ELC
214 running SunOS 4.1.3.
215
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.
221
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+}
225
226 \item [Cannot get the tilde'' (\~{}) to show]
227 The trick here is to use the command \verb|\~{}|.
228
229 Alternatively it is possible to use something like \\
230 \begin{verbatim}
232   {\begin{rawhtml}http://host/~me/path/file.html\end{rawhtml}}
233 \end{verbatim}
234
235 or
236
238
239 \textbf{Warning:} Some browsers may not be able to interpret the \verb|%7E|
240 as a tilde'' character.
241
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.
250
251 In general the macro handling mechanism is inefficient and very
252 fragile. Avoid using macros if possible.
253
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.
259
260 \item [\texttt{input} commands in verbatim environments]
261 These cause problems. There is no fix yet.
262
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]]}]+
268
269 \item [LaTeX2HTML behaves differently even when you run it on the
270 same file]
271
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.
277
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}
289
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.
303
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}.
311
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";| 317 318 to 319 320 \verb|$DVIPS = "dvips -r0";|
321
322 in the file \fn{latex2html.config}.
323
324 \item [\textbf{Unacceptable quality of converted images}]
325 Try changing the size of the image
326 (\hyperref{See image conversion}{See Section }{}{imgcon}).
327
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.
332
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.
337
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...
345
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.
351
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
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...}.
357
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.
375
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}
386
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.
392
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");/ 401 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} 411 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. 416 417 OPENING /usr/cblelca/nikos/scripts/tex2html/tests/image-test.tex 418 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> 425 426 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 443 444 Doing section links ..... 445 Done. 446 \end{verbatim} 447 448 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): 454 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} 492 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}. 507 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. 514 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 521 522 Reading ... 523 Processing macros ....+. 524 Reading test.aux ...................... 525 Translating ...0/1........1/1..... 526 Writing image file ... 527 528 Doing section links ..... 529 530 *********** WARNINGS *********** 531 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. 535 536 Done. 537 \end{verbatim} 538 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}. 543 544 The options \texttt{no\_reuse, no\_images} and \texttt{images\_only} 545 are available with \latextohtml{} version 0.7 or later. 546 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. 554 555 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} 564 565 %%% END FAQ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 566 % do not remove this magic marker ^^ 567 568 \section{Support and More Information} 569 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. 574 575 To join send a message to: \\ 576 \texttt{latex2html-request@tug.org} \\ 577 with the contents \\ 578 \texttt{subscribe} 579 580 To be removed from the list send a message to: \\ 581 \texttt{latex2html-request@tug.org} \\ 582 with the contents \\ 583 \texttt{unsubscribe}. 584 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. 591 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} 614 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. 626 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. 631 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. 636 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). 644 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. 649 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). 654 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. 667 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. 674 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. 679 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. 686 687 Many others, too many to mention, 688 have contributed bug reports, fixes, and other suggestions. Keep them coming! 689 690 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}. 698 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}) 707 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.
718
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})
724
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)
733
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})
741
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)
747
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)
752
753 \item[Support for textual font size changes]
754 HTML 2.1 support is now available fo 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)
760
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.
765
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)
770
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.)
777
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}
789
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)
799
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)
805
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)
812
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}).
816
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)
822
823 \item[Other changes] The following other numerous changes are
824 in no particular order:
825
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} 883 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. 901 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. 910 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. 915 916 917 \item[\textbf{Off-line'' Image Generation}] 918 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. 928 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. 933 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. 937 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} 993 994 \subsection{Changes upto v0.6.2} 995 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}. 1018 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. 1031 1032 \item Dvips is now called with the \texttt{-M} option which stops it 1033 from invoking \texttt{METAFONT}. 1034 \end{itemize} 1035 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} 1045 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. 1055 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. 1061 1062 \end{itemize} 1063 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} 1093 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} 1132 1133 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} 1160 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. 1174 1175 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}. 1190 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. 1227 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} 1306 1307 More details on all the changes are available in the file 1308 \fn{LATEX2HTMLDIR/Changes}. 1309 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} 1325 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. 1336 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. 1342 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. 1349 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. 1354 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}. 1375 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} 1394 1395 \textbf{The following were contributed by Robert S. Thau 1396 \Email{rst@ai.mit.edu}:} 1397 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}. 1405 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}
1459
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}
`