Generating HTML constructs
Author: Luc Maranget

8 | Generating HTML constructs

- High-Level Commands
- More on included images
- The `rawhtml` environment
- Internal macros
- Examples

HEVEA output language being HTML, it is normal for users to insert hypertext constructs their documents, or to control colors.

8.1 | High-Level Commands

HEVEA provides high-level commands for doing this. Users are advised to use these macros in the first place, because it is easy to write incorrect HTML and that writting HTML directly may interfeer in nasty ways with HEVEA internals.

8.1.1 | Commands for Hyperlinks

A few commands for hyperlink management and included images are provided, all these commands have approriate equivalents defined by the `hevea` package (see section 5.2). Hence, a document that relies on these high-level commands still can be typeset by LATEX, provided it loads the `hevea` package.

Macro | HEVEA | LATEX
`\ahref{`url`}{`text`}` | make text an hyperlink to url |  | echo text
`\footahref{`url`}{`text`}` | make text an hyperlink to url |  | make url a footnote to text, url is shown in typewriter font
`\ahrefurl{`url`}` | make url an hyperlink to url. |  | typeset url in typewriter font
`\ahrefloc{`label`}{`text`}` | make text an hyperlink to label inside the document |  | echo text
`\aname{`label`}{`text`}` | make text an hyperlink target with label label |  | echo text
`\mailto{`address`}` | make address a ``mailto'' link to address |  | typeset address in typewriter font
`\imgsrc[`attr`]{`url`}` | insert url as an image, attr are attributes in the HTML sense |  | do nothing
`\home{`text`}` | produce a home-dir url both for output and links, output aspect is: ``~text''

