Part IV
Working with Hevea

This part contains information on coping with Hevea warnings, and on a few SWP constructs that can cause Hevea to crash. It then discusses two more specialized macros (\today and \QTP) and concludes with some more personal Tips and Comments.

15 Understanding warnings

As Hevea progresses, it issues warnings when it thinks it's doing something out-of-the ordinary; and you need to understand how these arise so you can decide what to do about them. Note that you can get more information by running Hevea with the -v (for “verbose”) option. You could also try -v -v, for “extra verbose”, but my experience is that this produces so much information that it's useful only when Hevea crashes, when the last lines can provide a clue why. This section provides some tips for understanding warnings.

15.1 `Unknown macro`

The most common warning is of the form

: Warning: unknown macro: \mymacro

This is straightforward: Hevea has found the \mymacro macro in your document, and doesn't know what to do with it. You need to give it some instructions, probably in a configuration file.

15.2 `Defining a macro with \renewcommand`

The warning

: Warning: defining a macro with \renewcommand, \mymacro

means that you are trying to define a macro (here, \mymacro) using the \renewcommand construct. In L^AT_EX you use different keywords when first defining a macro (\newcommand) and when re-defining an existing macro (\renewcommand). So Hevea is telling you that when it found \renewcommand the macro \mymacro wasn't already in its dictionary. Though this is an error in L^AT_EX, it is harmless in Hevea, and can be ignored; but if it bothers you, you can find the offending definition and replace \renewcommand by \newcommand.

15.3 `Ignoring definition of \mymacro`

Consider the warning

: d:\hevea5\article.hva:28: Warning: ignoring definition of \mymacro

Note that the warning was generated in the file article.hva, a Hevea system file. Hevea reads any files you specify on the command line before system files. In this case, you have probably already defined the \mymacro macro in a non-system file, so when Hevea found a definition in one of its own files, it quite properly gives your definition precedence. In other words, this warning is harmless.

But consider a similar-looking warning

: d:\hevea5\html\swp.hva:28: Warning: ignoring definition of \mymacro

The difference here is that this is in a non-system file (swp.hva). If you think that Hevea should be processing this macro, then the warning probably means that you have tried to \def a macro which has already been defined in a previously read .hva file. Hevea semantics do not permit this. You can fix the problem in two ways.

The first (recommended by Luc Maranget) is to use a \renewcommand; but note the different forms for the two statements. For example, for the 2-parameter macro\mymacro we have

: \def\mymacro#1#2{definition}

in \def form; while the corresponding \renewcommand is

: \renewcommand{\mymacro}[2]{definition}

The second is to use the (non-standard) command \texdef, so you could write

: \texdef\mymacro#1#2{definition}

Why not use \ texdef from the start? you ask. The reason is that you want to know when you are over-riding a previously defined macro, in case it is doing things better than your proposal.⁸ Starting with \def generates a warning, so you can track down what's happening; while if you use \texdef from the start, no warning would be generated.

Similar semantics apply to \let, and there is a non-standard macro \texlet which will allow you to modify a previous \let.

15.4 `Not defining environment`

A warning like

: Warning: ignoring definition of \myenv
Warning: not defining environment myenv

is similar to the last warnings, except that the object in question is an environment, not a command. See section 19.4 for an example of how to define (or re-define) environments.

15.5 `Ignoring definition of \includegraphics`

The warning

: \graphicx.hva:18 Warning: ignoring definition of \includegraphics

arises because swp.hva defines \includegraphics (in the graphicx package) to provide support for SWP's graphics handling. Hevea's ignoring the attempt to redefine it is just what we want, and should be ignored.

15.6 `Index structure not found`

The warning

: Warning: Index structure not found, missing \makeindex

means that your document has requested an index. You need to explicitly invoke Hevea's index support, which you do by including the lines

: \usepackage{makeidx} \makeindex

into a document-specific configuration file.

15.7 `Multiple definitions for label`

The warning

: Warning: multiple definitions for label: mylabel

appears to be caused by SWP's including a \label within the scope of a sectioning command, as for example \section{Mysection \label{mylabel}}, rather than putting the \label outside the \section command. As far as I can tell, this is harmless.

15.8 `Undefined label`

The warning

: Warning: undefined label : my-label

