Customizing HEVEA
Author: Luc Maranget

9 | Customizing HEVEA

- Simple changes
- Changing defaults for type-styles
- Changing the interface of a command
- Checking the optional argument within a command
- Changing the Format of Images

HEVEA can be controlled by writing LATEX code. In this section, we examine how users can change HEVEA default behavior or add functionalities. In all this section we assume that a document `mydoc.tex` is processed, using a private command file `macros.hva`. That is, HEVEA is invoked as:

    # hevea macros.hva mydoc.tex

The general idea is as follows: one redefines LATEX constructs in `macros.hva`, using internal commands. This requires a good working knowledge of both LATEX and HTML. Usually, one can avoid internal commands, but then, all command redefinitions interact, sometimes in very nasty ways.

9.1 | Simple changes

Users can easily change the rendering of some constructs. For instance, assume that all quotations in a text should be emphasized. Then, it suffices to put the following redeclaration in `macros.hva`:

    \renewenvironment{quote}
      {\@open{BLOCKQUOTE}{}\@style{EM}}
      {\@close{BLOCKQUOTE}}

The same effect can be achieved without using any of the internal commands:

    \let\oldquote\quote
    \let\oldendquote\endquote
    \renewenvironment{quote}{\oldquote\em}{\oldendquote}

In some sense, this second solution is easier, when one already knows how to customize LATEX. However, this is less safe, since the definition of `\em` can be changed elsewhere.

9.2 | Changing defaults for type-styles

HEVEA default rendering of type style changes is described in section B.15.1. For instance, the following example shows the default rendering for the font shapes:

    \itshape italic shape \slshape slanted shape
    \scshape small caps shape \upshape upright shape

By default, `\itshape` is italics, `\slshape` is maroon italics, `\scshape` is navy blue color and `\upshape` is no style at all. All shapes are mutually exclusive, this means that each shape declaration cancels the effect of other active shape declarations. For instance, in the example, small caps shapes is navy blue and not navy blue italics.

> italic shape slanted shape small caps shape upright shape

If one wishes to change the rendering of some of the shapes (say small caps), then one should redefine the old-style `\sc` declaration. For instance, to render small caps as bold fonts, one should redefine `\sc` by `\renewcommand{\sc}{\@style{B}}` in `macros.hva`.
And now, the shape example above gets rendered as follows:

> italic shape slanted shape small caps shape upright shape

Redefining the old-style `\sc` is compatible with the cancelation mechanism, redefining `\scshape` is not. Thus, redefining directly LATEX 2e `\scshape` with `\renewcommand{\scshape}{\@style{B}}` would yield:

> italic shape slanted shape small caps shape upright shape

Hence, redefining old-style declarations using internal commands should yield satisfactory output. However, since cancelation is done at the HTML level, a declaration belonging to one component may sometimes cancel the effect of another that belongs to another component. Anyway, you might have not noticed it if I had not told you.

9.3 | Changing the interface of a command

Assume for instance that the base style of `mydoc.tex` is jsc (the Journal of Symbolic Computation style for articles). For running HEVEA, the jsc style can be replaced by article style, but for a few commands whose calling interface is changed. In particular, the `\title` command takes an extra optional argument (which HEVEA should ignore anyway). However, HEVEA can process the document as it stands. One solution to insert the following lines into `macros.hva`:

    \input{article.hva}% Force document class ``article''
    \let\oldtitle=\title
    \renewcommand{\title}[2][]{\oldtitle{#2}}

The effect is to replace `\title` by a new command which calls HEVEA `\title` with the appropriate argument.

9.4 | Checking the optional argument within a command

HEVEA fully implements LATEX 2e `\newcommand`. That is, users can define commands with an optional argument. Such a feature permits to write a `\epsfbox` command that has the same interface as the LATEX command and echoes itself as it is invoked to the image file. To do this, the HEVEA `\epsfbox` command has to check whether it is invoked with an optional argument or not. This can be achieved as follows :

    \newcommand{\epsfbox}[2][!*!]{%
    \ifthenelse{\equal{#1}{!*!}}
    {\begin{toimage}\epsfbox{#2}\end{toimage}}%No optional argument
    {\begin{toimage}\epsfbox[#1]{#2}\end{toimage}}}%With optional argument
    \imageflush}

9.5 | Changing the Format of Images

Semi-automatic generation of included images is described in section 6.
Links to included images are generated by the `\imageflush` command, which calls the `\imgsrc` command :

    \newcommand{\imageflush}[1][]
    {\@imageflush\stepcounter{image}\imgsrc[#1]{\jobname\theimage\heveaimageext}}

That is, you may supply a HTML-style attribute to the included image, as an optional argument to the `\imageflush` command.
By default, images are GIF images, stored in ```.gif`'' files. HEVEA provides direct support for the alternative PNG image file format. It suffices to invoke `hevea` as:
`# hevea png.hva` mydoc.tex
Then imagen must be run as:
`# imagen -png` mydoc
Beware that transparent colors are not shown correctly by my browser for PNG images, while they work as advertised for GIF images. This does not harm as long as the final HTML document has a white background color (see Section B.2).