Prev Up Next
Go backward to 9 Designing it yourself
Go up to Top
Go forward to 11 Changes since Hyperlatex 1.0

10 Controlling Hyperlatex

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.

10.1 Siteinit, Init, and other packages

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.

10.2 Splitting into nodes and menus

Normally, the HTML output for your document document.tex are created in files 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:
  \htmldirectory{directory}
  \htmlname{basename}
The actual files created by Hyperlatex are called
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

  \setcounter{htmldepth}{depth}
in the preamble. A value of 0 means that the full document will be stored in a single file.

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

  \setcounter{htmlautomenu}{0}
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}{depth}
where depth is the desired depth of recursion. The default behavior corresponds to a depth of 1.

10.3 Customizing the navigation panels

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 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:

10.4 Setting the Html level

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.

10.5 Changing the formatting of footnotes

The appearance of footnotes in the HTML output can be customized by redefining several macros:

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}

10.6 Setting Html attributes

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"}

10.7 Making characters non-special

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.

10.8 Extending Hyperlatex

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.

10.8.1 The sequential package

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).

10.8.2 The 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 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.

10.8.3 The frames package

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.

10.8.4 Xspace

Support for the xspace package is already built into Hyperlatex. The macro \xspace works as it does in LaTeX.

10.8.5 Longtable

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

10.8.6 Tabularx

The X column type is implemented.

10.8.7 Using color in Hyperlatex

From the color package: \color, \textcolor, \definecolor.

From the pstcol package: \newgray, \newrgbcolor, \newcmykcolor.

From the colortbl package: \columncolor, \rowcolor.

10.8.8 Multirow

A LaTeX package that supports table cells spanning multiple rows.

10.8.9 Babel

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.

10.8.10 Writing your own extensions

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 \thecountername 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.


Otfried Cheong, January 7, 2000

Prev Up Next