Extending Hyperlatex Contents Index

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.

The frames package

If you \usepackage{frames}, your document will use frames, like this manual. The navigation panel shown on the left hand side is implemented by \HlxFramesNavigation, modify it if you prefer a different layout.

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

Xspace

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

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.

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

Tabularx

The X column type is implemented.

Using color in Hyperlatex

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

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

From the colortbl package: \columncolor, \rowcolor.

Babel

Thanks to Eric Delaunay, the babel package is supported with English, French, German, Dutch, Italian, and Portuguese modes. If you need support for a different language, try to implement it yourself by looking at the files english.hlx, german.hlx, etc.

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.

Documenting code

The cppdoc package can be used to document code in C++ or Java. This is experimental, and may either be extended or removed in future Hyperlatex distributions. There are far more powerful code documentation tools available--I'm playing with the cppdoc package because I find a simple tool that I understand well more helpful than a complex one that I forget to use and therefore don't use.

The package defines a command cppinclude to include a C++ or Java header file. The header file is stripped down before it is interpreted by Hyperlatex, using certain comments to control the inclusion:

• A comment starting with /** and up to */ is included.
• Any line starting with //+ is included.
• A comment of the form //-- is converted to \begin{cppenv}, and the following code is not stripped. This environment is ended using //--. All known class names inside this environment will be converted to links.
• A comment of the form /// can be used at the end of the first line of a method. The method name will be extracted as the argument to \cppmethod,. The method declaration needs to be followed by a /** or //+ comment documenting the method.

Note that the cppenv environment and the \cppmethod command are not provided by cppdoc. You have to define them in your document. A simple definition would be:

\newenvironment{cppenv}{\begin{example}}{\end{example}}
\newcommand{\cppmethod}[1]{\paragraph{#1}}


You can use \cpplabel to put a label in the section documenting a certain class. \cpplabel{Engine} will place an ordinary label class:Engine in the document, and will also remember that Engine is the name of a class known in the project (and will therefore be converted to a link inside a cppenv environment and the argument to \cppmethod).

The command \cppclass takes a single class name as an argument, and creates a link if a label for that class has been defined in the document.

If you use \cppextras, then the vertical bar character is made active. You can use a pair of vertical bars as a shortcut for the \cppclass command.

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.

Macro names

You may wonder what the rationale behind the different macro names in Hyperlatex is. Here's the answer:

• A few macros like \link, \xlink and environments like menu, rawxml, example, ifhtml, iftex, ifset provide additional functionality to the markup language. They are understood by Hyperlatex and LaTeX (assuming \usepackage{hyperlatex}, of course).
• \xml and \html... macros allow the user to influence the generation of XML (HTML) output. They are meant to be used in Hyperlatex documents, but have no effect on the LaTeX output. They are understood by Hyperlatex and LaTeX (but are dummies in LaTeX).
• \Hlx... macros are understood by Hyperlatex, but not by LaTeX (they are not defined in hyperlatex.sty). They are meant for defining macros and environments in Hyperlatex without resorting to Lisp, making Hyperlatex styles easier to customize and maintain. They are used in siteinit.hlx, init.hlx, etc., and not normally used in Hyperlatex documents (you can use them inside of ifhtml environments or other escapes that stop LaTeX from complaining about them)

August 11, 2007

 Extending Hyperlatex Contents Index