## 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 LATEX2`HTML` 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 LATEX2`HTML` distribution. It must be included in any LATEX document using these features, by one of the following methods:

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

Warning: Some of these features, but not all, are also available with LATEX2.09.
Users of LATEX2`HTML` 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 LATEX2`HTML`, of this translator;
`\htmladdnormallink`
  creates a (perhaps named) textual hyperlink to a specified `<URL>`;
`\htmladdnormallinkfoot`
  same as `\htmladdnormallink`, but LATEX also prints the `<URL>` in a footnote;
`\htmladdimg`
  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 LATEX2`HTML`;
  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 LATEX2`HTML`; 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 LATEX2`HTML` document. In LATEX the file is input as usual, after counter values have first been written to a file, named `<file>.ptr`.
`\startdocument`
  tells LATEX2`HTML` 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.
`\htmlhead`
  places a sectional heading on a `HTML` page; used mainly with the document segmentation feature.
  It is ignored in LATEX.
`\htmlnohead`
  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.

`\HTMLcode`
  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.
`\tableofchildlinks`
  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.
`\htmladdtonavigation`
  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 LATEX2`HTML` 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 LATEX2`HTML` 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 `\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.

- Hyper-links in LATEX
  - `\htmladdnormallink`
  - `\htmladdimg`
  - `\htmladdnormallinkfoot`
- Including Arbitrary HTML Mark-up and Comments
  - `\begin{rawhtml}`
  - `\beginrawhtml`...`\endrawhtml`
  - `\begin{comment}`
  - `\comment...\endcomment`
- Arbitrary Tags and Attributes
- Conditional Text
  - `\begin{latexonly}` and `\begin{htmlonly}`
  - `\htmlonly...\endhtmlonly`
  - `\latexonly...\endlatexonly`
  - `\latex`, `\html` and `\latexhtml`
  - `%begin{latexonly}`
  - `\begin{imagesonly}`
  - `\begin{makeimage}`
- Symbolic References shown as Hyperized Text
  - `\hyperref`
  - `\htmlref`
- Hypertext Links in Bibliographic References (Citations)
  - `\hypercite`
  - `\htmlcite`
- Symbolic References between Living Documents
  - `\externallabels`
  - `\externalref`
  - `\externalcite`
  - Cross-Referencing Example
- Miscellaneous commands for `HTML` effects
  - `\htmlrule` and `\htmlrule*`
  - `\strikeout{<text>}`
  - `\tableofchildlinks`
  - `\htmlinfo`
  - `\bodytext{<options>}`
  - `\htmlbody{<options>}`
  - `\htmlbase{<URL>}`
  - `\HTMLset{<which>}{<value>}` and `\HTMLsetenv{<which>}{<value>}`
  - `\latextohtml`
- Active Image Maps
- Document Segmentation43
  - A Segmentation Example