Extending HyperlatexTopDesigning it yourselfControlling HyperlatexContentsIndex

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.

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.

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.

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.

If you wish to add additional fields (such as an index or table of contents entry) to the navigation panel, you can use \htmlpanelfield in the preamble. It takes two arguments, the text to show in the field, and a label in the document where clicking the link should take you. For instance, the navigation panels for this manual were created by adding the following two lines in the preamble:

\htmlpanelfield{Contents}{hlxcontents}
\htmlpanelfield{Index}{hlxindex}

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

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}

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 \xmlattributes. Its first argument is the name of an HTML tag (in lower case!), 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 \xml-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.) Note that this usage is deprecated, you should be using a style sheet instead.

   \xmlattributes{body}{bgcolor="#ffffe6"}

The following declaration makes the tables in your document have borders.

   \xmlattributes{table}{border}

A more compact representation of the list environments can be enforced using (this is for the itemize environment):

   \xmlattributes{ul}{compact}

The following attributes make section and subsection headings be centered.

   \xmlattributes{h1}{align="center"}
   \xmlattributes{h2}{align="center"}

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.

CSS, Character Sets, and so on

An HTML-file can carry a number of tags in the HTML-header, which is created automatically by Hyperlatex. There are two commands to create such header tags:

\htmlcss creates a link to a cascaded style sheet. The single argument is the URL of the style sheet. The tag will be added to every node created after the command has been processed. Use an empty argument to turn of the CSS link.

\htmlcharset tags the HTML-file as being encoded in a particular character set. Use an empty argument to turn off creation of the tag.

Here is an example:

\htmlcss{http://www.w3.org/StyleSheets/Core/Modernist}
\htmlcharset{EUC-KR}

Otfried Cheong, July 13, 2004

Extending HyperlatexTopDesigning it yourselfControlling HyperlatexContentsIndex