<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd"> <HTML> <HEAD> <META http-equiv="Content-Type" content="text/html; charset=US-ASCII"> <META name="GENERATOR" content="hevea 1.10"> <META name="Author" content="Luc Maranget"> <LINK rel="stylesheet" type="text/css" href="manual.css"> <TITLE>Generating HTML constructs</TITLE> </HEAD> <BODY > <A HREF="cutname.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A> <A HREF="manual002.html"><IMG SRC="contents_motif.gif" ALT="Up"></A> <A HREF="manual019.html"><IMG SRC="next_motif.gif" ALT="Next"></A> <HR> <H2 CLASS="section"><A NAME="htoc30">8</A>  Generating HTML constructs</H2><UL> <LI><A HREF="manual018.html#toc22">High-Level Commands</A> </LI><LI><A HREF="manual018.html#toc23">More on included images</A> </LI><LI><A HREF="manual018.html#toc24">Internal macros</A> </LI><LI><A HREF="manual018.html#toc25">The <TT>rawhtml</TT> environment</A> </LI><LI><A HREF="manual018.html#toc26">Examples</A> </LI><LI><A HREF="manual018.html#toc27">The document charset</A> </LI></UL> <P> H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output language being HTML, it is normal for users to insert hypertext constructs their documents, or to control colors.</P><H3 CLASS="subsection"><A NAME="toc22"></A><A NAME="htoc31">8.1</A>  High-Level Commands</H3><P> H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A internals.</P><H4 CLASS="subsubsection">8.1.1  Commands for Hyperlinks</H4><P><A NAME="@default56"></A><A NAME="hyperlink"></A> A few commands for hyperlink management and included images are provided, all these commands have appropriate equivalents defined by the <TT>hevea</TT> 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 <TT>hevea</TT> package.</P><P><A NAME="@default57"></A><A NAME="@default58"></A><A NAME="@default59"></A><A NAME="@default60"></A><A NAME="@default61"></A><A NAME="@default62"></A><A NAME="@default63"></A><A NAME="@default64"></A></P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD ALIGN=center NOWRAP>Macro</TD><TD ALIGN=center NOWRAP COLSPAN=2>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</TD><TD ALIGN=center NOWRAP>L<sup>A</sup>T<sub>E</sub>X</TD></TR> <TR><TD CLASS="hbar" COLSPAN=4></TD></TR> <TR><TD VALIGN=top ALIGN=left NOWRAP> <CODE>\ahref{</CODE><I>url</I><CODE>}{</CODE><I>text</I><CODE>}</CODE>    </TD><TD VALIGN=top ALIGN=left>make <I>text</I> an hyperlink to <I>url</I></TD><TD VALIGN=top ALIGN=center NOWRAP>    </TD><TD VALIGN=top ALIGN=left>echo <I>text</I></TD></TR> <TR><TD CLASS="hbar" COLSPAN=4></TD></TR> <TR><TD VALIGN=top ALIGN=left NOWRAP> <CODE>\footahref{</CODE><I>url</I><CODE>}{</CODE><I>text</I><CODE>}</CODE>    </TD><TD VALIGN=top ALIGN=left>make <I>text</I> an hyperlink to <I>url</I></TD><TD VALIGN=top ALIGN=center NOWRAP>    </TD><TD VALIGN=top ALIGN=left>make <I>url</I> a footnote to <I>text</I>, <I>url</I> is shown in typewriter font</TD></TR> <TR><TD CLASS="hbar" COLSPAN=4></TD></TR> <TR><TD VALIGN=top ALIGN=left NOWRAP> <CODE>\ahrefurl{</CODE><I>url</I><CODE>}</CODE>    </TD><TD VALIGN=top ALIGN=left>make <I>url</I> an hyperlink to <I>url</I>.</TD><TD VALIGN=top ALIGN=center NOWRAP>    </TD><TD VALIGN=top ALIGN=left>typeset <I>url</I> in typewriter font</TD></TR> <TR><TD CLASS="hbar" COLSPAN=4></TD></TR> <TR><TD VALIGN=top ALIGN=left NOWRAP> <CODE>\ahrefloc{</CODE><I>label</I><CODE>}{</CODE><I>text</I><CODE>}</CODE>    </TD><TD VALIGN=top ALIGN=left>make <I>text</I> an hyperlink to <I>label</I> inside the document</TD><TD VALIGN=top ALIGN=center NOWRAP>    </TD><TD VALIGN=top ALIGN=left>echo <I>text</I></TD></TR> <TR><TD CLASS="hbar" COLSPAN=4></TD></TR> <TR><TD VALIGN=top ALIGN=left NOWRAP> <CODE>\aname{</CODE><I>label</I><CODE>}{</CODE><I>text</I><CODE>}</CODE>    </TD><TD VALIGN=top ALIGN=left>make <I>text</I> an hyperlink target with label <I>label</I></TD><TD VALIGN=top ALIGN=center NOWRAP>    </TD><TD VALIGN=top ALIGN=left>echo <I>text</I></TD></TR> <TR><TD CLASS="hbar" COLSPAN=4></TD></TR> <TR><TD VALIGN=top ALIGN=left NOWRAP> <CODE>\mailto{</CODE><I>address</I><CODE>}</CODE>    </TD><TD VALIGN=top ALIGN=left>make <I>address</I> a “mailto” link to <I>address</I></TD><TD VALIGN=top ALIGN=center NOWRAP>    </TD><TD VALIGN=top ALIGN=left>typeset <I>address</I> in typewriter font</TD></TR> <TR><TD CLASS="hbar" COLSPAN=4></TD></TR> <TR><TD VALIGN=top ALIGN=left NOWRAP><CODE>\imgsrc[</CODE><I>attr</I><CODE>]{</CODE><I>url</I><CODE>}</CODE>    </TD><TD VALIGN=top ALIGN=left>insert <I>url</I> as an image, <I>attr</I> are attributes in the HTML sense</TD><TD VALIGN=top ALIGN=center NOWRAP>    </TD><TD VALIGN=top ALIGN=left>do nothing</TD></TR> <TR><TD CLASS="hbar" COLSPAN=4></TD></TR> <TR><TD VALIGN=top ALIGN=left NOWRAP><CODE>\home{</CODE><I>text</I><CODE>}</CODE>    </TD><TD VALIGN=top ALIGN=left COLSPAN=3>produce a home-dir url both for output and links, output aspect is: “~<I>text</I>”</TD></TR> </TABLE><P><A NAME="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 NAME="@default65"></A> Fortunately, the <TT>url</TT> 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 <TT>url</TT> 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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A (optionally) depends on only one third party package: <TT>url</TT>, which is as correct as it can be and well-written.</P><P><A NAME="@default66"></A> <A NAME="@default67"></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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A. Note that this usage of <CODE>\url</CODE> is deprecated.</P><H4 CLASS="subsubsection">8.1.2  HTML style colors</H4><P><A NAME="color:high"></A> Specifying colors both for L<sup>A</sup>T<sub>E</sub>X and H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A should be done using the <TT>color</TT> package (see section <A HREF="manual036.html#color:package">B.14.2</A>). However,one can also specify text color using special type style declarations. The <TT>hevea.sty</TT> style file define no equivalent for these declarations, which therefore are for H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A consumption only.</P><P>Those declarations follow HTML conventions for colors. There are sixteen predefined colors: </P><DIV CLASS="center"> <TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><FONT COLOR=black><CODE>\black</CODE>, </FONT><FONT COLOR=silver><CODE>\silver</CODE>, </FONT><FONT COLOR=gray><CODE>\gray</CODE>, </FONT><FONT COLOR=white><CODE>\white</CODE>, </FONT><FONT COLOR=maroon><CODE>\maroon</CODE>, </FONT><FONT COLOR=red><CODE>\red</CODE>, </FONT><FONT COLOR=fuchsia><CODE>\fuchsia</CODE>, </FONT><FONT COLOR=purple><CODE>\purple</CODE>, </FONT><FONT COLOR=green><CODE>\green</CODE>, </FONT><FONT COLOR=lime><CODE>\lime</CODE>, </FONT><FONT COLOR=olive><CODE>\olive</CODE>, </FONT><FONT COLOR=yellow><CODE>\yellow</CODE>, </FONT><FONT COLOR=navy><CODE>\navy</CODE>, </FONT><FONT COLOR=blue><CODE>\blue</CODE>, </FONT><FONT COLOR=teal><CODE>\teal</CODE>, </FONT><FONT COLOR=aqua><CODE>\aqua</CODE></FONT></TD></TR> </TABLE> </DIV><P> <A NAME="@default68"></A>Additionally, the current text color can be changed by the declaration <CODE>\htmlcolor{</CODE><I>number</I><CODE>}</CODE>, where <I>number</I> is a six digit hexadecimal number specifying a color in the RGB space. For instance, the declaration <FONT COLOR="#404040"><CODE>\htmlcolor{404040}</CODE></FONT> changes font color to dark gray,</P><H3 CLASS="subsection"><A NAME="toc23"></A><A NAME="htoc32">8.2</A>  More on included images</H3><P><A NAME="imgsrc"></A> <A NAME="@default69"></A><A NAME="@default70"></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 <TT>epsf</TT> package. For instance, if <TT>screenshot.ps</TT> is an encapsulated Postscript file, then a <TT>doc.tex</TT> 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 <TT>screenshot.ps.gif</TT> file. Then, for H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A to include a link to the GIF image in its output, it suffices to define the <CODE>\epsfbox</CODE> command in the <TT>macro.hva</TT> file as follows: </P><PRE CLASS="verbatim">\newcommand{\epsfbox}[1]{\imgsrc{#1.gif}} </PRE><P>Then H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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 <I>name</I><TT>.ps</TT>, while GIF files are of the kind <I>name</I><TT>.gif</TT>. Then, images can be included using <CODE>\includeimage{</CODE><I>name</I><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 <TT>hevea</TT> boolean register (see section <A HREF="manual007.html#heveabool">5.2.3</A>). If one does not wish to load the <TT>hevea.sty</TT> 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 GIF image and using the <CODE>\imgsrc</CODE> command is the most adequate. It should be preferred over using the more automated <I>image</I> 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"><A NAME="toc24"></A><A NAME="htoc33">8.3</A>  Internal <A NAME="internal"></A>macros</H3><P> In this section a few of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A internal macros are described. Internal macros occur at the final expansion stage of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A and invoke Objective Caml code.</P><P>Normally, user source code should not use them, since their behavior may change from one version of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A to another and because using them incorrectly easily crashes H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A works. </LI></UL><P><A NAME="@default71"></A> The general principle of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A is that L<sup>A</sup>T<sub>E</sub>X environments <CODE>\begin{</CODE><I>env</I><CODE>}</CODE>… <CODE>\end{</CODE><I>env</I><CODE>}</CODE> get translated into HTML block-level elements <CODE><</CODE><I>block attributes</I><CODE>></CODE>… <CODE></</CODE><I>block</I><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 paragraph, 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-4.0</A>]”, block-level elements cannot occur inside <CODE>P</CODE>; more precisely, block-level opening tags implicitely close any active <CODE>P</CODE>. As a consequence, H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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, similarily 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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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 NAME="@default72"></A> <A NAME="@default73"></A> <A NAME="@default74"></A> <A NAME="@default75"></A> <A NAME="@default76"></A> <A NAME="@default77"></A> <A NAME="@default78"></A> <A NAME="@default79"></A> <A NAME="@default80"></A> <A NAME="@default81"></A> <A NAME="@default82"></A> <A NAME="@default83"></A> <A NAME="@default84"></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"> <B><TT>\@print{</TT><I>text</I><TT>}</TT></B></DT><DD CLASS="dd-description"> Echo <I>text</I> verbatim. As a consequence use only ascii in <I>text</I>. </DD><DT CLASS="dt-description"><B><TT>\@getprint{</TT><I>text</I><TT>}</TT></B></DT><DD CLASS="dd-description"> Process <I>text</I> 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"><B><TT>\@hr[</TT><I>attr</I><TT>]{</TT><I>width</I><TT>}{</TT><I>height</I><TT>}</TT></B></DT><DD CLASS="dd-description"> Output an HTML horizontal rule, <I>attr</I> is attributes given directly (e.g. <CODE>SIZE=3 HOSHADE</CODE>), while <I>width</I> and <I>height</I> 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"><B><TT>\@print@u{</TT><I>n</I><TT>}</TT></B></DT><DD CLASS="dd-description"> Output the (Unicode) character “<I>n</I>”, which can be given either as a decimal number or an hexadecimal number prefixed by “<TT>X</TT>”.</DD><DT CLASS="dt-description"><B><TT>\@open{</TT><I>BLOCK</I><TT>}{</TT><I>attributes</I><TT>}</TT></B></DT><DD CLASS="dd-description"> Open HTML block-level element <I>BLOCK</I> with attributes <I>attributes</I>. The block name <I>BLOCK</I> <EM>must</EM> be uppercase. As a special case <I>BLOCK</I> may be the empty string, then a HTML <EM>group</EM> is opened. </DD><DT CLASS="dt-description"><B><TT>\@close{</TT><I>BLOCK</I><TT>}</TT></B></DT><DD CLASS="dd-description"> Close HTML block-level element <I>BLOCK</I>. Note that <CODE>\@open</CODE> and <CODE>\@close</CODE> must be properly balanced. </DD><DT CLASS="dt-description"><B><TT>\@out@par{</TT><I>arg</I><TT>}</TT></B></DT><DD CLASS="dd-description"> If occuring 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 <I>arg</I>, and then re-open a <CODE>P</CODE> element. Otherwise <CODE>\@out@par</CODE> simply formats <I>arg</I>. This command is adequate when formatting <I>arg</I> produces block-level elements. Besides text-level elements should be managed properly (see below). </DD></DL><P><A NAME="@default85"></A> Text-level elements are managed differently. They are not seen as blocks that must be closed explicitly and they are replaced by the internal text-level declarations <CODE>\@style</CODE> (and <CODE>\@styleattr</CODE>), <CODE>\@fontsize</CODE> and <CODE>\@fontcolor</CODE>. Block-level elements (and HTML groups) delimit the effect of such declarations. </P><DL CLASS="description"><DT CLASS="dt-description"> <B><TT>\@style{</TT><I>SHAPE</I><TT>}</TT></B></DT><DD CLASS="dd-description"> Declare the text shape <I>SHAPE</I> (which must be uppercase) as active. Text shapes are known as font style elements (<CODE>I</CODE>, <CODE>TT</CODE>, etc.) or phrase elements (<CODE>EM</CODE>, etc.) in the HTML terminology, they are part of the more general class of text-level elements.<P>The text-level element <I>SHAPE</I> 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 <I>SHAPE</I> before them, and re-opening <I>SHAPE</I> inside them. The next text-level constructs exhibit similar behavior with respect to block-level elements. </P></DD><DT CLASS="dt-description"><B><TT>\@styleattr{</TT><I>NAME</I><TT>}{</TT><I>attr</I><TT>}</TT></B></DT><DD CLASS="dd-description"><A NAME="@default86"></A> Declare the text-level element <I>NAME</I> with attribute <I>attr</I> active. This primitive behaves as <CODE>\@style</CODE>, except that the opening tag has attributes. This primitive may prove useful for introducing <TT>SPAN</TT> elements. Note that both argument are processed. </DD><DT CLASS="dt-description"><B><TT>\@span{</TT><I>attr</I><TT>}</TT></B></DT><DD CLASS="dd-description"> A shorthand for <CODE>\@styleattr{SPAN}{</CODE><I>attr</I><CODE>}</CODE>. </DD><DT CLASS="dt-description"><B><TT>\@fontsize{</TT><I>int</I><TT>}</TT></B></DT><DD CLASS="dd-description"> Declare the text-level element <CODE>FONT</CODE> with attribute <CODE>SIZE=</CODE><I>int</I> as active. Note that <I>int</I> must be a small integer in the range <TT>1</TT>,<TT>2</TT>, … , <TT>7</TT>. </DD><DT CLASS="dt-description"><B><TT>\@fontcolor{</TT><I>color</I><TT>}</TT></B></DT><DD CLASS="dd-description"> Declare the text-level element <CODE>FONT</CODE> with attribute <CODE>COLOR=</CODE><I>color</I> as active. Note that <I>color</I> must be a color attribute value in the HTML style. That is either one of the sixteen conventional colors <CODE>black</CODE>, <CODE>silver</CODE> etc, or a RGB hexadecimal color specification of the form <CODE>"#</CODE><I>XXXXXX</I><CODE>"</CODE> (yes, quotes are needed). Note that the argument <I>color</I> is processed, as a consequence numerical color arguments should be given as <CODE>"\#</CODE><I>XXXXXX</I><CODE>"</CODE>.</DD><DT CLASS="dt-description"><TT><B>\@nostyle</B></TT></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"><TT><B>\@clearstyle</B></TT></DT><DD CLASS="dd-description"> Simply close active text-level declarations. </DD></DL><H3 CLASS="subsection"><A NAME="toc25"></A><A NAME="htoc34">8.4</A>  The <TT>rawhtml</TT><A NAME="rawhtml"></A> environment</H3><P> <A NAME="@default87"></A><A NAME="@default88"></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><I>file</I><CODE>}</CODE> echoes the contents of file <I>file</I>. 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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A was less sophisticated then it is now, <TT>rawhtml</TT> was quite convenient. But, as time went by, numerous pitfalls around <TT>rawhtml</TT> 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 <TT>rawhtml</TT> environment should contain only HTML text that makes sense alone. For instance, writing <CODE>\begin{rawhtml}<TABLE><ALIGN=right>\end{rawhtml}</CODE>… <CODE>\begin{rawhtml}</TABLE>\end{rawhtml}</CODE> is dangerous, because H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A is not informed about opening and closing the block-level element <TT>TABLE</TT>. 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><I>text</I><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<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A is given the command-line option <A NAME="@default89"></A><TT>-O</TT>, checking and optimization of text-level elements in the whole document takes place. As a consequence, incorrect HTML introduced by using the <TT>rawhtml</TT> 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 <TT>rawhtml</TT> environment! A much safer option is to use the <TT>htmlonly</TT> 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 NAME="@default90"></A><A NAME="@default91"></A> <A NAME="@default92"></A><A NAME="@default93"></A> If H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A is targeted to text or info files (see Section <A HREF="manual021.html#alternative">11</A>). The text inside <TT>rawhtml</TT> environments is ignored. However there exists a <TT>rawtext</TT> environment (and a <CODE>\rawtextinput</CODE> command) to echo text verbatim in text or info output mode. Additionally, the <TT>raw</TT> environment and a <CODE>\rawinput</CODE> command echo their contents verbatim, regardless of H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A output mode. Of course, when H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A produces HTML, the latter environement and command suffer from the same drawbacks as <TT>rawhtml</TT>.</P><H3 CLASS="subsection"><A NAME="toc26"></A><A NAME="htoc35">8.5</A>  Examples</H3><P> <A NAME="@default94"></A><A NAME="@default95"></A><A NAME="@default96"></A> As a first example of using internal macros, consider the following excerpt from the <TT>hevea.hva</TT> file that defines the <CODE>center</CODE> environment: </P><PRE CLASS="verbatim">\newenvironment{center}{\@open{DIV}{ALIGN=center}}{\@close{DIV}} </PRE><P><A NAME="@default97"></A><A NAME="@default98"></A>Notice that the code above is no longer present and is given here for explanatory purpose only. Now H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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:change">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:high">8.1.2</A>): </P><PRE CLASS="verbatim">\newcommand{\purple}{\@fontcolor{purple}} </PRE><P>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A does not feature all text-level elements by default. However one can easily use them with the internal macro <CODE>\@style</CODE>. For instance this is how you can make all emphasized text blink: </P><PRE CLASS="verbatim">\renewcommand{\em}{\@style{EM}\@style{BLINK}} </PRE><P><A NAME="@default99"></A> <A NAME="@default100"></A> <A NAME="@default101"></A> <A NAME="@default102"></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 NAME="@default103"></A> Another interesting example is the definition of the command <CODE>\@doaelement</CODE>, which H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A uses internally to output <TT>A</TT> 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 canceled 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 NAME="getcolor:usage"></A> <A NAME="@default104"></A> <A NAME="@default105"></A> <A NAME="@default106"></A> Here is another example of direct block opening. The <TT>bgcolor</TT> environment from the <TT>color</TT> 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][CELLPADDING=10] {\@open{TABLE}{#1}\@open{TR}{}\@open{TD}{BGCOLOR=\@getcolor{#2}}} {\@close{TD}\@close{TR}\@close{TABLE}} </PRE><P>The <TT>bgcolor</TT> 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 NAME="@default107"></A>The one cell background color is forced with a <CODE>BGCOLOR</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 <TT>color</TT> 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 NAME="@default108"></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 <TT>U+02140</TT> (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"><A NAME="toc27"></A><A NAME="htoc36">8.6</A>  The <A NAME="encodings"></A>document charset</H3><P> According to standards, as I understand them, HTML pages are made of Unicode (ISO 10646) characters. By constrast, a file in any operating system is usually considerered as being made of bytes.</P><P><A NAME="@default109"></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 <TT>0xA4</TT> means Unicode <TT>0x00A4</TT> (¤) in the ISO-8859-1 (or latin1) encoding, and <TT>0x20AC</TT> (€) in the ISO-8859-15 (or latin9) encoding. Notice that H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>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 NAME="@default110"></A>Of course, the document charset and the output translator must be synchronized. 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 <TT>ISO-8859-</TT><I>n</I> where <I>n</I> is a number in <TT>1</TT>…<TT>15</TT>, <TT>KOI8-R</TT>, <TT>US-ASCII</TT> (the default), <TT>windows-</TT><I>n</I> where <I>n</I> is <TT>1250</TT>, <TT>1251</TT>, <TT>1252</TT> or <TT>1257</TT>, or <TT>macintosh</TT>, or <TT>UTF-8</TT>. 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 <TT>US-ASCII</TT> 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 NAME="@default111"></A>If wished so, the charset can be extracted from the current locale environment, provided this yields a valid (to H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A) charset name. This operation is performed by a companion script: <TT>xxcharset.exe</TT>. It thus suffices to launch H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A as: </P><DIV CLASS="flushleft"> <TT># hevea -exec xxcharset.exe</TT> <I>other arguments</I> </DIV><HR> <A HREF="cutname.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A> <A HREF="manual002.html"><IMG SRC="contents_motif.gif" ALT="Up"></A> <A HREF="manual019.html"><IMG SRC="next_motif.gif" ALT="Next"></A> </BODY> </HTML>