EditPageHistoryDiffInfoLikePages

Annotated edit history of latex2html(1) version 2, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	LaTeX2HTML
		2	!!!LaTeX2HTML
		3	NAME
		4	SYNOPSIS
		5	DESCRIPTION
		6	CAVEAT
		7	Options controlling Titles, File-Names and Sectioning
		8	Options controlling Extensions and Special Features
		9	Switches controlling Image Generation
		10	Switches controlling Navigation Panels
		11	Switches for Linking to other documents
		12	Switches for Help and Tracing
		13	Other Configuration Variables, without switches
		14	SEE ALSO
		15	AUTHOR
		16	----
		17	!!NAME
		18
		19
2	perry	20	latex2html - translate LaTeX files to HTML (!HyperText Markup Language)
1	perry	21	!!SYNOPSIS
		22
		23
		24	__latex2html__ ''[[options]'' [[target [[target
		25	...]]
		26	!!DESCRIPTION
		27
		28
		29	This manual page explains the __LaTeX2HTML__ utility,
		30	which is a __Perl__ program that translates __LaTeX__
		31	document into __HTML__ format. For each source file given
		32	as an argument the translator will create a directory
		33	containing the corresponding HTML files. For details and
		34	examples, please consult the online html documentation, a
		35	copy of which should be available in
		36	''/usr/share/doc/latex2html/manual.ps.gz'' or
		37	''/usr/share/doc/latex2html/html/''
		38	!!CAVEAT
		39
		40
		41	This documetation has been derived from the TeX manual, and
		42	may not be uptodate. Please refer to the online manual for
		43	authoritative documentation.
		44	!!Options controlling Titles, File-Names and Sectioning
		45
		46
		47	__-t __
		48
		49
		50	Same as setting: ''$TITLE = ''
		51	Name the document using this title.
		52
		53
		54	__-short_extn__
		55
		56
		57	Same as setting: ''$SHORTEXTN = 1;'' Use a filename
		58	prefix of .htm for the produced __HTML__ files. This is
		59	particularly useful for creating pages to be stored on
		60	CD-ROM or other media, to be used with operating systems
		61	that require a 3-character extension.
		62
		63
		64	__-long_titles __
		65
		66
		67	Same as setting: ''$LONG_TITLES = '' Instead
		68	of the standard names: node1.html, node2.html,... the
		69	filenames for each __HTML__ page are constructed from the
		70	first
		71	__
		72
		73
		74	__-custom_titles__
		75
		76
		77	Same as setting: ''$CUSTOM_TITLES = 1;'' Instead of the
		78	standard names: node1.html, node2.html, ... the filenames
		79	for each __HTML__ page are constructed using a
		80	__Perl__ subroutine named custom_title_hook . The user
		81	may define his/her own version of this subroutine, within a
		82	.latex2html-init file say, to override the default (which
		83	uses the standard names). This subroutine takes the
		84	section-heading as a parameter and must return the required
		85	name, or the empty string (default).
		86
		87
		88	__-dir __
		89
		90
		91	Same as setting: ''$DESTDIR =
		92	'' Redirect the output to the specified directory. The
		93	default behaviour is to create (or reuse) a directory having
		94	the same name as the prefix of the document being
		95	processed.
		96
		97
		98	__-no_subdir__
		99
		100
		101	Same as setting: ''$NO_SUBDIR = 1;'' Place the generated
		102	__HTML__ files into the current directory. This overrides
		103	any ''$DESTDIR'' setting.
		104
		105
		106	__-prefix __
		107
		108
		109	Same as setting: ''$PREFIX = ''
		110	The
		111	''LaTeX2HTML__ to peacefully
		112	coexist in the same directory. However, do not attempt to
		113	simultaneously run multiple instances of __LaTeX2HTML__
		114	using the same output directory, else various temporary
		115	files will overwrite each other.
		116
		117
		118	__-auto_prefix__
		119
		120
		121	Same as setting: ''$AUTO_PREFIX = 1;'' Constructs the
		122	prefix as `
		123	''LaTeX__ file being processed. (Note the `-' in this
		124	prefix.) This overrides any ''$PREFIX''
		125	setting.
		126
		127
		128	__-no_auto_link__
		129
		130
		131	Same as setting: ''$NO_AUTO_LINK = 1;'' If $NO_AUTO_LINK
		132	is empty and variables ''$LINKPOINT'' and
		133	''$LINKNAME'' are defined appropriately (as is the
		134	default in the latex2html.config file), then a hard link to
		135	the main __HTML__ page is produced, using the name
		136	supplied in ''$LINKNAME.'' Typically this is index.html;
		137	on many systems a file of this name will be used, if it
		138	exists, when a browser tries to view a URL which points to a
		139	directory. On other systems a different value for
		140	''$LINKNAME'' may be appropriate. Typically
		141	''$LINKPOINT'' has value ''$FILE.html,'' but this may
		142	also be changed to match whichever HTML page is to become
		143	the target of the automatic link. Use of the -no_auto_link
		144	switch cancels this automatic linking facility, when not
		145	required for a particular document.
		146
		147
		148	__-split __
		149
		150
		151	Same as setting: ''$MAX_SPLIT_DEPTH =
		152	'' Stop splitting sections into separate files at
		153	this depth. Specifying -split 0 will put the entire document
		154	into a single __HTML__ file. See below for the different
		155	levels of sectioning. Also see the next item for how to set
		156	a ``relative'' depth for splitting.
		157
		158
		159	__-split +__
		160
		161
		162	Same as setting: ''$MAX_SPLIT_DEPTH = -
		163	'' The level at which to stop splitting
		164	sections is calculated ``relative to'' the shallowest level
		165	of sectioning that occurs within the document. For example,
		166	if the document contains section commands, but no part or
		167	chapter commands, then -split +1 will cause splitting at
		168	each section but not at any deeper level; whereas -split +2
		169	or -split +3 also split down to subsection and subsubsection
		170	commands respectively. Specifying -split +0 puts the entire
		171	document into a single __HTML__ file.
		172
		173
		174	__-link __
		175
		176
		177	Same as setting: ''$MAX_LINK_DEPTH =
		178	'' For each node, create links to child nodes down to
		179	this much deeper than the node's sectioning-level.
		180	Specifying -link 0 will show no links to child nodes from
		181	that page, -link 1 will show only the immediate descendents,
		182	etc. A value at least as big as that of the -split
		183	''HTML__ pages, this table is located at
		184	the bottom of the page, unless placed elsewhere using the
		185	tableofchildlinks command. On pages having a
		186	sectioning-level just less than the -split depth the mini
		187	table-of-contents contains links to subsections etc.
		188	occurring on the same __HTML__ page. Now the table is
		189	located at the top of this page, unless placed elsewhere
		190	using the tableofchildlinks command.
		191
		192
		193	__-toc_depth __
		194
		195
		196	Same as setting: ''$TOC_DEPTH =
		197	'' Sectioning levels down to
		198	''
		199
		200
		201	__-toc_stars__
		202
		203
		204	Same as setting: ''$TOC_STARS = 1;'' Sections created
		205	using the starred-form of sectioning commands are included
		206	within the Table-of-Contents. As with __LaTeX,__ normally
		207	such sections are not listed.
		208
		209
		210	__-show_section_numbers__
		211
		212
		213	Same as setting: ''$SHOW_SECTION_NUMBERS = 1;'' Show
		214	section numbers. By default section numbers are not shown,
		215	so as to encourage the use of particular sections as
		216	stand-alone documents. In order to be shown, section titles
		217	must be unique and must not contain inlined
		218	graphics.
		219
		220
		221	__-unsegment__
		222
		223
		224	Same as setting: ''$UNSEGMENT = 1;'' Treat a segmented
		225	document (see the section about document segmentation) like
		226	it were not segmented. This will cause the translator to
		227	concatenate all segments and process them as a whole. You
		228	might find this useful to check a segmented document for
		229	consistency. For all documents the sectioning levels
		230	referred to above are:
		231	0 document 1 part 2 chapter 3 section 4 subsection 5
		232	subsubsection 6 paragraph 7 subparagraph 8
		233	subsubparagraph
		234
		235
		236	These levels apply even when the document contains no
		237	sectioning for the shallower levels; e.g. no part or chapter
		238	commands is most common, especially when using
		239	__LaTeX's__ article document-class.
		240	!!Options controlling Extensions and Special Features
		241
		242
		243	The switches described here govern the type of __HTML__
		244	code that can be generated, and how to choose between the
		245	available options when there are alternative strategies for
		246	implementing portions of __LaTeX__ code.
		247
		248
		249	__-html_version
		250	(2.0|3.0|3.2)[[,(math|i18n|table)]*__
		251
		252
		253	Same as setting: ''$HTML_VERSION = ... ;'' This specifies
		254	both the __HTML__ version to generate, and any extra
		255	(non-standard) __HTML__ features that may be required.
		256	The version number corresponds to a published DTD for an
		257	__HTML__ standard (although 3.0 was never accepted and
		258	subsequently withdrawn). A corresponding __Perl__ file in
		259	the versions/ subdirectory is loaded; these files are named
		260	`html
		261	__LaTeX2HTML__ up to 1996. Now these
		262	extensions can be loaded with any of `2.0', `3.2' or `4.0'
		263	as the specified standard. The default version is usually
		264	set to be `3.2', within latex2html.config.
		265
		266
		267	__-no_tex_defs__
		268
		269
		270	Same as setting: ''$TEXDEFS = 0; (default is 1)'' When
		271	''$TEXDEFS'' is set (default) the file texdefs.perl will
		272	be read. This provides code to allow common TEX commands
		273	like def, newbox, newdimen and others, to be recognised,
		274	especially within the document preamble. In the case of def,
		275	the definition may even be fully interpreted, but this
		276	requires the pattern-matching to be not too complicated. If
		277	''$TEXDEFS'' is `0' or empty, then texdefs.perl will not
		278	be loaded; the translator will make no attempt to interpret
		279	any raw TEX commands. This feature is intended to enable
		280	sophisticated authors the ability to insert arbitrary TEX
		281	commands in environments that are destined to be processed
		282	by __LaTeX__ anyway; e.g. figures, theorems, pictures,
		283	etc. However this should rarely be needed, as now there is
		284	better support for these types of environment. There are now
		285	other methods to specify which chunks of code are to be
		286	passed to __LaTeX__ for explicit image-generation; see
		287	the discussion of the makeimage environment.
		288
		289
		290	__-external_file __
		291
		292
		293	Same as setting: ''$EXTERNAL_FILE = ''
		294	Specifies the prefix of the .aux file that this document
		295	should read. The .aux extension will be appended to this
		296	prefix to get the complete filename, with directory path if
		297	needed. This file could contain necessary information
		298	regarding citations, figure, table and section numbers from
		299	__LaTeX__ and perhaps other information also. Use of this
		300	switch is vital for document segments, processed separately
		301	and linked to appear as if generated from a single LaTeX
		302	document.
		303
		304
		305	__-font_size __
		306
		307
		308	Same as setting: ''$FONT_SIZE = '' This
		309	option provides better control over the font size of
		310	environments made into images using __LaTeX.__
		311	__LaTeX__
		312	recognizes; i.e. `10pt', `11pt', `12pt', etc. Default is
		313	`10pt', or whatever option may have been specified on the
		314	documentclass or documentstyle line. Whatever size is
		315	selected, it will be magnified by the installation variables
		316	''$MATH_SCALE_FACTOR, $FIGURE_SCALE_FACTOR'' and
		317	''$DISP_SCALE_FACTOR'' as appropriate. Note: This switch
		318	provides no control over the size of text on the HTML pages.
		319	Such control is subject entirely to the user's choices of
		320	settings for the browser windows.
		321
		322
		323	__-scalable_fonts__
		324
		325
		326	Same as setting: ''$SCALABLE_FONTS = 1;'' This is used
2	perry	327	when scalable fonts, such as !PostScript versions of the TEX
1	perry	328	fonts, are available for image-generation. It has the effect
		329	of setting ''$PK_GENERATION'' to `1', and
		330	''$DVIPS_MODE'' to be empty, overriding any previous
		331	settings for these variables.
		332
		333
		334	__-no_math__
		335
		336
		337	Same as setting: ''$NO_SIMPLE_MATH = 1;'' Ordinarily
		338	simple mathematical expressions are set using the ordinary
		339	text font, but italiced. When part of the expression can not
		340	be represented this way, an image is made of the whole
		341	formula. This is called ``simple math''. When
		342	''$NO_SIMPLE_MATH'' is set, then all mathematics is made
		343	into images, whether simple or not. However, if the math
		344	extension is loaded, using the -html_version switch
		345	described earlier, then specifying -no_math produces a quite
		346	different effect. Now it is the special
		347	''
		348
		349
		350	__-local_icons__
		351
		352
		353	Same as setting: ''$LOCAL_ICONS = 1;'' A copy of each of
		354	the icons actually used within the document is placed in the
		355	directory along with the __HTML__ files and generated
		356	images. This allows the whole document to be fully
		357	self-contained, within this directory; otherwise the icons
		358	must be retrieved from a (perhaps remote) server. The icons
		359	are normally copied from a subdirectory of the
		360
		361
		362	__$LATEX2HTMLDIR,__ set within latex2html.config. An
		363	alternative set of icons can be used by specifying a
		364	(relative) directory path in $ALTERNATIVE_ICONS to where the
		365	customised images can be found.
		366
		367
		368	__-init_file __
		369
		370
		371	Load the specified initialisation file. This __Perl__
		372	file will be loaded after loading
		373	''$HOME/.latex2html-init,'' or .latex2html-init in the
		374	local directory, if either file exists. It is read at the
		375	time the switch is processed, so the contents of the file
		376	may change any of the values of any of the variables that
		377	were previously established, as well as any default options.
		378	More than one initialisation file can be read in this way.
		379	[[change_begin]98.1
		380
		381
		382	__-no_fork__
		383
		384
		385	Same as setting: ''$NOFORK = 1;'' When set this disables
		386	a feature in the early part of the processing whereby some
		387	memory-intensive operations are performed by `forked' child
		388	processes. Some single-task operating systems, such as DOS,
		389	do not support this feature. Having ''$NOFORK'' set then
		390	ensures that unnecessary file-handles that are needed with
		391	the forked processes, are not consumed unnecessarily,
		392	perhaps resulting in a fatal __Perl__ error.
		393
		394
		395	__-iso_language __
		396
		397
		398	This enables you to specify a different language type than
		399	'EN' to be used in the DTD entries of the __HTML__
		400	document, e.g. 'EN.US'. [[change_end] 98.1
		401
		402
		403	__-short_index__
		404
		405
		406	Same as setting: ''$SHORT_INDEX = 1;'' Creates shorter
		407	Index listings, using codified links; this is fully
		408	compatible with the makeidx package.
		409
		410
		411	__-no_footnode__
		412
		413
		414	Same as setting: ''$NO_FOOTNODE = 1;'' Suppresses use of
		415	a separate file for footnotes; instead these are placed at
		416	the bottom of the __HTML__ pages where the references
		417	occur. When this option is used, it is frequently desirable
		418	to change the style of the marker used to indicate the
		419	presence of a footnote. This is done as in __LaTeX,__
		420	using code such as follows.
		421	renewcommand{thefootnote}{arabic{footnote}} All the styles
		422	arabic, alph, roman, Alph and Roman are available.
		423	[[change_begin]98.1
		424
		425
		426	__-numbered_footnotes__
		427
		428
		429	Same as setting: ''$NUMBERED_FOOTNOTES = 1;'' If this is
		430	set you will get every footnote applied with a subsequent
		431	number, to ease readability. [[change_end] 98.1
		432
		433
		434	__-address __
		435
		436
		437	Same as setting: ''$ADDRESS = ''
		438	Sign each page with this address. See latex2html.config for
		439	an example using __Perl__ code to automatically include
		440	the date. A user-defined __Perl__ subroutine called
		441	__$ADDRESS'' as a parameter, which may
		442	be used or ignored as desired. At the time when this
		443	subroutine will be called, variables named $depth,
		444	''$title, $file'' hold the sectioning-level, title and
		445	filename of the __HTML__ page being produced;
		446	''$FILE'' holds the name of the filename for the
		447	title-page of the whole document.
		448
		449
		450	__-info __
		451
		452
		453	Same as setting: ''$INFO = '' Generate a
		454	new section ``About this document'' containing information
		455	about the document being translated. The default is to
		456	generate such a section with information on the original
		457	document, the date, the user and the translator. An empty
		458	string (or the value `0') disables the creation of this
		459	extra section. If a non-empty string is given, it will be
		460	placed as the contents of the ``About this document'' page
		461	instead of the default information.
		462	!!Switches controlling Image Generation
		463
		464
		465	These switches affect whether images are created at all,
		466	whether old images are reused on subsequent runs or new ones
		467	created afresh, and whether anti-aliasing effects are used
		468	within the images themselves.
		469
		470
		471	__-ascii_mode__
		472
		473
		474	Same as setting: ''$ASCII_MODE = $EXTERNAL_IMAGES = 1;''
		475	Use only ASCII characters and do not include any images in
		476	the final output. With -ascii_mode the output of the
		477	translator can be used on character-based browsers, such as
		478	lynx, which do not support inlined images (via the
		479	''
		480
		481
		482	__-nolatex__
		483
		484
		485	Same as setting: ''$NOLATEX = 1;'' Disable the mechanism
		486	for passing unknown environments to __LaTeX__ for
		487	processing. This can be thought of as ``draft mode'' which
		488	allows faster translation of the basic document structure
		489	and text, without fancy figures, equations or tables. (This
		490	option has been superseded by the -no_images option, see
		491	below.)
		492
		493
		494	__-external_images__
		495
		496
		497	Same as setting: ''$EXTERNAL_IMAGES = 1;'' Instead of
		498	including any generated images inside the document, leave
		499	them outside the document and provide hypertext links to
		500	them.
		501
		502
		503	__-ps_images__
		504
		505
		506	Same as setting: ''$PS_IMAGES = $EXTERNAL_IMAGES = 1;''
2	perry	507	Use links to external !PostScript files rather than inlined
1	perry	508	images in the chosen graphics format.
		509
		510
		511	__-discard__
		512
		513
		514	Same as setting: ''$DISCARD_PS = 1;'' The temporary
2	perry	515	!PostScript files are discarded immediately after they have
1	perry	516	been used to create the image in the desired graphics
		517	format.
		518
		519
		520	__-no_images__
		521
		522
		523	Same as setting: ''$NO_IMAGES = 1;'' Do not attempt to
		524	produce any inlined images. The missing images can be
		525	generated ``off-line'' by restarting __LaTeX2HTML__ with
		526	the option -images_only .
		527
		528
		529	__-images_only__
		530
		531
		532	Same as setting: ''$IMAGES_ONLY = 1;'' Try to convert any
		533	inlined images that were left over from previous runs of
		534	__LaTeX2HTML.__
		535
		536
		537	__-reuse __
		538
		539
		540	Same as setting: ''$REUSE = '' This
		541	switch specifies the extent to which image files are to be
		542	shared or recycled. There are three valid options: [[*] 0 Do
		543	not ever share or recycle image files. This choice also
		544	invokes an interactive session prompting the user about what
		545	to do about a pre-existing __HTML__ directory, if it
		546	exists. [[*] 1 Recycle image files from a previous run if
		547	they are available, but do not share identical images that
		548	must be created in this run. [[*] 2 Recycle image files from
		549	a previous run and share identical images from this run.
		550	This is the default. A later section provides additional
		551	information about image-reuse.
		552
		553
		554	__-no_reuse__
		555
		556
		557	Same as setting: ''$REUSE = 0;'' Do not share or recycle
		558	images generated during previous translations. This is
		559	equivalent to -reuse 0 . (This will enable the initial
		560	interactive session during which the user is asked whether
		561	to reuse the old directory, delete its contents or
		562	quit.)
		563
		564
		565	__-antialias__
		566
		567
		568	Same as setting: ''$ANTI_ALIAS = 1; (Default is 0.)''
		569	Generated images of figure environments and external
2	perry	570	!PostScript files should use anti-aliasing. By default
1	perry	571	anti-aliasing is not used with these images, since this may
		572	interfere with the contents of the images
		573	themselves.
		574
		575
		576	__-antialias_text__
		577
		578
		579	Same as setting: ''$ANTI_ALIAS_TEXT = 1; (Default is
		580	1.)'' Generated images of typeset material such as text,
		581	mathematical formulas, tables and the content of makeimage
		582	environments, should use anti-aliasing effects. The default
		583	is normally to use anti-aliasing for text, since the
		584	resulting images are much clearer on-screen. However the
		585	default may have been changed locally.
		586
		587
		588	__-no_antialias__
		589
		590
		591	Same as setting: ''$ANTI_ALIAS = 0; (Default is 0.)''
		592	Generated images of figure environments and external
2	perry	593	!PostScript files should not use anti-aliasing with images,
1	perry	594	though the local default may have been changed to use
		595	it.
		596
		597
		598	__-no_antialias_text__
		599
		600
		601	Same as setting: ''$ANTI_ALIAS_TEXT = 0; (Default is
		602	1.)'' Generated images of typeset material should not use
		603	anti-aliasing effects. Although on-screen images of text are
		604	definitely improved using anti-aliasing, printed images can
		605	be badly blurred, even at 300dpi. Higher resolution printers
		606	do a much better job with the resulting grey-scale images.
		607	[[change_begin]98.1
		608
		609
		610	__-white__
		611
		612
		613	Same as setting: ''$WHITE_BACKGROUND = 1; (Default is
		614	1.)'' Ensures that images of figure environments have a
		615	white background. Otherwise transparency effects may not
		616	work correctly.
		617
		618
		619	__-no_white__
		620
		621
		622	Same as setting: ''$WHITE_BACKGROUND = ''; (Default is
		623	1.)'' Cancels the requirement that figure environments
		624	have a white background.
		625
		626
		627	__-ldump__
		628
		629
		630	Same as setting: ''$LATEX_DUMP = 1; (Default is 0.)'' Use
		631	this if you want to speed up image processing during the 2nd
		632	and subsequent runs of __LaTeX2HTML__ on the same
		633	document. The translator now produces a __LaTeX__
		634	format-dump of the preamble to images.tex which is used on
		635	subsequent runs. This significantly reduces the startup time
		636	when __LaTeX__ reads the images.tex file for
		637	image-generation. This process actually consumes additional
		638	time on the first run, since __LaTeX__ is called twice --
		639	once to create the format-dump, then again to load and use
		640	it. The pay-off comes with the faster loading on subsequent
		641	runs. Approximately 1 Meg of disk space is consumed by the
		642	dump file. [[change_end] 98.1
		643	!!Switches controlling Navigation Panels
		644
		645
		646	The following switches govern whether to include one or more
		647	navigation panels on each __HTML__ page, also which
		648	buttons to include within such a panel.
		649
		650
		651	__-no_navigation__
		652
		653
		654	Same as setting: ''$NO_NAVIGATION = 1;'' Disable the
		655	mechanism for putting navigation links in each page. This
		656	overrides any settings of the ''$TOP_NAVIGATION,
		657	$BOTTOM_NAVIGATION'' and ''$AUTO_NAVIGATION''
		658	variables.
		659
		660
		661	__-top_navigation__
		662
		663
		664	Same as setting: ''$TOP_NAVIGATION = 1;'' Put navigation
		665	links at the top of each page.
		666
		667
		668	__-bottom_navigation__
		669
		670
		671	Same as setting: ''$BOTTOM_NAVIGATION = 1;'' Put
		672	navigation links at the bottom of each page as well as the
		673	top.
		674
		675
		676	__-auto_navigation__
		677
		678
		679	Same as setting: ''$AUTO_NAVIGATION = 1;'' Put navigation
		680	links at the top of each page. Also put one at the bottom of
		681	the page, if the page exceeds ''$WORDS_IN_PAGE'' number
		682	of words (default = 450).
		683
		684
		685	__-next_page_in_navigation__
		686
		687
		688	Same as setting: ''$NEXT_PAGE_IN_NAVIGATION = 1;'' Put a
		689	link to the next logical page in the navigation
		690	panel.
		691
		692
		693	__-previous_page_in_navigation__
		694
		695
		696	Same as setting: ''$PREVIOUS_PAGE_IN_NAVIGATION = 1;''
		697	Put a link to the previous logical page in the navigation
		698	panel.
		699
		700
		701	__-contents_in_navigation__
		702
		703
		704	Same as setting: ''$CONTENTS_IN_NAVIGATION = 1;'' Put a
		705	link to the table-of-contents in the navigation panel if
		706	there is one.
		707
		708
		709	__-index_in_navigation__
		710
		711
		712	Same as setting: ''$INDEX_IN_NAVIGATION = 1;'' Put a link
		713	to the index-page in the navigation panel if there is an
		714	index.
		715	!!Switches for Linking to other documents
		716
		717
		718	When processing a single stand-alone document, the switches
		719	described in this section should not be needed at all, since
		720	the automatically generated navigation panels, described on
		721	the previous page should generate all the required
		722	navigation links. However if a document is to be regarded as
		723	part of a much larger document, then links from its first
		724	and final pages, to locations in other parts of the larger
		725	(virtual) document, need to be provided explicitly for some
		726	of the buttons in the navigation panel. The following
		727	switches allow for such links to other documents, by
		728	providing the title and URL for navigation panel hyperlinks.
		729	In particular, the ``Document Segmentation'' feature
		730	necessarily makes great use of these switches. It is usual
		731	for the text and targets of these navigation hyperlinks to
		732	be recorded in a Makefile, to avoid tedious typing of long
		733	command-lines having many switches.
		734
		735
		736	__-up_url __
		737
		738
		739	Same as setting: ''$EXTERNAL_UP_LINK = ''
		740	Specifies a universal resource locator (URL) to associate
		741	with the ``UP'' button in the navigation
		742	panel(s).
		743
		744
		745	__-up_title __
		746
		747
		748	Same as setting: ''$EXTERNAL_UP_TITLE =
		749	'' Specifies a title associated with this
		750	URL.
		751
		752
		753	__-prev_url __
		754
		755
		756	Same as setting: ''$EXTERNAL_PREV_LINK = ''
		757	Specifies a URL to associate with the ``PREVIOUS'' button in
		758	the navigation panel(s).
		759
		760
		761	__-prev_title __
		762
		763
		764	Same as setting: ''$EXTERNAL_PREV_TITLE =
		765	'' Specifies a title associated with this
		766	URL.
		767
		768
		769	__-down_url __
		770
		771
		772	Same as setting: ''$EXTERNAL_DOWN_LINK = ''
		773	Specifies a URL for the ``NEXT'' button in the navigation
		774	panel(s).
		775
		776
		777	__-down_title __
		778
		779
		780	Same as setting: ''$EXTERNAL_DOWN_TITLE =
		781	'' Specifies a title associated with this
		782	URL.
		783
		784
		785	__-contents __
		786
		787
		788	Same as setting: ''$EXTERNAL_CONTENTS = ''
		789	Specifies a URL for the ``CONTENTS'' button, for document
		790	segments that would not otherwise have one.
		791
		792
		793	__-index __
		794
		795
		796	Same as setting: ''$EXTERNAL_INDEX = ''
		797	Specifies a URL for the ``INDEX'' button, for document
		798	segments that otherwise would not have an
		799	index.
		800
		801
		802	__-biblio __
		803
		804
		805	Same as setting: ''$EXTERNAL_BIBLIO = ''
		806	Specifies the URL for the bibliography page to be used, when
		807	not explicitly part of the document itself. Warning: On some
		808	systems it is difficult to give text-strings
		809	''
		810	!!Switches for Help and Tracing
		811
		812
		813	The first two of the following switches are
		814	self-explanatory. When problems arise in processing a
		815	document, the switches -debug and -verbosity will each cause
		816	__LaTeX2HTML__ to generate more output to the screen.
		817	These extra messages should help to locate the cause of the
		818	problem.
		819
		820
		821	__-tmp __
		822
		823
		824	Define a temporary directory to use for image generation. If
		825
		826
		827	__-h(elp)__
		828
		829
		830	Print out the list of all command-line options.
		831
		832
		833	__-v__
		834
		835
		836	Print the current version of __LaTeX2HTML.__
		837
		838
		839	__-debug__
		840
		841
		842	Same as setting: ''$DEBUG = 1;'' Run in debug-mode,
		843	displaying messages and/or diagnostic information about
		844	files read, and utilities called by __LaTeX2HTML.__ Shows
		845	any messages produced by these calls. More extensive
		846	diagnostics, from the __Perl__ debugger, can be obtained
		847	by appending the string `-w-' to the 1st line of the
		848	latex2html (and other) __Perl__ script(s).
		849
		850
		851	__-verbosity __
		852
		853
		854	Same as setting: ''$VERBOSITY = '' Display
		855	messages revealing certain aspects of the processing
		856	performed by __LaTeX2HTML__ on the provided input
		857	file(s). The
		858	__
		859
		860
		861	0.
		862
		863
		864	No special tracing; as for versions of __LaTeX2HTML__
		865	prior to V97.1.
		866
		867
		868	1.
		869
		870
		871	(This is the default.) Show section-headings and the
		872	corresponding HTML file names, and indicators that major
		873	stages in the processing have been completed.
		874
		875
		876	2.
		877
		878
		879	Print environment names and identifier numbers, and new
		880	theorem-types. Show warnings as they occur, and indicators
		881	for more stages of processing. Print names of files for
		882	storing auxiliary data arrays.
		883
		884
		885	3.
		886
		887
		888	Print command names as they are encountered and processed;
		889	also any unknown commands encountered while pre-processing.
		890	Show names of new commands, environments, theorems, counters
		891	and counter-dependencies, for each document
		892	partition.
		893
		894
		895	4.
		896
		897
		898	Indicate command-substitution the pre-process of
		899	math-environments. Print the contents of unknown
		900	environments for processing in __LaTeX,__ both before and
		901	after reverting to __LaTeX__ source. Show all operations
		902	affecting the values of counters. Also show links, labels
		903	and sectioning keys, at the stages of
		904	processing.
		905
		906
		907	5.
		908
		909
		910	Detail the processing in the document preamble. Show
		911	substitutions of new environments. Show the contents of all
		912	recognised environments, both before and after processing.
		913	Show the cached/encoded information for the image keys,
		914	allowing two images to be tested for equality.
		915
		916
		917	6.
		918
		919
		920	Show replacements of new commands, accents and wrapped
		921	commands.
		922
		923
		924	7.
		925
		926
		927	Trace the processing of commands in math mode; both before
		928	and after.
		929
		930
		931	8.
		932
		933
		934	Trace the processing of all commands, both before and after.
		935	The command-line option sets an initial value only. During
		936	processing the value of ''$VERBOSITY'' can be set
		937	dynamically using the htmltracing{...} command, whose
		938	argument is the desired value, or by using the more general
		939	HTMLset command as follows:
		940	HTMLset{VERBOSITY}{''
		941	!!Other Configuration Variables, without switches
		942
		943
		944	The configuration variables described here do not warrant
		945	having a command-line switch to assign values. Either they
		946	represent aspects of __LaTeX2HTML__ that are specific to
		947	the local site, or they govern properties that should apply
		948	to all documents, rather than something that typically would
		949	change for the different documents within a particular
		950	sub-directory. Normally these variables have their value set
		951	within the latex2html.config file. In the following listing
		952	the defaults are shown, as the lines of Perl code used to
		953	establish these values. If a different value is required,
		954	then these can be assigned from a local .latex2html-init
		955	initialisation file, without affecting the defaults for
		956	other users, or documents processed from other
		957	directories.
		958
		959
		960	__$dd__
		961
		962
		963	holds the string to be used in file-names to delimit
		964	directories; it is set internally to `/', unless the
		965	variable has already been given a value within
		966	latex2html.config . Note: This value cannot be set within a
		967	.latex2html-init initialisation file, since its value needs
		968	to be known in order to find such a file.
		969
		970
		971	__$LATEX2HTMLDIR__
		972
		973
		974	Read by the install-test script from latex2html.config, its
		975	value is inserted into the latex2html __Perl__ script as
		976	part of the installation process.
		977
		978
		979	__$LATEX2HTMLSTYLES = $LATEX2HTMLDIR/styles
		980	;__
		981
		982
		983	Read from the latex2html.config file by install-test, its
		984	value is checked to locate the styles/
		985	directory.
		986
		987
		988	__$LATEX2HTMLVERSIONS = $LATEX2HTMLDIR/versions
		989	;__
		990
		991
		992	The value of this variable should be set within
		993	latex2html.config to specify the directory path where the
		994	version and extension files can be found.
		995
		996
		997	__$ALTERNATIVE_ICONS = '';__
		998
		999
		1000	This may contain the (relative) directory path to a set of
		1001	customised icons to be used in conjunction with the
		1002	-local_icons switch.
		1003
		1004
		1005	__$TEXEXPAND = $LATEX2HTMLDIR/texexpand ;__
		1006
		1007
		1008	Read by the install-test __Perl__ script from
		1009	latex2html.config, its value is used to locate the texexpand
		1010	__Perl__ script.
		1011
		1012
		1013	__$PSTOIMG = $LATEX2HTMLDIR/pstoimg ;__
		1014
		1015
		1016	Read by the install-test __Perl__ script from
		1017	latex2html.config, its value is used to locate the pstoimg
		1018	__Perl__ script.
		1019
		1020
		1021	__$IMAGE_TYPE = '__
		1022
		1023
		1024	Set in latex2html.config, the currently supported
		1025
		1026
		1027	__$DVIPS = 'dvips';__
		1028
		1029
		1030	Read from latex2html.config by install-test, its value is
		1031	checked to locate the dvips program or script. There could
		1032	be several reasons to change the value here: o add a switch
		1033	-P
		1034
		1035
		1036	__$PK_GENERATION = 1;__
		1037
		1038
		1039	This variable must be set, to initiate font-generation;
		1040	otherwise fonts will be scaled from existing resources on
		1041	the local system. In particular this variable must not be
2	perry	1042	set, if one wishes to use !PostScript fonts or other scalable
1	perry	1043	font resources (see the -scalable_fonts
		1044	switch).
		1045
		1046
		1047	__$DVIPS_MODE = 'toshiba';__
		1048
		1049
		1050	The mode given here must be available in the modes.mf file,
		1051	located with the Metafont resource files, perhaps in the
		1052	misc/ subdirectory.
		1053
		1054
		1055	__$METAFONT_DPI = 180;__
		1056
		1057
		1058	The required resolution, in dots-per-inch, should be listed
		1059	specifically within the MakeTeXPK script, called by dvips to
		1060	invoke Metafont with the correct parameters for the required
		1061	fonts.
		1062
		1063
		1064	__$LATEX = 'latex';__
		1065
		1066
		1067	Read from latex2html.config by install-test, its value is
		1068	checked to locate the latex program or script. If
		1069	__LaTeX__ is having trouble finding style-files and/or
		1070	packages, then the default command can be prepended with
		1071	other commands to set environment variables intended to
		1072	resolve these difficulties; e.g. ''$LATEX = 'setenv
		1073	TEXINPUTS '' There are
		1074	several variables to help control exactly which files are
		1075	read by __LaTeX2HTML__ and by __LaTeX__ when
		1076	processing images:
		1077
		1078
		1079	__$TEXINPUTS__
		1080
		1081
		1082	This is normally set from the environment variable of the
		1083	same name. If difficulties occur so that styles and packages
		1084	are not being found, then extra paths can be specified here,
		1085	to resolve these difficulties.
		1086
		1087
		1088	__$DONT_INCLUDE__
		1089
		1090
		1091	This provides a list of filenames and extensions to not
		1092	include, even if requested to do so by an input or include
		1093	command. (Consult latex2html.config for the default
		1094	list.)
		1095
		1096
		1097	__$DO_INCLUDE = '';__
		1098
		1099
		1100	List of exceptions within the ''$DONT_INCLUDE'' list.
		1101	These files are to be read if requested by an input or
		1102	include command.
		1103
		1104
		1105	__$ICONSERVER = '__
		1106
		1107
		1108	This is used to specify a URL to find the standard icons, as
		1109	used for the navigation buttons. Names for the specific
		1110	images size, as well as size information, can be found in
		1111	latex2html.config. The icons themselves can be replaced by
		1112	customised versions, provided this information is correctly
		1113	updated and the location of the customised images specified
		1114	as the value of $ICONSERVER. When the -local_icons switch is
		1115	used, so that a copy of the icons is placed with the
		1116	__HTML__ files and other generated images, the value of
		1117	$ICONSERVER is not needed within the __HTML__ files
		1118	themselves. However it is needed to find the original icons
		1119	to be copied to the local directory.
		1120
		1121
		1122	__$NAV_BORDER = __
		1123
		1124
		1125	The value given here results in a border, measured in
		1126	points, around each icon. A value of `0' is common, to
		1127	maintain strict alignment of inactive and active buttons in
		1128	the control panels.
		1129
		1130
		1131	__$LINKNAME = '__
		1132
		1133
		1134	This is used when the ''$NO_AUTO_LINK'' variable is
		1135	empty, to allow a URL to the working directory to be
		1136	sufficient to reach the main page of the completed document.
		1137	It specifies the name of the __HTML__ file which will be
		1138	automatically linked to the directory name. The value of
		1139	''$EXTN'' is .html unless ''$SHORTEXTN'' is set, in
		1140	which case it is .htm .
		1141
		1142
		1143	__$LINKPOINT = '__
		1144
		1145
		1146	This specifies the name of the __HTML__ file to be
		1147	duplicated, or symbolically linked, with the name specified
		1148	in ''$LINKNAME.'' At the appropriate time the value of
		1149	''$FILE'' is the document name, which usually coincides
		1150	with the name of the working directory.
		1151
		1152
		1153	__$CHARSET = 'iso_8859_1';__
		1154
		1155
		1156	This specifies the character set used within the __HTML__
		1157	pages produced by __LaTeX2HTML.__ If no value is set in a
		1158	configuration or initialisation file, the default value will
		1159	be assumed. The lowercase form ''$charset'' is also
		1160	recognised, but this is overridden by the uppercase
		1161	form.
		1162
		1163
		1164	__$ACCENT_IMAGES = 'large';__
		1165
		1166
		1167	Accented characters that are not part of the ISO-Latin fonts
		1168	can be generated by making an image using __LaTeX.__ This
		1169	variable contains a (comma-separated) list of __LaTeX__
		1170	commands for setting the style to be used when these images
		1171	are made. If the value of this variable is empty then the
		1172	accent is simply ignored, using an un-accented font
		1173	character (not an image) instead. Within the color.perl
		1174	package, the following variables are used to identify the
		1175	names of files containing specifications for named colors.
		1176	Files having these names are provided, in the
		1177	''$LATEX2HTMLSTYLES'' directory, but they could be moved
		1178	elsewhere, or replaced by alternative files having different
		1179	names. In such a case the values of these variables should
		1180	be altered accordingly. $RGBCOLORFILE = 'rgb.txt';
		1181	$CRAYOLAFILE = 'crayola.txt'; The following variables may
		1182	well be altered from the system defaults, but this is best
		1183	done using a local .latex2html-init initialisation file, for
		1184	overall consistency of style within documents located at the
		1185	same site, or sites in close proximity.
		1186
		1187
		1188	__$default_language = 'english';__
		1189
		1190
		1191	This establishes which language code is to be placed within
		1192	the
		1193	HTML__ pages produced. Loading a
		1194	package for an alternative language can be expected to
		1195	change the value of this variable. See also the
		1196	''$TITLES_LANGUAGE'' variable, described
		1197	next.
		1198
		1199
		1200	__$TITLES_LANGUAGE = 'english';__
		1201
		1202
		1203	This variable is used to specify the actual strings used for
		1204	standard document sections, such as ``Contents'',
		1205	``References'', ``Table of Contents'', etc. Support for
		1206	French and German titles is available in corresponding
		1207	packages. Loading such a package will normally alter the
		1208	value of this variable, as well as the
		1209	''$default_language'' variable described
		1210	above.
		1211
		1212
		1213	__$WORDS_IN_NAVIGATION_PANEL_TITLES = 4;__
		1214
		1215
		1216	Specifies how many words to use from section titles, within
		1217	the textual hyperlinks which accompany the navigation
		1218	buttons.
		1219
		1220
		1221	__$WORDS_IN_PAGE = 450;__
		1222
		1223
		1224	Specifies the minimum page length required before a
		1225	navigation panel is placed at the bottom of a page, when the
		1226	''$AUTO_NAVIGATION'' variable is set.
		1227
		1228
		1229	__$CHILDLINE = __
		1230
		1231
		1232	This gives the __HTML__ code to be placed between the
		1233	child-links table and the ordinary contents of the page on
		1234	which it occurs.
		1235
		1236
		1237	__$NETSCAPE_HTML = 0;__
		1238
		1239
		1240	When set, this variable specifies that __HTML__ code may
		1241	be present which does not conform to any official standard.
		1242	This restricts the contents of any
		1243	__
		1244
		1245
		1246	__$BODYTEXT = '';__
		1247
		1248
		1249	The value of this variable is used within the
		1250
		1251
		1252	__$INTERLACE = 1;__
		1253
		1254
		1255	When set, interlaced images should be produced. This
		1256	requires graphics utilities to be available to perform the
		1257	interlacing operation.
		1258
		1259
		1260	__$TRANSPARENT_FIGURES = 1;__
		1261
		1262
		1263	When set, the background of images should be made
		1264	transparent; otherwise it is white. This requires graphics
		1265	utilities to be available which can specify the color to be
		1266	made transparent.
		1267
		1268
		1269	__$FIGURE_SCALE_FACTOR = 1.6;__
		1270
		1271
		1272	Scale factor applied to all images of figure and other
		1273	environments, when being made into an image. Note that this
		1274	does not apply to recognised mathematics environments, which
		1275	instead use the contents of ''$MATH_SCALE_FACTOR'' and
		1276	$DISP_SCALE_FACTOR to specify scaling.
		1277
		1278
		1279	__$MATH_SCALE_FACTOR = 1.6;__
		1280
		1281
		1282	Scale factor applied to all images of mathematics, both
		1283	inline and displayed. A value of 1.4 is a good alternative,
		1284	with anti-aliased images.
		1285
		1286
		1287	__$DISP_SCALE_FACTOR = 1;__
		1288
		1289
		1290	Extra scale factor applied to images of displayed math
		1291	environments. When set, this value multiplies
		1292	''$MATH_SCALE_FACTOR'' to give the total scaling. A value
		1293	of `1.2' is a good choice to accompany $MATH_SCALE_FACTOR =
		1294	1.4;.
		1295
		1296
		1297	__$EXTRA_IMAGE_SCALE__
		1298
		1299
		1300	This may hold an extra scale factor that can be applied to
		1301	all generated images. When set, it specifies that a scaling
		1302	of ''$EXTRA_IMAGE_SCALE'' be applied when images are
		1303	created, but to have their height and width recorded as the
		1304	un-scaled size. This is to coax browsers into scaling the
		1305	(usually larger) images to fit the desired size; when
		1306	printed a better quality can be obtained. Values of `1.5'
		1307	and `2' give good print quality at 600dpi.
		1308
		1309
		1310	__$PAPERSIZE = 'a5';__
		1311
		1312
		1313	Specifies the size of a page for typesetting figures or
		1314	displayed math, when an image is to be generated. This
		1315	affects the lengths of lines of text within images. Since
		1316	images of text or mathematics should use larger sizes than
		1317	when printed, else clarity is lost at screen resolutions,
		1318	then a smaller paper-size is generally advisable. This is
		1319	especially so if both the $MATH_SCALE_FACTOR and
		1320	''$DISP_SCALE_FACTOR'' scaling factors are being used,
		1321	else some images may become excessively large, including a
		1322	lot of blank space.
		1323
		1324
		1325	__$LINE_WIDTH = 500;__
		1326
		1327
		1328	Formerly specified the width of an image, when the contents
		1329	were to be right- or center-justified. (No longer
		1330	used.)
		1331
		1332
		1333	The following variables are used to access the utilities
		1334	required during image-generation. File and program locations
		1335	on the local system are established by the configure-pstoimg
		1336	__Perl__ script and stored within
		1337	''$LATEX2HTMLDIR/local.pm'' as __Perl__ code, to be
		1338	read by pstoimg when required. After running the
		1339	configure-pstoimg Perl script it should not be necessary to
		1340	alter the values obtained. Those shown below are what
		1341	happens on the author's system; they are for illustration
		1342	only and do not represent default values.
		1343
		1344
		1345	$GS_LIB = '/usr/local/share/ghostscript/4.02'; $PNMCAT =
		1346	'/usr/local/bin/pnmcat'; $PPMQUANT =
		1347	'/usr/local/bin/ppmquant'; $PNMFLIP =
		1348	'/usr/local/bin/pnmflip'; $PPMTOGIF =
		1349	'/usr/local/bin/ppmtogif'; $HOWTO_TRANSPARENT_GIF =
		1350	'netpbm'; $GS_DEVICE = 'pnmraw'; $GS = '/usr/local/bin/gs';
		1351	$PNMFILE = '/usr/local/bin/pnmfile'; $HOWTO_INTERLACE_GIF =
		1352	'netpbm'; $PBMMAKE = '/usr/local/bin/pbmmake'; $PNMCROP =
		1353	'/usr/local/bin/pnmcrop'; $TMP = '/usr/var/tmp'; The
		1354	following variables are no longer needed, having been
		1355	replaced by the more specific information obtained using the
		1356	Perl script configure-pstoimg. $USENETPBM = 1; $PBMPLUSDIR =
		1357	'/usr/local/bin';
		1358	!!SEE ALSO
		1359
		1360
		1361	latex(1)
		1362	!!AUTHOR
		1363
		1364
		1365	Nikos Drakos, Computer Based Learning Unit, University of
		1366	Leeds
		1367	----