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:
- Internal macros
are almost mandatory for writing supplementary base style files.
- Casual usage is a convenient (but dangerous) way to finely control
output (cf. the
\@nostyle
declaration below).
- Knowing a little about internal macros helps in understanding how
HEVEA works.
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.