means that Hevea has not found an .aux file for your document. The result is that in your HTML labels will be represented by ?? just as in L^AT_EX, except that they will be hyperlinks, and they will work correctly. In other words, the problem is one of appearance only. Hevea will report at the end of the run HeVeA Warning: Label(s) may have changed. Rerun to get cross-references right (just as L^AT_EX does, though SWP users will ordinarily not see this message). You can correct the appearance in either of two ways:

Run L^AT_EX again (SWP/SW only). This is the way to proceed if you want to typeset your document, since typesetting needs the information in the .aux file anyway.
Run Hevea again. Hevea will construct its own variant of the .aux file (which will have extension .haux) and references will now be correct. If your document is purely for online purposes, this may be faster than running L^AT_EX. Note that re-running Hevea isn't a substitute for re-running L^AT_EX, since L^AT_EX will not see the .haux file.

15.9 `Cannot find anchor`

The warning

: Warning: cannot find anchor ...

is generated by Hacha, and is the equivalent of (and caused by) Undefined labels in the source.

15.10 `Cannot open file`

The warning

: \htest.tex:43: Warning: Cannot open file: t

is generated when Hevea encounters a T_EX macro like \input tcilatex. The name of the file isn't parsed correctly, and Havea reports a file name consisting of just the first letter of the filename. The solution is to open the document's Preamble and replace \input tcilatex by \input{tcilatex}, ie with braces. This is completely safe, and I believe that most SWP3 (and probably SWP2.5) documents already do it this way.

15.11 `\FRAME: no filename`

The warning

: \FRAME: no filename (missing snapshot?) - using fallback name

is discussed in section 11.1. You probably forgot to generate a snapshot file for Maple graphics.

16 Errors

There are some SWP constructs that give Hevea grief, due to the way the SWP L^AT_EX filter writes output. I'll add to them as my experience increases. I've generally found that it is safe to use a text editor to fix them and continue to edit the document in SWP.

16.1 Table inside inline math

A table (L^AT_EX \tabular) inside “inline math” (i.e. $... $)generates a fatal error: *math closes : tabular. The source looks approximately like this:

$
\begin{tabular}
a & b & c \\
d & e & f
\end{tabular}
$

Solution: use a text editor to remove the dollar signs surrounding the tabular.

16.2 A decoration

The narrow decorative frame — the lower right-hand box in the Insert Decoration menu — inside inline math generates a Hevea fatal error: math closes : . The L^AT_EX source looks something like this:

$\frame{$math-stuff$}$

