Next: Hyper-links in LATEX Up: LaTeX2HTML Previous: Environments_and_Special_Features

## Hypertext Extensions to LATEX

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

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

96.1
• including html as an optional argument to \documentstyle in LATEX2.09;
• including html in a LATEX2e \usepackage command.
96.1
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 LATEX, but will not load the html.perl package file for LATEX2HTML.

Warning: Some of these features, but not all, are also available with LATEX2.09.
Users of LATEX2HTML are strongly advised to upgrade their LATEX installations to LATEX2e.

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 LATEX 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 LATEX 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 LATEX 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 LATEX versions.
(To put HTML comments into the HTML files, use the rawhtml environment.)
\begin{makeimage}
creates an image of its contents, as typeset by LATEX.
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 LATEX 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 LATEX in html.sty.
Corresponding Perl implementations are either in html.perl or in the latex2html script itself.

\latextohtml
expands to the name LATEX2HTML, of this translator;
creates a (perhaps named) textual hyperlink to a specified <URL>;
same as \htmladdnormallink, but LATEX also prints the <URL> in a footnote;
places an image (perhaps aligned) on the HTML page;
ignored by LATEX.
\hyperref
creates a textual hyperlink to where a \label command occurred within the same document.
This is the recommended substitute for LATEX's \ref command.
\htmlref
creates a textual hyperlink to the place where a \label command occurred; no reference is printed in the LATEX version.
\hypercite
creates a textual hyperlink to the bibliography page where citation details are shown.
This is the recommended substitute for LATEX's \cite command.
\htmlcite
creates a textual hyperlink to the bibliography page where citation details are shown; no citation marker is printed in the LATEX version.
\externalref
creates a textual hyperlink to where a \label command occurred within a different document that has also been processed by LATEX2HTML;
ignored in LATEX.
\externalcite
creates a textual hyperlink to where a reference occurs in a bibliography page from a different document that has also been processed by LATEX2HTML; ignored in LATEX.
\externallabels
allows hypertext links to a different document; ignored in LATEX.

The following commands, also defined for LATEX 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 LATEX2HTML document. In LATEX the file is input as usual, after counter values have first been written to a file, named <file>.ptr.
\startdocument
tells LATEX2HTML where the end of the preamble occurs for a document segment; ignored in LATEX.
(A segment cannot have a \begin{document} command, unless it is shielded from LATEX 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 LATEX.
places a sectional heading on a HTML page; used mainly with the document segmentation feature.
It is ignored in LATEX.
suppresses the section-heading for a document segment; ignored in LATEX.
\segmentcolor
read from the .ptr file, this sets the text color for a document segment;
ignored in LATEX.
\segmentpagecolor
read from the .ptr file, this sets the background color for a document segment;
ignored in LATEX.

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 LATEX version only;
\latexhtml
puts one piece of text into the LATEX version, another into the HTML version.

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

\HTML
a general command for placing raw HTML tags, with attributes and contents;
tags and attributes are ignored in LATEX, but not the contents.
\htmlrule
places a (perhaps styled) horizontal line on the HTML page;
ignored in LATEX.
\strikeout
places text between <STRIKE>...</STRIKE> tags; ignored in LATEX.
\htmlimage
used for fine control over the size of individual images, and other graphics effects (e.g. making a thumbnail' version);
ignored in LATEX.
\htmlborder
places a border around the contents of an environment, but placing the environment as a cell inside a <TABLE>;
ignored in LATEX.
determines where the table of childlinks should be placed on the HTML page;
ignored in LATEX.
\htmlinfo
determines where the About this document...'' information should be placed;
ignored in LATEX.
appends a button to the navigation panels; ignored in LATEX.
\bodytext
allows the contents of the <BODY ...> tag to be set explicitly for the current and subsequent HTML pages;
ignored in LATEX.
\htmlbody
allows an attribute to be added or changed within the <BODY ...> tag of HTML;
ignored in LATEX.
\htmlbase
Allows a URL to be specified within the <BASE ...> tag for all the HTML pages produced;
ignored in LATEX.
\htmltracing{<level>}
specifies that extra tracing messages be generated, according to the <level>;
ignored in LATEX.
\htmltracenv{<level>}
same as \htmltracing except that this command is evaluated in sequence with environments;
ignored in LATEX.
\HTMLset
programmer's device, allowing an arbitrary Perl variable to be set or changed dynamically during the LATEX2HTML processing;
ignored in LATEX.
\HTMLsetenv
Same as the preceding \HTMLset command, except that this one is processed in order, as if it were an environment;
ignored in LATEX.

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 AMS-TEX, is discouraged for general LATEX usage (even by the AMS 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 LATEX and LATEX2HTML processing.)

\rawhtml...\endrawhtml
old AMS-style variant of rawhtml environment.
\htmlonly...\endhtmlonly
old AMS-style variant of htmlonly environment.
\latexonly...\endlatexonly
old AMS-style variant of latexonly environment.
\imagesonly...\endimagesonly
old AMS-style variant of imagesonly environment.
\comment...\endcomment
old AMS-style variant of comment environment.

Warning: These pseudo'-environments are not as reliable as their LATEX counterparts. In particular, the \<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.

Next: Hyper-links in LATEX Up: LaTeX2HTML Previous: Environments_and_Special_Features
(merlin) BOFH
2000-03-14