Previous Up Next

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.

14  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.

14.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.

14.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 LATEX 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 LATEX, 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.

14.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.8 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.

14.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 18.4 for an example of how to define (or re-define) environments.

14.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.

14.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.

14.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.

14.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 LATEX, 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 LATEX does, though SWP users will ordinarily not see this message). You can correct the appearance in either of two ways:

14.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.

14.10  Cannot open file

The warning

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

is generated when Hevea encounters a TEX 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.

14.11  \FRAME: no filename

The warning

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

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

15  Errors

There are some SWP constructs that give Hevea grief, due to the way the SWP LATEX 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.

15.1  Table inside inline math

A table (LATEX \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.

15.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 LATEX 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$}.

15.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 LATEX subscript operator) as a separator.

16  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.

16.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.9 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:

  
CounterDescription
weekdayidentifies the day-of-the-week, with Sunday = 0 (0 – 6)
day1- or 2-digit representation of the day-of-the month (1 – 31)
month1- or 2-digit representation of the month, with January = 1 (1 – 12)
year4 digits (!)
hour24-hour, 2-digit representation of the current hour (00 – 23)
Hour12-hour, 2-digit representation of the current hour (00 – 12)
minute2-digit representation of the current minute (00 – 60)
second2-digit representation of the current second (00 – 60)
timeminutes since midnight (00 – 86400)
  
CommandDescription
\ampmstring, 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?).
\timezonestring, 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.
\datethis 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.

16.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 LATEX macro, we’d say \preface{Preface}. The fact that Preface is not in braces makes the construct a TEX — not LATEX — macro, and telling Hevea to extract the next word and treat it as an argument, even though it’s not in braces, is subtle.10 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: TEX’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 TEX parsing standard — it is after all primarily a LATEX 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.

17  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.


Previous Up Next