Note that this is \frame, not the graphics container \FRAME; and “math-stuff” is any math-mode material. This is math nested within math (two sets of $'s); the outer nesting is unnecessary.

Solution: remove the two outer math symbols, producing\frame{$math-stuff$}.

16.3 Split labels

SWP will sometimes split labels over two lines. The problem here is that Hevea takes the line-breaks as part of the label, and hence won't match later references.

Solution: move the entire label onto the next line. If the label contains a comment character (%), be sure to remove it. Note that Luc Maranget recommends against using spaces in labels: this may also help alleviate the problem. If you want multi-word labels, use - or : (but not _, which is the L^AT_EX subscript operator) as a separator.

17 Two special macros

This section contains detailed information on two special macros, one for producing dates and times (the \today macro) and a SWP Style-Editor macro (\QTP) requiring special treatment.

17.1 The `\today` macro

As of Hevea version 1.05, the \today command is implemented. In order to get the current date, Hevea runs a program xxdate.exe as a sub-process and reads in the result.⁹ All the batch files in the SWP distribution take care of this for you, so unless you want to customize the result (or provide a more detailed command) there's no need to read further.

The distribution includes a second file, xdate.exe which differs from xxdate.exe only in the way it represents your timezone (see below); you can substitute xdate.exe for xxdate.exe on the command line in any of the batch files if you prefer the alternative form.

If you run xxdate.exe from the command line you'll see that it produces more information than is used in the standard \today macro, so you have the building blocks to construct a more detailed representation. Specifically, it provides the following counters and commands:

Counter Description

weekday identifies the day-of-the-week, with Sunday = 0 (0 – 6)

day 1- or 2-digit representation of the day-of-the month (1 – 31)

month 1- or 2-digit representation of the month, with January = 1 (1 – 12)

year 4 digits (!)

hour 24-hour, 2-digit representation of the current hour (00 – 23)

Hour 12-hour, 2-digit representation of the current hour (00 – 12)

minute 2-digit representation of the current minute (00 – 60)

second 2-digit representation of the current second (00 – 60)

time minutes since midnight (00 – 86400)

Command Description

\ampm string, containing either AM or PM depending on the time (intended for use with Hour). This command is not redefined in the French support (would one say, e.g. 04:20:55 du matin in French?).

\timezone string, containing the current time-zone, or empty if the time-zone is unknown. With xdate.exe the time-zone is obtained from the TZ environment variable; if this isn't set, then the string will be empty. With xxdate.exe the information is obtained from built-in Windows functions: this is less likely to be empty, but it can happen. xxdate.exe is the default.

\date this is an approximation of the Unix date function. It produces a string something like Fri Dec 10 22:47:12 1999.

All these are available for use in configuration files when Hevea starts.

To print out the numeric value of a counter, for example the hour counter, you'd say \thehour (i.e., prepend \the to the counter name). To convert a counter to its spelled-out representation (e.g., “October” when the value of the month counter is 10, you repeatedly use the \value{counter) construct in an \ifthenelse conditional with an empty else part. See the end of latexcommon.hva for an example of this.

17.2 The `\QTP` macro

This section explains why teaching Hevea to handle this Style Editor macro is delicate. The macro will usually appear in a context like the following (taken from Manfred Szabo's book which is discussed in more detail in Part V):

\QTP{preface}
Preface

and the intent is to have the system define a new macro based on the first argument (preface, so we'd be defining the \preface macro) whose argument is to be the next word in the document (here, Preface). If we were writing this as a L^AT_EX macro, we'd say \preface{Preface}. The fact that Preface is not in braces makes the construct a T_EX — not L^AT_EX — macro, and telling Hevea to extract the next word and treat it as an argument, even though it's not in braces, is subtle.¹⁰ We need to do two things: tell Hevea to form the macro \preface from the first argument, and then tell it to look for the next word and consider that to be the argument to \preface.

Forming the macro is easy: T_EX's \csname ... \endcsname pair does exactly that, and Hevea has no problem understanding this. So swp.hva defines:

\def\QTP#1#2{\csname #1\endcsname #2}

Once this has been parsed, we will have defined the \preface macro.

The difficult part is to tell Hevea to look for the next word, and treat it as the argument to the macro we've just constructed. The problem is that Hevea does not completely conform to the T_EX parsing standard — it is after all primarily a L^AT_EX system. It turns out that the only way to get the desired effect is to break the next word into two parts: the first letter, which we will mark as #1, then everything else up to a space, which we will mark as #2. Having extracted the two parts, we can easily put them together again for processing. Suppose, then, that we want the \preface macro to generate an unnumbered Chapter heading. We define \preface as follows:

\def\preface#1#2 {\chapter*{#1#2}}

Here, the space between `#2' and the following open-brace ({) is crucial: without it, the macro will fail. In the definition itself, we're just putting the two parts together again (#1#2) and using the combined text as an argument to \chapter*. Armed with this, you should be able to handle other instances of the \QTP macro.

18 Tips and comments

Here are some ideas to help you make good use of Hevea, and notes on some decisions represented in swp.hva, the main SWP support file.

The proof environment is defined in the Preamble of SWP3 documents. The second argument of the definition is \rule{0.5em}{0.5em}. In L^AT_EX this produces a black square, the Halmos end-of-proof symbol. But Hevea translates any \rule into an HTML horizontal rule (<HR>) element, and this will result in a line after your proof, rather than a square. You can get closer to L^AT_EX by putting the following into a personal configuration file:
\renewenvironment{proof}[1][Proof]{\textbf{#1.} }{\ \UNICODE{0x25A0}}

If you're not sure your readers will have Unicode fonts you could change the \UNICODE{0x25A0} to \@symb{\char168} (which will give a dot), or even omit it entirely.
Hevea renders the macros \TeX and \LaTeX using super- and subscripts in HTML. If you'd rather not do this — it is a bit obtrusive — you can put into a configuration file
\texdef\TeX{TeX} and \texdef\LaTeX{LaTeX}
By default, Hevea produces black text on a silver background. If you'd prefer a white background, include the file white.hva in your command line or \input it in a document-specific (.hvb) configuration file. As of version 1.05 there's also a package called fancysection which produces attractive headings — green background, in progressively lighter shades as you go down the sectional hierarchy — and text is on white background. You can include a reference to fancysection.hva on your command line, or include it (via \input) in a document-specific configuration file.
SWP 3's hyperref construct. Check the definitions in swp.hva (\html and \text versions differ): you may want to change them. Remember that path separators must be / and not \. The simplest way to get the # and ~characters into a “target” is to type the text on-screen, copy it to the clipboard and paste it in. Otherwise, remember that # is \symbol{35} and ~is \symbol{126}, and both must be entered that way.

As distributed, the hyperref support is not entirely compatible with the way the HyperLink dialog is used in SWP. SWP allows you to enter a target, eg myloc, which will be interpreted as a link to the location (reference) myloc in the current document. Hevea treats this as a reference to the external document myloc, and generate the appropriate link. Similarly, a HyperLink target of myloc.tex will be interpreted by SWP as an instruction to open this document. Hevea will generate a link to myloc.tex also (rather than the obvious analog, myloc,html). This may change in future versions of the support; but for now you need to be aware of what happens.
In the article class, Sections become second-level (H2) hypertext headings, and so on down. If you'd prefer Sections to be level-1 (H1) headings (and so on down), include the file promote.hva in your command line, or \input it in a document-specific (.hvb) configuration file.
The Blackboard Bold fonts are supported in swp.hva by rendering them as sans-serif characters, but in red, to distinguish them from other sans-serif text. You may want to change this.
Inline generalized fractions and binomials — these are items on the Insert-> Binomial menu — are not handled well. The obvious strategy is to build them via a table (this is what happens to the displayed variants), but this isn't possible here, since inline tables are not supported in HTML. swp.hva renders an inline binomial something like (ⁿ _k) — note that the n and the k aren't lined up vertically — and a generalized fraction as (ⁿ/ _k). If anyone has a better solution, I'd like to hear about it.
The External Program Call facility (macro) is processed by swp.hva but ignored, ie generates nothing in your HTML. You may want to change this.
For working with single-character macros, the Windows Character Map can be useful. But remember
- if the character ID (bottom-right of the window) says, eg, “Unicode: 169”, then you must use the \U macro, or call \UNICODE with the number preceeded by 0x : the “169” here is a hexadecimal number.
- if the ID says, eg, “Keystroke: Alt+169”, this “169” is a decimal (not hex) number, and you must use the \charnnnn macro.
- if the ID says, eg, “Keystroke: n” you will need to look up the corresponding number in an ASCII table. Typically these give values in decimal, so use \char.
See section 12 for additional information on using Unicode.
Hevea doesn't seem to handle the \mathrm macro (for upright text inside mathematics; the Roman text tag in SWP) properly. A work-around — which is not implemented in swp.hva — is to say \renewcommand{\mathrm}{\textrm} inside an .hvb file. This may have side-effects which I've not seen; but so far it seems to work.
There's a minor appearance problem when doing text translations of some math. SWP writes β _i as \beta _i (with a space after the “beta”); this is OK for L^AT_EX which will ignore the space; but Hevea's text translator will include it. I don't see any way around this.

Part IV Working with Hevea

15 Understanding warnings

15.1 Unknown macro

15.2 Defining a macro with \renewcommand

15.3 Ignoring definition of \mymacro

15.4 Not defining environment

15.5 Ignoring definition of \includegraphics

15.6 Index structure not found

15.7 Multiple definitions for label

15.8 Undefined label

15.9 Cannot find anchor

15.10 Cannot open file

15.11 \FRAME: no filename

16 Errors

16.1 Table inside inline math

16.2 A decoration

16.3 Split labels

17 Two special macros

17.1 The \today macro

17.2 The \QTP macro

18 Tips and comments

Part IV
Working with Hevea

15.1 `Unknown macro`

15.2 `Defining a macro with \renewcommand`

15.3 `Ignoring definition of \mymacro`

15.4 `Not defining environment`

15.5 `Ignoring definition of \includegraphics`

15.6 `Index structure not found`

15.7 `Multiple definitions for label`

15.8 `Undefined label`

15.9 `Cannot find anchor`

15.10 `Cannot open file`

15.11 `\FRAME: no filename`

17.1 The `\today` macro

17.2 The `\QTP` macro