Controlling HyperlatexTopMoving information aroundDesigning it yourselfContentsIndex

Designing it yourself

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 \html, indicating that the command has no effect whatsoever in LaTeX.

Making menus

The \htmlmenu command generates a menu for the subsections of a section. Its argument is the depth of the desired menu. If you use \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 automatic menu 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 top node, containing all sections of all levels of the document. This can be achieved by putting \htmlmenu{6} in the text for the top node.

You can create a menu for a section other than the current one by passing the number of that section as the optional argument, as in \htmlmenu[0]{6}, which creates a full table of contents. (The optional argument uses Hyperlatex's internal numbering-not very useful except for the top node, which is always number 0.)


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

   \section{S2}
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:
   \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}

Rulers and images

The command \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.

   \htmlrule[width=70% align=center]
This will result in the following rule.

The command \htmlimage{URL} makes an inline bitmap with the given URL. It takes an optional argument that can be used to specify additional HTML-attributes understood by some HTML browsers. So \htmlimage[ALIGN=CENTER]{image.xbm} includes the image in image.xbm, vertically centered at the current text position. A more complicated example is:

  \htmlimage[align=left width=50 height=75 hspace=3]{image.gif}
The optional argument is not evaluated further, so you should not escape any special characters. The URL argument, on the other hand, is an evaluated argument, so that you can define macros for common 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 Ipe Manual that appear in both the printed document and the HTML-document:

   \begin{figure}
     \caption{The Ipe window}
     \begin{center}
       \texorhtml{\Ipe{window.ipe}}{\htmlimage{window.gif}}
     \end{center}
   \end{figure}
(\Ipe is the command to include "Ipe" figures.)

Adding raw XML

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

The \xmlsym{entity} command creates the XML entity description &entity;. It is useful if you need symbols from the ISO Latin 1 alphabet which are not predefined in Hyperlatex. You could, for instance, define a macro for the fraction ¼ as follows:

   \T \newcommand{\onequarter}{$1/4$}
   \W \newcommand{\onequarter}{\xmlsym{##188}}

The most basic command is \xml{tag}, which creates the XML tag <tag>. 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 \xml looks up any attributes for the tag that may have been set with \xmlattributes. If you want to avoid this, use the starred version \xml*.

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

Turning TeX into bitmaps

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{gif}[tags][resolution][font_resolution]{name}
    TeX material ...
  \end{gif}
For the LaTeX-document, this is equivalent to
  \begin{tex}
    TeX material ...
  \end{tex}
For the HTML-version, it is equivalent to
  \htmlimage[tags]{name.gif}
The other two parameters, resolution and font_resolution, are used when creating the gif-file. They default to 100 and 300 dots per inch.

Here is an example:

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

We could as well include a picture environment. The code

  \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}
creates the following image.

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 .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 source.tex, you simply use

  hyperlatex -gif source.tex
Note that since this runs latex on source.tex, the DVI-file source.dvi will no longer be what you want!
Otfried Cheong, November 26, 2001

Controlling HyperlatexTopMoving information aroundDesigning it yourselfContentsIndex