Hypertext Extensions to L^ATEX

This section describes how you can define hypertext entries in your HTML documents from within your L^ATEX source, as well as other effects available in HTML for which there need be no direct L^ATEX analog for a printed document. These are implemented as new L^ATEX commands which have special meaning during the translation by L^ATEX2HTML into HTML, but are mostly ignored when processed by L^ATEX.

The new commands described in the sections below are defined mainly in the html package, with L^ATEX definitions in the file html.sty, which is part of the L^ATEX2HTML distribution. It must be included in any L^ATEX document using these features, by one of the following methods:

• including html as an optional argument to \documentstyle in L^ATEX2.09;
• including html in a L^ATEX2_e \usepackage command.

It is not sufficient to load the style file via an \input or \include command, such as \input html.sty. This will load the required definitions for L^ATEX, but will not load the html.perl package file for L^ATEX2HTML.

Warning: Some of these features, but not all, are also available with L^ATEX2.09.
Users of L^ATEX2HTML are strongly advised to upgrade their L^ATEX installations to L^ATEX2_e.

Several new environments are defined, in particular for specifying large (or small) sections of the text which are appropriate to only one version of the document--either the HTML or the L^ATEX typeset version.

\begin{rawhtml}

for including raw HTML tags and SGML-like markup.

\begin{htmlonly}

for material intended for the HTML pages only.

\begin{latexonly}

for material intended for the L^ATEX version only.
Note that any macro-definitions or changes to counter-values are local to within this environment.

%begin{latexonly}

for material intended for the L^ATEX version only.
Macro-definitions and changes to counter-values are retained outside of this (pseudo-)environment.

\begin{imagesonly}

for material intended to be used in the images.tex file only.

\begin{comment}

for user-comments only, currently ignored in both the HTML and L^ATEX versions.
(To put HTML comments into the HTML files, use the rawhtml environment.)

\begin{makeimage}

creates an image of its contents, as typeset by L^ATEX.
This is also used to prevent an image being made of the complete contents of a figure environment, allowing more natural processing.

\begin{htmllist}

defined in htmllist.sty and htmllist.perl, this produces coloured balls tagging the items in a descriptive list, as used throughout this manual.

Warning: When using these environments it is important that the closing delimiter, \end{htmlonly} say, occurs on a line by itself with no preceding spaces, <tab>s or any other characters. (Otherwise L^ATEX will not recognise the intended end of the environment when processing for the .dvi version.) Similarly there should be nothing on the same line after the opening environment delimiter, \begin{htmlonly} say.

The following commands are defined for L^ATEX in html.sty.
Corresponding Perl implementations are either in html.perl or in the latex2html script itself.

\latextohtml

expands to the name L^ATEX2HTML, of this translator;

\htmladdnormallink

creates a (perhaps named) textual hyperlink to a specified <URL>;

\htmladdnormallinkfoot

same as \htmladdnormallink, but L^ATEX also prints the <URL> in a footnote;

\htmladdimg

places an image (perhaps aligned) on the HTML page;
ignored by L^ATEX.

\hyperref

creates a textual hyperlink to where a \label command occurred within the same document.
This is the recommended substitute for L^ATEX's \ref command.

\htmlref

creates a textual hyperlink to the place where a \label command occurred; no reference is printed in the L^ATEX version.

\hypercite

creates a textual hyperlink to the bibliography page where citation details are shown.
This is the recommended substitute for L^ATEX's \cite command.

\htmlcite

creates a textual hyperlink to the bibliography page where citation details are shown; no citation marker is printed in the L^ATEX version.

\externalref

creates a textual hyperlink to where a \label command occurred within a different document that has also been processed by L^ATEX2HTML;
ignored in L^ATEX.

\externalcite

creates a textual hyperlink to where a reference occurs in a bibliography page from a different document that has also been processed by L^ATEX2HTML; ignored in L^ATEX.

\externallabels

allows hypertext links to a different document; ignored in L^ATEX.

The following commands, also defined for L^ATEX in html.sty, are normally used only when creating segmented documents, see a later page.

\segment

directs that an \input file <file> should be regarded as a separate ``segment'' of a larger L^ATEX2HTML document. In L^ATEX the file is input as usual, after counter values have first been written to a file, named <file>.ptr.

