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 siteinit.hlx package.
When Hyperlatex processes the \documentclass{class}
command, it
tries to read the Hyperlatex package files siteinit.hlx,
init.hlx, and 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
.hyperlatex in the user's home directory, and in the
system-wide Hyperlatex directory selected by the system administrator
(or whoever installed Hyperlatex). siteinit.hlx contains the
standard definitions for the system-wide installation of Hyperlatex,
the package class.hlx (where class is one of
article, report, book etc) define the commands
that are different between different LaTeX classes.
System administrators can modify the default behavior of Hyperlatex by modifying siteinit.hlx. Users can modify their personal version of Hyperlatex by creating a file ~/.hyperlatex/init.hlx with definitions that override the ones in 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 siteinit.hlx. A user could define this command in her
personal init.hlx file. Finally, we can simply use this command
directly in the preamble.
\htmlname
and \htmldirectory
in the
preamble of your source file:
The actual files created by Hyperlatex are called\htmldirectory{directory} \htmlname{basename}
directory/basename.html, directory/basename_1.html, directory/basename_2.html,and so on. The filename can be changed for individual nodes using the
\xname
command.
Hyperlatex automatically
partitions the document into several nodes. This is done
based on the LaTeX sectioning. The section commands
\chapter
, \section
,
\subsection
, \subsubsection
,
\paragraph
, and \subparagraph
are assigned
levels 0 to 5.
The counter 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
in the preamble. A value of 0 means that the full document will be stored in a single file.\setcounter{htmldepth}{depth}
The individual nodes of an HTML document are linked together using 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, ....) 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
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\setcounter{htmlautomenu}{0}
where depth is the desired depth of recursion. The default behavior corresponds to a depth of 1.\setcounter{htmlautomenu}{depth}
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 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 siteinit.hlx for their
default definition.
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:
\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.)
\HlxPrevTitle
, \HlxUpTitle
, and \HlxNextTitle
return
the title of these nodes.
\HlxBackUrl
and \HlxForwUrl
return the URL of the previous
and following node (without looking at their depth)
\HlxBackTitle
and \HlxForwTitle
return the title of these
nodes.
\HlxThisTitle
and \HlxThisUrl
return title and URL of the
current node.
\EmptyP{expr}{A}{B}
evaluates to A
if expr
is not the empty string, to B
otherwise.
Hyperlatex supports the two "official" standards for HTML, namely
HTML 2 and HTML 3.2. The command \htmllevel
determines which
kind of HTML will be generated. Legal values for the argument are
html2 and html3.2.
The default is currently 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
following concepts:
HTML 2 HTML 3.2 changing type-size X sub- & superscripts X tables X centering X
Note that the optional argument of \htmlrule
and \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
\htmlattributes
.
The macro \htmlfootnotemark{n}
typesets the mark that
is placed in the text as a hyperlink to the footnote text. See the
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
\htmlfootnoteitem{n}{text}
. The default
definitions are
\newenvironment{thefootnotes}% {\chapter{Footnotes} \begin{description}}% {\end{description}} \newcommand{\htmlfootnoteitem}[2]% {\label{footnote-#1}\item[(#1)]#2}
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:
HTML 3.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 init.hlx or the preamble of your file, all nodes of your document will be colored this way.)
\htmlattributes{BODY}{BGCOLOR="#ffffe6"}
The following declaration makes the tables in your document have borders.
\htmlattributes{TABLE}{BORDER}
A more compact representation of the list environments can be enforced
using (this is for the itemize
environment):
\htmlattributes{UL}{COMPACT}
The following attributes make section and subsection headings be centered.
\htmlattributes{H1}{ALIGN="CENTER"} \htmlattributes{H2}{ALIGN="CENTER"}
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 some_variable
instead of always having to type
some\_variable
, especially if you never use any formula and
hence do not need the subscript function. This can be achieved with
the \NotSpecial
command.
The characters that you can make non-special are
~ ^ _ # $ &For instance, to make characters $ and ^ non-special, you need to use the command
\NotSpecial{\do\$\do\^}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 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 tex
environment. It is equivalent to iftex
, but also turns on all
ten special LaTeX characters.
As mentioned above, the documentclass
command looks for files that
implement LaTeX classes in the directory ~/.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.
Some people prefer to have the Next and Prev buttons in the navigation panels point to the sequentially adjacent nodes. In other words, when you press Next repeatedly, you browse through the document in linear order.
The package sequential provides this behavior. To use it, simply put
\W\usepackage{sequential}in the preamble of the document (or in your init.hlx file, if you want this behavior for all your documents).
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 emulate package contains (dummy) definitions for many of the missing LaTeX-commands. To convert a given LaTeX-document, simply add a
\W\usepackage{emulate}declaration in the preamble and try running Hyperlatex on the file.
Please do not take the existance of the emulate
package as an
indication that I want to turn Hyperlatex into a general
LaTeX-to-HTML converter. I will accept contributions for the
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.
If the package frames is enabled by putting a line
\W\usepackage{frames}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.
xspace
package is already built into
Hyperlatex. The macro \xspace
works as it does in LaTeX.
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.
Here is an example:
Language Codes (ISO 639:1988) code language aa Afar am Amharic ay Aymara ba Bashkir bh Bihari bo Tibetan ca Catalan cy Welch
The X column type is implemented.
From the color
package: \color
, \textcolor
,
\definecolor
.
From the pstcol
package: \newgray
, \newrgbcolor
,
\newcmykcolor
.
From the colortbl
package: \columncolor
, \rowcolor
.
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 english.hlx, german.hlx, or french.hlx.
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:
Der König saß da und überlegte sich, wieviele Öchslegrade wohl der weiße Wein haben würde, als er plötzlich «Majesté» rufen hörte.by writing:
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.
You can also switch to German date format, or use German navigation
panel captions using \htmlpanelgerman
.
Whenever Hyperlatex processes a \documentclass
or \usepackage
command, it first saves the options, then tries to find the file
package.hlx in either the .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 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 german.hlx, that makes
the double quote character active using a piece of Emacs lisp code.
The lisp code is embedded in the german.hlx file using the
\HlxEval
command.
Note that Hyperlatex now provides rudimentary support for counters.
The commands \setcounter
, \newcounter
, \addtocounter
,
\stepcounter
, and \refstepcounter
are implemented, as well as
the \the
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.