<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.06">
<style type="text/css">
.c000{background-color:green;height:3px}
.c001{border-spacing:0;}
.c002{border-spacing:6px;border-collapse:separate;}
.c003{border:0;border-spacing:1;border-collapse:separate;}
.c004{border:0;border-spacing:1px;border-collapse:separate}
.c005{border:1px solid black;}
.c006{color:#006600}
.c007{color:#B7140B}
.c008{color:fuchsia}
.c009{color:maroon}
.c010{color:purple}
.c011{color:yellow}
.c012{font-family:Helvetica}
.c013{font-family:monospace}
.c014{font-family:monospace;font-weight:bold}
.c015{font-size:small}
.c016{font-size:x-large}
.c017{font-size:xx-large}
.c018{font-style:italic}
.c019{font-style:oblique}
.c020{font-variant:small-caps}
.c021{font-variant:small-caps;font-size:small}
.c022{font-weight:bold}
.c023{font-weight:bold;color:blue}
.c024{font-weight:bold;color:red}
.c025{height:4em; margin:0ex 2px;}
.c026{height:4em; margin:0ex 4px;}
.c027{text-align:center}
.c028{text-align:center;border:solid 1px;white-space:nowrap}
.c029{text-align:center;white-space:nowrap}
.c030{text-align:left}
.c031{text-align:left;border:solid 1px;white-space:nowrap}
.c032{text-align:left;white-space:nowrap}
.c033{text-align:right;white-space:nowrap}
.c034{vertical-align:bottom}
.c035{vertical-align:middle}
.c036{vertical-align:middle;text-align:left;}
.c037{vertical-align:top}
.c038{vertical-align:top;text-align:center;border:solid 1px;white-space:nowrap}
.c039{vertical-align:top;text-align:left;}
.c040{vertical-align:top;text-align:left;border:solid 1px;}
.c041{vertical-align:top;text-align:left;white-space:nowrap}
.c042{whitespace:nowrap;text-align:center}
.c043{whitespace:nowrap;text-align:left}
.c044{width:10%;text-align:center}
.c045{width:100%;}
.c046{width:40%;text-align:center}
.c047{width:5%;text-align:center}
.c048{width:6px;}
.c049{width:80%;height:2}
.c050{width:90%;text-align:center}
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.footnotetext{margin:0ex; padding:0ex;}
div.footnotetext P{margin:0px; text-indent:1em;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.caption{padding-left:2ex; padding-right:2ex; margin-left:auto; margin-right:auto}
.title{margin:2ex auto;text-align:center}
.titlemain{margin:1ex 2ex 2ex 1ex;}
.titlerest{margin:0ex 2ex;}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
div table{margin-left:inherit;margin-right:inherit;margin-bottom:2px;margin-top:2px}
td table{margin:auto;}
table{border-collapse:collapse;}
td{padding:0;}
.cellpadding0 tr td{padding:0;}
.cellpadding1 tr td{padding:1px;}
pre{text-align:left;margin-left:0ex;margin-right:auto;}
blockquote{margin-left:4ex;margin-right:4ex;text-align:left;}
td p{margin:0px;}
.boxed{border:1px solid black}
.textboxed{border:1px solid black}
.vbar{border:none;width:2px;background-color:black;}
.hbar{border:none;height:2px;width:100%;background-color:black;}
.display{border-collapse:separate;border-spacing:2px;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px; border:none;}
.dcenter{margin:0ex auto;}
.marginparleft{float:left; margin-left:0ex; margin-right:1ex;}
.marginparright{float:right; margin-left:1ex; margin-right:0ex;}
.part{margin:2ex auto;text-align:center}
.clisting{font-family:monospace;white-space:pre;
border-left:solid black;padding-left:2ex;margin-left:2ex;}
.delimleft{border-collapse:separate;border-spacing:0px;margin:0px 4px 0px 0px;}
.delimright{border-collapse:separate;border-spacing:0px;margin:0px 0px 0px 4px;}
.bracell{padding:0ex;}
.lstlisting{font-family:monospace;white-space:pre;margin-right:auto;margin-left:0pt;text-align:left}
.mprow{border-collapse:separate;border-spacing:2ex;width:100%;margin:0ex;}
.mprcell{padding:0px;width:auto;}
.subsectionex{padding:1ex;color:navy;border:solid navy;}
.verbatim{margin:1ex 1ex;padding:1ex;background:#CCFFCC;}
.myverbatim{margin:1ex 3ex;padding:1ex;
color:maroon;
background:#FFAD7A}
.toc1{list-style:none;border-left:1ex solid #4C0D00;padding:0ex 1ex;}
.toc2{list-style:none;border-left:1ex solid #661300;padding:0ex 1ex;}
.toc3{list-style:none;border-left:1ex solid #DB9370;padding:0ex 1ex;}
.toc4{list-style:none;border-left:1ex solid #FF897F;padding:0ex 1ex;}
.xtitle{text-align:center;margin:1ex auto;color:navy;border:solid navy;}
.xtitlerest{font-variant:small-caps;}
.ruled{border:solid black;padding:1ex;background:#eeddbb;color:maroon}
.ruledbis{border:solid black;padding:1ex;background:#eeddbb;color:maroon;display:inline-block}
body{background-color:white}
a:link{color:#00B200;text-decoration:underline;}
a:visited{color:#006600;text-decoration:underline;}
a:hover{color:black;text-decoration:none;background-color:#99FF99}
.title{background-color:#00B200}
.titlemain{background-color:#00B200}
.titlerest{ackground-color:#00B200}
.part{padding:1ex;background-color:#00CC00}
.section{padding:.5ex;background-color:#2DE52D}
.subsection{padding:0.3ex;background-color:#66FF66}
.subsubsection{padding:0.5ex;background-color:#99FF99}
.paragraph{padding:0.5ex;background-color:#CCFFCC}
.fmarginpar{border:solid thin #66FF66; width:20%; text-align:left}
.ffootnoterule{border:none;margin:1em auto 1em 0px;width:50%;background-color:#00CC00}
.ftoc1{list-style:none;margin:0ex 1ex;padding:0ex 1ex;border-left:1ex solid #00CC00}
.ftoc2{list-style:none;margin:1ex 1ex;padding:0ex 1ex;border-left:1ex solid #2DE52D}
.ftoc3{list-style:none;margin:0ex 1ex;padding:0ex 1ex;border-left:1ex solid #66FF66}
</style>
<META name="Author" content="Luc Maranget">
<title>HEVEA User Documentation
Version 2.06
</title>
</head>
<body>
<!--HEVEA command line is: ../hevea.opt -fix -exec xxdate.exe -O -o doc/manual.html manual.hva manual.tex -->
<!--CUT STYLE article--><!--SETENV <arg PREVTXT><img src="previous_motif.gif" alt="Previous"></arg><arg UPTXT><img src="contents_motif.gif" alt="Up"></arg><arg NEXTTXT><img src="next_motif.gif" alt="Next"></arg>-->
<!--CUT DEF part 1 --><table class="title"><tr><td style="padding:1ex"><h1 class="titlemain">H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A User Documentation<br>
Version 2.06</h1><h3 class="titlerest">Luc Maranget<sup><a id="text1" href="#note1">*</a></sup></h3><h3 class="titlerest">March 29, 2013</h3></td></tr>
</table><hr><p>
This manual also exists in
<a href="http://hevea.inria.fr/distri/hevea-2.06-manual.ps.gz">compressed Postscript</a>,
<a href="http://hevea.inria.fr/distri/hevea-2.06-manual.pdf">PDF</a>, and as
a <a href="http://hevea.inria.fr/distri/hevea-2.06-manual.tar.gz">bundle of HTML files</a>.
</p><hr><blockquote class="abstract"><span class="c022">Abstract: </span>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is a L<sup>A</sup>T<sub>E</sub>X to
html translator.
The input language is a fairly complete subset of L<sup>A</sup>T<sub>E</sub>X 2є (old
L<sup>A</sup>T<sub>E</sub>X style is also accepted) and the
output language is html that is (hopefully) correct with respect to
version 5 [<a href="#html">HTML-5a</a>, <a href="#htmlb">HTML-5b</a>] <p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A understands L<sup>A</sup>T<sub>E</sub>X macro definitions. Simple user style
files are understood with little or no modifications.
Furthermore, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A customisation is done by writing L<sup>A</sup>T<sub>E</sub>X code.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is written in Objective Caml, as many lexers. It is
quite fast and flexible. Using H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A it is possible to translate
large documents such as manuals, books, etc. very quickly. All
documents are translated as one single html file. Then, the output
file can be cut into smaller files, using the companion program H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can also be instructed to output plain text or info files.</p><p>Information on H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is available at <a href="http://hevea.inria.fr/"><span class="c013">http://hevea.inria.fr/</span></a>.
</p></blockquote><!--CUT DEF section --><!--TOC section id="sec1" Contents-->
<h2 class="section" id="sec1"><a id="ftoc">Contents</a></h2><!--SEC END --><ul class="ftoc1"><li class="li-toc">
<a href="#sec2">Part A  Tutorial</a>
<ul class="ftoc2"><li class="li-toc">
<a href="#getstarted">1  How to get started</a>
</li><li class="li-toc"><a href="#sec4">2  Style files</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec5">2.1  Standard base styles</a>
</li><li class="li-toc"><a href="#sec6">2.2  Other base styles</a>
</li><li class="li-toc"><a href="#sec7">2.3  Other style files</a>
</li></ul>
</li><li class="li-toc"><a href="#sec10">3  A note on style</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec11">3.1  Spacing, Paragraphs</a>
</li><li class="li-toc"><a href="#sec14">3.2  Math mode</a>
</li><li class="li-toc"><a href="#sec19">3.3  Warnings</a>
</li><li class="li-toc"><a href="#sec20">3.4  Commands</a>
</li><li class="li-toc"><a href="#sec21">3.5  Style choices</a>
</li></ul>
</li><li class="li-toc"><a href="#sec22">4  How to detect and correct errors</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec23">4.1  H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not know a macro</a>
</li><li class="li-toc"><a href="#sec24">4.2  H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A incorrectly interprets a macro</a>
</li><li class="li-toc"><a href="#sec25">4.3  H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A crashes</a>
</li></ul>
</li><li class="li-toc"><a href="#sec29">5  Making H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and L<sup>A</sup>T<sub>E</sub>X both happy</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec30">5.1  File loading</a>
</li><li class="li-toc"><a href="#heveastyle">5.2  The <span class="c013">hevea</span> package</a>
</li><li class="li-toc"><a href="#sec35">5.3  Comments</a>
</li></ul>
</li><li class="li-toc"><a href="#imagen">6  With a little help from L<sup>A</sup>T<sub>E</sub>X</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#image%3Afile">6.1  The <span class="c018">image</span> file</a>
</li><li class="li-toc"><a href="#sec38">6.2  A toy example</a>
</li><li class="li-toc"><a href="#sec39">6.3  Including Postscript images</a>
</li><li class="li-toc"><a href="#sec40">6.4  Using filters</a>
</li></ul>
</li><li class="li-toc"><a href="#hacha">7  Cutting your document into pieces with H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec42">7.1  Simple usage</a>
</li><li class="li-toc"><a href="#sec43">7.2  Advanced usage</a>
</li><li class="li-toc"><a href="#sec49">7.3  More Advanced Usage</a>
</li></ul>
</li><li class="li-toc"><a href="#sec64">8  Generating html constructs</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec65">8.1  High-Level Commands</a>
</li><li class="li-toc"><a href="#imgsrc">8.2  More on included images</a>
</li><li class="li-toc"><a href="#internal">8.3  Internal macros</a>
</li><li class="li-toc"><a href="#rawhtml">8.4  The <span class="c013">rawhtml</span> environment</a>
</li><li class="li-toc"><a href="#sec72">8.5  Examples</a>
</li><li class="li-toc"><a href="#encodings">8.6  The document charset</a>
</li></ul>
</li><li class="li-toc"><a href="#style%3Asheets">9  Support for style sheets</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec75">9.1  Overview</a>
</li><li class="li-toc"><a href="#css%3Achange%3Aall">9.2  Changing
the style of all instances of an environment</a>
</li><li class="li-toc"><a href="#css%3Achange">9.3  Changing the style of some instances of an environment</a>
</li><li class="li-toc"><a href="#whatclass">9.4  Which class affects what</a>
</li><li class="li-toc"><a href="#sec79">9.5  A few examples</a>
</li><li class="li-toc"><a href="#sec83">9.6  Miscellaneous</a>
</li></ul>
</li><li class="li-toc"><a href="#sec88">10  Customising H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec89">10.1  Simple changes</a>
</li><li class="li-toc"><a href="#sec90">10.2  Changing defaults for type-styles</a>
</li><li class="li-toc"><a href="#sec91">10.3  Changing the interface of a command</a>
</li><li class="li-toc"><a href="#sec92">10.4  Checking the optional argument within a command</a>
</li><li class="li-toc"><a href="#sec93">10.5  Changing the format of images</a>
</li><li class="li-toc"><a href="#sec94">10.6  Storing images in a separate directory</a>
</li><li class="li-toc"><a href="#imagen-source">10.7  Controlling <span class="c013">imagen</span> from document source</a>
</li></ul>
</li><li class="li-toc"><a href="#alternative">11  Other output formats</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec97">11.1  Text</a>
</li><li class="li-toc"><a href="#sec98">11.2  Info</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#sec99">Part B  Reference manual</a>
<ul class="ftoc2"><li class="li-toc">
<a href="#sec100">B.1  Commands and Environments</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec101">B.1.1  Command Names and Arguments</a>
</li><li class="li-toc"><a href="#sec102">B.1.2  Environments</a>
</li><li class="li-toc"><a href="#sec103">B.1.3  Fragile Commands</a>
</li><li class="li-toc"><a href="#sec104">B.1.4  Declarations</a>
</li><li class="li-toc"><a href="#sec105">B.1.5  Invisible Commands</a>
</li><li class="li-toc"><a href="#sec106">B.1.6  The <span class="c013">\\</span> Command</a>
</li></ul>
</li><li class="li-toc"><a href="#sec107">B.2  The Structure of the Document</a>
</li><li class="li-toc"><a href="#sec108">B.3  Sentences and Paragraphs</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec109">B.3.1  Spacing</a>
</li><li class="li-toc"><a href="#sec110">B.3.2  Paragraphs</a>
</li><li class="li-toc"><a href="#sec111">B.3.3  Footnotes</a>
</li><li class="li-toc"><a href="#accents">B.3.4  Accents and special symbols</a>
</li></ul>
</li><li class="li-toc"><a href="#sec113">B.4  Sectioning</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#section%3Asection">B.4.1  Sectioning Commands</a>
</li><li class="li-toc"><a href="#appendix">B.4.2  The Appendix</a>
</li><li class="li-toc"><a href="#sec116">B.4.3  Table of Contents</a>
</li><li class="li-toc"><a href="#no%3Anumber">Use H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A</a>
</li></ul>
</li><li class="li-toc"><a href="#sec118">B.5  Classes, Packages and Page Styles</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec119">B.5.1  Document Class</a>
</li><li class="li-toc"><a href="#sec120">B.5.2  Packages and Page Styles</a>
</li><li class="li-toc"><a href="#sec121">B.5.3  The Title Page and Abstract</a>
</li></ul>
</li><li class="li-toc"><a href="#sec122">B.6  Displayed Paragraphs</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec123">B.6.1  Quotation and Verse</a>
</li><li class="li-toc"><a href="#sec124">B.6.2  List-Making environments</a>
</li><li class="li-toc"><a href="#sec125">B.6.3  The <span class="c013">list</span> and <span class="c013">trivlist</span>
environments</a>
</li><li class="li-toc"><a href="#sec126">B.6.4  Verbatim</a>
</li></ul>
</li><li class="li-toc"><a href="#sec127">B.7  Mathematical Formulae</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec128">B.7.1  Math Mode Environment</a>
</li><li class="li-toc"><a href="#sec129">B.7.2  Common Structures</a>
</li><li class="li-toc"><a href="#sec130">B.7.3  Square Root</a>
</li><li class="li-toc"><a href="#sec131">B.7.4  Unicode and mathematical symbols</a>
</li><li class="li-toc"><a href="#sec132">B.7.5  Putting one thing above/below/inside</a>
</li><li class="li-toc"><a href="#sec133">B.7.6  Math accents</a>
</li><li class="li-toc"><a href="#sec134">B.7.7  Spacing</a>
</li><li class="li-toc"><a href="#sec135">B.7.8  Changing Style</a>
</li></ul>
</li><li class="li-toc"><a href="#sec136">B.8  Definitions, Numbering</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec137">B.8.1  Defining Commands</a>
</li><li class="li-toc"><a href="#sec138">B.8.2  Defining Environments</a>
</li><li class="li-toc"><a href="#sec139">B.8.3  Theorem-like Environments</a>
</li><li class="li-toc"><a href="#sec140">B.8.4  Numbering</a>
</li><li class="li-toc"><a href="#sec141">B.8.5  The <span class="c013">ifthen</span> Package</a>
</li></ul>
</li><li class="li-toc"><a href="#sec142">B.9  Figures and Other Floating Bodies</a>
</li><li class="li-toc"><a href="#sec143">B.10  Lining It Up in Columns</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec144">B.10.1  The <span class="c013">tabbing</span> Environment</a>
</li><li class="li-toc"><a href="#sec145">B.10.2  The <span class="c013">array</span> and <span class="c013">tabular</span>
environments</a>
</li></ul>
</li><li class="li-toc"><a href="#sec146">B.11  Moving Information Around</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#files">B.11.1  Files</a>
</li><li class="li-toc"><a href="#cross-reference">B.11.2  Cross-References</a>
</li><li class="li-toc"><a href="#sec149">B.11.3  Bibliography and Citations</a>
</li><li class="li-toc"><a href="#sec151">B.11.4  Splitting the Input</a>
</li><li class="li-toc"><a href="#sec152">B.11.5  Index and Glossary</a>
</li><li class="li-toc"><a href="#sec153">B.11.6  Terminal Input and Output</a>
</li></ul>
</li><li class="li-toc"><a href="#sec154">B.12  Line and Page Breaking</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec155">B.12.1  Line Breaking</a>
</li><li class="li-toc"><a href="#sec156">B.12.2  Page Breaking</a>
</li></ul>
</li><li class="li-toc"><a href="#sec157">B.13  Lengths, Spaces and Boxes</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec158">B.13.1  Length</a>
</li><li class="li-toc"><a href="#sec159">B.13.2  Space</a>
</li><li class="li-toc"><a href="#sec160">B.13.3  Boxes</a>
</li></ul>
</li><li class="li-toc"><a href="#sec161">B.14  Pictures and Colours</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec162">B.14.1  The <span class="c013">picture</span> environment and the <span class="c013">graphics</span>
Package</a>
</li><li class="li-toc"><a href="#sec163">B.14.2  The <span class="c013">color</span> Package</a>
</li></ul>
</li><li class="li-toc"><a href="#sec166">B.15  Font Selection</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec167">B.15.1  Changing the Type Style</a>
</li><li class="li-toc"><a href="#sec168">B.15.2  Changing the Type Size</a>
</li><li class="li-toc"><a href="#sec169">B.15.3  Special Symbols</a>
</li></ul>
</li><li class="li-toc"><a href="#sec170">B.16  Extra Features</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec171">B.16.1  T<sub>E</sub>X macros</a>
</li><li class="li-toc"><a href="#sec177">B.16.2  Command Definition inside Command Definition</a>
</li><li class="li-toc"><a href="#sec178">B.16.3  Date and time</a>
</li><li class="li-toc"><a href="#fancysection">B.16.4  Fancy sectioning commands</a>
</li><li class="li-toc"><a href="#winfonts">B.16.5  Targeting Windows</a>
</li></ul>
</li><li class="li-toc"><a href="#sec181">B.17  Implemented Packages</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec182">B.17.1  AMS compatibility</a>
</li><li class="li-toc"><a href="#sec183">B.17.2  The <span class="c013">array</span> and <span class="c013">tabularx</span>
packages</a>
</li><li class="li-toc"><a href="#calc">B.17.3  The <span class="c013">calc</span> package</a>
</li><li class="li-toc"><a href="#inputenc">B.17.4  Specifying the document input encoding, the <span class="c013">inputenc</span> package</a>
</li><li class="li-toc"><a href="#sec186">B.17.5  More symbols</a>
</li><li class="li-toc"><a href="#commentpack">B.17.6  The <span class="c013">comment</span> package</a>
</li><li class="li-toc"><a href="#multind">B.17.7  Multiple Indexes with the <span class="c013">index</span> and
<span class="c013">multind</span> packages</a>
</li><li class="li-toc"><a href="#sec189">B.17.8  “Natural” bibliographies, the <span class="c013">natbib</span> package </a>
</li><li class="li-toc"><a href="#sec190">B.17.9  Multiple bibliographies</a>
</li><li class="li-toc"><a href="#sec193">B.17.10  Support for <span class="c013">babel</span></a>
</li><li class="li-toc"><a href="#urlpackage">B.17.11  The <span class="c013">url</span> package</a>
</li><li class="li-toc"><a href="#sec198">B.17.12  Verbatim text: the <span class="c013">moreverb</span> and
<span class="c013">verbatim</span> packages</a>
</li><li class="li-toc"><a href="#listings%3Apackage">B.17.13  Typesetting computer languages: the <span class="c013">listings</span> package</a>
</li><li class="li-toc"><a href="#sec200">B.17.14  (Non-)Multi page tabular material</a>
</li><li class="li-toc"><a href="#mathpartir%3Apackage">B.17.15  Typesetting inference rules: the
<span class="c013">mathpartir</span> package</a>
</li><li class="li-toc"><a href="#sec206">B.17.16  The <span class="c013">ifpdf</span> package</a>
</li><li class="li-toc"><a href="#sec207">B.17.17  Typesetting Thai</a>
</li><li class="li-toc"><a href="#sec208">B.17.18  Hanging paragraphs</a>
</li><li class="li-toc"><a href="#sec209">B.17.19  The <span class="c013">cleveref</span> package</a>
</li><li class="li-toc"><a href="#sec210">B.17.20  Other packages</a>
</li></ul>
</li></ul>
</li><li class="li-toc"><a href="#practical">Part C  Practical information</a>
<ul class="ftoc2"><li class="li-toc">
<a href="#sec212">C.1  Usage</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec213">C.1.1  H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A usage</a>
</li><li class="li-toc"><a href="#sec218">C.1.2  H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A usage</a>
</li><li class="li-toc"><a href="#sec219">C.1.3  <span class="c013">esponja</span> usage</a>
</li><li class="li-toc"><a href="#bibhva">C.1.4  <span class="c013">bibhva</span> usage</a>
</li><li class="li-toc"><a href="#sec223">C.1.5  <span class="c013">imagen</span> usage</a>
</li><li class="li-toc"><a href="#sec224">C.1.6  Invoking <span class="c013">hevea</span>, <span class="c013">hacha</span> and <span class="c013">imagen</span></a>
</li><li class="li-toc"><a href="#makefile">C.1.7  Using <span class="c013">make</span></a>
</li></ul>
</li><li class="li-toc"><a href="#browser">C.2  Browser configuration</a>
</li><li class="li-toc"><a href="#sec227">C.3  Availability</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec228">C.3.1  Internet stuff</a>
</li><li class="li-toc"><a href="#sec229">C.3.2  Law</a>
</li></ul>
</li><li class="li-toc"><a href="#sec230">C.4  Installation</a>
<ul class="ftoc3"><li class="li-toc">
<a href="#sec231">C.4.1  Requirements</a>
</li><li class="li-toc"><a href="#sec232">C.4.2  Principles</a>
</li></ul>
</li><li class="li-toc"><a href="#sec233">C.5  Other L<sup>A</sup>T<sub>E</sub>X to html translators</a>
</li><li class="li-toc"><a href="#sec234">C.6  Acknowledgements</a>
</li><li class="li-toc"><a href="#%40biblio">References</a>
</li><li class="li-toc"><a href="#%40index">Index</a>
</li></ul>
</li></ul><!--CUT END -->
<p>
This document consists in three parts, a tutorial introduction, a
reference manual and some practical information. The latter part
includes a small <a href="#%40index">index</a>.
</p><!--CUT DEF part -->
<!--TOC part id="sec2" Tutorial-->
<table class="center"><tr><td><h1 class="part" id="sec2">Part A<br>
Tutorial</h1></td></tr>
</table><!--SEC END --><p>
<a id="usermanual"></a>
</p><!--CUT DEF section -->
<!--TOC section id="getstarted" How to get started-->
<h2 class="section" id="getstarted">1  How to get started</h2><!--SEC END --><p>
Assume that you have a file, <span class="c013">a.tex</span>, written in L<sup>A</sup>T<sub>E</sub>X, using the
<span class="c013">article</span>, <span class="c013">book</span> or <span class="c013">report</span> style. Then,
translation
is achieved by issuing the command:
</p><pre class="verbatim"># hevea a.tex
</pre><p>Probably, you will get some warnings. If
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not crash, just ignore them for the moment
(Section <a href="#trouble">4</a> explains how to correct errors).</p><p>If everything goes fine, this will produce a new file,
<span class="c013">a.html</span>, which you can visualise through a html browser.</p><p>If you wish to experiment H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A on small L<sup>A</sup>T<sub>E</sub>X source fragments,
then launch H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A without arguments. H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will read its
standard input and print the translation on its standard output.
For instance:
</p><pre class="verbatim"># hevea
$x \in \mathcal{E}$
^D
<span style="font-style:italic">x</span> &#X2208; <span style="color:red"><span style="font-style:italic">E</span></span>
</pre><p>Incidentally, notice that the symbol “∈” translates to the
appropriate numerical character reference and that the calligraphic
letter “<span style="font-style:italic;color:red">E</span>” renders as a red “<span class="c018">E</span>”. You can find some
more elaborate <a href="http://hevea.inria.fr/examples/index.html">examples</a> in
the on-line documentation.</p>
<!--TOC section id="sec4" Style files-->
<h2 class="section" id="sec4">2  Style files</h2><!--SEC END --><p>
L<sup>A</sup>T<sub>E</sub>X style files are files that are not intended to produce output, but
define document layout parameters, commands, environments, etc.</p>
<!--TOC subsection id="sec5" Standard base styles-->
<h3 class="subsection" id="sec5">2.1  Standard base styles</h3><!--SEC END --><p>The base style of a L<sup>A</sup>T<sub>E</sub>X document is the argument to the
<code>\documentclass</code> command (<code>\documentstyle</code> in old style).
Normally, the base style of a document defines the structure and
appearance of the whole document.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A really knows about two L<sup>A</sup>T<sub>E</sub>X base styles,
<span class="c013">article</span> and <span class="c013">book</span>.
Additionally, the <span class="c013">report</span> base style is recognized and
considered equivalent to <span class="c013">book</span> and the
<span class="c013">seminar</span> base style for making slides is recognized and
implemented by small additions on the <span class="c013">article</span> style.</p><p>Base style <em>style</em> is implemented by an H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A specific
style file <em>style</em><code>.hva</code>.
More precisely, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A interprets
<code>\documentclass{</code><em>style</em><code>}</code> by attempting to load
the file <em>style</em><code>.hva</code> (see section <a href="#comline">C.1.1.1</a> on where
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A searches for files).
Thus, at the moment, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A distribution includes the files,
<span class="c013">article.hva</span>, <span class="c013">book.hva</span>, etc.</p>
<!--TOC subsection id="sec6" Other base styles-->
<h3 class="subsection" id="sec6">2.2  Other base styles</h3><!--SEC END --><p><a id="otherbase"></a>
Documents whose base style is not recognized by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can be
processed when the unknown base style is a derivation of a
recognized base style.</p><p>Let us assume that <span class="c013">doc.tex</span> uses an exotic
base style such as <span class="c013">acmconf</span>. Then, typing
<code>hevea doc.tex</code> will yield an error, since
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A cannot find the <span class="c013">acmconf.hva</span> file:
</p><pre class="verbatim"># hevea.opt doc.tex
doc.tex:1: Warning: Cannot find file: acmconf.hva
doc.tex:1: Error while reading LaTeX: No base style
Adios
</pre><p>This situation is avoided by invoking H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A with the known
base style file <span class="c013">article.hva</span> as an extra argument:
</p><pre class="verbatim"># hevea article.hva doc.tex
</pre><p>The extra argument instructs
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to load its <span class="c013">article.hva</span>
style file before processing <span class="c013">doc.tex</span>.
It will then ignore the document base style specified by
<code>\documentclass</code> (or <code>\documentstyle</code>).</p><p>Observe that the fix above works because the <span class="c013">acmconf</span> and
<span class="c013">article</span> base styles look the same to the document
(<em>i.e.</em> they define the same macros).
More generally, most base styles that are neither
<span class="c018">article</span> nor <span class="c018">book</span> are in fact variations
on either two of them.
However, such styles usually provides extra macros.
If users documents use these macros, then users should also instruct
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A about them (see section <a href="#dontknow">4.1</a>).</p><p>Finally, it is important to notice that
renaming a base style file <em>style</em><code>.cls</code> into
<em>style</em><code>.hva</code> will not work in general.
As a matter of fact, base style files are T<sub>E</sub>X and not L<sup>A</sup>T<sub>E</sub>X source and
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will almost surely fail on T<sub>E</sub>X-ish input.</p>
<!--TOC subsection id="sec7" Other style files-->
<h3 class="subsection" id="sec7">2.3  Other style files</h3><!--SEC END --><p>
A L<sup>A</sup>T<sub>E</sub>X document usually loads additional style files, by using
the commands <code>\input</code> or <code>\usepackage</code> or <code>\input</code>.</p>
<!--TOC subsubsection id="sec8" Files loaded with <span class="c013">\input</span>-->
<h4 class="subsubsection" id="sec8">2.3.1  Files loaded with <span class="c013">\input</span></h4><!--SEC END --><p>
Just like L<sup>A</sup>T<sub>E</sub>X, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A reacts to the construct
<code>\input{</code><span class="c018">file</span><code>}</code> by loading the file
<span class="c018">file</span>. (if I got it right, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A even follows T<sub>E</sub>X’s crazy
conventions on <span class="c013">.tex</span> extensions).</p><p>As it is often the case, assume that the document <span class="c013">doc.tex</span> has a
<code>\input{mymacros.tex}</code> instruction in its preamble, where
<span class="c013">mymacros.tex</span> gathers custom definitions.
Hopefully, only a few macros give rise to trouble: macros that performs fine
typesetting or T<sub>E</sub>Xish macros.
Such macros need to be rewritten, using basic L<sup>A</sup>T<sub>E</sub>X
constructs (section <a href="#trouble">4</a> gives examples of macro-rewriting).
The new definitions are best collected in a style file,
<span class="c013">mymacros.hva</span> for instance.
Then, <span class="c013">doc.tex</span> is to be translated by issuing the command:
</p><pre class="verbatim"># hevea mymacros.hva doc.tex
</pre><p>The file <span class="c013">mymacros.hva</span> is processed before
<span class="c013">doc.tex</span> (and thus before <span class="c013">mymacros.tex</span>).
As a consequence of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A behaviour with respect to
definition and redefinition (see section <a href="#usermacro">B.8.1</a>),
the macro definitions in <span class="c013">mymacros.hva</span>
take precedence over the ones in <span class="c013">mymacros.tex</span>, provided
the document original definitions (the ones in
<span class="c013">mymacros.tex</span>) are performed by <code>\newcommand</code>
(or <code>\newenvironment</code>).</p><p>Another situation is when H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A fails to process a whole
style file. Usually, this means that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A crashes on that style
file.
The basic idea is then
to write a <span class="c013">mymacros.hva</span> style file that contains alternative
definitions for all the commands defined in <span class="c013">mymacros.sty</span>.
Then, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A should be instructed
to load <span class="c013">mymacros.hva</span> and not to load <span class="c013">mymacros.tex</span>.
This is done by invoking <span class="c013">hevea</span> as follows:
</p><pre class="verbatim"># hevea mymacros.hva -e mymacros.tex doc.tex
</pre><p>Of course, <span class="c013">mymacros.hva</span> must now contain replacements for
all the useful macros of <span class="c013">mymacro.tex</span>.</p>
<!--TOC subsubsection id="sec9" Files loaded with <span class="c013">\usepackage</span>-->
<h4 class="subsubsection" id="sec9">2.3.2  Files loaded with <span class="c013">\usepackage</span></h4><!--SEC END --><p>
As far as I know, L<sup>A</sup>T<sub>E</sub>X reacts to the construct
<code>\usepackage{</code><span class="c018">name</span><code>}</code> by loading the file
<span class="c018">name</span><span class="c013">.sty</span>.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A reacts in a similar, but different, manner, by
loading the file <span class="c018">name</span><span class="c013">.hva</span>.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A distributions already includes quite a few <span class="c013">.hva</span>
implementations of famous packages (see section <a href="#implemented%3Apackage">B.17</a>).
When a given package (say <span class="c013">zorglub</span>) is not implemented, the
situation may not be as bad as it may seem first.
Hopefully, you are only using a few commands from package
<span class="c013">zorglub</span>, and you feel confident enough to implement
them yourself.
Then, it suffices to put your definitions in file <span class="c013">zorglub.hva</span>
and H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will react to <code>\usepackage{zorglub}</code> by loading
<span class="c013">zorglub.hva</span>.</p><p>See section <a href="#usepackage">B.5.2</a> for the full story on <code>\usepackage</code>.</p>
<!--TOC section id="sec10" A note on style-->
<h2 class="section" id="sec10">3  A note on style</h2><!--SEC END -->
<!--TOC subsection id="sec11" Spacing, Paragraphs-->
<h3 class="subsection" id="sec11">3.1  Spacing, Paragraphs</h3><!--SEC END --><p>
Sequence of spaces normally are translated into one single space.
Newlines in the input document undergo a special treatement.
A newline triggers a special scanning mode that reads all following
spaces and newlines. In case at least one additional newline character
is read, then H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A executes the <code>\par</code> command.
Otherwise, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A outputs a single newline character.
This process approximates T<sub>E</sub>X process for introducting paragraph
breaks and, as a result, empty lines produce paragraph breaks.</p><p>Space after commands with no argument is skipped (as in L<sup>A</sup>T<sub>E</sub>X) —
however this is not true in math mode, as explained in
section <a href="#spacemath">3.2.1</a>.</p><p>The following two subsections describe management of paragraphs and
spaces after command sequences in greater detail.
They can be skipped in first reading.</p>
<!--TOC subsubsection id="spurious:par" Spurious Paragraphs-->
<h4 class="subsubsection" id="spurious:par">3.1.1  Spurious Paragraphs</h4><!--SEC END --><p>
Paragraphs are rendered by the means of <code>p</code> elements.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is a bit simplistic in breaking paragraphs and spurious paragraphs
may be present in the final html document.
Normally, as H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A never outputs <code>p</code> elements whose contents is
made of spaces only, this should not happen very often.
Unfortunately, some commands do not produce any output in L<sup>A</sup>T<sub>E</sub>X,
while they do produce output in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A: those commands
are <code>\label</code>, <code>\index</code> etc.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A translates
<code>\label{</code><span class="c018">name</span><code>}</code> into the anchor
<code><a id="</code><span class="c018">name</span><code>"></a></code>. As a result, the following
source fragment will introduce a spurious paragraph.
</p><pre class="verbatim">This a first paragraph.
\label{label}
This is another paragraph.
</pre><p>Indeed, whe have the following translation:
</p><pre class="verbatim"><p>This a first paragraph.</p>
<p><a id="label"></a></p>
<p>This is another paragraph.</p>
</pre><p>Which your browser renders as follows — with additional borders
emphasizing <code>p</code> elements.
</p><blockquote class="quote">
<p class="c005">This a first paragraph.</p>
<p class="c005"><a id="label"></a></p>
<p class="c005">This is another paragraph.</p>
</blockquote><p>Most of the time, such extra paragraphs remain unnoticed.
Of course, they can be supressed by erasing one of the empty
lines. For instance:
</p><pre class="verbatim">This a first paragraph.
\label{label}
This is another paragraph.
</pre><p>A similar situation occurs when a sectioning command is followed by
<code>\label</code> and a paragraph break:
</p><pre class="verbatim">\section*{A section}\label{section:label}
First paragraph.
</pre><p>Produced html is, after a few cosmetic simplifications:
</p><pre class="verbatim"><h2 class="section">A section</h2>
<p><a id="section:label"></a></p>
<p>First paragraph.</p>
</pre><p>Output is so, because closing the element <code>h2</code> implies re-opening
a new paragraph.
Your browser renders the above html fragment as follows:
</p><blockquote class="quote">
<h2 class="section">A section</h2>
<p class="c005"><a id="section:label"></a></p>
<p class="c005">First paragraph.</p>
</blockquote><p>Here, two possible re-writing of source are:
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c039"><pre class="verbatim">\section*{A\label{section:label} section}
First paragraph.
</pre></td><td class="c039"><pre class="verbatim">\section*{A section}
\label{section:label}First paragraph.
</pre></td></tr>
</table>
</div><p>
In all cases, this amounts to avoiding a paragraph whose contents
consists in a sole <code>\label</code> command.</p><p>Spurious paragraphs are more easily seen by running <span class="c013">hevea</span>
with the command-line option <a id="hevea_default0"></a><span class="c013">-dv</span>, which instructs
<span class="c013">hevea</span> to add border on some of the elements it produces,
including <code>p</code> elements.</p>
<!--TOC subsubsection id="sec13" Spaces after Commands-->
<h4 class="subsubsection" id="sec13">3.1.2  Spaces after Commands</h4><!--SEC END --><p>
<a id="hevea_default1"></a>
Space after commands with no argument is skipped.
Consider the following example:
</p><pre class="verbatim">\newcommand{\open}{(}
\newcommand{\close}{)}
\open text opened by ``\verb+\open+''
and closed by ``\verb+\close+''\close.
</pre><p>We get:
</p><blockquote class="quote">
(text opened by “<code>\open</code>” and closed by
“<code>\close</code>”).
</blockquote><p>
In the output above, the space after <code>\open</code> does not
find its way to the output.</p><p>More generally,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A tries to emulate L<sup>A</sup>T<sub>E</sub>X behaviour in all situations, but
discrepancies probably exist.
Thus, users are invited to make explicit what they want.
This is good practice anyway, because L<sup>A</sup>T<sub>E</sub>X is mysterious
here. Consider the following example, where the <code>\tryspace</code>
macro is first applied and then expansed by hand:
</p><pre class="verbatim">\newcommand{\bfsymbol}{\textbf{symbol}}
\newcommand{\tryspace}[1]{#1 XXX}
Some space: \tryspace{\bfsymbol}\\
No space: \bfsymbol XXX
</pre><p>Spacing is a bit chaotic here,
the space after <span class="c022">symbol</span> remains when <code>#1</code> is substituted for it
by L<sup>A</sup>T<sub>E</sub>X (or H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A).</p><blockquote class="quote">
<table class="c002 cellpading0"><tr><td class="c032">Some space</td><td class="c029"> : </td><td class="c032"><span class="c022">symbol</span> XXX</td></tr>
<tr><td class="c032">No space</td><td class="c029"> : </td><td class="c032"><span class="c022">symbol</span>XXX
</td></tr>
</table></blockquote><p>
Note that, if a space before “XXX” is wanted, then
one should probably write:
</p><pre class="verbatim">\newcommand{\tryspace}[1]{#1{} XXX}
</pre><p>Finally, <a id="hevea_default2"></a>whether the tabulation character is a space or not
is random, so avoid tabs in your source document.</p>
<!--TOC subsection id="sec14" Math mode-->
<h3 class="subsection" id="sec14">3.2  Math mode</h3><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A math mode is not very far from normal text mode, except that
all letters are shown in italics and that space after macros
is echoed.</p><p>However, typesetting math formulas in html rises two difficulties.
First, formulas contain symbols, such as Greek letters; second,
even simple formulas do not follow the simple basic typesetting model of html.</p>
<!--TOC subsubsection id="spacemath" Spacing in math mode-->
<h4 class="subsubsection" id="spacemath">3.2.1  Spacing in math mode</h4><!--SEC END --><p>
<a id="hevea_default3"></a>
By contrast with L<sup>A</sup>T<sub>E</sub>X, spaces from the input are significant in
math mode, this
feature allows users to instruct H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
on how to put space in their formulas.
For instance, <code>\alpha\rightarrow\beta</code> is typeset without spaces between
symbols, whereas <code>\alpha \rightarrow \beta</code> produces these spaces.
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="c002 cellpading0"><tr><td class="c032"><code>\alpha\rightarrow\beta</code></td><td class="c029"> : </td><td class="c032">α→β</td></tr>
<tr><td class="c032"><code>\alpha \rightarrow \beta</code></td><td class="c029"> : </td><td class="c032">α → β</td></tr>
</table></td></tr>
</table><p>
Note that L<sup>A</sup>T<sub>E</sub>X ignores spaces in math mode, so that users can
freely adjust H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output without changing anything to L<sup>A</sup>T<sub>E</sub>X
output.</p>
<!--TOC subsubsection id="sec16" Symbols-->
<h4 class="subsubsection" id="sec16">3.2.2  Symbols</h4><!--SEC END --><p><a id="symbols"></a>
</p><blockquote class="figure"><div class="center"><hr class="c049"></div>
<div class="caption"><table class="c002 cellpading0"><tr><td class="c039">Figure 1: <a id="symbol:fig"></a>Some symbols</td></tr>
</table></div>
<div class="center">
<table class="c002 cellpading0"><tr><td class="c033"><span class="c013">\in</span>:  </td><td class="c032"><span class="c016">∈</span></td><td class="c029">    </td><td class="c033"><span class="c013">\notin</span>:  </td><td class="c032"><span class="c016">∉</span></td></tr>
<tr><td class="c033"><span class="c013">\int</span>:  </td><td class="c032"><span class="c016">∫</span></td><td class="c029">    </td><td class="c033"><span class="c013">\prod</span>:  </td><td class="c032"><span class="c016">∏</span></td></tr>
<tr><td class="c033"><span class="c013">\preceq</span>:  </td><td class="c032"><span class="c016">≼</span></td><td class="c029">    </td><td class="c033"><span class="c013">\prec</span>:  </td><td class="c032"><span class="c016">≺</span></td></tr>
<tr><td class="c033"><span class="c013">\leq</span>:  </td><td class="c032"><span class="c016">≤</span></td><td class="c029">    </td><td class="c033"><span class="c013">\geq</span>:  </td><td class="c032"><span class="c016">≥</span></td></tr>
<tr><td class="c033"><span class="c013">\cup</span>:  </td><td class="c032"><span class="c016">∪</span></td><td class="c029">    </td><td class="c033"><span class="c013">\cap</span>:  </td><td class="c032"><span class="c016">∩</span></td></tr>
<tr><td class="c033"><span class="c013">\supset</span>:  </td><td class="c032"><span class="c016">⊃</span></td><td class="c029">    </td><td class="c033"><span class="c013">\subset</span>:  </td><td class="c032"><span class="c016">⊂</span></td></tr>
<tr><td class="c033"><span class="c013">\supseteq</span>:  </td><td class="c032"><span class="c016">⊇</span></td><td class="c029">    </td><td class="c033"><span class="c013">\subseteq</span>:  </td><td class="c032"><span class="c016">⊆</span></td></tr>
</table>
</div>
<div class="center"><hr class="c049"></div></blockquote><p>
With respect to previous versions of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A since the begining, the
treatment of symbols has significantly evolved. Outputting symbols is
now performed by using Unicode character references, an option that
much more complies whith standards than the previous option of
selecting a “symbol” font. Observe that this choice is now
possible, because more and more browsers correctly display such
references. See Figure <a href="#symbol%3Afig">1</a> for a few such symbols.</p><p>However, this means that ancient or purposely limited browsers (such as
text-oriented browsers) cannot display maths, as translated by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
For authors that insist on avoiding symbols that cannot be shown
by any browser, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A offers a degraded mode that outputs text
in place of symbols.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A operates in this mode when given the <a id="hevea_default4"></a><span class="c013">-textsymbols</span>
command-line option. Replacement text is in English.
For instance. the “∈” symbol is replace by “in”.
This is far from being satisfactory, but degraded mode may be
appropriate for documents than contain few symbols.</p>
<!--TOC subsubsection id="sec17" Displays-->
<h4 class="subsubsection" id="sec17">3.2.3  Displays</h4><!--SEC END --><p>
Apart from containing symbols, formulas specify strong typesetting
constraints: sub-elements must be combined together following patterns
that departs from normal text typesetting. For instance, fractions
numerators and denominators must be placed one above the other.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A handles such constraints in display mode only.</p><p>The main two operating modes of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A are <em>text</em> mode and
<em>display</em> mode.
Text mode is the mode for typesetting normal text,
when in this mode, text items are echoed one following the other and
paragraph breaks are just blank lines, both in input and output.
The so called <em>displayed-paragraph environments</em> of L<sup>A</sup>T<sub>E</sub>X (such as
<span class="c013">center</span> or <span class="c013">quote</span>) are rendered by html block-level
elements (such as <span class="c013">div</span> or <span class="c013">blockquote</span>).
Rendering is correct becauses both L<sup>A</sup>T<sub>E</sub>X displayed environments and
html block-level elements start a new line.
Conversly, since opening a html block-level elements means starting
a new line, any text that sould appear inside a paragraph must be
translated using only html text-level elements.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A chooses to translate in-text formulas that way.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A display mode allows more control on text placement, since
entering display mode means opening
a html <code>table</code> element and that tables allow to control the
relative position of their sub-elements.
Displays come in two flavor, horizontal displays and vertical
displays.
An horizontal display is a one-row table, while a vertical display is
a one-column table. These tables holds display sub-elements, displays
sub-elements being centered vertically in horizontal display mode and
horizontally in vertical display mode.</p><p>Display mode is first opened by opening a <code>displaymath</code> environment
(e.g. by <code>$$</code>
or <code>\[</code>).
Then, sub-displays are opened by L<sup>A</sup>T<sub>E</sub>X constructs which require
them.
For instance, a displayed fraction (<code>\frac</code>) opens a vertical display.</p><p>The distinction between text and display modes clearly appears while
typesetting math formulas.
An in-text formula such as
<code>$\int_1^2 xdx = \frac{3}{2}$</code> appears as:
∫<sub>1</sub><sup>2</sup> <span class="c018">xdx</span> =3/2,
while the same formula has a better aspect in display mode:
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c017">∫</span></td><td class="dcell"><table class="display"><tr><td class="dcell c030">2</td></tr>
<tr><td class="dcell c030"><br>
<br>
</td></tr>
<tr><td class="dcell c030">1</td></tr>
</table></td><td class="dcell"><span class="c018">xdx</span> = </td><td class="dcell"><table class="display"><tr><td class="dcell c027">3</td></tr>
<tr><td class="hbar"></td></tr>
<tr><td class="dcell c027">2</td></tr>
</table></td></tr>
</table><p>
As a consequence, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is more powerful in display mode and
formulas should be displayed as soon as they get a bit complicated.
This rule is also true in L<sup>A</sup>T<sub>E</sub>X but it is more strict in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A,
since html capabilities to typeset formulas inside text are quite
poor.
In particular, it is not possible to get in-text “real” fractions or
in-text limit-like subscripts.</p><p>Users should remember that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is not T<sub>E</sub>X or L<sup>A</sup>T<sub>E</sub>X and that
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A author neither is D. E. Knuth nor L. Lamport.
Thus, some formulas may be rendered poorly.
For instance, two fractions with different denominator and numerator
height look strange.
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="display"><tr><td class="dcell c027">1</td></tr>
<tr><td class="hbar"></td></tr>
<tr><td class="dcell c027"><table class="display"><tr class="c035"><td class="dcell"><table class="display"><tr><td class="dcell c027"><span class="c018">N</span></td></tr>
<tr><td class="dcell c027"><span class="c017">∑</span></td></tr>
<tr><td class="dcell c027"><span class="c018">i</span>=0</td></tr>
</table></td><td class="dcell"><span class="c018">U</span><sub><span class="c018">i</span></sub></td></tr>
</table></td></tr>
</table></td><td class="dcell"> = </td><td class="dcell"><table class="display"><tr><td class="dcell c027"><table class="display"><tr class="c035"><td class="dcell"><table class="display"><tr><td class="dcell c027"><span class="c018">N</span></td></tr>
<tr><td class="dcell c027"><span class="c017">∑</span></td></tr>
<tr><td class="dcell c027"><span class="c018">i</span>=0</td></tr>
</table></td><td class="dcell"><span class="c018">U</span><sub><span class="c018">i</span></sub></td></tr>
</table></td></tr>
<tr><td class="hbar"></td></tr>
<tr><td class="dcell c027">1</td></tr>
</table></td></tr>
</table><p>
The reason is that vertical displays in an horizontal display are
html tables
that always get centered in the vertical direction.
Such a crude model cannot faithfully emulate any T<sub>E</sub>X box placement.</p><p>Users can get an idea on how H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A combines elements in display mode
by giving the <a id="hevea_default5"></a><span class="c013">-dv</span> command-line option, which
instructs H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to add
borders to the <code>table</code> elements introduced by displays.</p>
<!--TOC subsubsection id="sec18" Arrays and display mode-->
<h4 class="subsubsection" id="sec18">3.2.4  Arrays and display mode</h4><!--SEC END --><p>By contrast with formulas, which H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A attempts to render with
text-level elements only when they appear inside paragraphs, L<sup>A</sup>T<sub>E</sub>X arrays
always translate to the
block-level element <code>table</code>, thereby introducing non-desired line
breaks before and after in-text arrays.
As a consequence, in-text arrays yield an acceptable output, only while
alone in a paragraph.</p><p>
Consider the following source:
</p><pre class="verbatim">This is a small array:
\begin{tabular}{|cc|}
\hline item-1 & item-2 \\
\hline\end{tabular}. Next sentence.
</pre><p>We get:
</p><blockquote class="quote">
This is a small array:
<table class="c001 cellpadding1" border=1><tr><td class="c028">item-1</td><td class="c028">item-2
</td></tr>
</table>. Next sentence.
</blockquote><p>However, since in some sense, all html tables are displayed, the
<code>array</code> and <code>tabular</code> environments implicitly open display
mode, thus allowing a satisfactory typesetting of formulas in
arrays. More precisely, array elements whose column format
specification is <code>l</code>, <code>c</code> or <code>r</code> are typeset in display
mode (see section <a href="#arraydef">B.10.2</a>).</p>
<!--TOC subsection id="sec19" Warnings-->
<h3 class="subsection" id="sec19">3.3  Warnings</h3><!--SEC END --><p>
When H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A thinks it cannot translate a symbol or construct
properly, it issues a warning. This draws user attention onto a
potential problem. However, rendering may be correct.</p><p>
In the following (silly) example, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A gets nervous because of
the complicated length given as argument to <code>\hspace</code>:
</p><pre class="verbatim">\newlength{\mylength}\setlength{\mylength}{5pt}
\begin{tabular}{c@{\hspace{\mylength}}c}
Before & After
\end{tabular}
</pre><p>Running H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A on this input produces a warning:
</p><pre class="verbatim"># hevea manual.tex
...
manual.tex:507: Warning: \hspace with arg '\mylength'
...
</pre><p>However the final rendering is correct:
</p><blockquote class="quote">
<table class="c002 cellpading0"><tr><td class="c029">Before</td><td class="c029"></td><td class="c029">After
</td></tr>
</table>
</blockquote><p>Note that all warnings can be suppressed with the <code>-s</code> (silent)
option.
When a warning reveals a real problem, it can often be cured by
writing a specific macro. The next two sections introduce H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
macros, then section <a href="#trouble">4</a> describes how to proceed with
greater detail.</p>
<!--TOC subsection id="sec20" Commands-->
<h3 class="subsection" id="sec20">3.4  Commands</h3><!--SEC END --><p>
Just like L<sup>A</sup>T<sub>E</sub>X, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can be seen as a macro language, macros
are rewritten until no more expansion is possible. Then, either some
characters (such as letters, integers…) are outputed or some
internal operation (such as changing font attributes, or arranging
text items in a certain manner) are performed.</p><p>This scheme favors easy extension of program capabilities
by users. However, predicting program behaviour and correcting errors
may prove difficult, since final output or errors
may occur after several levels of macro expansion.
As a consequence, users can tailor H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to their needs, but it
remains a subtle task.
Nevertheless, happy L<sup>A</sup>T<sub>E</sub>X users should enjoy customizing
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, since this is done by writing L<sup>A</sup>T<sub>E</sub>X code.</p>
<!--TOC subsection id="sec21" Style choices-->
<h3 class="subsection" id="sec21">3.5  Style choices</h3><!--SEC END --><p><a id="stylechoice"></a>
L<sup>A</sup>T<sub>E</sub>X and html differ in many aspects. For instance, L<sup>A</sup>T<sub>E</sub>X allows
fine control over text placement, whereas
html does not.
More symbols and font attributes are available in L<sup>A</sup>T<sub>E</sub>X than in
html. Conversely, html has font attributes, such as color, which
standard L<sup>A</sup>T<sub>E</sub>X has not.</p><p>Therefore, there are many situations where H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A just cannot
render the visual effect of L<sup>A</sup>T<sub>E</sub>X constructions. Here some choices
have to be made. For instance, calligraphic letters (<code>\mathcal</code>)
are rendered in red.</p><p>If you are not satisfied with H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A rendering of text style
declarations, then you
can choose your own, by redefining the <code>\cal</code>
macros, using <code>\renewcommand</code>, the macro redefinition operator of
L<sup>A</sup>T<sub>E</sub>X. The key point is that you need not worry about H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
internals: just redefine the old-L<sup>A</sup>T<sub>E</sub>X style text-style
declarations (<em>i.e.</em> <code>\it</code>, <code>\sc</code>, etc.) and everything should
get fine:
</p><pre class="verbatim">\renewcommand{\sc}{\Huge}
\renewcommand{\cal}{\em}
</pre><p>(See sections <a href="#trouble">4</a> and <a href="#both">5</a> on how to make such
changes while leaving your file processable by L<sup>A</sup>T<sub>E</sub>X, and
section <a href="#customize-style">10.2</a> for a more thorough descripton of
customizing type styles).</p><p>
With such redefinitions, we get:
</p><blockquote class="quote">
This is <span class="c017"><span style="font-size:150%">small caps</span></span> and this is <span class="c018"><em>CALLIGRAPHIC LETTERS</em></span>
</blockquote><p>Note that many of L<sup>A</sup>T<sub>E</sub>X commands and environments are defined in the
<span class="c013">hevea.hva</span> file that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A loads before processing any
input.
These constructs are written using L<sup>A</sup>T<sub>E</sub>X source code, in the end they
invoke H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A internal commands.</p><p>Other L<sup>A</sup>T<sub>E</sub>X constructs, such as
L<sup>A</sup>T<sub>E</sub>X key constructs or H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A internal commands (see section <a href="#internal">8.3</a>),
that require special processing are defined
in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A source code.
However, the vast majority of these definitions can be overridden by a
redefinition.
This may prove useless, since there is little point in
redefining core constructs such as <code>\newcommand</code> for instance.</p>
<!--TOC section id="sec22" How to detect and correct errors-->
<h2 class="section" id="sec22">4  How to detect and correct errors</h2><!--SEC END --><p><a id="trouble"></a></p><p>Most of the problems that occur during the translation of a given
L<sup>A</sup>T<sub>E</sub>X file (say <code>trouble.tex</code>) can be detected and solved at
the macro-level. That is, most problems induce a macro-related warning
and can be solved by writing a few
macros. The best place for these macros is an user style file (say
<span class="c013">trouble.hva</span>) given as
argument to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
</p><pre class="verbatim"># hevea trouble.hva trouble.tex
</pre><p>By doing so, the macros written specially for H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A are not
seen by L<sup>A</sup>T<sub>E</sub>X. Even better, <code>trouble.tex</code> is not changed
at all.</p><p>A worth-mentiong alternative is inserting <code>\usepackage{trouble}</code>
in the document preamble. Then, given H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A semantics for
<code>\usepackage</code> (see Section <a href="#usepackage">B.5.2</a>),
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A-specific commands should be placed in
the file “<span class="c013">trouble.hva</span>” file, while L<sup>A</sup>T<sub>E</sub>X-specific commands
should be placed in teh file “<span class="c013">trouble.sty</span>”.</p><p>Of course, adapting a document to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A processing
will be easier if the L<sup>A</sup>T<sub>E</sub>X source is written in a
generic style, using macros.
Note that this style is recommended anyway, since it facilitates
document maintenance.</p>
<!--TOC subsection id="sec23" H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not know a macro-->
<h3 class="subsection" id="sec23">4.1  H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not know a macro</h3><!--SEC END --><p><a id="dontknow"></a>
Consider the following L<sup>A</sup>T<sub>E</sub>X source excerpt:
</p><pre class="verbatim">You can \raisebox{.6ex}{\em raise} text.
</pre><p>L<sup>A</sup>T<sub>E</sub>X typesets this as follows:
</p><blockquote class="quote">
<img src="manual001.png">
</blockquote><p>Since H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not know about <code>\raisebox</code>,
it incorrectly processes this input. More precisely,
it first prints a warning message:
</p><pre class="verbatim">trouble.tex:34: Unknown macro: \raisebox
</pre><p>Then, it goes on by translating the arguments of <code>\raisebox</code> as if
they were normal text. As a
consequence some <code>.6ex</code> is finally found in the html output:
</p><blockquote class="quote">
You can .6ex<em>raise</em> text.
</blockquote><p>To correct this, you should provide a macro that has more or less the effect of
<code>\raisebox</code>. It is impossible to write a generic
<code>\raisebox</code> macro for H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, because of html limitations.
However, in this case, the effect
of <code>\raisebox</code> is to raise the box <em>a little</em>.
Thus, the first, numerical, argument to <code>\raisebox</code> can be
ignored in a private <code>\raisebox</code> macro defined in <span class="c013">trouble.hva</span>:
</p><pre class="verbatim">\newcommand{\raisebox}[2]{$^{\mbox{#2}}$}
</pre><p>Now, translating the document yields:
</p><blockquote class="quote">
You can <sup><em>raise</em></sup> text a little.
</blockquote><p>Of course, this will work only when all <code>\raisebox</code> commands in
the document raise text a little. Consider, the following
example, where text
is both raised a lowered a little:
</p><pre class="verbatim">You can \raisebox{.6ex}{\em raise}
or \raisebox{-.6ex}{\em lower} text.
</pre><p>Which L<sup>A</sup>T<sub>E</sub>X renders as follows:
</p><blockquote class="quote">
<img src="manual002.png">
</blockquote><p>
Whereas, with the above definition of <code>\raisebox</code>, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A produces:
</p><blockquote class="quote">
You can <sup><em>raise</em></sup>
or <sup><em>lower</em></sup> text.
</blockquote><p>A solution is to add a new macro definition in the <code>trouble.hva</code> file:
</p><pre class="verbatim">\newcommand{\lowerbox}[2]{$_{\mbox{#2}}$}
</pre><p>Then, <code>trouble.tex</code> itself has to be modified a little.
</p><pre class="verbatim">You can \raisebox{.6ex}{\em raise}
or \lowerbox{-.6ex}{\em lower} text.
</pre><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A now produces a satisfying output:
</p><blockquote class="quote">
You can <sup><em>raise</em></sup>
or <sub><em>lower</em></sub> text.
</blockquote><p>Note that, for the document to remain L<sup>A</sup>T<sub>E</sub>X-processable,
it should also contain the following definition for
<code>\lowerbox</code>:
</p><pre class="verbatim">\newcommand{\lowerbox}[2]{\raisebox{#1}{#2}}
</pre><p>This definition can safely be placed anywhere in <span class="c013">trouble.tex</span>,
since by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A semantics for <code>\newcommand</code> (see
section <a href="#usermacro">B.8.1</a>)
the new definition will not overwrite the old one.</p>
<!--TOC subsection id="sec24" H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A incorrectly interprets a macro-->
<h3 class="subsection" id="sec24">4.2  H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A incorrectly interprets a macro</h3><!--SEC END --><p><a id="blob"></a></p><p>Sometimes H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A knows about a macro, but the produced html
does not look good when seen through a browser.
This kind of errors is detected while visually checking the
output.
However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does its best to issue warnings when such situations
are likely to occur.</p><p>Consider, for instance, this definition of <code>\blob</code> as a small
black square.
</p><pre class="verbatim">\newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
\blob\ Blob \blob
</pre><p>Which L<sup>A</sup>T<sub>E</sub>X typesets as follows:
</p><blockquote class="quote">
<img src="manual003.png"></blockquote><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A always translates <code>\rule</code> as <code><hr></code>, ignoring size
arguments.
Hence, it produces the following, wrong, output:
</p><blockquote class="quote">
<hr style="height:2"> Blob <hr style="height:2">
</blockquote><p>We may not be particularily commited to a square blob.
In that case, other small symbols would perfectly do the job
of <code>\blob</code>, such as a bullet (<code>\bullet</code>).
Thus, you may choose to give <code>\blob</code> a definition in
<code>trouble.hva</code>:
</p><pre class="verbatim">\newcommand{\blob}{\bullet}
</pre><p>This new definition yields the following, more satisfying output:
</p><blockquote class="quote">• Blob •
</blockquote><p><a id="square:blob"></a>
<a id="hevea_default6"></a>In case we do want a square blob, there are two alternatives.
We can have L<sup>A</sup>T<sub>E</sub>X typeset some subparts of
the document and then to include them as images, section <a href="#imagen">6</a>
explains how to proceed.
We can also find a square blob somewhere in the variety of Unicode
(or do I mean ISO 10646?) characters,
and define <code>\blob</code> as a numerical
character reference. Here, the character <span class="c013">U+02588</span>
seems ok.
</p><pre class="verbatim">\newcommand{\blob}{\@print@u{X2588}}
</pre><blockquote class="quote">█ Blob █
</blockquote><p>
However, beware that not all browsers display all of Unicode…</p>
<!--TOC subsection id="sec25" H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A crashes-->
<h3 class="subsection" id="sec25">4.3  H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A crashes</h3><!--SEC END --><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A failure may have many causes, including a bug.
However, it may also stem from a wrong L<sup>A</sup>T<sub>E</sub>X input.
Thus, this section is to be read before reporting a bug…</p>
<!--TOC subsubsection id="sec26" Simple cases: L<sup>A</sup>T<sub>E</sub>X also crashes-->
<h4 class="subsubsection" id="sec26">4.3.1  Simple cases: L<sup>A</sup>T<sub>E</sub>X also crashes</h4><!--SEC END --><p>
In the following source, environments are not properly balanced:
</p><pre class="verbatim">\begin{flushright}
\begin{quote}
This is right-flushed quoted text.
\end{flushright}
\end{quote}
</pre><p>Such a source will make both L<sup>A</sup>T<sub>E</sub>X and H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A choke.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A issues the following error message that shows the L<sup>A</sup>T<sub>E</sub>X
environment that is not closed properly:
</p><pre class="verbatim">./trouble.tex:6: Environment nesting error: html: 'DIV' closes 'BLOCKQUOTE'
./trouble.tex:4: Latex environment 'quote' is pending
Adios
</pre><p>Thus, when H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A crashes, it is a good idea to check that the
input is correct by running L<sup>A</sup>T<sub>E</sub>X on it.</p>
<!--TOC subsubsection id="sec27" Complicated cases-->
<h4 class="subsubsection" id="sec27">4.3.2  Complicated cases</h4><!--SEC END --><p>Unfortunately, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A may crash on input that does not affect
L<sup>A</sup>T<sub>E</sub>X.
Such errors usually relate to environment or group nesting.</p><p>Consider for instance the following “optimized” version of a
<code>quoteright</code> environment:
</p><pre class="verbatim">\newenvironment{quoteright}{\quote\flushright}{\endquote}
\begin{quoteright}
This a right-flushed quotation
\end{quoteright}
</pre><p>The <code>\quote</code> and <code>\flushright</code> constructs
are intended to replace
<code>\begin{quote}</code> and <code>\begin{flushright}</code>,
while <code>\endquote</code> stands for <code>\end{quote}</code>.
Note that the closing <code>\endflushright</code>
is omitted, since it does nothing.
L<sup>A</sup>T<sub>E</sub>X accepts such an input and produces a right-flushed quotation.</p><p>However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A usually translates L<sup>A</sup>T<sub>E</sub>X environments to html
block-level elements and it <em>requires</em>
those elements to be nested properly.
Here, <code>\quote</code> translates to <code><blockquote></code>,
<code>\flushright</code> translates to <code><div class="flushright"></code> and
<code>\endquote</code> translates to <code></blockquote></code>.
At that point, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A refuses to generate obviously
non-correct html and it crashes:
</p><pre class="verbatim">Giving up command: \@close
Giving up command: \endquote
Giving up command: \endquoteright
Giving up command: \end
./trouble.tex:7: Environment nesting error: html: 'BLOCKQUOTE' closes 'DIV'
./trouble.tex:5: Latex environment 'quoteright' is pending
Adios
</pre><p>Also notice that the error message above includes a backtrace showing
the call-chain of commands.</p><p>In this case, the solution is easy: environments must be opened and
closed consistently. L<sup>A</sup>T<sub>E</sub>X style being recommended, one should write:
</p><pre class="verbatim">\newenvironment{quoteright}
{\begin{quote}\begin{flushright}}
{\end{flushright}\end{quote}}
</pre><p>And we get:
</p><blockquote class="quote">
<blockquote class="quote"><div class="flushright">
This is a right-flushed quotation
</div></blockquote>
</blockquote><p>Unclosed L<sup>A</sup>T<sub>E</sub>X groups (<code>{</code>…) are another source
of nuisance to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
Consider the following <span class="c013">horreur.tex</span> file:
</p><pre class="verbatim">\documentclass{article}
\begin{document}
In this sentence, a group is opened now {\em and never closed.
\end{document}
</pre><p>L<sup>A</sup>T<sub>E</sub>X accepts this file, although it produces a warning:
</p><pre class="verbatim"># latex horreur.tex
This is TeX, Version 3.14159 (Web2C 7.2)
...
(\end occurred inside a group at level 1)
Output written on horreur.dvi (1 page, 280 bytes).
</pre><p>By contrast, running H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A on <span class="c013">horreur.tex</span> yields a fatal error:
</p><pre class="verbatim"># hevea horreur.tex
Giving up command: \@raise@enddocument
Giving up command: \enddocument
Giving up command: \end
./horreur.tex:4: Environment nesting error: Latex env error: 'document' closes ''
./horreur.tex:3: Latex environment '' is pending
Adios
</pre><p>Thus, users should close opening braces where it belongs.
Note that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A error message “<span class="c013">Latex environment
’</span><span class="c018">env</span><span class="c013">’ is pending</span>” helps a lot in locating
the brace that hurts.</p>
<!--TOC subsubsection id="sec28" Desperate cases-->
<h4 class="subsubsection" id="sec28">4.3.3  Desperate cases</h4><!--SEC END --><p>If H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A crashes on L<sup>A</sup>T<sub>E</sub>X source (not on T<sub>E</sub>X source),
then you may have discovered a bug, or this manual is not as complete
as it should.
In any case, please report to <a href="mailto:Luc.Maranget@inria.fr">Luc.Maranget@inria.fr</a>.</p><p>To be useful, your bug report should include L<sup>A</sup>T<sub>E</sub>X code
that triggers the bug (the shorter, the better) and mention
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A version number.</p>
<!--TOC section id="sec29" Making H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and L<sup>A</sup>T<sub>E</sub>X both happy-->
<h2 class="section" id="sec29">5  Making H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and L<sup>A</sup>T<sub>E</sub>X both happy</h2><!--SEC END --><p>
<a id="both"></a>
A satisfactory translation from L<sup>A</sup>T<sub>E</sub>X to html often requires
giving instructions to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
Typically, these instructions are macro definitions and
these instructions should not be seen by L<sup>A</sup>T<sub>E</sub>X.
Conversely, some source that L<sup>A</sup>T<sub>E</sub>X needs should not be processed
by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
Basically, there are three ways to make input vary according to the
processor, file loading, the <span class="c013">hevea</span> package
and comments.</p>
<!--TOC subsection id="sec30" File loading-->
<h3 class="subsection" id="sec30">5.1  File loading</h3><!--SEC END --><p><a id="fileloading"></a></p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and L<sup>A</sup>T<sub>E</sub>X treat files differently. Here is a summary of the main
differences:</p><ul class="itemize"><li class="li-itemize">
L<sup>A</sup>T<sub>E</sub>X and H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A both load files given as arguments to
<code>\input</code>, however when given the option <code>-e</code> <em>filename</em>,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not load <em>filename</em>.
</li><li class="li-itemize">H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A loads all files given as command-line arguments.
</li><li class="li-itemize">Both L<sup>A</sup>T<sub>E</sub>X and H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A load style files given as optional
arguments to
<code>\documentstyle</code> and as arguments to <code>\usepackage</code>,
but the files are searched by following different methods and
considering different file extensions.
</li></ul><p>As a consequence, for having a file <em>latexonly</em> loaded by
L<sup>A</sup>T<sub>E</sub>X only, it suffices
to use <code>\input{</code><em>latexonly</em><code>}</code>
in the source and to invoke H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A as follows:
</p><div class="flushleft">
<code># hevea</code> <span class="c013">-e</span> <em>latexonly</em>…</div><p><a id="heveaonly"></a>Having <em>heveaonly</em> loaded by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A only is more
simple: it suffices to invoke H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A as follows:
</p><div class="flushleft">
<code># hevea</code> <em>heveaonly</em>…</div><p>Finally, if one has an H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A equivalent <span class="c018">style</span><span class="c013">.hva</span>
for a L<sup>A</sup>T<sub>E</sub>X style file <span class="c018">style</span><span class="c013">.sty</span>,
then one should load the file as follows:
</p><div class="flushleft">
<code>\usepackage{</code><span class="c018">style</span><code>}</code>
</div><p>
This will result in, L<sup>A</sup>T<sub>E</sub>X loading <span class="c018">style</span><span class="c013">.sty</span>,
while H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A loads <span class="c018">style</span><span class="c013">.hva</span>.
As H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will not fail in case <span class="c018">style</span><span class="c013">.hva</span> does not
exist, this is another method for having a style file loaded by
L<sup>A</sup>T<sub>E</sub>X only.</p><p>Writing an H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A-specific file <span class="c018">file</span><span class="c013">.hva</span>
is the method of choice for supplying command definitions
to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A only. Users can then be sure that these definitions are
not seen by L<sup>A</sup>T<sub>E</sub>X and will not get echoed to the <span class="c018">image</span>
file (see section <a href="#imagen">6</a>).</p><p>The file <span class="c018">file</span><span class="c013">.hva</span> can be loaded by either
supplying the command-line argument
<span class="c018">file</span><span class="c013">.hva</span>, or by
<code>\usepackage{</code><span class="c018">file</span><code>}</code> from inside the document.
Which method is better depends
on whether you choose to override or to replace the document
definition.
In the command-line case,
definitions from <span class="c018">file</span><span class="c013">.hva</span> are processed before the
ones from the document and will override them, provided
the document definitions are made using <code>\newcommand</code> (or
<code>\newenvironment</code>).
In the <code>\usepackage</code> case, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A loads <span class="c018">file</span><span class="c013">.hva</span>
at the place where L<sup>A</sup>T<sub>E</sub>X loads <span class="c018">file</span><span class="c013">.sty</span>, hence
the definitions from <span class="c018">file</span><span class="c013">.hva</span> replace
the definitions from <span class="c018">file</span><span class="c013">.sty</span> in the strict sense.</p>
<!--TOC subsection id="heveastyle" The <span class="c013">hevea</span> package-->
<h3 class="subsection" id="heveastyle">5.2  The <span class="c013">hevea</span> package</h3><!--SEC END --><p>
The <span class="c013">hevea.sty</span> style file is intended to be loaded by L<sup>A</sup>T<sub>E</sub>X
and not by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
It provides L<sup>A</sup>T<sub>E</sub>X with means to ignore or process some parts of the
document.
Note that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A copes with the constructs defined in
the <span class="c013">hevea.sty</span> file by default.
It is important to notice that the <span class="c013">hevea.sty</span> style file from
the distribution is a <em>package</em> in L<sup>A</sup>T<sub>E</sub>X 2є terms and that it
is not compatible with old L<sup>A</sup>T<sub>E</sub>X. Moreover, the <span class="c013">hevea</span>
package loads the <span class="c013">comment</span> package which must be present.
Also notice that, for compatibility,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A reacts to
<code>\usepackage{hevea}</code> by loading its own version
of the <span class="c013">comment</span> package (Section <a href="#commentpack">B.17.6</a>).</p>
<!--TOC subsubsection id="sec32" Environments for selecting a translator-->
<h4 class="subsubsection" id="sec32">5.2.1  Environments for selecting a translator</h4><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and L<sup>A</sup>T<sub>E</sub>X perform the following actions on source inside
the <code>latexonly</code>, <code>verblatex</code>, <code>htmlonly</code>, <code>rawhtml</code>,
<code>toimage</code> and <code>verbimage</code> environments:
<a id="hevea_default7"></a>
<a id="hevea_default8"></a>
<a id="hevea_default9"></a>
<a id="hevea_default10"></a>
<a id="hevea_default11"></a>
<a id="hevea_default12"></a>
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="hbar" colspan=5></td></tr>
<tr><td class="c041">environment</td><td class="c029"> </td><td class="c029" colspan=2>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A</td><td class="c029">L<sup>A</sup>T<sub>E</sub>X
</td></tr>
<tr><td class="hbar" colspan=5></td></tr>
<tr><td class="c041"><code>latexonly</code></td><td class="c029"> </td><td class="c039">ignore, <code>\end{</code><span class="c018">env</span><code>}</code>
constructs are processed (see section <a href="#why">5.2.2</a>)</td><td class="c029">  </td><td class="c041">process </td></tr>
<tr><td class="c041"><code>verblatex</code></td><td class="c029"> </td><td class="c039">ignore</td><td class="c029">  </td><td class="c041">process </td></tr>
<tr><td class="c041"><code>htmlonly</code></td><td class="c029"> </td><td class="c039">process</td><td class="c029">  </td><td class="c041">ignore </td></tr>
<tr><td class="c041"><code>rawhtml</code></td><td class="c029"> </td><td class="c039">echo verbatim (see section <a href="#rawhtml">8.4</a>)</td><td class="c029">  </td><td class="c041">ignore</td></tr>
<tr><td class="c041"><code>toimage</code></td><td class="c029"> </td><td class="c039">send to the <em>image</em> file, <code>\end{</code><span class="c018">env</span><code>}</code>
constructs and macro characters are processed (see section <a href="#imagen">6</a>)</td><td class="c029">  </td><td class="c041">process</td></tr>
<tr><td class="c041"><code>verbimage</code></td><td class="c029"> </td><td class="c039">send to the <em>image</em> file (see section <a href="#imagen">6</a>)</td><td class="c029">  </td><td class="c041">process</td></tr>
<tr><td class="hbar" colspan=5></td></tr>
</table>
</div><p>As an example, this is how some text can be typeset in purple by
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and left alone by L<sup>A</sup>T<sub>E</sub>X:
</p><pre class="verbatim">We get:
\begin{htmlonly}%
\purple purple rain, purple rain%
\end{htmlonly}
\begin{latexonly}%
purple rain, purple rain%
\end{latexonly}%
\ldots
</pre><p>We get:
<span class="c010">purple rain, purple rain</span>
…</p><p>It is impossible to avoid the spurious space in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output
for the source above.
This extra spaces comes from the newline character that follows
<code>\end{htmlonly}</code>. Namely this
construct must appear in a line of its own for
L<sup>A</sup>T<sub>E</sub>X to recognize it. Anyway, better control over spaces
can be achieved
by using the <span class="c013">hevea</span> boolean register
or comments, see sections <a href="#heveabool">5.2.3</a>
and <a href="#comments">5.3</a>.</p><p>Also note that environments define a scope and that style changes
(and non-global definitions) are local to them. For instance, in the
example above, “…” appears in black in html output.
However, as an exception, the environments <span class="c013">image</span>
and <span class="c013">verbimage</span> do not create scope.
It takes a little practice of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to understand why this is
convenient.</p>
<!--TOC subsubsection id="sec33" Why are there two environments for ignoring input?-->
<h4 class="subsubsection" id="sec33">5.2.2  Why are there two environments for ignoring input?</h4><!--SEC END --><p><a id="why"></a>
<a id="hevea_default13"></a><a id="hevea_default14"></a>
<a id="hevea_default15"></a><a id="hevea_default16"></a>
Some scanning and analysis of source is performed
by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A inside the <span class="c013">latexonly</span> environment, in order to
allow <span class="c013">latexonly</span> to dynamically occur inside other environments.</p><p>More specifically, <code>\end{</code><span class="c018">env</span><code>}</code> macros
are recognized and their <span class="c018">env</span> argument is tested against
the name of the environment whose opening macro <code>\</code><span class="c018">env</span>
opened the <span class="c013">latexonly</span> environment.
In that case, macro expansion of <code>\end</code><span class="c018">env</span> is performed and
any further occurrence of <code>\end{</code><span class="c018">env’</span><code>}</code> is tested
and may get expanded if it matches a pending
<code>\begin{</code><span class="c018">env’</span><code>}</code>
construct.</p><p>This enables playing tricks such as:
</p><pre class="verbatim">\newenvironment{latexhuge}
{\begin{latexonly}\huge}
{\end{latexonly}}
\begin{latexhuge}
This will appear in huge font in \LaTeX{} output only.
\end{latexhuge}
</pre><p>L<sup>A</sup>T<sub>E</sub>X output will be:
</p><blockquote class="quote">
<img src="manual004.png">
</blockquote><p>
While there is no H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output.</p><p>Since H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A somehow analyses input that is enclosed in the
<span class="c013">latexonly</span> environment,
it may choke.
However, this environment is intended to select processing by
L<sup>A</sup>T<sub>E</sub>X only and might contain arbitrary source code.
Fortunately, it remains possible to have input processed by L<sup>A</sup>T<sub>E</sub>X
only, regardless of what it is, by enclosing it in the
<span class="c013">verblatex</span> environment.
Inside this environment, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A performs no other action
than looking for <code>\end{verblatex}</code>. As a consequence,
the <code>\begin{verblatex}</code> and <code>\end{verblatex}</code> constructs
may only appear in the main flow of text or inside the same macro body,
a bit like L<sup>A</sup>T<sub>E</sub>X <span class="c013">verbatim</span> environment.</p><p>Relations between <span class="c013">toimage</span> and <span class="c013">verbimage</span> are similar.
Additionally, formal parameters <code>#</code><span class="c018">i</span> are replaced by
actual arguments inside the <span class="c013">toimage</span> environment
(see end of section <a href="#substimage">6.3</a> for an example of this feature).</p>
<!--TOC subsubsection id="sec34" The <span class="c013">hevea</span> boolean register-->
<h4 class="subsubsection" id="sec34">5.2.3  The <span class="c013">hevea</span> boolean register</h4><!--SEC END --><p><a id="heveabool"></a></p><p>Boolean registers are provided by the <span class="c013">ifthen</span> package
(see [<a href="#latex">L<sup>A</sup>T<sub>E</sub>X</a>, Section C.8.5] and section <a href="#ifthen">B.8.5</a> in this
document).
<a id="hevea_default17"></a>Both the <span class="c013">hevea.sty</span> style file
and H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A define the boolean register <span class="c013">hevea</span>.
However, this register initial value is <span class="c018">false</span> for L<sup>A</sup>T<sub>E</sub>X
and <span class="c018">true</span> for H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.</p><p>Thus, provided, both the <span class="c013">hevea.sty</span> style file and the
<span class="c013">ifthen</span> packages are loaded, the “purple rain” example can
be rephrased as follows:
</p><pre class="verbatim">We get:
{\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots
</pre><p>We get:
<span class="c010">purple rain, purple rain</span>…</p><p>Another choice is using the T<sub>E</sub>X-style conditional macro
<code>\ifhevea</code> (see Section <a href="#texcond">B.16.1.4</a>):
</p><pre class="verbatim">We get:
{\ifhevea\purple\fi purple rain, purple rain}\ldots
</pre><p>We get: <span class="c010">purple rain, purple rain</span>…</p><p><a id="hevea_default18"></a>
</p>
<!--TOC subsection id="sec35" Comments-->
<h3 class="subsection" id="sec35">5.3  Comments</h3><!--SEC END --><p><a id="comments"></a>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A processes all lines that start with <code>%HEVEA</code>, while
L<sup>A</sup>T<sub>E</sub>X treats these lines as comments.
Thus, this is a last variation on the “purple rain” example:
</p><pre class="verbatim">We get
%HEVEA{\purple
purple rain, purple rain%
%HEVEA}%
\ldots
</pre><p>(Note how comments are placed at the end of some lines to avoid spurious spaces
in the final output.)</p><p>We get:
<span class="c010">purple rain, purple rain</span>…</p><p>Comments thus provide an alternative to loading the
<span class="c013">hevea</span> package. For user convenience, comment equivalents to
the <code>latexonly</code> and <code>toimage</code> environment are also provided:
<a id="hevea_default19"></a>
<a id="hevea_default20"></a>
<a id="hevea_default21"></a>
<a id="hevea_default22"></a>
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="hbar" colspan=2></td></tr>
<tr><td class="c029">environment</td><td class="c029">comment
equivalent</td></tr>
<tr><td class="hbar" colspan=2></td></tr>
<tr><td class="c032"><code>\begin{latexonly}</code>… <code>\end{latexonly}</code></td><td class="c032"><table class="c002 cellpading0"><tr><td class="c032"><code>%BEGIN LATEX</code> </td></tr>
<tr><td class="c032">…</td></tr>
<tr><td class="c032"><code>%END LATEX</code>
</td></tr>
</table>
</td></tr>
<tr><td class="c032"> </td><td class="c032"> </td></tr>
<tr><td class="hbar" colspan=2></td></tr>
<tr><td class="c032"><code>\begin{toimage}</code>… <code>\end{toimage}</code></td><td class="c032"><table class="c002 cellpading0"><tr><td class="c032"><code>%BEGIN IMAGE</code> </td></tr>
<tr><td class="c032">…</td></tr>
<tr><td class="c032"><code>%END IMAGE</code>
</td></tr>
</table>
</td></tr>
</table>
</div><p>
Note that L<sup>A</sup>T<sub>E</sub>X, by ignoring comments, naturally performs the action
of processing text between <code>%BEGIN</code><span class="c013">…</span> and <code>%END</code><span class="c013">…</span> comments. However, no environment is opened and closed and no scope is
created while using comment equivalents.</p>
<!--TOC section id="imagen" With a little help from L<sup>A</sup>T<sub>E</sub>X-->
<h2 class="section" id="imagen">6  With a little help from L<sup>A</sup>T<sub>E</sub>X</h2><!--SEC END --><p>
Sometimes,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A just cannot process its input, but it remains acceptable to
have L<sup>A</sup>T<sub>E</sub>X process it, to produce an image from
L<sup>A</sup>T<sub>E</sub>X output and to include a link to this image into H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
output.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A provides a limited support for doing this.</p>
<!--TOC subsection id="image:file" The <span class="c018">image</span> file-->
<h3 class="subsection" id="image:file">6.1  The <span class="c018">image</span> file</h3><!--SEC END --><p>While outputting <em>doc</em><span class="c013">.html</span>, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A echoes some
of its input to the <em>image</em> file,
<em>doc</em><span class="c013">.image.tex</span>.
<a id="hevea_default23"></a>
Part of this process is done at the user’s request.
More precisely, the following two constructs
send <span class="c018">text</span> to the <em>image</em> file:
</p><div class="flushleft">
<code>\begin{toimage}</code><br>
<span class="c018">text</span><br>
<code>\end{toimage}</code><br>
 <br>
<code>%BEGIN IMAGE</code><br>
<span class="c018">text</span><br>
<code>%END IMAGE</code>
</div><p>
Additionally, <code>\usepackage</code> commands, top-level and global
definitions
are automatically echoed to the image file. This enables using
document-specific commands in <span class="c018">text</span> above.</p><p><a id="hevea_default24"></a>
Output to the image file builds up a current page, which is flushed
by the <code>\imageflush</code> command.
This command has the following effect: it outputs a strict page break
in the <em>image</em> file, increments the image counter and
output a <code><img src="</code><span class="c018">pagename</span><code>.png"></code> tag in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
output file, where <span class="c018">pagename</span> is build from the image counter
and H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output file name.
Then the <code>imagen</code> script has to be run by:
</p><div class="flushleft">
<code># imagen</code> <em>doc</em>
</div><p>
This will process the <em>doc</em><span class="c013">.image.tex</span>
file through L<sup>A</sup>T<sub>E</sub>X,
<span class="c013">dvips</span>, <span class="c013">ghostscript</span> and a few others tools, which must all be
present (see section <a href="#requirements">C.4.1</a>), finally producing one
<span class="c018">pagename</span><span class="c013">.png</span> file per page in the <em>image</em>
file.</p><p>The usage of <code>imagen</code> is described at
section <a href="#imagenusage">C.1.5</a>. Note that <span class="c013">imagen</span> is a simple shell
script. Unix users can pass <span class="c013">hevea</span> the command-line option
<a id="hevea_default25"></a><span class="c013">-fix</span>. Then <span class="c013">hevea</span> will
itself call <span class="c013">imagen</span>, when appropriate.</p>
<!--TOC subsection id="sec38" A toy example-->
<h3 class="subsection" id="sec38">6.2  A toy example</h3><!--SEC END --><p>
Consider the “blob” example from section <a href="#blob">4.2</a>.
Here is the active part of a <span class="c013">blob.tex</span> file:
</p><pre class="verbatim"> \newcommand{\blob}{\rule[.2ex]{1ex}{1ex}}
\blob\ Blob \blob
</pre><p>This time, we would like <code>\blob</code> to produce a small black square, which
<code>\rule[.2ex]{1ex}{1ex}</code> indeed does in L<sup>A</sup>T<sub>E</sub>X.
Thus we can write:
</p><pre class="verbatim"> \newcommand{\blob}{%
\begin{toimage}\rule[.2ex]{1ex}{1ex}%
\end{toimage}%
\imageflush}
\blob\ Blob \blob
</pre><p>Now we issue the following two commands:
</p><pre class="verbatim"> # hevea blob.tex
# imagen blob
</pre><p>And we get:
</p><blockquote class="quote">
<img src="manual005.png"> Blob <img src="manual005.png">
</blockquote><p>Observe that the trick can be used to replace missing symbols by small
<span class="c013">.png</span> images. However, the cost may be prohibitive, text rendering
is generally bad, fine placement is ignored and font style changes are
problematic.
Cost can be lowered using <code>\savebox</code>, but the other problems remain.</p>
<!--TOC subsection id="sec39" Including Postscript images-->
<h3 class="subsection" id="sec39">6.3  Including Postscript images</h3><!--SEC END --><p><a id="substimage"></a>
<a id="hevea_default26"></a>
In this section, a technique to transform included Postscript images
into included bitmap images is described.
Note that this technique is used by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implementation of the
<span class="c013">graphics</span> package (see section <a href="#graphics">B.14.1</a>),
which provides a more standard manner to include Postscript images in
L<sup>A</sup>T<sub>E</sub>X documents.</p><p>Included images are easy to manage: it suffices to let L<sup>A</sup>T<sub>E</sub>X do the
job.
Let <span class="c013">round.ps</span> be a Postscript file, which is included as an
image in the source file <span class="c013">round.tex</span> (which must load the
<em>epsf</em> package):
</p><pre class="verbatim"> \begin{center}
\epsfbox{round.ps}
\end{center}
</pre><p>Then, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can have this image translated into a inlined (and
centered) <span class="c013">.png</span> image by modifying source as follows:
</p><pre class="verbatim"> \begin{center}
%BEGIN IMAGE
\epsfbox{round.ps}
%END IMAGE
%HEVEA\imageflush
\end{center}
</pre><p>(Note that the <span class="c013">round.tex</span> file
still can be processed by L<sup>A</sup>T<sub>E</sub>X, since comment equivalents
of the <span class="c013">toimage</span> environment are used and that
the <code>\imageflush</code> command is inside
a <code>%HEVEA</code> comment — see section <a href="#comments">5.3</a>.)</p><p>Then, processing <span class="c013">round.tex</span> through H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and
<span class="c013">imagen</span> yields:
</p><blockquote class="quote">
<div class="center">
<img src="manual006.png"></div>
</blockquote><p>
It is important to notice that things go smoothly because the
<code>\usepackage{epsf}</code> command gets echoed to the
<em>image</em> file. In more complicated cases, L<sup>A</sup>T<sub>E</sub>X may fail
on the <em>image</em> file because it does not load the right
packages or define the right macros.</p><p>However, the above solution implies modifying the original L<sup>A</sup>T<sub>E</sub>X
source code.
A better solution is to define the <code>\epsfbox</code>
command, so that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A echoes <code>\epsfbox</code> and its argument to
the image file and performs <code>\imageflush</code>:
</p><pre class="verbatim"> \newcommand{\epsfbox}[1]{%
\begin{toimage}
\epsfbox{#1}
\end{toimage}
\imageflush}
</pre><p>Such a definition must be seen by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A only. So, it is best put
in a separate file whose name is given as an extra argument on
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A command-line (see section <a href="#heveaonly">5.1</a>).
Putting it in the document source
protected inside an <code>%HEVEA</code> comment is a bad idea, because it might then get echoed to the <span class="c018">image</span> file
and generate trouble when L<sup>A</sup>T<sub>E</sub>X is later run by <span class="c013">imagen</span>.</p><p>Observe that the above definition of <code>\epsfbox</code> is a definition
and not a redefinition (<em>i.e.</em> <code>\newcommand</code> is used and not
<code>\renewcommand</code>),
because H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not know about <code>\epsfbox</code> by default.
Also observe that this not a recursive definition, since
commands do not get expanded inside the <code>toimage</code> environment.</p><p>Finally, if the Postscript image is produced from a bitmap, it is
a pity to translate it back into a bitmap.
A better idea is first to generate a PNG file from the bitmap source
independantly
and then to include a link to that PNG file in html output, see
section <a href="#imgsrc">8.2</a> for a description of this more adequate technique.</p>
<!--TOC subsection id="sec40" Using filters-->
<h3 class="subsection" id="sec40">6.4  Using filters</h3><!--SEC END --><p>Some programs extend L<sup>A</sup>T<sub>E</sub>X capabilities using a filter principle.
In such a scheme, the document contains source fragments for the program.
A first run of the program on L<sup>A</sup>T<sub>E</sub>X source changes these fragments
into constructs that L<sup>A</sup>T<sub>E</sub>X (or a subsequent stage in the paper
document production chain, such as <span class="c013">dvips</span>) can handle.
Here again, the rule of the game is keeping H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A away from the
normal process: first applying the filter, then making H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A send
the filter output to the <em>image</em> file, and then having
<span class="c013">imagen</span> do the job.</p><p>Consider the <span class="c013">gpic</span> filter, for making drawings.
Source for <span class="c013">gpic</span> is enclosed in <code>.PS</code>…<code>.PE</code>,
then the result is available to subsequent L<sup>A</sup>T<sub>E</sub>X source as a T<sub>E</sub>X
box <code>\box\graph</code>.
For instance the following source, from a <span class="c013">smile.tex</span> file,
draws a “Smile!” logo as a centered
paragraph:
</p><pre class="verbatim"> .PS
ellipse "{\Large\bf Smile!}"
.PE
\begin{center}
~\box\graph~
\end{center}
</pre><p>Both the image description (<code>.PS</code>… <code>.PE</code>) and usage (<code>\box\graph</code>)
are for the <em>image</em> file, and they should be
enclosed by <code>%BEGIN IMAGE</code>… <code>%END IMAGE</code> comments.
Additionally, the image link is put where it belongs by an
<code>\imageflush</code> command:
</p><pre class="verbatim"> %BEGIN IMAGE
.PS
ellipse "{\Large\bf Smile!}"
.PE
%END IMAGE
\begin{center}
%BEGIN IMAGE
~\box\graph~
%END IMAGE
%HEVEA\imageflush
\end{center}
</pre><p>The <span class="c013">gpic</span> filter is applied first, then come <span class="c013">hevea</span>
and <span class="c013">imagen</span>:
</p><pre class="verbatim"> # gpic -t < smile.tex > tmp.tex
# hevea tmp.tex -o smile.html
# imagen smile
</pre><p>And we get:
</p><div class="center">
<img src="manual007.png"></div><p>
Observe how the <code>-o</code> argument to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is used and that
<span class="c013">imagen</span> argument is H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output basename (see
section <a href="#basenames">C.1.1.2</a> for the full definition of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output basename).</p><p>In the <span class="c013">gpic</span> example, modifying user source cannot be totally avoided.
However, writing in a generic style saves typing.
For instance, users may define the following environment for
centered <span class="c013">gpic</span> pictures in L<sup>A</sup>T<sub>E</sub>X:
</p><pre class="verbatim"> \newenvironment{centergpic}{}{\begin{center}~\box\graph~\end{center}}
</pre><p>Source code will now be as follows:
</p><pre class="verbatim"> \begin{centergpic}
.PS
ellipse "{\Large\bf Smile!}"
.PE
\end{centergpic}
</pre><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will process this source correctly, provided it is given its
own definition for the <code>centergpic</code> environment beforehand:
</p><pre class="verbatim"> \newenvironment{centergpic}
{\begin{toimage}}
{\box\graph\end{toimage}\begin{center}\imageflush\end{center}}
</pre><p>Assuming that the definition above is in a <a href="http://hevea.inria.fr/examples/smile.hva">smile.hva</a> file,
the command sequence for translating
<a href="http://hevea.inria.fr/examples/smile.tex">smile.tex</a> now is:
</p><pre class="verbatim"> # gpic -t < smile.tex > tmp.tex
# hevea smile.hva tmp.tex -o smile.html
tmp.tex:5: Warning: ignoring definition of \centergpic
tmp.tex:5: Warning: not defining environment centergpic
# imagen smile
</pre><p>The warnings above are normal: they are issued when H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A runs
across the L<sup>A</sup>T<sub>E</sub>X-intended definition of the <code>centergpic</code>
environment and refuses to override its own definition for that
environment.</p>
<!--TOC section id="hacha" Cutting your document into pieces with H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A-->
<h2 class="section" id="hacha">7  Cutting your document into pieces with H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A</h2><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A outputs a single <span class="c013">.html</span> file. This file can be
cut into pieces at various sectional units by H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A</p>
<!--TOC subsection id="sec42" Simple usage-->
<h3 class="subsection" id="sec42">7.1  Simple usage</h3><!--SEC END --><p>
First generate your html document by applying H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A:
</p><div class="flushleft">
<span class="c013"># hevea </span><em>doc</em><span class="c013">.tex</span>
</div><p>
Then cut <em>doc</em><span class="c013">.html</span> into pieces by the command:
</p><div class="flushleft">
<span class="c013"># hacha </span><em>doc</em><span class="c013">.html</span>
</div><p>
This will generate a simple root file
<span class="c013">index.html</span>.
This root file holds document title, abstract and a simple table of
contents.
Every item in the table of contents contains a link to or into a file
that holds a “cutting” sectional unit.
By default, the cutting sectional unit is <em>section</em> in the
<em>article</em> style and <em>chapter</em> in the <em>book</em>
style.
The name of those files are <em>doc</em>001<span class="c013">.html</span>,
<em>doc</em>002<span class="c013">.html</span>, etc.</p><p>Additionally, one level of sectioning below the cutting unit
(<em>i.e.</em> subsections in the <em>article</em> style and sections in the
<em>book</em> style) is shown
as an entry in the table of contents.
Sectional units above the cutting section (<em>i.e.</em> parts in both
<em>article</em> and <em>book</em> styles) close the current table
of contents and open a new one.
Cross-references are properly handled, that is, the local links generated by
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A are changed into remote links.</p><p>The name of the root file can be changed using the
<code>-o</code> option:
</p><div class="flushleft">
<span class="c013"># hacha -o root.html </span><em>doc</em><span class="c013">.html</span>
</div><p>Some of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output get replicated in all the files generated by
H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A.
<a id="html:footer"></a>Users can supply a header and a footer, which will appear at the
begining and end of every page generated by H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A. It suffices to
include the following commands in the document preamble:
</p><div class="flushleft">
  <code>\htmlhead{</code><span class="c018">header</span><code>}</code><br>
  <code>\htmlfoot{</code><span class="c018">footer</span><code>}</code>
</div><p>H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A also makes every page it generates a clone of its input as
regards attributes to the <code><body ...></code> opening tag and
meta-information from the <code><head></code>… <code><\head></code>
block. See section <a href="#metadef">B.2</a> for examples of this replication
feature.</p><p><a id="hacha:style"></a><a id="hevea_default27"></a>By contrast, style information specified in the <code>style</code> elements
from rom the <code><head></code>… <code><\head></code>
block is not replicated. Instead, all style definitions are collected into an
external style sheet file whose name is <em>doc</em><span class="c013">.css</span>,
and all generated html files adopt <em>doc</em><span class="c013">.css</span> as
an external style sheet.
It is important to notice that, since version 1.08, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A produces
a <code>style</code> element by itself, even if users do not explicitely
use styles. As a consequence,
H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A normally produces a
file <em>doc</em><span class="c013">.css</span>, which should not be forgotten while
copying files to their final destination after a run of H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A.</p>
<!--TOC subsection id="sec43" Advanced usage-->
<h3 class="subsection" id="sec43">7.2  Advanced usage</h3><!--SEC END --><p>H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A behaviour can be altered from the document source, by using
a counter and a few macros.</p><p>A document that explicitly includes cutting macros still can be typeset by
L<sup>A</sup>T<sub>E</sub>X, provided it loads the
<span class="c013">hevea.sty</span> style file from the H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A distribution.
(See section <a href="#both">5</a> for details on this style file).
An alternative to loading the <span class="c013">hevea</span> package is to put
all cutting instructions in comments starting with <code>%HEVEA</code>.</p>
<!--TOC subsubsection id="sec44" Principle-->
<h4 class="subsubsection" id="sec44">7.2.1  Principle</h4><!--SEC END --><p>
H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A recognizes all sectional units, ordered as follows, from
top to bottom: <em>part</em>, <em>chapter</em>,
<em>section</em>, <em>subsection</em>, <em>subsubsection</em>,
<em>paragraph</em> and <em>subparagraph</em>.</p><p>At any point between <code>\begin{document}</code> and
<code>\end{document}</code>,
there exist a current cutting sectional unit (cutting unit for short),
a current cutting depth, a root file and an output file.
Table of contents output goes to the root file, normal output goes to
the output file.
Cutting units start a new output file, whereas units comprised between the
cutting unit and the cutting units plus the cutting depth add new
entries in the table of contents.</p><p>At document start, the root file and the output file are H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A
output file (<em>i.e.</em> <span class="c013">index.html</span>).
The cutting unit and the cutting depth are set to default values that
depend on the document style.</p>
<!--TOC subsubsection id="sec45" Cutting macros-->
<h4 class="subsubsection" id="sec45">7.2.2  Cutting macros</h4><!--SEC END --><p>
The following cutting instructions are for use in the document
preamble. They command the cutting scheme of the whole document:
<a id="hevea_default28"></a><a id="hevea_default29"></a><a id="hevea_default30"></a><a id="hevea_default31"></a></p><dl class="description"><dt class="dt-description">
<span class="c014">\cuttingunit</span></dt><dd class="dd-description">
This is a macro that holds the document cutting unit. You can change
the default (which is <em>section</em> in the <em>article</em> style
and <em>chapter</em> in the <em>book</em> style) by doing:
<div class="flushleft">
<code>\renewcommand{\cuttingunit}{</code><span class="c018">secname</span><code>}</code>.
</div>
</dd><dt class="dt-description"><span class="c014">\tocnumber</span></dt><dd class="dd-description"> Instruct H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to put section numbers
into table of content entries.
</dd><dt class="dt-description"><span class="c014">\notocnumber</span></dt><dd class="dd-description"> Instruct H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A <em>not</em> to put
section numbers
into table of content entries. This is the default.
</dd><dt class="dt-description"><span class="c014">cuttingdepth</span></dt><dd class="dd-description">
This is a counter that holds the document cutting depth.
You can change the default value of 1 by doing
<code>\setcounter{cuttingdepth}{</code><span class="c018">numvalue</span><code>}</code>.
A cutting depth of zero means no other entries than the cutting units
in the table of contents.
</dd></dl><p>Other cutting instructions are to be used after
<code>\begin{document}</code>. They all generate html comments in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
output.
These comments then act as instructions to H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A.
<a id="hevea_default32"></a>
<a id="hevea_default33"></a>
<a id="hevea_default34"></a>
</p><dl class="description"><dt class="dt-description">
<span class="c022"><span class="c013">\cuthere{</span><span class="c018">secname</span><span class="c013">}{</span><span class="c018">itemtitle</span><span class="c013">}</span></span></dt><dd class="dd-description">
Attempt a cut.
<ul class="itemize"><li class="li-itemize">
If <span class="c018">secname</span> is the current cutting unit or
the keyword <span class="c013">now</span>, then
a new output file is started and an entry in the current table of contents
is generated, with title <span class="c018">itemtitle</span>. This entry holds a link
to the new output file.
</li><li class="li-itemize">If <span class="c018">secname</span> is above the cutting unit, then the
current table of contents is closed. The output file is set to the
current root file.
</li><li class="li-itemize">If <span class="c018">secname</span> is below the cutting unit and less than the
cutting depth away from it, then an entry is added in the table of
contents.
This entry contains <em>itemtitle</em> and a link to the point where
<code>\cuthere</code> appears.
</li><li class="li-itemize">Otherwise, no action is performed.
</li></ul></dd><dt class="dt-description"><span class="c022"><span class="c013">\cutdef[</span><span class="c018">depth</span><span class="c013">]{</span><span class="c018">secname</span><span class="c013">}</span></span></dt><dd class="dd-description">
Open a new table of contents, with cutting depth <em>depth</em> and
cutting unit <em>secname</em>. If the optional <em>depth</em> is absent,
the cutting depth does not change.
The output file becomes the root file.
Result is unspecified if whatever <em>secname</em> expands to is
a sectional unit name above
the current cutting unit, is not a valid sectional unit name or if
<em>depth</em> does not expand to a small positive number.
</dd><dt class="dt-description"><span class="c014">\cutend</span></dt><dd class="dd-description">
End the current table of contents. This closes the scope of the
previous <code>\cutdef</code>. The cutting unit and cutting depth are
restored.
Note that <code>\cutdef</code> and <code>\cutend</code> must be properly balanced.
</dd></dl><p>
Commands <code>\cuthere</code> and <code>\cutend</code> have starred variants,
which behave identically except for footnotes (see <a href="#hachafoot">7.3.6</a>).</p><p>Default settings work as follows:
<code>\begin{document}</code> performs
</p><pre class="verbatim">\cutdef*[\value{cuttingdepth}]{\cuttingunit}
</pre><p>and <code>\end{document}</code> performs <code>\cutend*</code>.
All sectioning commands perform <code>\cuthere</code>,
with the sectional unit name as first argument and the (optional, if
present) sectioning
command argument (<em>i.e.</em> the section title) as second argument.
Note that starred versions of the sectioning commands also perform
cutting instructions.</p>
<!--TOC subsubsection id="table:link:style" Table of links organisation-->
<h4 class="subsubsection" id="table:link:style">7.2.3  Table of links organisation</h4><!--SEC END --><p>
A table of links generated by H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A is a list
of links to generated files.
Additionally, some sublists may be present, up to a certain depth.
The items in those sublists are
links inside generated files, they point to sectional unit titles
below the cutting unit, up to a certain depth.</p><p>More precisely, let <span class="c018">A</span> be a certain sectional unit (<em>e.g.</em>
“part”), let <span class="c018">B</span> be just below <span class="c018">A</span>
(<em>e.g.</em> “section”),
and let <span class="c018">C</span> be just below <span class="c018">C</span> (<em>e.g.</em> “subsection”).
Further assume that cutting is performed at level <span class="c018">B</span> with a depth of
more than one.
Then, every unit <span class="c018">A</span> holds a one or several tables of links
to generated files, and each generated file normally holds a <span class="c018">B</span> unit.
Sublists with links to <span class="c018">C</span> units inside <span class="c018">B</span> units normally appear in the
tables of links of level <span class="c018">A</span>.
The command-line options <a id="hevea_default35"></a><span class="c013">-tocbis</span>
and <a id="hevea_default36"></a><span class="c013">-tocter</span> instruct <span class="c013">hacha</span>
to put sublists at other places.
With <span class="c013">-tocbis</span> sublists are duplicated at the beginning
of the <span class="c018">B</span> level files; while with <span class="c013">-tocter</span> sublist only
appear at the beginning
of the <span class="c018">B</span> level files.</p><p>In my opinion,
default style is appropriate for documents with short <span class="c018">B</span> units;
while <span class="c013">-tocbis</span> style
is appropriate for documents with long <span class="c018">B</span> units with
a few sub-units; and <span class="c013">-tocter</span> style is appropriate
for documents with long <span class="c018">B</span> units with
a lot of sub-units.
As you may have noticed, this manual is cut by following the
<span class="c013">-tocbis</span> style.</p><p>Whatever the style is, if a <span class="c018">B</span> unit is cut
(<em>e.g.</em> because its text is enclosed in
<code>\cutdef{</code><span class="c018">C</span><code>}</code>… <code>\cutend</code>),
then every <span class="c018">C</span> unit goes into its own file and there is no sublist
after the relevant <span class="c018">B</span> level entry in the <span class="c018">A</span> level table of links.</p>
<!--TOC subsubsection id="sec47" Examples-->
<h4 class="subsubsection" id="sec47">7.2.4  Examples</h4><!--SEC END --><p>Consider, for instance, a <em>book</em> document with a long chapter
that you want to cut at the section level, showing subsections:
</p><pre class="verbatim">\chapter{A long chapter}
.....
\chapter{The next chapter}
</pre><p><a id="hevea_default37"></a><a id="hevea_default38"></a>
Then, you should insert a <code>\cutdef</code> at chapter start and a
<code>\cutend</code> at chapter end:
</p><pre class="verbatim">\chapter{A long chapter}
%HEVEA\cutdef[1]{section}
.....
%HEVEA\cutend
\chapter{The next chapter}
</pre><p>Then, the file
that would otherwise contain the long chapter now contains the chapter
title and a table of sections.
No other change is needed, since the command <code>\section</code> already
performs the appropriate <code>\cuthere{section}{...}</code> commands,
which were ignored by default.
(Also note that cutting macros are placed inside <code>%HEVEA</code> comments,
for L<sup>A</sup>T<sub>E</sub>X not to be disturbed).</p><p><a id="hevea_default39"></a>
<a id="hevea_default40"></a>
The <code>\cuthere</code> macro can be used to put some document parts into
their own file.
This may prove appropriate for long cover pages or abstracts that would
otherwise go into the root file.
Consider the following document:
</p><pre class="verbatim">\documentclass{article}
\begin{document}
\begin{abstract} A big abstract \end{abstract}
...
</pre><p>Then, you make the abstract go to its own file as it was a cutting
unit by typing:
</p><pre class="verbatim">\documentclass{article}
\usepackage{hevea}
\begin{document}
\cuthere{\cuttingunit}{Abstract}
\begin{abstract} A big abstract \end{abstract}
...
</pre><p>(Note that, this time, cutting macros appear unprotected in the
source. However, L<sup>A</sup>T<sub>E</sub>X still can process the document, since the
<span class="c013">hevea</span> package is loaded).</p>
<!--TOC subsubsection id="sec48" More and More Pages in Output-->
<h4 class="subsubsection" id="sec48">7.2.5  More and More Pages in Output</h4><!--SEC END --><p>
<a id="hevea_default41"></a><a id="hevea_default42"></a>In some situations it may be appropriate to produce many
pages from one source files.
More specifically, loading the <span class="c013">deepcut</span> package will put
all sectioning units of your document (from <code>\part</code> to
<code>\subsection</code> in their own file.</p><p>Similarly, loading the <span class="c013">figcut</span> package will make all figures
and tables go into their own file.
The <span class="c013">figcut</span> package accepts two options, <span class="c013">show</span> and
<span class="c013">noshow</span>. The former, which is the default, instructs H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
to repeat the caption into the main flow of text, with a link to the figure.
The latter option disables the feature.</p>
<!--TOC subsection id="sec49" More Advanced Usage-->
<h3 class="subsection" id="sec49">7.3  More Advanced Usage</h3><!--SEC END --><p>
In this section we show how to alter some details of H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A
behaviour.
This includes controlling output file names and the title of generated
web pages and introducing arbitrary cuts.</p>
<!--TOC subsubsection id="cutname" Controlling output file names-->
<h4 class="subsubsection" id="cutname">7.3.1  Controlling output file names</h4><!--SEC END --><!--NAME cutname.html-->
<p><a id="hevea_default43"></a>When invoked as <span class="c013">hacha <em>doc</em>.html</span>,
H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A produces a <span class="c013">index.html</span> table of links file that
points into <em>doc</em><span class="c013">001.html</span>,
<em>doc</em><span class="c013">002.html</span>, etc. content files.
This is not very convenient when one wishes to point inside the
document from outside.
However, the <code>\cutname{</code><span class="c018">name</span><code>}</code> command
sets the name of the current output file name as <span class="c018">name</span>.</p><p>Consider a document cut at the section level, which contains the
following important section:
</p><pre class="verbatim">\section{Important\label{important} section}
...
</pre><p>To make the important section goes into file <span class="c013">important.html</span>,
one writes:
</p><pre class="verbatim">\section{Important\label{important} section}\cutname{important.html}
...
</pre><p>Then, section “Important section” can be referenced from
an H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A unaware html page by:
</p><pre class="verbatim">In this document, there is a very
<a href="important.html#important">important section</a>.
</pre><p>If you are reading the html version of this manual, you may check
that you are now reading file <span class="c013">cutname.html</span>.
This particular file name has been specified from the source
using <code>\cutname{cutname.html}</code>.
</p>
<!--TOC subsubsection id="sec51" Controlling page titles-->
<h4 class="subsubsection" id="sec51">7.3.2  Controlling page titles</h4><!--SEC END --><p>
<a id="hevea_default44"></a>
When H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A creates a web page from a given sectional unit,
the title of this page normally is the name of the sectional unit.
For instance, the title of this very page should be
“Cutting your document into pieces with H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A”.
It is possible to insert some text at the beginning of all page
titles, by using the <code>\htmlprefix</code> command.
Hence, by writing
<code>\htmlprefix{\hevea{} Manual: }</code> in the document,
the title of this page would become:
“H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A Manual: Cutting your document into pieces with H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A”
and the title of all other pages would show the same prefix.</p>
<!--TOC subsubsection id="sec52" Links for the root file-->
<h4 class="subsubsection" id="sec52">7.3.3  Links for the root file</h4><!--SEC END --><p>
<a id="hevea_default45"></a>
The command <code>\toplinks{</code><span class="c018">prev</span><code>}{</code><span class="c018">up</span><code>}{</code><span class="c018">next</span><code>}</code> instructs H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A to put links to a
“previous”, “up” and “next” page in the root file.
The following points are worth noticing:
</p><ul class="itemize"><li class="li-itemize">
The <code>\toplink</code> command must appear in the document preamble
(<em>i.e.</em> before <code>\begin{document}</code>).
</li><li class="li-itemize">The arguments
<span class="c018">prev</span>, <span class="c018">up</span> and <span class="c018">next</span> should expand to urls,
notice that these argument are processed (see section <a href="#urlareprocessed">8.1.1</a>).
</li><li class="li-itemize">When one of the expected argument is left empty,
the corresponding link is not generated.
</li></ul><p>
This feature can prove useful to
relate documents that are generated independently by
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A.</p>
<!--TOC subsubsection id="sec53" Controlling link aspect from the document-->
<h4 class="subsubsection" id="sec53">7.3.4  Controlling link aspect from the document</h4><!--SEC END --><p>
<a id="hevea_default46"></a>By default the links to the previous, up and next pages show a small
icon (an appropriate arrow). This can be changed with the command
<code>\setlinkstext{</code><span class="c018">prev</span><code>}{</code><span class="c018">up</span><code>}{</code><span class="c018">next</span><code>}</code>,
where <span class="c018">prev</span>, <span class="c018">up</span> and <span class="c018">next</span> are some L<sup>A</sup>T<sub>E</sub>X
source.
<a id="hevea_default47"></a>
For instance the default behaviour is equivalent to:
</p><pre class="verbatim">\setlinkstext
{\imgsrc[alt="Previous"]{previous_motif.gif}}
{\imgsrc[alt="Up"]{contents_motif.gif}}
{\imgsrc[alt="Next"]{next_motif.gif}}
</pre><p>Command <code>\setlinkstext</code> behaves as <code>\toplinks</code> does.
That is, it must occur in document preamble, arguments are processed
and empty arguments yield no effect (<em>i.e.</em> defaults apply).</p>
<!--TOC subsubsection id="sec54" Cutting a document anywhere-->
<h4 class="subsubsection" id="sec54">7.3.5  Cutting a document anywhere</h4><!--SEC END --><p>
<a id="hevea_default48"></a>
Part of a document goes to a separate file when enclosed in a
<code>cutflow</code> environment:
</p><div class="flushleft">
<code>\begin{cutflow}{</code><span class="c018">title</span><code>}</code>…<code>\end{cutflow}</code>
</div><p>The content “…” will go into a file of its
own, while
the argument <span class="c018">title</span> is used as the title of the introduced
html page.</p><p>The html page introduced here does not belong to the normal flow of
text.
Consequently, one needs an explicit reference from the normal flow of text
into the content of the <code>cutflow</code> environment.
This will occur naturally when the content of the <code>cutflow</code> environment.
contains a <code>\label</code> construct.
This look natural in the following quiz example:
</p><pre class="verbatim">\paragraph{A small quiz}
\begin{enumerate}
\item What is black?
\item What is white?
\item What is Dylan?
\end{enumerate}
Answers in section~\ref{answers}.
\begin{cutflow}{Answers}
\paragraph{Quiz answers}\label{answers}
\begin{enumerate}
\item Black is black.
\item White is white.
\item Dylan is Dylan.
\end{enumerate}
\end{cutflow}
</pre><p>The example yields:
</p>
<!--TOC paragraph id="sec55" A small quiz-->
<h4 class="paragraph" id="sec55">A small quiz</h4><!--SEC END --><ol class="enumerate" type=1><li class="li-enumerate">
What is black?
</li><li class="li-enumerate">What is white?
</li><li class="li-enumerate">What is Dylan?
</li></ol><p>
Answers in section <a href="#answers">7.3.5</a>.
</p><!--FLOW <arg footer>YES</arg><arg title>Answers</arg>-->
<!--TOC paragraph id="sec56" Quiz answers-->
<h4 class="paragraph" id="sec56">Quiz answers</h4><!--SEC END --><p><a id="answers"></a>
</p><ol class="enumerate" type=1><li class="li-enumerate">
Black is black.
</li><li class="li-enumerate">White is white.
</li><li class="li-enumerate">Dylan is Dylan.
</li></ol><!--END FLOW-->
<p>
<a id="hevea_default49"></a><a id="hevea_default50"></a>
However,introducing html hyperlink targets and
references with the <code>\aname</code> and <code>\ahrefloc</code> commands
(see section <a href="#hyperlink">8.1.1</a>)
will be more practical most of the time.</p><p><a id="hevea_default51"></a>The starred variant environment
<code>cutflow*</code> is the same
as <code>cutflow</code>, save for the html header and footer (see
Section <a href="#html%3Afooter">7.1</a>) which are not replicated in the introduced
page.</p>
<!--TOC subsubsection id="hachafoot" Footnotes-->
<h4 class="subsubsection" id="hachafoot">7.3.6  Footnotes</h4><!--SEC END --><p>
<a id="hevea_default52"></a><a id="hevea_default53"></a>Footnote texts (given as arguments either to <code>\footnote</code> or
<code>\footnotetext</code>) do not go directly to output.
Instead, footnote texts accumulate internally in a <em>buffer</em>,
awaiting to be flushed.
The flushing of notes is controlled by the means of a current
<em>flushing unit</em>, which is a sectional unit name or
<span class="c018">document</span> — a fictional unit above all units.
At any point, the current flushing unit is the value of the
command <code>\@footnotelevel</code><a id="hevea_default54"></a>.
In practice, the flushing of footnote texts is performed by two commands:
</p><ul class="itemize"><li class="li-itemize">
<code>\flushdef{</code><span class="c018">secname</span><code>}</code> simply sets
the flushing unit to <span class="c018">secname</span>.
</li><li class="li-itemize"><code>\footnoteflush{</code><span class="c018">secname</span><code>}</code> acts
as follows:
<ul class="itemize"><li class="li-itemize">
If argument <span class="c018">secname</span> is equal to or above the
current flushing unit, then footnote texts are flushed (if any).
In the output, the texts themselves are surrounded by special comments
that tag them as footnote texts and record <span class="c018">secname</span>.
</li><li class="li-itemize">Otherwise, no action is performed.
</li></ul>
</li></ul><p>
The <em>article</em> style file performs <code>\flushdef{document}</code>,
while the <em>book</em> style file performs <code>\flushdef{chapter}</code>.
At the end of processing, <code>\end{document}</code> performs
<code>\footnoteflush{\@footnotelevel}</code>, so as to flush any pending notes.</p><p>Cutting commands interact with footnote flushing as follows:
</p><ul class="itemize"><li class="li-itemize">
<code>\cuthere{</code><span class="c018">secname</span><code>}</code>
executes <code>\footnoteflush{</code><span class="c018">secname</span><code>}</code>.
Remember that all sectioning commands perform
<code>\cuthere</code> with their sectional unit name as argument.
</li><li class="li-itemize"><code>\cutdef{</code><span class="c018">secname</span><code>}</code>
saves the current flushing unit and buffer on some internal stack,
starts a new buffer for footnote texts, and
sets the current flushing unit to <span class="c018">secname</span>
(by performing <code>\flushdef{</code><span class="c018">secname</span><code>}</code>).
</li><li class="li-itemize"><code>\cutend</code> first flushes any pending texts
(by performing <code>\footnoteflush</code> with the current flushing unit
as argument), and restores the flushing unit and footnote text buffer saved
by the matching <code>\cutdef</code>.
</li><li class="li-itemize">The starred variants <code>\cutdef*</code> and <code>\cutend*</code> perform
no operation that is related to footnotes.
</li></ul><p>Later, when running across footnote texts in its input file, H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A
sometimes put notes in a separate file.
More precisely, H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A has knowledge of the
current <em>cutting level</em>, the current sectional unit where
cuts occur — as given by the relevant <code>\cutdef</code>.
Moreover, H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A knows the current <em>section level</em> —
that is, the last sectional command processed.
Besides, H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A extracts the <em>note level</em> from the comments
that surround the notes (as given by the command
<code>\footnoteflush</code> that produced the notes).
Then, H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A creates a separate file for notes
when the cutting level and the note level differ,
or when the current level is above the cutting level
(<em>e.g.</em> the current level is <span class="c013">document</span> while the cutting
level is <span class="c013">chapter</span>).
As a result, notes should stay where they are when they occur at the end of
H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A output file and otherwise go to a separate file.</p><p>To make a complicated story even more complicated,
footnotes in <span class="c013">minipage</span> environments or in the arguments
to <code>\title</code> or <code>\author</code> have a different, I guess satisfactory,
behaviour.</p><p>Given the above description, footnotes are managed by default as follows.
</p><ul class="itemize"><li class="li-itemize">
In style <em>article</em>, <span class="c013">hevea</span> puts all footnotes
go at the end of the html file.
A later run of <span class="c013">hacha</span> creates a separate footnote file.
</li><li class="li-itemize">In style <em>book</em>, footnotes are collected at the end of
chapters. A later run of  <span class="c013">hacha</span> leaves them where they
are. Footnotes in the title or author names are managed specially,
they will normally appear at the end of the root file.
</li></ul><p>
<a id="hevea_default55"></a>In case you wish to adopt a <em>book</em>-like behaviour for
an <em>article</em> (footnotes at the end of sections),
it suffices to insert <code>\flushdef{section}</code> in the document
preamble.</p><p>We now give a few example of interaction between notes and cutting.
We first consider normal behaviour.
The page you are reading is a section page, since the current
cutting unit is “section”. The current unit is “subsection”.
The following two subsubsections are sent to their own files by
the means of a <code>\cutdef{subsubsection}</code>/<code>\cutend</code> pair.
As a result the text of footnotes appear at the end of the
subsubsection pages.
</p><!--CUT DEF subsubsection -->
<!--TOC subsubsection id="sec58" A cut subsubsection-->
<h4 class="subsubsection" id="sec58">7.3.7  A cut subsubsection</h4><!--SEC END --><p>
A note in a subsubsection, flushed at subsubsections.<sup><a id="text2" href="#note2">1</a></sup>
</p>
<!--BEGIN NOTES subsubsection-->
<hr class="ffootnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes">
<a id="note2" href="#text2">1</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">At the
end of my page.</div>
</dd></dl>
<!--END NOTES-->
<!--TOC subsubsection id="sec59" Another cut subsubsection-->
<h4 class="subsubsection" id="sec59">7.3.8  Another cut subsubsection</h4><!--SEC END --><p>
Another note in a subsubsection, flushed at subsubsections.<sup><a id="text3" href="#note3">2</a></sup>
</p><!--BEGIN NOTES subsubsection-->
<hr class="ffootnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes">
<a id="note3" href="#text3">2</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">At the
end of my page.</div>
</dd></dl>
<!--END NOTES-->
<!--CUT END -->
<p>The following two subsubsections are sent to their own files by
the means of a <code>\cutdef*{subsubsection}</code>/<code>\cutend*</code> pair.
As a result, the text of footnotes in the subsections appear
at the end of the current section page.<sup><a id="text4" href="#note4">3</a></sup>
</p><!--CUT DEF subsubsection -->
<!--TOC subsubsection id="sec60" A cut subsubsection-->
<h4 class="subsubsection" id="sec60">7.3.9  A cut subsubsection</h4><!--SEC END --><p>
A note in a subsubsection, flushed at sections.<sup><a id="text5" href="#note5">4</a></sup>
</p>
<!--TOC subsubsection id="sec61" Another cut subsubsection-->
<h4 class="subsubsection" id="sec61">7.3.10  Another cut subsubsection</h4><!--SEC END --><p>
Another note in a subsubsection, flushed at sections.<sup><a id="text6" href="#note6">5</a></sup>
</p><!--CUT END -->
<p>Finally, to send the footnotes in subsubsections
to a separate web page, one should use
a <code>\cutdef{subsubsection}</code>/<code>\cutend</code> pair
(to create a proper buffer for subsubsection notes),
redefine the flushing unit, and flush notes explicitly.
</p><pre class="verbatim">\cutdef{subsubsection}\flushdef{document}%
\subsubsection{...}
...
\footnoteflush{document}\cutend
</pre><!--CUT DEF subsubsection -->
<!--TOC subsubsection id="sec62" A cut subsubsection-->
<h4 class="subsubsection" id="sec62">7.3.11  A cut subsubsection</h4><!--SEC END --><p>
A note in a subsubsection flushed at document level.<sup><a id="text7" href="#note7">6</a></sup>
</p>
<!--TOC subsubsection id="sec63" Another cut subsubsection-->
<h4 class="subsubsection" id="sec63">7.3.12  Another cut subsubsection</h4><!--SEC END --><p>
Another note in a subsubsection at document level.<sup><a id="text8" href="#note8">7</a></sup>
</p><!--BEGIN NOTES document-->
<hr class="ffootnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes">
<a id="note7" href="#text7">6</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">Sent to a
separate file</div>
</dd><dt class="dt-thefootnotes"><a id="note8" href="#text8">7</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">Sent to
a separate file</div>
</dd></dl>
<!--END NOTES-->
<!--CUT END -->
<!--BEGIN NOTES section-->
<hr class="ffootnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes">
<a id="note4" href="#text4">3</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">Standard section footnote.</div>
</dd><dt class="dt-thefootnotes"><a id="note5" href="#text5">4</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">Sent at
the end of <span class="c013">cutname.html</span></div>
</dd><dt class="dt-thefootnotes"><a id="note6" href="#text6">5</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">Sent at
the end of <span class="c013">cutname.html</span></div>
</dd></dl>
<!--END NOTES-->
<!--TOC section id="sec64" Generating html constructs-->
<h2 class="section" id="sec64">8  Generating html constructs</h2><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><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>
<!--TOC subsection id="sec65" High-Level Commands-->
<h3 class="subsection" id="sec65">8.1  High-Level Commands</h3><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><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="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A internals.</p>
<!--TOC subsubsection id="sec66" Commands for Hyperlinks-->
<h4 class="subsubsection" id="sec66">8.1.1  Commands for Hyperlinks</h4><!--SEC END --><p><a id="hevea_default56"></a><a id="hyperlink"></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="#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_default57"></a><a id="hevea_default58"></a><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></p><table class="c002 cellpading0"><tr><td class="c029">Macro</td><td class="c029" colspan=2>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A</td><td class="c029">L<sup>A</sup>T<sub>E</sub>X</td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c041">
<code>\ahref{</code><span class="c018">url</span><code>}{</code><span class="c018">text</span><code>}</code>    </td><td class="c039">make <span class="c018">text</span> an hyperlink to <span class="c018">url</span></td><td class="c029">    </td><td class="c039">echo <span class="c018">text</span></td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c041">
<code>\footahref{</code><span class="c018">url</span><code>}{</code><span class="c018">text</span><code>}</code>    </td><td class="c039">make <span class="c018">text</span> an hyperlink to <span class="c018">url</span></td><td class="c029">    </td><td class="c039">make <span class="c018">url</span> a footnote to <span class="c018">text</span>,
<span class="c018">url</span> is shown in typewriter font</td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c041">
<code>\ahrefurl{</code><span class="c018">url</span><code>}</code>    </td><td class="c039">make <span class="c018">url</span> an hyperlink to <span class="c018">url</span>.</td><td class="c029">    </td><td class="c039">typeset <span class="c018">url</span> in typewriter font</td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c041">
<code>\ahrefloc{</code><span class="c018">label</span><code>}{</code><span class="c018">text</span><code>}</code>    </td><td class="c039">make <span class="c018">text</span> an hyperlink to <span class="c018">label</span> inside the document</td><td class="c029">    </td><td class="c039">echo <span class="c018">text</span></td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c041">
<code>\aname{</code><span class="c018">label</span><code>}{</code><span class="c018">text</span><code>}</code>    </td><td class="c039">make <span class="c018">text</span> an hyperlink target with label <span class="c018">label</span></td><td class="c029">    </td><td class="c039">echo <span class="c018">text</span></td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c041">
<code>\mailto{</code><span class="c018">address</span><code>}</code>    </td><td class="c039">make <span class="c018">address</span> a “mailto” link to <span class="c018">address</span></td><td class="c029">    </td><td class="c039">typeset <span class="c018">address</span> in typewriter font
</td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c041"><code>\imgsrc[</code><span class="c018">attr</span><code>]{</code><span class="c018">url</span><code>}</code>    </td><td class="c039">insert <span class="c018">url</span> as an image, <span class="c018">attr</span> are attributes in the
html sense</td><td class="c029">    </td><td class="c039">do nothing </td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c041"><code>\home{</code><span class="c018">text</span><code>}</code>    </td><td class="c039" colspan=3>produce a home-dir url both for output and links, output aspect is: “~<span class="c018">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_default65"></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="#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="c015"><sup>E</sup></span>V<span class="c015"><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="c015"><sup>E</sup></span>V<span class="c015"><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_default66"></a>
<a id="hevea_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<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
Note that this usage of <code>\url</code> is deprecated.</p>
<!--TOC subsubsection id="sec67" html style colours-->
<h4 class="subsubsection" id="sec67">8.1.2  html style colours</h4><!--SEC END --><p><a id="color:high"></a>
Specifying colours both for L<sup>A</sup>T<sub>E</sub>X and
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A should be done using the <span class="c013">color</span> package (see
section <a href="#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="c015"><sup>E</sup></span>V<span class="c015"><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="c039"><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_default68"></a>Additionally, the current text color can be
changed by the declaration <code>\htmlcolor{</code><span class="c018">number</span><code>}</code>,
where <span class="c018">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>
<!--TOC subsection id="imgsrc" More on included images-->
<h3 class="subsection" id="imgsrc">8.2  More on included images</h3><!--SEC END --><p>
<a id="hevea_default69"></a><a id="hevea_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="#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="c015"><sup>E</sup></span>V<span class="c015"><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="c015"><sup>E</sup></span>V<span class="c015"><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="c015"><sup>E</sup></span>V<span class="c015"><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="c018">name</span><span class="c013">.ps</span>, while GIF files are of the kind
<span class="c018">name</span><span class="c013">.gif</span>.
Then, images can be included using
<code>\includeimage{</code><span class="c018">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="#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="c018">image</span> file
mechanism (see section <a href="#imagen">6</a>),
which will translate the image back from
Postscript to bitmap format and will thus degrade it.</p>
<!--TOC subsection id="internal" Internal macros-->
<h3 class="subsection" id="internal">8.3  Internal macros</h3><!--SEC END --><p>
In this section a few of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A internal macros are
described.
Internal macros occur at the final expansion stage of H<span class="c015"><sup>E</sup></span>V<span class="c015"><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="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to another and
because using them incorrectly easily
crashes H<span class="c015"><sup>E</sup></span>V<span class="c015"><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="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A works.
</li></ul><p><a id="hevea_default71"></a>
The general principle of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is that L<sup>A</sup>T<sub>E</sub>X environments
<code>\begin{</code><span class="c018">env</span><code>}</code>…
<code>\end{</code><span class="c018">env</span><code>}</code> get
translated into html block-level elements <code><</code><span class="c018">block
attributes</span><code>></code>… <code></</code><span class="c018">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="#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="c015"><sup>E</sup></span>V<span class="c015"><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="c015"><sup>E</sup></span>V<span class="c015"><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="c015"><sup>E</sup></span>V<span class="c015"><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_default72"></a>
<a id="hevea_default73"></a>
<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>
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="c022"><span class="c013">\@print{</span><span class="c018">text</span><span class="c013">}</span></span></dt><dd class="dd-description">
Echo <span class="c018">text</span> verbatim. As a consequence use only ascii
in <span class="c018">text</span>.
</dd><dt class="dt-description"><span class="c022"><span class="c013">\@getprint{</span><span class="c018">text</span><span class="c013">}</span></span></dt><dd class="dd-description">
Process <span class="c018">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="c022"><span class="c013">\@hr[</span><span class="c018">attr</span><span class="c013">]{</span><span class="c018">width</span><span class="c013">}{</span><span class="c018">height</span><span class="c013">}</span></span></dt><dd class="dd-description">
Output an html horizontal rule, <span class="c018">attr</span> is attributes given
directly (e.g. <code>SIZE=3 HOSHADE</code>), while <span class="c018">width</span> and
<span class="c018">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="c022"><span class="c013">\@print@u{</span><span class="c018">n</span><span class="c013">}</span></span></dt><dd class="dd-description">
Output the (Unicode) character “<span class="c018">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="c022"><span class="c013">\@open{</span><span class="c018">block</span><span class="c013">}{</span><span class="c018">attributes</span><span class="c013">}</span></span></dt><dd class="dd-description">
Open html block-level element <span class="c018">block</span> with attributes
<span class="c018">attributes</span>. The block name <span class="c018">block</span> <span class="c022">must</span> be
lowercase.
As a special case <span class="c018">block</span> may be the empty string, then a html
<em>group</em> is opened.
</dd><dt class="dt-description"><span class="c022"><span class="c013">\@close{</span><span class="c018">block</span><span class="c013">}</span></span></dt><dd class="dd-description">
Close html block-level element <span class="c018">block</span>.
Note that <code>\@open</code> and <code>\@close</code> must be properly balanced.
</dd><dt class="dt-description"><span class="c022"><span class="c013">\@out@par{</span><span class="c018">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="c018">arg</span>, and then re-open a <code>p</code> element.
Otherwise <code>\@out@par</code> simply formats <span class="c018">arg</span>.
This command is adequate when
formatting <span class="c018">arg</span> produces block-level elements.
</dd></dl><p><a id="hevea_default85"></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="c022"><span class="c013">\@span{</span><span class="c018">attr</span><span class="c013">}</span></span></dt><dd class="dd-description">
<a id="hevea_default86"></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="c022"><span class="c013">\@style{</span><span class="c018">shape</span><span class="c013">}</span></span></dt><dd class="dd-description"> Declare the
text shape <span class="c018">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="c022">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="c022"><span class="c013">\@styleattr{</span><span class="c018">name</span><span class="c013">}{</span><span class="c018">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="c018">name</span> and attributes are specified.
More specifically,
<code>\@span{</code><span class="c018">attr</span><code>}</code> can be seen as a shorthand for
<code>\@styleattr{span}{</code><span class="c018">attr</span><code>}</code>;
while
<code>\@style{</code><span class="c018">name</span><code>}</code> can be seen as
a shorthand for
<code>\@styleattr{</code><span class="c018">name</span><code>}{}</code>.</dd><dt class="dt-description"><span class="c022"><span class="c013">\@fontsize{</span><span class="c018">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="c018">font-size</span><code>"</code> as active.
The argument
<span class="c018">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="c018">font-size</span>, a CSS fontsize value,
from <span class="c018">int</span>.
More specifically, <span class="c018">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="c022"><span class="c013">\@fontcolor{</span><span class="c018">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="c018">color</span><code>"</code> as active.
The argument <span class="c018">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="c018">XXXXXX</span>.
Note that the argument <span class="c018">color</span> is processed, as a consequence
numerical color arguments should be given as <code>\#</code><span class="c018">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><!--TOC subsubsection id="sec70" Notice on font styling with CSS-->
<h4 class="subsubsection" id="sec70">Notice on font styling with CSS</h4><!--SEC END --><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="c015"><sup>E</sup></span>V<span class="c015"><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="c024">Das Kapital</cite>.
</p><p><a id="hevea_default87"></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="c022"><span class="c013">\@addstyle{</span><span class="c018">name:val</span><span class="c013">}{</span><span class="c018">attrs</span><span class="c013">}</span></span></dt><dd class="dd-description">
Echo the space-separated attributes <span class="c018">attrs</span> of a tag with the
<span class="c018">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="c024">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="c022">The Holy Bible</span></cite> and
<span class="c024"><cite>Das Kapital</cite></span>.</p>
<!--TOC subsection id="rawhtml" The <span class="c013">rawhtml</span> environment-->
<h3 class="subsection" id="rawhtml">8.4  The <span class="c013">rawhtml</span> environment</h3><!--SEC END --><p>
<a id="hevea_default88"></a><a id="hevea_default89"></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="c018">file</span><code>}</code> echoes the
contents of file <span class="c018">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="c015"><sup>E</sup></span>V<span class="c015"><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="#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="c015"><sup>E</sup></span>V<span class="c015"><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="c018">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="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is given the command-line option <a id="hevea_default90"></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_default91"></a><a id="hevea_default92"></a>
<a id="hevea_default93"></a><a id="hevea_default94"></a>
If H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is targeted to text or info files (see
Section <a href="#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="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output
mode. Of course, when H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A produces html,
the latter environment and command suffer from
the same drawbacks as <span class="c013">rawhtml</span>.</p>
<!--TOC subsection id="sec72" Examples-->
<h3 class="subsection" id="sec72">8.5  Examples</h3><!--SEC END --><p>
<a id="hevea_default95"></a><a id="hevea_default96"></a><a id="hevea_default97"></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_default98"></a><a id="hevea_default99"></a>Notice that the code above is no longer present and is given here
for explanatory purpose only.
Now H<span class="c015"><sup>E</sup></span>V<span class="c015"><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="#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="c015"><sup>E</sup></span>V<span class="c015"><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_default100"></a></p><p><a id="hevea_default101"></a>
<a id="hevea_default102"></a>
<a id="hevea_default103"></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_default104"></a>
Another interesting example is the definition of the command
<code>\@doaelement</code>,
which H<span class="c015"><sup>E</sup></span>V<span class="c015"><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_default105"></a>
<a id="hevea_default106"></a>
<a id="hevea_default107"></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="#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_default108"></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_default109"></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>
<!--TOC subsection id="encodings" The document charset-->
<h3 class="subsection" id="encodings">8.6  The document charset</h3><!--SEC END --><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_default110"></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="c015"><sup>E</sup></span>V<span class="c015"><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_default111"></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="c018">n</span> where <span class="c018">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="c018">n</span> where <span class="c018">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="#inputenc">B.17.4</a>.</p><p><a id="hevea_default112"></a>If wished so, the charset can be extracted from the current
locale environment, provided this yields a valid (to H<span class="c015"><sup>E</sup></span>V<span class="c015"><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="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A as:
</p><div class="flushleft">
<span class="c013"># hevea -exec xxcharset.exe</span> <span class="c018">other arguments</span>
</div>
<!--TOC section id="style:sheets" Support for style sheets-->
<h2 class="section" id="style:sheets">9  Support<a id="hevea_default113"></a> for style sheets</h2><!--SEC END -->
<!--TOC subsection id="sec75" Overview-->
<h3 class="subsection" id="sec75">9.1  Overview</h3><!--SEC END --><p>
Starting with version 1.08, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A offers support for style sheets
(of the CSS variant see [<a href="#css">CSS-2</a>]).</p><p>Style sheets provide enhanced expressiveness. For instance, it is now possible
to get “real” (whatever real means here) small caps in html, and in a
relatively standard manner. There are other, discrete, maybe
unnoticeable, similar enhancements.</p><p>However, style sheets mostly offer an additional mechanism to
customise their documents to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A users. To do so, users should
probably get familiar with how H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A uses style sheets in the first
place.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A interest for style sheets is at the moment confined to
block-level elements (<code>div</code>, <code>table</code>, <code>H<</code><span class="c018">n</span><code>></code>,
etc.).
The general principle is as follows: when a command or an
environment gets translated into a block-level element,
the opening tag of the block level element has a
<span class="c013">class="<span class="c018">name</span>"</span> attribute, where <span class="c018">name</span> is the
command or environment name.</p><p>As an example the L<sup>A</sup>T<sub>E</sub>X command <code>\subsection</code>
is implemented with the element <code>h3</code>, resulting in
html output of the form:
</p><pre class="verbatim"> <h3 class="subsection">
...
</h3>
</pre><p>By default, most styles are undefined, and default rendering of
block-level elements applies. However, some packages (such as, for
instance <span class="c013">fancysection</span>, see Section <a href="#fancysection">B.16.4</a>) may
define them.
<a id="hevea_default114"></a><a id="hevea_default115"></a>If you wish to change the style of section headers, loading the
<span class="c013">fancysection</span> package may prove appropriate (see <a href="#fancysection">B.16.4</a>).
However, one can also proceed more directly, by appending new
definitions to the <em>document style
sheet</em>, with the command <code>\newstyle</code>.
For instance, here is a <code>\newstyle</code> to add style for subsections.
</p><pre>
\newstyle{.subsection}{padding:1ex;color:navy;border:solid navy;}
</pre><p>
This declaration adds some style element to the
<span class="c013">subsection</span> class (notice the dot!):
blocks that declare to belong to the class
will show dark-blue text, some padding
(space inside the box) is added and a border will be drawn around the block.
These specification will normally affect all subsections in the document.
Given the previous style definition, the sectioning command
</p><pre class="verbatim">\subsection*{A styled subsection heading}
</pre><p>should yield:
</p><h3 class="subsectionex">
A styled subsection heading
</h3><p>The following points are worth noticing:
</p><ul class="itemize"><li class="li-itemize">
To yield some effect, <code>\newstyle</code> commands <em>must</em> appear
in the document preamble, <em>i.e.</em> before <code>\begin{document}</code>.
</li><li class="li-itemize">Arguments to <code>\newstyle</code> commands are processed.
</li><li class="li-itemize">The <span class="c013">hevea</span> package defines all style sheet related
commands as no-ops. Thus, these commands do not affect
document processing by L<sup>A</sup>T<sub>E</sub>X.
</li></ul>
<!--TOC subsection id="css:change:all" Changing
the style of all instances of an environment-->
<h3 class="subsection" id="css:change:all">9.2  Changing
the style of all instances of an environment</h3><!--SEC END --><p>In this very document, all <span class="c013">verbatim</span> environments appear over
a light green background, with small left and right margins.
This has been performed by simply issuing the following command in
the document preamble.
</p><pre class="verbatim">\newstyle{.verbatim}{margin:1ex 1ex;padding:1ex;background:\#ccffcc;}
</pre><p>Observe that, in the explicit numerical color argument above, the
hash character “<span class="c013">#</span>” has to be escaped.</p>
<!--TOC subsection id="css:change" Changing the style of some instances of an environment-->
<h3 class="subsection" id="css:change">9.3  Changing the style of some instances of an environment</h3><!--SEC END --><p>
<a id="hevea_default116"></a><a id="hevea_default117"></a>One can also change the style class attached to a given instance of
an environment and thus control styling of environments more precisely.</p><p>As a matter of fact, the name of the class attribute of
environment <span class="c018">env</span> is referred to through an indirection, by
using the command <code>\getenvclass{</code><span class="c018">env</span><code>}</code>.
The class attribute can be changed with the command
<code>\setenvclass{</code><span class="c018">env</span><code>}{</code><span class="c018">class</span><code>}</code>.
The <code>\setenvclass</code> command internally defines a command
<code>\</code><span class="c018">env</span><code>@class</code>, whose content is read
by the <code>\getenvclass</code> command. As a consequence, the class
attribute of environments follows normal scoping rules.
<a id="getstylecolor:example"></a>
For instance, here is how to change the style of <em>one</em> <span class="c013">verbatim</span>
environment.
</p><pre class="myverbatim">{\setenvclass{verbatim}{myverbatim}
\begin{verbatim}
This will be styled through class 'myverbatim', introduced by:
\newstyle{.myverbatim}
{margin:1ex 3x;padding:1ex;
color:maroon;
background:\@getstylecolor[named]{Apricot}}
\end{verbatim}}</pre><p>
Observe how the class of environment <span class="c013">verbatim</span> is changed from
its default value to the
new value <span class="c013">myverbatim</span>. The change remains active until the
end of the current group (here, the “<span class="c013">}</span>” at the end). Then, the class
of environment <span class="c013">verbatim</span> is restored to its default value
— which happen to be <span class="c013">verbatim</span>.</p><p><a id="hevea_default118"></a>
This example also shows two new ways to specify colours in style
definition, with a
conventional html color name (here <span class="c009">maroon</span>) or as
a high-level color (see Section <a href="#color%3Apackage">B.14.2</a>), given as an argument to
the <code>\@getstylecolor</code> internal command
(here <span style="font-family:monospace;background-color:#FFAD7A">Apricot</span> from the <span class="c013">named</span> color model).</p><p>A good way of specifying style class changes probably is by defining
new environments.
</p><pre class="verbatim">\newenvironment{flashyverbatim}
{\setenvclass{verbatim}{myverbatim}\verbatim}
{\endverbatim}
</pre><p>Then, we can use <code>\begin{flashyverbatim}</code>…
<code>\end{flashyverbatim}</code> to get verbatim environments style with
the intended <span class="c013">myverbatim</span> style class.
</p><pre class="myverbatim">This text is typeset inside the environment
\emph{flashyverbatim}, and hence with the \emph{myverbatim}
style.
</pre>
<!--TOC subsection id="whatclass" Which class affects what-->
<h3 class="subsection" id="whatclass">9.4  Which class affects what</h3><!--SEC END --><p>Generally, the styling of environment <span class="c018">env</span> is performed through
the commands
<code>\getenvclass{</code><span class="c018">env</span><code>}</code>
and <code>\setenvclass{</code><span class="c018">env</span><code>}{</code>…<code>}</code>,
with <code>\getenvclass{</code><span class="c018">env</span><code>}</code> producing the
default value of <span class="c018">env</span>.</p><p>Concretely, this means that most of the environments are styled through
an homonymous style class. Here is a non-exhaustive list of such
environments
</p><blockquote class="quote">
figure, table, itemize, enumerate, list, description,
trivlist, center, flushleft, flushright, quote,
quotation, verbatim, abstract, mathpar (cf
Section <a href="#mathpartir%3Apackage">B.17.15</a>), lstlisting
(cf. Section <a href="#listings%3Apackage">B.17.13</a>), etc.
</blockquote><p>All sectioning commands (<code>\part</code>, <code>\section</code> etc.)
output <code>H<</code><span class="c018">n</span><code>></code> block-level elements, which are styled
through style classes named <span class="c013">part</span>, <span class="c013">section</span>, etc.</p><p>List making-environment introduce extra style classes for items.
More specifically, for list-making environments
<span class="c013">itemize</span> and <span class="c013">enumerate</span>,
<code>li</code> elements are styled as follows:
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c039"><pre class="verbatim"><ul class="itemize">
<li class="li-itemize"> ...
</ul>
</pre></td><td class="c039"><pre class="verbatim"><ol class="enumerate">
<li class="li-enumerate"> ...
</ol>
</pre></td></tr>
</table>
</div><p>
That is, <code>li</code> elements are styled as environments, the key name
being <span class="c013">li-</span><span class="c018">env</span>.</p><p>The <span class="c013">description</span>, <span class="c013">trivlist</span> and <span class="c013">list</span> environments
(which all get translated into <span class="c013">DL</span> elements) are styled in
a similar way, internal <span class="c013">DT</span> and <span class="c013">DD</span> elements being
styles through names <span class="c013">dt-</span><span class="c018">env</span> and
<span class="c013">dd-</span><span class="c018">env</span> respectively.</p>
<!--TOC subsection id="sec79" A few examples-->
<h3 class="subsection" id="sec79">9.5  A few examples</h3><!--SEC END -->
<!--TOC subsubsection id="sec80" The title of the document-->
<h4 class="subsubsection" id="sec80">9.5.1  The title of the document</h4><!--SEC END --><p><a id="hevea_default119"></a>
The command <code>\maketitle</code> formats the document
title within a <code>table</code> element, with
class <span class="c013">title</span>, for display. The name of the title is displayed
inside block <code>h1</code>, with class <span class="c013">titlemain</span>, while all other
information (author, date) are displayed inside block <code>h3</code>, with class
<span class="c013">titlerest</span>.
</p><pre class="verbatim"><table class="title">
<tr>
<td style="padding:1ex">
<h1 class="titlemain">..title here..</h1>
<h3 class="titlerest">..author here..</h3>
<h3 class="titlerest">..date here..</h3>
</td>
</tr>
</table>
</pre><p>Users can impact on title formatting by adding style in the
appropriate style classes.
For instance the following style class definitions:
</p><pre class="verbatim">\newstyle{.title}
{text-align:center;margin:1ex auto;color:navy;border:solid navy;}
\newstyle{.titlerest}{font-variant:small-caps;}
</pre><p>will normally produce a title in dark blue, centered in a box, with
author and date in small-caps.
</p><table class="xtitle"><tr><td style="padding:1ex;">
<h1 class="xtitlemain">Title</h1>
<h3 class="xtitlerest">Date</h3>
<h3 class="xtitlerest">Author</h3>
</td></tr>
</table>
<!--TOC subsubsection id="sec81" Enclosing things in a styled <span class="c013">div</span>-->
<h4 class="subsubsection" id="sec81">9.5.2  Enclosing things in a styled <span class="c013">div</span></h4><!--SEC END --><p>
<a id="hevea_default120"></a><a id="hevea_default121"></a><a id="hevea_default122"></a>At the moment, due to the complexity of the task, environments
<span class="c013">tabular</span> and <span class="c013">array</span> cannot be styled as others
environments can be,
by defining an appropriate class in the preamble.
However, even for such constructs,
limited styling can be performed, by using
the <span class="c013">divstyle</span> environment.
The opening command <code>\begin{divstyle}{</code><span class="c018">class</span><code>}</code>
takes the name of a class as
an argument, and translates to <code><div class="</code><span class="c018">class</span><code>"></code>.
Of course the closing command <code>\end{divstyle}</code> translates to
<code></div></code>.
The limitation is that the enclosed part may generate more html
blocks, and that not all style attribute defined in class class
<span class="c018">class</span> will apply to those inner blocks.</p><p>As an example consider the style class definition below.
</p><pre class="verbatim">\newstyle{.ruled}{border:solid black;padding:1ex;background:\#eeddbb;color:maroon}
</pre><p>The intended behaviour is to add a black border around the inner block
(with some padding), and to have <span class="c009">maroon</span> text over
a light brown background.</p><p>If we, for instance, enclose an <span class="c013">itemize</span> environment, the
resulting effect is more or less what we have expected:
</p><pre class="verbatim">\begin{divstyle}{ruled}
\begin{itemize}
\item A ruled itemize
\item With two items.
\end{itemize}
\end{divstyle}
</pre><div class="ruled">
<ul class="itemize"><li class="li-itemize">
A ruled itemize
</li><li class="li-itemize">With two items.
</li></ul>
</div><p>However, enclosing a centered
<span class="c013">tabular</span> environment in a <span class="c013">divstyle{ruled}</span> one
is less satisfactory.
</p><pre class="verbatim">\begin{divstyle}{ruled}
\begin{center}\begin{tabular}{|c|c|}
\hline \bf English & \bf French\\ \hline
Good Morning & Bonjour\\ Thank You & Merci\\ Good Bye & Au Revoir\\ \hline
\end{tabular}\end{center}
\end{divstyle}
</pre><div class="ruled">
<div class="center"><table class="c001 cellpadding1" border=1><tr><td class="c028"><span class="c022">English</span></td><td class="c028"><span class="c022">French</span></td></tr>
<tr><td class="c028">Good Morning</td><td class="c028">Bonjour</td></tr>
<tr><td class="c028">Thank You</td><td class="c028">Merci</td></tr>
<tr><td class="c028">Good Bye</td><td class="c028">Au Revoir</td></tr>
</table></div>
</div><p>
In the html version of this document,
one sees that the brown background extend on all the width
of the displayed page.</p><p>This problem can be solved by introducing an extra table.
We first open an extra centered table and then only open the
<span class="c013">divstyle</span> environment.
</p><pre class="verbatim">\begin{center}\begin{tabular}{c}
\begin{divstyle}{ruled}
\begin{tabular}{|c|c|}
\hline \bf English & \bf French\\ \hline
Good Morning & Bonjour\\ Thank You & Merci\\ Good Bye & Au Revoir\\
\hline
\end{tabular}
\end{divstyle}
\end{tabular}\end{center}
</pre><p>This works because of the rules that
govern the width of html <code>table</code> elements, which yield
minimal width. This trick is used in
numerous places by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, for instance in document titles, and looks
quite safe.
</p><div class="center"><table class="c002 cellpading0"><tr><td class="c029"><div class="ruled">
<table class="c001 cellpadding1" border=1><tr><td class="c028"><span class="c022">English</span></td><td class="c028"><span class="c022">French</span></td></tr>
<tr><td class="c028">Good Morning</td><td class="c028">Bonjour</td></tr>
<tr><td class="c028">Thank You</td><td class="c028">Merci</td></tr>
<tr><td class="c028">Good Bye</td><td class="c028">Au Revoir</td></tr>
</table>
</div>
</td></tr>
</table></div><p>Another solution is to specify the <span class="c013">display</span> property
of the styling <span class="c013">div</span> block as being <span class="c013">inline-block</span>:
</p><pre class="verbatim">\newstyle{.ruledbis}
{border:solid black;padding:1ex;background:\#eeddbb;color:maroon;display:inline-block;}
</pre><div class="center">
<div class="ruledbis">
<table class="c001 cellpadding1" border=1><tr><td class="c028"><span class="c022">English</span></td><td class="c028"><span class="c022">French</span></td></tr>
<tr><td class="c028">Good Morning</td><td class="c028">Bonjour</td></tr>
<tr><td class="c028">Thank You</td><td class="c028">Merci</td></tr>
<tr><td class="c028">Good Bye</td><td class="c028">Au Revoir</td></tr>
</table>
</div>
</div>
<!--TOC subsubsection id="sec82" Styling the <span class="c013">itemize</span> environment-->
<h4 class="subsubsection" id="sec82">9.5.3  Styling the <span class="c013">itemize</span> environment</h4><!--SEC END --><p>
<a id="hevea_default123"></a>
Our idea is highlight lists with a left border whose color fades
while lists are nested.
Such a design may be appropriate for tables of content, as
the <a href="#ftoc">one of this document</a>.
</p><ul class="toc1"><li class="li-itemize">
Part A
<ul class="toc2"><li class="li-itemize">
Chapter I
<ul class="toc3"><li class="li-itemize">
Section I.1
</li><li class="li-itemize">Section I.2
</li></ul>
</li><li class="li-itemize">Chapter II
<ul class="toc3"><li class="li-itemize">
Section II.1
</li><li class="li-itemize">Section II.2
</li></ul>
</li><li class="li-itemize">Chapter III
</li></ul>
</li><li class="li-itemize">Part B
<ul class="toc2"><li class="li-itemize">
Chapter IV
<ul class="toc3"><li class="li-itemize">
Section IV.1
<ul class="toc4"><li class="li-itemize">
Section IV.1.a
</li><li class="li-itemize">Section IV.1.b
</li></ul>
</li><li class="li-itemize">Section IV.2
</li></ul>
</li><li class="li-itemize">Chapter V
</li></ul>
</li></ul><p>
The text above is typeset from the following L<sup>A</sup>T<sub>E</sub>X source.
</p><pre class="verbatim">\begin{toc}
\item Part~A
\begin{toc}
\item Chapter~I
\begin{toc}
\item Section~I.1
\item Section~I.2
\end{toc}
...
\end{toc}
\end{toc}
</pre><p>For simplicity, we assume a limit of four over the nesting depth of
<span class="c013">toc</span> environment.
We first define four style classes <span class="c013">toc1</span>, <span class="c013">toc2</span>,
<span class="c013">toc3</span> and <span class="c013">toc4</span> in the document preamble.
Since those classes are similar, a command <code>\newtocstyle</code> is
designed.
</p><pre class="verbatim">\newcommand{\newtocstyle}[2]
{\newstyle{.toc#1}{list-style:none;border-left:1ex solid #2;padding:0ex 1ex;}}
\newtocstyle{1}{\@getstylecolor{Sepia}}
\newtocstyle{2}{\@getstylecolor{Brown}}
\newtocstyle{3}{\@getstylecolor{Tan}}
\newtocstyle{4}{\@getstylecolor{Melon}}
</pre><p>The <span class="c013">toc</span> environment uses a counter to record nesting depth.
Notice how the style class of the <span class="c013">itemize</span> environment is
redefined before <code>\begin{itemize}</code>.
</p><pre class="verbatim">\newcounter{toc}
\newenvironment{toc}
{\stepcounter{toc}\setenvclass{itemize}{toc\thetoc}\begin{itemize}}
{\addtocounter{toc}{-1}\end{itemize}}
</pre><p>The outputted html is:
</p><pre class="verbatim"><ul class="toc1"><li class="li-itemize">
Part&nbsp;A
<ul class="toc2"><li class="li-itemize">
Chapter&nbsp;I
<ul class="toc3"><li class="li-itemize">
Section&nbsp;I.1
<li class="li-itemize">Section&nbsp;I.2
...
</ul>
</ul>
</pre>
<!--TOC subsection id="sec83" Miscellaneous-->
<h3 class="subsection" id="sec83">9.6  Miscellaneous</h3><!--SEC END -->
<!--TOC subsubsection id="sec84" H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A and style sheets-->
<h4 class="subsubsection" id="sec84">9.6.1  H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A and style sheets</h4><!--SEC END --><p>
H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A now produces an additional file: a style sheet, which is
shared by all the html files produced by H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A.
Please refer to section <a href="#hacha%3Astyle">7.1</a> for details.</p>
<!--TOC subsubsection id="sec85" Producing an external style sheet-->
<h4 class="subsubsection" id="sec85">9.6.2  Producing an external style sheet</h4><!--SEC END --><p>
<a id="hevea_default124"></a><a id="hevea_default125"></a>By default, style declarations defined with
<code>\newstyle</code> go into the header of the html document
<em>doc</em><span class="c013">.html</span>.
However, one can send those declaration into an external style file,
whose name is <em>doc</em><span class="c013">.css</span>.
Then, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A automatically relates <em>doc</em><span class="c013">.html</span> to
its style sheet <em>doc</em><span class="c013">.css</span>.
To achieve this behaviour, it suffices to set the value of the boolean
register <span class="c013">externalcss</span> to <span class="c018">true</span>, by issuing the command
<code>\externalcsstrue</code> in the preamble of the source document.
Notice that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output still can be processed by H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A, with
correct behaviour.</p>
<!--TOC subsubsection id="sec86" Linking to external style sheets-->
<h4 class="subsubsection" id="sec86">9.6.3  Linking to external style sheets</h4><!--SEC END --><p>
<a id="hevea_default126"></a><a id="hevea_default127"></a>The H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A command <code>\loadcssfile{</code><span class="c018">url</span><code>}</code> allows the
user to link to an external style sheet (like the link option for
HTML). The command takes an <span class="c018">url</span> of the external
sheet as argument and emits the HTML text to
<em>link</em> to the given external style sheet. As an example, the command
</p><pre class="verbatim">\loadcssfile{../abc.css}
</pre><p>produces the following html text in the <code>head</code> of the document.
</p><pre class="verbatim"> <link rel="stylesheet" type="text/css" href="../abc.css">
</pre><p>To yield some effect, <code>\loadcssfile</code> must appear in the document
preamble. Several <code>\loadcssfile</code> commands can be issued. Then
the given external style sheets appear in the output, following source
order.</p><p>Notice that the argument to <code>\loadcssfile</code> is processed. Thus, if it
contains special characters such as “#” or “$”, those must be specified
as <code>\#</code> and <code>\$</code> respectively.
A viable alternative would be to quote
the argument using the <code>\url</code> command from the <span class="c013">url</span>
package (see Section <a href="#urlpackage">B.17.11</a>).</p>
<!--TOC subsubsection id="sec87" Limitations-->
<h4 class="subsubsection" id="sec87">9.6.4  Limitations</h4><!--SEC END --><p>
At the moment, style class definitions cumulate, and appear
in the <code>style</code> element in the order they are given in the
document source. There is no way to cancel the default class
definitions performed by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A before it starts to process the
user’s document.
Additionally, external style sheets specified with <code>\loadcssfile</code>
appear before style classes defined with <code>\newstyle</code>.
As a consequence (if I am right), styles
declared by <code>\newstyle</code> take precedence over those contained in
external style sheets. Thus, using external style-sheets, especially
if they alter the styling of elements, may produce awkward results.</p><p>Those limitations do not apply of course to style classes whose
names are new, since there cannot be default definitions for them.
Then, linking with external style sheets can prove useful to
promote uniform styling of several documents produced by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.</p>
<!--TOC section id="sec88" Customising H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A-->
<h2 class="section" id="sec88">10  Customising H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A</h2><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can be controlled by writing L<sup>A</sup>T<sub>E</sub>X code. In this section,
we examine how users can change H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A default behaviour or add
functionalities. In all this section we assume that a document
<span class="c013">doc.tex</span> is processed, using a private command file
<span class="c013">macros.hva</span>. That is, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is invoked as:
</p><pre class="verbatim"># hevea macros.hva doc.tex
</pre><p>The general idea is as follows: one redefines L<sup>A</sup>T<sub>E</sub>X constructs in
<span class="c013">macros.hva</span>, using internal commands. This requires a good
working knowledge of both L<sup>A</sup>T<sub>E</sub>X and html.
Usually, one can avoid internal commands, but then, all command
redefinitions interact, sometimes in very nasty ways.</p>
<!--TOC subsection id="sec89" Simple changes-->
<h3 class="subsection" id="sec89">10.1  Simple changes</h3><!--SEC END --><p>
Users can easily change the rendering of some constructs. For
instance, assume that <em>all</em> quotations in a text should be
emphasised. Then, it suffices to put the following re-declaration in
<span class="c013">macros.hva</span>:
</p><pre class="verbatim">\renewenvironment{quote}
{\@open{blockquote}{}\@style{em}}
{\@close{blockquote}}
</pre><p>The same effect can be achieved without using any of the internal
commands:
</p><pre class="verbatim">\let\oldquote\quote
\let\oldendquote\endquote
\renewenvironment{quote}{\oldquote\em}{\oldendquote}
</pre><p>In some sense, this second
solution is easier, when one already knows
how to customise L<sup>A</sup>T<sub>E</sub>X. However, this is less safe, since the definition of
<code>\em</code> can be changed elsewhere.</p><p>There is yet another solution that takes advantage of style sheets.
One can also add this line to the <span class="c013">macros.hva</span> file:
</p><pre class="verbatim">\newstyle{.quote}{font-style:oblique;}
</pre><p>This works because the environment <span class="c013">quote</span> is styled through
style class <span class="c013">quote</span> (see Section <a href="#css%3Achange%3Aall">9.2</a>).
Notice that this solution has very little to do with
“<em>emphasising</em>” in the proper sense, since here we
short-circuit the implicit path from <code>\em</code> to oblique fonts.</p>
<!--TOC subsection id="sec90" Changing defaults for type-styles-->
<h3 class="subsection" id="sec90">10.2  Changing defaults for type-styles</h3><!--SEC END --><p><a id="customize-style"></a>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A default rendering of type style changes is described in
section <a href="#type-style">B.15.1</a>.
For instance, the following example shows the default rendering
for the font shapes:
</p><pre class="verbatim">\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape
</pre><p>By default, <code>\itshape</code> is italics, <code>\slshape</code> is oblique
italics, <code>\scshape</code> is small-caps (thanks to style sheets) and <code>\upshape</code> is no style at all.
All shapes are mutually exclusive, this means that each shape
declaration cancels the effect of other active shape declarations.
For instance, in the example, small caps shapes is small caps (no italics here).
</p><blockquote class="quote">
<span class="c018">italic shape </span><span class="c019">slanted shape
</span><span class="c020">small caps shape </span>upright shape
</blockquote><p>If one wishes to change the rendering of some of the shapes (say slanted
caps), then one should redefine the old-style <code>\sl</code> declaration.
For instance, to render slanted as Helvetica (why so?), one should
redefine <code>\sl</code> by <code>\renewcommand{\sl}{\@span{style="font-family:Helvetica"}}</code> in
<span class="c013">macros.hva</span>.</p><p>
And now, the shape example above gets rendered as follows:
</p><blockquote class="quote">
<span class="c018">italic shape </span><span class="c012">slanted shape
</span><span class="c020">small caps shape </span>upright shape
</blockquote><p>Redefining the old-style <code>\sl</code> is compatible with the cancellation
mechanism, redefining <code>\slshape</code> is not.
Thus, redefining directly L<sup>A</sup>T<sub>E</sub>X 2є <code>\slshape</code> with
<code>\renewcommand{\slshape}{}</code> would yield:
</p><blockquote class="quote">
<span class="c018">italic shape <span class="c012">slanted shape
</span></span><span class="c012"><span class="c020">small caps shape </span>upright shape</span>
</blockquote><p>Hence, redefining old-style declarations using internal commands
should yield satisfactory output.
However, since cancellation is done at the html
level, a declaration belonging to one component may sometimes cancel the
effect of another that belongs to another component.
Anyway, you might have not noticed it if I had not told you.</p>
<!--TOC subsection id="sec91" Changing the interface of a command-->
<h3 class="subsection" id="sec91">10.3  Changing the interface of a command</h3><!--SEC END --><p><a id="customize-let"></a>
Assume for instance that the base style of <span class="c013">doc.tex</span> is
<span class="c018">jsc</span> (the
<em>Journal of Symbolic Computation</em> style for articles).
For running H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, the <span class="c018">jsc</span> style can be replaced by
<span class="c018">article</span>
style, but for a few commands whose calling interface is changed.
In particular, the <code>\title</code> command
takes an extra optional argument (which H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A should ignore
anyway).
However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can process the document as it stands.
One solution to insert the following lines into <span class="c013">macros.hva</span>:
</p><pre class="verbatim">\input{article.hva}% Force document class 'article'
\let\oldtitle=\title
\renewcommand{\title}[2][]{\oldtitle{#2}}
</pre><p>The effect is to replace <code>\title</code> by a new command which
calls H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A <code>\title</code> with the appropriate argument.
</p>
<!--TOC subsection id="sec92" Checking the optional argument within a command-->
<h3 class="subsection" id="sec92">10.4  Checking the optional argument within a command</h3><!--SEC END --><p><a id="fullepsfbox"></a>
<a id="hevea_default128"></a>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A fully implements L<sup>A</sup>T<sub>E</sub>X 2є <code>\newcommand</code>.
That is, users can define commands with an optional argument.
Such a feature permits to write a <code>\epsfbox</code> command that
has the same interface as the L<sup>A</sup>T<sub>E</sub>X command and
echoes itself as it is invoked to the <span class="c018">image</span> file.
To do this, the H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A <code>\epsfbox</code> command has to check
whether it is invoked with an optional argument or not.
This can be achieved as follows:
</p><pre class="verbatim">\newcommand{\epsfbox}[2][!*!]{%
\ifthenelse{\equal{#1}{!*!}}
{\begin{toimage}\epsfbox{#2}\end{toimage}}%No optional argument
{\begin{toimage}\epsfbox[#1]{#2}\end{toimage}}}%With optional argument
\imageflush}
</pre>
<!--TOC subsection id="sec93" Changing the format of images-->
<h3 class="subsection" id="sec93">10.5  Changing the format of images</h3><!--SEC END --><p>
<a id="hevea_default129"></a>
<a id="hevea_default130"></a>
<a id="hevea_default131"></a>
<a id="hevea_default132"></a>
<a id="hevea_default133"></a>
Semi-automatic generation of included images is described in
section <a href="#imagen">6</a>.
Links to included images are generated by the <code>\imageflush</code>
command, which calls the <code>\imgsrc</code> command:
</p><pre class="verbatim">\newcommand{\imageflush}[1][]
{\@imageflush\stepcounter{image}\imgsrc[#1]{\hevaimagedir\jobname\theimage\heveaimageext}}
</pre><p>That is, you may supply a html-style attribute to the included image,
as an optional argument to the <code>\imageflush</code> command.</p><p>By default, images are PNG images stored in <span class="c013">.png</span> files.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A provides support for the alternative GIF image file format.
It suffices to invoke <span class="c013">hevea</span> as:
</p><div class="flushleft">
<span class="c013"># hevea gif.hva</span> <span class="c018">doc.tex</span>
</div><p>
Then <span class="c013">imagen</span> must be run with option <a id="hevea_default134"></a><span class="c013">-gif</span>:
</p><div class="flushleft">
<span class="c013"># imagen -gif</span> <em>doc</em>
</div><p>A convenient alternative is to invoke <span class="c013">hevea</span> as:
</p><div class="flushleft">
<span class="c013"># hevea -fix gif.hva</span> <span class="c018">doc.tex</span>
</div><p>
Then <span class="c013">hevea</span> will invoke <span class="c013">imagen</span> with the appropriate
option when it thinks images need to be rebuild.</p>
<!--TOC subsection id="sec94" Storing images in a separate directory-->
<h3 class="subsection" id="sec94">10.6  Storing images in a separate directory</h3><!--SEC END --><p>
<a id="hevea_default135"></a>
By redefining the <code>\heveaimagedir</code> command, users can specify a
directory for images.
More precisely, if the following redefinition occurs in the document
preamble.
</p><div class="flushleft">
<code>\renewcommand{\heveaimagedir}{</code><span class="c018">dir</span><code>}</code>
</div><p>
Then, all links to images in the produced html file will be as
“<span class="c018">dir</span>/…”.
Then <span class="c013">imagen</span> must be invoked with option <a id="hevea_default136"></a><span class="c013">-
todir</span>:
</p><div class="flushleft">
<span class="c013"># imagen -todir</span> <span class="c018">dir</span> <em>doc</em>
</div><p>
As usual, <span class="c013">hevea</span> will invoke <span class="c013">imagen</span> with the
appropriate option, provided it is passed the <span class="c013">-fix</span> option.</p>
<!--TOC subsection id="imagen-source" Controlling <span class="c013">imagen</span> from document source-->
<h3 class="subsection" id="imagen-source">10.7  Controlling <span class="c013">imagen</span> from document source</h3><!--SEC END --><p>
<a id="hevea_default137"></a>
The internal command
<code>\@addimagenopt{</code><span class="c018">option</span><code>}</code> add
the text <span class="c018">option</span> to <span class="c013">imagen</span> command-line options, when
launched automatically by <span class="c013">hevea</span> (<em>i.e.</em> when
<span class="c013">hevea</span> is given the <a id="hevea_default138"></a><span class="c013">-fix</span> command-line option).</p><p>For instance, to instruct <span class="c013">hevea</span>/<span class="c013">imagen</span> to
reduce all images by a factor of √<span style="text-decoration:overline">2</span>, it suffices to state:
</p><div class="flushleft">
<span class="c013">%HEVEA</span><code>\@addimagenopt{-mag 707}</code>
</div><p>
See section <a href="#imagenusage">C.1.5</a> for the list of command-line options
accepted by <span class="c013">imagen</span>.</p>
<!--TOC section id="alternative" Other output formats-->
<h2 class="section" id="alternative">11  Other output formats</h2><!--SEC END --><p>
It is possible to translate L<sup>A</sup>T<sub>E</sub>X file into other formats than
html. There are two such formats: plain text and info files.
This enables producing postscript,
html, plain text and info manuals from one (L<sup>A</sup>T<sub>E</sub>X) input file.</p>
<!--TOC subsection id="sec97" Text-->
<h3 class="subsection" id="sec97">11.1  Text</h3><!--SEC END --><p>
The L<sup>A</sup>T<sub>E</sub>X file is processed and converted into a plain text
formatted file. It allows some pretty-printing in plain text.</p><p>To translate into text, invoke H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A as follow:
</p><pre class="verbatim"># hevea -text [-w <width>] myfile.tex
</pre><p>Then, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A produces <span class="c013">myfiles.txt</span> a plain text translation
of <span class="c013">myfile.tex</span>.</p><p>Additionally, the optional argument <span class="c013">-w <number></span> sets the
width of the output for text formatting. By default, The text will be
72 characters wide.</p><p>Nearly every environment has been translated, included lists and tables.
The support is nearly the same as in html, excepted in some cases
described hereafter.</p><p>Most style changes are ignored, because it is hardly
possible to render them in plain text. Thus, there are no italics,
bold fonts, underlinings, nor size change or colours…
The only exception is for the verbatim environment
that puts the text inside quotes, to distinguish it more easily.</p><p>Tables with borders are rendered in the same spirit as in L<sup>A</sup>T<sub>E</sub>X.
Thus for instance, it is possible to get vertical lines between some
columns only.
Table rendering can be poor in case of line overflow.
The only way to correct this (apart from changing the tables
themselves) is to adjust the formatting width, using the
the <a id="hevea_default139"></a><span class="c013">-w</span> command-line option.</p><p>For now, maths are not supported at all in text mode. You can get very weird
results with in-text mathematical formulas.
Of course, simple expressions such as subscripts remains readable.
For instance, <span class="c018">x</span><sup>2</sup> will be rendered as <code>x^2</code>, but ∫<sub>0</sub><sup>1</sup><span class="c018">f</span>(<span class="c018">x</span>)<span class="c018">dx</span> will
yield something like : <code>int01f(x)dx</code>.</p>
<!--TOC subsection id="sec98" Info-->
<h3 class="subsection" id="sec98">11.2  Info</h3><!--SEC END --><p>
The file format info is also supported.
Info files are text files with limited hypertext links, they
can be read by using <em>emacs</em> info mode or the
<span class="c013">info</span> program.
Please note that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A translates plain L<sup>A</sup>T<sub>E</sub>X to info, and not
TeXinfo.</p><p>You can translate your L<sup>A</sup>T<sub>E</sub>X files into info file(s) as follows:
</p><pre class="verbatim"># hevea -info [-w <width>] myfile.tex
</pre><p>Then, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A produces the file <span class="c013">myfile.info</span>, an info
translation of <span class="c013">myfile.tex</span>.
However, if the resulting file is too large, it is cut into pieces
automatically,
and <span class="c013">myinfo.info</span> now contains references for all
the nodes in the others files, which are named <span class="c013">myfile.info-1</span>,
<span class="c013">myfile.info-2</span>,…</p><p>The optional argument <code>-w</code> has the same meaning as for text output.</p><p>The text will be organised in nodes that follow
the pattern of L<sup>A</sup>T<sub>E</sub>X sectioning
commands. Menus are created to navigate through the sections easily</p><p>A table of content is produced automatically.
References, indexes and footnotes are supported, as they are in
html mode.
However, the info format only allows pointers to info nodes,
<em>i.e.</em> in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A case, to sectional units.
As a consequence all cross references lead to sectional unit headers.</p><!--CUT END -->
<!--TOC part id="sec99" Reference manual-->
<table class="center"><tr><td><h1 class="part" id="sec99">Part B<br>
Reference manual</h1></td></tr>
</table><!--SEC END --><p>
<a id="referencemanual"></a>
</p><!--CUT DEF section --><p>
This part follows the pattern of the L<sup>A</sup>T<sub>E</sub>X reference
manual [<a href="#latex">L<sup>A</sup>T<sub>E</sub>X</a>, Appendix C].</p>
<!--TOC section id="sec100" Commands and Environments-->
<h2 class="section" id="sec100">B.1  Commands and Environments</h2><!--SEC END -->
<!--TOC subsection id="sec101" Command Names and Arguments-->
<h3 class="subsection" id="sec101">B.1.1  Command Names and Arguments</h3><!--SEC END --><p>L<sup>A</sup>T<sub>E</sub>X comments that start with “<code>%</code>” and end at end of line are ignored and produce no output.
Usually, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A ignore such comments. However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A processes
text that follows “<code>%HEVEA</code>” and some other comments have a specific meaning to it (see
section <a href="#comments">5.3</a>).</p><p><a id="hevea_default140"></a>
Command names follow strict L<sup>A</sup>T<sub>E</sub>X syntax. That is, apart from
<code>#</code>, <code>$</code>, <code>~</code>, <code>_</code> and <code>^</code>, they either are
“<code>\</code>” followed by a single non-letter character or
“<code>\</code>” followed by a sequence of letters.
Additionally, the letter sequence may be preceded by “<code>@</code>”
(and this is the case of many of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A internal commands), or
terminated by “<code>*</code>” (starred variants are implemented as plain
commands).</p><p>Users are strongly advised to follow strict L<sup>A</sup>T<sub>E</sub>X syntax for
arguments. That is, mandatory arguments are enclosed in curly braces
<code>{</code>… <code>}</code> and braces inside arguments must be properly
balanced.
Optional arguments are enclosed in square brackets <code>[</code>…
<code>]</code>.
However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does its best to read arguments even when they are
not enclosed in curly braces.
Such arguments are a single, different from “<code>\</code>”, “<code>{</code>”
and “<code> </code>”, character or
a command name.
Thus, constructs such as <code>\'ecole</code>,
<code>$a_1$</code> or <code>$a_\Gamma$</code> are
recognized and processed as école <span class="c018">a</span><sub>1</sub> and <span class="c018">a</span><sub>Γ</sub>.
By contrast, <code>a^\mbox{...}</code> is not recognized
and must be written <code>a^{\mbox{...}}</code>.</p><p>Also note that, by contrast with L<sup>A</sup>T<sub>E</sub>X, comments are parsed during
argument scanning, as an important consequence brace nesting is also
checked inside comments.</p><p><a id="hevea_default141"></a>
<a id="hevea_default142"></a>
With respect to previous versions,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A has been improved as regards emulation of complicated
argument passing. That is,
commands and their arguments can now appear in
different static text bodies. As a consequence,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A correctly processes the following source:
</p><pre class="verbatim">\newcommand{\boite}{\textbf}
\boite{In bold}
</pre><p>The definition of <code>\boite</code> makes it reduces as
<code>\textbf</code> and H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A succeeds in fetching the argument
“<code>{In bold}</code>”. We get
</p><blockquote class="quote">
<span class="c022">In bold</span>
</blockquote><p>The above example arguably is no “legal” L<sup>A</sup>T<sub>E</sub>X,
but H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A handles it.
Of course, there remains
numerous “clever” L<sup>A</sup>T<sub>E</sub>X tricks that exploits T<sub>E</sub>X internal
behaviour, which H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not handle.
For instance consider the following source:
</p><pre class="verbatim">\newcommand{\boite}[1]{\textbf#1}
\boite{{In bold}, Not in Bold.}
</pre><p>L<sup>A</sup>T<sub>E</sub>X typesets the text “In bold” using bold font, leaving
the rest of the text alone. While H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A typesets everything using
bold font. Here is H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output:
</p><blockquote class="quote">
<span class="c022">In bold, Not in Bold.</span>
</blockquote><p>
Note that, in most similar situations, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will likely crash.</p><p>As a conclusion of this important section,
Users are strongly advised to use ordinary command names and
curly braces and not to think too much the T<sub>E</sub>X way.</p>
<!--TOC subsection id="sec102" Environments-->
<h3 class="subsection" id="sec102">B.1.2  Environments</h3><!--SEC END --><p>Environment opening and closing is performed like in L<sup>A</sup>T<sub>E</sub>X, with
<code>\begin{</code><span class="c018">env</span><code>}</code> and
<code>\end{</code><span class="c018">env</span><code>}</code>.
The <code>*</code>-form of an environment is a plain environment.</p><p>It is not advised to use <code>\</code><span class="c018">env</span> and
<code>\end</code><span class="c018">env</span> in place of <code>\begin{</code><span class="c018">env</span><code>}</code> and
<code>\end{</code><span class="c018">env</span><code>}</code>.</p>
<!--TOC subsection id="sec103" Fragile Commands-->
<h3 class="subsection" id="sec103">B.1.3  Fragile Commands</h3><!--SEC END --><p>
Fragile commands are not relevant to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and <code>\protect</code> is
defined as a null command.</p>
<!--TOC subsection id="sec104" Declarations-->
<h3 class="subsection" id="sec104">B.1.4  Declarations</h3><!--SEC END --><p>
Scope rules are the same as in L<sup>A</sup>T<sub>E</sub>X.</p>
<!--TOC subsection id="sec105" Invisible Commands-->
<h3 class="subsection" id="sec105">B.1.5  Invisible Commands</h3><!--SEC END --><p>
I am a bit lost here. However spaces in the output should correspond
to users expectations. Note that, to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A being
invisible commands is a static property attached to command name.</p>
<!--TOC subsection id="sec106" The <span class="c013">\\</span> Command-->
<h3 class="subsection" id="sec106">B.1.6  The <span class="c013">\\</span> Command</h3><!--SEC END --><p>The <code>\\</code> and <code>\\*</code> commands are the same, they perform a
line break, except inside arrays where they end the current row.
Optional arguments to <code>\\</code> and <code>\\*</code> are ignored.</p>
<!--TOC section id="sec107" The Structure of the Document-->
<h2 class="section" id="sec107">B.2  The Structure of the Document</h2><!--SEC END --><p><a id="structure"></a>
Document structure is a bit simplified with respect to L<sup>A</sup>T<sub>E</sub>X, since
documents consist of only two parts.
The <em>preamble</em> starts as soon as H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A starts to operate and
ends with the <code>\begin{document}</code> construct.
Then, any input occurring before
<code>\end{document}</code> is translated to html.
However, the preamble is processed
and the preamble comprises the content of the files given as command-line
arguments to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, see section <a href="#comline">C.1.1.1</a>).
As a consequence, command and environment definitions that
occur before <code>\begin{document}</code> are performed.
and they remain
valid during all the processing.</p><p><a id="hevea_default143"></a>
<a id="hevea_default144"></a>
In particular one can define a <em>header</em> and a <em>footer</em>, by using the
<code>\htmlhead</code> and <code>\htmlfoot</code> commands in the preamble.
Those commands register their argument as the header and the footer of
the final html document. The header appears first while the footer
appears last in (visible) html output.
This is mostly useful when H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output is later cut into pieces by
H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A, since both header and footer are replicated
at the start and end of any file generated by H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A.
For instance, to append a copyright notice at the end of all the html
pages, it suffices to invoke the <code>\htmlfoot</code> command as follows
in the document preamble:
</p><pre class="verbatim">\htmlfoot{\copyright to me}
</pre><p><a id="hevea_default145"></a>
<a id="hevea_default146"></a>
<a id="hevea_default147"></a><a id="metadef"></a>
The <code>\htmlhead</code> command cannot be used for changing anything outside of
the html document body, there are specific commands for doing this.
Those command must be used in the document preamble.
One can
change H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A default (empty) attribute for
the opening <code><body ...></code> tag by redefining
<code>\@bodyargs</code>.
For instance, you get black text on a white background, when the
following declaration occurs before <code>\begin{document}</code>:
</p><pre class="verbatim">\renewcommand{\@bodyargs}{style="color:black;background:white"}
</pre><p>Since version 1.08, a recommended alternative is to use style sheets:
</p><pre class="verbatim">\newstyle{body}{color:black; background:white;}
</pre><p><a id="hevea_default148"></a><a id="hevea_default149"></a>
<a id="exlet"></a>Similarly, some elements can be inserted into the output file
<code>head</code> element by redefining the <code>\@meta</code> command
(Such elements typically are <code>meta</code>, <code>link</code>, etc.).
As such text is pure html, it should be included in a
<code>rawhtml</code> environment. For instance, you can specify
author information as follows:
</p><pre class="verbatim">\let\oldmeta=\@meta
\renewcommand{\@meta}{%
\oldmeta
\begin{rawhtml}
<meta name="Author" content="Luc Maranget">
\end{rawhtml}}
</pre><p>Note how <code>\@meta</code> is first bound to
<code>\oldmeta</code> before being redefined and how <code>\oldmeta</code> is
invoked in the new definition of <code>\@meta</code>.
Namely, simply overriding the old definition of <code>\@meta</code> would
imply not outputting default meta-information.</p><p><a id="hevea_default150"></a>
The <code>\@charset</code> command holds the value of the (html) document character
set. By default, this value is <span class="c013">US-ASCII</span>.
In previous versions of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, one could change the
value of the document character set by simply redefining
<code>\@charset</code>. Then, it was users responsability to provide a
(L<sup>A</sup>T<sub>E</sub>X) document in the correspounding encoding.
This is no longer so, and users should <em>not</em> redefine
<code>\@charset</code> directly. Please, see Section <a href="#encodings">8.6</a> for details.</p>
<!--TOC section id="sec108" Sentences and Paragraphs-->
<h2 class="section" id="sec108">B.3  Sentences and Paragraphs</h2><!--SEC END -->
<!--TOC subsection id="sec109" Spacing-->
<h3 class="subsection" id="sec109">B.3.1  Spacing</h3><!--SEC END --><p>
<a id="hevea_default151"></a>
<a id="hevea_default152"></a>
Generally speaking, spaces (and single newline characters) in the
source are echoed in the output. Browser then manage with spaces and
line-breaks. Following L<sup>A</sup>T<sub>E</sub>X behaviour, spaces after commands are
not echoed. Spaces after invisible commands with arguments are not
echoed either.</p><p>However this is no longer true in math mode, see
section <a href="#spacemathref">B.7.7</a> on spaces in math mode.</p>
<!--TOC subsection id="sec110" Paragraphs-->
<h3 class="subsection" id="sec110">B.3.2  Paragraphs</h3><!--SEC END --><p>
New paragraphs are introduced by one blank line or more.
Paragraphs are not indented. Thus the macros <code>\indent</code> and
<code>\noindent</code> perform no action.
Paragraph are rendered by <code>p</code> elements.
In some occasions, this technique may produce spurious paragraphs
(see <a href="#spurious%3Apar">3.1.1</a>).</p>
<!--TOC subsection id="sec111" Footnotes-->
<h3 class="subsection" id="sec111">B.3.3  Footnotes</h3><!--SEC END --><p>
The commands <code>\footnote</code>,
<code>\footnotetext</code> and <code>\footnotemark</code> (with or without
optional arguments) are supported.
The <code>footnote</code> counter exists and (re)setting it or redefining
<code>\thefootnote</code> should work properly.
When footnotes are issued by a combination of <code>\footnotemark</code> and
<code>\footnotetext</code>, a <code>\footnotemark</code>
command must be issued
first, otherwise some footnotes may get numbered incorrectly or disappear.
Footnotes appear at document end in the <em>article</em> style and
at chapters end in the <em>book</em> style.
See section <a href="#hachafoot">7.3.6</a> for a description of how footnotes are flushed.</p>
<!--TOC subsection id="accents" Accents and special symbols-->
<h3 class="subsection" id="accents">B.3.4  Accents and special symbols</h3><!--SEC END --><p>
Thanks to Unicode character references, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can virtually output
any symbol.
It may happen that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not known about a particular symbol,
that is, most of the time, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not known about a particular
command. In that case a warning is issued to draw user attention.
Users can then choose a particular symbol amongst the recognized ones,
or as an explicit Unicode character reference (see
Section <a href="#square%3Ablob">4.2</a> for an example of this technique).</p><p>Commands for making accents used in non-English languages, such as
<code>\'</code>, work when applied to accent-less (<em>i.e.</em> ascii)
letters and that the corresponding accented letters exist
in the Unicode character set.
Otherwise, the argument to the command is not modified
and a warning is issued.
For instance, consider the following source code, where, after a
legitimate use of acute accents, one attempt to put an accute accent
over the letter “h”:
</p><pre class="verbatim">``\'Ecole'' works as in \LaTeX, while ``\'h'' does not.
</pre><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output will be “École” works as in L<sup>A</sup>T<sub>E</sub>X, while “h” does not.
And a warning will be issued.
</p><pre class="verbatim">./tmp.tex:3741: Warning: Application of '\'' on 'h' failed
</pre><p>Observe that using input encodings
is a convenient alternative to accent commands —
see Section <a href="#inputenc">B.17.4</a>.</p>
<!--TOC section id="sec113" Sectioning-->
<h2 class="section" id="sec113">B.4  Sectioning</h2><!--SEC END --><!--NAME sectioning.html-->
<!--TOC subsection id="section:section" Sectioning Commands-->
<h3 class="subsection" id="section:section">B.4.1  Sectioning Commands</h3><!--SEC END --><p>
Sectioning commands from <code>\part</code> down to
<code>\subparagraph</code> are defined in base style files.
They accept an optional argument and have starred versions.</p><p>The non-starred sectioning commands from <code>\part</code> down to
<code>\subsubsection</code> show section numbers in sectional unit headings,
provided their <span class="c018">level</span> is greater than or equal to the current
value of the <code>secnumdepth</code> counter.
Sectional unit levels and the default value of the <code>secnumdepth</code> counter
are the same as in L<sup>A</sup>T<sub>E</sub>X.
Furthermore, given a sectional unit <span class="c018">secname</span>, the
counter <span class="c018">secname</span> exists and the appearance of sectional units
numbers can be changed by redefining <code>\the</code><span class="c018">secname</span>.
For instance, the following redefinition turn the numbering of
chapters into alphabetic (uppercase) style:
</p><pre class="verbatim">\renewcommand{\thechapter}{\Alph{chapter}}
</pre><p><a id="hevea_default153"></a>When jumping to anchors, browsers put the targeted line on top
of display. As a consequence, in the following code:
</p><pre class="verbatim">\section{A section}
\label{section:section}
...
See Section~\ref{section:section}
</pre><p>Clicking on the link produced by
<code>\ref{section:section}</code> will result in <em>not</em> displaying the
targeted section title.
A fix is writing:
</p><pre class="verbatim">\section{\label{section:section}A section}
...
See Section~\ref{section:section}
</pre><p>Starting with version 2.04, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A will use the label name
(<code>section:section</code> above) for the table of contents they generate.
For instance, the source code for the next sectioning command just
below is:
</p><pre class="verbatim">\subsection{The \label{appendix}Appendix}
</pre><p>As a consequence, the link to the next section on top
of this page should read as:
</p><pre class="verbatim"><a href="sectioning.html#appendix">The Appendix</a>
</pre><p>That is, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A used the label name given in source as
an anchor.
Notice that this behaviour applies to the <code>\label</code> command
that occurs first in the sectioning command argument.</p>
<!--TOC subsection id="appendix" The Appendix-->
<h3 class="subsection" id="appendix">B.4.2  The Appendix</h3><!--SEC END --><p>
The <code>\appendix</code> command exists and should work as in L<sup>A</sup>T<sub>E</sub>X.</p>
<!--TOC subsection id="sec116" Table of Contents-->
<h3 class="subsection" id="sec116">B.4.3  Table of Contents</h3><!--SEC END --><p>
<a id="hevea_default154"></a><a id="hevea_default155"></a>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A now generates a table of contents, using a procedure similar
to the one of L<sup>A</sup>T<sub>E</sub>X(a <span class="c013">.htoc</span> file is involved).
One inserts this table of contents in the main document by issuing
the command <code>\tableofcontents</code>.
Table of contents is controlled by the counter <code>tocdepth</code>.
By default, the table of contents shows sectioning units down to the
subsubsection level in <span class="c018">article</span> style and down to the subsection level
in <span class="c018">book</span> (or <span class="c018">report</span>) style. To include more or less
sectioning units in the
table of contents, one should increase or decrease the <code>tocdepth</code>
counter.
It is important to notice that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A produces such a table of
contents, only when it has total control over cross-references.
More precisely, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A cannot produce the table of contents when it
reads L<sup>A</sup>T<sub>E</sub>X-produced <span class="c013">.aux</span> files.
Instead, it should read its own <span class="c013">.haux</span> files.
This will naturally occur if no <span class="c013">.aux</span> files are present,
otherwise these <span class="c013">.aux</span> files should be deleted, or H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
should be instructed not to read them with the command-line option
<a id="hevea_default156"></a><span class="c013">-fix</span>
(see Sections <a href="#files">B.11.1</a> and  <a href="#heveaoptions">C.1.1.4</a>).</p><p>One can also add extra entries in the table of contents by using
the command <code>\addcontentslines</code>, in a way similar
to L<sup>A</sup>T<sub>E</sub>X homonymous command.
However, hyperlinks need to be introduced explicitly,
as in the following example, where
an anchor is defined in the section title and referred to in the
argument to <code>\addcontentsline</code>:
</p><pre class="verbatim">\subsection*{\aname{no:number}{Use \hacha{}}}
\addcontentsline{toc}{subsection}{\ahrefloc{no:number}{Use \hacha{}}}
</pre><p>(See Section <a href="#hyperlink">8.1.1</a> for details on commands related to hyperlinks.)</p><p>There is no list of figures nor list of tables.</p><!--TOC subsection id="sec117" Use H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A-->
<h3 class="subsection" id="sec117"><a id="no:number">Use H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A</a></h3><!--SEC END --><p>
However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A has a more sophisticated way of producing
a kind of map w.r.t. the sectioning of the document.
A later run of H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A on H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output file splits it
in smaller files organized in a tree whose nodes are tables of
links.
By contrast with L<sup>A</sup>T<sub>E</sub>X, starred sectioning commands generate
entries in these tables of contents.
Table of contents entries hold the optional argument to sectioning
commands or their argument when there is no optional
argument. Section <a href="#hacha">7</a> explains how to
control H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A.</p>
<!--TOC section id="sec118" Classes, Packages and Page Styles-->
<h2 class="section" id="sec118">B.5  Classes, Packages and Page Styles</h2><!--SEC END -->
<!--TOC subsection id="sec119" Document Class-->
<h3 class="subsection" id="sec119">B.5.1  Document Class</h3><!--SEC END --><p>
Both L<sup>A</sup>T<sub>E</sub>X 2є <code>\documentclass</code> and old L<sup>A</sup>T<sub>E</sub>X
<code>\documentstyle</code> are accepted.
Their argument <em>style</em> is interpreted by attempting to load a
<em>style</em><span class="c013">.hva</span> file.
Presently, only the style files <span class="c013">article.hva</span>, <span class="c013">seminar.hva</span>,
<span class="c013">book.hva</span> and <span class="c013">report.hva</span> exist, the latter two
being equivalent.</p><p>If one of the recognized styles has already been loaded at the time when
<code>\documentclass</code> or
<code>\documentstyle</code> is executed, then no attempt to load a style
file is made. This allows to override the document style file by
giving one of the four recognized style files of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A as a command
line argument (see <a href="#otherbase">2.2</a>).</p><p>Conversely, if H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A attempt to load <em>style</em><span class="c013">.hva</span>
fails, then a fatal error is flagged, since it can be sure
that the document cannot be processed.</p>
<!--TOC subsection id="sec120" Packages and Page Styles-->
<h3 class="subsection" id="sec120">B.5.2  Packages and Page Styles</h3><!--SEC END --><p><a id="usepackage"></a>
<a id="hevea_default157"></a>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A reacts to
<code>\usepackage[</code><span class="c018">options</span><code>]{</code><span class="c018">pkg</span><code>}</code> in
the following way:
</p><ol class="enumerate" type=1><li class="li-enumerate">
The whole
<code>\usepackage</code> command with its arguments gets echoed to the
<em>image</em> file (see <a href="#imagen">6</a>).
</li><li class="li-enumerate">H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A attempt to load file <span class="c018">pkg</span><span class="c013">.hva</span>,
(see section <a href="#search%3Apath">C.1.1.1</a> on where H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A searches for files).
</li></ol><p>
Note that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will not fail if it cannot load
<span class="c018">pkg</span><span class="c013">.hva</span> and that no warning is issued in that case.</p><p>The H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A distribution contains implementations of some packages,
such as <span class="c013">verbatim</span>, <span class="c013">colors</span>, <span class="c013">graphics</span>, etc.</p><p>In some situations it may not hurt at all if H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not
implement a package, for instance H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not provide an
implementation for the <span class="c013">fullpage</span> package.</p><p>Users needing an implementation of a package that is widely used and
available are encouraged to contact the
<a href="mailto:Luc.Maranget@inria.fr">author</a>.
Experienced users may find it fun to attempt to write package
implementations by themselves.</p>
<!--TOC subsection id="sec121" The Title Page and Abstract-->
<h3 class="subsection" id="sec121">B.5.3  The Title Page and Abstract</h3><!--SEC END --><p>
All title related commands exist, with the following peculiarities:
</p><ul class="itemize"><li class="li-itemize">
The argument to the <code>\title</code><a id="hevea_default158"></a> command appears
in the html document header. As a consequence, titles should
remain simple. Normal design (as regards H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A) is for
<code>\title</code> to occur in the document preamble, so that the title
is known at the time when the document header is emitted (while
processing <code>\begin{document}</code>). However, there are two subtleties.<p>If no <code>\title</code>
command occurs in document preamble and that one <code>\title</code>
command appears in the document, then the title is saved into the
<span class="c013">.haux</span> file for a next run of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to put it in the
html document header.</p><p>If <code>\title</code> commands are present both in preamble and after
<code>\begin{document}</code>, then the former takes precedence.</p></li><li class="li-itemize">When not present the date is left empty. The
<code>\today</code><a id="hevea_default159"></a> command generates will work properly
only if <span class="c013">hevea</span> is invoked with the <code>-exec xxdate.exe</code>
option. Otherwise <code>\today</code> generates nothing and a warning is
issued.
</li></ul><p>The <code>abstract</code> environment is present is all base styles,
including the <em>book</em> style.
The <code>titlepage</code> environment does nothing.</p>
<!--TOC section id="sec122" Displayed Paragraphs-->
<h2 class="section" id="sec122">B.6  Displayed Paragraphs</h2><!--SEC END --><p>
Displayed-paragraph environments translate to block-level
elements.</p><p>In addition to the environments described in this section,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements the <code>center</code>, <code>flushleft</code> and
<code>flushright</code> environments.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A also implements the corespondant T<sub>E</sub>X style declaration
<code>\centering</code> <code>\raggedright</code> and <code>\raggedleft</code>,
but these declarations may not work as expected, when they do not
appear directly inside a displayed-paragraph environment or inside an array
element.</p>
<!--TOC subsection id="sec123" Quotation and Verse-->
<h3 class="subsection" id="sec123">B.6.1  Quotation and Verse</h3><!--SEC END --><p>
The <code>quote</code> and <code>quotation</code> environments are the same thing: they
translate to <code>BLOCKQUOTE</code> elements.
The <code>verse</code> environment is not supported.</p>
<!--TOC subsection id="sec124" List-Making environments-->
<h3 class="subsection" id="sec124">B.6.2  List-Making environments</h3><!--SEC END --><p>
The <code>itemize</code>, <code>enumerate</code> and <code>description</code>
environments translate to the <code>ul</code>, <code>ol</code>, and
<code>DL</code> elements and this is the whole story.</p><p>As a consequence, no control is allowed on the appearances of these
environments. More precisely optional arguments to <code>\item</code> do not
function properly inside <code>itemize</code> and <code>enumerate</code>. Moreover, item
labels inside <code>itemize</code> or numbering style inside <code>enumerate</code>
are browser dependent.</p><p>However, customized lists can be produced by using the
the <span class="c013">list</span> environment (see next section).</p>
<!--TOC subsection id="sec125" The <span class="c013">list</span> and <span class="c013">trivlist</span>
environments-->
<h3 class="subsection" id="sec125">B.6.3  The <span class="c013">list</span> and <span class="c013">trivlist</span>
environments</h3><!--SEC END --><p>
The <code>list</code> environment translates to the
<code>DL</code> element.
Arguments to <code>\begin{list}</code> are handled as follows:</p><div class="flushleft">
  <code>\begin{list}{</code><span class="c018">default_label</span><code>}{</code><span class="c018">decls</span><code>}</code>
</div><p>The first argument <span class="c018">default_label</span> is the label generated by an
<code>\item</code> command with no argument.
The second argument, <span class="c018">decls</span> is a sequence of declarations.
In practice, the following declarations are relevant:
</p><dl class="list"><dt class="dt-list">
<span class="c013">\usecounter{</span><span class="c018">counter</span><span class="c013">}</span></dt><dd class="dd-list">
The counter <span class="c018">counter</span> is incremented by <code>\refstepcounter</code>
by every <code>\item</code> command with no argument, before it does
anything else.
</dd><dt class="dt-list"><span class="c013">\renewcommand{\makelabel}[1]{</span>…<span class="c013">}</span></dt><dd class="dd-list">
The command <code>\item</code> executes
<code>\makelabel{</code><span class="c018">label</span><code>}</code>, where <span class="c018">label</span> is the item
label, to print its label.
Thus, users can change label formatting by redefining
<code>\makelabel</code>.
The default definition of <code>\makelabel</code> simply echoes <span class="c018">label</span>.
</dd></dl><p>As an example, a list with an user-defined counter can be defined as
follows:
</p><pre class="verbatim">\newcounter{coucou}
\begin{list}{\thecoucou}{%
\usecounter{coucou}%
\renewcommand{\makelabel}[1]{\textbf{#1}.}}
...
\end{list}
</pre><p>This yields:
</p><dl class="list"><dt class="dt-list">
<span class="c022">1</span>.</dt><dd class="dd-list">First item.
</dd><dt class="dt-list"><span class="c022">2</span>.</dt><dd class="dd-list">Second item.
</dd></dl><p>The <code>trivlist</code> environment is also supported. It is equivalent to
the <code>description</code> environment.</p>
<!--TOC subsection id="sec126" Verbatim-->
<h3 class="subsection" id="sec126">B.6.4  Verbatim</h3><!--SEC END --><p>The <code>verbatim</code> and <code>verbatim*</code> environments translate to
the <code>PRE</code> element.
Inside <code>verbatim*</code>, spaces are replaced by underscores (“<code>_</code>”).</p><p>Similarly, <code>\verb</code> and <code>\verb*</code>
translate to the <code>CODE</code> text element.</p><p>The <code>alltt</code> environment is supported.</p>
<!--TOC section id="sec127" Mathematical Formulae-->
<h2 class="section" id="sec127">B.7  Mathematical Formulae</h2><!--SEC END -->
<!--TOC subsection id="sec128" Math Mode Environment-->
<h3 class="subsection" id="sec128">B.7.1  Math Mode Environment</h3><!--SEC END --><p>
The three ways to use math mode (<code>$</code>…<code>$</code>,
<code>\(</code>…<code>\)</code> and
<code>\begin{math}</code>…<code>\end{math}</code>) are supported.
The three ways to use display math mode (<code>$$</code>…<code>$$</code>,
<code>\[</code>…<code>\]</code> and
<code>\begin{displaymath}</code>… <code>\end{displaymath}</code>) are also
supported.
Furthermore, <code>\ensuremath</code> behaves as expected.</p><p>The <code>equation</code>, <code>eqnarray</code>, <code>eqnarray*</code> environments
are supported.
Equation labelling and numbering is performed in the first two
environments, using the <code>equation</code> counter.
Additionally, numbering can be suppressed in one row of an
<code>eqnarray</code>, using the <code>\nonumber</code> command.</p><p>Math mode is not as powerful in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A as in L<sup>A</sup>T<sub>E</sub>X. The
limitations of math mode can often be surpassed by using math display
mode. As a matter of fact, math mode is for in-text formulas. From
the html point of view, this means that math mode does not close
the current flow of text and that formulas in math mode must be
rendered using text-level elements only. By contrast, displayed
formulas can be rendered using block-level elements. This means that
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A have much more possibilities in display context than inside
normal flow of text. In particular, stacking text elements one above
the over is possible only in display context.
For instance compare how H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A renders
<code>$\frac{1}{\sum_{i=1}^{\infty} i$</code>
as: 1/∑<sub><span class="c018">i</span>=1</sub><sup>∞</sup> <span class="c018">i</span>, and
<code>$$\frac{1}{\sum_{i=1}^{\infty} i$$</code> as:
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="display"><tr><td class="dcell c027">1</td></tr>
<tr><td class="hbar"></td></tr>
<tr><td class="dcell c027"><table class="display"><tr class="c035"><td class="dcell"><table class="display"><tr><td class="dcell c027">∞</td></tr>
<tr><td class="dcell c027"><span class="c017">∑</span></td></tr>
<tr><td class="dcell c027"><span class="c018">i</span>=1</td></tr>
</table></td><td class="dcell"> <span class="c018">i</span></td></tr>
</table></td></tr>
</table></td></tr>
</table>
<!--TOC subsection id="sec129" Common Structures-->
<h3 class="subsection" id="sec129">B.7.2  Common Structures</h3><!--SEC END --><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A admits, subscript (<code>_</code>), superscripts (<code>^</code>) and
fractions (<code>\frac{</code><span class="c018">numer</span><code>}{</code><span class="c018">denom</span><code>}</code>).
The best effect is obtained in display mode, where html
<code>table</code> element is extensively used.
By contrast, when not in display mode, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A uses only
<code>SUB</code> and <code>SUP</code> text-level elements to render superscrits
and subscript, and the result may not be very satisfying.</p><p>However,
simple subscripts and superscripts, such as <code>x_i</code> or <code>x^2</code>,
are always rendered using the <code>SUB</code>
and <code>SUP</code> text-level elements and their appearance should be correct
even in in-text formulas.</p><p>When occurring outside math mode, characters <code>_</code> and <code>^</code> act as
ordinary characters and get echoed to the output. However, a warning
is issued.</p><p>An attempt is made to render all ellipsis constructs (<code>\ldots</code>,
<code>\cdots</code>, <code>\vdots</code> and <code>\ddots</code>). The effect may be
strange for the latter two.</p>
<!--TOC subsection id="sec130" Square Root-->
<h3 class="subsection" id="sec130">B.7.3  Square Root</h3><!--SEC END --><p>
<a id="hevea_default160"></a><a id="hevea_default161"></a>
The n<sup>th</sup> root command <code>\sqrt</code> is supported only for n=3,4, thanks to the existence of Unicode characters for the same. For the others, we shift to fractional exponents, in which case, the <code>\sqrt</code> command is
defined as follows:
</p><pre class="verbatim">\newcommand{\sqrt}[3][2]{\left(#2\right)^{1/#1}}
</pre><p>
Then, the source
fragment: <code>$$\sqrt[5]{\frac{1}{n!}} + \sqrt[3]{\pi} + \sqrt{\pi}$$</code> gets rendered
as follows:
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="display"><tr class="c035"><td class="dcell">⎛<br>
⎜<br>
⎜<br>
⎝</td><td class="dcell"><table class="display"><tr><td class="dcell c027">1</td></tr>
<tr><td class="hbar"></td></tr>
<tr><td class="dcell c027"><span class="c018">n</span>!</td></tr>
</table></td><td class="dcell">⎞<br>
⎟<br>
⎟<br>
⎠</td><td class="dcell"><table class="display"><tr><td class="dcell c030"><table class="display"><tr><td class="dcell c027">1</td></tr>
<tr><td class="hbar"></td></tr>
<tr><td class="dcell c027">5</td></tr>
</table></td></tr>
<tr><td class="dcell c030"><br>
<br>
<br>
</td></tr>
<tr><td class="dcell c030"> </td></tr>
</table></td></tr>
</table></td><td class="dcell"> + </td><td class="dcell"><span class="c016">∛</span></td><td class="dcell"><table class="c003 cellpadding0"><tr><td class="hbar"></td></tr>
<tr><td class="c029">π</td></tr>
</table></td><td class="dcell"> + </td><td class="dcell"><span class="c016">√</span></td><td class="dcell"><table class="c003 cellpadding0"><tr><td class="hbar"></td></tr>
<tr><td class="c029">π</td></tr>
</table></td></tr>
</table>
<!--TOC subsection id="sec131" Unicode and mathematical symbols-->
<h3 class="subsection" id="sec131">B.7.4  Unicode and mathematical symbols</h3><!--SEC END --><p><a id="hevea_default162"></a></p><p>The support for unicode symbols offered by modern browsers allows to
translate almost all math symbols correctly.</p><p>Log-like functions and variable sized-symbols are recognized and their
subscripts and superscripts are put where they should in display mode.
Subscript and superscript placement can be changed using the
<code>\limits</code> and <code>\nolimits</code> commands.
Big delimiters are also handled.</p>
<!--TOC subsection id="sec132" Putting one thing above/below/inside-->
<h3 class="subsection" id="sec132">B.7.5  Putting one thing above/below/inside</h3><!--SEC END --><p><a id="hevea_default163"></a><a id="hevea_default164"></a><a id="hevea_default165"></a>
The commands <code>\stackrel</code>, <code>\underline</code> and <code>\overline</code>
are recognized.
They produce sensible output in display mode.
In text mode, these macros call the <code>\textstackrel</code>,
<code>\textunderline</code> and <code>\textoverline</code> macros.
These macros perform the following default actions
</p><dl class="description"><dt class="dt-description">
<span class="c014">\textstackrel</span></dt><dd class="dd-description"> Performs ordinary superscripting.
</dd><dt class="dt-description"><span class="c014">\textunderline</span></dt><dd class="dd-description"> Underlines its argument, using the
<code>U</code> text-level element.
</dd><dt class="dt-description"><span class="c014">\textoverline</span></dt><dd class="dd-description"> Overlines using style-sheets (used <span class="c013"><SPAN></span> with a top border).
</dd></dl><p><a id="hevea_default166"></a> The command <code>\boxed</code> works well both in display and normal math mode. Input of the form <code>\boxed{\frac{\pi}{2}}</code> produces <span class="textboxed">π/2</span> in normal math, and
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="boxed"><tr><td><table class="display"><tr><td class="dcell c027">π</td></tr>
<tr><td class="hbar"></td></tr>
<tr><td class="dcell c027">2</td></tr>
</table></td></tr>
</table></td></tr>
</table><p>
in display-math mode. The commands <code>\bigl,\bigr</code> etc. <a id="hevea_default167"></a>are also rendered well. Some examples can be found <a href="../examples/random-math.html">here</a>.</p>
<!--TOC subsection id="sec133" Math accents-->
<h3 class="subsection" id="sec133">B.7.6  Math accents</h3><!--SEC END --><p><a id="hevea_default168"></a>
Math accents that have coresponding text accents
(<code>\hat</code>, <code>\tilde</code>, etc.) are
handled<a id="mathaccents"></a> by default. They in fact act as the
corresponding text-mode accents (Section <a href="#accents">B.3.4</a>).
As a consequence, they work properly only on ascii letters.
This may be quite cumbersome, but at least some warnings draw user’s
attention on the problem.
If accents are critical to your document and that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A issues
a lot of warnings, a solution is to redefine the math accent command.
A suggested replacement is using limit superscripts.
That way accents are positioned above symbols in display mode and
after symbols in text mode.
</p><pre class="verbatim">\renewcommand{\hat}[1]{\mathop{#1}\limits^{\textasciicircum}\nolimits}
Displayed:
$$
\hat{\mu} = \hat{\Delta}.
$$
In text: $\hat{\mu} = \hat{\delta}$
</pre><p>An you get,
displayed:
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="display"><tr><td class="dcell c027">^</td></tr>
<tr><td class="dcell c027">µ</td></tr>
<tr><td class="dcell c027"> </td></tr>
</table></td><td class="dcell"> = </td><td class="dcell"><table class="display"><tr><td class="dcell c027">^</td></tr>
<tr><td class="dcell c027">Δ</td></tr>
<tr><td class="dcell c027"> </td></tr>
</table></td><td class="dcell">.
</td></tr>
</table><p>
In text: µ<sup>^</sup> = δ<sup>^</sup>.</p><p>Whereas, with the default of <code>\hat</code> being <code>\^</code>,
you get “µ = δ”, with the following warnings:
</p><pre class="verbatim">./tmp.tex:4652: Warning: Application of '\^' on '\mu' failed
./tmp.tex:4652: Warning: Application of '\^' on '\delta' failed
</pre><p>The <code>\vec</code>
command is rendered differently in display and non-display mode. In
display mode, the arrow appears in normal position, while in
non-display the arrow appears as an ordinary superscript.
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c013">\vec{u}</span> in text mode: <span class="c018">u</span><sup>→</sup>,  
<span class="c013">\vec{u}</span> in display mode: </td><td class="dcell"><table class="display"><tr><td class="dcell c027">→</td></tr>
<tr><td class="dcell c027"><span class="c018">u</span></td></tr>
<tr><td class="dcell c027"> </td></tr>
</table></td></tr>
</table><p>Most “extensible accents” (<code>\widetilde</code>, <code>\widehat</code>, etc.)
are not even defined.
There are a few exceptions: line “accents”:
</p><table class="display dcenter"><tr class="c035"><td class="dcell">
</td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029"><table class="display"><tr class="c035"><td class="dcell">    </td><td class="dcell"><table class="c003 cellpadding0"><tr><td class="c029"><span class="c018">abc</span></td></tr>
<tr><td class="hbar"></td></tr>
</table></td><td class="dcell">  <span class="c013">\underline</span></td></tr>
</table></td><td class="c029"><table class="display"><tr class="c035"><td class="dcell">    </td><td class="dcell"><table class="c003 cellpadding0"><tr><td class="hbar"></td></tr>
<tr><td class="c029"><span class="c018">abc</span></td></tr>
</table></td><td class="dcell">  <span class="c013">\overline</span>
</td></tr>
</table></td></tr>
</table></td></tr>
</table><p>
Brace “accents”:
</p><table class="display dcenter"><tr class="c035"><td class="dcell">
</td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029"><table class="display"><tr class="c035"><td class="dcell">    </td><td class="dcell"><table class="display c045"><tr><td class="dcell c027" colspan="5"> </td></tr>
<tr><td class="dcell c027" colspan="5">1 × 2 × ⋯ × <span class="c018">n</span></td></tr>
<tr><td class="dcell c047">◥</td><td class="dcell c046"><hr class="hbar"></td><td class="dcell c044">▼</td><td class="dcell c046"><hr class="hbar"></td><td class="dcell c047">◤</td></tr>
</table></td><td class="dcell">  <span class="c013">\underbrace</span></td></tr>
</table></td><td class="c029"><table class="display"><tr class="c035"><td class="dcell">    </td><td class="dcell"><table class="display c045"><tr><td class="dcell c047">◢</td><td class="dcell" style="width:40%;;text-align:center"><hr class="hbar"></td><td class="dcell c044">▲</td><td class="dcell c046"><hr class="hbar"></td><td class="dcell c047">◣</td></tr>
<tr><td class="dcell c027" colspan="5">1 × 2 × ⋯ × <span class="c018">n</span></td></tr>
<tr><td class="dcell c027" colspan="5"> </td></tr>
</table></td><td class="dcell">  <span class="c013">\overbrace</span>
</td></tr>
</table></td></tr>
</table></td></tr>
</table><p>
And arrow “accents”:
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029"><table class="display"><tr class="c035"><td class="dcell">    </td><td class="dcell"><table class="display c045"><tr><td class="dcell c044">◂</td><td class="dcell c050"><hr class="hbar"></td></tr>
<tr><td class="dcell c027" colspan="2">1 × 2 × ⋯ × <span class="c018">n</span></td></tr>
<tr><td class="dcell c027" colspan="2"> </td></tr>
</table></td><td class="dcell">  <span class="c013">\overleftarrow</span></td></tr>
</table></td><td class="c029"><table class="display"><tr class="c035"><td class="dcell">    </td><td class="dcell"><table class="display c045"><tr><td class="dcell c050"><hr class="hbar"></td><td class="dcell c044">▸</td></tr>
<tr><td class="dcell c027" colspan="2">1 × 2 × ⋯ × <span class="c018">n</span></td></tr>
<tr><td class="dcell c027" colspan="2"> </td></tr>
</table></td><td class="dcell">  <span class="c013">\overrightarrow</span>
</td></tr>
</table></td></tr>
</table></td></tr>
</table>
<!--TOC subsection id="sec134" Spacing-->
<h3 class="subsection" id="sec134">B.7.7  Spacing</h3><!--SEC END --><p><a id="spacemathref"></a>
<a id="hevea_default169"></a>
By contrast with L<sup>A</sup>T<sub>E</sub>X, space in the input matters in math mode.
One or more spaces are translated to one space.
Furthermore,
spaces after commands (such as <code>\alpha</code>) are echoed
except for invisible commands (such as <code>\tt</code>).
This allows users to control space in their formulas, output being
near to what can be expected.</p><p>Explicit spacing commands (<code>\,</code>, <code>\!</code>, <code>\:</code> and
<code>\;</code>) are recognized, the first two commands do nothing, while
the others two output one space.</p>
<!--TOC subsection id="sec135" Changing Style-->
<h3 class="subsection" id="sec135">B.7.8  Changing Style</h3><!--SEC END --><p>Letters are italicized inside math mode and this cannot be
changed. The appearance of
other symbols can be changed using
L<sup>A</sup>T<sub>E</sub>X 2є style changing commands (<code>\mathbf</code>, etc.).
The commands <code>\boldmath</code> and <code>\unboldmath</code> are not
recognized. Whether symbols belonging to the symbol font are affected
by style changes or not is browser dependent.</p><p>The <code>\cal</code> declaration and the <code>\mathcal</code> command (that
yield calligraphic letters in L<sup>A</sup>T<sub>E</sub>X) exist. They yield red letters by
default.</p><p>Observe that this does not corresponds directly to how L<sup>A</sup>T<sub>E</sub>X manage style
in math mode and that, in fact, style cannot really change in math mode.</p><p>Math style changing declarations <code>\displaystyle</code> and
<code>\textstyle</code> do nothing when H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is already in the requested
mode,
otherwise they issue a warning.
This is so because H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements displayed maths as tables,
which require to be both opened and closed and introduce line breaks
in the output.
As a consequence, warnings on <code>\displaystyle</code> are to be taken seriously.</p><p>The commands <code>\scriptstyle</code> and <code>\scriptscriptstyle</code>
perform type size changes.</p>
<!--TOC section id="sec136" Definitions, Numbering-->
<h2 class="section" id="sec136">B.8  Definitions, Numbering</h2><!--SEC END -->
<!--TOC subsection id="sec137" Defining Commands-->
<h3 class="subsection" id="sec137">B.8.1  Defining Commands</h3><!--SEC END --><p><a id="usermacro"></a></p><p><a id="hevea_default170"></a>
<a id="hevea_default171"></a>
<a id="hevea_default172"></a>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A understands command definitions given in L<sup>A</sup>T<sub>E</sub>X style. Such
definitions are made using
<code>\newcommand</code>, <code>\renewcommand</code> and <code>\providecommand</code>.
These three constructs accept the same arguments and have the same
meaning as in L<sup>A</sup>T<sub>E</sub>X, in particular it is possible to define an user
command with one optional argument.
However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is more tolerant: if command
<span class="c018">name</span> already exists, then a subsequent <code>\newcommand{</code><span class="c018">name</span><code>}</code>…is ignored. If macro <span class="c018">name</span> does not exists, then
<code>\renewcommand{</code><span class="c018">name</span><code>}</code>…performs a definition of <span class="c018">name</span>. In both cases, L<sup>A</sup>T<sub>E</sub>X would crash, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A just issues
warnings.</p><p>The behaviour of <code>\newcommand</code> allows to shadow document
definition, provided the new definitions are processed before the
document definitions.
This is easily done by grouping the shadowing definition in a
specific style file given as an argument to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A (see section <a href="#heveaonly">5.1</a>).
Conversely, changes of base macros (<em>i.e.</em> the ones that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
defines before loading any user-specified file) must be performed
using <code>\renewcommand</code>.</p><p>Scoping rules apply to macros, as they do in L<sup>A</sup>T<sub>E</sub>X.
Environments and groups define a scope and command definition
are local to the scope they occur.</p><p>It is worth noticing that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A also partly implements T<sub>E</sub>X definitions
(using <code>\def</code>) and bindings (using <code>\let</code>), see
section <a href="#texmacro">B.16.1</a> for details.</p>
<!--TOC subsection id="sec138" Defining Environments-->
<h3 class="subsection" id="sec138">B.8.2  Defining Environments</h3><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A accepts environment definitions and redefinitions
by <code>\newenvironment</code> and <code>\renewenvironment</code>.
The support is complete and should conform
to [<a href="#latex">L<sup>A</sup>T<sub>E</sub>X</a>, Sections C.8.2].</p><p>Environments define a scope both for commands and environment
definitions.</p>
<!--TOC subsection id="sec139" Theorem-like Environments-->
<h3 class="subsection" id="sec139">B.8.3  Theorem-like Environments</h3><!--SEC END --><p>
New theorem-like environments can also be introduced and redefined,
using <code>\newtheorem</code> and <code>\renewtheorem</code>.</p><p>Note that, by contrast with plain environments definitions,
theorem-like environment definitions are global definitions.</p>
<!--TOC subsection id="sec140" Numbering-->
<h3 class="subsection" id="sec140">B.8.4  Numbering</h3><!--SEC END --><p>
L<sup>A</sup>T<sub>E</sub>X counters are (fully ?) supported.
In particular, defining a counter <span class="c018">cmd</span> with
<code>\newcounter{</code><span class="c018">cmd</span><code>}</code> creates a macro
<code>\the</code><span class="c018">cmd</span> that outputs the counter value.
Then the <code>\the</code><span class="c018">cmd</span> command can be redefined.
For instance, section numbering can be turned into alphabetic style by:
</p><pre class="verbatim">\renewcommand{\thesection}{\alph{section}}
</pre><p>Note that T<sub>E</sub>X style for counters is not supported at all and that using
this style will clobber the output. However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements
the <span class="c018">calc</span> package that makes using T<sub>E</sub>X style for counters
useless in most situations (see section <a href="#calc">B.17.3</a>).</p>
<!--TOC subsection id="sec141" The <span class="c013">ifthen</span> Package-->
<h3 class="subsection" id="sec141">B.8.5  The <span class="c013">ifthen</span> Package</h3><!--SEC END --><p><a id="ifthen"></a>
<a id="hevea_default173"></a>
The <span class="c013">ifthen</span> package is partially supported.
The one unsupported construct is the
<code>\lengthtest</code> test expression, which is
undefined.</p><p>As a consequence, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A accepts the following example from the
L<sup>A</sup>T<sub>E</sub>X manual:
</p><pre class="verbatim">\newcounter{ca}\newcounter{cb}%
\newcommand{\printgcd}[2]{%
\setcounter{ca}{#1}\setcounter{cb}{#2}%
Gcd(#1,#2) =
\whiledo{\not\(\value{ca}= \value{cb}\)}%
{\ifthenelse{\value{ca}>\value{cb}}%
{\addtocounter{ca}{-\value{cb}}}%
{\addtocounter{cb}{-\value{ca}}}%
gcd(\arabic{ca}, \arabic{cb}) = }%
\arabic{ca}.}%
For example: \printgcd{54}{30}
</pre><p>For example: Gcd(54,30) =
gcd(24, 30) = gcd(24, 6) = gcd(18, 6) = gcd(12, 6) = gcd(6, 6) = 6.</p><p>Additionally, a few boolean registers are defined by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
Some of them are of interest to users.
</p><dl class="description"><dt class="dt-description">
<span class="c014">hevea</span></dt><dd class="dd-description"> Initial value is <span class="c013">true</span>.
The <span class="c013">hevea.sty</span> style file also defines this register with
initial value <span class="c018">false</span>.
</dd><dt class="dt-description"><span class="c014">mmode</span></dt><dd class="dd-description"> This register value reflects H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A operating
mode, it is <span class="c018">true</span> in math-mode and <span class="c018">false</span> otherwise.
</dd><dt class="dt-description"><span class="c014">display</span></dt><dd class="dd-description"> This register value reflects H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A operating
mode, it is <span class="c018">true</span> in display-mode and <span class="c018">false</span> otherwise.
</dd><dt class="dt-description"><span class="c014">footer</span></dt><dd class="dd-description"> Initial value is <span class="c013">true</span>.
When set false, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not insert its footer “<em>This
document has been translated by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A</em>”.</dd></dl><p>Finally, note that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A also recognised à la T<sub>E</sub>X conditional
macros (see section <a href="#texcond">B.16.1.4</a>). Such macros are fully compatible
with the boolean registers of the <span class="c013">ifthen</span> package, as it is
the case in L<sup>A</sup>T<sub>E</sub>X.</p>
<!--TOC section id="sec142" Figures and Other Floating Bodies-->
<h2 class="section" id="sec142">B.9  Figures and Other Floating Bodies</h2><!--SEC END --><p>Figures and tables are put where they appear in source, regardless of
their placement arguments.
They are outputted inside a <code>BLOCKQUOTE</code> element and they are
separated from enclosing text by two
horizontal rules.</p><p>Captions and cross referencing are handled.
However captions are not moved at end of figures: instead, they appear
where the <code>\caption</code> commands occur in source code.
The <code>\suppressfloats</code> command does nothing and the
figure related counters (such as <code>topnumber</code>) exist but are useless.</p><p><a id="hevea_default174"></a><a id="hevea_default175"></a><a id="hevea_default176"></a></p><div class="fmarginpar marginparright">Marginal notes go in the right margin by default.</div><div class="fmarginpar marginparleft">To get marginal notes in the left margin, use
<span class="c013">\reversemaginpar</span>.</div><p>
Marginal notes are handled in an H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A specific way.
By default, all notes go in the right margin.
Issuing <code>\reversemarginpar</code> causes the notes to go in the left
margin. Unsurprisingly, issuing <code>\normalmarginpar</code> reverts to
default behaviour.</p><p>The <code>\marginpar</code> command has an optional argument.
</p><div class="flushleft">
  <code>\marginpar[</code><span class="c018">left_text</span><code>]{</code><span class="c018">right_text</span><code>}</code>
</div><p>
If optional argument <span class="c018">left_text</span> is present and that notes
go in the left margin, then <span class="c018">left_text</span> is the text of the
note. Otherwise, <span class="c018">right_text</span> is the text of the note.
As a conclusion, marginal notes in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A always go to a fixed side
of the page, which side being controlled by the commands
<code>\normalmarginpar</code> (right side) and <code>\reversemarginpar</code>
(left side). This departs form L<sup>A</sup>T<sub>E</sub>X that selects a default side
depending on the parity of the page counter.</p><p>Marginal notes are styled by the means of two environment style
classes (see Section <a href="#css%3Achange">9.3</a>) :
<code>marginpar</code> and <code>marginparside</code>.
The latter <code>marginparside</code> takes care of margins and placement as
a float, its value is <code>marginparright</code> for notes in the right
margin and <code>marginparleft</code> for notes in the left margin.
Users are not expected to alter those.
The <code>marginpar</code> environment style class governs the general
aspect of all marginal notes.
Users can control the aspect of all marginal notes by defining a new
style class and assigning the <code>marginpar</code> environment style
class.
For instance, to get all marginal notes in red font,
and taking 10% of the page width (in place of the default
20%),
one can issue the following commands in the document preamble.
</p><pre class="verbatim">\newstyle{.mynote}{width:10\%; color:red;}
\setenvclass{marginpar}{mynote}
</pre>
<!--TOC section id="sec143" Lining It Up in Columns-->
<h2 class="section" id="sec143">B.10  Lining It Up in Columns</h2><!--SEC END -->
<!--TOC subsection id="sec144" The <span class="c013">tabbing</span> Environment-->
<h3 class="subsection" id="sec144">B.10.1  The <span class="c013">tabbing</span> Environment</h3><!--SEC END --><p>
Limited support is offered.
The <span class="c013">tabbing</span> environment translate to a flexible <span class="c013">tabular</span>-like
environment.
Inside this environment, the command <code>\kill</code> ends a row, while
commands
<code>\=</code> and <code>\></code> start a new column.
All other tabbing commands do not even exist.</p>
<!--TOC subsection id="sec145" The <span class="c013">array</span> and <span class="c013">tabular</span>
environments-->
<h3 class="subsection" id="sec145">B.10.2  The <span class="c013">array</span> and <span class="c013">tabular</span>
environments</h3><!--SEC END --><p><a id="arraydef"></a></p><p>These environments are supported, using html
<code>table</code> element, rendering is satisfactory in most (not too
complicated) cases.
By contrast with L<sup>A</sup>T<sub>E</sub>X,
some of the array items always are typeset in display mode.
Whether an array item is typeset in display mode or not depends upon
its column specification,
the <code>l</code>, <code>c</code> and <code>r</code> specifications open display mode
while the remaining <code>p</code> and <code>@</code> do not.
The <code>l</code>, <code>c</code>,<code>r</code> and <code>@</code> specifications
disable word wrap, while the <code>p</code> specification enables it.</p><p>Entries in a column whose specification is <code>l</code> (resp. <code>c</code> or
<code>r</code>) get left-aligned (resp. centered or right-aligned)
in the horizontal direction.
They will get top-aligned in the vertical direction if there are
other column specifications in the
same array that specify vertical alignment constraints
(such as <code>p{</code><span class="c018">wd</span><code>}</code>, see below).
Otherwise, vertical alignment is unspecified.</p><p>Entries in a column whose specification is <code>p{</code><span class="c018">wd</span><code>}</code>
get left-aligned in the horizontal direction and
top-aligned in the vertical direction
and a paragraph break reduces to one line break inside them.
This is the only occasion where
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A makes a distinction between LR-mode and paragraph mode.
Also observe that the length argument <span class="c018">wd</span> to the <code>p</code>
specification is ignored.</p><p>Some L<sup>A</sup>T<sub>E</sub>X array features are not supported at all:
</p><ul class="itemize"><li class="li-itemize">
Optional arguments to <code>\begin{array}</code> and
<code>\begin{tabular}</code> are ignored.
</li><li class="li-itemize">The command <code>\vline</code> does not exists.
</li></ul><p>Some others are partly rendered:
</p><ul class="itemize"><li class="li-itemize">
Spacing between columns is different.
</li><li class="li-itemize"><code>@</code> formatting specifications in <code>\multicolumn</code>
argument are ignored.
</li><li class="li-itemize">If a <code>|</code> appears somewhere in the column formatting
specification, then the array is shown with borders.
</li><li class="li-itemize">The command <code>\hline</code> does nothing if the array has borders
(see above). Otherwise, an horizontal rule is outputted.
</li><li class="li-itemize">The command <code>\cline</code> ignores its argument and is equivalent
to <code>\hline</code>.
</li><li class="li-itemize">Similarly the command
<code>\extracolsep</code> issues a warning and ignores its argument.
</li></ul><p>
Additionally, the <code>tabular*</code> environment is
recognised and gets rendered as an html table with an advisory
width attribute.</p><p>By default, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements the <span class="c013">array</span> package
(see [<a href="#latexbis">L<sup>A</sup>T<sub>E</sub>X-bis</a>, Section 5.3] and section <a href="#arraypack">B.17.2</a> in this
document), which significantly extends the
<code>array</code> and <code>tabular</code> environments.</p>
<!--TOC section id="sec146" Moving Information Around-->
<h2 class="section" id="sec146">B.11  Moving Information Around</h2><!--SEC END -->
<!--TOC subsection id="files" Files-->
<h3 class="subsection" id="files">B.11.1  Files</h3><!--SEC END --><p>
In some situations,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A uses some of the ancillary files generated by L<sup>A</sup>T<sub>E</sub>X.
More precisely, while processing file <em>doc</em><span class="c013">.tex</span>,
the following files may be read:
</p><dl class="description"><dt class="dt-description">
<span class="c014">.aux</span></dt><dd class="dd-description"> The file <em>doc</em><span class="c013">.aux</span> contains
cross-referencing information, such as figure or section numbers.
If this file is present, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A reads it and put such numbers (or
labels) inside
the links generated by the <code>\ref</code> command. If the <span class="c013">.aux</span>
file is not present, or if the <span class="c013">hevea</span> command is given the
<span class="c013">-fix</span> option, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will instead use <span class="c013">.haux</span>
files.
</dd><dt class="dt-description"><span class="c014">.haux</span></dt><dd class="dd-description"> Such files are H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A equivalents of
<span class="c013">.aux</span> files. Indeed, they are <span class="c013">.aux</span> files tailored to
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A needs.
Two runs of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A might be needed to get cross references right.
</dd><dt class="dt-description"><span class="c014">.htoc</span></dt><dd class="dd-description"> This file contains a formatted table of
contents. It is produced while reading the <span class="c013">.haux</span> file.
As consequence a table of contents is available only when the
<span class="c013">.haux</span> file is read.</dd><dt class="dt-description"><span class="c014">.hbbl</span></dt><dd class="dd-description"> The <em>doc</em><span class="c013">.hbbl</span> file
is generated by <span class="c013">bibhva</span> from <em>doc</em><span class="c013">.haux</span>.
When present, it is read by the <code>\bibliography</code> command.</dd><dt class="dt-description"><span class="c014">.bbl</span></dt><dd class="dd-description"> The <em>doc</em><span class="c013">.bbl</span> file is
generated by BibT<sub>E</sub>X from <em>doc</em><span class="c013">.aux</span>.
When present, and if no <em>doc</em><span class="c013">.hbbl</span> exists,
<em>doc</em><span class="c013">.bbl</span> is read by the <code>\bibliography</code> command.</dd><dt class="dt-description"><span class="c022"><span class="c013">.hidx</span> and <span class="c013">.hind</span></span></dt><dd class="dd-description">
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A computes its own indexes, using <span class="c013">.hidx</span> files for
storing index references and, using <span class="c013">.hind</span> files
for storing formatted indexes.
Index formatting significantly departs from the one of L<sup>A</sup>T<sub>E</sub>X.
Again, several runs of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A might be needed to get indexes right.
</dd></dl><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not fail when it cannot find an auxiliary file.
When another run of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is needed, a warning is issued,
and it is user’s responsibility to rerun H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
However, the convenient <a id="hevea_default177"></a><span class="c013">-fix</span> command-line option instructs
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to rerun itself, until it believes it has reached stable state.</p>
<!--TOC subsection id="cross-reference" Cross-References-->
<h3 class="subsection" id="cross-reference">B.11.2  Cross-References<a id="cross"></a></h3><!--SEC END --><p>
<a id="hevea_default178"></a><a id="hevea_default179"></a>
The L<sup>A</sup>T<sub>E</sub>X commands <code>\label</code> and <code>\ref</code> are changed by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
into html anchors and local links, using the “<code>a</code>” element.
Additionally, numerical references to sectional units, figures,
tables, etc. are shown, as they would appear in the <span class="c013">.dvi</span> file.
Numerical references to pages (such as generated by <code>\pageref</code>)
are not shown; only an link is generated.</p><p>The anchor used is the <span class="c018">label</span> argument to
<code>\label{</code><span class="c018">label</span><code>}</code>.
More precisely, <code>\label{</code><span class="c018">label</span><code>}</code> translates to
<code><a id="</code><span class="c018">label</span><code>"></a></code>;
while <code>\ref{</code><span class="c018">label</span><code>}</code>
translates to <code><a name="#</code><span class="c018">label</span><code>"></code><span class="c018">nnn</span><code></a></code>,
where <span class="c018">nnn</span> is the appropriate numerical reference to a section.
As a consequence spaces are better avoided in <span class="c018">label</span>.</p><p>Starting with H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A version 2.04,
the html anchors used by <code>\label</code> and <code>\ref</code> cannot
differ from the arguments to these commands anymore.
Moreover,
when <code>\label{</code><span class="c018">label</span><code>}</code> occurs
inside the argument of a sectioning command (<em>i.e.</em> in section title,
as recommended by section <a href="#section%3Asection">B.4.1</a>),
then H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A will use <span class="c018">label</span>
as the “<span class="c013">id</span>” attribute of the corresponding section.
For instance, the L<sup>A</sup>T<sub>E</sub>X source of this very section is:
</p><pre class="verbatim">\subsection{Cross-References\label{cross-reference}}
</pre><p>It translates to html similar to
</p><pre class="verbatim"><h3 class="subsection" id="cross-reference">B.11.2&#XA0;&#XA0;Cross-References</h3>
</pre><p>Notice that no <code><a id="cross-reference"></a></code> appears above.
Instead <code>id="cross-reference"</code> appears
in the enclosing <code>h3</code> header element.</p><p>While processing a document <em>doc</em><span class="c013">.tex</span>,
cross-referencing information can be computed in two different, mutually
exclusive, ways, depending
on whether L<sup>A</sup>T<sub>E</sub>X has been previously run or not:
</p><ul class="itemize"><li class="li-itemize">
If there exists a file
<em>doc</em><span class="c013">.aux</span> and that <span class="c013">hevea</span> has not been
given the command-line option <span class="c013">-fix</span>,
then cross-referencing information is extracted
from that file. Of course, the <em>doc</em><span class="c013">.aux</span> file
has to be up-to-date, that is,
it should be generated by running L<sup>A</sup>T<sub>E</sub>X as many times as necessary.
(For H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A needs, one run is probably sufficient).
</li><li class="li-itemize">If no <em>doc</em><span class="c013">.aux</span> file exists or if <span class="c013">hevea</span>
has been given the <span class="c013">-fix</span> command-line option, then H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
expect to find cross-referencing information in the file
<em>doc</em><span class="c013">.haux</span>.
</li></ul><p>
The second option is recommended.</p><p>When using its own <em>doc</em><span class="c013">.haux</span> file,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will output a
new <em>doc</em><span class="c013">.haux</span> file at the end of its processing.
This new <em>doc</em><span class="c013">.haux</span> file contains actualised
cross referencing information.
Hence, in that case, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A may need to run twice to get
cross-references right.
Note that, just like L<sup>A</sup>T<sub>E</sub>X,
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A issues a warning then the cross-referencing information it
generates differs from what it has read at start-up, and that it does
not fail if <em>doc</em><span class="c013">.haux</span> does not exist.</p><p>Observe that if a non-correct <em>doc</em><span class="c013">.aux</span> file is
present, then cross-references will apparently be wrong. However the
links are correct.</p>
<!--TOC subsection id="sec149" Bibliography and Citations-->
<h3 class="subsection" id="sec149">B.11.3  Bibliography and Citations</h3><!--SEC END --><p>
The <code>\cite</code> macro is supported. Its optional argument is
correctly handled. Citation labels are extracted from the
<span class="c013">.aux</span> file if present, from the <span class="c013">.haux</span> file otherwise.
Note that these labels are put there by L<sup>A</sup>T<sub>E</sub>X in the first case,
and by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A in the second case, when they process the
<code>\bibitem</code> command.</p><!--TOC subsubsection id="sec150" Using BibT<sub>E</sub>X-->
<h4 class="subsubsection" id="sec150">Using BibT<sub>E</sub>X</h4><!--SEC END --><p>
All BibT<sub>E</sub>X related commands exist and echo the appropriate
information into the <span class="c013">.haux</span> file.</p><p>In particular, the <code>\bibliography</code> command exists and attempts to load the
formatted bibliography, <em>i.e.</em> to load the <span class="c013">.hbbl</span> file.
The <span class="c013">.hbbl</span> file is produced from the <span class="c013">.haux</span> file by
the companion program <span class="c013">bibhva</span> (see <a href="#bibhva">C.1.4</a>).
To include the bibliographic references extracted from <span class="c013">.bib</span>
databases, it should normally suffice to do:
</p><pre class="verbatim"># hevea doc.tex
# bibhva doc
# hevea doc.tex
</pre><p>In case no <span class="c013">.hbbl</span> file exists,
the <code>\bibliography</code> command attempts to load
the <span class="c013">.bbl</span> file normally used while combining L<sup>A</sup>T<sub>E</sub>X and
BibT<sub>E</sub>X. Thus, another way to extract bibliographic references from
<span class="c013">.bib</span> databases is:
</p><pre class="verbatim"># latex doc.tex
# bibtex doc
# hevea doc.tex
</pre><p>In case both files exist,
notice that loading the <span class="c013">.hbbl</span> file has priority over
loading the <span class="c013">.bbl</span> file.</p>
<!--TOC subsection id="sec151" Splitting the Input-->
<h3 class="subsection" id="sec151">B.11.4  Splitting the Input</h3><!--SEC END --><p>
<a id="hevea_default180"></a>
The <code>\input</code> and <code>\include</code> commands exist and they perform
exactly the same operation of searching (and then processing) a file,
whose name is given as an argument.
See section <a href="#comline">C.1.1.1</a> on how H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A searches files.
However, in the case of the <code>\include</code> command, the file is
searched only when previously given as an argument to
the <code>\includeonly</code> command.</p><p><a id="hevea_default181"></a>
Note the following features:
</p><ul class="itemize"><li class="li-itemize">
T<sub>E</sub>X syntax for <code>\input</code> is not supported. That is,
one should write <code>\input{</code><span class="c018">filename</span><code>}</code>.
</li><li class="li-itemize">If <span class="c018">filename</span> is excluded with the <a id="hevea_default182"></a><span class="c013">-e</span> command-line
option (see section <a href="#heveaoptions">C.1.1.4</a>),
then H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not attempt to load <span class="c018">filename</span>.
Instead, it
echoes <code>\input{</code><span class="c018">filename</span><code>}</code> and
<code>\include{</code><span class="c018">filename</span><code>}</code> commands into the
<span class="c018">image</span> file. This sounds complicated, but this is what you want!
</li><li class="li-itemize">H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not fail when it cannot find
a file, it just issues a warning.
</li></ul><p>The <code>\listfiles</code> command is a null command.</p>
<!--TOC subsection id="sec152" Index and Glossary-->
<h3 class="subsection" id="sec152">B.11.5  Index and Glossary</h3><!--SEC END --><p><a id="index"></a>
<a id="hevea_default183"></a><a id="hevea_default184"></a>
Glossaries are not handled (who uses them ?).</p><p>While processing a document <em>doc</em><span class="c013">.tex</span>, index
entries go into the file <em>doc</em><span class="c013">.hidx</span>, while
the formatted index gets written into the file
<em>doc</em><span class="c013">.hind</span>.
As with L<sup>A</sup>T<sub>E</sub>X, two runs of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A are normally needed to format
the index.
However, if all index producing commands (normally <code>\index</code>)
occur before the index formatting command (normally
<code>\printindex</code>), then only one run is needed.</p><p>As in L<sup>A</sup>T<sub>E</sub>X, index processing is not enabled by default and
some package has to be loaded explicitly in the
document preamble.
To that aim, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A provides the standard package <span class="c013">makeidx</span>,
and two extended packages that allow the production of several indexes
(see section <a href="#multind">B.17.7</a>).</p><p>Formatting of indexes in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A departs from L<sup>A</sup>T<sub>E</sub>X behaviour.
More precisely the <code>theindex</code> environment does not exist.
Instead, indexes are formatted using special
<span class="c013">indexenv</span> environments.
Those details do not normally concern users.
However, the
number of columns in the presentation of the index can be controlled
by setting the value of the <span class="c013">indexcols</span> counter (default value
is two).</p>
<!--TOC subsection id="sec153" Terminal Input and Output-->
<h3 class="subsection" id="sec153">B.11.6  Terminal Input and Output</h3><!--SEC END --><p>The <code>\typeout</code> command echos its argument on the
terminal, macro parameter <code>#</code><span class="c018">i</span> are replaced by their values.
The <code>\typein</code> command is not supported.</p>
<!--TOC section id="sec154" Line and Page Breaking-->
<h2 class="section" id="sec154">B.12  Line and Page Breaking</h2><!--SEC END -->
<!--TOC subsection id="sec155" Line Breaking-->
<h3 class="subsection" id="sec155">B.12.1  Line Breaking</h3><!--SEC END --><p>
The advisory line breaking command <code>\linebreak</code>
will produce a line break if it has no argument or if its optional
argument is 4.
The <code>\nolinebreak</code> command is a null command.</p><p>The <code>\\</code> and <code>\\*</code> commands output a <code><BR></code> tag,
except inside arrays where the close the current row.
Their optional argument is ignored.
The <code>\newline</code> command outputs a <code><BR></code> tag.</p><p>All other line breaking commands, declarations or environments are
silently ignored.</p>
<!--TOC subsection id="sec156" Page Breaking-->
<h3 class="subsection" id="sec156">B.12.2  Page Breaking</h3><!--SEC END --><p>
They are no pages in the physical sense in html. Thus, all these
commands are ignored.</p>
<!--TOC section id="sec157" Lengths, Spaces and Boxes-->
<h2 class="section" id="sec157">B.13  Lengths, Spaces and Boxes</h2><!--SEC END -->
<!--TOC subsection id="sec158" Length-->
<h3 class="subsection" id="sec158">B.13.1  Length</h3><!--SEC END --><p>All length commands are ignored, things go smoothly when L<sup>A</sup>T<sub>E</sub>X syntax is
used (using the <code>\newlength</code>, <code>\setlength</code>, etc. commands,
which are null macros).
Of course, if lengths are really important to the document, rendering
will be poor.</p><p>Note that T<sub>E</sub>X length syntax is not at all recognised. As a
consequence, writing things like <code>\textwidth=10cm</code> will clobber
the output.
Users can correct such misbehaviour by adopting L<sup>A</sup>T<sub>E</sub>X syntax, here
they should write
<code>\setlength{\textwidth}{10cm}</code>.</p>
<!--TOC subsection id="sec159" Space-->
<h3 class="subsection" id="sec159">B.13.2  Space</h3><!--SEC END --><p>
The <code>\hspace</code>, <code>\vspace</code> and <code>\addvspace</code> spacing
commands and their starred versions recognise positive explicit length
arguments. Such arguments get converted to a number of non-breaking
spaces or line breaks.
Basically, the value of <code>1em</code> or <code>1ex</code> is one space or one
line-break. For other length units, a simple conversion based upon a
10pt font is used.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A cannot interpret more complicated length arguments
or perform negative spacing.
In these situations, a warning is issued and no output is done.</p><p>Spacing commands without arguments are recognised.
The <code>\enspace</code>, <code>\quad</code> and <code>\qquad</code> commands output
one, two and four non-breaking spaces, while the <code>\smallskip</code>,
<code>\medskip</code> and <code>\bigskip</code> output one, one, and two line
breaks.</p><p>Stretchable lengths do not exist, thus the <code>\hfill</code> and
<code>\vfill</code> macros are undefined.</p>
<!--TOC subsection id="sec160" Boxes-->
<h3 class="subsection" id="sec160">B.13.3  Boxes</h3><!--SEC END --><p>Box contents is typeset in text mode (<em>i.e.</em> non-math and non-display
mode).
Both L<sup>A</sup>T<sub>E</sub>X boxing commands <code>\mbox</code> and <code>\makebox</code>
commands exist.
However <code>\makebox</code> generates a specific warning, since H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
ignore the length and positioning instructions given as optional
argument.</p><p>Similarly, the boxing with frame <code>\fbox</code> and <code>\framebox</code>
commands are recognised and
<code>\framebox</code> issues a warning.
When in display mode, <code>\fbox</code> frames its argument by
enclosing it in a
table with borders. Otherwise, <code>\fbox</code> calls the <code>\textfbox</code>
command, which issues a warning and typesets its argument
inside a <code>\mbox</code> (and thus no frame is drawn).
Users can alter the behaviour of <code>\fbox</code> in non-display mode by
redefining <code>\textfbox</code>.</p><p>Boxes can be saved for latter usage by storing them in <em>bins</em>.
New bins are defined by <code>\newsavebox{</code><span class="c018">cmd</span><code>}</code>.</p><p>Then some text can be saved into <span class="c018">cmd</span> by
<code>\sbox{</code><span class="c018">cmd</span><code>}{</code><span class="c018">text</span><code>}</code> or
<code>\begin{lrbox}{</code><span class="c018">cmd</span><code>}</code> <span class="c018">text</span> <code>\end{lrbox}</code>.
The text is translated to html, as if it was inside a <code>\mbox</code>
and the resulting output is stored.
It is retrieved (and outputted) by the command
<code>\usebox{</code><span class="c018">cmd</span><code>}</code>.
The <code>\savebox</code> command reduces to <code>\sbox</code>, ignoring its
optional arguments.</p><p>The <code>\rule</code> commands translate to a html horizontal rule
(<code><HR></code>) regardless of its arguments.</p><p>All other box-related commands do not exist.</p>
<!--TOC section id="sec161" Pictures and Colours-->
<h2 class="section" id="sec161">B.14  Pictures and Colours</h2><!--SEC END -->
<!--TOC subsection id="sec162" The <span class="c013">picture</span> environment and the <span class="c013">graphics</span>
Package-->
<h3 class="subsection" id="sec162">B.14.1  The <span class="c013">picture</span> environment and the <span class="c013">graphics</span>
Package</h3><!--SEC END --><p>It is possible to have pictures and graphics processed by
<span class="c013">imagen</span> (see section <a href="#image%3Afile">6.1</a>).
In the case of the <span class="c013">picture</span> environment
it remains users responsibility to explicitly choose
source chunks that will get rendered as images.
In the case of the commands from the <span class="c013">graphics</span> package,
this choice is made by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.</p><p>For instance consider the following picture:
</p><pre class="verbatim">\newcounter{cms}
\setlength{\unitlength}{1mm}
\begin{picture}(50,10)
\put(0,7){\makebox(0,0)[b]{cm}}
\multiput(10,7)(10,0){5}{\addtocounter{cms}{1}\makebox(0,0)[b]{\arabic{cms}}}
\multiput(1,0)(1,0){49}{\line(0,1){2.5}}
\multiput(5,0)(10,0){5}{\line(0,1){5}}
\thicklines
\put(0,0){\line(1,0){50}}
\multiput(0,0)(10,0){6}{\line(0,1){5}}
\end{picture}
</pre><p>Users should enclose <em>all</em> picture elements in a <code>toimage</code>
environment (or inside <code>%BEGIN IMAGE</code>… <code>%END IMAGE</code> comments) and insert an <code>\imageflush</code> command, where they want
the image to appear in html output:
</p><pre class="verbatim">%BEGIN IMAGE
\newcounter{cms}
\setlength{\unitlength}{1mm}
\begin{picture}(50,10)
...
\end{picture}
%END IMAGE
%HEVEA\imageflush
</pre><p>This will result in normal processing by L<sup>A</sup>T<sub>E</sub>X and image inclusion
by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A:</p><p><img src="manual008.png"></p><p><a id="graphics"></a><a id="hevea_default185"></a><a id="hevea_default186"></a><a id="hevea_default187"></a>All commands from the graphics package are implemented using the
automatic image inclusion feature.
More precisely, the outermost invocations of
the <code>\includegraphics</code>, <code>\scalebox</code>,
etc. commands are sent to the image <span class="c018">image</span> file and there will
be one image per outermost invocation of these commands.</p><p>For instance, consider a document <span class="c013">doc.tex</span> that
loads the <span class="c013">graphics</span> package and that includes some (scaled)
images by:
</p><pre class="verbatim">\begin{center}
\scalebox{.5}{\includegraphics{round.ps}}
\scalebox{.75}{\includegraphics{round.ps}}
\includegraphics{round.ps}
\end{center}
</pre><p>Then, issuing the following two commands:
</p><pre class="verbatim"># hevea doc.tex
# imagen doc
</pre><p>yields html that basically consists in three image links,
the images being generated by <span class="c013">imagen</span>.
</p><blockquote class="quote">
<div class="center">
<img src="manual009.png">
<img src="manual010.png">
<img src="manual011.png">
</div>
</blockquote><p>
Since the advent of <span class="c013">pdflatex</span>,
using <code>\includegraphics</code> to insert bitmap images
(<em>e.g.</em> <span class="c013">.gif</span> or <span class="c013">.jpg</span>)
became frequent.
In that case, users are advised <em>not</em> to use H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A default
implementation of the <span class="c013">graphics</span> package.
Instead, they may use a simple variation of
the technique described in Section <a href="#imgsrc">8.2</a>.</p>
<!--TOC subsection id="sec163" The <span class="c013">color</span> Package-->
<h3 class="subsection" id="sec163">B.14.2  The <span class="c013">color</span> Package</h3><!--SEC END --><p><a id="color"></a><a id="hevea_default188"></a><a id="color:package"></a>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A partly implements the <span class="c013">color</span> package.
Implemented commands are <code>\definecolor</code>, <code>\color</code>,
<code>\colorbox</code> and
<code>\textcolor</code>. Other commands from the <span class="c013">color</span> package do
not exist.
At startup,
colours <span style="font-family:monospace;color:black">black</span>, <span style="font-family:monospace;color:white">white</span>,
<span style="font-family:monospace;color:red">red</span>, <span style="font-family:monospace;color:lime">green</span>, <span style="font-family:monospace;color:blue">blue</span>,
<span style="font-family:monospace;color:aqua">cyan</span>, <span style="font-family:monospace;color:yellow">yellow</span> and <span style="font-family:monospace;color:fuchsia">magenta</span> are
pre-defined.</p><p>Colours are defined by
<code>\definecolor{</code><span class="c018">name</span><code>}{</code><span class="c018">model</span><code>}{</code><span class="c018">spec</span><code>}</code>,
where <span class="c018">name</span> is the color name, <span class="c018">model</span> is the color
model used, and <span class="c018">spec</span> is the color specification according to
the given model.
Defined colours are used by the declaration
<code>\color{</code><span class="c018">name</span><code>}</code> and by the command
<code>\textcolor{</code><span class="c018">name</span><code>}{</code><span class="c018">text</span><code>}</code>, which
change text color.
Please note that, the <code>\color</code> declaration
accepts color specifications directly
when invoked as
<code>\color[</code><span class="c018">model</span><code>]{</code><span class="c018">spec</span><code>}</code>.
The <code>\textcolor</code> command has a similar feature.</p><p>As regards color models, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements the <span class="c013">rgb</span>,
<span class="c013">cmyk</span>, <span class="c013">hsv</span> and <span class="c013">hls</span> color models.
In those models, color specifications are floating point numbers less
than one.
For instance, here is the definition for the <span class="c013">red</span> color:
</p><pre class="verbatim">\definecolor{red}{rgb}{1, 0, 0}
</pre><p>The <span class="c013">named</span> color model is also supported, in this model color
specification are just names…
Named colours are the ones of <span class="c013">dvips</span>.
</p><div class="flushleft">
<span style="color:#D8FF4F">GreenYellow</span>,
<span class="c011">Yellow</span>,
<span style="color:#FFE528">Goldenrod</span>,
<span style="color:#FFB528">Dandelion</span>,
<span style="color:#FFAD7A">Apricot</span>,
<span style="color:#FF7F4C">Peach</span>,
<span style="color:#FF897F">Melon</span>,
<span style="color:#FF9300">YellowOrange</span>,
<span style="color:#FF6321">Orange</span>,
<span style="color:#FF7C00">BurntOrange</span>,
<span style="color:#C13000">Bittersweet</span>,
<span style="color:#FF3A21">RedOrange</span>,
<span style="color:#A51815">Mahogany</span>,
<span style="color:#AD1637">Maroon</span>,
<span class="c007">BrickRed</span>,
<span style="color:red">Red</span>,
<span style="color:#FF007F">OrangeRed</span>,
<span style="color:#FF00DD">RubineRed</span>,
<span style="color:#FF0A9B">WildStrawberry</span>,
<span style="color:#FF779E">Salmon</span>,
<span style="color:#FF5EFF">CarnationPink</span>,
<span class="c008">Magenta</span>,
<span style="color:#FF30FF">VioletRed</span>,
<span style="color:#FF2DFF">Rhodamine</span>,
<span style="color:#A418F9">Mulberry</span>,
<span style="color:#9C10A8">RedViolet</span>,
<span style="color:#7C15EA">Fuchsia</span>,
<span style="color:#FF84FF">Lavender</span>,
<span style="color:#E068FF">Thistle</span>,
<span style="color:#AD5BFF">Orchid</span>,
<span style="color:#9932CC">DarkOrchid</span>,
<span style="color:#8C23FF">Purple</span>,
<span style="color:#7F00FF">Plum</span>,
<span style="color:#351EFF">Violet</span>,
<span style="color:#3F19FF">RoyalPurple</span>,
<span style="color:#2216F4">BlueViolet</span>,
<span style="color:#6D72FF">Periwinkle</span>,
<span style="color:#606DC4">CadetBlue</span>,
<span style="color:#59DDFF">CornflowerBlue</span>,
<span style="color:#027E91">MidnightBlue</span>,
<span style="color:#0F75FF">NavyBlue</span>,
<span style="color:#007FFF">RoyalBlue</span>,
<span style="color:blue">Blue</span>,
<span style="color:#0FE2FF">Cerulean</span>,
<span style="color:aqua">Cyan</span>,
<span style="color:#0AFFFF">ProcessBlue</span>,
<span style="color:#60FFE0">SkyBlue</span>,
<span style="color:#26FFCC">Turquoise</span>,
<span style="color:#22F9A4">TealBlue</span>,
<span style="color:#2DFFB2">Aquamarine</span>,
<span style="color:#26FFAA">BlueGreen</span>,
<span style="color:#00FF7F">Emerald</span>,
<span style="color:#02FF7A">JungleGreen</span>,
<span style="color:#4FFF7F">SeaGreen</span>,
<span style="color:lime">Green</span>,
<span style="color:#14E01A">ForestGreen</span>,
<span style="color:#0FBF4E">PineGreen</span>,
<span style="color:#7FFF00">LimeGreen</span>,
<span style="color:#8EFF42">YellowGreen</span>,
<span style="color:#BCFF3D">SpringGreen</span>,
<span style="color:#379907">OliveGreen</span>,
<span style="color:#8C2700">RawSienna</span>,
<span style="color:#4C0D00">Sepia</span>,
<span style="color:#661300">Brown</span>,
<span style="color:#DB9370">Tan</span>,
<span style="color:#7F7F7F">Gray</span>,
<span style="color:black">Black</span>,
<span style="color:white">White</span>.
</div><p>There are at least three ways to use colours from the <span class="c013">named</span>
model.
</p><ol class="enumerate" type=1><li class="li-enumerate">
Define a color name for them.
</li><li class="li-enumerate">Specify the named color model as an optional argument to
<code>\color</code> and <code>\textcolor</code>.
</li><li class="li-enumerate">Use the names directly
(H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements the <span class="c013">color</span> package with
the <span class="c013">usenames</span> option given).
</li></ol><p>
That is:
</p><ol class="enumerate" type=1><li class="li-enumerate">
<code>\definecolor{rouge-brique}{named}{BrickRed}\textcolor{rouge-brique}{Text as a brick}</code>.
</li><li class="li-enumerate"><code>\textcolor[named]{BrickRed}{Text as another brick}</code>.
</li><li class="li-enumerate"><code>\textcolor{BrickRed}{Text as another brick}</code>.
</li></ol><p>
Which yields:
</p><ol class="enumerate" type=1><li class="li-enumerate">
<span class="c007">Text as a brick</span>.
</li><li class="li-enumerate"><span class="c007">Text as another brick</span>.
</li><li class="li-enumerate"><span class="c007">Text as another brick</span>.
</li></ol><p>Colours should be used carefully. Too many colours
hinders clarity and some of the colours may not be readable on the
document background color.</p>
<!--TOC subsubsection id="sec164" The <span class="c013">bgcolor</span> environment-->
<h4 class="subsubsection" id="sec164">B.14.2.1  The <span class="c013">bgcolor</span> environment</h4><!--SEC END --><p>
<a id="hevea_default189"></a><a id="bgcolor"></a>
With respect to the L<sup>A</sup>T<sub>E</sub>X <span class="c013">color</span> package, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A features
an additional
<span class="c013">bgcolor</span> environment, for changing the background color of some
subparts of the document.
The <span class="c013">bgcolor</span> environment is a displayed environment and it
normally starts a new line.
Simple usage is <code>\begin{bgcolor}{</code><span class="c018">color</span><code>}</code>…
<code>\end{bgcolor}</code>, where
<span class="c018">color</span> is a color defined with <code>\definecolor</code>.
Hence the following source yield a paragraph with a red background:
</p><pre class="verbatim">\begin{bgcolor}{red}
\color{yellow}Yellow letters on a red backgroud
\end{bgcolor}
</pre><table><tr><td style="padding:1em;background-color:red">
<span class="c011">Yellow letters on a red background
</span></td></tr>
</table><p>The <span class="c013">bgcolor</span> environment is implemented by one-cell
<code>table</code> element, it takes an
optional argument that is used as an attribute for the inner <code>td</code>
element (default value is <code>style="padding:1em"</code>).
Advanced users may change the default, for instance as:
</p><pre class="verbatim">\begin{bgcolor}[style="padding:0"]{yellow}
\color{red}Red letters on a yellow backgroud
\end{bgcolor}
</pre><p>The resulting output will be red letters
on a yellow background and no padding:
</p><table><tr><td style="padding:0;background-color:yellow">
<span style="color:red">Red letters on a yellow background, no padding
</span></td></tr>
</table>
<!--TOC subsubsection id="sec165" From High-Level Colours to Low-Level Colours-->
<h4 class="subsubsection" id="sec165">B.14.2.2  From High-Level Colours to Low-Level Colours</h4><!--SEC END --><p><a id="getcolor"></a>
<a id="hevea_default190"></a>
<a id="hevea_default191"></a>
High-level colours are color names
defined with <code>\definecolor</code>.
Low-level colours are html-style colours.
That is, they are either one of the sixteen conventional colours black,
silver etc., or a RGB hexadecimal color specification of the form
<code>"#XXXXXX"</code>.</p><p>One changes the high-level <em>high-color</em> into a low-level color by
<code>\@getcolor{</code><em>high-color</em><code>}</code>.
Low-level colours are appropriate inside html attributes and as
arguments to the <code>\@fontcolor</code> internal macro.
An example of <code>\@getcolor</code> usage can be found at the end of
section <a href="#getcolor%3Ausage">8.5</a>.</p><p>There is also <code>\@getstylecolor</code> command that acts
like<code>\@getcolor</code>, except that it does not output the double
quotes around RGB hexadecimal color specifications.
Such low-level colours are appropriate for style definitions in
cascading style sheets [<a href="#css">CSS-2</a>]. See
Section <a href="#getstylecolor%3Aexample">9.3</a> for an example.</p>
<!--TOC section id="sec166" Font Selection-->
<h2 class="section" id="sec166">B.15  Font Selection</h2><!--SEC END -->
<!--TOC subsection id="sec167" Changing the Type Style-->
<h3 class="subsection" id="sec167">B.15.1  Changing the Type Style</h3><!--SEC END --><p><a id="type-style"></a>
All L<sup>A</sup>T<sub>E</sub>X 2є declarations and environments for changing type style
are recognised. Aspect is rather like L<sup>A</sup>T<sub>E</sub>X 2є output, but there is
no guarantee.</p><p>As html does not provide the same variety of type styles as
L<sup>A</sup>T<sub>E</sub>X does.
However <span class="c020">css</span> provide a wide variety of font properties.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A uses generic properties, proper rendering will then depend
upon user agent.
For instance, it belongs to the user agent
to make a difference between
<span class="c018">italics</span> (rendered by the font style “italic”)
and <span class="c019">slanted</span> (rendered by the font style “oblique”).</p><p>Here is how H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements text-style declarations by default:
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c039"><table class="c002 cellpading0"><tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c032"><code>\itshape</code></td><td class="c029">  </td><td class="c032"><span class="c018">font-style:italic</span></td></tr>
<tr><td class="c032"><code>\slshape</code></td><td class="c029">  </td><td class="c032"><span class="c019">font-style:oblique</span></td></tr>
<tr><td class="c032"><code>\scshape</code></td><td class="c029">  </td><td class="c032"><span class="c020">font-variant:small-caps</span></td></tr>
<tr><td class="c032"><code>\upshape</code></td><td class="c029">  </td><td class="c032">no style</td></tr>
<tr><td class="hbar" colspan=3></td></tr>
</table></td><td class="c039"><table class="c002 cellpading0"><tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c032"><code>\ttfamily</code></td><td class="c029">  </td><td class="c032"><span class="c013">font-family:monospace</span></td></tr>
<tr><td class="c032"><code>\sffamily</code></td><td class="c029">  </td><td class="c032"><span style="font-family:sans-serif">font-family:sans-serif</span></td></tr>
<tr><td class="c032"><code>\rmfamily</code></td><td class="c029">  </td><td class="c032">no style</td></tr>
<tr><td class="hbar" colspan=3></td></tr>
</table></td><td class="c039"><table class="c002 cellpading0"><tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c032"><code>\bfseries</code></td><td class="c029">  </td><td class="c032"><span class="c022">font-weight:bold</span></td></tr>
<tr><td class="c032"><code>\mdseries</code></td><td class="c029">  </td><td class="c032">no style</td></tr>
<tr><td class="hbar" colspan=3></td></tr>
</table>
</td></tr>
</table>
</div><p>Text-style commands also exists, they are defined as
<code>\mbox{\</code><span class="c018">decl</span>…<code>}</code>. For instance,
<code>\texttt</code> is defined as a command with one argument whose body is
<code>\mbox{\ttfamily#1}</code>.
Finally, the <code>\emph</code> command for emphasised text also exists,
it yields text-level <code>em</code> elements.</p><p>As in L<sup>A</sup>T<sub>E</sub>X, type styles consists in three components:
<em>shape</em>, <em>series</em> and <em>family</em>.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements the three components by making one declaration to
cancel the effect of other declarations of the same kind.
For instance consider the following source, that exhibits shape changes:
</p><pre class="verbatim">{\itshape italic shape \slshape slanted shape
\scshape small caps shape \upshape upright shape}
</pre><p>Then, in the rendering below, “small caps shape” appears in small caps shape
only and not in italics:
</p><blockquote class="quote">
<span class="c018">italic shape </span><span class="c019">slanted shape
</span><span class="c020">small caps shape </span>upright shape
</blockquote><p>Old style declarations are also recognised, they translate to
text-level elements. However, no elements are cancelled when using
old style declaration. Thus, the source
“<code>{\sl\sc slanted and small caps}</code>” yields “slanted”
small caps: “<span style="font-style:oblique;font-variant:small-caps">slanted and small caps</span>”.
Users need probably not worry about this. However this has an
important practical consequence: to change the default rendering of
type styles, one should redefine old style declaration in order to
benefit from the cancellation mechanism. See
section <a href="#customize-style">10.2</a> for a more thorough description.</p>
<!--TOC subsection id="sec168" Changing the Type Size-->
<h3 class="subsection" id="sec168">B.15.2  Changing the Type Size</h3><!--SEC END --><p>
All declarations, from <code>\tiny</code> to <code>\Huge</code> are recognised.
Output is not satisfactory inside headers elements
generated by sectioning commands.</p>
<!--TOC subsection id="sec169" Special Symbols-->
<h3 class="subsection" id="sec169">B.15.3  Special Symbols</h3><!--SEC END --><p>The <code>\symbol{</code><span class="c018">num</span><code>}</code> outputs character number <span class="c018">num</span>
(decimal) from the Unicode character set.
This departs from L<sup>A</sup>T<sub>E</sub>X, which output symbol number <span class="c018">num</span> in
the current font.</p>
<!--TOC section id="sec170" Extra Features-->
<h2 class="section" id="sec170">B.16  Extra Features</h2><!--SEC END --><p>
This section describes H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A functionalities that extends on plain L<sup>A</sup>T<sub>E</sub>X,
as defined in [<a href="#latex">L<sup>A</sup>T<sub>E</sub>X</a>].
Most of the features described here are performed by default.</p>
<!--TOC subsection id="sec171" T<sub>E</sub>X macros-->
<h3 class="subsection" id="sec171">B.16.1  T<sub>E</sub>X macros</h3><!--SEC END --><p><a id="texmacro"></a>
Normally, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not recognise constructs that are specific to
T<sub>E</sub>X.
However, some of the internal commands of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A are homonymous to
T<sub>E</sub>X macros, in order to enhance compatibility.
Note that full compatibility with T<sub>E</sub>X is not guaranteed.</p>
<!--TOC subsubsection id="sec172" À la T<sub>E</sub>X macros definitions-->
<h4 class="subsubsection" id="sec172">B.16.1.1  À la T<sub>E</sub>X macros definitions</h4><!--SEC END --><p><a id="texmacros"></a>
<a id="hevea_default192"></a><a id="hevea_default193"></a>
The <code>\def</code> construct for defining commands is supported.
It is important to
notice that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A semantics for <code>\def</code>
follows T<sub>E</sub>X semantics.
That is, defining a command that already
exists with <code>\def</code> succeeds.</p><p>Delimiting characters in command definition are somehow supported.
Consider the following example from the T<sub>E</sub>X Book:
</p><pre class="verbatim">\def\Look{\textsc{Look}}
\def\x{\textsc{x}}
\def\cs AB#1#2C$#3\$ {#3{ab#1}#1 c\x #2}
\cs AB {\Look}{}C${And \$}{look}\$ 5.
</pre><p>It yields:
And $lookab<span class="c020">LookLook</span> c<span class="c020">x</span>5.</p><p>Please note that delimiting characters are supported as far as I
could, problems are likely with delimiting characters which include
spaces or command names, in particular the command name <code>\{</code>.
One can include <code>\{</code> in a command argument by using the grouping
characters <code>{</code>… <code>}</code>:
</p><pre class="verbatim">\def\frenchquote(#1){\guillemotleft~\emph{#1}~\guillemotright{} (in French)}
he said \frenchquote(Alors cette accolade ouvrante {``\{''}~?).
</pre><p>Yields:
he said « <em>Alors cette accolade ouvrante “{” ?</em> » (in French).
</p><p>Another issue regards comments: “%” in arguments may give undefined
behaviours, while comments are better avoided while defining
macros. As an example, the following code will <em>not</em>
be handled properly
by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A:
</p><pre class="verbatim">\def\x%
#1{y}
</pre><p>Such T<sub>E</sub>X source should be rewritten as <code>\def\x#1{y}</code>.</p><p>Another source of incompatibility with T<sub>E</sub>X is that substitution of
macros parameters is not performed at the same moment by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and
T<sub>E</sub>X.
However, things should go smoothly at the first level of macro
expansion, that is when the delimiters
appear in source code at the same level as the macro that is to
parse them.
For instance, the following source will give different results in
L<sup>A</sup>T<sub>E</sub>X and in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A:
</p><pre class="verbatim">\def\cs#1A{``#1''}
\def\othercs#1{\cs#1A}
\othercs{coucouA}
</pre><p>L<sup>A</sup>T<sub>E</sub>X output is “coucou”A, while H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output is “coucouA”.
Here is H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output:
“coucouA”
Please note that in most situations this discrepancy will make
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A crash. </p>
<!--TOC subsubsection id="sec173" The <span class="c013">\let</span> construct-->
<h4 class="subsubsection" id="sec173">B.16.1.2  The <span class="c013">\let</span> construct</h4><!--SEC END --><p>
<a id="hevea_default194"></a>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A also processes a
limited version of <code>\let</code>:
</p><div class="flushleft">
<code>\let</code> <span class="c018">macro-name1</span> = <span class="c018">macro-name2</span>
</div><p>
The effect is to bind <span class="c018">macro-name1</span> to whatever <span class="c018">macro-name2</span>
is bound to at the time <code>\let</code> is processed. This construct may
prove very useful in situations where
one wishes to slightly modify basic commands.
See sections <a href="#customize-let">10.3</a> and <a href="#exlet">B.2</a> for examples of using
<code>\let</code> in such a situation.</p>
<!--TOC subsubsection id="sec174" The <span class="c013">\global</span> construct-->
<h4 class="subsubsection" id="sec174">B.16.1.3  The <span class="c013">\global</span> construct</h4><!--SEC END --><p>
<a id="hevea_default195"></a>
It is possible to escape scope and to make global definitions
and bindings by using the T<sub>E</sub>X construct <code>\global</code>.
The <code>\global</code> construct is significant before
<code>\def</code> and <code>\let</code> constructs.</p><p><a id="hevea_default196"></a>
Also note that <code>\gdef</code> is equivalent to <code>\global\def</code>.</p>
<!--TOC subsubsection id="sec175" T<sub>E</sub>X Conditional Macros-->
<h4 class="subsubsection" id="sec175">B.16.1.4  T<sub>E</sub>X Conditional Macros</h4><!--SEC END --><p><a id="texcond"></a>
<a id="hevea_default197"></a><a id="hevea_default198"></a><a id="hevea_default199"></a><a id="hevea_default200"></a>
The <code>\newif\if</code><span class="c018">name</span>, where <span class="c018">name</span> is made of letters
only, creates three macros:
<code>\if</code><span class="c018">name</span>, <code>\</code><span class="c018">name</span><code>true</code> and
<code>\</code><span class="c018">name</span><code>false</code>.
The latter two set the <span class="c018">name</span> condition to <span class="c018">true</span> and
<span class="c018">false</span>, respectively.
The <code>\if</code><span class="c018">name</span> command tests the condition <span class="c018">name</span>:
</p><div class="flushleft">
<code>\if</code><span class="c018">name<br>
text</span><sub>1</sub><br>
<code>\else</code><br>
<span class="c018">text</span><sub>2</sub><br>
<code>\fi</code><br>
</div><p>
Text <span class="c018">text</span><sub>1</sub> is processed when <span class="c018">name</span> is
<span class="c018">true</span>, otherwise <span class="c018">text</span><sub>2</sub> is processed.
If <span class="c018">text</span><sub>2</sub> is empty, then the <code>\else</code> keyword can be
omitted.</p><p>Note that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A also implements L<sup>A</sup>T<sub>E</sub>X <span class="c013">ifthen</span> package
and that T<sub>E</sub>X simple conditional macros are fully compatible with
L<sup>A</sup>T<sub>E</sub>X boolean registers. More precisely,
we have the following correspondences:
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c029" colspan=2>T<sub>E</sub>X</td><td class="c029">L<sup>A</sup>T<sub>E</sub>X</td></tr>
<tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c039"><code>\newif\if</code><span class="c018">name</span></td><td class="c029">  </td><td class="c039"><code>\newboolean{</code><span class="c018">name</span><code>}</code></td></tr>
<tr><td class="c039"><code>\</code><span class="c018">name</span><code>true</code></td><td class="c029">  </td><td class="c039"><code>\setboolean{</code><span class="c018">name</span><code>}{true}</code></td></tr>
<tr><td class="c039"><code>\</code><span class="c018">name</span><code>false</code></td><td class="c029">  </td><td class="c039"><code>\setboolean{</code><span class="c018">name</span><code>}{false}</code></td></tr>
<tr><td class="c039"><code>\if</code><span class="c018">name text</span><sub>1</sub><code>\else</code>
<span class="c018">text</span><sub>2</sub><code>\fi</code></td><td class="c029">  </td><td class="c039"><code>\ifthenelse{\boolean{</code><span class="c018">name</span><code>}}{</code><span class="c018">text</span><sub>1</sub><code>}{</code><span class="c018">text</span><sub>2</sub><code>}</code></td></tr>
</table>
</div>
<!--TOC subsubsection id="sec176" Other T<sub>E</sub>X Macros-->
<h4 class="subsubsection" id="sec176">B.16.1.5  Other T<sub>E</sub>X Macros</h4><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements the macros <code>\unskip</code> and <code>\endinput</code>.
It also supports the <code>\csname</code>… <code>\endcsname</code>
construct.</p>
<!--TOC subsection id="sec177" Command Definition inside Command Definition-->
<h3 class="subsection" id="sec177">B.16.2  Command Definition inside Command Definition</h3><!--SEC END --><p>
<a id="hevea_default201"></a><a id="hevea_default202"></a>
If one strictly follows the L<sup>A</sup>T<sub>E</sub>X manual, only commands with no
arguments can be defined inside other commands.
Parameters (<em>i.e.</em> <code>#</code><span class="c018">n</span>) occurring inside command bodies
refer to the outer definition, even when they appear in nested
command definitions.
That is, the following source:
</p><pre class="verbatim">\newcommand{\outercom}[1]{\newcommand{\insidecom}{#1}\insidecom}
\outercom{outer}
</pre><p>yields this output:
</p><div class="center">
outer
</div><p>Nevertheless, nested commands with arguments are allowed.
Standard parameters <code>#</code><span class="c018">n</span> still refer to the outer
definition, while nested parameters <code>##</code><span class="c018">n</span> refer to the
inner definition.
That is, the source:
</p><pre class="verbatim">\newcommand{\outercom}[1]{\newcommand{\insidecom}[1]{##1}\insidecom{inner}}
\outercom{outer}
</pre><p>yields this output:
</p><div class="center">
inner
</div>
<!--TOC subsection id="sec178" Date and time-->
<h3 class="subsection" id="sec178">B.16.3  Date and time</h3><!--SEC END --><p>
<a id="hevea_default203"></a><a id="hevea_default204"></a>
Date and time support is not enabled by default, for portability and
simplicity reasons.</p><p>However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A source distribution includes a simple (<span class="c013">sh</span>)
shell script
<span class="c013">xxdate.exe</span> that activates date and time support.
The <span class="c013">hevea</span> command, should be invoked as:
</p><pre class="verbatim"># hevea -exec xxdate.exe ...
</pre><p>This will execute the script <span class="c013">xxdate.exe</span>, whose output is then
read by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
As a consequence, standard L<sup>A</sup>T<sub>E</sub>X counters <code>year</code>,
<code>month</code>, <code>day</code> and
<code>time</code> are defined and
L<sup>A</sup>T<sub>E</sub>X command <code>\today</code> works properly.
<a id="hevea_default205"></a>
Additionally the following counters and commands are defined:
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c041">Counter <span class="c013">weekday</span></td><td class="c029">  </td><td class="c039">day of week, 0…6
(e.g. 5)</td></tr>
<tr><td class="c041">Counter <span class="c013">Hour</span></td><td class="c029">  </td><td class="c039">hour, 00…11
(e.g. 11)</td></tr>
<tr><td class="c041">Counter <span class="c013">hour</span></td><td class="c029">  </td><td class="c039">hour, 00…23 (e.g. 11)</td></tr>
<tr><td class="c041">Counter <span class="c013">minute</span></td><td class="c029">  </td><td class="c039">minute, 00…59
(e.g. 51)</td></tr>
<tr><td class="c041">Counter <span class="c013">second</span></td><td class="c029">  </td><td class="c039">second, 00…61<sup><a id="text9" href="#note9">8</a></sup>(e.g. 49)</td></tr>
<tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c041">Command <code>\ampm</code></td><td class="c029">  </td><td class="c039">AM or PM
(e.g. AM)</td></tr>
<tr><td class="c041">Command <code>\timezone</code></td><td class="c029">  </td><td class="c039">Time zone
(e.g. CET)</td></tr>
<tr><td class="c041">Command <code>\heveadate</code></td><td class="c029">  </td><td class="c039">Output of the <span class="c013">date</span> Unix
command, (e.g. Fri Mar 29 11:51:49 CET 2013)</td></tr>
<tr><td class="hbar" colspan=3></td></tr>
</table>
</div><p>Note that I chose to add an extra option (and not an extra
<code>\@exec</code> primitive) for security reasons. You certainly do
not want to enable H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to execute silently an arbitrary program
without being conscious of that fact.
Moreover, the <span class="c013">hevea</span> program does not execute
<span class="c013">xxdate.exe</span> by default since it is difficult to write such
a script in a portable manner.</p><p>Windows users should enjoy the same features with the version of
<span class="c013">xxdate.exe</span> included in the Win32 distribution. </p>
<!--TOC subsection id="fancysection" Fancy sectioning commands-->
<h3 class="subsection" id="fancysection">B.16.4  Fancy sectioning commands</h3><!--SEC END --><p>
<a id="hevea_default206"></a><a id="hevea_default207"></a>Loading the <span class="c013">fancysection.hva</span> file will radically change the
style of sectional units headers: they appear over a green
background, the background color saturation decreases as the sectioning
commands themselves do (this is the style of this manual).
Additionally, the document background color is white.</p><p><span class="c022">Note : </span>Fancy section has been re-implemented using style-sheets. While it respects the old behaviour, users are encouraged to try out style-sheets for more flexibility. See Section <a href="#style%3Asheets">9</a> for details.</p><p>The <span class="c013">fancysection.hva</span> file is intended to be loaded after
the document base style.
Hence the easiest way to load the <span class="c013">fancysection.hva</span> file
is by issuing <code>\usepackage{fancysection}</code> in the document preamble.
To allow processing by L<sup>A</sup>T<sub>E</sub>X, one may for instance create
an empty <span class="c013">fancysection.sty</span> file.</p><p>As an alternative, to use fancy section style in
<span class="c013">doc.tex</span> whose base style is <span class="c018">article</span>
you should issue the command:
</p><pre class="verbatim"> # hevea article.hva fancysection.hva doc.tex
</pre><p>You can also make a <span class="c013">doc.hva</span> file that contains the two lines:
</p><pre class="verbatim"> \input{article.hva}
\input{fancysection.hva}
</pre><p>And then launch <span class="c013">hevea</span> as:
</p><pre class="verbatim"> # hevea doc.hva doc.tex
</pre><p>Sectioning command background colours can be changed by
redefining the corresponding colours (<span class="c013">part</span>, <span class="c013">chapter</span>,
<span class="c013">section</span>,…).
For instance, you get various mixes of red and orange by:
</p><pre class="verbatim">\input{article.hva}
\input{fancysection.hva}
\definecolor{part}{named}{BrickRed}
\definecolor{section}{named}{RedOrange}
\definecolor{subsection}{named}{BurntOrange}
</pre><p>(See section <a href="#color%3Apackage">B.14.2</a> for details on the <span class="c013">named</span>
color model that is used above.)</p><p><a id="hevea_default208"></a>
Another choice is issuing the command
<code>\colorsections{</code><span class="c018">hue</span><code>}</code>, where
<span class="c018">hue</span> is a hue value to be interpreted in the HSV model.
For instance,
</p><pre class="verbatim">\input{article.hva}
\input{fancysection.hva}
\colorsections{20}
</pre><p>will yield sectional headers on a red-orange background.</p><p><a id="hevea_default209"></a>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A distribution features another style for fancy sectioning commands:
the <span class="c013">undersection</span> package provides underlined sectional headers.</p>
<!--TOC subsection id="winfonts" Targeting Windows-->
<h3 class="subsection" id="winfonts">B.16.5  Targeting Windows</h3><!--SEC END --><p>
<a id="hevea_default210"></a><a id="hevea_default211"></a>
At the time of this release, Windows support for symbols
through Unicode is not as complete as the one of Linux, which I am
using for testing H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.</p><p>One of the most salient shortcomings is the inability to display sub-elements
for big brackets, braces and parenthesis, which H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A normally
outputs when it processes <code>\left[</code>, <code>\right\}</code> etc.</p><p>We (hopefully) expect Windows fonts to display more of
Unicode easily in a foreseeable future. As a temporary fix, we provide
a style file <span class="c013">winfonts.hva</span>.
Authors concerned by producing pages that do not look too ugly
when viewed through Windows browsers are thus advised to
load the file <span class="c013">winfonts.hva</span>.
For instance they can invoke H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A as:
</p><pre class="verbatim"># hevea winfonts.hva ...
</pre><p>At the moment, loading <span class="c013">winfonts.hva</span>
only changes the rendering
of L<sup>A</sup>T<sub>E</sub>X big delimiters, avoiding the troublesome Unicode entities.
As an example, here are some examples of rendering.
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="c002 cellpading0"><tr><td class="hbar" colspan=5></td></tr>
<tr><td class="c029" colspan=2>delimiters</td><td class="c029" colspan=2>default</td><td class="c029">winfonts</td></tr>
<tr><td class="hbar" colspan=5></td></tr>
<tr><td class="c032"><span class="c013">\left\{  …  \right\}</span></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell">⎧<br>
⎪<br>
⎨<br>
⎪<br>
⎩</td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell">⎫<br>
⎪<br>
⎬<br>
⎪<br>
⎭</td></tr>
</table></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell"> / <br>
 | <br>
< <br>
 | <br>
 \ </td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell"> \<br>
 |<br>
 ><br>
 |<br>
 /</td></tr>
</table></td></tr>
<tr><td class="c032"><span class="c013">\left[  …  \right]</span></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell">⎡<br>
⎢<br>
⎢<br>
⎣</td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell">⎤<br>
⎥<br>
⎥<br>
⎦</td></tr>
</table></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell"><table class="delimleft"><tr><td class="bracell hbar c048"></td></tr>
<tr><td class="bracell c030"><div class="vbar" style="height:4em;"></div></td></tr>
<tr><td class="bracell hbar c048"></td></tr>
</table></td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell"><table class="delimright"><tr><td class="bracell hbar c048"></td></tr>
<tr><td class="bracell" style="text-align:right"><div class="vbar" style="height:4em;"></div></td></tr>
<tr><td class="bracell hbar c048"></td></tr>
</table></td></tr>
</table></td></tr>
<tr><td class="c032"><span class="c013">\left(  …  \right)</span></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell">⎛<br>
⎜<br>
⎜<br>
⎝</td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell">⎞<br>
⎟<br>
⎟<br>
⎠</td></tr>
</table></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell">/ <br>
| <br>
| <br>
\ </td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell"> \<br>
 |<br>
 |<br>
 /</td></tr>
</table></td></tr>
<tr><td class="c032"><span class="c013">\left\vert  …  \right\vert</span></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell">⎪<br>
⎪<br>
⎪<br>
⎪</td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell">⎪<br>
⎪<br>
⎪<br>
⎪</td></tr>
</table></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell"><div class="vbar c026"></div></td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell"><div class="vbar c026"></div></td></tr>
</table></td></tr>
<tr><td class="c032"><span class="c013">\left\Vert  …  \right\Vert</span></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell">⎪⎪<br>
⎪⎪<br>
⎪⎪<br>
⎪⎪</td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell">⎪⎪<br>
⎪⎪<br>
⎪⎪<br>
⎪⎪</td></tr>
</table></td><td class="c029">    </td><td class="c029"><table class="display"><tr class="c035"><td class="dcell"><div class="vbar c025"></div></td><td class="dcell"><div class="vbar c025"></div></td><td class="dcell"><table class="c002 cellpading0"><tr><td class="c029">1</td></tr>
<tr><td class="c029">2</td></tr>
<tr><td class="c029">3</td></tr>
</table></td><td class="dcell"><div class="vbar c025"></div></td><td class="dcell"><div class="vbar c025"></div></td></tr>
</table></td></tr>
<tr><td class="hbar" colspan=5></td></tr>
</table></td></tr>
</table><p>More generally, it remains authors responsibility to be careful not to
issue too refined Unicode entities. To that aim, authors that target
a wide audience should first limit themselves to the most common
symbols (<em>e.g.</em> use <code>\leq</code> [≤]
in place of <code>\preceq</code> [≼]) and, above all,
they should control the rendering of their documents using several browsers.</p>
<!--BEGIN NOTES section-->
<hr class="ffootnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes">
<a id="note9" href="#text9">8</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">According to
<span class="c013">date</span> man page.</div>
</dd></dl>
<!--END NOTES-->
<!--TOC section id="sec181" Implemented Packages-->
<h2 class="section" id="sec181">B.17  Implemented Packages</h2><!--SEC END --><p><a id="implemented:package"></a>
</p><!--NAME manual-packages.html-->
<p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A distribution includes <span class="c013">.hva</span> packages that are
implementations of L<sup>A</sup>T<sub>E</sub>X packages.
Packages described in the “<em>Blue Book</em>” (<span class="c013">makeidx</span>,
<span class="c013">ifthen</span>, <span class="c013">graphics</span> —and <span class="c013">graphicx</span>!—,
<span class="c013">color</span>, <span class="c013">alltt</span>) are provided. Additionally, quite a
few extra packages are provided. I provide no full documentation for
these packages, users should refer to the first pages of the package
documentation, which can usually be found in the book [<a href="#latexbis">L<sup>A</sup>T<sub>E</sub>X-bis</a>],
in your local
L<sup>A</sup>T<sub>E</sub>X installation or in a TeX CTAN-archive.</p><p>At the moment, most package options are ignored, except for the babel
package, where it is essential.</p>
<!--TOC subsection id="sec182" AMS compatibility-->
<h3 class="subsection" id="sec182">B.17.1  AMS compatibility</h3><!--SEC END --><p>
<a id="hevea_default212"></a>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A <span class="c013">amsmath</span> package defines some of the constructs of the
<span class="c013">amsmath</span> package. At the moment, supported constructs are
the <code>cases</code> environment and matrix
environments [<a href="#latexbis">L<sup>A</sup>T<sub>E</sub>X-bis</a>, Section 8.4], the
environments for multi-line displayed
equations (<code>gather</code>,
<code>split</code>,…) [<a href="#latexbis">L<sup>A</sup>T<sub>E</sub>X-bis</a>, Section 8.5] and the
<code>\numberwithin</code> command [<a href="#latexbis">L<sup>A</sup>T<sub>E</sub>X-bis</a>, Section 8.6.2].</p><p><a id="hevea_default213"></a>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A provides support for the <span class="c013">amssymb</span> symbols using
Unicode. I found Unicode equivalent for most symbols. However, a few symbols
remain undefined (<em>e.g.</em> <code>\varsubsetneqq</code>).</p>
<!--TOC subsection id="sec183" The <span class="c013">array</span> and <span class="c013">tabularx</span>
packages-->
<h3 class="subsection" id="sec183">B.17.2  The <span class="c013">array</span> and <span class="c013">tabularx</span>
packages</h3><!--SEC END --><p><a id="arraypack"></a>
<a id="hevea_default214"></a><a id="hevea_default215"></a>The <a href="http://www.ctan.org/pkg/array.html"><span class="c013">array</span></a>
package is described in
[<a href="#latexbis">L<sup>A</sup>T<sub>E</sub>X-bis</a>, Section 5.3] and in the local documentation of modern L<sup>A</sup>T<sub>E</sub>X
installations.
It is a compatible extension of L<sup>A</sup>T<sub>E</sub>X arrays (see <a href="#arraydef">B.10.2</a>).
Basically, it provides new column specifications
and a <code>\newcolumntype</code> construct for user-defined column
specifications.
Table <a href="#arraytable">1</a> gives a summary of the new column
specifications and of how H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
implements them.
</p><blockquote class="table"><div class="center"><hr class="c049"></div>
<div class="caption"><table class="c002 cellpading0"><tr><td class="c039">Table 1: <a id="arraytable"></a> Column specifications from the
<span class="c013">array</span> package</td></tr>
</table></div>
<div class="center">
<table class="cellpading0" style="border-spacing:6px;border-collapse:separate;width:70%"><tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c041"><code>m{</code><span class="c018">width</span><code>}</code></td><td class="c029">  </td><td class="c039">Equivalent to the <code>p</code> column specification (the <span class="c018">width</span>
argument is ignored, entries are typeset in paragraph mode with
paragraph breaks being reduced to a single line break), except that the entries
are centered vertically.</td></tr>
<tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c041"><code>b{</code><span class="c018">width</span><code>}</code></td><td class="c029">  </td><td class="c039">Equivalent to the <code>p</code> column specification, except that the entries
are bottom-aligned vertically.</td></tr>
<tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c041"><code>>{</code><span class="c018">decl</span><code>}</code></td><td class="c029">  </td><td class="c039">Can be used before <code>l</code>, <code>c</code>, <code>r</code>,
<code>p{</code>…<code>}</code>, <code>m{</code>…<code>}</code> or
<code>b{</code>…<code>}</code>.
It inserts <span class="c018">decl</span> in front of the entries in the corresponding
column. </td></tr>
<tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c041"><code><{</code><span class="c018">decl</span><code>}</code></td><td class="c029">  </td><td class="c039">Can be used after <code>l</code>, <code>c</code>, <code>r</code>,
<code>p{</code>…<code>}</code>, <code>m{</code>…<code>}</code> or
<code>b{</code>…<code>}</code>.
It inserts <span class="c018">decl</span> after entries in the corresponding
column. </td></tr>
<tr><td class="hbar" colspan=3></td></tr>
<tr><td class="c041"><code>!{</code><span class="c018">decl</span><code>}</code></td><td class="c029">  </td><td class="c039">Equivalent to <code>@{</code><span class="c018">decl</span><code>}</code> </td></tr>
<tr><td class="hbar" colspan=3></td></tr>
</table>
</div>
<div class="center"><hr class="c049"></div></blockquote><p>Note that <em>centered</em>, <em>top-aligned</em> or <em>bottom-aligned</em>
in the vertical direction, do not
have exactly the same meaning in L<sup>A</sup>T<sub>E</sub>X and in html. However, the
aspect is the same when all columns agree w.r.t. vertical alignment.
Ordinary column types (<code>c</code>, <code>l</code> and <code>r</code>)
do not specify vertical alignment, which therefore becomes browser
dependent.</p><p>The <code>>{</code><span class="c018">decl</span><code>}</code> and <code><{</code><span class="c018">decl</span><code>}</code>
constructs permit the encoding of T<sub>E</sub>X <code>\cases</code> macro as follows:
</p><pre class="verbatim">\def\cases#1{\left\{\begin{array}{l>{$}l<{$}}#1\end{array}\right.}
</pre><p>(This is an excerpt of the <span class="c013">latexcommon.hva</span> file.)</p><p>New column specifications are defined by the <code>\newcolumntype</code>
construct:
</p><div class="flushleft">
  <code>\newcolumntype{</code><span class="c018">col</span><code>}[</code><span class="c018">narg</span><code>]{</code><span class="c018">body</span><code>}</code>
</div><p>
Where <span class="c018">col</span> is one letter, the optional <span class="c018">narg</span> is a
number (defaults to <span class="c013">0</span>), and <span class="c013">body</span> is built up with
valid column specifications and macro-argument references
(<code>#</code><span class="c018">int</span>).
Examples are:
</p><pre class="verbatim">\newcolumntype{C}{>{\bf}c}
\newcolumntype{E}[1]{*{#1}{c}}
\begin{tabular}{CE{3}}\hline
one & two & three & four \\
five & six & seven & eight \\ \hline
\end{tabular}
</pre><p>The column specification
<span class="c013">C</span> means that entries will be typeset centered and using bold
font, while the column specifications <code>E{</code><span class="c018">num</span><code>}</code>
stands for <span class="c018">num</span> centered columns. We get:</p><table class="c002 cellpading0"><tr><td class="hbar" colspan=4></td></tr>
<tr><td class="c029"><span class="c022">one</span></td><td class="c029">two</td><td class="c029">three</td><td class="c029">four </td></tr>
<tr><td class="c029"><span class="c022">five</span></td><td class="c029">six</td><td class="c029">seven</td><td class="c029">eight </td></tr>
<tr><td class="hbar" colspan=4></td></tr>
</table><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements column specifications with commands defined in the
<code>\newcommand</code> style. Thus, they have the same behaviour as regards
double definition, which is not performed and induces a warning
message.
Thus, a column specification that is
first defined in a <span class="c013">macro.hva</span> specific
file, overrides the document definition.</p><p>The <a href="http://www.ctan.org/pkg/tabularx.html"><span class="c013">tabularx</span></a>
package [<a href="#latexbis">L<sup>A</sup>T<sub>E</sub>X-bis</a>, Section 5.3.5] provides a new tabular
environment <code>tabularx</code> and a new column type <code>X</code>. H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
makes the former equivalent to <code>tabular</code> and the latter
equivalent to <code>p{</code><span class="c018">ignored</span><code>}</code>. By contrast with the
subtle array formatting that the <span class="c013">tabularx</span> package performs,
this may seem a crude implementation. However, rendering is usually
correct, although different.</p><p>More generally and from the html point of view such sophisticated
formatting is browser job in the first place.
However, the html definition allows suggested widths or heights for
table entries and table themselves.
From H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A point of view, drawing the border line between what can be
specified and what can be left to the browser is not obvious at all.
At the moment H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A choice is not to specify too much (in
particular, all length
arguments, either to column specifications or to the arrays
themselves, are ignored). As a consequence, the final, browser viewed,
aspect of arrays will usually be different from their printed
aspect.</p>
<!--TOC subsection id="calc" The <span class="c013">calc</span> package-->
<h3 class="subsection" id="calc">B.17.3  The <span class="c013">calc</span> package</h3><!--SEC END --><p>
<a id="hevea_default216"></a>The <a href="http://www.ctan.org/pkg/calc.html"><span class="c013">calc</span></a>
package enables using traditional, infix, notation for
arithmetic operations
inside the <span class="c018">num</span> argument to the
<code>\setcounter{</code><span class="c018">name</span><code>}{</code><span class="c018">num</span><code>}</code>
and <code>\addtocounter{</code><span class="c018">name</span><code>}{</code><span class="c018">num</span><code>}</code>
constructs (see [<a href="#latexbis">L<sup>A</sup>T<sub>E</sub>X-bis</a>, Section A.4])</p><p>The <span class="c013">calc</span> package provides a similar extension of the syntax
of the <span class="c018">len</span> argument to the <code>\setlength</code> and
<code>\addtolength</code> constructs.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not implement this extension, since it does not
implement length registers in the first place.</p>
<!--TOC subsection id="inputenc" Specifying the document input encoding, the <span class="c013">inputenc</span> package-->
<h3 class="subsection" id="inputenc">B.17.4  Specifying the document input encoding, the <span class="c013">inputenc</span> package</h3><!--SEC END --><p>
<a id="hevea_default217"></a>The <a href="http://www.ctan.org/pkg/inputenc.html"><span class="c013">inputenc</span></a>
package enables L<sup>A</sup>T<sub>E</sub>X to process a file
according to various <em>8 bits</em> encodings, plus <span class="c013">UTF-8</span>.
The one used encoding is specified as an option while loading the package
<code>\usepackage[</code><span class="c018">encoding</span><code>]{inputenc}</code>.
At the moment, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A recognises ten latin encodings
(from <span class="c013">latin1</span> to <span class="c013">latin10</span>),
the <span class="c013">koi8-r</span> encoding,
the <span class="c013">ascii</span> encoding,
four windows encodings, the <span class="c013">applemac</span> encoding, and the
<span class="c013">utf8</span> encoding.
It is important to notice that loading the <code>inputenc</code> package
alters the html document charset.
For instance if the <span class="c013">latin9</span> input encoding is selected by:
</p><pre class="verbatim">\usepackage[latin9]{inputenc}
</pre><p>Then, the document charset is <code>ISO-8859-15</code>, which is an
enhanced version of <code>ISO-8859-1</code> with some characters
for Œ, œ and €.
The rationale behind changing the output document charset at the same
time as changing the input encoding is to allow
non-ascii bytes in the input file to be replicated as
themselves in the output file.</p><p><a id="hevea_default218"></a>
However, one can change the document charset (and the output
translator) by using the internal command <code>\@def@charset</code>.
For instance, one can specify <span class="c013">latin1</span> encoding, while
producing html pages in ascii:
</p><pre class="verbatim">\usepackage[latin1]{inputenc}
%HEVEA\@def@charset{US-ASCII}
</pre><p>See section <a href="#encodings">8.6</a> for a more thorough description of html
charset management.</p><p><a id="hevea_default219"></a>The <span class="c013">inputenc</span> package also provides the
command <code>\inputcoding{</code><span class="c018">encoding</span><code>}</code> that
changes the input encoding at any time.
The argument <span class="c018">encoding</span> can be any of the options accepted
by <code>\usepackage[</code><span class="c018">encoding</span><code>]{inputenc}</code>.
The command <code>\inputcoding</code> of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
follows the behaviour of its L<sup>A</sup>T<sub>E</sub>X counterpart, it the sense
that it obeys scope rules.
Notice that <code>\inputcoding</code> does not change the document output
encoding and charset.</p>
<!--TOC subsection id="sec186" More symbols-->
<h3 class="subsection" id="sec186">B.17.5  More symbols</h3><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implements the following packages: <span class="c013">latexsym</span>
<span class="c013">amssymb</span>, <span class="c013">textcomp</span> (a.k.a. “Text companion”)
and <span class="c013">eurosym</span> (a nice € symbol in L<sup>A</sup>T<sub>E</sub>X).</p>
<!--TOC subsection id="commentpack" The <span class="c013">comment</span> package-->
<h3 class="subsection" id="commentpack">B.17.6  The <span class="c013">comment</span> package</h3><!--SEC END --><p>
<a id="hevea_default220"></a>The <a href="http://www.ctan.org/pkg/comment.html"><span class="c013">comment</span></a> package provides two commands,
<code>\excludecomment</code> and <code>\includecomment</code>, for (re-)defining
new environments that ignore their content or that do nothing. The
comment environment is also defined as an environment of the first
kind.</p>
<!--TOC subsection id="multind" Multiple Indexes with the <span class="c013">index</span> and
<span class="c013">multind</span> packages-->
<h3 class="subsection" id="multind">B.17.7  Multiple Indexes with the <span class="c013">index</span> and
<span class="c013">multind</span> packages</h3><!--SEC END --><p>
<a id="hevea_default221"></a><a id="hevea_default222"></a>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A supports several simultaneous indexes, following the scheme
of the
<a href="ftp://tug.ctan.org/pub/tex-archive/help/Catalogue/entries/index.html"><span class="c013">index</span></a> package,
which is present in modern L<sup>A</sup>T<sub>E</sub>X distributions.
This scheme is backward compatible with the standard indexing scheme
of L<sup>A</sup>T<sub>E</sub>X.</p><p>Support is not complete, but the most useful commands are available.
More precisely, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A knows the following commands:
</p><dl class="description"><dt class="dt-description">
<span class="c022"><span class="c013">\newindex{</span><span class="c018">tag</span><span class="c013">}{</span><span class="c018">ext</span><span class="c013">}{</span><span class="c018">ignored</span><span class="c013">}{</span><span class="c018">indexname</span><span class="c013">}</span></span></dt><dd class="dd-description">
Declare an index.
The first argument <span class="c018">tag</span> is a tag to select this index in other
commands; <span class="c018">ext</span> is the extension of the index information file
generated by L<sup>A</sup>T<sub>E</sub>X (e.g., <span class="c013">idx</span>); <span class="c018">ignored</span> is ignored by
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A; and <span class="c018">indexname</span> is the title of the index.
There also exists a
<code>\renewindex</code> commands that takes the same arguments and that can be
used to redefine previously declared indexes.
</dd><dt class="dt-description"><span class="c014">\makeindex</span></dt><dd class="dd-description"> Perform
<code>\newindex{default}{idx}{ind}{Index}</code>.
</dd><dt class="dt-description"><span class="c022"><span class="c013">\index[</span><span class="c018">tag</span><span class="c013">]{</span><span class="c018">arg</span><span class="c013">}</span></span></dt><dd class="dd-description">
Act as the L<sup>A</sup>T<sub>E</sub>X <code>\index</code> command except that the information
extracted from <span class="c018">arg</span> goes to the <span class="c018">tag</span> index.
The <span class="c018">tag</span> argument defaults to <code>default</code>, thereby yielding
standard L<sup>A</sup>T<sub>E</sub>X behaviour for the <code>\index</code> command without an
optional argument.
There also exists a stared-variant <code>\index*</code> that Additionally
typesets <span class="c018">arg</span>.
</dd><dt class="dt-description"><span class="c022"><span class="c013">\printindex[</span><span class="c018">tag</span><span class="c013">]</span></span></dt><dd class="dd-description"> Compute, format and
output index whose tag is <span class="c018">tag</span>. The <span class="c018">tag</span> argument
defaults to <code>default</code>.
</dd></dl><p>The <a href="http://www.ctan.org/pkg/multind.html"><span class="c013">multind</span></a> package is
supported to some extend, but <span class="c013">index</span> is definitely to be
preferred.</p>
<!--TOC subsection id="sec189" “Natural” bibliographies, the <span class="c013">natbib</span> package -->
<h3 class="subsection" id="sec189">B.17.8  “Natural” bibliographies, the <span class="c013">natbib</span> package </h3><!--SEC END --><p>
L<sup>A</sup>T<sub>E</sub>X <a href="http://www.ctan.org/pkg/natbib.html">version of <span class="c013">natbib</span></a>
is present in modern installations.<a id="hevea_default223"></a></p><p>Implementation is quite complete and compatible
with version 8.0 of the <span class="c013">natbib</span> package
(with the <span class="c013">keyval</span> style command <code>\setcitestyle</code>).</p><p>Unimplemented features are the sorting and compression of references.
Automatic generation of an index of citations is handled, but
the current implementation probably is quite fragile.</p>
<!--TOC subsection id="sec190" Multiple bibliographies-->
<h3 class="subsection" id="sec190">B.17.9  Multiple bibliographies</h3><!--SEC END --><!--TOC subsubsection id="sec191" The <span class="c013">multibib</span> package-->
<h4 class="subsubsection" id="sec191">The <span class="c013">multibib</span> package</h4><!--SEC END --><p>
<a id="hevea_default224"></a><a id="hevea_default225"></a>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A provides a slightly incomplete implementation of the
<span class="c013">multibib</span> package. The one non-implemented feature is the
simultaneous definition of more than one bibliography.
That is one cannot invoke <code>\newcites</code> as follows:
</p><pre class="verbatim">\newcites{suf1, suf2}{Title1, Title2}
</pre><p>Instead, one should perform to calls to the <code>\newcites</code> command:
</p><pre class="verbatim">\newcites{suf1}{Title1}\newcites{suf2}{Title2}
</pre><!--TOC subsubsection id="sec192" The <span class="c013">chapterbib</span> package-->
<h4 class="subsubsection" id="sec192">The <span class="c013">chapterbib</span> package</h4><!--SEC END --><p>
<a id="hevea_default226"></a>
A basic implementation is provided. At the moment, you can
define one bibliography per included file and no toplevel
bibliography.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implementation of this package recognises the option
<code>sectionbib</code> and provides the command <code>\sectionbib</code>
to change the sectioning command introduced by bibliographies.</p>
<!--TOC subsection id="sec193" Support for <span class="c013">babel</span>-->
<h3 class="subsection" id="sec193">B.17.10  Support for <span class="c013">babel</span></h3><!--SEC END --><p><a id="hevea_default227"></a>
</p>
<!--TOC subsubsection id="sec194" Basics-->
<h4 class="subsubsection" id="sec194">B.17.10.1  Basics</h4><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A offers support for the L<sup>A</sup>T<sub>E</sub>X package <span class="c013">babel</span>. When it reads the command
</p><pre class="verbatim"> \usepackage[lang-list]{babel}
</pre><p>it loads <span class="c013">babel.hva</span>, and sends it the saved <span class="c013">lang-list</span>. The
file <span class="c013">babel.hva</span> then looks at each language (say <span class="c013">x</span>) in it, and loads <span class="c013">x.hva</span>, which offers support for the language <span class="c013">x</span>. As in L<sup>A</sup>T<sub>E</sub>X, the last language in the list is selected as default. As an example the command
</p><pre class="verbatim">\usepackage[english,french,german]{babel}
</pre><p>would load <span class="c013">babel.hva</span>, then the files <span class="c013">english.hva,french.hva,german.hva</span> containing the respective definitions, and finally activate the definitions in <span class="c013">german.hva</span> and sets the current language to german.</p>
<!--TOC subsubsection id="sec195" Commands and languages-->
<h4 class="subsubsection" id="sec195">B.17.10.2  Commands and languages</h4><!--SEC END --><p>
The following babel commands for changing and querying the language work as in L<sup>A</sup>T<sub>E</sub>X :
</p><ol class="enumerate" type=1><li class="li-enumerate">
<code>\selectlanguage</code> : to change the language
</li><li class="li-enumerate"><code>\iflanguage</code> : to branch after comparing with current language
</li></ol><p>The language specific details are described in the corresponding
<code>.hva</code> file, just as in the <code>.sty</code> file for L<sup>A</sup>T<sub>E</sub>X. Users
need to supply this file for their language, or modify/check the files
if they are already supplied with the distribution. The list of
languages is given below.</p><div class="center"><a id="hevea_default228"></a>
<table class="c001 cellpadding1" border=1><tr><td class="c031">american</td><td class="c031">austrian</td><td class="c031">brazil</td><td class="c031">catalan </td></tr>
<tr><td class="c031">check</td><td class="c031">croatian</td><td class="c031">danish</td><td class="c031">dutch </td></tr>
<tr><td class="c031">english</td><td class="c031">esperanto</td><td class="c031">finnish</td><td class="c031">french </td></tr>
<tr><td class="c031">galician</td><td class="c031">german</td><td class="c031">italian</td><td class="c031">magyar </td></tr>
<tr><td class="c031">norsk</td><td class="c031">nynorsk</td><td class="c031">polish</td><td class="c031">portuges </td></tr>
<tr><td class="c031">romanian</td><td class="c031">russian</td><td class="c031">slovak</td><td class="c031">slovene </td></tr>
<tr><td class="c031">spanish</td><td class="c031">swedish</td><td class="c031">turkish</td><td class="c031"> </td></tr>
</table>
</div>
<!--TOC subsubsection id="sec196" Writing <span class="c013">hva</span> files-->
<h4 class="subsubsection" id="sec196">B.17.10.3  Writing <span class="c013">hva</span> files</h4><!--SEC END --><p>The languages for which <span class="c013">.hva</span> files are available with the
distribution are english, french, german, austrian and czech. These
may need to be modified as not all accents and hyphenation techniques
are supported.</p><p>They can be written/modified as simple T<sub>E</sub>X files (see the section  <a href="#texmacros">B.16.1.1</a> on writing T<sub>E</sub>X macros for details). As an example, one may also take a look at the file <a href="../html/french.hva">french.hva</a>, which describes the details for french. </p><p>Note how all definitions are <em>inside</em> the definition for
<code>\french@babel</code>, which is the command that
<code>\selectlanguage{french}</code> would call. Similar commands need to be
provided (<em>i.e.</em> <code>\x@babel</code> in <code>\x.hva</code> for language
<code>x</code>).</p><p>Some definitions may involve specifying Unicode characters, for doing
so, using the <code>\@print@u</code> is recommended (cf. Section <a href="#internal">8.3</a>).
The definition of Unicode characters can be found at
<a href="http://www.unicode.org/charts/">http://www.unicode.org/charts/</a>.
Most language specific Unicode characters can be found in the first
few files.</p>
<!--TOC subsection id="urlpackage" The <span class="c013">url</span> package-->
<h3 class="subsection" id="urlpackage">B.17.11  The <span class="c013">url</span> package</h3><!--SEC END --><p>
<a id="hevea_default229"></a><a id="hevea_default230"></a><a id="hevea_default231"></a>L<sup>A</sup>T<sub>E</sub>X <a href="http://www.ctan.org/pkg/url.html">source</a>.</p><p>This package in fact provides a enhanced <code>\verb</code> command that
can appear inside other command arguments.
This command is named <code>\url</code>,
but it can be used for any verbatim text, including DOS-like path
names.
Hence, one can insert urls in one’s document without worrying about
L<sup>A</sup>T<sub>E</sub>X active characters:
</p><pre class="verbatim">This is a complicated url: \url{http://foo.com/~user#label%coucou}.
</pre><p>which gets typeset as: “This is a complicated url: <span class="c013">http://foo.com/~user#label%coucou</span>.”</p><p>The main use for the <code>\url</code> command is to specify urls as arguments to
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A commands for hyperlinks (see section <a href="#hyperlink">8.1.1</a>):
</p><pre class="verbatim">\hevea{} home page is
\ahrefurl{\url{http://hevea.inria.fr/}}
</pre><p>It yields: “H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A home page is
<a href="http://hevea.inria.fr/"><span class="c013">http://hevea.inria.fr/</span></a>”.</p><p><a id="hevea_default232"></a>
However the <code>\url</code> command is fragile, as a consequence it
cannot be used inside <code>\footahref</code> first argument (This is a
L<sup>A</sup>T<sub>E</sub>X problem, not an H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A one).
The <span class="c013">url</span> package solves this problem by providing the
<code>\urldef</code> command
for defining commands whose body is typeset by using <code>\url</code>:
</p><pre class="verbatim">\urldef{\heveahome}{\url}{http://hevea.inria.fr/}
</pre><p>Such a source defines the robust command <code>\heveahome</code> as the
intended url.
Hence the following source works as expected:
</p><pre class="verbatim">Have a look at \footahref{\heveahome}{\hevea{} home page}
</pre><p>It yields: “Have a look at <a href="http://hevea.inria.fr/">H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A home page</a>”.</p><p>Using <code>\url</code> inside command definitions with a
<code>#</code><span class="c018">i</span> argument is a bad idea, since
it gives “verbatim” a rather random meaning.
Unfortunately, in some situations (e.g, no <code>%</code>, no <code>#</code>),
it may work in L<sup>A</sup>T<sub>E</sub>X. By
contrast, it does not work in H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A. In such situations,
<code>\urldef</code> should be used.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implementation is somehow compatible at the “programming level”.
Thus, users can define new commands whose argument is understood
verbatim. The <span class="c013">urlhref.hva</span> style file
from the distribution
takes advantage of this to define the <code>\url</code> command, so that it both
typesets an url and inserts a link to it.
</p><pre class="verbatim">\input{urlhref.hva}
Have a look at \url{http://hevea.inria.fr/}
</pre><p>It yields “Have a look at <a href="http://hevea.inria.fr/"><span class="c013">http://hevea.inria.fr/</span></a>”.
The <span class="c013">urlhref.hva</span>
style file (which is an H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A style file and not a L<sup>A</sup>T<sub>E</sub>X
style file) can be adequate for bibliographic references,
which often use <code>\url</code> for its typesetting power.
Of course, loading <span class="c013">urlhref.hva</span> only makes sense when
all arguments to <code>\url</code> are urls…</p>
<!--TOC subsection id="sec198" Verbatim text: the <span class="c013">moreverb</span> and
<span class="c013">verbatim</span> packages-->
<h3 class="subsection" id="sec198">B.17.12  Verbatim text: the <span class="c013">moreverb</span> and
<span class="c013">verbatim</span> packages</h3><!--SEC END --><p>
These two packages provide new commands and environments for
processing verbatim text.
I recommend using
<a href="http://www.ctan.org/pkg/moreverb.html"><span class="c013">moreverb</span></a>
rather than <span class="c013">verbatim</span>,
since H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implementation is more advanced for the former package.</p>
<!--TOC subsection id="listings:package" Typesetting computer languages: the <span class="c013">listings</span> package-->
<h3 class="subsection" id="listings:package">B.17.13  Typesetting computer languages: the <span class="c013">listings</span> package</h3><!--SEC END --><p>
<a id="hevea_default233"></a>I strongly recommend the
<a href="http://www.ctan.org/pkg/listings.html"><span class="c013">listings</span></a> package.
Learning the user interface requires a little effort, but it is worth
it.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A features a quite compatible implementation, please refer to
the original package documentation.
Do not hesitate to report discrepancies.
Note that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not produce very compact
html in case you use this package.
This can be cured by
giving <span class="c013">hevea</span> the command-line option <a id="hevea_default234"></a><span class="c013">-O</span>
(see <a href="#heveaoptions">C.1.1.4</a>).</p><p>The <span class="c013">lstlisting</span> environment is styled through
an homonymous style class (see <a href="#css%3Achange%3Aall">9.2</a> and <a href="#css%3Achange">9.3</a>) and
most <span class="c013">lstlisting</span> environments get translated to <code>div</code>
elements with the appropriate <code>\getenvclass{lstlisting}</code> class,
which, by default is <span class="c013">lstlisting</span>.
A few points deserve mention:
</p><ol class="enumerate" type=1><li class="li-enumerate">
The definition of default style class <span class="c013">lstlisting</span> includes
the important declarations
<code>font-family:monospace;</code> and <code>white-space:pre;</code>, which, more or less,
specify non-proportional font and mandatory line breaks.
In case you replace <span class="c013">lstlisting</span> by another style class (by
<code>\setenvclass{lstlisting}{</code><span class="c018">another one</span><code>}</code>), your
alternate definition should probably feature an identical
specification. Otherwise, rendering would be poor, as regards spacing
and line breaks.
Here is how specific listings are styled.
We first define a new environment to typeset programs written in the C
language, by using the command <code>\lstnewenvironment</code>:
<pre class="verbatim">\lstdefinestyle{colors}{keywordstyle={\bf\color{blue}}, commentstyle={\em\color{magenta}}}
\lstnewenvironment{clisting}
{\setenvclass{lstlisting}{clisting}\lstset{language=C, style=colors}}
{}
</pre>The command
<code>\lstnewenvironment{</code><span class="c018">name</span><code>}{</code><span class="c018">starting
code</span><code>}{</code><span class="c018">ending code</span><code>}</code> is from the
<span class="c013">listings</span> package, with similar semantics.
In the starting code above, the fragment
<code>\setenvclass{lstlisting}{clisting}</code> instructs H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A to
use the style class <span class="c013">clisting</span> locally (notice that it could just
be another name). The style class <span class="c013">clisting</span> is defined in
the document preamble as follows:
<pre class="verbatim">\newstyle{.clisting}{font-family:monospace;white-space:pre;
border-left:solid black;padding-left:2ex;margin-left:2ex;}
</pre>Typesetting a C listing with a black border on the left is then as
simple as:
<pre class="verbatim">\begin{clisting}
/* Compute, guess what! */
int fact(int n) {
int r = 1 ;
for ( ; n > 0 ; n--) {
r *= n ;
}
return r ;
}
\end{clisting}
</pre>The final result is:
<div class="clisting"><span class="c008"><em>/* Compute, guess what! */</em></span>
<span class="c023">int</span> fact(<span class="c023">int</span> n) {
<span class="c023">int</span> r = 1 ;
<span class="c023">for</span> ( ; n > 0 ; n--) {
r *= n ;
}
<span class="c023">return</span> r ;
}</div></li><li class="li-enumerate">When listings are framed, that is, when some
<span class="c013">frame=</span>… or <span class="c013">background=</span>… keyval
specifications are active, they no longer get translated to <code>div</code>
elements.
Instead they get translated to one cell tables whose <code>td</code>
and <code>table</code> elements
are styled through style classes <span class="c013">lstlisting</span> and
<span class="c013">lstframe</span>, respectively. Of course, those two style classes
follow the usual <code>\setenvclass</code>/<code>\getenvclass</code> mechanism.
That way, one can for instance center all framed listings by issuing
the following declaration in the document preamble:
<pre class="verbatim">\newstyle{.lstframe}{margin:auto;}
</pre>Notice that the default style class <span class="c013">lstframe</span> is empty.</li><li class="li-enumerate"><a id="hevea_default235"></a>Unfortunately the <code>white-space:pre;</code> style declaration is still a
bit young, and some browsers implement it in rather incomplete
fashion. This is particularly true as regards text copy-pasted from
browser display. In case you want to provide your readers with easy
copy-paste of <span class="c013">listings</span>, you can, by issuing the command
<code>\lstavoidwhitepre</code> in the document preamble. Then,
<code>white-space:pre;</code> is not used any longer: spaces get rendered
by non-breaking space entities and line-breaks by <code><BR></code> elements,
which significantly increase output size. However, as a positive
consequence, display remains correct and text copy-pasted from browser
display indeed possesses the line-breaks shown in display.
</li></ol>
<!--TOC subsection id="sec200" (Non-)Multi page tabular material-->
<h3 class="subsection" id="sec200">B.17.14  (Non-)Multi page tabular material</h3><!--SEC END --><p>
<a id="hevea_default236"></a><a id="hevea_default237"></a>L<sup>A</sup>T<sub>E</sub>X source
for the
<a href="http://www.ctan.org/pkg/longtable.html"><span class="c013">longtable</span></a>
and
<a href="http://www.ctan.org/pkg/supertabular.html"><span class="c013">supertabular</span></a>
packages.</p><p>Those two packages provide L<sup>A</sup>T<sub>E</sub>X users with the
possibility to typeset tabular material over several
pages [<a href="#latexbis">L<sup>A</sup>T<sub>E</sub>X-bis</a>, Section 5.4]. Of course, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
does not care much about physical pages.
Thus the <span class="c013">supertabular</span>
and <span class="c013">longtable</span> environments are rendered more or less
as <span class="c013">tabular</span> environments inside <span class="c013">table</span> environments.</p>
<!--TOC subsection id="mathpartir:package" Typesetting inference rules: the
<span class="c013">mathpartir</span> package-->
<h3 class="subsection" id="mathpartir:package">B.17.15  Typesetting inference rules: the
<a id="mathpartir"><span class="c013">mathpartir</span></a> package</h3><!--SEC END --><p>
<a id="hevea_default238"></a><a id="hevea_default239"></a>The <span class="c013">mathpartir</span> package, authored by D. Rémy, essentially
provides two features:
</p><ol class="enumerate" type=1><li class="li-enumerate">
An environment <span class="c013">mathpar</span> for typesetting a sequence of math formulas in mixed horizontal and vertical mode. The environment selects the best arrangement according to the line width, exactly as paragraph mode does for words.
</li><li class="li-enumerate">A command <code>\inferrule</code> (and its starred variant) for
typesetting inferences rules.
</li></ol><p>
We give a short description, focussing on H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A-related details.
Users are encouraged to refer to the
<a href="http://pauillac.inria.fr/~remy/latex/index.html#tir">original
documentation</a> of the package.</p><p>In the following, comments on rule typesetting apply to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output
and not to L<sup>A</sup>T<sub>E</sub>X output.</p>
<!--TOC subsubsection id="sec202" The mathpar environment-->
<h4 class="subsubsection" id="sec202">B.17.15.1  The mathpar environment</h4><!--SEC END --><p><a id="hevea_default240"></a></p><p>In its L<sup>A</sup>T<sub>E</sub>X version, the <span class="c013">mathpar</span> environment is a
“paragraph mode for formulas”. It allows to typeset long list of
formulas putting as many as possible on the same line:
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c036"><div class="lstlisting">\begin{mathpar}
A-Formula \and
Longer-Formula \and
And \and The-Last-One
\end{mathpar}</div></td><td class="c036">        </td><td class="c036"><div class="mathpar">
<table class="mprow"><tr class="c035"><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c018">A</span>−<span class="c018">Formula</span> 
</td></tr>
</table></td><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c018">Longer</span>−<span class="c018">Formula</span>
</td></tr>
</table></td><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c018">And</span> 
</td></tr>
</table></td><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c018">The</span>−<span class="c018">Last</span>−<span class="c018">One</span>
</td></tr>
</table></td></tr>
</table></div>
</td></tr>
</table>
</div><p>
In the example above, formulas are separated with <code>\and</code>. The
L<sup>A</sup>T<sub>E</sub>X implementation also changes the meaning of paragraph breaks
(either explicit as a <code>\par</code> command or implicit as a blank line)
to act as <code>\and</code>. It also redefines the command <code>\\</code> as
an explicit line-break in the flow of formulas.
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c036"><div class="lstlisting">\begin{mathpar}
\int_0^2 xdx = \frac{3}{2}
\\
\int_0^3 xdx = \frac{5}{2}
\end{mathpar}</div></td><td class="c036">        </td><td class="c036"><div class="mathpar">
<table class="mprow"><tr class="c035"><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c017">∫</span></td><td class="dcell"><table class="display"><tr><td class="dcell c030">2</td></tr>
<tr><td class="dcell c030"><br>
<br>
</td></tr>
<tr><td class="dcell c030">0</td></tr>
</table></td><td class="dcell"> <span class="c018">xdx</span> = </td><td class="dcell"><table class="display"><tr><td class="dcell c027">3</td></tr>
<tr><td class="hbar"></td></tr>
<tr><td class="dcell c027">2</td></tr>
</table></td></tr>
</table></td></tr>
</table><table class="mprow"><tr class="c035"><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c017">∫</span></td><td class="dcell"><table class="display"><tr><td class="dcell c030">3</td></tr>
<tr><td class="dcell c030"><br>
<br>
</td></tr>
<tr><td class="dcell c030">0</td></tr>
</table></td><td class="dcell"> <span class="c018">xdx</span> = </td><td class="dcell"><table class="display"><tr><td class="dcell c027">5</td></tr>
<tr><td class="hbar"></td></tr>
<tr><td class="dcell c027">2</td></tr>
</table></td></tr>
</table></td></tr>
</table></div>
</td></tr>
</table>
</div><p>The H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A version is simplistic:
Formulas are typeset in math display
mode,
<code>\and</code> separators always produce horizontal space, while
<code>\\</code> always produce line-breaks.
However, when prefixed by <code>\hva</code> the meaning of explicit
separators is reversed: that is,
<code>\hva\and</code> produces a line-break, while <code>\hva\\</code>
produces horizontal space.
Hence, we can typeset the previous example on two lines:
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c036"><div class="lstlisting">\begin{mathpar}
A-Formula \and
Longer-Formula \hva\and
And \and The-Last-One
\end{mathpar}</div></td><td class="c036">        </td><td class="c036"><div class="mathpar">
<table class="mprow"><tr class="c035"><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c018">A</span>−<span class="c018">Formula</span> </td></tr>
</table></td><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c018">Longer</span>−<span class="c018">Formula</span> </td></tr>
</table></td></tr>
</table><table class="mprow"><tr class="c035"><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c018">And</span> </td></tr>
</table></td><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><span class="c018">The</span>−<span class="c018">Last</span>−<span class="c018">One</span>
</td></tr>
</table></td></tr>
</table></div>
</td></tr>
</table>
</div><p>
It is to be noticed that the L<sup>A</sup>T<sub>E</sub>X version of the package defines
<code>\hva</code> as a no-op, so as to allow explicit instructions given to
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A not to impact on the automatic typesetting performed by L<sup>A</sup>T<sub>E</sub>X.</p>
<!--TOC subsubsection id="sec203" The inferrule macro-->
<h4 class="subsubsection" id="sec203">B.17.15.2  The inferrule macro</h4><!--SEC END --><p><a id="hevea_default241"></a></p><p>The <code>\inferrule</code> macro is designed to typeset inference rules. It
should only be used in math mode (or display math mode). It takes
three arguments, the first being optional, specifying the label,
premises, and conclusions respectively. The premises and the
conclusions are both lists of formulas, and are separated by
<code>\\</code>.
A simple example of its use is
</p><pre class="verbatim">\inferrule
[label]
{one \\ two \\ three \\ or \\ more \\ premises}
{and \\ any \\ number \\ of \\ conclusions \\ as \\ well}
</pre><p>which gives the following rendering:
</p><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="c004 cellpadding0"><tr><td class="c030"><span class="c021">label</span></td></tr>
<tr class="c034"><td class="c042"><span class="c018">one</span>           <span class="c018">two</span>           <span class="c018">three</span>           <span class="c018">or</span>           <span class="c018">more</span>           <span class="c018">premises</span></td></tr>
<tr><td class="c000"></td></tr>
<tr class="c037"><td class="c042"><span class="c018">and</span>           <span class="c018">any</span>           <span class="c018">number</span>           <span class="c018">of</span>           <span class="c018">conclusions</span>           <span class="c018">as</span>           <span class="c018">well</span></td></tr>
</table></td></tr>
</table><p>
Again, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is simplistic. Where L<sup>A</sup>T<sub>E</sub>X performs
actual typesetting, interpreting <code>\\</code> as horizontal or
vertical breaks, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A always interpret <code>\\</code> as an
horizontal break. In fact H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A interpret all separators
(<code>\\</code>, <code>\and</code>) as horizontal breaks, when
they appear in the arguments of the <code>\inferrule</code> command.
Nevertheless prefixing separators with <code>\hva</code> yields vertical
breaks:
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c036"><div class="lstlisting">\inferrule
{aa \hva\\ bb}
{dd \\ ee \\ ff}</div></td><td class="c036">        </td><td class="c036"><table class="c004 cellpadding0"><tr class="c034"><td class="c042"><span class="c018">aa</span> </td></tr>
<tr><td class="c042"><span class="c018">bb</span></td></tr>
<tr><td class="c000"></td></tr>
<tr class="c037"><td class="c042"><span class="c018">dd</span>           <span class="c018">ee</span>           <span class="c018">ff</span></td></tr>
</table>
</td></tr>
</table>
</div><p>The color of the horizontal rule that separates the premises and
conclusions can be changed by redefining the command
<code>\mpr@hhline@color</code>. This color must be specified as a low-level
color (cf. Section <a href="#getcolor">B.14.2.2</a>).</p>
<!--TOC subsubsection id="sec204" Options-->
<h4 class="subsubsection" id="sec204">B.17.15.3  Options</h4><!--SEC END --><p>By default, lines are centered in inference rules. However, this can be changed either by using <code>\mprset{flushleft}</code> or <code>\mprset{center}</code>, as shown below.
</p><div class="center">
<table class="c002 cellpading0"><tr><td class="c036"><div class="lstlisting">$$\mprset{flushleft}
\inferrule
{a \\ bbb \hva\\ ccc \\ dddd}
{e \\ ff \hva\\ gg}
$$</div></td><td class="c036">        </td><td class="c036"><table class="display dcenter"><tr class="c035"><td class="dcell"> 
</td><td class="dcell"><table class="c004 cellpadding0"><tr class="c034"><td class="c043"><span class="c018">a</span>           <span class="c018">bbb</span>  </td></tr>
<tr><td class="c043"><span class="c018">ccc</span>           <span class="c018">dddd</span></td></tr>
<tr><td class="c000"></td></tr>
<tr class="c037"><td class="c043"><span class="c018">e</span>           <span class="c018">ff</span> </td></tr>
<tr><td class="c043"><span class="c018">gg</span></td></tr>
</table></td></tr>
</table>
</td></tr>
</table>
</div>
<!--TOC subsubsection id="sec205" Derivation trees-->
<h4 class="subsubsection" id="sec205">B.17.15.4  Derivation trees</h4><!--SEC END --><p><a id="hevea_default242"></a>
The <span class="c013">mathpartir</span> package provides a starred variant
<code>\inferrule*</code>. In L<sup>A</sup>T<sub>E</sub>X, the boxes
produced by <code>\inferrule</code> and <code>\inferrule*</code> differ as regards
their baseline, the second being well adapted to derivation trees.
All this is irrelevant to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A,
but <code>\inferrule*</code> remains of interest because of its interface:
the optional argument to the <code>\inferrule*</code> command is a list of
<span class="c018">key</span><span class="c013">=</span><span class="c018">value</span> pairs in the style of
<span class="c013">keyval</span>.
This makes the variant command much more flexible.
</p><table class="display dcenter"><tr class="c035"><td class="dcell">
</td><td class="dcell"><table class="c001 cellpadding1" border=1><tr><td class="c038"><span class="c014">key</span></td><td class="c040"><span class="c022">Effect for value <em>v</em></span>
</td></tr>
<tr><td class="c038"><span class="c013">before</span></td><td class="c040">Execute <em>v</em> before typesetting the rule.
Useful for instance to change the maximal width of the rule.
</td></tr>
<tr><td class="c038"><span class="c013">left</span></td><td class="c040">Put a label <em>v</em> on the left of the rule
</td></tr>
<tr><td class="c038"><span class="c013">Left</span></td><td class="c040">Idem.
</td></tr>
<tr><td class="c038"><span class="c013">right</span></td><td class="c040">As <code>left</code>, but on the right of the rule.
</td></tr>
<tr><td class="c038"><span class="c013">Right</span></td><td class="c040">As <code>Left</code>, but on the right of the rule.
</td></tr>
<tr><td class="c038"><span class="c013">lab</span></td><td class="c040">Put a label <em>v</em> above the inference rule, in the style
of <code>\inferrule</code>.
</td></tr>
<tr><td class="c038"><span class="c013">Lab</span></td><td class="c040">Idem.
</td></tr>
<tr><td class="c038"><span class="c013">vdots</span></td><td class="c040">Raise the rule by <em>v</em> and insert vertical dots, the length
argument is translated to a number of line-skips.
</td></tr>
</table></td></tr>
</table><p>
Additionally, the value-less key <code>center</code> centers premises and
conclusions (this is
the default), while <code>flushleft</code> commands left alignment of
premises and conclusions (as <code>\mprset{flushleft}</code> does).
Other keys defined by the L<sup>A</sup>T<sub>E</sub>X package exist and are parsed, but
they perform no operation.</p><p>As an example, the code
</p><div class="lstlisting">\begin{mathpar}
\inferrule* [Left=Foo]
{\inferrule* [Right=Bar,width=8em,
leftskip=2em,rightskip=2em,vdots=1.5em]
{a \and a \and bb \hva\\ cc \and dd}
{ee}
\and ff \and gg}
{hh}
\hva\and
\inferrule* [lab=XX]{uu \and vv}{ww}
\end{mathpar}</div><p>produces the following output:
</p><div class="mathpar">
<table class="mprow"><tr class="c035"><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="c004 cellpadding0"><tr class="c034"><td><span class="c021">Foo</span> </td><td class="c042"><table class="display"><tr class="c034"><td class="dcell"><table class="c004 cellpadding0"><tr class="c034"><td class="c042"><span class="c018">a</span>           <span class="c018">a</span>           <span class="c018">bb</span> </td><td> <span class="c021">Bar</span></td></tr>
<tr><td class="c042"><span class="c018">cc</span>           <span class="c018">dd</span></td><td> </td></tr>
<tr><td class="c000"></td><td></td></tr>
<tr class="c037"><td class="c042"><span class="c018">ee</span></td><td> </td></tr>
<tr class="c035"><td class="c027">⋮<br>
⋮</td><td></td></tr>
</table></td><td class="dcell">
          <span class="c018">ff</span>           <span class="c018">gg</span></td></tr>
</table></td></tr>
<tr><td></td><td class="c000"></td></tr>
<tr class="c037"><td> </td><td class="c042"><span class="c018">hh</span></td></tr>
</table></td></tr>
</table></td></tr>
</table><table class="mprow"><tr class="c035"><td class="mprcell c027"><table class="display dcenter"><tr class="c035"><td class="dcell"><table class="c004 cellpadding0"><tr><td class="c030"><span class="c021">XX</span></td></tr>
<tr class="c034"><td class="c042"><span class="c018">uu</span>           <span class="c018">vv</span></td></tr>
<tr><td class="c000"></td></tr>
<tr class="c037"><td class="c042"><span class="c018">ww</span></td></tr>
</table></td></tr>
</table></td></tr>
</table></div>
<!--TOC subsection id="sec206" The <span class="c013">ifpdf</span> package-->
<h3 class="subsection" id="sec206">B.17.16  The <span class="c013">ifpdf</span> package</h3><!--SEC END --><p>
<a id="hevea_default243"></a>
This package should be present in modern <span class="c013">latex</span> installations.
Basically, the package defines a boolean register <span class="c013">pdf</span>, whose
value is true for tools that produce <span class="c020">PDF</span> (such as
<span class="c013">pdflatex</span>) and false for tools that produce <span class="c020">DVI</span>
(such as <span class="c013">latex</span>).</p><p>The hevea version of the package simply defines the boolean
register <span class="c013">pdf</span> with initial value true. Command-line option
<a id="hevea_default244"></a><span class="c013">-pdf</span> is also added to <span class="c013">imagen</span> command-line
options (by using the command <code>\@addimagenopt</code>, see
Section <a href="#imagen-source">10.7</a>). As a result, <span class="c013">imagen</span> will
normally call <span class="c013">pdflatex</span> in place of <span class="c013">latex</span>.</p><p>In case standard <span class="c013">latex</span> processing in <span class="c013">imagen</span> is
wished, one can issue the command <code>\pdffalse</code> after loading the
ifpdf package and before <code>\begin{document}</code>. Then, no
command line option is added.
Hence, to achieve <span class="c013">latex</span> processing of the <span class="c018">image</span>
file, while still loading the <span class="c013">ifpdf</span> package, one writes:
</p><pre class="verbatim">\usepackage{ifpdf}
%HEVEA\pdffalse
</pre>
<!--TOC subsection id="sec207" Typesetting Thai-->
<h3 class="subsection" id="sec207">B.17.17  Typesetting Thai</h3><!--SEC END --><p>
<a id="hevea_default245"></a>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A features an implementation of Andrew Seagar’s technique
for Thai in L<sup>A</sup>T<sub>E</sub>X,
by the means of the package <span class="c013">thai.hva</span> in the distribution.</p><p>As regards input encoding, Thai users of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A could (perhaps) use
<code>\usepackage[utf8]{inputenc}</code>.
However, the typesetting of Thai is more subtle than just proper
characters. For that reason, Thai in L<sup>A</sup>T<sub>E</sub>X is better performed by
another technique, which H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A supports. See this specific
<a href="./thaihevea.html">document</a>.</p>
<!--TOC subsection id="sec208" Hanging paragraphs-->
<h3 class="subsection" id="sec208">B.17.18  Hanging paragraphs</h3><!--SEC END --><p>
<a id="hevea_default246"></a>The <span class="c013">hanging</span> package is implemented.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implementation consists of no-ops, except for the
<span class="c013">hangparas</span> environment, which is partially implemented.
Assume the following usage of <span class="c013">hangparas</span>:
</p><div class="flushleft">
<code>\begin{hangparas}{</code><span class="c018">wd</span><code>}{</code><span class="c018">n</span><code>}</code>
  …<code>\end{hangparas}</code>
</div><p>
where <span class="c018">wd</span> is a length that makes sense both for L<sup>A</sup>T<sub>E</sub>X
and CSS (typically <span class="c013">2ex</span>).
Then html output will reproduce L<sup>A</sup>T<sub>E</sub>X output for <span class="c018">n</span>=1, regardless
of the given value of argument <span class="c018">n</span>.
That is, in any paragraph inside the environment,
all lines except the first get indented by <span class="c018">wd</span>.</p>
<!--TOC subsection id="sec209" The <span class="c013">cleveref</span> package-->
<h3 class="subsection" id="sec209">B.17.19  The <span class="c013">cleveref</span> package</h3><!--SEC END --><p>
<a id="hevea_default247"></a>The <a href="http://www.ctan.org/pkg/cleveref.html"><span class="c013">cleveref</span></a> package
attempts (and mostly succeeds) typesetting references
cleverly. Its main feature is a <code>\cref</code> command that accepts several,
comma separated, label references and typesets them as a list
(which can be one-element long, of course) prefixed with sectional unit names.
The H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implementation is quite complete, but it does not support some
of the subtleties of the L<sup>A</sup>T<sub>E</sub>X implementations, especially as regards
customisation.</p>
<!--TOC subsection id="sec210" Other packages-->
<h3 class="subsection" id="sec210">B.17.20  Other packages</h3><!--SEC END --><p>
The <span class="c013">fancyverb</span> and <span class="c013">colortbl</span>
packages are partly implemented.</p><p>The <span class="c013">xspace</span> package is implemented,
in simple cases, rendering is satisfactory, but beware: H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
differs significantly from T<sub>E</sub>X, and discrepancies are likely.</p><p>The <span class="c013">chngcntr</span> package is implemented.
This package provides commands to connect (and disconnect) counters
once they are created (see
<a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=addtoreset"><span class="c013">http://www.tex.ac.uk/cgi-bin/texfaq2html?label=addtoreset</span></a>).</p><p>The <span class="c013">import</span> package is partially implemented:
all starred commands are missing.</p><p>The <span class="c013">booktabs</span> package is implemented.
This package provides nicer rulers in tables as specific commands.
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A defines those as no-ops.</p><!--CUT END -->
<!--TOC part id="practical" Practical information-->
<table class="center"><tr><td><h1 class="part" id="practical">Part C<br>
Practical information</h1></td></tr>
</table><!--SEC END --><!--CUT DEF section -->
<!--TOC section id="sec212" Usage-->
<h2 class="section" id="sec212">C.1  Usage</h2><!--SEC END -->
<!--TOC subsection id="sec213" H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A usage-->
<h3 class="subsection" id="sec213">C.1.1  H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A usage</h3><!--SEC END --><p><a id="heveausage"></a>
<a id="hevea_default248"></a>
The <span class="c013">hevea</span> command has two operating modes, normal mode and
filter mode.
Operating mode is determined by the nature of the last command-line
argument.</p>
<!--TOC subsubsection id="sec214" Command line arguments-->
<h4 class="subsubsection" id="sec214">C.1.1.1  Command line arguments</h4><!--SEC END --><p><a id="comline"></a>
The <span class="c013">hevea</span> command interprets its arguments as names of
files and attempts to process them.
Given an argument <span class="c018">filename</span> there are two cases:
</p><ul class="itemize"><li class="li-itemize">
If <span class="c018">filename</span> is <span class="c018">base</span><span class="c013">.tex</span> or
<span class="c018">base</span><span class="c013">.hva</span>,
then a single attempt to open <span class="c018">filename</span> is made.
</li><li class="li-itemize">In other cases,
a first attempt to open <span class="c018">filename</span><span class="c013">.tex</span> is made.
In case of failure, a second attempt to open <span class="c018">filename</span> is made.
</li></ul><p>
<a id="search:path"></a>
In all attempts, implicit filenames are
searched along <span class="c013">hevea</span> search path, which consist in:
</p><ol class="enumerate" type=1><li class="li-enumerate">
the current directory “<span class="c013">.</span>”,
</li><li class="li-enumerate">user-specified directories (with the <span class="c013">-I</span> command-line
option),
</li><li class="li-enumerate"><span class="c013">hevea</span> library directory.
</li><li class="li-enumerate">one of the sub-directories <span class="c013">html</span>, <span class="c013">text</span> or
<span class="c013">info</span> from <span class="c013">hevea</span> library directory, depending upon
<span class="c013">hevea</span> output format,
</li></ol><p>
<a id="hevea_default249"></a>
The <span class="c013">hevea</span> library directory is fixed at compile-time
(this is where <span class="c013">hevea</span> library files are installed)
and typically is <span class="c013">/usr/local/lib/hevea</span>.
However, this compile-time value can be overridden
by setting the <span class="c013">HEVEADIR</span> shell environment variable.
In all cases, the value of <span class="c013">hevea</span> library directory can
be accessed from the processed document as the value of the command
<code>\@hevealibdir</code>.</p>
<!--TOC subsubsection id="sec215" Normal mode-->
<h4 class="subsubsection" id="sec215">C.1.1.2  Normal mode</h4><!--SEC END --><p><a id="basenames"></a>
If the last argument has an extension that is different from
<span class="c013">.hva</span> or has no extension,
then it is interpreted as the name of the <em>main input file</em>.
The main input file is the document to be translated and normally
contains the <code>\documentclass</code> command.
In that case two <em>basenames</em> are defined:
</p><ul class="itemize"><li class="li-itemize">
The input basename, <span class="c018">basein</span>,
is defined as the main input file name,
with extension removed when present.
</li><li class="li-itemize">The output basename, <span class="c018">baseout</span>, is <span class="c018">basein</span>
with leading directories omitted. However the output basename can be
changed, using the <code>-o</code> option (see <a href="#output%3Abase">below</a>).
</li></ul><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A will attempt to load the main input file.
Ancillary files from a previous run of L<sup>A</sup>T<sub>E</sub>X
(<em>i.e.</em> <span class="c013">.aux</span>, <span class="c013">.bll</span> and <span class="c013">.idx</span> files)
will be searched as <span class="c018">basein</span><code>.</code><span class="c018">ext</span>.
The output base name governs all files produced by H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
That is, html output of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A normally goes to the file
<span class="c018">baseout</span><span class="c013">.html</span>,
while cross-referencing information goes into
<span class="c018">baseout</span><span class="c013">.haux</span>. Furthemore,
if an <span class="c018">image</span> file is generated (cf. section <a href="#imagen">6</a>), its
name will be <span class="c018">baseout</span><span class="c013">.image.tex</span>.</p><p>Thus, in the simple case where the <span class="c013">hevea</span> command is invoked
as:
</p><pre class="verbatim"># hevea file.tex
</pre><p>The input basename is <span class="c013">file</span> and the output basename also is
<span class="c013">file</span>. The main input file is searched once along <span class="c013">hevea</span>
search path as <span class="c013">file.tex</span>.
html output goes into file
<span class="c013">file.html</span>, in the current directory.
In the more complicated case where the <span class="c013">hevea</span> command is invoked
as:
</p><pre class="verbatim"># hevea ./dir/file
</pre><p>The input base name is <span class="c013">./dir/file</span> and the output basename is
<span class="c013">file</span>. The main input file is loaded by first attempting to
open file <span class="c013">./dir/file.tex</span>, then file <span class="c013">./dir/file</span>.
html output goes into file <span class="c013">file.html</span>, in the current directory.</p><p><a id="output:base">Finally</a>, the output base name can be a full path,
but you have to use option <a id="hevea_default250"></a><span class="c013">-o</span>.
For instance, we consider:
</p><pre class="verbatim"># hevea -o out/out.html file.tex
</pre><p>Then, html output goes into <span class="c013">out/out.html</span> — notice
that directory <span class="c013">out</span> must exist.
Furthermore, <span class="c013">hevea</span> output base name is <span class="c013">out/out</span>.
This means that <span class="c013">hevea</span> generates files
<span class="c013">out/out.haux</span>, <span class="c013">out/out.image.tex</span> etc.</p><p>The <span class="c013">article.hva</span>, <span class="c013">seminar.hva</span>, <span class="c013">book.hva</span> and
<span class="c013">report.hva</span>
base style files from H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A library are special.
Only the first base style file is loaded and the
<code>\documentclass</code> command has no effect when a base style file is
already loaded. This feature allows to override the document base style.
Thus, a document <span class="c013">file.tex</span> can be translated using the
<span class="c018">article</span> base style as follows:
</p><pre class="verbatim"># hevea article.hva file.tex
</pre>
<!--TOC subsubsection id="sec216" Filter mode-->
<h4 class="subsubsection" id="sec216">C.1.1.3  Filter mode</h4><!--SEC END --><p>
If there is no command-line argument, or if the last command-line
argument has the extension <span class="c013">.hva</span>, then
there is neither input base name nor output base name,
the standard input is read and
output normally goes to the standard output.
Output starts immediately, whithout waiting for <code>\begin{document}</code>.
In other words <span class="c013">hevea</span> acts as a filter.</p><p>Please note that this operating mode is just for translating
isolated L<sup>A</sup>T<sub>E</sub>X constructs.
The normal way to translate a full document <span class="c018">file</span><code>.tex</code> being
“<code>hevea</code> <span class="c018">file</span><code>.tex</code>” and not
“<code>hevea < </code> <span class="c018">file</span><code>.tex > </code><span class="c018">file</span><code>.html</code>”.</p>
<!--TOC subsubsection id="heveaoptions" Options-->
<h4 class="subsubsection" id="heveaoptions">C.1.1.4  Options</h4><!--SEC END --><p>
The <span class="c013">hevea</span> command recognises the following options:
</p><dl class="description"><dt class="dt-description">
<span class="c014">-version</span></dt><dd class="dd-description"> Show <span class="c013">hevea</span> version and exit.
</dd><dt class="dt-description"><span class="c014">-v</span></dt><dd class="dd-description"> Verbose flag, can be repeated to increase
verbosity. However, this is mostly for debug.
</dd><dt class="dt-description"><span class="c014">-dv</span></dt><dd class="dd-description"> Add border around some of the block-level
elements issued. Specifically, all <code>div</code> and <code>p</code> are bordered,
while the structure of displayed material is also shown.
</dd><dt class="dt-description"><span class="c014">-s</span></dt><dd class="dd-description"> Suppress warnings.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-I</span> <span class="c018">dirname</span></span></dt><dd class="dd-description"> Add <span class="c018">dirname</span> to the search path.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-o</span> <span class="c018">name</span></span></dt><dd class="dd-description"> Make <span class="c018">name</span> the output basename.
However, if <span class="c018">name</span> is <span class="c018">base</span><span class="c013">.html</span>, then
the output basename is <span class="c018">base</span>.
Besides, <span class="c013">-o -</span> makes H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output to standard output.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-e</span> <span class="c018">filename</span></span></dt><dd class="dd-description"> Prevent <span class="c013">hevea</span> from loading any file
whose name is <span class="c018">filename</span>. Note that this option applies to all
files, including <span class="c013">hevea.hva</span> and base style files.
</dd><dt class="dt-description"><span class="c014">-fix</span></dt><dd class="dd-description"> Iterate H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A until a fixpoint is found.
Additionally, images get generated automatically.
</dd><dt class="dt-description"><span class="c014">-O</span></dt><dd class="dd-description"> Optimise html by calling <span class="c013">esponja</span> (see
section <a href="#esponjausage">C.1.3</a>).
</dd><dt class="dt-description"><span class="c022"><span class="c013">-exec</span> <span class="c018">prog</span></span></dt><dd class="dd-description"> Execute file <span class="c018">prog</span> and read the
output. The file <span class="c018">prog</span> must have execution permission and is
searched by following the searching rules of <span class="c013">hevea</span>.
</dd><dt class="dt-description"><span class="c014">-francais</span></dt><dd class="dd-description"> Deprecated by <span class="c013">babel</span> support. This
option issues a warning message.
</dd><dt class="dt-description"><span class="c014">-help</span></dt><dd class="dd-description"> Print version number and a short help message.
</dd></dl><p>The following options control the html code produced by
<span class="c013">hevea</span>. By default, <span class="c013">hevea</span> outputs a page encoded in
US-ASCII with most symbols rendered as html or numerical Unicode
entities.
</p><dl class="description"><dt class="dt-description">
<span class="c014">-entities</span></dt><dd class="dd-description"> Render symbols by using entities. This is the default.
</dd><dt class="dt-description"><span class="c014">-textsymbols</span></dt><dd class="dd-description"> Render symbols by English text.
</dd><dt class="dt-description"><span class="c014">-moreenties</span></dt><dd class="dd-description"> Enable the output of some infrequent entities. Use
this option to target browsers with wide entities support.
</dd><dt class="dt-description"><span class="c014">-mathml</span></dt><dd class="dd-description"> Produces MathML output for equations, very
experimental.
</dd><dt class="dt-description"><span class="c014">-pedantic</span></dt><dd class="dd-description"> Be strict in interpreting html
definition. In particular, this option disable size and color changes inside
<code><PRE></code>… <code></PRE></code>, which are otherwise performed.
</dd></dl><p>The following options select and control alternative output formats
(see section <a href="#alternative">11</a>):
</p><dl class="description"><dt class="dt-description">
<span class="c014">-text</span></dt><dd class="dd-description"> Output plain text. Output file
extension is <span class="c013">.txt</span>.
</dd><dt class="dt-description"><span class="c014">-info</span></dt><dd class="dd-description"> Output info format. Output file extension
is <span class="c013">.info</span>.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-w</span> <span class="c018">width</span></span></dt><dd class="dd-description"> Set the line width for text or info
output, defaults to 72.
</dd></dl><p>Part <a href="#usermanual">A</a> of this document is
a tutorial introduction to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A,
while Part <a href="#referencemanual">B</a> is the reference manual of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.</p>
<!--TOC subsection id="sec218" H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A usage-->
<h3 class="subsection" id="sec218">C.1.2  H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A usage</h3><!--SEC END --><p>
<a id="hevea_default251"></a>
The <span class="c013">hacha</span> command interprets its argument
<span class="c018">base</span><span class="c013">.html</span> as the name of
a html source file to cut into pieces.</p><p>It also recognises the following options:
</p><dl class="description"><dt class="dt-description">
<span class="c014">-v</span></dt><dd class="dd-description"> Be a little verbose.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-o</span> <span class="c018">filename</span></span></dt><dd class="dd-description"> Make H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A output go into file
<span class="c018">filename</span> (defaults to index.html).
Additionally, if <span class="c018">filename</span> is a composite filename,
<span class="c018">dir/base</span>, then all files outputted by H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A will
reside in directory <span class="c018">dir</span>.
</dd><dt class="dt-description"><span class="c014">-tocbis</span></dt><dd class="dd-description">
Another style for table of contents:
sub-tables are replicated at the beginning of
every file.
</dd><dt class="dt-description"><span class="c014">-tocter</span></dt><dd class="dd-description">
Like <span class="c013">-tocbis</span> above, except that
sub-tables do not appear in the main table of contents
(see Section <a href="#table%3Alink%3Astyle">7.2.3</a>).
</dd><dt class="dt-description"><span class="c014">-nolinks</span></dt><dd class="dd-description"> Do not insert Previous/Up/Next links in
generated pages.
</dd><dt class="dt-description"><span class="c014">-hrf</span></dt><dd class="dd-description"> Output a <span class="c018">base</span><span class="c013">.hrf</span> file, showing
in which output files are the anchors from the input file gone.
The format of this summary is one
“<span class="c018">anchor</span><code>\t</code><span class="c018">file</span>” line per anchor.
This information may be needed by other tools.
</dd><dt class="dt-description"><span class="c014">-help</span></dt><dd class="dd-description"> Print version number and a short help message.
</dd></dl><p>Section <a href="#hacha">7</a> of the user manual explains how to
alter H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A default behaviour.</p>
<!--TOC subsection id="sec219" <span class="c013">esponja</span> usage-->
<h3 class="subsection" id="sec219">C.1.3  <span class="c013">esponja</span> usage</h3><!--SEC END --><p><a id="esponjausage"></a>
<a id="hevea_default252"></a>
The program <span class="c013">esponja</span>
is part of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A and is designed to optimise <span class="c013">hevea</span>
output.
However, <span class="c013">esponja</span> can also be used alone to optimise
text-level elements in html files.
Since <span class="c013">esponja</span> fails
to operate when it detects incorrect html, it can be used as a
partial html validator.</p>
<!--TOC subsubsection id="sec220" Operating mode-->
<h4 class="subsubsection" id="sec220">C.1.3.1  Operating mode</h4><!--SEC END --><p>
The program <span class="c013">esponja</span> interprets its arguments as names of
files and attempt to process them.
It is important to notice that <span class="c013">esponja</span> will <em>replace</em> files
by their optimised versions, unless instructed not to do so with
option <span class="c013">-n</span>.</p><p>Invoking <span class="c013">esponja</span> as
</p><pre class="verbatim"># esponja foo.html
</pre><p>will alter <span class="c013">foo.html</span>.
Of course, if <span class="c013">esponja</span> does not succeed in making <span class="c013">foo.html</span> any
smaller or if <span class="c013">esponja</span> fails, the original <span class="c013">foo.html</span>
is left unchanged.
Note that this feature allows to optimise all html files in a given directory
by:
</p><pre class="verbatim"># esponja *.html
</pre>
<!--TOC subsubsection id="sec221" Options-->
<h4 class="subsubsection" id="sec221">C.1.3.2  Options</h4><!--SEC END --><p><a id="esponjaoptions"></a>
The command <span class="c013">esponja</span> recognises the following options:
</p><dl class="description"><dt class="dt-description">
<span class="c014">-v</span></dt><dd class="dd-description">Be verbose, can be repeated to increase verbosity.
</dd><dt class="dt-description"><span class="c014">-n</span></dt><dd class="dd-description">Do not alter input files. Instead, <span class="c013">esponja</span>
output for file <span class="c018">input</span><span class="c013">.html</span> goes to file
<span class="c018">input</span><span class="c013">.esp</span>. Option <span class="c013">-n</span> implies option <span class="c013">-v</span>.
</dd><dt class="dt-description"><span class="c014">-u</span></dt><dd class="dd-description">Output <span class="c013">esponja</span> intermediate version of html.
In most occasions, this amounts to pessimize instead of to optimise.
It may yield challenging input for other html optimisers.
</dd></dl>
<!--TOC subsection id="bibhva" <span class="c013">bibhva</span> usage-->
<h3 class="subsection" id="bibhva">C.1.4  <span class="c013">bibhva</span> usage</h3><!--SEC END --><p>
The program <span class="c013">bibhva</span>
is a simple wrapper, which basically
forces <span class="c013">bibtex</span> into accepting a <span class="c013">.haux</span> file as input
and producing a <span class="c013">.hbbl</span> file as output.
Usage is
<span class="c013">bibhva </span><span class="c018">bibtex-options<span class="c013"> </span>basename</span>.</p>
<!--TOC subsection id="sec223" <span class="c013">imagen</span> usage-->
<h3 class="subsection" id="sec223">C.1.5  <span class="c013">imagen</span> usage</h3><!--SEC END --><p><a id="imagenusage"></a>
<a id="hevea_default253"></a>
The command <span class="c013">imagen</span> is a simple shell script that translates
a L<sup>A</sup>T<sub>E</sub>X document into many <span class="c013">.png</span> images.
The <span class="c013">imagen</span> script relies on much software to be installed on
your computer, see Section <a href="#imagen%3Aneeds">C.4.1</a>.</p><p>It is a companion program of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, which must have been previously run as:
</p><div class="flushleft">
<span class="c013"># hevea</span>… <span class="c018">base</span><span class="c013">.tex</span><br>
or<br>
<span class="c013"># hevea</span>… <span class="c013">-o</span> <span class="c018">base</span><span class="c013">.html</span>…<br>
</div><p>
In both cases, <span class="c018">base</span> is H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A output basename.
When told to do so (see section <a href="#imagen">6</a>)
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A echoes part of its input into
the <span class="c018">base</span><span class="c013">.image.tex</span> file.</p><p>The <span class="c013">imagen</span> script should then be run as:
</p><div class="flushleft">
<span class="c013"># imagen</span> <span class="c018">base</span>
</div><p>
The <span class="c013">imagen</span> script produces
one <span class="c018">base</span><span class="c019">nnn</span><span class="c013">.png</span> image file per page in the
<span class="c018">base</span><span class="c013">.image.tex</span> file.</p><p>This is done by first calling <span class="c013">latex</span> on
<span class="c018">base</span><span class="c013">.image.tex</span>, yielding one <span class="c013">dvi</span>
file.
Then, <span class="c013">dvips</span> translates this file into one single Postscript file that
contains all
the images, or into one Postscript file per image,
depending upon your version of <span class="c013">dvips</span>.
Postscript files are interpreted by ghostscript (<span class="c013">gs</span>) that
outputs <span class="c013">ppm</span> images, which are then fed into a series of
transformations that change them into <span class="c013">.png</span> files.</p><p>The <span class="c013">imagen</span> script recognises the following options:
</p><dl class="description"><dt class="dt-description">
<span class="c022"><span class="c013">-mag</span> <span class="c019">nnnn</span></span></dt><dd class="dd-description"> Change the enlarging ratio that is applied
while translating DVI into Postscript.
More precisely, <span class="c013">dvips</span> is run with <span class="c013">-x</span><span class="c019">nnnn</span>
option.
Default value for this ration is 1414, this means
that, by default, <span class="c013">imagen</span> magnifies L<sup>A</sup>T<sub>E</sub>X output by a factor of
1.414.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-extra</span> <span class="c018">command</span></span></dt><dd class="dd-description"> Insert <span class="c018">command</span> as an additional
stage in <span class="c013">imagen</span> <span class="c013">ppm</span> to <span class="c013">png</span> production chain.
<span class="c018">command</span> is an Unix filter that expects a <span class="c013">ppm</span> image
in its standard input and outputs a <span class="c013">ppm</span> image on its standard output.
A sensible choice for <span class="c018">command</span> is one command from the
<span class="c013">netpbm</span> package, several such commands piped together, or
various invocations of the <span class="c013">convert</span> command from <span class="c022">ImageMagick</span>.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-quant</span> <span class="c018">number</span></span></dt><dd class="dd-description"> Add an extra color quantisation step
in <span class="c013">imagen</span> <span class="c013">ppm</span> image production chain, where
<span class="c018">number</span> is the maximal number of colors in the produced
images. This option may be needed as a response to a failure in the
image production chain. It can also help in limiting image files size.
</dd><dt class="dt-description"><span class="c014">-png</span></dt><dd class="dd-description"><a id="hevea_default254"></a> Output PNG images. This is the default.
</dd><dt class="dt-description"><span class="c014">-gif</span></dt><dd class="dd-description"><a id="hevea_default255"></a>
Output GIF images in place of PNG images.
GIF image files have a <span class="c013">.gif</span> extension.
Note that <span class="c013">hevea</span> should have been previously run as
<span class="c013">hevea gif.hva</span> <span class="c018">base</span><span class="c013">.tex</span> (so that the proper
<span class="c013">.gif</span> filename
extension is given to image file references from within the html
document).
</dd><dt class="dt-description"><span class="c014">-pnm</span></dt><dd class="dd-description"> Output PPM images. This option mostly serves
debugging purposes. Experimented users can also take advantage
of it for performing additional image transformation or
adopting exotic image formats.
</dd><dt class="dt-description"><span class="c022"><span class="c013">-t</span> <span class="c018">arg</span></span></dt><dd class="dd-description"> Pass option “<span class="c013">-t</span> <span class="c018">arg</span>” to
<span class="c013">dvips</span>.
For instance, using “<span class="c013">-t a3</span>” may help when images are
truncated on the right.
</dd><dt class="dt-description"><span class="c014">-pdf</span></dt><dd class="dd-description"><a id="hevea_default256"></a><a id="hevea_default257"></a>
Have <span class="c013">imagen</span> call <span class="c013">pdflatex</span> instead
of <span class="c013">latex</span>.
</dd></dl><p>The first three options enable users to correct some misbehaviours.
For instance, when the document base style is <span class="c018">seminar</span>, image
orientation may
be wrong and the images are too small. This can be cured by invoking
<span class="c013">imagen</span> as:
</p><div class="flushleft">
<span class="c013"># imagen -extra "pnmflip -ccw" -mag 2000</span> <span class="c018">base</span>
</div><p>Notice that <span class="c013">hevea</span> calls <span class="c013">imagen</span> by itself,
when given the command-line option <a id="hevea_default258"></a><span class="c013">-fix</span>.
In that situation, the command-line options of <span class="c013">imagen</span> can
be controlled from source file by using the
command <code>\@addimagenopt</code> (see Section <a href="#imagen-source">10.7</a>).</p>
<!--TOC subsection id="sec224" Invoking <span class="c013">hevea</span>, <span class="c013">hacha</span> and <span class="c013">imagen</span>-->
<h3 class="subsection" id="sec224">C.1.6  Invoking <span class="c013">hevea</span>, <span class="c013">hacha</span> and <span class="c013">imagen</span></h3><!--SEC END --><p>
In this section, we give a few sequence of (Unix) commands to build
the html version of a document in various
situations. The next section gives a few
<span class="c013">Makefile</span>’s for similar situations.</p><p>We translate a file <span class="c013">doc.tex</span>
that requires a specific style file <span class="c013">doc.hva</span>.
The file is first translated into <span class="c013">doc.html</span> by <span class="c013">hevea</span>,
which also reads
the specific style file <span class="c013">doc.hva</span>.
Then, <span class="c013">hacha</span> cuts <span class="c013">doc.html</span> into several,
<span class="c013">doc001.html</span>, <span class="c013">doc002.html</span>, etc. also producing the
table of links file <span class="c013">index.html</span>.
</p><pre class="verbatim"># hevea -fix doc.hva doc.tex
# hacha doc.html
</pre><p>Thanks to the command-line option <a id="hevea_default259"></a><span class="c013">-fix</span>, <span class="c013">hevea</span> runs the
appropriate number of times automatically.
In case <span class="c013">hevea</span> produces a non-empty <span class="c013">doc.image.tex</span>
file, then <span class="c013">hevea</span> calls <span class="c013">imagen</span> by itself
(because of option <span class="c013">-fix</span>).
Hence, the above sequence of two commands is also appropriate in
that situation.</p><p>In case some problem occurs, it is sometime convenient to
run <span class="c013">imagen</span> by hand.
It is time <em>not</em> to use the option <span class="c013">-fix</span>.
</p><pre class="verbatim"># rm -f doc.image.tex
# hevea doc.hva doc.tex
</pre><p>Now, <span class="c013">hevea</span> normally has shown the <span class="c013">imagen</span>
command line that it would have run, if it had been given
the option <span class="c013">-fix</span>.
For instance, if <span class="c013">doc.hva</span> includes <code>\input{gif.hva}</code>, then
<span class="c013">hevea</span> shows the following warning:
</p><pre class="verbatim">HeVeA Warning: images may have changed, run 'imagen -gif doc'
</pre><p>Now, one can run <span class="c013">imagen</span> as it should be.</p><p>It is sometime convenient not to clobber the source directory with
numerous target files.
It suffices to instruct
<span class="c013">hevea</span> and <span class="c013">hacha</span> to output files in a
specific directory, say <span class="c013">doc</span>.
</p><pre class="verbatim"># hevea -fix -o doc/doc.html doc.hva doc.tex
# hacha -o doc/index.html doc/doc.html
</pre><p>Notice that <span class="c013">hevea</span> does not create the target directory
<span class="c013">doc</span>: it must exist before <span class="c013">hevea</span> runs.
Again, in case <span class="c013">hevea</span> calls <span class="c013">imagen</span>,
image generation should proceed smoothly and the final files
<span class="c013">doc001.png</span>, <span class="c013">doc002.png</span>, … should go into
directory <span class="c013">doc</span>.</p><p>In all situations, while installing files to their final destination,
it is important not to forget any relevant files.
In particular, in addition to the root file
(<span class="c013">index.html</span>), contents files (<span class="c013">doc001.html</span>,
<span class="c013">doc002.html</span>, etc.) and images
(<span class="c013">doc001.png</span>, <span class="c013">doc002.png</span>, etc.),
one should not forget the arrow images and the
style sheet generated by <span class="c013">hacha</span>
(<span class="c013">contents_motif.gif</span>, <span class="c013">next_motif.gif</span>,
<span class="c013">previous_motif.gif</span> and <span class="c013">doc.css</span>).</p><p>As a consequence, producing all files into the subdirectory
<span class="c013">doc</span> may be a good idea, since then one easily install all
relevant files by copying <span class="c013">doc</span> to a public destination.
</p><pre class="verbatim"># cp -r doc $(HOME)/public_html
</pre><p>However, one then also installs the auxiliary files of <span class="c013">hevea</span>,
and <span class="c013">hevea</span> output file <span class="c013">doc.html</span>, which is no longer
useful once <span class="c013">hacha</span> has run.
Hence, those should be erased beforehand.
</p><pre class="verbatim"># rm -f doc/doc.h{tml,aux,ind,toc} doc/doc.image.tex
# cp -r doc $(HOME)/public_html
</pre>
<!--TOC subsection id="makefile" Using <span class="c013">make</span>-->
<h3 class="subsection" id="makefile">C.1.7  Using <span class="c013">make</span></h3><!--SEC END --><p>Here is a typical <span class="c013">Makefile</span>, which is appropriate when
no images are produced.
</p><pre class="verbatim">HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
index.html: $(DOC).html
$(HACHA) -o index.html $(DOC).html
$(DOC).html: $(DOC).hva $(DOC).tex
$(HEVEA) $(HEVEAOPTS) $(DOC).hva $(DOC).tex
clean:
rm -f $(DOC).html $(DOC).h{toc,aux,ind}
rm -f index.html $(DOC)[0-9][0-9][0-9].html $(DOC).css
</pre><p>Note that the <span class="c013">clean</span> rule removes all the <span class="c013">doc001.html</span>,
<span class="c013">doc002.html</span>, etc. and <span class="c013">doc.css</span> files produced by
<span class="c013">hacha</span>.
Also note that <span class="c013">make clean</span> also removes the
<span class="c013">doc.haux</span>, <span class="c013">doc.hind</span> and <span class="c013">doc.htoc</span> files, which are H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
auxiliary files.</p><p>When the <span class="c018">image</span> file feature is used, one can use the
following, extended, <span class="c013">Makefile</span>:
</p><pre class="verbatim">HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
index.html: $(DOC).html
$(HACHA) -o index.html $(DOC).html
$(DOC).html: $(DOC).hva $(DOC).tex
$(HEVEA) $(HEVEAOPTS) $(DOC).hva $(DOC).tex
clean:
rm -f $(DOC).html $(DOC).h{toc,aux,ind}
rm -f index.html $(DOC)[0-9][0-9][0-9].html $(DOC).css
rm -f $(DOC).image.* $(DOC)[0-9][0-9][0-9].png *_motif.gif
</pre><p>Observe that the <span class="c013">clean</span> rule now also gets rid of
<span class="c013">doc.image.tex</span> and of the various files produced by
<span class="c013">imagen</span>.</p><p>With the following <span class="c013">Makefile</span>,
<span class="c013">hevea</span>, <span class="c013">imagen</span>, <span class="c013">hacha</span> all output their files into
a specific directory <span class="c013">DIR</span>.
</p><pre class="verbatim">HEVEA=hevea
HEVEAOPTS=-fix
HACHA=hacha
#document base name
DOC=doc
DIR=$(HOME)/public_html/$(DOC)
BASE=$(DIR)/$(DOC)
$(DIR)/index.html: $(BASE).html
$(HACHA) -tocter -o $(DIR)/index.html $(BASE).html
$(BASE).html: $(DOC).hva $(DOC).tex
$(HEVEA) $(HEVEAOPTS) $(DOC).hva -o $(BASE).html $(DOC).tex
partialclean:
rm -f $(BASE).h{tml,aux,toc,ind} $(BASE).image.*
clean:
rm -f $(DIR)/*
</pre><p>The above <span class="c013">Makefile</span> directly produces html and PNG files
into the final directory <code>$(HOME)/public_html/$(DOC)</code>.
The new <span class="c013">partialclean</span> entry erases files that are not
useful anymore, once <span class="c013">imagen</span> and <span class="c013">hacha</span> have
performed their tasks.</p><p>However, most often, it is more appropriate to build html and PNG files
in a specific directory, and then to copy them to their final
destination.
</p><pre class="verbatim"> ...
#document base name
DOC=doc
DIR=$(DOC)
BASE=$(DIR)/$(DOC)
INSTALLDIR=$(HOME)/public_html/$(DOC)
...
install: partialclean
cp $(DIR)/* $(INSTALLDIR)
...
</pre>
<!--TOC section id="browser" Browser configuration-->
<h2 class="section" id="browser">C.2  Browser configuration</h2><!--SEC END --><!--NAME browser.html-->
<p>
<a id="hevea_default260"></a><a id="hevea_default261"></a>By default, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A does not anymore use the <code>FACE=symbol</code>
attribute to the <code><FONT ...></code> tag. As a consequence, browser
configuration is no longer needed.</p><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A now extensively outputs Unicode entities.
This first means that H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A targets modern browsers with
decent unicode support, and only those.</p><p>In case your browser is recent and that you nevertheless experience display
problems on H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A-generated pages, see the excellent
<a href="http://www.alanwood.net/unicode/">Alan Wood’s Unicode Resources</a>.
It may help to understand display problems and even to solve them
by configuring browsers or installing some fonts.</p>
<!--TOC section id="sec227" Availability-->
<h2 class="section" id="sec227">C.3  Availability</h2><!--SEC END -->
<!--TOC subsection id="sec228" Internet stuff-->
<h3 class="subsection" id="sec228">C.3.1  Internet stuff</h3><!--SEC END --><p>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A home page is <a href="http://hevea.inria.fr/"><span class="c013">http://hevea.inria.fr/</span></a>. It contains links to the
<a href="http://hevea.inria.fr//doc/">on-line manual</a>
and to the <a href="http://hevea.inria.fr/distri">distribution</a>.</p><p>The author can be contacted at <a href="mailto:Luc.Maranget@inria.fr">Luc.Maranget@inria.fr</a>.</p>
<!--TOC subsection id="sec229" Law-->
<h3 class="subsection" id="sec229">C.3.2  Law</h3><!--SEC END --><p>
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A can be freely used and redistributed without modifications.
Modifying and redistributing H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implies a few constraints.
More precisely, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A is distributed under the terms of the
Q Public License, but H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A binaries include the Objective Caml
runtime system, which is distributed under the Gnu Library General
Public License (LGPL).
See the <a href="http://hevea.inria.fr/distri/LICENSE">LICENSE</a> file for details.</p><p>The manual itself is distributed under the terms of
the
<a href="fddl.html">Free Document Dissemination Licence</a>.
</p>
<!--TOC section id="sec230" Installation-->
<h2 class="section" id="sec230">C.4  Installation</h2><!--SEC END -->
<!--TOC subsection id="sec231" Requirements-->
<h3 class="subsection" id="sec231">C.4.1  Requirements</h3><!--SEC END --><p><a id="requirements"></a>
The programs <span class="c013">hevea</span> and <span class="c013">hacha</span> are written in
<a href="http://caml.inria.fr/ocaml/">Objective Caml</a>. Thus, you
really need Objective Caml (the more recent version, the better) to
compile them.
However, some binary distributions exist, which are managed by
people other than me (thanks to them).
Links to some of these distributions appear in <a href="http://hevea.inria.fr/">H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A home page</a>.</p><p><a id="imagen:needs"></a>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A users may instruct the program not to process a
part of the input (see section <a href="#imagen">6</a>). Instead, this part is
processed into a bitmap file and H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A outputs a link to the image file.
L<sup>A</sup>T<sub>E</sub>X source is changed into <code>.png</code> images by the <code>imagen</code>
script, which basically calls, L<sup>A</sup>T<sub>E</sub>X, <span class="c013">dvips</span>,
<a href="http://www.cs.wisc.edu/~ghost/index.html"><span class="c013">ghostscript</span></a>
and the <span class="c013">convert</span> command from the image processing package
<a href="http://www.imagemagick.org/"><span class="c022">ImageMagick</span></a>.</p><p>To benefit from the full functionality of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A, you need all
this software. However, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A runs without them, but then you will
have to produce images by yourself.</p>
<!--TOC subsection id="sec232" Principles-->
<h3 class="subsection" id="sec232">C.4.2  Principles</h3><!--SEC END --><p>
The details are given in the <a href="http://hevea.inria.fr/distri/README"><span class="c013">README</span></a>
file from the distribution.
Basically, H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A should be given a library
directory. The installation procedure stores the <span class="c013">hevea.hva</span>
and base style files in this directory.
There are two compilation modes, the <span class="c013">opt</span> mode selects the
native code OCaml compiler <span class="c013">ocamlopt</span>, while the <span class="c013">byte</span>
mode selects the bytecode OCaml compiler <span class="c013">ocamlc</span>.
In H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A case, <span class="c013">ocamlopt</span> produces code that is up to three
times as fast as the one produced by <span class="c013">ocamlc</span>.
Thus, default compilation mode is <span class="c013">opt</span>, however it may be the
case on some systems that only <span class="c013">ocamlc</span> is available.</p><p>Note that, when installing H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A from the source distribution, the
<span class="c013">hevea.sty</span> file is simply copied to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
library directory. It remains users responsibility to
make it accessible to L<sup>A</sup>T<sub>E</sub>X.</p>
<!--TOC section id="sec233" Other L<sup>A</sup>T<sub>E</sub>X to html translators-->
<h2 class="section" id="sec233">C.5  Other L<sup>A</sup>T<sub>E</sub>X to html translators</h2><!--SEC END --><p>
This short section gives pointers to a few other translators. I
performed not extensive testing and make no thorough comparison.
</p><dl class="description"><dt class="dt-description">
<span class="c022">LaTeX2html</span></dt><dd class="dd-description">
LaTeX2html is a full system. It is written in perl and
calls L<sup>A</sup>T<sub>E</sub>X when in trouble.
As a consequence, LaTeX2html is powerful but it may fail on
large documents, for speed and memory reasons.
More information on LaTeX2html can be found at
<div class="center">
<a href="http://www-dsed.llnl.gov/files/programs/unix/latex2html/"><span class="c013">http://www-dsed.llnl.gov/files/programs/unix/latex2html/</span></a>
</div></dd><dt class="dt-description"><span class="c022">TTH</span></dt><dd class="dd-description"> The principle behind TTH is the same as the one of
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A: write a fast translator as a lexer, use symbol fonts and
tables. However, there are differences, TTH accepts both T<sub>E</sub>X and
L<sup>A</sup>T<sub>E</sub>X source,
TTH is written in C and the full source is not available
(only <code>lex</code> output is available).
Additionally, TTH insist on not using any kind of L<sup>A</sup>T<sub>E</sub>X
generated information and will show proper cross-reference labels,
even when no <span class="c013">.aux</span> file is present.
TTH output is a single document,
whereas H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A can cut the output of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A into several files.
(however there exists a commercial
version of TTH that provides this extra functionality).
TTH can be found at
<div class="center">
<a href="http://hutchinson.belmont.ma.us/tth/"><span class="c013">http://hutchinson.belmont.ma.us/tth/</span></a>.
</div></dd><dt class="dt-description"><span class="c014">htmlgen</span></dt><dd class="dd-description"> The <span class="c013">htmlgen</span> translator is specialized
for producing the Caml manuals. This is H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A direct ancestor and I
owe much to its author, X. Leroy. See [<a href="#htmlgen">htmlgen</a>] for a description
of <span class="c013">htmlgen</span> and a (bit outdated) discussion on L<sup>A</sup>T<sub>E</sub>X to
html translation.
</dd></dl>
<!--TOC section id="sec234" Acknowledgements-->
<h2 class="section" id="sec234">C.6  Acknowledgements</h2><!--SEC END --><p>
The following people contributed to H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A development:
</p><ul class="itemize"><li class="li-itemize">
Philip A.Viton, maintains a
<a href="http://facweb.knowlton.ohio-state.edu/pviton/support/winport.html">Windows (win32) port</a> of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
</li><li class="li-itemize">Tibault Suzanne authored the HTML 5 generator that now is
the default generator of H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A.
</li><li class="li-itemize">Abhishek Thakur implemented most of the new features of version
1.08, including, translations of symbols to Unicode entities,
the <span class="c013">babel</span> package, and style sheet support.
</li><li class="li-itemize">Christian Queinnec wrote an extra lexer to translate code
snippets produced by its tool
<a href="http://www-spi.lip6.fr/~queinnec/VideoC/VideoC.html">VideoC</a>
for writing pedagogical documents on programming.
The very principle he introduced for interfacing the <span class="c013">videoc</span>
lexer with H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A main lexer is now used extensively throughout
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A source code.
</li><li class="li-itemize"><a href="http://electric.ee.psu.ac.th/~andrew/">Andrew Seagar</a>
is at the origin of support for the Thai language. He is
the author of the document <a href="thaihevea.html">“How to Use H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A
with the Thai Character Set”</a>.
</li><li class="li-itemize">Pierre Boulet, by using H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A as a stage in his tool
<a href="http://www.lifl.fr/~boulet/softs/mldoc/index.html">MlDoc</a>
for documenting Objective Caml source code, forced me into debugging
H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A implementation of the <code>alltt</code> environment.
</li><li class="li-itemize">Nicolas Tessaud implemented the <code>-text</code> and <code>-info</code>
output modes (see section <a href="#alternative">11</a>).
</li><li class="li-itemize">Georges Mariano asked for
many feature, and argued a lot to have them implemented.
</li><li class="li-itemize">Many users contributed by sending bug reports.
</li></ul><!--TOC section id="sec235" References-->
<h2 class="section" id="sec235"><a id="@biblio">References</a></h2><!--SEC END --><dl class="thebibliography"><dt class="dt-thebibliography">
<a id="latexbis"><span class="c006">[L<sup>A</sup>T<sub>E</sub>X-bis]</span></a></dt><dd class="dd-thebibliography">
M. Gooseens, F. Mittelbach, A. Samarin.
<em>The L<sup>A</sup>T<sub>E</sub>X Companion</em>
Addison-Websley, 1994.
</dd><dt class="dt-thebibliography"><a id="latex"><span class="c006">[L<sup>A</sup>T<sub>E</sub>X]</span></a></dt><dd class="dd-thebibliography">
L. Lamport.
<em>A Document Preparation System System, L<sup>A</sup>T<sub>E</sub>X, User’s
Guide and Reference Manual</em>.
Addison-Websley, 1994.
</dd><dt class="dt-thebibliography"><a id="htmlgen"><span class="c006">[htmlgen]</span></a></dt><dd class="dd-thebibliography">
X. Leroy.
<em>Lessons learned from the translation of documentation
from L<sup>A</sup>T<sub>E</sub>X to html</em>.
ERCIM/W4G Int. Workshop on WWW Authoring and Integration
Tools, 1995.
Available on the web at
<a href="http://cristal.inria.fr/~xleroy/w4g.html"><span class="c013">http://cristal.inria.fr/~xleroy/w4g.html</span></a></dd><dt class="dt-thebibliography"><a id="html4"><span class="c006">[HTML-4.0]</span></a></dt><dd class="dd-thebibliography">
D. Ragget, A. Le Hors and I. Jacobs.
<em>HTML 4.0 Reference Specification</em>. Available on the web at
<a href="http://www.w3.org/TR/REC-html40"><span class="c013">http://www.w3.org/TR/REC-html40</span></a>, 1997.</dd><dt class="dt-thebibliography"><a id="html"><span class="c006">[HTML-5a]</span></a></dt><dd class="dd-thebibliography">
W3C HTML Working groups.
<em>HTML5 A vocabulary and associated APIs for HTML and XHTML</em>
<a href="http://dev.w3.org/html5/spec/spec.html"><span class="c013">http://dev.w3.org/html5/spec/spec.html</span></a>, 2012.</dd><dt class="dt-thebibliography"><a id="htmlb"><span class="c006">[HTML-5b]</span></a></dt><dd class="dd-thebibliography">
<em>HTML Living Standard</em>
<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/"><span class="c013">http://www.whatwg.org/specs/web-apps/current-work/multipage/</span></a>,
2012.</dd><dt class="dt-thebibliography"><a id="css"><span class="c006">[CSS-2]</span></a></dt><dd class="dd-thebibliography">
Bert Bos,
Tantek Çelik,
Ian Hickson
and
Håkon Wium Lie.
<em>Cascading Style Sheets, Level 2 Revision 2 Specification</em>. Available on
the web at
<a href="http://www.w3.org/TR/REC-CSS2/"><span class="c013">http://www.w3.org/TR/REC-CSS2/</span></a>, 2011.
</dd></dl><!--TOC section id="sec236" Index-->
<h2 class="section" id="sec236"><a id="@index">Index</a></h2><!--SEC END --><p></p><table class="c002 cellpading0"><tr><td class="c039"><ul class="indexenv"><li class="li-indexenv">
“ ” (space), <a href="#hevea_default151">B.3.1</a>
<ul class="indexenv"><li class="li-indexenv">
after macro, <a href="#hevea_default1">3.1.2</a>
<ul class="indexenv"><li class="li-indexenv">
in math, <a href="#hevea_default3">3.2.1</a>, <a href="#hevea_default169"><span class="c018">B.7.7</span></a>
</li></ul>
</li></ul>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">##</span><span class="c018">n</span>, <a href="#hevea_default201">B.16.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">-
todir</span> (<span class="c013">imagen</span> option), <a href="#hevea_default136">10.6</a>
</li><li class="li-indexenv"><span class="c013">-dv</span> (<span class="c013">hevea</span> option), <a href="#hevea_default0">3.1.1</a>, <a href="#hevea_default5">3.2.3</a>
</li><li class="li-indexenv"><span class="c013">-e</span> (<span class="c013">hevea</span> option), <a href="#hevea_default182">B.11.4</a>
</li><li class="li-indexenv"><span class="c013">-fix</span> (<span class="c013">hevea</span> option), <a href="#hevea_default25">6.1</a>, <a href="#hevea_default138">10.7</a>, <a href="#hevea_default156">B.4.3</a>, <a href="#hevea_default177">B.11.1</a>, <a href="#hevea_default258">C.1.5</a>, <a href="#hevea_default259">C.1.6</a>
</li><li class="li-indexenv"><span class="c013">-gif</span> (<span class="c013">imagen</span> option), <a href="#hevea_default134">10.5</a>
</li><li class="li-indexenv"><span class="c013">-O</span> (<span class="c013">hevea</span> option), <a href="#hevea_default90">8.4</a>, <a href="#hevea_default234">B.17.13</a>
</li><li class="li-indexenv"><span class="c013">-o</span> (<span class="c013">hevea</span> option), <a href="#hevea_default250">C.1.1.2</a>
</li><li class="li-indexenv"><span class="c013">-pdf</span> (<span class="c013">imagen</span> option), <a href="#hevea_default244">B.17.16</a>
</li><li class="li-indexenv"><span class="c013">-textsymbols</span> (<span class="c013">hevea</span> option), <a href="#hevea_default4">3.2.2</a>
</li><li class="li-indexenv"><span class="c013">-tocbis</span> (<span class="c013">hacha</span> option), <a href="#hevea_default35">7.2.3</a>
</li><li class="li-indexenv"><span class="c013">-tocter</span> (<span class="c013">hacha</span> option), <a href="#hevea_default36">7.2.3</a>
</li><li class="li-indexenv"><span class="c013">-w</span> (<span class="c013">hevea</span> option), <a href="#hevea_default139">11.1</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">\@addimagenopt</span>, <a href="#hevea_default137"><span class="c018">10.7</span></a>
</li><li class="li-indexenv"><span class="c013">\@addstyle</span>, <a href="#hevea_default87">8.3</a>
</li><li class="li-indexenv"><span class="c013">\@bodyargs</span>, <a href="#hevea_default146">B.2</a>
</li><li class="li-indexenv"><span class="c013">\@charset</span>, <a href="#hevea_default150">B.2</a>
</li><li class="li-indexenv"><span class="c013">\@clearstyle</span>, <a href="#hevea_default82"><span class="c018">8.3</span></a>
</li><li class="li-indexenv"><span class="c013">\@close</span>, <a href="#hevea_default77"><span class="c018">8.3</span></a>, <a href="#hevea_default97">8.5</a>, <a href="#hevea_default107">8.5</a>
</li><li class="li-indexenv"><span class="c013">\@def@charset</span>, <a href="#hevea_default111"><span class="c018">8.6</span></a>, <a href="#hevea_default218">B.17.4</a>
</li><li class="li-indexenv"><span class="c013">\@fontcolor</span>, <a href="#hevea_default84"><span class="c018">8.3</span></a>
</li><li class="li-indexenv"><span class="c013">\@fontsize</span>, <a href="#hevea_default83"><span class="c018">8.3</span></a>
</li><li class="li-indexenv"><span class="c013">\@footnotelevel</span>, <a href="#hevea_default54"><span class="c018">7.3.6</span></a>
</li><li class="li-indexenv"><span class="c013">\@getcolor</span>, <a href="#hevea_default108">8.5</a>, <a href="#hevea_default190"><span class="c018">B.14.2.2</span></a>
</li><li class="li-indexenv"><span class="c013">\@getprint</span>, <a href="#hevea_default73"><span class="c018">8.3</span></a>, <a href="#hevea_default102">8.5</a>
</li><li class="li-indexenv"><span class="c013">\@getstylecolor</span>, <a href="#hevea_default118">9.3</a>, <a href="#hevea_default191"><span class="c018">B.14.2.2</span></a>
</li><li class="li-indexenv"><span class="c013">\@hevealibdir</span>, <a href="#hevea_default249"><span class="c018">C.1.1.1</span></a>
</li><li class="li-indexenv"><span class="c013">\@hr</span>, <a href="#hevea_default75"><span class="c018">8.3</span></a>
</li><li class="li-indexenv"><span class="c013">\@meta</span>, <a href="#hevea_default147">B.2</a>
</li><li class="li-indexenv"><span class="c013">\@nostyle</span>, <a href="#hevea_default81"><span class="c018">8.3</span></a>, <a href="#hevea_default103">8.5</a>, <a href="#hevea_default104">8.5</a>
</li><li class="li-indexenv"><span class="c013">\@open</span>, <a href="#hevea_default76"><span class="c018">8.3</span></a>, <a href="#hevea_default96">8.5</a>, <a href="#hevea_default106">8.5</a>
</li><li class="li-indexenv"><span class="c013">\@print</span>, <a href="#hevea_default72"><span class="c018">8.3</span></a>, <a href="#hevea_default101">8.5</a>
</li><li class="li-indexenv"><span class="c013">\@print@u</span>, <a href="#hevea_default6">4.2</a>, <a href="#hevea_default74"><span class="c018">8.3</span></a>, <a href="#hevea_default109">8.5</a>, <a href="#hevea_default110">8.6</a>
</li><li class="li-indexenv"><span class="c013">\@span</span>, <a href="#hevea_default80"><span class="c018">8.3</span></a>
</li><li class="li-indexenv"><span class="c013">\@style</span>, <a href="#hevea_default78"><span class="c018">8.3</span></a>
</li><li class="li-indexenv"><span class="c013">\@styleattr</span>, <a href="#hevea_default79"><span class="c018">8.3</span></a>
<br>
<br>
</li><li class="li-indexenv"><code>\bigl,\bigr</code> etc., <a href="#hevea_default167">B.7.5</a>
</li><li class="li-indexenv"><code>\boxed</code>, <a href="#hevea_default166">B.7.5</a>
</li><li class="li-indexenv"><code>\sqrt</code>, <a href="#hevea_default160">B.7.3</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">\addcontentsline</span>, <a href="#hevea_default155"><span class="c018">B.4.3</span></a>
</li><li class="li-indexenv"><span class="c013">\ahref</span>, <a href="#hevea_default57"><span class="c018">8.1.1</span></a>
</li><li class="li-indexenv"><span class="c013">\ahrefloc</span>, <a href="#hevea_default50">7.3.5</a>, <a href="#hevea_default60"><span class="c018">8.1.1</span></a>
</li><li class="li-indexenv"><span class="c013">\ahrefurl</span>, <a href="#hevea_default58"><span class="c018">8.1.1</span></a>
</li><li class="li-indexenv"><span class="c013">amsmath</span> package, <a href="#hevea_default212">B.17.1</a>
</li><li class="li-indexenv"><span class="c013">amssymb</span> package, <a href="#hevea_default213">B.17.1</a>
</li><li class="li-indexenv"><span class="c013">\aname</span>, <a href="#hevea_default49">7.3.5</a>, <a href="#hevea_default61"><span class="c018">8.1.1</span></a>
</li><li class="li-indexenv">argument<ul class="indexenv"><li class="li-indexenv">
of commands, <a href="#hevea_default142">B.1.1</a>
</li><li class="li-indexenv">of <span class="c013">\input</span>, <a href="#hevea_default181">B.11.4</a>
</li></ul>
</li><li class="li-indexenv"><span class="c013">array</span> package, <a href="#hevea_default214">B.17.2</a>
<br>
<br>
</li><li class="li-indexenv">babel<ul class="indexenv"><li class="li-indexenv">
languages, <a href="#hevea_default228">B.17.10.2</a>
</li></ul>
</li><li class="li-indexenv"><span class="c013">babel</span> package, <a href="#hevea_default227">B.17.10</a>
</li><li class="li-indexenv"><span class="c013">bgcolor</span> environment, <a href="#hevea_default105">8.5</a>, <a href="#hevea_default189"><span class="c018">B.14.2.1</span></a>
</li><li class="li-indexenv">block-level elements, <a href="#hevea_default71">8.3</a>
</li><li class="li-indexenv">browser configuration, <a href="#hevea_default260">C.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">calc</span> package, <a href="#hevea_default216">B.17.3</a>
</li><li class="li-indexenv"><span class="c013">chapterbib</span> package, <a href="#hevea_default226">B.17.9</a>
</li><li class="li-indexenv"><span class="c013">cleveref</span> package, <a href="#hevea_default247">B.17.19</a>
</li><li class="li-indexenv">color<ul class="indexenv"><li class="li-indexenv">
of background, see <span style="font-family:monospace;font-style:italic">\@bodyargs</span>
</li><li class="li-indexenv">of section headings, <a href="#hevea_default206">B.16.4</a>
</li></ul>
</li><li class="li-indexenv"><span class="c013">color</span> package, <a href="#hevea_default188">B.14.2</a>
</li><li class="li-indexenv"><span class="c013">\colorsections</span>, <a href="#hevea_default208"><span class="c018">B.16.4</span></a>
</li><li class="li-indexenv">command<ul class="indexenv"><li class="li-indexenv">
and arguments, <a href="#hevea_default141">B.1.1</a>
</li><li class="li-indexenv">definition, <a href="#hevea_default170"><span class="c018">B.8.1</span></a>, <a href="#hevea_default193">B.16.1.1</a>, <a href="#hevea_default202">B.16.2</a>
</li><li class="li-indexenv">syntax, <a href="#hevea_default140">B.1.1</a>
</li></ul>
</li><li class="li-indexenv">comment<ul class="indexenv"><li class="li-indexenv">
<span class="c013">%BEGIN IMAGE</span>, <a href="#hevea_default20">5.3</a>
</li><li class="li-indexenv"><span class="c013">%BEGIN LATEX</span>, <a href="#hevea_default19">5.3</a>
</li><li class="li-indexenv"><span class="c013">%END IMAGE</span>, <a href="#hevea_default22">5.3</a>
</li><li class="li-indexenv"><span class="c013">%END LATEX</span>, <a href="#hevea_default21">5.3</a>
</li><li class="li-indexenv"><span class="c013">%HEVEA</span>, <a href="#hevea_default18">5.2.3</a>
</li></ul>
</li><li class="li-indexenv"><span class="c013">comment</span> package, <a href="#hevea_default220">B.17.6</a>
</li><li class="li-indexenv"><span class="c013">\cutdef</span>, <a href="#hevea_default33">7.2.2</a>, <a href="#hevea_default37">7.2.4</a>
</li><li class="li-indexenv"><span class="c013">\cutend</span>, <a href="#hevea_default34">7.2.2</a>, <a href="#hevea_default38">7.2.4</a>
</li><li class="li-indexenv"><span class="c013">cutflow</span> environment, <a href="#hevea_default48"><span class="c018">7.3.5</span></a>
</li><li class="li-indexenv"><span class="c013">cutflow*</span> environment, <a href="#hevea_default51"><span class="c018">7.3.5</span></a>
</li><li class="li-indexenv"><span class="c013">\cuthere</span>, <a href="#hevea_default32">7.2.2</a>, <a href="#hevea_default39">7.2.4</a>
</li><li class="li-indexenv"><span class="c013">\cutname</span>, <a href="#hevea_default43"><span class="c018">7.3.1</span></a>
</li><li class="li-indexenv"><span class="c013">cuttingdepth</span> counter, <a href="#hevea_default31">7.2.2</a>
</li><li class="li-indexenv"><span class="c013">\cuttingunit</span>, <a href="#hevea_default28">7.2.2</a>, <a href="#hevea_default40">7.2.4</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">deepcut</span> package, <a href="#hevea_default41">7.2.5</a>
</li><li class="li-indexenv"><span class="c013">\def</span>, <a href="#hevea_default192">B.16.1.1</a>
</li><li class="li-indexenv">display problems<ul class="indexenv"><li class="li-indexenv">
for authors, <a href="#hevea_default210">B.16.5</a>
</li><li class="li-indexenv">for viewers, <a href="#hevea_default261">C.2</a>
</li></ul>
</li><li class="li-indexenv"><span class="c013">divstyle</span> environment, <a href="#hevea_default122"><span class="c018">9.5.2</span></a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">\else</span>, <a href="#hevea_default199">B.16.1.4</a>
</li><li class="li-indexenv"><span class="c013">esponja</span> command, <a href="#hevea_default252">C.1.3</a>
</li><li class="li-indexenv"><span class="c013">externalcss</span> (boolean register), <a href="#hevea_default124"><span class="c018">9.6.2</span></a>
</li><li class="li-indexenv"><span class="c013">\externalcsstrue</span>, <a href="#hevea_default125"><span class="c018">9.6.2</span></a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">fancysection</span> package, <a href="#hevea_default207">B.16.4</a>
</li><li class="li-indexenv"><span class="c013">\fi</span>, <a href="#hevea_default200">B.16.1.4</a>
</li><li class="li-indexenv"><span class="c013">figcut</span> package, <a href="#hevea_default42">7.2.5</a>
</li><li class="li-indexenv"><span class="c013">\flushdef</span>, <a href="#hevea_default53"><span class="c018">7.3.6</span></a>, <a href="#hevea_default55">7.3.6</a>
</li><li class="li-indexenv"><span class="c013">\footahref</span>, <a href="#hevea_default59"><span class="c018">8.1.1</span></a>
</li><li class="li-indexenv"><span class="c013">\footnoteflush</span>, <a href="#hevea_default52"><span class="c018">7.3.6</span></a>
</li><li class="li-indexenv"><span class="c013">\footurl</span>, <a href="#hevea_default67">8.1.1</a>
<br>
<br>
</li><li class="li-indexenv">GIF, <a href="#hevea_default131">10.5</a>, <a href="#hevea_default255">C.1.5</a>
</li><li class="li-indexenv"><span class="c013">\gdef</span>, <a href="#hevea_default196">B.16.1.3</a>
</li><li class="li-indexenv"><span class="c013">\getenvclass</span>, <a href="#hevea_default99">8.5</a>, <a href="#hevea_default117"><span class="c018">9.3</span></a>
</li><li class="li-indexenv"><span class="c013">\global</span>, <a href="#hevea_default195">B.16.1.3</a>
</li><li class="li-indexenv"><span class="c013">graphics</span> package, <a href="#hevea_default186">B.14.1</a>
</li><li class="li-indexenv"><span class="c013">graphicx</span> package, <a href="#hevea_default187">B.14.1</a>
</li></ul></td><td class="c039"><ul class="indexenv"><li class="li-indexenv"><span class="c013">hacha</span> command, <a href="#hevea_default251">C.1.2</a>
</li><li class="li-indexenv"><span class="c013">hanging</span> package, <a href="#hevea_default246">B.17.18</a>
</li><li class="li-indexenv"><span class="c013">hevea</span> boolean register, <a href="#hevea_default17">5.2.3</a>
</li><li class="li-indexenv"><span class="c013">hevea</span> command, <a href="#hevea_default248">C.1.1</a>
</li><li class="li-indexenv"><span class="c013">\heveadate</span>, <a href="#hevea_default205">B.16.3</a>
</li><li class="li-indexenv"><span class="c013">\heveaimagedir</span>, <a href="#hevea_default135">10.6</a>
</li><li class="li-indexenv"><span class="c013">\home</span>, <a href="#hevea_default64"><span class="c018">8.1.1</span></a>
</li><li class="li-indexenv"><span class="c013">\htmlcolor</span>, <a href="#hevea_default68">8.1.2</a>
</li><li class="li-indexenv"><span class="c013">\htmlfoot</span>, <a href="#hevea_default144">B.2</a>
</li><li class="li-indexenv"><span class="c013">\htmlhead</span>, <a href="#hevea_default143">B.2</a>
</li><li class="li-indexenv"><span class="c013">htmlonly</span> environment, <a href="#hevea_default8"><span class="c018">5.2.1</span></a>
</li><li class="li-indexenv"><span class="c013">\htmlprefix</span>, <a href="#hevea_default44"><span class="c018">7.3.2</span></a>
</li><li class="li-indexenv">hyperlinks, <a href="#hevea_default56">8.1.1</a>, <a href="#hevea_default230">B.17.11</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">\if</span>, <a href="#hevea_default198">B.16.1.4</a>
</li><li class="li-indexenv"><span class="c013">ifpdf</span> package, <a href="#hevea_default243">B.17.16</a>
</li><li class="li-indexenv"><span class="c013">ifthen</span> package, <a href="#hevea_default173">B.8.5</a>
</li><li class="li-indexenv">image inclusion<ul class="indexenv"><li class="li-indexenv">
bitmap, <a href="#hevea_default69">8.2</a>
</li><li class="li-indexenv">in Postscript, <a href="#hevea_default26"><span class="c018">6.3</span></a>, <a href="#hevea_default128">10.4</a>, <a href="#hevea_default185">B.14.1</a>
</li><li class="li-indexenv">output format, <a href="#hevea_default129">10.5</a>
</li></ul>
</li><li class="li-indexenv"><span class="c013">\imageflush</span>, <a href="#hevea_default24"><span class="c018">6.1</span></a>, <a href="#hevea_default132">10.5</a>
</li><li class="li-indexenv"><span class="c013">imagen</span> command, <a href="#hevea_default253">C.1.5</a>
</li><li class="li-indexenv"><span class="c013">\imgsrc</span>, <a href="#hevea_default47">7.3.4</a>, <a href="#hevea_default63"><span class="c018">8.1.1</span></a>, <a href="#hevea_default70">8.2</a>, <a href="#hevea_default100">8.5</a>, <a href="#hevea_default133">10.5</a>
</li><li class="li-indexenv"><span class="c013">index</span> package, <a href="#hevea_default221">B.17.7</a>
</li><li class="li-indexenv"><span class="c013">indexcols</span> counter, <a href="#hevea_default184">B.11.5</a>
</li><li class="li-indexenv"><span class="c013">indexenv</span> environment, <a href="#hevea_default183"><span class="c018">B.11.5</span></a>
</li><li class="li-indexenv">inference rules, <a href="#hevea_default239">B.17.15</a>
</li><li class="li-indexenv"><span class="c013">\input</span>, <a href="#hevea_default180"><span class="c018">B.11.4</span></a>
</li><li class="li-indexenv"><span class="c013">inputenc</span> package, <a href="#hevea_default217">B.17.4</a>
</li><li class="li-indexenv"><span class="c013">\inputencoding</span>, <a href="#hevea_default219"><span class="c018">B.17.4</span></a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">\label</span>, <a href="#hevea_default153">B.4.1</a>, <a href="#hevea_default178"><span class="c018">B.11.2</span></a>
</li><li class="li-indexenv"><span class="c013">latexonly</span> environment, <a href="#hevea_default7"><span class="c018">5.2.1</span></a>, <a href="#hevea_default14">5.2.2</a>
</li><li class="li-indexenv"><span class="c013">\let</span>, <a href="#hevea_default148">B.2</a>, <a href="#hevea_default194"><span class="c018">B.16.1.2</span></a>
</li><li class="li-indexenv"><span class="c013">listings</span> package, <a href="#hevea_default233">B.17.13</a>
</li><li class="li-indexenv"><span class="c013">\loadcssfile</span>, <a href="#hevea_default126"><span class="c018">9.6.3</span></a>
</li><li class="li-indexenv"><span class="c013">longtable</span> package, <a href="#hevea_default236">B.17.14</a>
</li><li class="li-indexenv"><span class="c013">\lstavoidwhitepre</span>, <a href="#hevea_default235"><span class="c018">B.17.13</span></a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">\mailto</span>, <a href="#hevea_default62"><span class="c018">8.1.1</span></a>
</li><li class="li-indexenv"><span class="c013">\marginpar</span>, <a href="#hevea_default174"><span class="c018">B.9</span></a>
</li><li class="li-indexenv">math accents, <a href="#hevea_default168">B.7.6</a>
</li><li class="li-indexenv"><span class="c013">mathpartir</span> package, <a href="#hevea_default238">B.17.15</a>
<ul class="indexenv"><li class="li-indexenv">
derivation trees, <a href="#hevea_default242">B.17.15.4</a>
</li><li class="li-indexenv"><code>\inferrule</code>, <a href="#hevea_default241">B.17.15.2</a>
</li><li class="li-indexenv"><span class="c013">mathpar</span> environment, <a href="#hevea_default240">B.17.15.1</a>
</li></ul>
</li><li class="li-indexenv"><span class="c013">multibib</span> package, <a href="#hevea_default224">B.17.9</a>
</li><li class="li-indexenv"><span class="c013">multind</span> package, <a href="#hevea_default222">B.17.7</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">natbib</span> package, <a href="#hevea_default223">B.17.8</a>
</li><li class="li-indexenv"><span class="c013">\newcites</span>, <a href="#hevea_default225">B.17.9</a>
</li><li class="li-indexenv"><span class="c013">\newcommand</span>, <a href="#hevea_default171">B.8.1</a>
</li><li class="li-indexenv"><span class="c013">\newif</span>, <a href="#hevea_default197">B.16.1.4</a>
</li><li class="li-indexenv"><span class="c013">\newstyle</span>, <a href="#hevea_default114"><span class="c018">9.1</span></a>
</li><li class="li-indexenv"><span class="c013">\normalmarginpar</span>, <a href="#hevea_default176"><span class="c018">B.9</span></a>
</li><li class="li-indexenv"><span class="c013">\notocnumber</span>, <a href="#hevea_default30">7.2.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">\oneurl</span>, <a href="#hevea_default66">8.1.1</a>
<br>
<br>
</li><li class="li-indexenv">PDF, <a href="#hevea_default256">C.1.5</a>
</li><li class="li-indexenv">PNG, <a href="#hevea_default130">10.5</a>, <a href="#hevea_default254">C.1.5</a>
</li><li class="li-indexenv">pdflatex, <a href="#hevea_default257">C.1.5</a>
</li><li class="li-indexenv"><span class="c013">\purple</span>, <a href="#hevea_default95">8.5</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">raw</span> environment, <a href="#hevea_default91">8.4</a>
</li><li class="li-indexenv"><span class="c013">rawhtml</span> environment, <a href="#hevea_default9"><span class="c018">5.2.1</span></a>, <a href="#hevea_default88">8.4</a>, <a href="#hevea_default149">B.2</a>
</li><li class="li-indexenv"><span class="c013">\rawhtmlinput</span>, <a href="#hevea_default89">8.4</a>
</li><li class="li-indexenv"><span class="c013">\rawinput</span>, <a href="#hevea_default92">8.4</a>
</li><li class="li-indexenv"><span class="c013">rawtext</span> environment, <a href="#hevea_default93">8.4</a>
</li><li class="li-indexenv"><span class="c013">\rawtextinput</span>, <a href="#hevea_default94">8.4</a>
</li><li class="li-indexenv"><span class="c013">\ref</span>, <a href="#hevea_default179"><span class="c018">B.11.2</span></a>
</li><li class="li-indexenv"><span class="c013">\renewcommand</span>, <a href="#hevea_default172">B.8.1</a>
</li><li class="li-indexenv"><span class="c013">\reversemarginpar</span>, <a href="#hevea_default175"><span class="c018">B.9</span></a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">\setenvclass</span>, <a href="#hevea_default98">8.5</a>, <a href="#hevea_default116"><span class="c018">9.3</span></a>
</li><li class="li-indexenv"><span class="c013">\setlinkstext</span>, <a href="#hevea_default46"><span class="c018">7.3.4</span></a>
</li><li class="li-indexenv">spacing, see <span class="c018">“ ”</span>
</li><li class="li-indexenv">sqrt, <a href="#hevea_default161">B.7.3</a>
</li><li class="li-indexenv">style-sheets, <a href="#hevea_default113">9</a>
<ul class="indexenv"><li class="li-indexenv">
<code>\divstyle</code>, <a href="#hevea_default121">9.5.2</a>
</li><li class="li-indexenv"><code>\loadcssfile</code>, <a href="#hevea_default127">9.6.3</a>
</li><li class="li-indexenv"><code>\newstyle</code>, <a href="#hevea_default115">9.1</a>
</li><li class="li-indexenv">and H<span class="c015"><sup>A</sup></span>C<span class="c015"><sup>H</sup></span>A, <a href="#hevea_default27">7.1</a>
</li></ul>
</li><li class="li-indexenv">styles for<ul class="indexenv"><li class="li-indexenv">
lists, <a href="#hevea_default123">9.5.3</a>
</li><li class="li-indexenv">miscellaneous objects, <a href="#hevea_default120">9.5.2</a>
</li><li class="li-indexenv">title, <a href="#hevea_default119">9.5.1</a>
</li></ul>
</li><li class="li-indexenv"><span class="c013">supertabular</span> package, <a href="#hevea_default237">B.17.14</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">\tableofcontents</span>, <a href="#hevea_default154"><span class="c018">B.4.3</span></a>
</li><li class="li-indexenv"><span class="c013">tabularx</span> package, <a href="#hevea_default215">B.17.2</a>
</li><li class="li-indexenv">tabulation, <a href="#hevea_default2">3.1.2</a>
</li><li class="li-indexenv">text-level elements, <a href="#hevea_default85">8.3</a>
<ul class="indexenv"><li class="li-indexenv">
span, <a href="#hevea_default86">8.3</a>
</li></ul>
</li><li class="li-indexenv"><span class="c013">\textoverline</span>, <a href="#hevea_default165">B.7.5</a>
</li><li class="li-indexenv"><span class="c013">\textstackrel</span>, <a href="#hevea_default163">B.7.5</a>
</li><li class="li-indexenv"><span class="c013">\textunderline</span>, <a href="#hevea_default164">B.7.5</a>
</li><li class="li-indexenv">Thai, <a href="#hevea_default245">B.17.17</a>
</li><li class="li-indexenv"><span class="c013">\title</span>, <a href="#hevea_default158">B.5.3</a>
</li><li class="li-indexenv"><span class="c013">\tocnumber</span>, <a href="#hevea_default29">7.2.2</a>
</li><li class="li-indexenv"><span class="c013">\today</span>, <a href="#hevea_default159">B.5.3</a>, <a href="#hevea_default203">B.16.3</a>
</li><li class="li-indexenv"><span class="c013">toimage</span> environment, <a href="#hevea_default10"><span class="c018">5.2.1</span></a>, <a href="#hevea_default16">5.2.2</a>, <a href="#hevea_default23">6.1</a>
</li><li class="li-indexenv"><span class="c013">\toplinks</span>, <a href="#hevea_default45"><span class="c018">7.3.3</span></a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">undersection</span> package, <a href="#hevea_default209">B.16.4</a>
</li><li class="li-indexenv">unicode, <a href="#hevea_default162">B.7.4</a>
</li><li class="li-indexenv"><span class="c013">\url</span>, <a href="#hevea_default65">8.1.1</a>, <a href="#hevea_default229"><span class="c018">B.17.11</span></a>
</li><li class="li-indexenv"><span class="c013">url</span> package, <a href="#hevea_default231">B.17.11</a>
</li><li class="li-indexenv"><span class="c013">\urldef</span>, <a href="#hevea_default232">B.17.11</a>
</li><li class="li-indexenv"><span class="c013">\usepackage</span>, <a href="#hevea_default157">B.5.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">verbimage</span> environment, <a href="#hevea_default11"><span class="c018">5.2.1</span></a>, <a href="#hevea_default15">5.2.2</a>
</li><li class="li-indexenv"><span class="c013">verblatex</span> environment, <a href="#hevea_default12"><span class="c018">5.2.1</span></a>, <a href="#hevea_default13">5.2.2</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">winfonts</span> package, <a href="#hevea_default211">B.16.5</a>
<br>
<br>
</li><li class="li-indexenv"><span class="c013">xxcharset.exe</span> script, <a href="#hevea_default112">8.6</a>
</li><li class="li-indexenv"><span class="c013">xxdate.exe</span> script, <a href="#hevea_default204">B.16.3</a>
</li></ul></td></tr>
</table><!--CUT END -->
<!--CUT END -->
<!--BEGIN STICKYNOTES document-->
<hr class="ffootnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes">
<a id="note1" href="#text1">*</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">Inria Rocquencourt – BP 105, 78153 Le
Chesnay Cedex. <a href="mailto:Luc.Maranget@inria.fr"><span class="c013">Luc.Maranget@inria.fr</span></a></div>
</dd></dl>
<!--END NOTES-->
<!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<hr style="height:2"><blockquote class="quote"><em>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</em><a href="http://hevea.inria.fr/index.html"><em>H<span class="c015"><sup>E</sup></span>V<span class="c015"><sup>E</sup></span>A</em></a><em>.</em></blockquote></body>
</html>
