Previous Next Contents

8  Writing HTML directly

In some rare occasions, it may be appropriate to generate HTML directly.

8.1  The rawhtml environment

Any text enclosed between \begin{rawhtml} and \end{rawhtml} is echoed verbatim into the HTML output file. Normally, no processing of any kind is performed on this text.

However, if hevea is given the -noiso command line option (see section C.1.1 some characters (such as ``é'') get translated into HTML entities (such as é).

For the document to remain processable by LATEX, it must load the hevea.sty style file (see section 5.2).

8.2  Convenience macros

A few ``high-level'' macros are provided. These are first the ``bonus'' macros, \url, \oneurl, \home and \mailto that are described in section 5.2.3. All these macros have LATEX equivalents defined in the hevea.sty style file.

The following macros can be used to output specific HTML constructs. They have no LATEX equivalents and should be seen by HEVEA only.
\imgsrc{arg}
Output <IMG SRC="arg">. The argument arg should reduce to a file name.
\anchor{arg}
Output <A NAME="arg">. The argument should reduce to some kind of label.
The \anchor command is an alternative to the \label command for inserting hyperlinks targets.

The \imgsrc command is more useful. It 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 put 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.4). 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 thus degrade it.

8.3  Internal macros

In this short section a few of HEVEA internal macros are described. Internal macros occur at the last expansion stage of HEVEA, they are interpreted by HEVEA main lexical analyzer and cannot be redefined.

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

Text-level element need not be closed, they are replaced by the internal text-level declarations \@style, \@fontsize and \@fontcolor. Block-level elements delimit the effect of such declarations.

\@print{text}
Echo text verbatim. The word ``verbatim'' means that (almost, see section 8.1) no processing of text occurs.
\@print{BLOCK}{attributes}
Open HTML block-level elements 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.

\@style{SHAPE}
Declare the 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 1,2, ... , 7.
\@fontcolor{color}
Declare the text-level element FONT with attribute COLOR=color as active. Note that color must be a color specification in the HTML style.
\@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.
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 high-level color declaration (see section B.15.1):
\newcommand{\purple}{\@fontcolor{purple}}
Finally, here is the definition of the \imgsrc command, also extracted from the hevea.hva file:
\newcommand{\imgsrc}[1]{{\@nostyle\@print{<IMG SRC="}#1\@print{">}}}
Observe how a group {... } and the text-level declaration \@nostyle are combined in order to allow the expansion of the macro-argument #1 without introducing untimely HTML tags.


Previous Next Contents