-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathlatex2html.1
1345 lines (1343 loc) · 45.1 KB
/
latex2html.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" Hey, Emacs! This is an -*- nroff -*- source file.
.\" Copyright (c) 1997 Manoj Srivastava <[email protected]>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301
.\" USA.
.\"
.\"
.TH LaTeX2HTML 1 "July 1 2021" "Debian" "Debian GNU/Linux manual"
.SH NAME
latex2html \- translate LaTeX files to HTML (HyperText Markup Language)
.SH SYNOPSIS
.B latex2html
.I [options]
\&[target [target ...]]
.SH DESCRIPTION
This manual page explains the
.B "LaTeX2HTML"
utility, which is a
.B Perl
program that translates
.B LaTeX
document into
.B HTML
format. For each source file given as an argument
the translator will create a directory containing the corresponding
HTML files. For details and examples, please consult the online html
documentation, a copy of which should be available in
.I /usr/share/doc/latex2html/manual.ps.gz
or
.I /usr/share/doc/latex2html/html/
.SH CAVEAT
This documentation has been derived from the TeX manual, and may not be
up to date. Please refer to the online manual for authoritative
documentation.
.SH Options controlling Titles, File-Names and Sectioning
.TP
.B -t <top-page-title>
Same as setting:
.I $TITLE = "<top-page-title>";
Name the document using this title.
.TP
.B -short_extn
Same as setting:
.I $SHORTEXTN = 1;
Use a filename prefix of .htm for the produced
.B HTML
files. This is
particularly useful for creating pages to be stored on CD-ROM or other
media, to be used with operating systems that require a 3-character
extension.
.TP
.B -long_titles <num>
Same as setting:
.I $LONG_TITLES = <num>;
Instead of the standard names: node1.html, node2.html,... the filenames
for each
.B HTML
page are constructed from the first <num> words of the
section heading for that page, separated by the `_' character.
Commas and common short words (a an to by of and for the) are omitted
from both title and word-count.
When duplication of constructed filenames is detected (see also the
.B -unicase_titles
option), an incremented number starting from 2
is appended to each duplicated filename.
.TP
.B -unicase_titles
Same as setting:
.I $UNICASE_TITLES = 1;
If set, and the
.B -long_titles
option is used, duplication of generated filenames
is checked in case insensitive manner.
Useful under case insensitive filesystems such as NTFS or FAT.
.TP
.B -custom_titles
Same as setting:
.I $CUSTOM_TITLES = 1;
Instead of the standard names: node1.html, node2.html, ... the
filenames for each
.B HTML
page are constructed using a
.B Perl
subroutine
named custom_title_hook . The user may define his/her own version of
this subroutine, within a .latex2html-init file say, to override the
default (which uses the standard names). This subroutine takes the
section-heading as a parameter and must return the required name, or
the empty string (default).
.TP
.B -dir <output-directory>
Same as setting:
.I $DESTDIR = "<output-directory>";
Redirect the output to the specified directory.
The default behaviour is to create (or reuse) a directory having the
same name as the prefix of the document being processed.
.TP
.B -no_subdir
Same as setting:
.I $NO_SUBDIR = 1;
Place the generated
.B HTML
files into the current directory. This
overrides any
.I $DESTDIR
setting.
.TP
.B -prefix <filename-prefix>
Same as setting:
.I $PREFIX = "<filename-prefix>";
The <filename-prefix> will be prepended to all .gif, .pl and .html
files produced, except for the top-level .html file; it may include a
(relative) directory path. This will enable multiple products of
.B LaTeX2HTML
to peacefully coexist in the same directory. However, do not
attempt to simultaneously run multiple instances of
.B LaTeX2HTML
using
the same output directory, else various temporary files will overwrite
each other.
.TP
.B -auto_prefix
Same as setting:
.I $AUTO_PREFIX = 1;
Constructs the prefix as `<title>-' to be prepended to all the files
produced, where <title> is the name of the
.B LaTeX
file being processed.
(Note the `-' in this prefix.)
This overrides any
.I $PREFIX
setting.
.TP
.B -no_auto_link
Same as setting:
.I $NO_AUTO_LINK = 1;
If $NO_AUTO_LINK is empty and variables
.I $LINKPOINT
and
.I $LINKNAME
are
defined appropriately (as is the default in the latex2html.config
file), then a hard link to the main
.B HTML
page is produced, using the
name supplied in
.I $LINKNAME.
Typically this is index.html; on many
systems a file of this name will be used, if it exists, when a browser
tries to view a URL which points to a directory. On other systems a
different value for
.I $LINKNAME
may be appropriate. Typically
.I $LINKPOINT
has
value
.I $FILE.html,
but this may also be changed to match whichever
HTML page is to become the target of the automatic link.
Use of the -no_auto_link switch cancels this automatic linking
facility, when not required for a particular document.
.TP
.B -split <num>
Same as setting:
.I $MAX_SPLIT_DEPTH = <num>; (default is 8)
Stop splitting sections into separate files at this depth. Specifying
-split 0 will put the entire document into a single
.B HTML
file. See
below for the different levels of sectioning. Also see the next item
for how to set a ``relative'' depth for splitting.
.TP
.B -split +<num>
Same as setting:
.I $MAX_SPLIT_DEPTH = -<num>; (default is 8)
The level at which to stop splitting sections is calculated ``relative
to'' the shallowest level of sectioning that occurs within the
document. For example, if the document contains \\section commands, but
no \\part or \\chapter commands, then -split +1 will cause splitting at
each \\section but not at any deeper level; whereas -split +2 or -split
+3 also split down to \\subsection and \\subsubsection commands
respectively. Specifying -split +0 puts the entire document into a
single
.B HTML
file.
.TP
.B -link <num>
Same as setting:
.I $MAX_LINK_DEPTH = <num>; (default is 4)
For each node, create links to child nodes down to this much deeper
than the node's sectioning-level.
Specifying -link 0 will show no links to child nodes from that page,
-link 1 will show only the immediate descendants, etc.
A value at least as big as that of the -split <num> depth will produce
a mini table-of-contents (when not empty) on each page, for the tree
structure rooted at that node.
When the page has a sectioning-level less than the -split depth, so
that the a mini table-of-contents has links to other
.B HTML
pages, this
table is located at the bottom of the page, unless placed elsewhere
using the \\tableofchildlinks command.
On pages having a sectioning-level just less than the -split depth the
mini table-of-contents contains links to subsections etc. occurring on
the same
.B HTML
page. Now the table is located at the top of this page,
unless placed elsewhere using the \\tableofchildlinks command.
.TP
.B -toc_depth <num>
Same as setting:
.I $TOC_DEPTH = <num>; (default is 4)
Sectioning levels down to <num> are to be included within the
Table-of-Contents tree.
.TP
.B -toc_stars
Same as setting:
.I $TOC_STARS = 1;
Sections created using the starred-form of sectioning commands are
included within the Table-of-Contents. As with
.B LaTeX,
normally such
sections are not listed.
.TP
.B -show_section_numbers
Same as setting:
.I $SHOW_SECTION_NUMBERS = 1;
Show section numbers. By default section numbers are not shown, so as
to encourage the use of particular sections as stand-alone documents.
In order to be shown, section titles must be unique and must not
contain inlined graphics.
.TP
.B -add_ref_name
Same as setting:
.I $ADD_REF_NAME = 1;
Usually cross reference text contains only the caption number as a
hyperlink to the corresponding
.B LaTeX
label. However, it could be
handy to see the name of the object referenced, if the reference text
would contain both the caption number and the caption name.
With -add_ref_name the caption name is shown additionally when available.
.TP
.B -cut_ref_num
Same as setting:
.I $CUT_REF_NUM = 1;
Usually cross reference text contains only the caption number as a
hyperlink to the corresponding
.B LaTeX
label. With -add_ref_name the
caption name can be shown additionally. If the caption number is not
desired, it can be cut out with -cut_ref_num. If -cut_ref_num is
given and -add_ref_name is not, then the cross reference text is
suppressed completely and a cross reference button shown instead.
.TP
.B -unsegment
Same as setting:
.I $UNSEGMENT = 1;
Treat a segmented document (see the section about document
segmentation) like it were not segmented. This will cause the
translator to concatenate all segments and process them as a whole. You
might find this useful to check a segmented document for consistency.
For all documents the sectioning levels referred to above are:
.RS
0 document
1 part
2 chapter
3 section
4 subsection
5 subsubsection
6 paragraph
7 subparagraph
8 subsubparagraph
.RE
.P
These levels apply even when the document contains no sectioning for the
shallower levels; e.g. no \\part or \\chapter commands is most common,
especially when using
.B LaTeX's
article document-class.
.SH Options controlling Extensions and Special Features
The switches described here govern the type of
.B HTML
code that can be
generated, and how to choose between the available options when there are
alternative strategies for implementing portions of
.B LaTeX
code.
.TP
.B -html_version (2.0|3.2|4.0|5.0)[,(math|i18n)]*
Same as setting:
.I $HTML_VERSION = "... ";
This specifies both the
.B HTML
version to generate, and any extra
(non-standard)
.B HTML
features that may be required.
The version number corresponds to a published DTD for an
.B HTML
standard. A
corresponding
.B Perl
file in the versions/ subdirectory is loaded; these
files are named `html<num>.pl'.
Following the version number, a comma-separated list of extensions can
be given. Each corresponds to a file `<name>.pl' also located in the
versions/ subdirectory. When such a file is loaded the resulting HTML
code can no longer be expected to validate with the specified DTD. An
exception is math when the -no_math switch is also used, which should
still validate.
Currently, versions 2.0, 3.2, 4.0 and 5.0 are available.
The default version is usually set to be `5.0', within
latex2html.config.
.TP
.B -no_tex_defs
Same as setting:
.I $TEXDEFS = 0; (default is 1)
When
.I $TEXDEFS
is set (default) the file texdefs.perl will be read. This
provides code to allow common TEX commands like \\def, \\newbox,
\\newdimen and others, to be recognised, especially within the document
preamble. In the case of \\def, the definition may even be fully
interpreted, but this requires the pattern-matching to be not too
complicated.
If
.I $TEXDEFS
is `0' or empty, then texdefs.perl will not be loaded; the
translator will make no attempt to interpret any raw TEX commands. This
feature is intended to enable sophisticated authors the ability to
insert arbitrary TEX commands in environments that are destined to be
processed by
.B LaTeX
anyway; e.g. figures, theorems, pictures, etc.
However this should rarely be needed, as now there is better support
for these types of environment. There are now other methods to specify
which chunks of code are to be passed to
.B LaTeX
for explicit
image-generation; see the discussion of the makeimage environment.
.TP
.B -external_file <filename>
Same as setting:
.I $EXTERNAL_FILE = "<filename>";
Specifies the prefix of the .aux file that this document should read.
The .aux extension will be appended to this prefix to get the complete
filename, with directory path if needed.
This file could contain necessary information regarding citations,
figure, table and section numbers from
.B LaTeX
and perhaps other
information also. Use of this switch is vital for document segments,
processed separately and linked to appear as if generated from a single
LaTeX document.
.TP
.B -font_size <size>
Same as setting:
.I $FONT_SIZE = "<size>";
This option provides better control over the font size of environments
made into images using
.B LaTeX.
<size> must be one of the font sizes that
.B LaTeX
recognizes; i.e. `10pt', `11pt', `12pt', etc. Default is `10pt',
or whatever option may have been specified on the \\documentclass or
\\documentstyle line.
Whatever size is selected, it will be magnified by the installation
variables
.I $MATH_SCALE_FACTOR,
.I $FIGURE_SCALE_FACTOR
and
.I $DISP_SCALE_FACTOR
as appropriate.
Note: This switch provides no control over the size of text on the HTML
pages. Such control is subject entirely to the user's choices of
settings for the browser windows.
.TP
.B -scalable_fonts
Same as setting:
.I $SCALABLE_FONTS = 1;
This is used when scalable fonts, such as PostScript versions of the
TEX fonts, are available for image-generation.
It has the effect of setting
.I $PK_GENERATION
to `1', and
.I $DVIPS_MODE
to
be empty, overriding any previous settings for these variables.
.TP
.B -no_math
Same as setting:
.I $NO_SIMPLE_MATH = 1;
Ordinarily simple mathematical expressions are set using the ordinary
text font, but italicized. When part of the expression can not be
represented this way, an image is made of the whole formula. This is
called ``simple math''. When
.I $NO_SIMPLE_MATH
is set, then all
mathematics is made into images, whether simple or not.
However, if the math extension is loaded, using the -html_version
switch described earlier, then specifying -no_math produces a quite
different effect. Now it is the special <MATH> tags and entities which
are canceled. In their place a sophisticated scheme for parsing
mathematical expressions is used. Images are made of those sub-parts of
a formula which cannot be adequately expressed using (italicized) text
characters and <SUB> and <SUP> tags. See the subsection on mathematics
for more details.
.TP
.B -local_icons
Same as setting:
.I $LOCAL_ICONS = 1;
A copy of each of the icons actually used within the document is placed
in the directory along with the
.B HTML
files and generated images. This
allows the whole document to be fully self-contained, within this
directory; otherwise the icons must be retrieved from a (perhaps
remote) server.
It is also the default behavior if $ICONSERVER is not set.
The icons are normally copied from a subdirectory of the
.B $LATEX2HTMLDIR,
set within latex2html.config. An alternative set of
icons can be used by specifying a (relative) directory path in
$ALTERNATIVE_ICONS to where the customised images can be found.
.TP
.B -init_file <file>
Load the specified initialisation file. This
.B Perl
file will be loaded
after loading
.I $HOME/.latex2html-init,
or .latex2html-init in the local
directory, if either file exists. It is read at the time the switch is
processed, so the contents of the file may change any of the values of
any of the variables that were previously established, as well as any
default options. More than one initialisation file can be read in this
way.
.TP
.B -no_fork
Same as setting:
.I $NOFORK = 1;
When set this disables a feature in the early part of the processing
whereby some memory-intensive operations are performed by `forked'
child processes. Some single-task operating systems, such as DOS, do
not support this feature. Having
.I $NOFORK
set then ensures that
unnecessary file-handles that are needed with the forked processes, are
not consumed unnecessarily, perhaps resulting in a fatal
.B Perl
error.
.TP
.B -iso_language <type>
This enables you to specify a different language type than 'EN' to be
used in the lang attribute of the
.B HTML
document, e.g. 'en-US'.
.TP
.B -short_index
Same as setting:
.I $SHORT_INDEX = 1;
Creates shorter Index listings, using codified links; this is fully
compatible with the makeidx package.
.TP
.B -no_footnode
Same as setting:
.I $NO_FOOTNODE = 1;
Suppresses use of a separate file for footnotes; instead these are
placed at the bottom of the
.B HTML
pages where the references occur.
When this option is used, it is frequently desirable to change the
style of the marker used to indicate the presence of a footnote. This
is done as in
.B LaTeX,
using code such as follows.
\\renewcommand{\\thefootnote}{\\arabic{footnote}}
All the styles \\arabic, \\alph, \\roman, \\Alph and \\Roman are available.
.TP
.B -numbered_footnotes
Same as setting:
.I $NUMBERED_FOOTNOTES = 1;
If this is set you will get every footnote applied with a subsequent
number, to ease readability.
.TP
.B -address <author-address>
Same as setting:
.I $ADDRESS = "<author-address>";
Sign each page with this address.
See latex2html.config for an example using
.B Perl
code to automatically
include the date.
A user-defined
.B Perl
subroutine called &custom_address can be used
instead, if defined; it takes the value of
.I $ADDRESS
as a parameter,
which may be used or ignored as desired. At the time when this
subroutine will be called, variables named $depth,
.I $title,
.I $file
hold
the sectioning-level, title and filename of the
.B HTML
page being
produced;
.I $FILE
holds the name of the filename for the title-page of
the whole document.
.TP
.B -info <string>
Same as setting:
.I $INFO = "<string>";
Generate a new section ``About this document'' containing information
about the document being translated. The default is to generate such a
section with information on the original document, the date, the user
and the translator. An empty string (or the value `0') disables the
creation of this extra section.
If a non-empty string is given, it will be placed as the contents of
the ``About this document'' page instead of the default information.
.SH Switches controlling Image Generation
These switches affect whether images are created at all, whether old images
are reused on subsequent runs or new ones created afresh, and whether
anti-aliasing effects are used within the images themselves.
.TP
.B -use_dvipng
Use the dvipng program to generate png images, rather than using
dvips followed by gs. This method produces better alignment of
math formulas which extend significantly above or below
the line of text in which they are contained.
.TP
.B -nouse_pdftex
Generate intermediate images with plain latex instead of pdflatex.
If your document is written for pdflatex, run ``pdflatex'' first and
then ``latex2html''. If your document is written for plain, dvi-producing
latex, run ``latex'' first and then ``latex2html -nouse_pdftex''.
.TP
.B -use_luatex
Generate intermediate images with lualatex instead of plain latex.
Produced PDF output will then be translated into images with GhostScript.
Useful for lualatex documents which cannot be translated by latex or pdflatex.
.TP
.B -use_luadvi
Generate intermediate images with dvilualatex instead of plain latex.
Useful for dvilualatex documents which cannot be translated by latex.
.TP
.B -use_hilite
Additional support for the listings and minted packages: generate colorized
syntax highlighting of lstlisting environments and lstinline
snippets via the external pygmentize or source-highlight tool. For this option
to work, either Pygments or GNU source-highlight package must be installed.
.TP
.B -hilite_opts <string>
Additional options to pygmentize or GNU source-highlight. See the appropriate
manpage for the list of possible options, and the console output for the actual
source highlighting command lines generated by latex2html.
.TP
.B -ascii_mode
Same as setting:
.I $ASCII_MODE = $EXTERNAL_IMAGES = 1;
Use only ASCII characters and do not include any images in the final
output. With -ascii_mode the output of the translator can be used on
character-based browsers, such as lynx, which do not support inlined
images (via the <IMG> tag).
.TP
.B -nolatex
Same as setting:
.I $NOLATEX = 1;
Disable the mechanism for passing unknown environments to
.B LaTeX
for
processing. This can be thought of as ``draft mode'' which allows
faster translation of the basic document structure and text, without
fancy figures, equations or tables.
(This option has been superseded by the -no_images option, see below.)
.TP
.B -external_images
Same as setting:
.I $EXTERNAL_IMAGES = 1;
Instead of including any generated images inside the document, leave
them outside the document and provide hypertext links to them.
.TP
.B -ps_images
Same as setting:
.I $PS_IMAGES = $EXTERNAL_IMAGES = 1;
Use links to external PostScript files rather than inlined images in
the chosen graphics format.
.TP
.B -discard
Same as setting:
.I $DISCARD_PS = 1;
The temporary PostScript files are discarded immediately after they
have been used to create the image in the desired graphics format.
.TP
.B -no_images
Same as setting:
.I $NO_IMAGES = 1;
Do not attempt to produce any inlined images. The missing images can be
generated ``off-line'' by restarting
.B LaTeX2HTML
with the option
-images_only .
.TP
.B -images_only
Same as setting:
.I $IMAGES_ONLY = 1;
Try to convert any inlined images that were left over from previous
runs of
.B LaTeX2HTML.
.TP
.B -reuse <reuse_option>
Same as setting:
.I $REUSE = <reuse_option>;
This switch specifies the extent to which image files are to be shared
or recycled.
There are three valid options:
[*] 0
Do not ever share or recycle image files.
This choice also invokes an interactive session prompting the user
about what to do about a pre-existing
.B HTML
directory, if it
exists.
[*] 1
Recycle image files from a previous run if they are available,
but do not share identical images that must be created in this
run.
[*] 2
Recycle image files from a previous run and share identical images
from this run.
This is the default.
A later section provides additional information about image-reuse.
.TP
.B -no_reuse
Same as setting:
.I $REUSE = 0;
Do not share or recycle images generated during previous translations.
This is equivalent to -reuse 0 . (This will enable the initial
interactive session during which the user is asked whether to reuse the
old directory, delete its contents or quit.)
.TP
.B -antialias
Same as setting:
.I $ANTI_ALIAS = 1; (Default is 0.)
Generated images of figure environments and external PostScript files
should use anti-aliasing. By default anti-aliasing is not used with
these images, since this may interfere with the contents of the images
themselves.
.TP
.B -antialias_text
Same as setting:
.I $ANTI_ALIAS_TEXT = 1; (Default is 1.)
Generated images of typeset material such as text, mathematical
formulas, tables and the content of makeimage environments, should use
anti-aliasing effects.
The default is normally to use anti-aliasing for text, since the
resulting images are much clearer on-screen. However the default may
have been changed locally.
.TP
.B -no_antialias
Same as setting:
.I $ANTI_ALIAS = 0; (Default is 0.)
Generated images of figure environments and external PostScript files
should not use anti-aliasing with images, though the local default may
have been changed to use it.
.TP
.B -no_antialias_text
Same as setting:
.I $ANTI_ALIAS_TEXT = 0; (Default is 1.)
Generated images of typeset material should not use anti-aliasing
effects. Although on-screen images of text are definitely improved
using anti-aliasing, printed images can be badly blurred, even at
300dpi. Higher resolution printers do a much better job with the
resulting grey-scale images.
.TP
.B -white
Same as setting:
.I $WHITE_BACKGROUND = 1; (Default is 1.)
Ensures that images of figure environments have a white background.
Otherwise transparency effects may not work correctly.
.TP
.B -no_white
Same as setting:
.I $WHITE_BACKGROUND = ''; (Default is 1.)
Cancels the requirement that figure environments have a white
background.
.TP
.B -ldump
Same as setting:
.I $LATEX_DUMP = 1; (Default is 0.)
Use this if you want to speed up image processing during the 2nd and
subsequent runs of
.B LaTeX2HTML
on the same document. The translator now
produces a
.B LaTeX
format-dump of the preamble to images.tex which is
used on subsequent runs. This significantly reduces the startup time
when
.B LaTeX
reads the images.tex file for image-generation.
This process actually consumes additional time on the first run, since
.B LaTeX
is called twice -- once to create the format-dump, then again to
load and use it. The pay-off comes with the faster loading on
subsequent runs. Approximately 1 Meg of disk space is consumed by the
dump file.
.SH Switches controlling Navigation Panels
The following switches govern whether to include one or more navigation
panels on each
.B HTML
page, also which buttons to include within such a panel.
.TP
.B -no_navigation
Same as setting:
.I $NO_NAVIGATION = 1;
Disable the mechanism for putting navigation links in each page.
This overrides any settings of the
.I $TOP_NAVIGATION,
.I $BOTTOM_NAVIGATION
and
.I $AUTO_NAVIGATION
variables.
.TP
.B -top_navigation
Same as setting:
.I $TOP_NAVIGATION = 1;
Put navigation links at the top of each page.
.TP
.B -bottom_navigation
Same as setting:
.I $BOTTOM_NAVIGATION = 1;
Put navigation links at the bottom of each page as well as the top.
.TP
.B -auto_navigation
Same as setting:
.I $AUTO_NAVIGATION = 1;
Put navigation links at the top of each page. Also put one at the
bottom of the page, if the page exceeds
.I $WORDS_IN_PAGE
number of words
(default = 450).
.TP
.B -next_page_in_navigation
Same as setting:
.I $NEXT_PAGE_IN_NAVIGATION = 1;
Put a link to the next logical page in the navigation panel.
.TP
.B -previous_page_in_navigation
Same as setting:
.I $PREVIOUS_PAGE_IN_NAVIGATION = 1;
Put a link to the previous logical page in the navigation panel.
.TP
.B -contents_in_navigation
Same as setting:
.I $CONTENTS_IN_NAVIGATION = 1;
Put a link to the table-of-contents in the navigation panel if there is
one.
.TP
.B -index_in_navigation
Same as setting:
.I $INDEX_IN_NAVIGATION = 1;
Put a link to the index-page in the navigation panel if there is an
index.
.SH Switches for Linking to other documents
When processing a single stand-alone document, the switches described in
this section should not be needed at all, since the automatically generated
navigation panels, described on the previous page should generate all the
required navigation links. However if a document is to be regarded as part
of a much larger document, then links from its first and final pages, to
locations in other parts of the larger (virtual) document, need to be
provided explicitly for some of the buttons in the navigation panel.
The following switches allow for such links to other documents, by providing
the title and URL for navigation panel hyperlinks. In particular, the
``Document Segmentation'' feature necessarily makes great use of these
switches. It is usual for the text and targets of these navigation
hyperlinks to be recorded in a Makefile, to avoid tedious typing of long
command-lines having many switches.
.TP
.B -up_url <URL>
Same as setting:
.I $EXTERNAL_UP_LINK = "<URL>";
Specifies a universal resource locator (URL) to associate with the
``UP'' button in the navigation panel(s).
.TP
.B -up_title <string>
Same as setting:
.I $EXTERNAL_UP_TITLE = "<string>";
Specifies a title associated with this URL.
.TP
.B -prev_url <URL>
Same as setting:
.I $EXTERNAL_PREV_LINK = "<URL>";
Specifies a URL to associate with the ``PREVIOUS'' button in the
navigation panel(s).
.TP
.B -prev_title <string>
Same as setting:
.I $EXTERNAL_PREV_TITLE = "<string>";
Specifies a title associated with this URL.
.TP
.B -down_url <URL>
Same as setting:
.I $EXTERNAL_DOWN_LINK = "<URL>";
Specifies a URL for the ``NEXT'' button in the navigation panel(s).
.TP
.B -down_title <string>
Same as setting:
.I $EXTERNAL_DOWN_TITLE = "<string>";
Specifies a title associated with this URL.
.TP
.B -contents <URL>
Same as setting:
.I $EXTERNAL_CONTENTS = "<URL>";
Specifies a URL for the ``CONTENTS'' button, for document segments that
would not otherwise have one.
.TP
.B -index <URL>
Same as setting:
.I $EXTERNAL_INDEX = "<URL>";
Specifies a URL for the ``INDEX'' button, for document segments that
otherwise would not have an index.
.TP
.B -biblio <URL>
Same as setting:
.I $EXTERNAL_BIBLIO = "<URL>";
Specifies the URL for the bibliography page to be used, when not
explicitly part of the document itself.
Warning: On some systems it is difficult to give text-strings <string>
containing space characters, on the command-line or via a Makefile. One way
to overcome this is to use the corresponding variable. Another way is to
replace the spaces with underscores (_).
.SH Switches for Help and Tracing
The first two of the following switches are self-explanatory. When problems
arise in processing a document, the switches -debug and -verbosity will each
cause
.B LaTeX2HTML
to generate more output to the screen. These extra messages
should help to locate the cause of the problem.
.TP
.B -tmp <path>
Define a temporary directory to use for image generation. If <path> is
0, the standard temporary directory /tmp is used.
.TP
.B -h(elp)
Print out the list of all command-line options.
.TP
.B -v
Print the current version of
.B LaTeX2HTML.
.TP
.B -debug
Same as setting:
.I $DEBUG = 1;
Run in debug-mode, displaying messages and/or diagnostic information
about files read, and utilities called by
.B LaTeX2HTML.
Shows any
messages produced by these calls.
More extensive diagnostics, from the
.B Perl
debugger, can be obtained by
appending the string `-w-' to the 1st line of the latex2html (and
other)
.B Perl
script(s).
.TP
.B -verbosity <num>
Same as setting:
.I $VERBOSITY = <num>;
Display messages revealing certain aspects of the processing performed
by
.B LaTeX2HTML
on the provided input file(s). The <num> parameter can be
an integer in the range 0 to 8. Each higher value adds to the messages
produced.
.TP
0.
No special tracing; as for versions of
.B LaTeX2HTML
prior to V97.1.
.TP
1.
(This is the default.) Show section-headings and the corresponding
HTML file names, and indicators that major stages in the
processing have been completed.
.TP
2.
Print environment names and identifier numbers, and new
theorem-types. Show warnings as they occur, and indicators for
more stages of processing. Print names of files for storing
auxiliary data arrays.
.TP
3.
Print command names as they are encountered and processed; also
any unknown commands encountered while pre-processing. Show names
of new commands, environments, theorems, counters and
counter-dependencies, for each document partition.
.TP
4.
Indicate command-substitution the pre-process of
math-environments. Print the contents of unknown environments for
processing in
.B LaTeX,
both before and after reverting to
.B LaTeX
source. Show all operations affecting the values of counters. Also
show links, labels and sectioning keys, at the stages of
processing.
.TP
5.
Detail the processing in the document preamble. Show substitutions
of new environments. Show the contents of all recognised
environments, both before and after processing. Show the
cached/encoded information for the image keys, allowing two images
to be tested for equality.
.TP
6.
Show replacements of new commands, accents and wrapped commands.
.TP
7.
Trace the processing of commands in math mode; both before and
after.
.TP
8.
Trace the processing of all commands, both before and after.
The command-line option sets an initial value only. During processing
the value of
.I $VERBOSITY
can be set dynamically using the
\\htmltracing{...} command, whose argument is the desired value, or by
using the more general \\HTMLset command as follows:
\\HTMLset{VERBOSITY}{<num>}.
.SH Other Configuration Variables, without switches
The configuration variables described here do not warrant having a
command-line switch to assign values. Either they represent aspects of
.B LaTeX2HTML
that are specific to the local site, or they govern properties
that should apply to all documents, rather than something that typically
would change for the different documents within a particular sub-directory.
Normally these variables have their value set within the latex2html.config
file. In the following listing the defaults are shown, as the lines of Perl
code used to establish these values. If a different value is required, then
these can be assigned from a local .latex2html-init initialisation file,
without affecting the defaults for other users, or documents processed from
other directories.
.TP
.B $dd
holds the string to be used in file-names to delimit directories; it
is set internally to `/', unless the variable has already been given a
value within latex2html.config .
Note: This value cannot be set within a .latex2html-init initialisation
file, since its value needs to be known in order to find such a file.
.TP
.B $LATEX2HTMLDIR
Read by the install-test script from latex2html.config, its value is
inserted into the latex2html
.B Perl
script as part of the installation
process.
.TP
.B $LATEX2HTMLSTYLES = "$LATEX2HTMLDIR/styles";
Read from the latex2html.config file by install-test, its value is
checked to locate the styles/ directory.
.TP
.B $LATEX2HTMLVERSIONS = "$LATEX2HTMLDIR/versions";
The value of this variable should be set within latex2html.config to
specify the directory path where the version and extension files can be
found.
.TP
.B $ALTERNATIVE_ICONS = '';
This may contain the (relative) directory path to a set of customised
icons to be used in conjunction with the -local_icons switch.
.TP
.B $TEXEXPAND = "$LATEX2HTMLDIR/texexpand";
Read by the install-test
.B Perl
script from latex2html.config, its value
is used to locate the texexpand