<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.32">
<meta name="Author" content="Luc Maranget">
<script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML"></script><link rel="stylesheet" type="text/css" href="manual.css">
<title>Generating html constructs</title>
</head>
<body>
<a href="cutname.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="manual019.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h2 class="section" id="sec64">8  Generating html constructs</h2>
<ul>
<li><a href="manual018.html#sec65">High-Level Commands</a>
</li><li><a href="manual018.html#imgsrc">More on included images</a>
</li><li><a href="manual018.html#internal">Internal macros</a>
</li><li><a href="manual018.html#rawhtml">The <span class="c013">rawhtml</span> environment</a>
</li><li><a href="manual018.html#sec72">Examples</a>
</li><li><a href="manual018.html#encodings">The document charset</a>
</li></ul>
<p>
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A output language being html, it is normal for users to insert
hypertext constructs their documents, or to control colours.</p>
<h3 class="subsection" id="sec65">8.1  High-Level Commands</h3>
<p>
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A provides high-level commands for generating
hypertext constructs.
Users are advised to use these commands in the first place,
because it is easy to write incorrect html and that writing
html directly may interfere in nasty ways with H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A internals.</p>
<h4 class="subsubsection" id="hyperlink">8.1.1  Commands for Hyperlinks</h4>
<p><a id="hevea_default58"></a>
A few commands for hyperlink management and included images
are provided, all these
commands have appropriate equivalents defined by the <span class="c013">hevea</span>
package (see section <a href="manual007.html#heveastyle">5.2</a>).
Hence, a document that relies on these high-level commands
still can be typeset by L<sup>A</sup>T<sub>E</sub>X, provided it loads the <span class="c013">hevea</span>
package.</p><p><a id="hevea_default59"></a><a id="hevea_default60"></a><a id="hevea_default61"></a><a id="hevea_default62"></a><a id="hevea_default63"></a><a id="hevea_default64"></a><a id="hevea_default65"></a><a id="hevea_default66"></a></p><table class="c002 cellpading0"><tr><td class="c030">Macro</td><td class="c030" colspan=2>H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A</td><td class="c030">L<sup>A</sup>T<sub>E</sub>X</td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c042">
<code>\ahref{</code><span class="c019">url</span><code>}{</code><span class="c019">text</span><code>}</code>    </td><td class="c040">make <span class="c019">text</span> an hyperlink to <span class="c019">url</span></td><td class="c030">    </td><td class="c040">echo <span class="c019">text</span></td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c042">
<code>\footahref{</code><span class="c019">url</span><code>}{</code><span class="c019">text</span><code>}</code>    </td><td class="c040">make <span class="c019">text</span> an hyperlink to <span class="c019">url</span></td><td class="c030">    </td><td class="c040">make <span class="c019">url</span> a footnote to <span class="c019">text</span>,
<span class="c019">url</span> is shown in typewriter font</td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c042">
<code>\ahrefurl{</code><span class="c019">url</span><code>}</code>    </td><td class="c040">make <span class="c019">url</span> an hyperlink to <span class="c019">url</span>.</td><td class="c030">    </td><td class="c040">typeset <span class="c019">url</span> in typewriter font</td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c042">
<code>\ahrefloc{</code><span class="c019">label</span><code>}{</code><span class="c019">text</span><code>}</code>    </td><td class="c040">make <span class="c019">text</span> an hyperlink to <span class="c019">label</span> inside the document</td><td class="c030">    </td><td class="c040">echo <span class="c019">text</span></td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c042">
<code>\aname{</code><span class="c019">label</span><code>}{</code><span class="c019">text</span><code>}</code>    </td><td class="c040">make <span class="c019">text</span> an hyperlink target with label <span class="c019">label</span></td><td class="c030">    </td><td class="c040">echo <span class="c019">text</span></td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c042">
<code>\mailto{</code><span class="c019">address</span><code>}</code>    </td><td class="c040">make <span class="c019">address</span> a “mailto” link to <span class="c019">address</span></td><td class="c030">    </td><td class="c040">typeset <span class="c019">address</span> in typewriter font
</td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c042"><code>\imgsrc[</code><span class="c019">attr</span><code>]{</code><span class="c019">url</span><code>}</code>    </td><td class="c040">insert <span class="c019">url</span> as an image, <span class="c019">attr</span> are attributes in the
html sense</td><td class="c030">    </td><td class="c040">do nothing </td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c042"><code>\home{</code><span class="c019">text</span><code>}</code>    </td><td class="c040" colspan=3>produce a home-dir url both for output and links, output aspect is: “~<span class="c019">text</span>”
</td></tr>
</table><p><a id="urlareprocessed"></a>It is important to notice that all arguments
are processed.
For instance, to insert a link to
my home page, (<code>http://pauillac.inria.fr/~maranget/index.html</code>),
you should do something like this:
</p><pre class="verbatim">\ahref{http://pauillac.inria.fr/\home{maranget}/index.html}{his home page}
</pre><p>Given the frequency of <code>~</code>, <code>#</code> etc. in urls,
this is annoying. Moreover, the immediate solution, using <code>\verb</code>,
<code>\ahref{\verb" ... /~maranget/..."}{his home page}</code>
does not work, since L<sup>A</sup>T<sub>E</sub>X forbids verbatim formatting
inside command arguments.</p><p><a id="hevea_default67"></a>
Fortunately, the <span class="c013">url</span> package provides a very convenient
<code>\url</code> command that acts like <code>\verb</code> and can appear in
other command arguments
(unfortunately, this is not the full story, see section <a href="manual-packages.html#urlpackage">B.17.11</a>).
Hence, provided the <span class="c013">url</span> package is loaded,
a more convenient reformulation of the example above is:
</p><pre class="verbatim">\ahref{\url{http://pauillac.inria.fr/~maranget/index.html}}{his home page}
</pre><p>
Or even better:
</p><pre class="verbatim">\urldef{\lucpage}{\url}{http://pauillac.inria.fr/~maranget/index.html}
\ahref{\lucpage}{his home page}
</pre><p>
It may seem complicated, but this is a safe way to have a
document processed both by L<sup>A</sup>T<sub>E</sub>X and H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A.
Drawing a line between url typesetting and hyperlinks is correct,
because users may sometime want urls to be processed and some other
times not.
Moreover, H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A (optionally) depends on only one third party package:
<span class="c013">url</span>, which is as correct as it can be and well-written.</p><p><a id="hevea_default68"></a>
<a id="hevea_default69"></a>
In case the <code>\url</code> command is undefined
at the time <code>\begin{document}</code> is processed, the commands
<code>\url</code>, <code>\oneurl</code> and <code>\footurl</code> are defined as
synonymous for
<code>\ahref</code>, <code>\ahrefurl</code> and <code>\footahref</code>, thereby
ensuring
some compatibility with older versions of H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A.
Note that this usage of <code>\url</code> is deprecated.</p>
<h4 class="subsubsection" id="sec67">8.1.2  html style colours</h4>
<p><a id="color:high"></a>
Specifying colours both for L<sup>A</sup>T<sub>E</sub>X and
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A should be done using the <span class="c013">color</span> package (see
section <a href="manual036.html#color%3Apackage">B.14.2</a>).
However,one can also specify text color using special type style declarations.
The <span class="c013">hevea.sty</span> style file
define no equivalent for these declarations, which therefore are for
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A consumption only.</p><p>Those declarations follow html conventions for colours.
There are sixteen predefined colours:
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c040"><span style="color:black"><code>\black</code>,
</span><span style="color:silver"><code>\silver</code>,
</span><span style="color:gray"><code>\gray</code>,
</span><span style="color:white"><code>\white</code>,
</span><span class="c009"><code>\maroon</code>,
</span><span style="color:red"><code>\red</code>,
</span><span class="c008"><code>\fuchsia</code>,
</span><span class="c010"><code>\purple</code>,
</span><span style="color:green"><code>\green</code>,
</span><span style="color:lime"><code>\lime</code>,
</span><span style="color:olive"><code>\olive</code>,
</span><span class="c011"><code>\yellow</code>,
</span><span style="color:navy"><code>\navy</code>,
</span><span style="color:blue"><code>\blue</code>,
</span><span style="color:teal"><code>\teal</code>,
</span><span style="color:aqua"><code>\aqua</code></span>
</td></tr>
</table>
</div><p>
<a id="hevea_default70"></a>Additionally, the current text color can be
changed by the declaration <code>\htmlcolor{</code><span class="c019">number</span><code>}</code>,
where <span class="c019">number</span> is a six digit hexadecimal number specifying a
color in the RGB space. For instance, the declaration
<span style="color:#404040"><code>\htmlcolor{404040}</code></span>
changes font color to dark gray,</p>
<h3 class="subsection" id="imgsrc">8.2  More on included images</h3>
<p>
<a id="hevea_default71"></a><a id="hevea_default72"></a>
The <code>\imgsrc</code> command becomes handy when one has images both in
Postscript and GIF (or PNG or JPG) format. As explained in
section <a href="manual008.html#substimage">6.3</a>, Postscript images can be included in
L<sup>A</sup>T<sub>E</sub>X documents by using the <code>\epsfbox</code> command from the
<span class="c013">epsf</span> package. For instance, if <span class="c013">screenshot.ps</span> is an
encapsulated Postscript file, then a <span class="c013">doc.tex</span> document can
include it by:
</p><pre class="verbatim">\epsfbox{screenshot.ps}
</pre><p>
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 store it in a <span class="c013">screenshot.ps.gif</span> file.
Then, for H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A to include a link to the GIF image in its
output, it suffices
to define the <code>\epsfbox</code> command in the <span class="c013">macro.hva</span> file
as follows:
</p><pre class="verbatim">\newcommand{\epsfbox}[1]{\imgsrc{#1.gif}}
</pre><p>
Then H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A has to be run as:
</p><pre class="verbatim"># hevea macros.hva doc.tex
</pre><p>
Since it has its own definition of <code>\epsfbox</code>, H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A will
silently include a link the GIF image and not to the Postscript image.</p><p>If another naming scheme for image files is preferred, there are
alternatives.
For instance, assume that Postscript files are of the kind
<span class="c019">name</span><span class="c013">.ps</span>, while GIF files are of the kind
<span class="c019">name</span><span class="c013">.gif</span>.
Then, images can be included using
<code>\includeimage{</code><span class="c019">name</span><code>}</code>, where
<code>\includeimage</code> is a specific user-defined command:
</p><pre class="verbatim">\newcommand{\includeimage}[1]{\ifhevea\imgsrc{#1.gif}\else\epsfbox{#1.ps}\fi}
</pre><p>
Note that this method uses the <span class="c013">hevea</span> boolean register (see
section <a href="manual007.html#heveabool">5.2.3</a>).
If one does not wish to load the <span class="c013">hevea.sty</span> file,
one can adopt the slightly more verbose definition:
</p><pre class="verbatim">\newcommand{\includeimage}[1]{%
%HEVEA\imgsrc{#1.gif}%
%BEGIN LATEX
\epsfbox{#1.ps}
%END LATEX
}
</pre><p>
When the Postscript file has been produced by
translating a bitmap file, this simple method of making a bitmap image and
using the <code>\imgsrc</code> command
is the most adequate.
It should be preferred over using the more automated <span class="c019">image</span> file
mechanism (see section <a href="manual008.html#imagen">6</a>),
which will translate the image back from
Postscript to bitmap format and will thus degrade it.</p>
<h3 class="subsection" id="internal">8.3  Internal macros</h3>
<p>
In this section a few of H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A internal macros are
described.
Internal macros occur at the final expansion stage of H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A and
invoke Objective Caml code.</p><p>Normally, user source code should not use them, since
their behaviour may change from one version of H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A to another and
because using them incorrectly easily
crashes H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A.
However:
</p><ul class="itemize"><li class="li-itemize">
Internal macros
are almost mandatory for writing supplementary base style files.
</li><li class="li-itemize">Casual usage is a convenient (but dangerous) way to finely control
output (cf. the examples in the next section).
</li><li class="li-itemize">Knowing a little about internal macros helps in understanding how
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A works.
</li></ul><p><a id="hevea_default73"></a>
The general principle of H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A is that L<sup>A</sup>T<sub>E</sub>X environments
<code>\begin{</code><span class="c019">env</span><code>}</code>…
<code>\end{</code><span class="c019">env</span><code>}</code> get
translated into html block-level elements <code><</code><span class="c019">block
attributes</span><code>></code>… <code></</code><span class="c019">block</span><code>></code>.
More specifically, such block level elements are opened by the
internal macro <code>\@open</code> and closed by the internal macro
<code>\@close</code>.
As a special case, L<sup>A</sup>T<sub>E</sub>X groups <code>{</code>… <code>}</code>
get translated into html <em>groups</em>, which are shadow block-level
elements with neither opening nor closing tag.</p><p>In the following few paragraphs, we sketch the interaction of
<code>\@open</code>…<code>\@close</code> with paragraphs.
Doing so, we intend to warn users about the complexity
of the task of producing correct html, and to encourage
them to use internal macros, which, most of the time, take nasty
details into account.</p><p>Paragraphs are rendered by <code>p</code> elements, which are opened and
closed automatically.
More specifically, a first <code>p</code> is opened after
<code>\begin{document}</code>, then paragraph breaks close the active
<code>p</code> and open a new one.
The final <code>\end{document}</code> closes the last <code>p</code>.
In any occasion, paragraphs consisting only of space characters
are discarded silently.</p><p>Following html “normative reference [<a href="manual047.html#html">HTML-5a</a>]”, block-level
elements cannot occur inside <code>p</code>; more precisely,
block-level opening tags implicitly close any active <code>p</code>.
As a consequence,
H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A closes the active <code>p</code> element when it processes
<code>\@open</code>
and opens a new <code>p</code> when it processes the matching
<code>\@close</code>.
Generally, no <code>p</code> element is opened by default inside block-level
elements, that is, H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A does not immediately open <code>p</code> after having
processed <code>\@open</code>.
However, if a paragraph break occurs later, then a new <code>p</code>
element is opened, and will be closed automatically
when the current block is closed.
Thus, the first “paragraph” inside block-level elements
that include several paragraphs is not a <code>p</code> element.
That alone probably prevents the consistent styling
of paragraphs with style sheets.</p><p>Groups behave differently, opening or closing them does
not close nor open <code>p</code> elements.
However, processing paragraph breaks inside groups involves temporarily
closing all groups up to the nearest enclosing <code>p</code>, closing it,
opening a new <code>p</code> and finally re-opening all groups.
Opening a block-level element inside a group, similarly
involves closing the active <code>p</code> and opening a new <code>p</code>
when the matching <code>\@close</code> is processed.</p><p>Finally, display mode (as introduced by <code>$$</code>) is also
complicated. Displays basically are <code>table</code> elements with one row
(<code>tr</code>), and H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A manages to introduce table cells (<code>td</code>)
where appropriate. Processing <code>\@open</code> inside a display
means closing the current cell, starting a new cell, opening the
specified block, and then immediately opening a new display.
Processing the matching <code>\@close</code> closes the internal
display, then the specified block, then the cell and finally opens a
new cell. In many occasions (in particular for groups), either cell
break or the internal display may get cancelled.</p><p><a id="hevea_default74"></a>
<a id="hevea_default75"></a>
<a id="hevea_default76"></a>
<a id="hevea_default77"></a>
<a id="hevea_default78"></a>
<a id="hevea_default79"></a>
<a id="hevea_default80"></a>
<a id="hevea_default81"></a>
<a id="hevea_default82"></a>
<a id="hevea_default83"></a>
<a id="hevea_default84"></a>
<a id="hevea_default85"></a>
<a id="hevea_default86"></a>
It is important to notice that primitive arguments <em>are</em>
processed (except for the <code>\@print</code> primitive, and for some of
the basic style primitives). Thus,
some characters cannot be given directly (e.g. <code>#</code> and
<code>%</code> must be given as <code>\#</code> and <code>\%</code>).
</p><dl class="description"><dt class="dt-description">
<span class="c023"><span class="c013">\@print{</span><span class="c019">text</span><span class="c013">}</span></span></dt><dd class="dd-description">
Echo <span class="c019">text</span> verbatim. As a consequence use only ascii
in <span class="c019">text</span>.
</dd><dt class="dt-description"><span class="c023"><span class="c013">\@getprint{</span><span class="c019">text</span><span class="c013">}</span></span></dt><dd class="dd-description">
Process <span class="c019">text</span> using a special output mode that strips off
html tags. This macro is the one to use for processed attributes of
html tags.
</dd><dt class="dt-description"><span class="c023"><span class="c013">\@hr[</span><span class="c019">attr</span><span class="c013">]{</span><span class="c019">width</span><span class="c013">}{</span><span class="c019">height</span><span class="c013">}</span></span></dt><dd class="dd-description">
Output an html horizontal rule, <span class="c019">attr</span> is attributes given
directly (e.g. <code>SIZE=3 HOSHADE</code>), while <span class="c019">width</span> and
<span class="c019">height</span> are length arguments given in the L<sup>A</sup>T<sub>E</sub>X style
(e.g. <code>2pt</code> or <code>.5\linewidth</code>).
</dd><dt class="dt-description"><span class="c023"><span class="c013">\@print@u{</span><span class="c019">n</span><span class="c013">}</span></span></dt><dd class="dd-description">
Output the (Unicode) character “<span class="c019">n</span>”, which can
be given either as a decimal number or an hexadecimal number prefixed
by “<span class="c013">X</span>”.</dd><dt class="dt-description"><span class="c023"><span class="c013">\@open{</span><span class="c019">block</span><span class="c013">}{</span><span class="c019">attributes</span><span class="c013">}</span></span></dt><dd class="dd-description">
Open html block-level element <span class="c019">block</span> with attributes
<span class="c019">attributes</span>. The block name <span class="c019">block</span> <span class="c023">must</span> be
lowercase.
As a special case <span class="c019">block</span> may be the empty string, then a html
<em>group</em> is opened.
</dd><dt class="dt-description"><span class="c023"><span class="c013">\@close{</span><span class="c019">block</span><span class="c013">}</span></span></dt><dd class="dd-description">
Close html block-level element <span class="c019">block</span>.
Note that <code>\@open</code> and <code>\@close</code> must be properly balanced.
</dd><dt class="dt-description"><span class="c023"><span class="c013">\@out@par{</span><span class="c019">arg</span><span class="c013">}</span></span></dt><dd class="dd-description">
If occurring inside a <code>p</code> element,
that is if a <code><p></code> opening tag is active,
<code>\@out@par</code> first closes it (by emitting <code></p></code>),
then formats <span class="c019">arg</span>, and then re-open a <code>p</code> element.
Otherwise <code>\@out@par</code> simply formats <span class="c019">arg</span>.
This command is adequate when
formatting <span class="c019">arg</span> produces block-level elements.
</dd></dl><p><a id="hevea_default87"></a>
Text-level elements are managed differently. They are not seen
as blocks that must be closed explicitly.
Instead they follow a “declaration” style, similar
to the one of L<sup>A</sup>T<sub>E</sub>X “text-style declarations” — namely,
<code>\itshape</code>, <code>\em</code> etc.
Block-level elements (and html groups)
delimit the effect of such declarations.
</p><dl class="description"><dt class="dt-description">
<span class="c023"><span class="c013">\@span{</span><span class="c019">attr</span><span class="c013">}</span></span></dt><dd class="dd-description">
<a id="hevea_default88"></a>
Declare the text-level element <code>span</code> (with given attributes)
as active.
The text-level element <code>span</code> 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 <code>span</code>
before them, and re-opening <code>span</code> (with given attributes)
inside them.
The following text-level constructs exhibit similar behaviour with respect
to block-level elements.</dd><dt class="dt-description"><span class="c023"><span class="c013">\@style{</span><span class="c019">shape</span><span class="c013">}</span></span></dt><dd class="dd-description"> Declare the
text shape <span class="c019">shape</span> (which must be lowercase) as active. Text
shapes are known as font style elements (<code>i</code>, <code>tt</code>, etc.;
<span class="c023">warning</span>:most of font style elements are depreciated in html5,
and some of them are no longer valid, prefer CSS in <code>span</code> tags)
or phrase elements (<code>em</code>, etc.) in the html terminology.</dd><dt class="dt-description"><span class="c023"><span class="c013">\@styleattr{</span><span class="c019">name</span><span class="c013">}{</span><span class="c019">attr</span><span class="c013">}</span></span></dt><dd class="dd-description">
This command generalises both <code>\@span</code> and <code>\@style</code>,
as both a text-level element name <span class="c019">name</span> and attributes are specified.
More specifically,
<code>\@span{</code><span class="c019">attr</span><code>}</code> can be seen as a shorthand for
<code>\@styleattr{span}{</code><span class="c019">attr</span><code>}</code>;
while
<code>\@style{</code><span class="c019">name</span><code>}</code> can be seen as
a shorthand for
<code>\@styleattr{</code><span class="c019">name</span><code>}{}</code>.</dd><dt class="dt-description"><span class="c023"><span class="c013">\@fontsize{</span><span class="c019">int</span><span class="c013">}</span></span></dt><dd class="dd-description"> Declare
the text-level element <code>span</code> with attribute
<code>style="font-size:</code><span class="c019">font-size</span><code>"</code> as active.
The argument
<span class="c019">int</span> must be a small integer in the range
<span class="c013">1</span>,<span class="c013">2</span>, … , <span class="c013">7</span>.
<span class="c013">hevea</span> computes <span class="c019">font-size</span>, a CSS fontsize value,
from <span class="c019">int</span>.
More specifically, <span class="c019">font-size</span> will
range from <code>x-small</code> to <code>120%</code> included in
a <code>xx-large</code>, 3 being the default size <code>medium</code>.
Notice that <code>\@fontsize</code> is deprecated in favour of
<code>\@span</code> with proper fontsize declarations:
<code>\@span{style="font-size=xx-small"}</code>,
<code>\@span{style="font-size=x-small"}</code>,
<code>\@span{style="font-size=small"}</code>,
etc.</dd><dt class="dt-description"><span class="c023"><span class="c013">\@fontcolor{</span><span class="c019">color</span><span class="c013">}</span></span></dt><dd class="dd-description">
Declare the text-level element <code>span</code> with attribute
<code>"style=</code><span class="c019">color</span><code>"</code> as active.
The argument <span class="c019">color</span> must be a color attribute value in the html
style. That is either one of the sixteen conventional colours
<code>black</code>, <code>silver</code> etc, or a RGB hexadecimal color specification
of the form
<code>#</code><span class="c019">XXXXXX</span>.
Note that the argument <span class="c019">color</span> is processed, as a consequence
numerical color arguments should be given as <code>\#</code><span class="c019">XXXXXX</span>.</dd><dt class="dt-description"><span class="c014">\@nostyle</span></dt><dd class="dd-description">
Close active text-level declarations and ignore further text-level
declarations.
The effect stops when the enclosing block-level element is closed.
</dd><dt class="dt-description"><span class="c014">\@clearstyle</span></dt><dd class="dd-description">
Simply close active text-level declarations.
</dd></dl><h4 class="subsubsection" id="sec70">Notice on font styling with CSS</h4>
<p>The preferred way to style text in new versions of the html “standard”
is using style-sheet specifications. Those can be given as argument to
a “<span class="c013">style</span>” attributes of html elements, most noticeably
of the <span class="c013">span</span> elements.
For instance, to get italics in old versions of html one used
the text-level “<span class="c013">i</span>” element as in
<code><i></code>…<code></i></code>. Now, for the same results of getting
italics one may write:
<code><span style="font-style:italic"></code>…<code></span></code>.
An indeed <span class="c013">hevea</span> styles text in that manner,
starting from version 2.00.
Such (verbose) declarations are then abstracted into style class declarations
by H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A optimiser <span class="c013">esponja</span>, which is invoked by <span class="c013">hevea</span>
when given option “<span class="c013">-O</span>”.</p><p>Notice that style attributes can be given to elements other than <span class="c013">span</span>.
However, combining style attributes requires a little care as only one style
attribute is allowed.
Namely <code><cite style="font-weight:bold" style="color:red"></code>
is illegal and should be written
<code><cite style="font-weight:bold;color:red"></code>.
For instance:
<cite class="c025">Das Kapital</cite>.
</p><p><a id="hevea_default89"></a>
The command <code>\@addtyle</code> can be handy for adding style to
already style elements:
</p><dl class="description"><dt class="dt-description">
<span class="c023"><span class="c013">\@addstyle{</span><span class="c019">name:val</span><span class="c013">}{</span><span class="c019">attrs</span><span class="c013">}</span></span></dt><dd class="dd-description">
Echo the space-separated attributes <span class="c019">attrs</span> of a tag with the
<span class="c019">name:val</span> style declaration added to these attributes. The
<code>style</code> attribute is added if necessary. Examples:
<code>\@addstyle{color:red}{href="#"}</code> will produce
<code>href="#" style="color:red"</code>, and
<code>\@addstyle{color:red}{href="#" style="font-style:italic"}</code> will
produce <code>href="#" style="font-style:italic;color:red"</code>. Note
that an unnecessary extra space can be added in some cases.
</dd></dl><p>
As an example, consider the following definition of a command
for typesetting citation in bold, written directly in html:
</p><pre class="verbatim">\newcommand{\styledcite}[2][]
{{\@styleattr{cite}{\@addstyle{#1}{style="font-weight:bold"}}#2}}
</pre><p>
The purpose of the optional argument is to add style to specific citations,
as in:
</p><pre class="verbatim">Two fundamental works: \styledcite{The Holy Bible} and
\styledcite[color:red]{Das Kapital}.
</pre><p>
We get: Two fundamental works: <cite style="font-weight:bold;">The Holy Bible</cite> and
<cite class="c025">Das Kapital</cite>.</p><p>Notice that the example is given for illustrating the usage of the
<code>\@addstyle</code> macros, which is intended for package writers.
A probably simpler way to proceed would be to use
L<sup>A</sup>T<sub>E</sub>X text-style declarations:
</p><pre class="verbatim">\newcommand{styledcite}[2][]{{\@style{cite}#1\bf{}#2}}
Two fundamental works: \styledcite{The Holy Bible} and
\styledcite[\color{red}]{Das Kapital}.
</pre><p>
We get:
Two fundamental works: <cite><span class="c023">The Holy Bible</span></cite> and
<span class="c025"><cite>Das Kapital</cite></span>.</p>
<h3 class="subsection" id="rawhtml">8.4  The <span class="c013">rawhtml</span> environment</h3>
<p>
<a id="hevea_default90"></a><a id="hevea_default91"></a>
Any text enclosed between <code>\begin{rawhtml}</code> and
<code>\end{rawhtml}</code> is echoed verbatim into the html output file.
Similarly, <code>\rawhtmlinput{</code><span class="c019">file</span><code>}</code> echoes the
contents of file <span class="c019">file</span>.
In fact, <code>rawhtml</code> is the environment counterpart of the
<code>\@print</code> command, but experience showed it to be much more
error prone.</p><p>When H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A was less sophisticated then it is now,
<span class="c013">rawhtml</span> was quite convenient.
But, as time went by,
numerous pitfalls around <span class="c013">rawhtml</span> showed up. Here are a few:
</p><ul class="itemize"><li class="li-itemize">
Verbatim means that no translation of any kind is performed. In
particular, be aware that input encoding (see <a href="manual-packages.html#inputenc">B.17.4</a>) does
not apply. Hence one should use ascii only, if needed
non-ascii characters can be given as
entity or numerical character references — <em>e.g.</em>
<code>&eacute;</code> or <code>&#XE9;</code> for é.</li><li class="li-itemize">The <span class="c013">rawhtml</span>
environment should contain only html text that makes sense alone.
For instance, writing
<code>\begin{rawhtml}<table>\end{rawhtml}</code>…
<code>\begin{rawhtml}</table>\end{rawhtml}</code> is
dangerous, because H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A is not informed about opening and closing
the block-level element <span class="c013">table</span>. In that case, one should use
the internal macros <code>\@open</code> and <code>\@close</code>.</li><li class="li-itemize"><code>\begin{rawhtml}</code><span class="c019">text</span><code>\end{rawhtml}</code> fragments that
contain block-level elements will almost certainly mix poorly with
<code>p</code> elements (introduced by paragraph breaks) and with active
style declaration (introduced by, for instance, <code>\it</code>).
Safe usage will most of the time means using the internal macros
<code>\@nostyle</code> and <code>\@out@par</code>.</li><li class="li-itemize">When H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A is given the command-line option <a id="hevea_default92"></a><span class="c013">-O</span>,
checking and optimisation of text-level elements in the whole document
takes place. As a consequence, incorrect html introduced by using
the <span class="c013">rawhtml</span> environment may be detected at a later stage,
but this is far from being certain.
</li></ul><p>As a conclusion, do not use the <span class="c013">rawhtml</span> environment!
A much safer option is to use the <span class="c013">htmlonly</span> environment
and to write L<sup>A</sup>T<sub>E</sub>X code.
For instance, in place of writing:
</p><pre class="verbatim">\begin{rawhtml}
A list of links:
<ul>
<li><a href="http://www.apple.com/">Apple</a>.
<li><a href="http://www.sun.com/">Sun</a>.
</ul>
\end{rawhtml}
</pre><p>
One can write:
</p><pre class="verbatim">\begin{htmlonly}
A list of links:
\begin{itemize}
\item \ahref{http://www.apple.com/}{Apple}.
\item \ahref{http://www.sun.com/}{Sun}.
\end{itemize}
\end{htmlonly}
</pre><p>
A list of links:
</p><ul class="itemize"><li class="li-itemize">
<a href="http://www.apple.com/">Apple</a>.
</li><li class="li-itemize"><a href="http://www.sun.com/">Sun</a>.
</li></ul><p><a id="hevea_default93"></a><a id="hevea_default94"></a>
<a id="hevea_default95"></a><a id="hevea_default96"></a>
If H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A is targeted to text or info files (see
Section <a href="manual021.html#alternative">11</a>).
The text inside <span class="c013">rawhtml</span> environments is ignored.
However there exists a <span class="c013">rawtext</span> environment (and a
<code>\rawtextinput</code> command) to echo text verbatim in text or info
output mode.
Additionally, the <span class="c013">raw</span> environment and a <code>\rawinput</code>
command echo their contents verbatim, regardless of H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A output
mode. Of course, when H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A produces html,
the latter environment and command suffer from
the same drawbacks as <span class="c013">rawhtml</span>.</p>
<h3 class="subsection" id="sec72">8.5  Examples</h3>
<p>
<a id="hevea_default97"></a><a id="hevea_default98"></a><a id="hevea_default99"></a>
As a first example of using internal macros, consider the following
excerpt from the <span class="c013">hevea.hva</span> file that
defines the <code>center</code> environment:
</p><pre class="verbatim">\newenvironment{center}{\@open{div}{style="text-align:center"}}{\@close{div}}
</pre><p>
<a id="hevea_default100"></a><a id="hevea_default101"></a>Notice that the code above is no longer present and is given here
for explanatory purpose only.
Now H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A uses style-sheets and the actual definition of the
<code>center</code> environment is as follows:
</p><pre class="verbatim">\newstyle{.center}{text-align:center;margin-left:auto;margin-right:auto;}%
\setenvclass{center}{center}%
\newenvironment{center}
{\@open{div}{\@getprint{class="\getenvclass{center}"}}
{\@close{div}}%
</pre><p>
Basically environments <code>\begin{center}</code>…<code>\end{center}</code> will, by
default, be translated into blocks
<code><div class="center"></code>…<code></div></code>.
Additionally, the style class associated to <code>center</code> environments
is managed through an indirection, using the
commands <code>\setenvclass</code> and <code>\getenvclass</code>.
See section <a href="manual019.html#css%3Achange">9.3</a> for more explanations.</p><p>Another example is the definition of the <code>\purple</code>
color declaration (see section <a href="#color%3Ahigh">8.1.2</a>):
</p><pre class="verbatim">\newcommand{\purple}{\@fontcolor{purple}}
</pre><p>H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A does not feature all text-level elements by default.
However one can easily use them with internal macros.
For instance this is how you can make all emphasised text blink:
</p><pre class="verbatim">\renewcommand{\em}{\@styleattr{em}{style="text-decoration:blink"}}
</pre><p>
Here is an example of this questionable blinking feature:
</p><div class="center">
<em style="text-decoration:blink">Hello!</em>
</div><p>
<a id="hevea_default102"></a></p><p><a id="hevea_default103"></a>
<a id="hevea_default104"></a>
<a id="hevea_default105"></a>
Then, here is the definition of a simplified <code>\imgsrc</code>
command (see section <a href="#hyperlink">8.1.1</a>), without its optional argument:
</p><pre class="verbatim">\newcommand{\imgsrc}[1]
{\@print{<img src="}\@getprint{#1}\@print{">}}
</pre><p>
Here, <code>\@print</code> and <code>\@getprint</code> are used to output
html text, depending upon whether this text requires processing or not.
Note that <code>\@open{img}{src="#1"}</code> is not correct,
because the element <code>img</code> consists in a single tag, without a
closing tag.</p><p><a id="hevea_default106"></a>
Another interesting example is the definition of the command
<code>\@doaelement</code>,
which H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A uses internally to output <span class="c013">A</span> elements.
</p><pre class="verbatim">\newcommand{\@doaelement}[2]
{{\@nostyle\@print{<a }\@getprint{#1}\@print{>}}{#2}{\@nostyle\@print{</a>}}
</pre><p>
The command <code>\@doaelement</code> takes two arguments: the first
argument contains the opening tag attributes; while the second element is
the textual content of the <code>A</code> element.
By contrast with the <code>\imgsrc</code> example above,
tags are emitted inside groups where styles are cancelled by using the
<code>\@nostyle</code> declaration.
Such a complication is needed, so as to avoid breaking proper nesting
of text-level elements.</p><p><a id="getcolor:usage"></a>
<a id="hevea_default107"></a>
<a id="hevea_default108"></a>
<a id="hevea_default109"></a>
Here is another example of direct block opening.
The <span class="c013">bgcolor</span> environment from the <span class="c013">color</span> package
locally changes background color (see section <a href="manual036.html#bgcolor">B.14.2.1</a>).
This environment is defined as follows:
</p><pre class="verbatim">\newenvironment{bgcolor}[2][style="padding:1em"]
{\@open{table}{}\@open{tr}{}%
\@open{td}{\@addstyle{background-color:\@getcolor{#2}}{#1}}}
{\@close{td}\@close{tr}\@close{table}}
</pre><p>
The <span class="c013">bgcolor</span> environment operates by opening a html table
(<code>table</code>) with only one row (<code>tr</code>) and cell (<code>td</code>) in
its opening command, and closing all these elements in its closing
command. In my opinion, such a style of opening block-level elements
in environment opening commands and closing them in environment
closing commands is good style.
<a id="hevea_default110"></a>The one cell background color is forced with a <code>background-color</code>
property in a <code>style</code> attribute.
Note that the mandatory argument to <code>\begin{bgcolor}</code> is the
background color expressed as a high-level color, which therefore
needs to be translated into a low-level color by using the
<code>\@getcolor</code> internal macro from the <span class="c013">color</span> package.
Additionally, <code>\begin{bgcolor}</code> takes html attributes
as an optional argument. These attributes are the ones of the
<code>table</code> element.</p><p><a id="hevea_default111"></a>If you wish to output a given Unicode character whose value you know,
the recommended technique is to define an ad-hoc command
that simply call the <code>\@print@u</code> command.
For instance, “blackboard sigma” is Unicode <span class="c013">U+02140</span> (hexa).
Hence you can define the command <code>\bbsigma</code> as follows:
</p><pre class="verbatim">\newcommand{\bbsigma}{\@print@u{X2140}}
</pre><p>
Then, “<code>\bbsigma</code>” will output “⅀”</p>
<h3 class="subsection" id="encodings">8.6  The document charset</h3>
<p>
According to standards, as far as I understand them, html pages are
made of Unicode (ISO 10646) characters.
By contrast, a file in any operating system is usually considered as
being made of bytes.</p><p><a id="hevea_default112"></a>To account for that fact, html pages usually specify a <em>document
charset</em> that defines a translation from a flow of bytes to a flow of
characters.
For instance, the byte
<span class="c013">0xA4</span> means Unicode <span class="c013">0x00A4</span> (¤) in the
ISO-8859-1 (or latin1) encoding, and <span class="c013">0x20AC</span> (€) in
the ISO-8859-15 (or latin9) encoding.
Notice that H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A has no difficulty to output both symbols, in fact
they are defined as Unicode characters:
</p><pre class="verbatim">\newcommand{\textcurrency}{\@print@u{XA4}}
\newcommand{\texteuro}{\@print@u{X20AC}}
</pre><p>
But the <code>\@print@u</code> command may output the specified character as
a byte, when possible, by the means of the <em>output translator</em>.
If not possible, <code>\@print@u</code> outputs a numerical character
references (for instance <code>&#X20AC;</code>).</p><p><a id="hevea_default113"></a>Of course, the document charset and the output translator
must be synchronised. The command <code>\@def@charset</code> takes a
charset name as argument and performs the operation of specifying the
document character set and the output translator. It should occur in
the document preamble.
Valid charset names are <span class="c013">ISO-8859-</span><span class="c019">n</span> where <span class="c019">n</span> is a
number in <span class="c013">1</span>…<span class="c013">15</span>,
<span class="c013">KOI8-R</span>, <span class="c013">US-ASCII</span> (the
default),
<span class="c013">windows-</span><span class="c019">n</span> where <span class="c019">n</span> is
<span class="c013">1250</span>, <span class="c013">1251</span>, <span class="c013">1252</span> or <span class="c013">1257</span>,
or <span class="c013">macintosh</span>, or <span class="c013">UTF-8</span>.
In case those charsets do not suffice, you may ask the author for
other document charsets. Notice however that document charset is not
that important, the default <span class="c013">US-ASCII</span> works everywhere!
<em>Input</em> encoding of source files is another, although
related, issue — see Section <a href="manual-packages.html#inputenc">B.17.4</a>.</p><p><a id="hevea_default114"></a>If wished so, the charset can be extracted from the current
locale environment, provided this yields a valid (to H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A) charset name.
This operation is performed by a companion script: <span class="c013">xxcharset.exe</span>.
It thus suffices to launch H<span class="c016"><sup>E</sup></span>V<span class="c016"><sup>E</sup></span>A as:
</p><div class="flushleft">
<span class="c013"># hevea -exec xxcharset.exe</span> <span class="c019">other arguments</span>
</div>
<hr>
<a href="cutname.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="manual002.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="manual019.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>
distrib
>
Mageia
>
7
>
i586
>
media
>
core-release
>
by-pkgid
>
fe880a8a8b91ae0b29da8fb72f3c41de
>
files
>
56