\startdocument

tells L^ATEX2HTML where the end of the preamble occurs for a document segment; ignored in L^ATEX.
(A segment cannot have a \begin{document} command, unless it is shielded from L^ATEX within an htmlonly environment.)

\internal

reads internal information from another document, so that symbolic references can be treated as if part of the current document; ignored in L^ATEX.

\htmlhead

places a sectional heading on a HTML page; used mainly with the document segmentation feature.
It is ignored in L^ATEX.

\htmlnohead

suppresses the section-heading for a document segment; ignored in L^ATEX.

\segmentcolor

read from the .ptr file, this sets the text color for a document segment;
ignored in L^ATEX.

\segmentpagecolor

read from the .ptr file, this sets the background color for a document segment;
ignored in L^ATEX.

The following commands are shorthand forms for some of the ``conditional'' environments listed above.

\html

for putting small pieces of text into the HTML version only;

\latex

for putting small pieces of text into the L^ATEX version only;

\latexhtml

puts one piece of text into the L^ATEX version, another into the HTML version.

The following commands implement effects on the HTML pages for which there is no direct L^ATEX counterpart. Most of these commands are discussed in detail in a later section.

\HTMLcode

a general command for placing raw HTML tags, with attributes and contents;
tags and attributes are ignored in L^ATEX, but not the contents.

\htmlrule

places a (perhaps styled) horizontal line on the HTML page;
ignored in L^ATEX.

\strikeout

places text between <STRIKE>...</STRIKE> tags; ignored in L^ATEX.

\htmlimage

used for fine control over the size of individual images, and other graphics effects (e.g. making a `thumbnail' version);
ignored in L^ATEX.

\htmlborder

places a border around the contents of an environment, but placing the environment as a cell inside a <TABLE>;
ignored in L^ATEX.

\tableofchildlinks

determines where the table of childlinks should be placed on the HTML page;
ignored in L^ATEX.

\htmlinfo

determines where the ``About this document...'' information should be placed;
ignored in L^ATEX.

\htmladdtonavigation

appends a button to the navigation panels; ignored in L^ATEX.

\bodytext

allows the contents of the <BODY ...> tag to be set explicitly for the current and subsequent HTML pages;
ignored in L^ATEX.

\htmlbody

allows an attribute to be added or changed within the <BODY ...> tag of HTML;
ignored in L^ATEX.

\htmlbase

Allows a URL to be specified within the <BASE ...> tag for all the HTML pages produced;
ignored in L^ATEX.

\htmltracing{<level>}

specifies that extra tracing messages be generated, according to the <level>;
ignored in L^ATEX.

\htmltracenv{<level>}

same as \htmltracing except that this command is evaluated in sequence with environments;
ignored in L^ATEX.

\HTMLset

programmer's device, allowing an arbitrary Perl variable to be set or changed dynamically during the L^ATEX2HTML processing;
ignored in L^ATEX.

\HTMLsetenv

Same as the preceding \HTMLset command, except that this one is processed in order, as if it were an environment;
ignored in L^ATEX.

Most of the new environments listed above can also be used with delimiter macros \<env-name>...\end<env-name>. This alternative style, which is common with A_MS-TEX, is discouraged for general L^ATEX usage (even by the A_MS itself) in favour of the usual \begin{<env-name>}...\end{<env-name>} markup notation. (Safety features that are available with the usual \begin...\end mechanism may not always work in the best way with this alternative style of environment delimiter. These comments apply to both the L^ATEX and L^ATEX2HTML processing.)

\rawhtml...\endrawhtml

old A_MS-style variant of rawhtml environment.

\htmlonly...\endhtmlonly

old A_MS-style variant of htmlonly environment.

\latexonly...\endlatexonly

old A_MS-style variant of latexonly environment.

\imagesonly...\endimagesonly

old A_MS-style variant of imagesonly environment.

\comment...\endcomment

old A_MS-style variant of comment environment.

Warning: These `pseudo'-environments are not as reliable as their L^ATEX counterparts. In particular, the \begin<env-name> and \end<env-name> commands should appear on lines by themselves, preferably with no preceding spaces or <tab> characters. This requirement is analogous to the warning for conditional environments.