It is important to notice that all arguments are processed. For instance, to insert a link to my home page, (`http://pauillac.inria.fr/~maranget/index.html`), you should do something like this :

    \ahref{http://pauillac.inria.fr/\home{maranget}/index.html}{his home page}

Given the frequency of `~`, `#` etc. in urls, this is annoying. Moreover, the immediate solution `\ahref{\verb" ... /~maranget/..."}{his home page}` does not work, since LATEX forbids verbatim formatting inside command arguments.
Fortunately, the `url` package provides a very convenient `\url` command that acts like `\verb` and can appear in other command arguments (unfortunately, this is not the full story, see section B.17.6). Hence, provided the `url` package is loaded, a more convenient reformulation of the example above is :

    \ahref{\url{http://pauillac.inria.fr/~maranget/index.html}}{his home page}

Or even better :

    \urldef{\lucpage}{\url}{http://pauillac.inria.fr/~maranget/index.html}
    \ahref{\lucpage}{his home page}

It may seem complicated, but this is a safe way to have a document processed both by LATEX and HEVEA. Drawing a line between url typesetting and hyperlinks is correct, because users may sometime want urls to be processed and some other times not. Moreover, HEVEA (optionnaly) depends on only one third party package: `url`, which as correct as it can be and well-written.
In case the `\url` command is undefined at the time `\begin{document}` is processed, the commands `\url`, `\oneurl` and `\footurl` are defined as synonymous for `\ahref`, `\ahrefurl` and `\footahref`, thereby ensuring some compatibility with older versions of HEVEA. Note that this usage of `\url` is deprecated.

8.1.2 | HTML style colors

Specifying colors both for LATEX and HEVEA should be done using the `color` package (see section B.14.2). However,one can also specify text color using special type style declarations. The `hevea.sty` style file define no equivalent for these declarations, which therefore are for HEVEA consumption only.
Those declarations follow HTML conventions for colors. There are sixteen predefined colors:

`\black`, `\silver`, `\gray`, `\white`, `\maroon`, `\red`, `\fuchsia`, `\purple`, `\green`, `\lime`, `\olive`, `\yellow`, `\navy`, `\blue`, `\teal`, `\aqua`

Additionally, the current text color can be changed by the declaration `\htmlcolor{`number`}`, where number is a six digit hexadecimal number specifying a color in the RGB space. For instance, the following declarations change font color to dark gray:

      \htmlcolor{404040}

8.2 | More on included images

The `\imgsrc` command becomes handy when one has images both in Postscript and GIF format. As explained in section 6.3, Postscript images can be included in LATEX documents by using the `\epsfbox` command from the `epsf` package. For instance, if `screenshot.ps` is an encapsulated Postscript file, then a `doc.tex` document can include it by:

    \epsfbox{screenshot.ps}

We may very well also have a GIF version of the screenshot image (or be able to produce one easily using image converting tools), let us store it in a `screenshot.ps.gif` file. Then, for HEVEA to include a link to the GIF image in its output, it suffices to define the `\epsfbox` command in the `macro.hva` file as follows:

    \newcommand{\epsfbox}[1]{\imgsrc{#1.gif}}

Then HEVEA has to be run as:

    # hevea macros.hva doc.tex

Since it has its own definition of `\epsfbox`, HEVEA will silently include a link the GIF image and not to the Postscript image.
If another naming scheme for image files is prefered, there are alternatives. For instance, assume that Postscript files are of the kind name`.ps`, while GIF files are of the kind name`.gif`. Then, images can be included using `\includeimage{`name`}`, where `\includeimage` is a specific user-defined command:

    \newcommand{\includeimage}[1]{\ifhevea\imgsrc{#1.gif}\else\epsfbox{#1.ps}\fi}

Note that this method uses the `hevea` boolean register (see section 5.2.3). If one does not wish to load the `hevea.sty` file, one can adopt the slightly more verbose definition:

    \newcommand{\includeimage}[1]{%
    %HEVEA\imgsrc{#1.gif}%
    %BEGIN LATEX
    \epsfbox{#1.ps}
    %END LATEX
    }

When the Postscript file has been produced by translating a bitmap file, this simple method of making a GIF image and using the `\imgsrc` command is the most adequate. It should be prefered over using the more automated image file mechanism (see section 6), which will translate the image back from Postscript to bitmap format and will thus degrade it.

8.3 | The `rawhtml` environment

Any text enclosed between `\begin{rawhtml}` and `\end{rawhtml}` is echoed verbatim into the HTML output file. For avoiding to break HTML element nesting, the `rawhtml` environment should be used only at toplevel (i.e. not within another environment), and it should contain only HTML text that makes sense alone (e.g. `\begin{rawhtml}<TABLE><ALIGN=right>\end{rawhtml}`... `\begin{rawhtml}</TABLE>\end{rawhtml}` is dangerous. In that case, use the internal macros `\@open` and `\@close` of the following section instead).
When HEVEA is given the command line option ```-O`'', checking and optimization of text-level elements in the whole document takes place. As a consequence, incorrect HTML introduced by using the `rawhtml` environment may be detected at a later stage.
For the document to remain processable by LATEX, it must load the `hevea.sty` style file (see section 5.2).

8.4 | Internal macros

In this section a few of HEVEA internal macros are described. Internal macros occur at the final expansion stage of HEVEA and invoke Objective Caml code.
Normally, user source code should not use them, since their behavior may change from one version of HEVEA to another and because using them incorrectly easily crashes HEVEA. However:

- Internal macros are almost mandatory for writing supplementary base style files.
- Casual usage is a convenient (but dangerous) way to finely control output (cf. the examples in the next section).
- Knowing a little about internal macros helps in understanding how HEVEA works.

The general principle of HEVEA is that LATEX environments `\begin{`env`}`... `\end{`env`}` get translated into HTML block-level elements `<`block attributes`>`... `</`block`>`. More specifically, such block level elements are opened by the internal macro `\@open` and closed by the internal macro `\@close`. As a special case, LATEX groups `{`... `}` get translated into HTML groups, which are shadow block-level elements with neither opening tag nor closing tag.
It is important to notice that primitive arguments are processed (except for the `\@print` primitive). Thus, some characters cannot be given directly (e.g. `#` and `%` must be given as `\#` and `\%`).

`\@print{`text`}`
  Echo text verbatim.
`\@getprint{`text`}`
  Process text using a special output mode that strips off HTML tags. This macro is the one to use for processed attributes of HTML tags.
`\@hr[`attr`]{`width`}{`height`}`
  Ouput an HTML horizontal rule, attr is attributes given directly (e.g. `SIZE=3 HOSHADE`), while width and height are length arguments given in the LATEX style (e.g. `2pt` or `.5\linewidth`).
`\@open{`BLOCK`}{`attributes`}`
  Open HTML block-level element BLOCK with attributes attributes. The block name BLOCK must be uppercase. As a special case BLOCK may be the empty string, then a HTML group is opened.
`\@close{`BLOCK`}`
  Close HTML block-level element BLOCK. Note that `\@open` and `\@close` must be properly balanced.

Text-level elements are managed differently. They are not seen as blocks that must be closed explicitely and they are replaced by the internal text-level declarations `\@style`, `\@fontsize` and `\@fontcolor`. Block-level elements (and HTML groups) delimit the effect of such declarations.

`\@style{`SHAPE`}`
  Declare the text shape SHAPE (which must be uppercase) as active. Text shapes are known as font style elements (`I`, `TT`, etc.) or phrase elements (`EM`, etc.) in the HTML terminology, they are part of the more general class of text-level elements.
  The text-level element SHAPE will get opened as soon as necessary and closed automatically, when the enclosing block-level elements get closed. Enclosed block-level elements are treated properly by closing SHAPE before them, and re-opening SHAPE inside them. The next text-level constructs exhibit similar behavior with respect to block-level elements.
`\@fontsize{`int`}`
  Declare the text-level element `FONT` with attribute `SIZE=`int as active. Note that int must be a small integer in the range `1`,`2`, ... , `7`.
`\@fontcolor{`color`}`
  Declare the text-level element `FONT` with attribute `COLOR=`color as active. Note that color must be a color attribute value in the HTML style. That is either one of the sixteen conventional colors `black`, `silver` etc, or a RGB hexadecimal color specification of the form `"#`XXXXXX`"` (yes, quotes are needed). Note that the argument color is processed, as a consequence numerical color arguments should be given as `"\#`XXXXXX`"`.
`\@nostyle`
  Close active text-level declarations and ignore further text-level declarations (such as `\@style`, etc). The effect stops when the enclosing block-level element is closed.

8.5 | Examples

As a first example of using internal macros, consider the following excerpt from the `hevea.hva` file that defines the LATEX `center` environment:

    \newenvironment{center}{\@open{DIV}{ALIGN=center}}{\@close{DIV}}

Another example is the definition of the `\purple` color declaration (see section 8.1.2):

    \newcommand{\purple}{\@fontcolor{purple}}

HEVEA does not feature all text-level elements by default. However one can easily use them with the internal macro `\@style`. For instance this is how you can make all emphasized text blink:

    \renewcommand{\em}{\@style{EM}\@style{BLINK}}

Then, here is the definition of a simplified `\imgsrc` command (see section 8.1.1), without its optional argument:

    \newcommand{\imgsrc}[1]
      {\@print{<IMG SRC="}\@getprint{#1}\@print{">}}

Here, `\@print` and `\@getprint` are used to output HTML text, depending upon wether this text requires processing or not. Note that `\@open{IMG}{SRC="#1"}` is not correct, because the element `IMG` consists in a single tag, without a closing tag.
Another interesting example is the definition of the command `\@doaelement`, which HEVEA uses internaly to output `A` elements.

    \newcommand{\@doaelement}[2]
      {{\@nostyle\@print{<A }\@getprint{#1}\@print{>}}{#2}{\@nostyle\@print{</A>}}

The command `\@doaelement` takes two arguments: the first argument contains the opening tag attributes; while the second element is the textual content of the `A` element. By contrast with the `\imgsrc` exemple above, tags are emitted inside groups where styles are canceled by using the `\@nostyle` declaration. Such a complication is needed, so as to avoid breaking proper nesting of text-level elements.
Finally, here is an example of direct block opening. The `bgcolor` environment from the `color` package locally changes background color (see section B.14.2.1). This environment is defined as follows:

    \newenvironment{bgcolor}[2][CELLPADDING=10]
      {\@open{TABLE}{#1}\@open{TR}{}\@open{TD}{BGCOLOR=\@getcolor{#2}}}
      {\@close{TD}\@close{TR}\@close{TABLE}}

The `bgcolor` environment operates by opening a HTML table (`TABLE`) with only one row (`TR`) and cell (`TD`) in its opening command, and closing all these elements in its closing command. In my opinion, such a style of opening block-level elements in environment opening commands and closing them in environment closing commands is good style.
The one cell background color is forced with a `BGCOLOR` attribute. Note that the mandatory argument to `\begin{bgcolor}` is the background color expressed as a high-level color, which therefore needs to be translated into a low-level color by using the `\@getcolor` internal macro from the `color` package. Additionally, `\begin{bgcolor}` takes HTML attributes as an optional argument. These attributes are the ones of the `TABLE` element.