%
% The Hyperlatex manual, version 2.3.1
%
% Last $Modified: Mon Mar 17 19:16:42 1997 by otfried $
%
\documentclass{article}
\usepackage{hyperlatex}
\usepackage{xspace}
%% Comment out the following two lines if you do not have Babel
\usepackage[german,english]{babel}
\W\usepackage{longtable}
\W\usepackage{makeidx}

%\htmlpanelgerman

\W\begin{iftex}
\sloppy
%% These definitions work reasonably for A4 and letter paper
\oddsidemargin 0mm
\evensidemargin 0mm
\topmargin 0mm
\textwidth 15cm
\textheight 22cm
\advance\textheight by -\topskip
\count255=\textheight\divide\count255 by \baselineskip
\textheight=\the\count255\baselineskip
\advance\textheight by \topskip
\W\end{iftex}

%% Html declarations: Output directory and filenames, node title
\htmltitle{Hyperlatex Manual}
\htmldirectory{html}
\htmladdress{Otfried Cheong, \today}

\htmlattributes{BODY}{BGCOLOR="#ffffe6"}
\htmlattributes{TABLE}{BORDER}
\setcounter{secnumdepth}{3}
\setcounter{htmldepth}{2}

%% Toppanel should include the Index (TODO)

\newcommand{\homepage}{http://www.cs.ust.hk/\~{}otfried/}

%% two useful shortcuts: \+, \*
\newcommand{\+}{\verb+}
\renewcommand{\*}{\back{}}

%% General macros
\newcommand{\Html}{\textsc{Html}\xspace }
\newcommand{\latex}{\LaTeX\xspace }
\newcommand{\latexinfo}{\texttt{latexinfo}\xspace }
\newcommand{\texinfo}{\texttt{texinfo}\xspace }
\newcommand{\dvi}{\textsc{Dvi}\xspace }

\makeindex

\title{The Hyperlatex Markup Language}
\author{Otfried Cheong\\
  {\small Dept.\ of Computer Science, The Hong Kong University of
    Science and Technology,}\\[-0.7ex]
  {\small Clear Water Bay, Kowloon, Hong Kong}}
\date{}

\begin{document}
\maketitle
\T\section{Introduction}

\emph{Hyperlatex} is a package that allows you to prepare documents in
\Html, and, at the same time, to produce a neatly printed document
from your input. Unlike some other systems that you may have seen,
Hyperlatex is \emph{not} a general \latex-to-\Html converter.  In my
eyes, conversion is not a solution to \Html authoring.  A well written
\Html document must differ from a printed copy in a number of rather
subtle ways---you'll see many examples in this manual.  I doubt that
these differences can be recognized mechanically, and I believe that
converted \latex can never be as readable as a document written for
\Html.

This manual is for Hyperlatex~2.3.1, of September~1998.

\htmlmenu{6}

\begin{ifhtml}
  \section{Introduction}
\end{ifhtml}

The basic idea of Hyperlatex is to make it possible to write a
document that will look like a flawless \latex document when printed
and like a handwritten \Html document when viewed with an \Html
browser. In this it completely follows the philosophy of \latexinfo
(and \texinfo).  Like \latexinfo, it defines its own input
format---the \emph{Hyperlatex markup language}---and provides two
converters to turn a document written in Hyperlatex markup into a \dvi
file or a set of \Html documents.

\label{philosophy}
Obviously, this approach has the disadvantage that you have to learn a
``new'' language to generate \Html files. However, the mental effort
for this is quite limited. The Hyperlatex markup language is simply a
well-defined subset of \latex that has been extended with commands to
create hyperlinks, to control the conversion to \Html, and to add
concepts of \Html such as horizontal rules and embedded images.
Furthermore, you can use Hyperlatex perfectly well without knowing
anything about \Html markup.

The fact that Hyperlatex defines only a restricted subset of \latex
does not mean that you have to restrict yourself in what you can do in
the printed copy. Hyperlatex provides many commands that allow you to
include arbitrary \latex commands (including commands from any package
that you'd like to use) which will be processed to create your printed
output, but which will be ignored in the \Html document.  However, you
do have to specify that \emph{explicitly}.  Whenever Hyperlatex
encounters a \latex command outside its restricted subset, it will
complain bitterly.

The rationale behind this is that when you are writing your document,
you should keep both the printed document and the \Html output in
mind.  Whenever you want to use a \latex command with no defined \Html
equivalent, you are thus forced to specify this equivalent.  If, for
instance, you have marked a logical separation between paragraphs with
\latex's \verb+\bigskip+ command (a command not in Hyperlatex's
restricted set, since there is no \Html equivalent), then Hyperlatex
will complain, since very probably you would also want to mark this
separation in the \Html output. So you would have to write
\begin{verbatim}
   \texonly{\bigskip}
   \htmlrule
\end{verbatim}
to imply that the separation will be a \verb+\bigskip+ in the printed
version and a horizontal rule in the \Html-version.  Even better, you
could define a command \verb+\separate+ in the preamble and give it a
different meaning in \dvi and \Html output. If you find that for your
documents \verb+\bigskip+ should always be ignored in the \Html
version, then you can state so in the preamble as follows. (It is also
possible that you setup personal definitions like these in your
personal \file{init.hlx} file, and Hyperlatex will never bother you
again.)
\begin{verbatim}
   \W\newcommand{\bigskip}{}
\end{verbatim}

This philosophy implies that in general an existing \latex-file will
not make it through Hyperlatex. In many cases, however, it will
suffice to go through the file once, adding the necessary markup that
specifies how Hyperlatex should treat the unknown commands.

There also is an optional Hyperlatex package
\link{\file{emulate}}{emulate-package} that defines many standard
\latex-commands with some reasonable default behavior.

\section{Using Hyperlatex}
\label{sec:using-hyperlatex}

Using Hyperlatex is easy. You create a file \textit{document.tex},
say, containing your document with Hyperlatex markup (the most
important \latex-commands, with a number of additions to make it
easier to create readable \Html).

If you use the command
\begin{example}
  latex document
\end{example}
then your file will be processed by \latex, resulting in a
\dvi-file, which you can print as usual.

On the other hand, you can run the command
\begin{example}
  hyperlatex document
\end{example}
and your document will be converted to \Html format, presumably to a
set of files called \textit{document.html}, \textit{document\_1.html},
\ldots{}. You can then use any \Html-viewer or \textsc{www}-browser to
view the document.  (The entry point for your document will be the
file \textit{document.html}.)

This document describes how to use the Hyperlatex package and explains
the Hyperlatex markup language. It does not teach you {\em how} to
write for the web. There are \xlink{style
  guides}{http://www.w3.org/hypertext/WWW/Provider/Style/Overview.html}
available, which you might want to consult. Writing an on-line
document is not the same as writing a paper. I hope that Hyperlatex
will help you to do both properly.

This manual assumes that you are familiar with \latex, and that you
have at least some familiarity with hypertext documents---that is,
that you know how to use a \textsc{www}-browser and understand what a
\emph{hyperlink} is.

If you want, you can have a look at the source of this manual, which
illustrates most points discussed here. You can also look at the
documents on my \xlink{home page}{\homepage}, all of which are created
using Hyperlatex. 

The primary distribution site for Hyperlatex is at
\file{ftp://ftp.cs.ust.hk/pub/ipe}. However, if you are not close to
Hong Kong, then I would strongly recommend using the mirror site
\file{ftp://ftp.cs.uni-magdeburg.de/pub/ipe}. It is mirrored daily.

There is also a mailing list for Hyperlatex, maintained by Roland
Jesse.  This list is for discussion of Hyperlatex and anything that
relates to it.  This is also where new versions of Hyperlatex are
announced. To subscribe to the list send mail to:
\xlink{majordomo@cs.uni-magdeburg.de}{mailto:majordomo@cs.uni-magdeburg.de}
with the following line in the body (not subject):
\begin{verbatim}
   subscribe hyperlatex
\end{verbatim}
To send Email to the list, mail to
\xlink{hyperlatex@cs.uni-magdeburg.de}{mailto:hyperlatex@cs.uni-magdeburg.de}.

The mailing list is the only ``official'' place where you can find
support for problems with Hyperlatex.  I am unfortunately no longer in
a position to answer mail with questions about Hyperlatex. Please
understand that Hyperlatex is just a by-product of Ipe--I wrote it to
be able to write the Ipe manual the way I wanted to. I am making
Hyperlatex available because others seem to find it useful, and I'm
trying to make this manual and the installation instructions as clear
as possible, but I cannot provide any personal support.  If you have
problems installing or using Hyperlatex, or if you think that you have
found a bug, please mail it to the Hyperlatex mailing list at
\xlink{hyperlatex@cs.uni-magdeburg.de}{mailto:hyperlatex@cs.uni-magdeburg.de}.
One of the friendly Hyperlatex users will probably be able to help
you.  And I do read the list regularly and will try to fix real bugs
promptly.  Maybe some day a kind soul will even collect a list of
frequently asked questions.

A final footnote: The converter to \Html implemented in Hyperlatex is
written in \textsc{Gnu} Emacs Lisp. If you want, you can invoke it
directly from Emacs (see the beginning of \file{hyperlatex.el} for
instructions). But even if you don't use Emacs, even if you don't like
Emacs, or even if you subscribe to \code{alt.religion.emacs.haters},
you can happily use Hyperlatex.  Hyperlatex can be invoked from the
shell as ``hyperlatex,'' and you will never know that this script
calls Emacs to produce the \Html document.

The Hyperlatex code is based on the Emacs Lisp macros of the
\code{latexinfo} package.

Hyperlatex is \link{copyrighted.}{sec:copyright}

\section{About the Html output}
\label{sec:about-html}

\label{nodes}
\cindex{node} Hyperlatex will automatically partition your input file
into separate \Html files, using the sectioning commands in the input.
It attaches buttons and menus to every \Html file, so that the reader
can walk through your document and can easily find the information
that she is looking for.  (Note that \Html documentation usually calls
a single \Html file a ``document''. In this manual we take the
\latex point of view, and call ``document'' what is enclosed in a
\code{document} environment. We will use the term \emph{node} for the
individual \Html files.)  You may want to experiment a bit with
\texonly{the \Html version of} this manual. You'll find that every
\+\section+ and \+\subsection+ command starts a new node. The \Html
node of a section that contains subsections contains a menu whose
entries lead you to the subsections. Furthermore, every \Html node has
three buttons: \emph{Next}, \emph{Previous}, and \emph{Up}.

The \emph{Next} button leads you to the next section \emph{at the same
  level}. That means that if you are looking at the node for the
section ``Getting started,'' the \emph{Next} button takes you to
``Conditional Compilation,'' \emph{not} to ``Preparing an input file''
(the first subsection of ``Getting started''). If you are looking at
the last subsection of a section, there will be no \emph{Next} button,
and you have to go \emph{Up} again, before you can step further.  This
makes it easy to browse quickly through one level of detail, while
only delving into the lower levels when you become interested.  (It is
possible to \link{change this behavior}{sequential-package} so that
the \emph{Next} button always leads to the next piece of
text\texonly{, see Section~\Ref}.)

\label{topnode}
If you look at \texonly{the \Html output for} this manual, you'll find
that there is one special node that acts as the entry point to the
manual, and as the parent for all its sections. This node is called
the \emph{top node}.  Everything between \+\begin{document}+ and the
  first sectioning command (such as \+\section+ or \+\chapter+) goes
  into the top node.
  
\label{htmltitle}
\label{preamble}
An \Html file needs a \emph{title}. The default title is ``Untitled'',
you can set it to something more meaningful in the
preamble\footnote{\label{footnote-preamble}The \emph{preamble} of a
  \latex file is the part between the \code{\back{}documentclass}
  command and the \code{\back{}begin\{document\}} command.  \latex
  does not allow text in the preamble; you can only put definitions
  and declarations there.} of your document using the
\code{\back{}htmltitle} command. You should use something not too
long, but useful. (The \Html title is often displayed by browsers in
the window header, and is used in history lists or bookmark files.)
The title you specify is used directly for the top node of your
document. The other nodes get a title composed of this and the section
heading.

\label{htmladdress}
\cindex[htmladdress]{\code{\back{}htmladdress}} It is common practice
to put a short notice at the end of every \Html node, with a reference
to the author and possibly the date of creation. You can do this by
using the \code{\back{}htmladdress} command in the preamble, like
this:
\begin{verbatim}
   \htmladdress{Otfried Cheong, \today}
\end{verbatim}

\section{Trying it out}
\label{sec:trying-it-out}

For those who don't read manuals, here are a few hints to allow you
to use Hyperlatex quickly. 

Hyperlatex implements a certain subset of \latex, and adds a number of
other commands that allow you to write better \Html. If you already
have a document written in \latex, the effort to convert it to
Hyperlatex should be quite limited. You mainly have to check the
preamble for commands that Hyperlatex might choke on.

The beginning of a simple Hyperlatex document ought to look something
like this:
\begin{example}
  \*documentclass\{article\}
  \*usepackage\{hyperlatex\}
  
  \*htmltitle\{\textit{Title of HTML nodes}\}
  \*htmladdress\{\textit{Your Email address, for instance}\}
  
      \textit{more LaTeX declarations, if you want}
  
  \*title\{\textit{Title of document}\}
  \*author\{\textit{Author document}\}
  
  \*begin\{document\}
  
  \*maketitle
  
  This is the beginning of the document\ldots
\end{example}
Note the use of the \textit{hyperlatex} package. It contains the
definitions of the Hyperlatex commands that are not part of \latex.

Those few commands are all that is absolutely needed by Hyperlatex,
and adding them should suffice for a simple \latex document. You might
try it on the \file{sample2e.tex} file that comes with \LaTeXe, to get
a feeling for the \Html formatting of the different \latex concepts.

Sooner or later Hyperlatex will fail on a \latex-document. As
explained in the introduction, Hyperlatex is not meant as a general
\latex-to-\Html converter. It has been designed to understand a certain
subset of \latex, and will treat all other \latex commands with an
error message. This does not mean that you should not use any of these
instructions for getting exactly the printed document that you want.
By all means, do. But you will have to hide those commands from
Hyperlatex using the \link{escape mechanisms}{sec:escaping}.

And you should learn about the commands that allow you to generate
much more natural \Html than any plain \latex-to-\Html converter
could.  For instance, \+\pageref+ is not understood by the Hyperlatex
converter, because \Html has no pages. Cross-references are best made
using the \link{\code{\*link}}{link} command.

The following sections explain in detail what you can and cannot do in
Hyperlatex.

Practically all aspects of the generated output can be
\link{customized}[, see Section~\Ref]{sec:customizing}.

\section[Getting started]{A \LaTeX{} subset --- Getting started}
\label{sec:getting-started}

Starting with this section, we take a stroll through the
\link{\latex-book}[~\Cite]{latex-book}, explaining all features that
Hyperlatex understands, additional features of Hyperlatex, and some
missing features. For the \latex output the general rule is that
\emph{no \latex command has been changed}. If a familiar \latex
command is listed in this manual, it is understood both by \latex
and the Hyperlatex converter, and its \latex meaning is the familiar
one. If it is not listed here, you can still use it by
\link{escaping}{sec:escaping} into \TeX-only mode, but it will then
have effect in the printed output only.

\subsection{Preparing an input file}
\label{sec:special-characters}
\cindex[back]{\+\back+}
\cindex[%]{\+\%+}
\cindex[~]{\+\~+}
\cindex[^]{\+\^+}
There are ten characters that \latex and Hyperlatex treat specially:
\begin{verbatim}
      \  {  }  ~  ^  _  #  $  %  &
\end{verbatim}
%% $
To typeset one of these, use
\begin{verbatim}
      \back   \{   \}  \~{}  \^{}  \_  \#  \$  \%  \&
\end{verbatim}
(Note that \+\back+ is different from the \+\backslash+ command of
\latex. \+\backslash+ can only be used in math mode\texonly{ and looks
  like this: $\backslash$}, while \+\back+ can be used in any mode
\texorhtml{and looks like this: \back}{and is typeset in a typewriter
  font}.)

Sometimes it is useful to turn off the special meaning of some of
these ten characters. For instance, when writing documentation about
programs in~C, it might be useful to be able to write
\code{some\_variable} instead of always having to type
\code{some\*\_variable}. This can be achieved with the
\link{\code{\*NotSpecial}}{not-special} command.

In principle, all other characters simply typeset themselves. This has
to be taken with a grain of salt, though. \latex still obeys
ligatures, which turns \kbd{ffi} into `ffi', and some characters, like
\kbd{>}, do not resemble themselves in some fonts \texonly{(\kbd{>}
  looks like > in roman font)}. The only characters for which this is
critical are \kbd{<}, \kbd{>}, and \kbd{|}. Better use them in a
typewriter-font.  Note that \texttt{?{}`} and \texttt{!{}`} are
ligatures in any font and are displayed and printed as \texttt{?`} and
\texttt{!`}.

\cindex[par]{\+\par+}
Like \latex, the Hyperlatex converter understands that an empty line
indicates a new paragraph. You can achieve the same effect using the
command \+\par+.

\subsection{Dashes and Quotation marks}
\label{dashes}
Hyperlatex translates a sequence of two dashes \+--+ into a single
dash, and a sequence of three dashes \+---+ into two dashes \+--+. The
quotation mark sequences \+''+ and \+``+ are translated into simple
quotation marks \kbd{\"{}}.


\subsection{Simple text generating commands}
\cindex[latex]{\code{\back{}LaTeX}}
The following simple \latex macros are implemented in Hyperlatex:
\begin{menu}
\item \+\LaTeX+ produces \latex.
\item \+\TeX+ produces \TeX{}.
\item \+\LaTeXe+ produces {\LaTeXe}.
\item \+\ldots+ produces three dots \ldots{}
\item \+\today+ produces \today---although this might depend on when
  you use it\ldots
\end{menu}

\subsection{Emphasizing Text}
\cindex[em]{\verb+\em+}
\cindex[emph]{\verb+\emph+}
You can emphasize text using \+\emph+ or the old-style command
\+\em+. It is also possible to use the construction \+\begin{em}+
  \ldots \+\end{em}+.

\subsection{Preventing line breaks}
\cindex[~]{\+~+}

The \verb+~+ is a special character in Hyperlatex, and is replaced by
the \Html-tag for \xlink{``non-breakable
  space''}{http://www.w3.org/hypertext/WWW/MarkUp/Entities.html}.

As we saw before, you can typeset the \kbd{\~{}} character by typing
\+\~{}+. This is also the way to go if you need the \kbd{\~{}} in an
argument to an \Html command that is processed by Hyperlatex, such as
in the \var{URL}-argument of \link{\code{\*xlink}}{xlink}.

You can also use the \+\mbox+ command. It is implemented by replacing
all sequences of white space in the argument by a single
\+~+. Obviously, this restricts what you can use in the
argument. (Better don't use any math mode material in the argument.)

\subsection{Footnotes}
\label{sec:footnotes}
\cindex[footnote]{\+\footnote+}
\cindex[htmlfootnotes]{\+\htmlfootnotes+}
The footnotes in your document will be collected together and output
as a separate section or chapter right at the end of your document.
You can specify a different location using the \+\htmlfootnotes+
command, which has to come \emph{after} all \+\footnote+ commands in
the document.

\subsection{Formulas}
\label{sec:math}
\cindex[math]{\verb+\math+}

There is no \emph{math mode} in \Html. (The proposed standard \Html3
contained a math mode, but has been withdrawn. \Html-browsers that
will understand math do not seem to become widely available in the
near future.)

Hyperlatex understands the \+$+ sign delimiting math mode as well as
\+\(+ and \+\)+. Subscripts and superscripts produced using \+_+ and
\+^+ are understood. If the \+\htmllevel+ is larger than \verb|html2|
then \Html tags for subscripts and superscripts are created.
Otherwise, Hyperlatex creates a textual approximation of the form
\textit{a\^{}2 = x\^{}\{2n\}}.
%% $

Hyperlatex now has a simply textual implementation of many common math
mode commands, so simple formulas in your text should be converted to
some textual representation. If you are not satisfied with that
representation, you can use the \verb+\math+ command:
\begin{example}
  \verb+\math[+\var{{\Html}-version}]\{\var{\LaTeX-version}\}
\end{example}
In \latex, this command typesets the \var{\LaTeX-version}, which is
read in math mode (with all special characters enabled, if you
have disabled some using \link{\code{\*NotSpecial}}{not-special}).
Hyperlatex typesets the optional argument if it is present, or
otherwise the \latex-version.

If, for instance, you want to typeset the \math{i}th element
(\verb+the \math{i}th element+) of an array as \math{a_i} in \latex,
but as \code{a[i]} in \Html, you can use
\begin{verbatim}
   \math[\code{a[i]}]{a_{i}}
\end{verbatim}

\index{htmlmathitalic@\+\htmlmathitalic+} By default, Hyperlatex sets
all math mode material in italic, as is common practice in typesetting
mathematics: ``Given $n$ points\ldots{}'' Sometimes, however, this
looks bad, and you can turn it off by using \+\htmlmathitalic{0}+
(turn it back on using \+\htmlmathitalic{1}+).  For instance: $2^{n}$,
but \htmlmathitalic{0}$H^{-1}$\htmlmathitalic{1}.  (In the long run,
Hyperlatex should probably recognize different concepts in math mode
and select the right font for each.)

It takes a bit of care to find the best representation for your
formula. This is an example of where any mechanical \latex-to-\Html
converter must fail---I hope that Hyperlatex's \+\math+ command will
help you produce a good-looking and functional representation.

You could create a bitmap for a complicated expression, but you should
be aware that bitmaps eat transmission time, and they only look good
when the resolution of the browser is nearly the same as the
resolution at which the bitmap has been created, which is not a
realistic assumption. In many situations, there are easier solutions:
If $x_{i}$ is the $i$th element of an array, then I would rather write
it as \verb+x[i]+ in \Html.  If it's a variable in a program, I'd
probably write \verb+xi+. In another context, I might want to write
\textit{x\_i}. To write Pythagoras's theorem, I might simply use
\verb/a^2 + b^2 = c^2/, or maybe \texttt{a*a + b*b = c*c}. To express
``For any $\varepsilon > 0$ there is a $\delta > 0$ such that for $|x
- x_0| < \delta$ we have $|f(x) - f(x_0)| < \varepsilon$'' in \Html, I
would write ``For any \textit{eps} \texttt{>} \textit{0} there is a
\textit{delta} \texttt{>} \textit{0} such that for
\texttt{|}\textit{x}\texttt{-}\textit{x0}\texttt{|} \texttt{<}
\textit{delta} we have
\texttt{|}\textit{f(x)}\texttt{-}\textit{f(x0)}\texttt{|} \texttt{<}
\textit{eps}.''

\subsection{Ignorable input}
\cindex[%]{\verb+%+}
The percent character \kbd{\%} introduces a comment in Hyperlatex.
Everything after a \kbd{\%} to the end of the line is ignored, as well
as any white space on the beginning of the next line.

\subsection{Document class}
\index{documentclass@\+\documentclass+}
\index{documentstyle@\+\documentstyle+}
\index{usepackage@\+\usepackage+}
The \+\documentclass+ (or alternatively \+\documentstyle+) and
\+\usepackage+ commands are interpreted by Hyperlatex to select
additional package files with definitions for commands particular to
that class or package.

\subsection{Title page}
\cindex[title]{\+\title+} \index{author@\+\author+}
\index{date@\+\date+} \index{maketitle@\+\maketitle+}
\index{abstract@\+abstract+} \index{thanks@\+\thanks+} The \+\title+,
\+\author+, \+\date+, and \+\maketitle+ commands and the \+abstract+
environment are all understood by Hyperlatex. The \+\thanks+ command
currently simply generates a footnote. This is often not the right way
to format it in an \Html-document, use \link{conditional
  translation}{sec:escaping} to make it better\texonly{ (Section~\Ref)}.

\subsection{Sectioning}
\label{sec:sectioning}
\cindex[section]{\verb+\section+}
\cindex[subsection]{\verb+\subsection+}
\cindex[subsubsection]{\verb+\subsection+}
\cindex[paragraph]{\verb+\paragraph+}
\cindex[subparagraph]{\verb+\subparagraph+}
\cindex{chapter@\verb+\chapter+} The sectioning commands
\verb+\chapter+, \verb+\section+, \verb+\subsection+,
\verb+\subsubsection+, \verb+\paragraph+, and \verb+\subparagraph+ are
recognized by Hyperlatex and used to partition the document into
\link{nodes}{nodes}. You can also use the starred version and the
optional argument for the sectioning commands.  The optional
argument will be used for node titles and in menus.
Hyperlatex can number your sections if you set the counter
\+secnumdepth+ appropriately. The default is not to number any
sections. For instance, if you use this in the preamble
\begin{verbatim}
   \setcounter{secnumdepth}{3}
\end{verbatim}
chapters, sections, subsections, and subsubsections will be numbered.

\cindex[htmlheading]{\verb+\htmlheading+}
\label{htmlheading}
You will probably sooner or later want to start an \Html node without
a heading, or maybe with a bitmap before the main heading. This can be
done by leaving the argument to the sectioning command empty. (You can
still use the optional argument to set the title of the \Html node.)
Do not use \+\htmlimage+ inside the argument of the sectioning
command. The right way to start a document with an image is the
following:
\begin{verbatim}
\T\section{An example of a node starting with an image}
\W\section[Node with Image]{}
\W\begin{center}\htmlimage{theimage.gif}\end{center}
\W\htmlheading[1]{An example of a node starting with an image}
\end{verbatim}
The \+\htmlheading+ command creates a heading in the \Html output just
as \+\section+ does, but without starting a new node.  The optional
argument has to be a number from~1 to~6, and specifies the level of
the heading (in \+article+ style, level~1 corresponds to \+\section+,
level~2 to \+\subsection+, and so on).

\cindex[protect]{\+\protect+}
\cindex[noindent]{\+\noindent+}
You can use the commands \verb+\protect+ and \+\noindent+. They will be
ignored in the \Html-version.

\subsection{Displayed material}
\label{sec:displays}
\cindex[blockquote]{\verb+blockquote+ environment}
\cindex[quote]{\verb+quote+ environment}
\cindex[quotation]{\verb+quotation+ environment}
\cindex[verse]{\verb+verse+ environment}
\cindex[center]{\verb+center+ environment}
\cindex[itemize]{\verb+itemize+ environment}
\cindex[menu]{\verb+menu+ environment}
\cindex[enumerate]{\verb+enumerate+ environment}
\cindex[description]{\verb+description+ environment}
The \verb+quote+, \verb+quotation+, and \verb+verse+ environment are
all implemented by the Hyperlatex converter---but they are all
identical!  Alternatively, you can use the \+blockquote+ environment,
so named for the \Html-tag that it creates.

The \+center+ environment is identical to the \+quote+ environment for
\Html2, but creates a centering environment in \Html3.2.

To make lists, you can use the \verb+itemize+, \verb+enumerate+, and
\verb+description+ environments. You \emph{cannot} specify an optional
argument to \verb+\item+ in \verb+itemize+ or \verb+enumerate+, and
you \emph{must} specify one for \verb+description+.

All these environments can be nested.

The \verb+\\+ command is recognized, with and without \verb+*+. You
can use the optional argument to \+\\+, but it will be ignored.

There is also a \verb+menu+ environment, which looks like an
\verb+itemize+ environment, but is somewhat denser since the space
between items has been reduced. It is only meant for single-line
items.

Hyperlatex understands the math display environments \+\[+, \+\]+,
\+displaymath+, \+equation+, and \+equation*+.

\section[Conditional Compilation]{Conditional Compilation: Escaping
  into one mode} 
\label{sec:escaping}

In many situations you want to achieve slightly (or maybe even
drastically) different behavior of the \latex code and the
\Html-output.  Hyperlatex offers several different ways of letting
your document depend on the mode.


\subsection{\LaTeX{} versus Html mode}
\label{sec:versus-mode}
\cindex[texonly]{\verb+\texonly+}
\cindex[texorhtml]{\verb+\texorhtml+}
\cindex[htmlonly]{\verb+\htmlonly+}
\label{texonly}
\label{texorhtml}
\label{htmlonly}
The easiest way to put a command or text in your document that is only
included in one of the two output modes it by using a \verb+\texonly+
or \verb+\htmlonly+ command. They ignore their argument, if in the
wrong mode, and otherwise simply expand it:
\begin{verbatim}
   We are now in \texonly{\LaTeX}\htmlonly{HTML}-mode.
\end{verbatim}
In cases such as this you can simplify the notation by using the
\+\texorhtml+ command, which has two arguments:
\begin{verbatim}
   We are now in \texorhtml{\LaTeX}{HTML}-mode.
\end{verbatim}

\label{W}
\label{T}
\cindex[T]{\verb+\T+}
\cindex[W]{\verb+\W+}
Another possibility is by prefixing a line with \verb+\T+ or
\verb+\W+. \verb+\T+ acts like a comment in \Html-mode, and as a noop
in \latex-mode, and for \verb+\W+ it is the other way round:
\begin{verbatim}
   We are now in
   \T \LaTeX-mode.
   \W HTML-mode.
\end{verbatim}


\cindex[iftex]{\code{iftex}}
\cindex[ifhtml]{\code{ifhtml}}
\label{iftex}
\label{ifhtml}
The last way of achieving this effect is useful when there are large
chunks of text that you want to skip in one mode---a \Html-document
might skip a section with a detailed mathematical analysis, a
\latex-document will not contain a node with lots of hyperlinks to
other documents.  This can be done using the \code{iftex} and
\code{ifhtml} environments:
\begin{verbatim}
   We are now in
   \begin{iftex}
     \LaTeX-mode.
   \end{iftex}
   \begin{ifhtml}
     HTML-mode.
   \end{ifhtml}
\end{verbatim}

In \latex, commands that are defined inside an enviroment are
``forgotten'' at the end of the environment. So \latex commands
defined inside a \code{iftex} environment are defined, but then
immediately forgotten by \latex.
A simple trick to avoid this problem is to use the following idiom:
\begin{verbatim}
   \W\begin{iftex}
   ... command definitions
   \W\end{iftex}
\end{verbatim}

Now the command definitions are correctly made in the Latex, but not
in the Html version.

\label{tex}
\cindex[tex]{\code{tex}} Instead of the \+iftex+ environment, you can
also use the \+tex+ environment. It is different from \+iftex+ only if
you have used \link{\code{\*NotSpecial}}{not-special} in the preamble.

\cindex[latexonly]{\code{latexonly}}
\label{latexonly}
The environment \code{latexonly} has been provided as a service to
\+latex2html+ users. Its effect is the same as \+iftex+.

\subsection{Ignoring more input}
\label{sec:comment}
\cindex[comment]{\+comment+ environment}
The contents of the \+comment+ environment is ignored.

\subsection{Flags --- more on conditional compilation}
\label{sec:flags}
\cindex[ifset]{\code{ifset} environment}
\cindex[ifclear]{\code{ifclear} environment}

You can also have sections of your document that are included
depending on the setting of a flag:
\begin{example}
  \verb+\begin{ifset}{+\var{flag}\}
    Flag \var{flag} is set!
  \verb+\end{ifset}+

  \verb+\begin{ifclear}{+\var{flag}\}
    Flag \var{flag} is not set!
  \verb+\end{ifset}+
\end{example}
A flag is simply the name of a \TeX{} command. A flag is considered
set if the command is defined and its expansion is neither empty nor
the single character ``0'' (zero).

You could for instance select in the preamble which parts of a
document you want included (in this example, parts~A and~D are
included in the processed document):
\begin{example}
   \*newcommand\{\*IncludePartA\}\{1\}
   \*newcommand\{\*IncludePartB\}\{0\}
   \*newcommand\{\*IncludePartC\}\{0\}
   \*newcommand\{\*IncludePartD\}\{1\}
     \ldots
   \*begin\{ifset\}\{IncludePartA\}
     \textit{Text of part A}
   \*end\{ifset\}
     \ldots
   \*begin\{ifset\}\{IncludePartB\}
     \textit{Text of part B}
   \*end\{ifset\}
     \ldots
   \*begin\{ifset\}\{IncludePartC\}
     \textit{Text of part C}
   \*end\{ifset\}
     \ldots
   \*begin\{ifset\}\{IncludePartD\}
     \textit{Text of part D}
   \*end\{ifset\}
     \ldots
\end{example}
Note that it is permitted to redefine a flag (using \+\renewcommand+)
in the document. That is particularly useful if you use these
environments in a macro.

\section{Carrying on}
\label{sec:carrying-on}

In this section we continue to Chapter~3 of the \latex-book, dealing
with more advanced topics.

\subsection{Changing the type style}
\label{sec:type-style}
\cindex[underline]{\+\underline+}
\cindex[textit]{\+textit+}
\cindex[textbf]{\+textbf+}
\cindex[textsc]{\+textsc+}
\cindex[texttt]{\+texttt+}
\cindex[it]{\verb+\it+}
\cindex[bf]{\verb+\bf+}
\cindex[tt]{\verb+\tt+}
\label{font-changes}
\label{underline}
Hyperlatex understands the following physical font specifications of
\LaTeXe{}:
\begin{menu}
\item \+\textbf+ for \textbf{bold}
\item \+\textit+ for \textit{italic}
\item \+\textsc+ for \textsc{small caps}
\item \+\texttt+ for \texttt{typewriter}
\item \+\underline+ for \underline{underline}
\end{menu}
In \LaTeXe{} font changes are
cumulative---\+\textbf{\textit{BoldItalic}}+ typesets the text in a
bold italic font. Different \Html browsers will display different
things. 

The following old-style commands are also supported:
\begin{menu}
\item \verb+\bf+ for {\bf bold}
\item \verb+\it+ for {\it italic}
\item \verb+\tt+ for {\tt typewriter}
\end{menu}
So you can write
\begin{example}
  \{\*it italic text\}
\end{example}
but also
\begin{example}
  \*textit\{italic text\}
\end{example}
You can use \verb+\/+ to separate slanted and non-slanted fonts (it
will be ignored in the \Html-version).

Hyperlatex complains about any other \latex commands for font changes,
in accordance with its \link{general philosophy}{philosophy}. If you
do believe that, say, \+\sf+ should simply be ignored, you can easily
ask for that in the preamble by defining:
\begin{example}
  \*W\*newcommand\{\*sf\}\{\}
\end{example}

Both \latex and \Html encourage you to express yourself in terms
of \emph{logical concepts} instead of visual concepts. (Otherwise, you
wouldn't be using Hyperlatex but some \textsc{Wysiwyg} editor to
create \Html.) In fact, \Html defines tags for \emph{logical}
markup, whose rendering is completely left to the user agent (\Html
client). 

The Hyperlatex package defines a standard representation for these
logical tags in \latex---you can easily redefine them if you don't
like the standard setting.

The logical font specifications are:
\begin{menu}
\item \+\cit+ for \cit{citations}.
\item \+\code+ for \code{code}.
\item \+\dfn+ for \dfn{defining a term}.
\item \+\em+ and \+\emph+ for \emph{emphasized text}.
\item \+\file+ for \file{file.names}.
\item \+\kbd+ for \kbd{keyboard input}.
\item \verb+\samp+ for \samp{sample input}.
\item \verb+\strong+ for \strong{strong emphasis}.
\item \verb+\var+ for \var{variables}.
\end{menu}

\subsection{Changing type size}
\label{sec:type-size}
\cindex[normalsize]{\+\normalsize+} \cindex[small]{\+\small+}
\cindex[footnotesize]{\+\footnotesize+}
\cindex[scriptsize]{\+\scriptsize+} \cindex[tiny]{\+\tiny+}
\cindex[large]{\+\large+} \cindex[Large]{\+\Large+}
\cindex[LARGE]{\+\LARGE+} \cindex[huge]{\+\huge+}
\cindex[Huge]{\+\Huge+}
Hyperlatex understands the \latex declarations
to change the type size. \Html tags for font size changes are
generated only if the \link{\code{\*htmllevel}}{htmllevel} is
\+html3.2+. The \Html font changes are relative to the \Html node's
\emph{basefont size}. (\+\normalfont+ being the basefont size,
\+\large+ begin the basefont size plus one etc.) To set the basefont
size, you can use
\begin{example}
  \*html\{basefont size=\var{x}\}
\end{example}
where \var{x} is a number between~1 and~7.

\subsection{Symbols from other languages}
\cindex{accents}
\cindex{\verb+\'+}
\cindex{\verb+\`+}
\cindex{\verb+\~+}
\cindex{\verb+\^+}
\cindex[c]{\verb+\c+}
\label{accents}
Hyperlatex recognizes all of \latex's commands for making accents.
However, only few of these are are available in \Html. Hyperlatex will
make a \Html-entity for the accents in \textsc{iso} Latin~1, but will
reject all other accent sequences. The command \verb+\c+ can be used
to put a cedilla on a letter `c' (either case), but on no other
letter.  So the following is legal
\begin{verbatim}
     Der K{\"o}nig sa\ss{} am wei{\ss}en Strand von Cura\c{c}ao und
     nippte an einer Pi\~{n}a Colada \ldots
\end{verbatim}
and produces
\begin{quote}
  Der K{\"o}nig sa\ss{} am wei{\ss}en Strand von Cura\c{c}ao und
  nippte an einer Pi\~{n}a Colada \ldots
\end{quote}
\label{hungarian}
Not available in \Html are \verb+Ji{\v r}\'{\i}+, or \verb+Erd\H{o}s+.
(You can tell Hyperlatex to simply typeset all these letters without
the accent by using the following in the preamble:
\begin{verbatim}
   \newcommand{\HlxIllegalAccent}[2]{#2}
\end{verbatim}

Hyperlatex also understands the following symbols:
\begin{center}
  \T\leavevmode
  \begin{tabular}{|cl|cl|cl|} \hline
    \oe & \code{\*oe} & \aa & \code{\*aa} & ?` & \code{?{}`} \\
    \OE & \code{\*OE} & \AA & \code{\*AA} & !` & \code{!{}`} \\
    \ae & \code{\*ae} & \o  & \code{\*o}  & \ss & \code{\*ss} \\
    \AE & \code{\*AE} & \O  & \code{\*O}  & & \\
    \S  & \code{\*S}  & \copyright & \code{\*copyright} & &\\
    \P  & \code{\*P}  & \pounds    & \code{\*pounds} & & \T\\ \hline
  \end{tabular}
\end{center}

\+\quad+ and \+\qquad+ produce some empty space.

\subsection{Defining commands and environments}
\cindex[newcommand]{\verb+\newcommand+}
\cindex[newenvironment]{\verb+\newenvironment+}
\cindex[renewcommand]{\verb+\renewcommand+}
\cindex[renewenvironment]{\verb+\renewenvironment+}
\label{newcommand}
\label{newenvironment}

Hyperlatex understands definitions of new commands with the
\latex-instructions \+\newcommand+ and \+\newenvironment+.
\+\renewcommand+ and \+\renewenvironment+ are understood as well
(Hyperlatex makes no attempt to test whether a command is actually
already defined or not.)  The optional parameter of \LaTeXe\ is also
implemented. 

Note that it is not possible to redefine a Hyperlatex command that is
\emph{hard-coded} in Emacs lisp inside the Hyperlatex converter. So
you could redefine the command \+\cite+ or the \+verse+ environment,
but you cannot redefine \+\T+.  (But you can redefine most of the
commands understood by Hyperlatex, namely all the ones defined in
\link{\file{siteinit.hlx}}{siteinit}.)

Some basic examples:
\begin{verbatim}
   \newcommand{\Html}{\textsc{Html}}

   \T\newcommand{\bad}{$\surd$}
   \W\newcommand{\bad}{\htmlimage{badexample_bitmap.xbm}}

   \newenvironment{badexample}{\begin{description}
     \item[\bad]}{\end{description}}

   \newenvironment{smallexample}{\begingroup\small
               \begin{example}}{\end{example}\endgroup}
\end{verbatim}

Command definitions made by Hyperlatex are global, their scope is not
restricted to the enclosing environment. If you need to restrict their
scope, use the \+\begingroup+ and \+\endgroup+ commands to create a
scope (in Hyperlatex, this scope is completely independent of the
\latex-environment scoping).

Note that Hyperlatex does not tokenize its input the way \TeX{} does.
To evaluate a macro, Hyperlatex simply inserts the expansion string,
replaces occurrences of \+#1+ to \+#9+ by the arguments, strips one
\kbd{\#} from strings of at least two \kbd{\#}'s, and then reevaluates
the whole.  Problems may occur when you try to use \kbd{\%}, \+\T+, or
\+\W+ in the expansion string. Better don't do that.

\subsection{Theorems and such}
The \verb+\newtheorem+ command declares a new ``theorem-like''
environment. The optional arguments are allowed as well (but ignored
unless you customize the appearance of the environment to use
Hyperlatex's counters).
\begin{verbatim}
   \newtheorem{guess}[theorem]{Conjecture}[chapter]
\end{verbatim}

\subsection{Figures and other floating bodies}
\cindex[figure]{\code{figure} environment}
\cindex[table]{\code{table} environment}
\cindex[caption]{\verb+\caption+}

You can use \code{figure} and \code{table} environments and the
\verb+\caption+ command. They will not float, but will simply appear
at the given position in the text. No special space is left around
them, so put a \code{center} environment in a figure. The \code{table}
environment is mainly used with the \link{\code{tabular}
  environment}{tabular}\texonly{ below}.  You can use the \+\caption+
command to place a caption. The starred versions \+table*+ and
\+figure*+ are supported as well.

\subsection{Lining it up in columns}
\label{sec:tabular}
\label{tabular}
\cindex[tabular]{\+tabular+ environment}
\cindex[hline]{\verb+\hline+}
\cindex{\verb+\\+}
\cindex{\verb+\\*+}
\cindex{\&}
\cindex[multicolumn]{\+\multicolumn+}
\cindex[htmlcaption]{\+\htmlcaption+}
The \code{tabular} environment is available in Hyperlatex.

If you use \+\htmllevel{html2}+, then Hyperlatex has to display the
table using preformatted text. In that case, Hyperlatex removes all
the \+&+ markers and the \+\\+ or \+\\*+ commands. The result is not
formatted any more, and simply included in the \Html-document as a
``preformatted'' display. This means that if you format your source
file properly, you will get a well-formatted table in the
\Html-document---but it is fully your own responsibility.
You can also use the \verb+\hline+ command to include a horizontal
rule.

If you use any \+\htmllevel+ higher than \+html2+, then Hyperlatex can
use tags for making tables.  Many column types are now supported, and
even \+\newcolumntype+ is available.  The \kbd{|} column type
specifier is silently ignored. You can force borders around your table
(and every single cell) by using \+\htmlattributes*{TABLE}{BORDER}+
immediately before your \+tabular+ environment.  You can use the
\+\multicolumn+ command.  \+\hline+ is understood and ignored.

The \+\htmlcaption+ has to be used right after the
\+\+\+begin{tabular}+. It sets the caption for the \Html table. (In
\Html, the caption is part of the \+tabular+ environment. However, you
can as well use \+\caption+ outside the environment.)

\cindex[cindex]{\+\htmltab+}
\label{htmltab}
If you have made the \+&+ character \link{non-special}{not-special},
you can use the macro \+\htmltab+ as a replacement.

Here is an example:
\T \begingroup\small
\begin{verbatim}
    \begin{table}[htp]
    \T\caption{Keyboard shortcuts for \textit{Ipe}}
    \begin{center}
    \begin{tabular}{|l|lll|}
    \htmlcaption{Keyboard shortcuts for \textit{Ipe}}
    \hline
                & Left Mouse      & Middle Mouse  & Right Mouse      \\
    \hline
    Plain       & (start drawing) & move          & select           \\
    Shift       & scale           & pan           & select more      \\
    Ctrl        & stretch         & rotate        & select type      \\
    Shift+Ctrl  &                 &               & select more type \T\\
    \hline
    \end{tabular}
    \end{center}
    \end{table}
\end{verbatim}
\T \endgroup
The example is typeset as \texorhtml{in Table~\ref{tab:shortcut}.}{follows:}
\begin{table}[htp]
\T\caption{Keyboard shortcuts for \textit{Ipe}}
\begin{center}
\begin{tabular}{|l|lll|}
\htmlcaption{Keyboard shortcuts for \textit{Ipe}}
\hline
            & Left Mouse      & Middle Mouse  & Right Mouse      \\
\hline
Plain       & (start drawing) & move          & select           \\
Shift       & scale           & pan           & select more      \\
Ctrl        & stretch         & rotate        & select type      \\
Shift+Ctrl  &                 &               & select more type \T\\
\hline
\end{tabular}
\T\caption{}\label{tab:shortcut}
\end{center}
\end{table}

Note that the \code{netscape} browser treats empty fields in a table
specially. If you don't like that, put a single \kbd{\~{}} in that field.

A more complicated example\texorhtml{ is in Table~\ref{tab:examp}}{:}
\begin{table}[ht]
  \begin{center}
    \T\leavevmode
    \begin{tabular}{|l|l|r|}
      \hline\hline
      \emph{type} & \multicolumn{2}{c|}{\emph{style}} \\ \hline
      smart & red & short \\
      rather silly & puce & tall \T\\ \hline\hline
    \end{tabular}
    \T\caption{}\label{tab:examp}
  \end{center}
\end{table}

To create certain effects you can employ the
\link{\code{\*htmlattributes}}{htmlattributes} command\texorhtml{, as
  for the example in Table~\ref{tab:examp2}}{:}
\begin{table}[ht]
  \begin{center}
    \T\leavevmode
    \htmlattributes*{TABLE}{BORDER}
    \htmlattributes*{TD}{ROWSPAN="2"}
    \begin{tabular}{||l|lr||}\hline
      gnats & gram & \$13.65 \\ \T\cline{2-3}
            \texonly{&} each & \multicolumn{1}{r||}{.01} \\ \hline
      gnu \htmlattributes*{TD}{ROWSPAN="2"} & stuffed
                   & 92.50 \\ \T\cline{1-1}\cline{3-3}
      emu   &      \texonly{&} \multicolumn{1}{r||}{33.33} \\ \hline
      armadillo & frozen & 8.99 \T\\ \hline
    \end{tabular}
    \T\caption{}\label{tab:examp2}
  \end{center}
\end{table}
As an alternative for creating cells spanning multiple rows, you could
check out the \code{multirow} package.

\subsection{Tabbing}
\label{sec:tabbing}
\cindex[tabbing environment]{\+tabbing+ environment}

A weak implementation of the tabbing environment is available if the
\Html level is~3.2 or higher.  It works using \Html \texttt{<TABLE>}
markup, which is a bit of a hack, but seems to work well for simple
tabbing environments.

The only commands implemented are \+\=+, \+\>+, \+\\+, and \+\kill+.

Here is an example:
\begin{tabbing}
  \textbf{while} \= $n < (42 * x/y)$ \\
  \>  \textbf{if} \= $n$ odd \\
  \> \> output $n$ \\
  \> increment $n$ \\
  \textbf{return} \code{TRUE}
\end{tabbing}

\subsection{Simulating typed text}
\cindex[verbatim]{\code{verbatim} environment}
\cindex[verb]{\verb+\verb+}
\label{verbatim}
The \code{verbatim} environment and the \verb+\verb+ command are
implemented. The starred varieties are currently not implemented.
(The implementation of the \code{verbatim} environment is not the
standard \latex implementation, but the one from the \+verbatim+
package by Rainer Sch\"opf). 

\cindex[example]{\code{example} environment}
\label{example}
Furthermore, there is another, new environment \code{example}.
\code{example} is also useful for including program listings or code
examples. Like \code{verbatim}, it is typeset in a typewriter font
with a fixed character pitch, and obeys spaces and line breaks. But
here ends the similarity, since \code{example} obeys the special
characters \+\+, \+{+, \+}+, and \+%+. You can 
still use font changes within an \code{example} environment, and you
can also place \link{hyperlinks}{sec:cross-references} there.  Here is
an example:
\begin{verbatim}
   To clear a flag, use
   \begin{example}
     {\back}clear\{\var{flag}\}
   \end{example}
\end{verbatim}

\cindex[exampleindent]{\verb+\exampleindent+}
Note also that an \code{example} environment is indented
automatically, while a \code{verbatim} environment is not.
In the \latex document, you can set the amount of indentation by
setting \code{\*exampleindent}:
\begin{example}
  \+\setlength{\exampleindent}{4mm}+
\end{example}

(The \+example+ environment is very similar to the \+alltt+
environment of the \+alltt+ package. The differences are that example
is automatically indented and obeys the \+%+ character.)

\section{Moving information around}
\label{sec:moving-information}

In this section we deal with questions related to cross referencing
between parts of your document, and between your document and the
outside world. This is where Hyperlatex gives you the power to write
natural \Html documents, unlike those produced by any \latex
converter.  A converter can turn a reference into a hyperlink, but it
will have to keep the text more or less the same. If we wrote ``More
details can be found in the classical analysis by Harakiri [8]'', then
a converter may turn ``[8]'' into a hyperlink to the bibliography in
the \Html document. In handwritten \Html, however, we would probably
leave out the ``[8]'' altogether, and make the \emph{name}
``Harakiri'' a hyperlink.

The same holds for references to sections and pages. The Ipe manual
says ``This parameter can be set in the configuration panel
(Section~11.1)''. A converted document would have the ``11.1'' as a
hyperlink. Much nicer \Html is to write ``This parameter can be set in
the configuration panel'', with ``configuration panel'' a hyperlink to
the section that describes it.  If the printed copy reads ``We will
study this more closely on page~42,'' then a converter must turn
the~``42'' into a symbol that is a hyperlink to the text that appears
on page~42. What we would really like to write is ``We will later
study this more closely,'' with ``later'' a hyperlink---after all, it
makes no sense to even allude to page numbers in an \Html document.

The Ipe manual also says ``Such a file is at the same time a legal
Encapsulated Postscript file and a legal \latex file---see
Section~13.'' In the \Html copy the ``Such a file'' is a hyperlink to
Section~13, and there's no need for the ``---see Section~13'' anymore.

\subsection{Cross-references}
\label{sec:cross-references}
\label{label}
\label{link}
\cindex[label]{\verb+\label+}
\cindex[link]{\verb+\link+}
\cindex[Ref]{\verb+\Ref+}
\cindex[Pageref]{\verb+\Pageref+}

You can use the \verb+\label{+\var{label}\} command to attach a
\var{label} to a position in your document. This label can be used to
create a hyperlink to this position from any other point in the
document.
This is done using the \verb+\link+ command:
\begin{example}
  \verb+\link{+\var{anchor}\}\{\var{label}\}
\end{example}
This command typesets anchor, expanding any commands in there, and
makes it an active hyperlink to the position marked with \var{label}:
\begin{verbatim}
   This parameter can be set in the
   \link{configuration panel}{sect:con-panel} to influence ...
\end{verbatim}

The \verb+\link+ command does not do anything exciting in the printed
document. It simply typesets the text \var{anchor}. If you also want a
reference in the \latex output, you will have to add a reference using
\verb+\ref+ or \verb+\pageref+. Sometimes you will want to place the
reference directly behind the \var{anchor} text. In that case you can
use the optional argument to \verb+\link+:
\begin{verbatim}
   This parameter can be set in the
   \link{configuration
     panel}[~(Section~\ref{sect:con-panel})]{sect:con-panel} to
   influence ... 
\end{verbatim}
The optional argument is ignored in the \Html-output.

The starred version \verb+\link*+ suppresses the anchor in the printed
version, so that we can write
\begin{verbatim}
   We will see \link*{later}[in Section~\ref{sl}]{sl}
   how this is done.
\end{verbatim}
It is very common to use \verb+\ref{+\textit{label}\verb+}+ or
\verb+\pageref{+\textit{label}\verb+}+ inside the optional
argument, where \textit{label} is the label set by the link command.
In that case the reference can be abbreviated as \verb+\Ref+ or
\verb+\Pageref+ (with capitals). These definitions are already active
when the optional arguments are expanded, so we can write the example
above as
\begin{verbatim}
   We will see \link*{later}[in Section~\Ref]{sl}
   how this is done.
\end{verbatim}
Often this format is not useful, because you want to put it
differently in the printed manual. Still, as long as the reference
comes after the \verb+\link+ command, you can use \verb+\Ref+ and
\verb+\Pageref+.
\begin{verbatim}
   \link{Such a file}{ipe-file} is at
   the same time ... a legal \LaTeX{}
   file\texonly{---see Section~\Ref}.
\end{verbatim}

\cindex[label]{\verb+Label+ environment} \cindex[ref]{\verb+\ref+,
  problems with} Note that when you use \latex's \verb+\ref+ command,
the label does not mark a \emph{position} in the document, but a
certain \emph{object}, like a section, equation etc. It sometimes
requires some care to make sure that both the hyperlink and the
printed reference point to the right place, and sometimes you will
have to place the label twice. The \Html-label tends to be placed
\emph{before} the interesting object---a figure, say---, while the
\latex-label tends to be put \emph{after} the object (when the
\verb+\caption+ command has set the counter for the label).  In such
cases you can use the new \+Label+ environment.  It puts the
\Html-label at the beginning of the text, but the latex label at the
end. For instance, you can correctly refer to a figure using:
\begin{verbatim}
   \begin{figure}
     \begin{Label}{fig:wonderful}
       %% here comes the figure itself
       \caption{Isn't it wonderful?}
     \end{Label}
   \end{figure}
\end{verbatim}
A \+\link{fig:wonderful}+ will now correctly lead to a position
immediatly above the figure, while a \+Figure~\ref{fig:wonderful}+
will show the correct number of the figure.

A special case occurs for section headings. Always place labels
\emph{after} the heading. In that way, the \latex reference will be
correct, and the Hyperlatex converter makes sure that the link will
actually lead to a point directly before the heading---so you can see
the heading when you follow the link. 

After a while, you may notice that in certain situations Hyperlatex
has a hard time dealing with a label. The reason is that although it
seems that a label marks a \emph{position} in your node, the \Html-tag
to set the label must surround some text. If there are other
\Html-tags in the neighborhood, Hyperlatex may not find an appropriate
contents for this container and has to add a space in that position
(which may sometimes mess up your formatting). In such cases you can
help Hyperlatex by using the \+Label+ environment, showing Hyperlatex
how to make a label tag surrounding the text in the environment.

Note that Hyperlatex uses the argument of a \+\label+ command to
produce a mnemonic \Html-label in the \Html file, but only if it is a
\link{legal URL}{label_urls}.

\index{ref@\+\ref+}
\index{htmlref@\+\htmlref+}
\label{htmlref}
In certain situations---for instance when it is to be expected that
documents are going to be printed directly from web pages, or when you
are porting a \latex-document to Hyperlatex---it makes sense to mimic
the standard way of referencing in \latex, namely by simply using the
number of a section as the anchor of the hyperlink leading to that
section.  Therefore, the \+\ref+ command is implemented in
Hyperlatex. It's default definition is
\begin{verbatim}
   \newcommand{\ref}[1]{\link{\htmlref{#1}}{#1}}
\end{verbatim}
The \+\htmlref+ command used here simply typesets the counter that was
saved by the \+\label+ command.  So I can simply write
\begin{verbatim}
   see Section~\ref{sec:cross-references}
\end{verbatim}
to refer to the current section: see
Section~\ref{sec:cross-references}.

\subsection{Links to external information}
\label{sec:external-hyperlinks}
\label{xlink}
\cindex[xlink]{\verb+\xlink+}

You can place a hyperlink to a given \var{URL} (\xlink{Universal
  Resource Locator}
{http://www.w3.org/hypertext/WWW/Addressing/Addressing.html}) using
the \verb+\xlink+ command. Like the \verb+\link+ command, it takes an
optional argument, which is typeset in the printed output only:
\begin{example}
  \verb+\xlink{+\var{anchor}\}\{\var{URL}\}
  \verb+\xlink{+\var{anchor}\}[\var{printed reference}]\{\var{URL}\}
\end{example}
In the \Html-document, \var{anchor} will be an active hyperlink to the
object \var{URL}. In the printed document, \var{anchor} will simply be
typeset, followed by the optional argument, if present. A starred
version \+\xlink*+ has the same function as for \+\link+.

If you need to use a \+~+ in the \var{URL} of an \+\xlink+ command, you have
to escape it as \+\~{}+ (the \var{URL} argument is an evaluated argument, so
that you can define macros for common \var{URL}'s).

\xname{hyperlatex_extlinks}
\subsection{Links into your document}
\label{sec:into-hyperlinks}
\cindex[xname]{\verb+\xname+}
\label{xname}
The Hyperlatex converter automatically partitions your document into
\Html-nodes.  These nodes are simply numbered sequentially. Obviously,
the resulting URL's are not useful for external references into your
document---after all, the exact numbers are going to change whenever
you add or delete a section, or when you change the
\link{\code{htmldepth}}{htmldepth}.

If you want to allow links from the outside world into your new
document, you will have to give that \Html node a mnemonic name that
is not going to change when the document is revised.

This can be done using the \+\xname{+\var{name}\+}+ command. It
assigns the mnemonic name \var{name} to the \emph{next} node created
by Hyperlatex. This means that you ought to place it \emph{in front
  of} a sectioning command.  The \+\xname+ command has no function for
the \LaTeX-document. No warning is created if no new node is started
in between two \+\xname+ commands.

The argument of \+\xname+ is not expanded, so you should not escape
any special characters (such as~\+_+). On the other hand, if you
reference it using \+\xlink+, you will have to escape special
characters.

Here is an example: This section \xlink{``Links into your
  document''}{hyperlatex\_extlinks.html} in this document starts as
follows. 
\begin{verbatim}
   \xname{hyperlatex_extlinks}
   \subsection{Links into your document}
   \label{sec:into-hyperlinks}
   The Hyperlatex converter automatically...
\end{verbatim}
This \Html-node can be referenced inside this document with
\begin{verbatim}
   \link{External links}{sec:into-hyperlinks}
\end{verbatim}
and both inside and outside this document with
\begin{verbatim}
   \xlink{External links}{hyperlatex\_extlinks.html}
\end{verbatim}

\label{label_urls}
\cindex[label]{\verb+\label+}
If you want to refer to a location \emph{inside} an \Html-node, you
need to make sure that the label you place with \+\label+ is a
legal URL. In other words, it should only contain characters in the
set
\begin{verbatim}
   a-z A-Z 0-9 $ - _ . + ! * ' ( ) ,
\end{verbatim}
%% $
Furthermore, your label may not consist of digits only.
(All labels that contain other characters are replaced by an
automatically created numbered label by Hyperlatex.)

The previous paragraph starts with
\begin{verbatim}
   \label{label_urls}
   \cindex[label]{\verb+\label+}
   If you want to refer to a location \emph{inside} an \Html-node,... 
\end{verbatim}
You can therefore \xlink{refer to that
  position}{hyperlatex\_extlinks.html\#label\_urls} from any document
using
\begin{verbatim}
   \xlink{refer to that position}{hyperlatex\_extlinks.html\#label\_urls}
\end{verbatim}
(Note that \+#+ and \+_+ have to be escaped in the \+\xlink+ command.)

\subsection{Bibliography and citation}
\label{sec:bibliography}
\cindex[thebibliography]{\code{thebibliography} environment}
\cindex[bibitem]{\verb+\bibitem+}
\cindex[Cite]{\verb+\Cite+}

Hyperlatex understands the \code{thebibliography} environment. Like
\latex, it creates a chapter or section (depending on the document
class) titled ``References''.  The \verb+\bibitem+ command sets a
label with the given \var{cite key} at the position of the reference.
This means that you can use the \verb+\link+ command to define a
hyperlink to a bibliography entry.

The command \verb+\Cite+ is defined analogously to \verb+\Ref+ and
\verb+\Pageref+ by \verb+\link+.  If you define a bibliography like
this
\begin{verbatim}
   \begin{thebibliography}{99}
      \bibitem{latex-book}
      Leslie Lamport, \cit{\LaTeX: A Document Preparation System,}
      Addison-Wesley, 1986.
   \end{thebibliography}
\end{verbatim}
then you can add a reference to the \latex-book as follows:
\begin{verbatim}
   ... we take a stroll through the
   \link{\LaTeX-book}[~\Cite]{latex-book}, explaining ...
\end{verbatim}

\cindex[htmlcite]{\+\htmlcite+} \cindex[cite]{\+\cite+} Furthermore,
the command \+\htmlcite+ generates the printed citation itself (in our
case, \+\htmlcite{latex-book}+ would generate
``\htmlcite{latex-book}''). The command \+\cite+ is approximately
implemented as \+\link{\htmlcite{#1}}{#1}+, so you can use it as usual
in \latex, and it will automatically become an active hyperlink, as in
``\cite{latex-book}''. (The actual definition allows you to use
multiple cite keys in a single \+\cite+ command.)

\cindex[bibliography]{\verb+\bibliography+}
\cindex[bibliographystyle]{\verb+\bibliographystyle+}
Hyperlatex also understands the \verb+\bibliographystyle+ command
(which is ignored) and the \verb+\bibliography+ command. It reads the
\textit{.bbl} file, inserts its contents at the given position and
proceeds as  usual. Using this feature, you can include bibliographies
created with Bib\TeX{} in your \Html-document!
It would be possible to design a \textsc{www}-server that takes queries
into a Bib\TeX{} database, runs Bib\TeX{} and Hyperlatex
to format the output, and sends back an \Html-document.

\cindex[htmlbibitem]{\+\htmlbibitem+} The formatting of the
bibliography can be customized by redefining the bibliography
environment \code{thebibliography} and the Hyperlatex macro
\code{\back{}htmlbibitem}. The default definitions are
\begin{verbatim}
   \newenvironment{thebibliography}[1]%
      {\chapter{References}\begin{description}}{\end{description}}
   \newcommand{\htmlbibitem}[2]{\label{#2}\item[{[#1]}]}
\end{verbatim}

If you use Bib\TeX{} to generate your bibliographies, then you will
probably want to incorporate hyperlinks into your \file{.bib}
files. No problem, you can simply use \+\xlink+. But what if you also
want to use the same \file{.bib} file with other (vanilla) \latex
files, which do not define the \+\xlink+ command?  What if you want to
share your \file{.bib} files with colleagues around the world who do
not know about Hyperlatex?

Here is a trick that solves this problem without defining a new
Bib\TeX{} style or something similar: You can put a \var{URL} into the
\emph{note} field of a Bib\TeX{} entry as follows:
\begin{verbatim}
   note = "\def\HTML{\XURL}{ftp://nowhere.com/paper.ps}"
\end{verbatim}
This is perfectly understandable for plain \latex, which will simply
ignore the funny prefix \+\def\HTML{\XURL}+ and typeset the \var{URL}.

In your Hyperlatex source, however, you can put these definitions in
the preamble:
\begin{verbatim}
   \W\newcommand{\def}{}
   \W\newcommand{\HTML}[1]{#1}
   \W\newcommand{\XURL}[1]{\xlink{#1}{#1}}
\end{verbatim}
This will turn the \emph{note} field into an active hyperlink to the
document in question.

(An alternative approach would be to redefine some \latex command in
Hyperlatex, such as \+\relax+.)

\subsection{Splitting your input}
\label{sec:splitting}
\label{input}
\cindex[input]{\verb+\input+}
\cindex[include]{\verb+\include+}
The \verb+\input+ command is implemented in Hyperlatex. The subfile is
inserted into the main document, and typesetting proceeds as usual.
You have to include the argument to \verb+\input+ in braces.
\+\include+ is understood as a synonym for \+\input+ (the command
\+\includeonly+ is ignored by Hyperlatex).

\subsection{Making an index or glossary}
\label{sec:index-glossary}
\label{index}
\cindex[index]{\verb+\index+}
\cindex[cindex]{\verb+\cindex+}
\cindex[htmlprintindex]{\verb+\htmlprintindex+}

The Hyperlatex converter understands the \verb+\index+ command. It
collects the entries specified, and you can include a sorted index
using \verb+\htmlprintindex+. This index takes the form of a menu with
hyperlinks to the positions where the original \verb+\index+ commands
where located.

You may want to specify a different sort key for an index
intry. If you use the index processor \code{makeindex}, then this can
be achieved in \latex by specifying \+\index{sortkey@entry}+.
This syntax is also understood by Hyperlatex. The entry
\begin{verbatim}
   \index{index@\verb+\index+}
\end{verbatim}
will be sorted like ``\code{index}'', but typeset in the index as
``\verb/\verb+\index+/''.

However, not everybody can use \code{makeindex}, and there are other
index processors around.  To cater for those other index processors,
Hyperlatex defines a second index command \verb+\cindex+, which takes
an optional argument to specify the sort key. (You may also like this
syntax better than the \+\index+ syntax, since it is more in line with
the general \latex-syntax.) The above example would look as follows:
\begin{verbatim}
   \cindex[index]{\verb+\index+}
\end{verbatim}
The \textit{hyperlatex.sty} style defines \verb+\cindex+ such that the
intended behavior is realized if you use the index processor
\code{makeindex}. If you don't, you will have to consult your
\cit{Local Guide} and redefine \verb+\cindex+ appropriately. (That may
be a bit tricky---ask your local \TeX{} guru for help.)

The index in this manual was created using \verb+\cindex+ commands in
the source file, the index processor \code{makeindex} and the following
code:
\begin{verbatim}
   \W \section*{Index}
   \W \htmlprintindex
   \T \input{hyperlatex.ind}
\end{verbatim}

You can generate a prettier index format more similar to the printed
copy by using the \code{makeidx} package donated by Sebastian Erdmann.
Include it using
\begin{verbatim}
   \W \usepackage{makeidx}
\end{verbatim}
in the preamble.


\subsection{Screen Output}
\label{sec:screen-output}
\index{typeout@\+\typeout+}
You can use \+\typeout+ to print a message while your file is being
processed.

\section{Designing it yourself}
\label{sec:design}

In this section we discuss the commands used to make things that only
occur in \Html-documents, not in printed papers. Practically all
commands discussed here start with \verb+\html+, indicating that the
command has no effect whatsoever in \latex.

\subsection{Making menus}
\label{sec:menus}

\label{htmlmenu}
\cindex[htmlmenu]{\verb+\htmlmenu+}

The \verb+\htmlmenu+ command generates a menu for the subsections
of the current section.
It takes a single argument, the depth of the desired menu. If you use
\verb+\htmlmenu{2}+ in a subsection, say, you will get a menu of
all subsubsections and paragraphs of this subsection.

If you use this command in a section, no \link{automatic
  menu}{htmlautomenu} for this section is created.

A typical application of this command is to put a ``master menu'' (the
analog of a table of contents) in the \link{top node}{topnode},
containing all sections of all levels of the document. This can be
achieved by putting \verb+\htmlmenu{6}+ in the text for the top node.

\htmlrule{}
\T\bigskip
Some people like to close off a section after some subsections of that
section, somewhat like this:
\begin{verbatim}
   \section{S1}
   text at the beginning of section S1
     \subsection{SS1}
     \subsection{SS2}
   closing off S1 text

   \section{S2}
\end{verbatim}
This is a bit of a problem for Hyperlatex, as it requires the text for
any given node to be consecutive in the file. A workaround is the
following:
\begin{verbatim}
   \section{S1}
   text at the beginning of section S1
   \htmlmenu{1}
   \texonly{\def\savedtext}{closing off S1 text}
     \subsection{SS1}
     \subsection{SS2}
   \texonly{\bigskip\savedtext}

   \section{S2}
\end{verbatim}

\subsection{Rulers and images}
\label{sec:bitmap}

\label{htmlrule}
\cindex[htmlrule]{\verb+\htmlrule+}
\cindex[htmlimage]{\verb+\htmlimage+}
The command \verb+\htmlrule+ creates a horizontal rule spanning the
full screen width at the current position in the \Html-document.
It has an optional argument that you can use to add additional
attributes to the \Html tag. The optional argument is not evaluated
further, so you should not escape any special characters.

Additional tags are currently only understood by the some browsers, so
use the optional argument at your own risk.
Here is an example.
\begin{verbatim}
   \htmlrule[width=70% align=center]
\end{verbatim}
\htmlonly{This will result in the following rule.}
\htmlrule[width=70% align=center]

\label{htmlimage}
The command \verb+\htmlimage{+\var{URL}\+}+ makes an inline bitmap
with the given \var{URL}. It takes an optional argument that can be
used to specify additional \Html-attributes understood by some \Html
browsers. So \verb+\htmlimage[ALIGN=CENTER]{image.xbm}+ includes the
image in \textit{image.xbm}, vertically centered at the current text
position. A more complicated example is:
\begin{example}
  \*htmlimage[align=left width=50 height=75 hspace=3]\{image.gif\}
\end{example}
The optional argument is not evaluated further, so you should not
escape any special characters.
The \var{URL} argument, on the other hand, is an evaluated argument, so that
you can define macros for common \var{URL}'s (such as your home page). That
means that if you need to use a special character (\+~+~is quite
common), you have to escape it (as~\+\~{}+ for the~\+~+).

This is what I use for figures in the \xlink{Ipe
  Manual}{http://www.postech.ac.kr/\~{}otfried/Ipe/Ipe.html} that
appear in both the printed document and the \Html-document:
\begin{verbatim}
   \begin{figure}
     \caption{The Ipe window}
     \begin{center}
       \texorhtml{\Ipe{window.ipe}}{\htmlimage{window.gif}}
     \end{center}
   \end{figure}
\end{verbatim}
(\verb+\Ipe+ is the command to include ``Ipe'' figures.)

\subsection{Adding raw Html}
\label{sec:raw-html}
\cindex[html]{\verb+\Html+}
\label{html}
\cindex[htmlsym]{\verb+\htmlsym+}
\cindex[rawhtml]{\verb+rawhtml+ environment}
\index{htmlinclude@\+\htmlinclude+}
\T \newcommand{\onequarter}{$1/4$}
\W \newcommand{\onequarter}{\htmlsym{##188}}

Hyperlatex provides a number of ways to access the \Html-tag level.

The \verb+\htmlsym{+\var{entity}\+}+ command creates the \Html entity
description \samp{\code{\&}\var{entity}\code{;}}.  It is useful if you
need symbols from the \textsc{iso} Latin~1 alphabet which are not
predefined in Hyperlatex.  You could, for instance, define a macro for
the fraction \onequarter{} as follows:
\begin{verbatim}
   \T \newcommand{\onequarter}{$1/4$}
   \W \newcommand{\onequarter}{\htmlsym{##188}}
\end{verbatim}

The most basic command is \verb+\html{+\var{tag}\+}+, which creates
the \Html tag \samp{\code{<}\var{tag}\code{>}}. This command is used
in the definition of most of Hyperlatex's commands and environments,
and you can use it yourself to achieve effects that are not available
in Hyperlatex directly. Note that \+\html+ looks up any attributes for
the tag that may have been set with
\link{\code{\*htmlattributes}}{htmlattributes}. If you want to avoid
this, use the starred version \+\html*+.

Finally, the \+rawhtml+ environment allows you to write plain \Html,
if you so desire.  Everything between \+\begin{rawhtml}+ and
  \+\end{rawhtml}+ will simply be included literally in the \Html
output.  Alternatively, you can include a file of \Html literally
using \+\htmlinclude+.

\subsection{Turning \TeX{} into bitmaps}
\label{sec:gif}
\cindex[gif]{\+gif+ environment}

Sometimes the only sensible way to represent some \latex concept in an
\Html-document is by turning it into a bitmap. Hyperlatex has an
environment \+gif+ that does exactly this: In the
\Html-version, it is turned into a reference to an inline
bitmap (just like \+\htmlimage+). In the \latex-version, the \+gif+
environment is equivalent to a \+tex+ environment. Note that running
the Hyperlatex converter doesn't create the bitmaps yet, you have to
do that in an extra step as described below.

The \+gif+ environment has three optional and one required arguments:
\begin{example}
  \*begin\{gif\}[\var{tags}][\var{resolution}][\var{font\_resolution}]%
\{\var{name}\}
    \var{\TeX{} material \ldots}
  \*end\{gif\}
\end{example}
For the \LaTeX-document, this is equivalent to
\begin{example}
  \*begin\{tex\}
    \var{\TeX{} material \ldots}
  \*end\{tex\}
\end{example}
For the \Html-version, it is equivalent to
\begin{example}
  \*htmlimage[\var{tags}]\{\var{name}.gif\}
\end{example}
The other two parameters, \var{resolution} and \var{font\_resolution},
are used when creating the \+gif+-file. They default to \math{100} and
\math{300} dots per inch.

Here is an example:
\begin{verbatim}
   \W\begin{quote}
   \begin{gif}{eqn1}
     \[
     \sum_{i=1}^{n} x_{i} = \int_{0}^{1} f
     \]
   \end{gif}
   \W\end{quote}
\end{verbatim}
produces the following output:
\W\begin{quote}
  \begin{gif}{eqn1}
    \[
    \sum_{i=1}^{n} x_{i} = \int_{0}^{1} f
    \]
  \end{gif}
\W\end{quote}

We could as well include a picture environment. The code
\texonly{\begin{footnotesize}}
\begin{verbatim}
  \begin{center}
    \begin{gif}[b][80]{boxes}
      \setlength{\unitlength}{0.1mm}
      \begin{picture}(700,500)
        \put(40,-30){\line(3,2){520}}
        \put(-50,0){\line(1,0){650}}
        \put(150,5){\makebox(0,0)[b]{$\alpha$}}
        \put(200,80){\circle*{10}}
        \put(210,80){\makebox(0,0)[lt]{$v_{1}(r)$}}
        \put(410,220){\circle*{10}}
        \put(420,220){\makebox(0,0)[lt]{$v_{2}(r)$}}
        \put(300,155){\makebox(0,0)[rb]{$a$}}
        \put(200,80){\line(-2,3){100}}
        \put(100,230){\circle*{10}}
        \put(100,230){\line(3,2){210}}
        \put(90,230){\makebox(0,0)[r]{$v_{4}(r)$}}
        \put(410,220){\line(-2,3){100}}
        \put(310,370){\circle*{10}}
        \put(355,290){\makebox(0,0)[rt]{$b$}}
        \put(310,390){\makebox(0,0)[b]{$v_{3}(r)$}}
        \put(430,360){\makebox(0,0)[l]{$\frac{b}{a} = \sigma$}}
        \put(530,75){\makebox(0,0)[l]{$r \in {\cal R}(\alpha, \sigma)$}}
      \end{picture}
    \end{gif}
  \end{center}
\end{verbatim}
\texonly{\end{footnotesize}}
creates the following image.
\begin{center}
  \begin{gif}[b][80]{boxes}
    \setlength{\unitlength}{0.1mm}
    \begin{picture}(700,500)
      \put(40,-30){\line(3,2){520}}
      \put(-50,0){\line(1,0){650}}
      \put(150,5){\makebox(0,0)[b]{$\alpha$}}
      \put(200,80){\circle*{10}}
      \put(210,80){\makebox(0,0)[lt]{$v_{1}(r)$}}
      \put(410,220){\circle*{10}}
      \put(420,220){\makebox(0,0)[lt]{$v_{2}(r)$}}
      \put(300,155){\makebox(0,0)[rb]{$a$}}
      \put(200,80){\line(-2,3){100}}
      \put(100,230){\circle*{10}}
      \put(100,230){\line(3,2){210}}
      \put(90,230){\makebox(0,0)[r]{$v_{4}(r)$}}
      \put(410,220){\line(-2,3){100}}
      \put(310,370){\circle*{10}}
      \put(355,290){\makebox(0,0)[rt]{$b$}}
      \put(310,390){\makebox(0,0)[b]{$v_{3}(r)$}}
      \put(430,360){\makebox(0,0)[l]{$\frac{b}{a} = \sigma$}}
      \put(530,75){\makebox(0,0)[l]{$r \in {\cal R}(\alpha, \sigma)$}}
    \end{picture}
  \end{gif}
\end{center}

It remains to describe how you actually generate those bitmaps from
your Hyperlatex source. This is done by running \latex on the input
file, setting a special flag that makes the resulting \dvi-file
contain an extra page for every \+gif+ environment.  Furthermore, this
\latex-run produces another file with extension \textit{.makegif},
which contains commands to run \+dvips+ and \+ps2gif+ to extract
the interesting pages into Postscript files which are then converted
to \+gif+ format. Obviously you need to have \+dvips+ and \+ps2gif+
installed if you want to use this feature.  (A shellscript \+ps2gif+
is supplied with Hyperlatex. This shellscript uses \+ghostscript+ to
convert the Postscript files to \+ppm+ format, and then runs
\+ppmtogif+ to convert these into \+gif+-files.)

Assuming that everything has been installed properly, using this is
actually quite easy: To generate the \+gif+ bitmaps defined in your
Hyperlatex source file \file{source.tex}, you simply use
\begin{example}
  hyperlatex -gif source.tex
\end{example}
Note that since this runs latex on \file{source.tex}, the
\dvi-file \file{source.dvi} will no longer be what you want!

\section{Controlling Hyperlatex}
\label{sec:customizing}

Practically everything about Hyperlatex can be modified and adapted to
your taste. In many cases, it suffices to redefine some of the macros
defined in the \link{\file{siteinit.hlx}}{siteinit} package.

\subsection{Siteinit, Init, and other packages}
\label{sec:packages}
\label{siteinit}

When Hyperlatex processes the \+\documentclass{class}+ command, it
tries to read the Hyperlatex package files \file{siteinit.hlx},
\file{init.hlx}, and \file{class.hlx} in this order.  These package
files implement most of Hyperlatex's functionality using \latex-style
macros. Hyperlatex looks for these files in the directory
\file{.hyperlatex} in the user's home directory, and in the
system-wide Hyperlatex directory selected by the system administrator
(or whoever installed Hyperlatex). \file{siteinit.hlx} contains the
standard definitions for the system-wide installation of Hyperlatex,
the package \file{class.hlx} (where \file{class} is one of
\file{article}, \file{report}, \file{book} etc) define the commands
that are different between different \latex classes.

System administrators can modify the default behavior of Hyperlatex by
modifying \file{siteinit.hlx}.  Users can modify their personal
version of Hyperlatex by creating a file
\file{\~{}/.hyperlatex/init.hlx} with definitions that override the
ones in \file{siteinit.hlx}.  Finally, all these definitions can be
overridden by redefining macros in the preamble of a document to be
converted.

To change the default depth at which a document is split into nodes,
the system administrator could change the setting of \+htmldepth+
in \file{siteinit.hlx}. A user could define this command in her
personal \file{init.hlx} file. Finally, we can simply use this command
directly in the preamble.

\subsection{Splitting into nodes and menus}
\label{htmldirectory}
\label{htmlname}
\cindex[htmldirectory]{\code{\back{}htmldirectory}}
\cindex[htmlname]{\code{\back{}htmlname}} \cindex[xname]{\+\xname+}
Normally, the \Html output for your document \file{document.tex} are
created in files \file{document\_?.html} in the same directory. You can
change both the name of these files as well as the directory using the
two commands \+\htmlname+ and \+\htmldirectory+ in the
preamble of your source file:
\begin{example}
  \back{}htmldirectory\{\var{directory}\}
  \back{}htmlname\{\var{basename}\}
\end{example}
The actual files created by Hyperlatex are called
\begin{quote}
\file{directory/basename.html}, \file{directory/basename\_1.html},
\file{directory/basename\_2.html},
\end{quote}
and so on. The filename can be changed for individual nodes using the
\link{\code{\*xname}}{xname} command.

\label{htmldepth}
\cindex[htmldepth]{\code{htmldepth}} Hyperlatex automatically
partitions the document into several \link{nodes}{nodes}. This is done
based on the \latex sectioning. The section commands
\code{\back{}chapter}, \code{\back{}section},
\code{\back{}subsection}, \code{\back{}subsubsection},
\code{\back{}paragraph}, and \code{\back{}subparagraph} are assigned
levels~0 to~5.

The counter \code{htmldepth} determines at what depth separate nodes
are created. The default setting is~4, which means that sections,
subsections, and subsubsections are given their own nodes, while
paragraphs and subparagraphs are put into the node of their parent
subsection. You can change this by putting
\begin{example}
  \back{}setcounter\{htmldepth\}\{\var{depth}\}
\end{example}
in the \link{preamble}{preamble}. A value of~0 means that
the full document will be stored in a single file.

\label{htmlautomenu}
\cindex[htmlautomenu]{\code{\back{}htmlautomenu}}
The individual nodes of an \Html document are linked together using
\emph{hyperlinks}. Hyperlatex automatically places buttons on every
node that link it to the previous and next node of the same depth, if
they exist, and a button to go to the parent node.

Furthermore, Hyperlatex automatically adds a menu to every node,
containing pointers to all subsections of this section. (Here,
``section'' is used as the generic term for chapters, sections,
subsections, \ldots.) This may not always be what you want. You might
want to add nicer menus, with a short description of the subsections.
In that case you can turn off the automatic menus by putting
\begin{example}
  \back{}setcounter\{htmlautomenu\}\{0\}
\end{example}
in the preamble. On the other hand, you might also want to have more
detailed menus, containing not only pointers to the direct
subsections, but also to all subsubsections and so on. This can be
achieved by using
\begin{example}
  \back{}setcounter\{htmlautomenu\}\{\var{depth}\}
\end{example}
where \var{depth} is the desired depth of recursion.
The default behavior corresponds to a \var{depth} of 1.

\subsection{Customizing the navigation panels}
\label{sec:navigation}
\label{htmlpanel}
\cindex[htmlpanel]{\+\htmlpanel+}
\cindex[toppanel]{\+\toppanel+}
\cindex[bottompanel]{\+\bottompanel+}
\cindex[bottommatter]{\+\bottommatter+}
Normally, Hyperlatex adds a ``navigation panel'' at the beginning of
every \Html node. This panel has links to the next and previous
node on the same level, as well as to the parent node. 

The easiest way to customize the navigation panel is to turn it off
for selected nodes. This is done using the commands \+\htmlpanel{0}+
and \+\htmlpanel{1}+. All nodes started while \+\htmlpanel+ is set
to~\math{0} are created without a navigation panel.

Furthermore, the navigation panels (and in fact the complete outline
of the created \Html files) can be customized to your own taste
by redefining some Hyperlatex macros. In fact, when it formats an
\Html node, Hyperlatex inserts the macro \+\toppanel+ at the
beginning, and the two macros \+\bottommatter+ and \+bottompanel+ at
the end. When \+\htmlpanel{0}+ has been set, then only \+\bottommatter+
is inserted.

The macros \+\toppanel+ and \+\bottompanel+ are responsible for
typesetting the navigation panels at the top and the bottom of every
node.  You can change the appearance of these panels by redefining
those macros. See \link{\file{siteinit.hlx}}{siteinit} for their
default definition.

\cindex[htmltopname]{\+\htmltopname+}
You can use \+\htmltopname+ to change the name of the top node.

If you have included language packages from the babel package, you can
change the language of the navigation panel using, for instance,
\+\htmlpanelgerman+. 

The following commands are useful for defining these macros:
\begin{itemize}
\item \+\HlxPrevUrl+, \+\HlxUpUrl+, and \+\HlxNextUrl+ return the URL
  of the next node in the backwards, upwards, and forwards direction.
  (If there is no node in that direction, the macro evaluates to the
  empty string.)
\item \+\HlxPrevTitle+, \+\HlxUpTitle+, and \+\HlxNextTitle+ return
  the title of these nodes.
\item \+\HlxBackUrl+ and \+\HlxForwUrl+ return the URL of the previous
  and following node (without looking at their depth)
\item \+\HlxBackTitle+ and \+\HlxForwTitle+ return the title of these
  nodes.
\item \+\HlxThisTitle+ and \+\HlxThisUrl+ return title and URL of the
  current node.
\item The command \+\EmptyP{expr}{A}{B}+ evaluates to \+A+ if \+expr+
  is not the empty string, to \+B+ otherwise.
\end{itemize}


\subsection{Setting the Html level}
\label{sec:html-level}
\label{htmllevel}

Hyperlatex supports the two ``official'' standards for \Html, namely
\Html2 and \Html3.2. The command \verb+\htmllevel+ determines which
kind of \Html will be generated. Legal values for the argument are
\texttt{html2} and \texttt{html3.2}.

The default is currently \texttt{html3.2}, which is understood by most
current browsers. However, this is subject to change without notice,
so if you want to generate a given \Html level, then include the
\+\htmllevel+ command in your document!

The setting of the \+\htmllevel+ has influence on the
\texorhtml{concepts in Table~\ref{tab:htmllevel}.}{following concepts:}
\begin{table}[ht]
  \begin{center}
    \T\leavevmode
    \begin{tabular}{lcc}
                     & \Html2 & \Html3.2\\
changing type-size   &        &    X    \\
sub- \& superscripts &        &    X    \\
tables               &        &    X    \\
centering            &        &    X    
    \end{tabular}
    \T\caption{}\label{tab:htmllevel}
  \end{center}
\end{table}

Note that the optional argument of \link{\code{\*htmlrule}}{htmlrule}
and \link{\code{\*htmlimage}}{htmlimage} allows you to add arbitrary
attributes that may violate the standard that you have chosen with
\+\htmllevel+. The same may be true if you use
\link{\code{\*htmlattributes}}{htmlattributes}.

\subsection{Changing the formatting of footnotes}
The appearance of footnotes in the \Html output can be customized by
redefining several macros:

The macro \code{\*htmlfootnotemark\{\var{n}\}} typesets the mark that
is placed in the text as a hyperlink to the footnote text. See the
file \file{siteinit.hlx} for the default definition.

The environment \+thefootnotes+ generates the \Html node with the
footnote text. Every footnote is formatted with the macro
\code{\*htmlfootnoteitem\{\var{n}\}\{\var{text}\}}. The default
definitions are
\begin{verbatim}
   \newenvironment{thefootnotes}%
      {\chapter{Footnotes}
       \begin{description}}%
      {\end{description}}
   \newcommand{\htmlfootnoteitem}[2]%
      {\label{footnote-#1}\item[(#1)]#2}
\end{verbatim}

\subsection{Setting Html attributes}
\label{htmlattributes}
\cindex[htmlattributes]{\+\htmlattributes+}

If you are familiar with \Html, then you will sometimes want to be
able to add certain \Html attributes to the \Html tags generated by
Hyperlatex. This is possible using the command \+\htmlattributes+. Its
first argument is the name of an \Html tag (in capitals!), the second
argument can be used to specify attributes for that tag. The
declaration can be used in the preamble as well as in the document. A
new declaration for the same tag cancels any previous declaration,
unless you use the starred version of the command: It has effect only on
the next occurrence of the named tag, after which Hyperlatex reverts
to the previous state.

All the \Html-tags created using the \+\html+-command can be
influenced by this declaration. There are, however, also some
\Html-tags that are created directly in the Hyperlatex kernel and that
do not look up any attributes here. You can only try and see (and
complain to me if you need to set attribute for a certain tag where
Hyperlatex doesn't allow it).

Some common applications:

\Html3.2 allows you to specify the background color of an \Html node
using an attribute that you can set as follows. (If you do this in
\file{init.hlx} or the preamble of your file, all nodes of your
document will be colored this way.)
\begin{verbatim}
   \htmlattributes{BODY}{BGCOLOR="#ffffe6"}
\end{verbatim}

The following declaration makes the tables in your document have
borders. 
\begin{verbatim}
   \htmlattributes{TABLE}{BORDER}
\end{verbatim}

A more compact representation of the list environments can be enforced
using (this is for the \+itemize+ environment):
\begin{verbatim}
   \htmlattributes{UL}{COMPACT}
\end{verbatim}

The following attributes make section and subsection headings be
centered.
\begin{verbatim}
   \htmlattributes{H1}{ALIGN="CENTER"}
   \htmlattributes{H2}{ALIGN="CENTER"}
\end{verbatim}

\subsection{Making characters non-special}
\label{not-special}
\cindex[notspecial]{\+\NotSpecial+}
\cindex[tex]{\code{tex}}

Sometimes it is useful to turn off the special meaning of some of the
ten special characters of \latex. For instance, when writing
documentation about programs in~C, it might be useful to be able to
write \code{some\_variable} instead of always having to type
\code{some\*\_variable}, especially if you never use any formula and
hence do not need the subscript function. This can be achieved with
the \link{\code{\*NotSpecial}}{not-special} command.
The characters that you can make non-special are
\begin{verbatim}
      ~  ^  _  #  $  &
\end{verbatim}
%% $
For instance, to make characters \kbd{\$} and \kbd{\^{}} non-special,
you need to use the command
\begin{verbatim}
      \NotSpecial{\do\$\do\^}
\end{verbatim}
Yes, this syntax is weird, but it makes the implementation much easier.

Note that whereever you put this declaration in the preamble, it will
only be turned on by \+\+\+begin{document}+. This means that you can
still use the regular \latex special characters in the
preamble.

Even within the \link{\code{iftex}}{iftex} environment the characters
you specified will remain non-special. Sometimes you will want to
return them their full power. This can be done in a \code{tex}
environment. It is equivalent to \code{iftex}, but also turns on all
ten special \latex characters.

\subsection{Extending Hyperlatex}
\label{sec:extending}

As mentioned above, the \+documentclass+ command looks for files that
implement \latex classes in the directory \file{\~{}/.hyperlatex} and
the system-wide Hyperlatex directory.  The same is true for the
\+\usepackage{package}+ commands in your document.

Some support has been implemented for a few of these \latex packages,
and their number is growing.  We first list the currently available
packages, and then explain how you can use this mechanism to provide
support for packages that are not yet supported by Hyperlatex.

\subsubsection{The \file{sequential} package}
\label{sequential-package}

Some people prefer to have the \emph{Next} and \emph{Prev} buttons in
the navigation panels point to the sequentially adjacent nodes. In
other words, when you press \emph{Next} repeatedly, you browse through
the document in linear order.

The package \file{sequential} provides this behavior. To use it,
simply put
\begin{verbatim}
   \W\usepackage{sequential}
\end{verbatim}
in the preamble of the document (or
in your \file{init.hlx} file, if you want this behavior for all your
documents).

\subsubsection{The \file{emulate} package}
\label{emulate-package}

Sometimes it is desirable to convert a given \latex-file into \Html
with as little work as possible. Hyperlatex has not been designed for
this, and by default many \latex-commands are not available in
Hyperlatex.  The \file{emulate} package contains (dummy) definitions
for many of the missing \latex-commands. To convert a given
\latex-document, simply add a
\begin{verbatim}
   \W\usepackage{emulate}
\end{verbatim}
declaration in the preamble and try running Hyperlatex on the file.

Please do not take the existance of the \code{emulate} package as an
indication that I want to turn Hyperlatex into a general
\latex-to-\Html converter.  I will accept contributions for the
\code{emulate} package that allow Hyperlatex to deal with existing
\latex code, but I don't plan to spend much time on providing such
support myself, if it does not contribute to Hyperlatex's real goal:
providing an environment that makes it easy to produce well-written
documents in both printed and \Html form. 

\subsubsection{The \file{frames} package}
\label{frames-package}

If the package \file{frames} is enabled by putting a line
\begin{verbatim}
   \W\usepackage{frames}
\end{verbatim}
in the preamble, Hyperlatex creates \Html-files using frames and
JavaScript macros.  Since it is using JavaScript~1.1, which is
currently only supported by  Netscape navigator 3.0 or higher, you
should probably not enable this for documents available to the whole
world (but you can try it for documents on your local network, if
everybody is using the same browser).

There are two different layouts available. The alternative, simpler
one can be used by using \+\W\usepackage[simple]{frames}+ in the preamble.

\subsubsection{Xspace}
\cindex[xspace]{\+\xspace+}
Support for the \+xspace+ package is already built into
Hyperlatex. The macro \+\xspace+ works as it does in \latex.


\subsubsection{Longtable}
\cindex[longtable]{\+longtable+ environment}

The \+longtable+ environment allows for tables that are split over
multiple pages. In \Html, obviously splitting is unnecessary, so
Hyperlatex treats a \+longtable+ environment identical to a \+tabular+
environment. You can use \+\label+ and \+\link+ inside a \+longtable+
environment to create cross references between entries.

The macros \+\endhead+ and \+\endfirsthead+ are ignored by
Hyperlatex. All other macros defined by the package have to be
escaped.

\begin{ifhtml}
  Here is an example:
  \T\setlongtables
  \W\begin{center}
    \begin{longtable}[c]{|cl|}
      \hline
      \multicolumn{2}{|c|}{Language Codes (ISO 639:1988)} \\
      code & language \\ \hline
      \endfirsthead
      \T\hline
      \T\multicolumn{2}{|l|}{\small continued from prev.\ page}\\ \hline
      \T code & language \\ \hline
      \T\endhead
      \T\hline\multicolumn{2}{|r|}{\small continued on next page}\\ \hline
      \T\endfoot
      \T\hline
      \T\endlastfoot
      \texttt{aa} & Afar \\
      \texttt{am} & Amharic \\
      \texttt{ay} & Aymara \\
      \texttt{ba} & Bashkir \\
      \texttt{bh} & Bihari \\
      \texttt{bo} & Tibetan \\
      \texttt{ca} & Catalan \\
      \texttt{cy} & Welch
    \end{longtable}
  \W\end{center}
\end{ifhtml}

\subsubsection{Tabularx}
\index{tabularx environment@\+tabularx+ environment}

The X column type is implemented.

\subsubsection{Using color in Hyperlatex}
\index{color}
\cindex[color]{\+\color+}
\cindex[textcolor]{\+\textcolor+}
\cindex[definecolor]{\+\definecolor+}
\cindex[newgray]{\+\newgray+}
\cindex[newrgbcolor]{\+\newrgbcolor+}
\cindex[newcmykcolor]{\+\newcmykcolor+}
\cindex[columncolor]{\+\columncolor+}
\cindex[rowcolor]{\+\rowcolor+}

From the \code{color} package: \+\color+, \+\textcolor+,
\+\definecolor+.

From the \code{pstcol} package: \+\newgray+, \+\newrgbcolor+,
\+\newcmykcolor+.

From the \code{colortbl} package: \+\columncolor+, \+\rowcolor+.

\subsubsection{Multirow}
A \latex package that supports table cells spanning multiple rows.

\subsubsection{Babel}
\index{babel}
\index{german}
\index{french}
\index{english}
\label{sec:german}

Thanks to Eric Delaunay, the babel package is supported with english,
french, and german modes. If you need support for a different
language, try to implement it yourself by looking at the files
\file{english.hlx}, \file{german.hlx}, or \file{french.hlx}.

\selectlanguage{german} For instance, the german mode implements all
the \"{}-commands of the babel package.  In addition, it defines the
macros for making quotation marks.  So you can easily write something
like this:
\begin{quotation}
  Der K"onig sa"z da  und "uberlegte sich, wieviele
  "Ochslegrade wohl der wei"ze Wein haben w"urde, als er pl"otzlich
  "<Majest\'e"> rufen h"orte.
\end{quotation}
by writing:
\begin{verbatim}
  Der K"onig sa"z da  und "uberlegte sich, wieviele
  "Ochslegrade wohl der wei"ze Wein haben w"urde, als er pl"otzlich
  "<Majest\'e"> rufen h"orte.
\end{verbatim}

You can also switch to German date format, or use German navigation
panel captions using \+\htmlpanelgerman+.
\selectlanguage{english}

\subsubsection{Writing your own extensions}

Whenever Hyperlatex processes a \+\documentclass+ or \+\usepackage+
command, it first saves the options, then tries to find the file
\file{package.hlx} in either the \file{.hyperlatex} or the systemwide
Hyperlatex directories.  If such a file is found, it is inserted into
the document at the current location and processed as usual. This
provides an easy way to add support for many \latex packages by simply
adding \latex commands.  You can test the options with the \+ifoption+
environment (see \file{babel.hlx} for an example).

To see how it works, have a look at the package files in the
distribution. 

If you want to do something more ambitious, you may need to do some
Emacs lisp programming. An example is \file{german.hlx}, that makes
the double quote character active using a piece of Emacs lisp code.
The lisp code is embedded in the \file{german.hlx} file using the
\+\HlxEval+ command.

\index{counters}
\label{counters}
\cindex[setcounter]{\+\setcounter+}
\cindex[newcounter]{\+\newcounter+}
\cindex[addtocounter]{\+\addtocounter+}
\cindex[stepcounter]{\+\stepcounter+}
\cindex[refstepcounter]{\+\refstepcounter+}
Note that Hyperlatex now provides rudimentary support for counters. 
The commands \+\setcounter+, \+\newcounter+, \+\addtocounter+,
\+\stepcounter+, and \+\refstepcounter+ are implemented, as well as
the \+\the+\var{countername} command that returns the current value of
the counter. The counters are used for numbering sections, you could
use them to number theorems or other environments as well.

If you write a support file for one of the standard \latex packages,
please share it with us.

\begin{comment}
\xname{hyperlatex_upgrade}
\section{Upgrading from Hyperlatex~1.3}
\label{sec:upgrading}

If you have used Hyperlatex~1.3 before, then you may be surprised by
this new version of Hyperlatex. A number of things have changed in an
incompatible way. In this section we'll go through them to make the
transition easier. (See \link{below}{easy-transition} for an easy way
to use your old input files with Hyperlatex~1.4 and~2.0.)

You may wonder why those incompatible changes were made. The reason is
that I wrote the first version of Hyperlatex purely for personal use
(to write the Ipe manual), and didn't spent much care on some design
decisions that were not important for my application.  In particular,
there were a few ideosyncrasies that stem from Hyperlatex's origin in
the Emacs \latexinfo package. As there seem to be more and more
Hyperlatex users all over the world, I decided that it was time to do
things properly. I realize that this is a burden to everyone who is
already using Hyperlatex~1.3, but think of the new users who will find
Hyperlatex so much more familiar and consistent.

\begin{enumerate}
\item In Hyperlatex~1.4 and up all \link{ten special
    characters}{sec:special-characters} of \latex are recognized, and
  have their usual function. However, Hyperlatex now offers the
  command \link{\code{\*NotSpecial}}{not-special} that allows you to
  turn off a special character, if you use it very often.

  The treatment of special characters was really a historic relict
  from the \latexinfo macros that I used to write Hyperlatex.
  \latexinfo has only three special characters, namely \verb+\+,
  \verb+{+, and \verb+}+.  (\latexinfo is mainly used for software
  documentation, where one often has to use these characters without
  their special meaning, and since there is no math mode in info
  files, most of them are useless anyway.)

\item A line that should be ignored in the \dvi output has to be
  prefixed with \+\W+ (instead of \+\H+).

  The old command \+\H+ redefined the \latex command for the Hungarian
  accent. This was really an oversight, as this manual even
  \link{shows an example}{hungarian} using that accent!
  
\item The old Hyperlatex commands \verb-\+-, \+\*+, \+\S+, \+\C+,
  \+\minus+, \+\sim+ \ldots{} are no longer recognized by
  Hyperlatex~1.4.

  It feels wrong to deviate from \latex without any reason. You can
  easily define these commands yourself, if you use them (see below).
    
\item The \+\htmlmathitalics+ command has disappeared (it's now the
  default)
  
\item Within the \code{example} environment, only the four
  characters \+%+, \+\+, \+{+, and \+}+ are special.

  In Hyperlatex~1.3, the \+~+ was special as well, to be more
  consistent. The new behavior seems more consistent with having ten
  special characters.
  
\item The \+\set+ and \+\clear+ commands have been removed, and their
  function has been \link{taken over}{sec:flags} by
  \+\newcommand+\texonly{, see Section~\Ref}.

\item So far we have only been talking about things that may be a
  burden when migrating to Hyperlatex~1.4.  Here are some new features
  that may compensate you for your troubles:
  \begin{menu}
  \item The \link{starred versions}{link} of \+\link*+ and \+\xlink*+.
  \item The command \link{\code{\*texorhtml}}{texorhtml}.
  \item It was difficult to start an \Html node without a heading, or
    with a bitmap before the heading. This is now
    \link{possible}{sec:sectioning} in a clean way.
  \item The new \link{math mode support}{sec:math}.
  \item \link{Footnotes}{sec:footnotes} are implemented.
  \item Support for \Html \link{tables}{sec:tabular}.
  \item You can select the \link{\Html level}{sec:html-level} that you
    want to generate.
  \item Lots of possibilities for customization.
  \end{menu}
\end{enumerate}

\label{easy-transition}
Most of your files that you used to process with Hyperlatex~1.3 will
probably not work with newer versions of Hyperlatex immediately. To
make the transition easier, you can include the following declarations
in the preamble of your document (or even in your \file{init.hlx}
file). These declarations make Hyperlatex behave very much like
Hyperlatex~1.3---only five special characters, the control sequences
\+\C+, \+\H+, and \+\S+, \+\set+ and \+\clear+ are defined, and so are
the small commands that have disappeared.  If you need only some
features of Hyperlatex~1.3, pick them and copy them into your
preamble.
\begin{quotation}\T\small
\begin{verbatim}

%% In Hyperlatex 1.3, ^ _ & $ # were not special
\NotSpecial{\do\^\do\_\do\&\do\$\do\#}

%% commands that have disappeared
\newcommand{\scap}{\textsc}
\newcommand{\italic}{\textit}
\newcommand{\bold}{\textbf}
\newcommand{\typew}{\texttt}
\newcommand{\dmn}[1]{#1}
\newcommand{\minus}{$-$}
\newcommand{\htmlmathitalics}{}

%% redefinition of Latex \sim, \+, \*
\W\newcommand{\sim}{\~{}}
\let\TexSim=\sim
\T\newcommand{\sim}{\ifmmode\TexSim\else\~{}\fi}
\newcommand{\+}{\verb+}
\renewcommand{\*}{\back{}}

%% \C for comments
\W\newcommand{\C}{%}
\T\newcommand{\C}{\W}

%% \S to separate cells in tabular environment
\newcommand{\S}{\htmltab}

%% \H for Html mode
\T\let\H=\W
\W\newcommand{\H}{}

%% \set and \clear
\W\newcommand{\set}[1]{\renewcommand{\#1}{1}}
\W\newcommand{\clear}[1]{\renewcommand{\#1}{0}}
\T\newcommand{\set}[1]{\expandafter\def\csname#1\endcsname{1}}
\T\newcommand{\clear}[1]{\expandafter\def\csname#1\endcsname{0}}
\end{verbatim}
\end{quotation}

\xname{hyperlatex_two}
\section{Upgrading to Hyperlatex~2.0}
\label{sec:upgrading-2.0}
Hyperlatex~2.0 is a major new revision. Hyperlatex now consists of a
kernel written in Emacs lisp that mainly acts as a macro interpreter
and that implements some low-level functionality.  Most of the
Hyperlatex commands are now defined in the system-wide initialization
file \link{\file{siteinit.hlx}}{siteinit}.  This will make it much
easier to customize, update, and improve Hyperlatex.

There are two major incompatibilities with respect to previous
versions. First, the \+\topnode+ command has disappeared. Now,
everything between \+\+\+begin{document}+ and the first sectioning
command goes in the top node, and the heading is generated using the
\+\maketitle+ command. Secondly, the preamble is now fully parsed by
Hyperlatex---which means that Hyperlatex will choke on all the
specialized \latex-stuff that it simply ignored in previous versions.

You will have to use \+\T+ or the \+iftex+ environment to escape
everything that Hyperlatex doesn't understand.  I realize that this
will break many user's existing documents, but it also makes many
improvements possible.

The \+\xlabel+ command has also disappeared. It was a bit of a
nuisance, because it often did not produce labels in the right place.
Now the \+\label+ command produces mnemonic \Html-labels, provided
that the argument is a \link{legal URL}{label_urls}.

So instead of having to write
\begin{verbatim}
   \xlabel{interesting_section}
   \subsection{Interesting section}
\end{verbatim}
you can now use the standard paradigm:
\begin{verbatim}
   \subsection{Interesting section}
   \label{interesting_section}
\end{verbatim}
\end{comment}

\section{Changes since Hyperlatex~1.0}
\label{sec:changes}

\paragraph{Changes from~1.0 to~1.1}
\begin{menu}
\item
  The only change that introduces a real incompatibility concerns
  the percent sign \kbd{\%}. It has its usual \LaTeX-meaning of
  introducing a comment in Hyperlatex~1.1, but was not special in
  Hyperlatex~1.0.
\item
  Fixed a bug that made Hyperlatex swallow certain \textsc{iso}
  characters embedded in the text.
\item
  Fixed \Html tags generated for labels such that they can be
  parsed by \code{lynx}.
\item
  The commands \link{\code{\*+\var{verb}+}}{verbatim} and
  \code{\*=} are now shortcuts for
  \verb-\verb+-\var{verb}\verb-+- and \+\back+.
\item
  It is now possible to place labels that can be accessed from the
  outside of the document using \link{\code{\*xname}}{xname} and
  \code{\*xlabel}.
\item
  The navigation panels can now be suppressed using
  \link{\code{\*htmlpanel}}{sec:navigation}.
\item
  If you are using \LaTeXe, the Hyperlatex input
    mode is now turned on at \+\begin{document}+. For
  \LaTeX2.09 it is still turned on by \+\topnode+.
\item
  The environment \link{\code{gif}}{sec:gif} can now be used to turn
  \dvi information into a bitmap that is included in the
  \Html-document.
\end{menu}

\paragraph{Changes from~1.1 to~1.2}
Hyperlatex~1.2 has a few new options that allow you to better use the
extended \Html tags of the \code{netscape} browser.
\begin{menu}
\item \link{\code{\*htmlrule}}{htmlrule} now has an optional argument.
\item The optional argument for the \link{\code{\*htmlimage}}{htmlimage}
  command and the \link{\code{gif} environment}{sec:gif} has been
  extended.
\item The \link{\code{center} environment}{sec:displays} now uses the
  \emph{center} \Html tag understood by some browsers.
\item The \link{font changing commands}{font-changes} have been
  changed to adhere to \LaTeXe. The \link{font size}{sec:type-size} can be
  changed now as well, using the usual \latex commands.
\end{menu}

\paragraph{Changes from~1.2  to~1.3}
Hyperlatex~1.3 fixes a few bugs.

\paragraph{Changes from~1.3  to~1.4}
Hyperlatex~1.4 introduces some incompatible changes, in particular the
ten special characters. There is support for a number of
\Html3 features.
\begin{menu}
\item All ten special \latex characters are now also special in
  Hyperlatex. However, the \+\NotSpecial+ command can be used to make
  characters non-special. 
\item Some non-standard-\latex commands (such as \+\H+, \verb-\+-,
  \+\*+, \+\S+, \+\C+, \+\minus+) are no longer recognized by
  Hyperlatex to be more like standard Latex.
\item The \+\htmlmathitalics+ command has disappeared (it's now the
  default, unless we use \texttt{<math>} tags.)
\item Within the \code{example} environment, only the four
  characters \+%+, \+\+, \+{+, and \+}+ are special now.
\item Added the starred versions of \+\link*+ and \+\xlink*+.
\item Added \+\texorhtml+.
\item The \+\set+ and \+\clear+ commands have been removed, and their
  function has been taken over by \+\newcommand+.
\item Added \+\htmlheading+, and the possibility of leaving section
  headings empty in \Html.
\item Added math mode support.
\item Added tables using the \texttt{<table>} tag.
\item \ldots and many other things. 
\end{menu}

\paragraph{Changes from~1.4  to~2.0}
Hyperlatex~2.0 is a major new revision. Hyperlatex now consists of a
kernel written in Emacs lisp that mainly acts as a macro interpreter
and that implements some low-level functionality.  Most of the
Hyperlatex commands are now defined in the system-wide initialization
file \link{\file{siteinit.hlx}}{siteinit}.  This will make it much
easier to customize, update, and improve Hyperlatex.
\begin{menu}
\item Made Hyperlatex kernel deal only with macro processing and
  fundamental tasks.  High-level functionality has been moved to the
  Hyperlatex macro level in \file{siteinit.hlx}.
\item The preamble is now parsed properly, and the treatment of the
  classes and packages with \code{\back{}documentclass} and
  \code{\back{}usepackage} has been revised to allow for easier
  customization by loading macro packages. 
\item Added Peter D. Mosses's \texttt{tabbing} package to
  distribution.
\item Changed \texttt{ps2gif} to use \code{netpbm}'s version of
  \code{ppmtogif}, which makes \code{giftrans} unnecessary.
\item Added explanation of some features to the manual.
\item The \link{\code{\*index} command}{index} now understands the
  \emph{sortkey@entry} syntax of \+makeindex+.
\item Fixed the problem that forced one to put a space at the end of
  commands.
\item The \+\xlabel+ command has been
  removed. \link{\code{\*label}}{label_urls} has been extended to
  include its functionality.
\item And many others\ldots
\end{menu}

\paragraph{Changes from~2.0  to~2.1}
\begin{menu}
\item Bug fixes.
\item Added rudimentary support for \link{counters}{counters}.
\item Added support for creating packages that define active
  characters.  Created a basic implementation for
  \+\usepackage[german]{babel}+.
\end{menu}

\paragraph{Changes from~2.1  to~2.2}
\begin{menu}
\item Extended \link{counters}{counters} considerably, implementing
  counters within other counters.  Some special \+\html+\ldots{}
  commands where replaced by counters, such as \+\htmlautomenu+,
  \+\htmldepth+.
\item \+\htmlref+\{label\} returns the counter that was stepped before
  the label was defined.
\item Sections can now be numbered automatically by setting the
  counter \+secnumdepth+.
\item Removed searching for packages in Emacs lisp, instead provided
  \+\HlxEval+ command.
\item Added a package for making a frame based document with
  Javascript. Needed to put some support in the Hyperlatex kernel.
\item Extended the \+Emulate+ package with dummy declarations of many
  \latex commands.
\item \+\cite{key1,key2,key3}+ works now.
\item Counter arguments in \+\newtheorem+ now work.
\item Made additional icon bitmaps \file{greynext.xbm},
  \file{greyprevious.xbm}, and \file{greyup.xbm}. These are greyed out
  versions of the normal icons and used when the links are not active
  (when there is no next or previous node). They have to be installed
  on the server at the same place as the old icons.
\end{menu}

\paragraph{Changes from~2.2  to~2.3}
\begin{menu}
\item Added possibility of making \texttt{<META>} tags.
\item Compatibility with GNU Emacs 20.
\item Lots and lots of improvements by Eric Delaunay, including
  support for color packages, support for more column types and
  \+\newcolumntype+ for tabular environments, and a real Babel system
  that can handle multiple languages, even in the same document.
\item Allow \file{.htm} file extension for brain-damaged file systems.
\item Bugfixes, and new commands \+\HlxThisUrl+, \+\HlxThisTitle+,
  \+\htmltopname+ by Sebastian Erdmann.
\item Makeidx package by Sebastian Erdmann.
\item Improved GIF generation by Rolf Niepraschk (based on
  "Goossens/Rahtz/Mittelbach: The LaTeX Graphics Companion" pp.~455).
\item (2.3.1) Fixed bug in tabular.
\item (2.3.1) Moved tabbing environment into main Hyperlatex code.
\item (2.3.1) Array environment.
\end{menu}

\section{Acknowledgments}
\label{sec:acknowledgments}

Thanks to everybody who reported bugs or who suggested (or even
implemented!) useful new features. This includes Eric Delaunay,
Sebastian Erdmann, Rolf Niepraschk, Roland Jesse, Arne Helme, Bob
Kanefsky, Greg Franks, Jim Donnelly, Jon Brinkmann, Nick Galbreath,
Piet van Oostrum, Robert M.  Gray, Peter D. Mosses, Chris George,
Barbara Beeton, Ajay Shah, Erick Branderhorst, Wolfgang Schreiner,
Stephen Gildea, Gunnar Borthne, Christophe Prudhomme, Stefan Sitter,
Louis Taber, Jason Harrison.

\xname{hyperlatex_copyright}
\section{Copyright}
\label{sec:copyright}

Hyperlatex is ``free,'' this means that everyone is free to use it and
free to redistribute it on certain conditions. Hyperlatex is not in
the public domain; it is copyrighted and there are restrictions on its
distribution as follows:
  
Copyright \copyright{} 1994-1998 Otfried Cheong
  
This program is free software; you can redistribute it and/or modify
it under the terms of the \textsc{Gnu} General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.
     
This program is distributed in the hope that it will be useful, but
\emph{without any warranty}; without even the implied warranty of
\emph{merchantability} or \emph{fitness for a particular purpose}.
See the \xlink{\textsc{Gnu} General Public
  License}{http://www.gnu.org/copyleft/gpl.html} for more details.
\begin{iftex}
  A copy of the \textsc{Gnu} General Public License is available on the
  World Wide web.\footnote{at
    \texttt{http://www.gnu.org/copyleft/gpl.html}} You
  can also obtain it by writing to the Free Software Foundation, Inc.,
  675 Mass Ave, Cambridge, MA 02139, USA.
\end{iftex}

\begin{thebibliography}{99}
\bibitem{latex-book}
  Leslie Lamport, \cit{\LaTeX: A Document Preparation System,}
  Second Edition, Addison-Wesley, 1994.
\end{thebibliography}

%%\htmlpanel{0}
\W \section*{Index}
\label{sec:index}
\htmlprintindex
\T \input{hyperlatex.ind}

\end{document}