Customising HEVEA
Author: Luc Maranget

## 10 Customising 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
- Storing images in a separate directory
- Controlling imagen from document source

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

    # hevea macros.hva doc.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.

### 10.1 Simple changes

Users can easily change the rendering of some constructs. For instance, assume that all quotations in a text should be emphasised. Then, it suffices to put the following re-declaration 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 customise LATEX. However, this is less safe, since the definition of `\em` can be changed elsewhere.

There is yet another solution that takes advantage of style sheets. One can also add this line to the macros.hva file:

    \newstyle{.quote}{font-style:oblique;}

This works because the environment quote is styled through style class quote (see Section 9.2). Notice that this solution has very little to do with “emphasising” in the proper sense, since here we short-circuit the implicit path from `\em` to oblique fonts.

### 10.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 oblique italics, `\scshape` is small-caps (thanks to style sheets) 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 small caps (no italics here).

> italic shape slanted shape small caps shape upright shape

If one wishes to change the rendering of some of the shapes (say slanted caps), then one should affect the old-style `\sl` declaration. The recommended technique CSS classes. For instance, to render all slanted text in the complete document as slanted monospace font (why so?), one can add the following command in the macros.hva file:

    \newstyle{.sl}{font-family:monospace}

(See section 9.4 for the whole story on redefining old-style declarations.)

And now, the shape example above gets rendered as follows:

> italic shape slanted shape small caps shape upright shape

One sees that the monospace font change remains confined to “slanted shape”.

A deprecated alternative would be to bypass the CSS classes and to redefine the command `\sl` with `\renewcommand{\sl}{\@span{style="font-family:monospace; font-style:oblique"}}`, resulting in the same rendering:

> italic shape slanted shape small caps shape upright shape

Changing `\sl` is compatible with the cancellation mechanism, redefining `\slshape` is not. Thus, redefining directly LATEX 2є `\slshape` with `\renewcommand{\slshape}{\tt}` 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 cancellation 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.

### 10.3 Changing the interface of a command

Assume for instance that the base style of doc.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.

### 10.4 Checking the optional argument within a command

HEVEA fully implements LATEX 2є `\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}

### 10.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]{\hevaimagedir\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 PNG images stored in .png files. HEVEA provides support for the alternative GIF image file format. It suffices to invoke hevea as:

# hevea gif.hva doc.tex

Then imagen must be run with option -gif:

# imagen -gif doc

A convenient alternative is to invoke hevea as:

# hevea -fix gif.hva doc.tex

Then hevea will invoke imagen with the appropriate option when it thinks images need to be rebuild. An even more convenient alternative is to load gif.hva from within document source, for instance with the `\usepackage` command.

HEVEA also provides support for the alternative SVG image file format. As for GIF images, it is more convenient to use option -fix to combine hevea and imagen invocations:

# hevea -fix svg.hva doc.tex

Notice that imagen production chain of SVG images always call pdflatex, even when not given the -pdf command-line option. Hence the source code of images must be processable by pdflatex. This precludes using latex-only packages such as pstricks for instance.

As not all browsers display SVG images, hevea and imagen are bit special: imagen produces both PNG10 and SVG images; while hevea offers both image sources, letting client browser select the most appropriate one by the means of the `srcset` attribute of the `img` element.

### 10.6 Storing images in a separate directory

By redefining the `\heveaimagedir` command, users can specify a directory for images. More precisely, if the following redefinition occurs in the document preamble.

`\renewcommand{\heveaimagedir}{`dir`}`

Then, all links to images in the produced html file will be as “dir/…”. Then imagen must be invoked with option - todir:

# imagen -todir dir doc

As usual, hevea will invoke imagen with the appropriate option, provided it is passed the -fix option.

### 10.7 Controlling imagen from document source

The internal command `\@addimagenopt{`option`}` add the text option to imagen command-line options, when launched automatically by hevea (i.e. when hevea is given the -fix command-line option).

For instance, to instruct hevea/imagen to reduce all images by a factor of √2, it suffices to state:

%HEVEA`\@addimagenopt{-mag 707}`

See section C.1.5 for the list of command-line options accepted by imagen.

10
  or GIF, if gif.hva is loaded