HEVEA User Documentation |
This manual also exists in compressed Postscript, PDF, and as a bundle of HTML files.
Abstract: HEVEA is a LATEX to html translator. The input language is a fairly complete subset of LATEX 2є (old LATEX style is also accepted) and the output language is html that is (hopefully) correct with respect to version 5 [HTML-5a, HTML-5b]HEVEA understands LATEX macro definitions. Simple user style files are understood with little or no modifications. Furthermore, HEVEA customisation is done by writing LATEX code.
HEVEA is written in Objective Caml, as many lexers. It is quite fast and flexible. Using HEVEA 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 HACHA.
HEVEA can also be instructed to output plain text or info files.
Information on HEVEA is available at http://hevea.inria.fr/.
This document consists in three parts, a tutorial introduction, a reference manual and some practical information. The latter part includes a small index.
Part A |
Assume that you have a file, a.tex, written in LATEX, using the article, book or report style. Then, translation is achieved by issuing the command:
# hevea a.tex
Probably, you will get some warnings. If HEVEA does not crash, just ignore them for the moment (Section 4 explains how to correct errors).
If everything goes fine, this will produce a new file, a.html, which you can visualise through a html browser.
If you wish to experiment HEVEA on small LATEX source fragments, then launch HEVEA without arguments. HEVEA will read its standard input and print the translation on its standard output. For instance:
# hevea $x \in \mathcal{E}$ ^D <span style="font-style:italic">x</span> ∈ <span style="color:red"><span style="font-style:italic">E</span></span>
Incidentally, notice that the symbol “∈” translates to the appropriate numerical character reference and that the calligraphic letter “E” renders as a red “E”. You can find some more elaborate examples in the on-line documentation.
LATEX style files are files that are not intended to produce output, but define document layout parameters, commands, environments, etc.
The base style of a LATEX document is the argument to the
\documentclass
command (\documentstyle
in old style).
Normally, the base style of a document defines the structure and
appearance of the whole document.
HEVEA really knows about two LATEX base styles, article and book. Additionally, the report base style is recognized and considered equivalent to book and the seminar base style for making slides is recognized and implemented by small additions on the article style.
Base style style is implemented by an HEVEA specific
style file style.hva
.
More precisely, HEVEA interprets
\documentclass{
style}
by attempting to load
the file style.hva
(see section C.1.1.1 on where
HEVEA searches for files).
Thus, at the moment, HEVEA distribution includes the files,
article.hva, book.hva, etc.
Documents whose base style is not recognized by HEVEA can be processed when the unknown base style is a derivation of a recognized base style.
Let us assume that doc.tex uses an exotic
base style such as acmconf. Then, typing
hevea doc.tex
will yield an error, since
HEVEA cannot find the acmconf.hva file:
# hevea.opt doc.tex doc.tex:1: Warning: Cannot find file: acmconf.hva doc.tex:1: Error while reading LaTeX: No base style Adios
This situation is avoided by invoking HEVEA with the known base style file article.hva as an extra argument:
# hevea article.hva doc.tex
The extra argument instructs
HEVEA to load its article.hva
style file before processing doc.tex.
It will then ignore the document base style specified by
\documentclass
(or \documentstyle
).
Observe that the fix above works because the acmconf and article base styles look the same to the document (i.e. they define the same macros). More generally, most base styles that are neither article nor book 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 HEVEA about them (see section 4.1).
Finally, it is important to notice that
renaming a base style file style.cls
into
style.hva
will not work in general.
As a matter of fact, base style files are TEX and not LATEX source and
HEVEA will almost surely fail on TEX-ish input.
A LATEX document usually loads additional style files, by using
the commands \input
or \usepackage
or \input
.
Just like LATEX, HEVEA reacts to the construct
\input{
file}
by loading the file
file. (if I got it right, HEVEA even follows TEX’s crazy
conventions on .tex extensions).
As it is often the case, assume that the document doc.tex has a
\input{mymacros.tex}
instruction in its preamble, where
mymacros.tex gathers custom definitions.
Hopefully, only a few macros give rise to trouble: macros that performs fine
typesetting or TEXish macros.
Such macros need to be rewritten, using basic LATEX
constructs (section 4 gives examples of macro-rewriting).
The new definitions are best collected in a style file,
mymacros.hva for instance.
Then, doc.tex is to be translated by issuing the command:
# hevea mymacros.hva doc.tex
The file mymacros.hva is processed before
doc.tex (and thus before mymacros.tex).
As a consequence of HEVEA behaviour with respect to
definition and redefinition (see section B.8.1),
the macro definitions in mymacros.hva
take precedence over the ones in mymacros.tex, provided
the document original definitions (the ones in
mymacros.tex) are performed by \newcommand
(or \newenvironment
).
Another situation is when HEVEA fails to process a whole style file. Usually, this means that HEVEA crashes on that style file. The basic idea is then to write a mymacros.hva style file that contains alternative definitions for all the commands defined in mymacros.sty. Then, HEVEA should be instructed to load mymacros.hva and not to load mymacros.tex. This is done by invoking hevea as follows:
# hevea mymacros.hva -e mymacros.tex doc.tex
Of course, mymacros.hva must now contain replacements for all the useful macros of mymacro.tex.
As far as I know, LATEX reacts to the construct
\usepackage{
name}
by loading the file
name.sty.
HEVEA reacts in a similar, but different, manner, by
loading the file name.hva.
HEVEA distributions already includes quite a few .hva
implementations of famous packages (see section B.17).
When a given package (say zorglub) 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
zorglub, and you feel confident enough to implement
them yourself.
Then, it suffices to put your definitions in file zorglub.hva
and HEVEA will react to \usepackage{zorglub}
by loading
zorglub.hva.
See section B.5.2 for the full story on \usepackage
.
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 HEVEA executes the \par
command.
Otherwise, HEVEA outputs a single newline character.
This process approximates TEX process for introducting paragraph
breaks and, as a result, empty lines produce paragraph breaks.
Space after commands with no argument is skipped (as in LATEX) — however this is not true in math mode, as explained in section 3.2.1.
The following two subsections describe management of paragraphs and spaces after command sequences in greater detail. They can be skipped in first reading.
Paragraphs are rendered by the means of p
elements.
HEVEA is a bit simplistic in breaking paragraphs and spurious paragraphs
may be present in the final html document.
Normally, as HEVEA never outputs p
elements whose contents is
made of spaces only, this should not happen very often.
Unfortunately, some commands do not produce any output in LATEX,
while they do produce output in HEVEA: those commands
are \label
, \index
etc.
HEVEA translates
\label{
name}
into the anchor
<a id="
name"></a>
. As a result, the following
source fragment will introduce a spurious paragraph.
This a first paragraph. \label{label} This is another paragraph.
Indeed, whe have the following translation:
<p>This a first paragraph.</p> <p><a id="label"></a></p> <p>This is another paragraph.</p>
Which your browser renders as follows — with additional borders
emphasizing p
elements.
This a first paragraph.
This is another paragraph.
Most of the time, such extra paragraphs remain unnoticed. Of course, they can be supressed by erasing one of the empty lines. For instance:
This a first paragraph. \label{label} This is another paragraph.
A similar situation occurs when a sectioning command is followed by
\label
and a paragraph break:
\section*{A section}\label{section:label} First paragraph.
Produced html is, after a few cosmetic simplifications:
<h2 class="section">A section</h2> <p><a id="section:label"></a></p> <p>First paragraph.</p>
Output is so, because closing the element h2
implies re-opening
a new paragraph.
Your browser renders the above html fragment as follows:
A section
First paragraph.
Here, two possible re-writing of source are:
\section*{A\label{section:label} section} First paragraph. | \section*{A section} \label{section:label}First paragraph. |
In all cases, this amounts to avoiding a paragraph whose contents
consists in a sole \label
command.
Spurious paragraphs are more easily seen by running hevea
with the command-line option -dv, which instructs
hevea to add border on some of the elements it produces,
including p
elements.
Space after commands with no argument is skipped. Consider the following example:
\newcommand{\open}{(} \newcommand{\close}{)} \open text opened by ``\verb+\open+'' and closed by ``\verb+\close+''\close.
We get:
(text opened by “\open
” and closed by “\close
”).
In the output above, the space after \open
does not
find its way to the output.
More generally,
HEVEA tries to emulate LATEX behaviour in all situations, but
discrepancies probably exist.
Thus, users are invited to make explicit what they want.
This is good practice anyway, because LATEX is mysterious
here. Consider the following example, where the \tryspace
macro is first applied and then expansed by hand:
\newcommand{\bfsymbol}{\textbf{symbol}} \newcommand{\tryspace}[1]{#1 XXX} Some space: \tryspace{\bfsymbol}\\ No space: \bfsymbol XXX
Spacing is a bit chaotic here,
the space after symbol remains when #1
is substituted for it
by LATEX (or HEVEA).
Some space : symbol XXX No space : symbolXXX
Note that, if a space before “XXX” is wanted, then one should probably write:
\newcommand{\tryspace}[1]{#1{} XXX}
Finally, whether the tabulation character is a space or not is random, so avoid tabs in your source document.
HEVEA 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.
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.
By contrast with LATEX, spaces from the input are significant in
math mode, this
feature allows users to instruct HEVEA
on how to put space in their formulas.
For instance, \alpha\rightarrow\beta
is typeset without spaces between
symbols, whereas \alpha \rightarrow \beta
produces these spaces.
|
Note that LATEX ignores spaces in math mode, so that users can freely adjust HEVEA output without changing anything to LATEX output.
\in: ∈ \notin: ∉ \int: ∫ \prod: ∏ \preceq: ≼ \prec: ≺ \leq: ≤ \geq: ≥ \cup: ∪ \cap: ∩ \supset: ⊃ \subset: ⊂ \supseteq: ⊇ \subseteq: ⊆
With respect to previous versions of HEVEA 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 1 for a few such symbols.
However, this means that ancient or purposely limited browsers (such as text-oriented browsers) cannot display maths, as translated by HEVEA. For authors that insist on avoiding symbols that cannot be shown by any browser, HEVEA offers a degraded mode that outputs text in place of symbols. HEVEA operates in this mode when given the -textsymbols 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.
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. HEVEA handles such constraints in display mode only.
The main two operating modes of HEVEA are text mode and display 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 displayed-paragraph environments of LATEX (such as center or quote) are rendered by html block-level elements (such as div or blockquote). Rendering is correct becauses both LATEX 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. HEVEA chooses to translate in-text formulas that way.
HEVEA display mode allows more control on text placement, since
entering display mode means opening
a html table
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.
Display mode is first opened by opening a displaymath
environment
(e.g. by $$
or \[
).
Then, sub-displays are opened by LATEX constructs which require
them.
For instance, a displayed fraction (\frac
) opens a vertical display.
The distinction between text and display modes clearly appears while
typesetting math formulas.
An in-text formula such as
$\int_1^2 xdx = \frac{3}{2}$
appears as:
∫12 xdx =3/2,
while the same formula has a better aspect in display mode:
∫ |
| xdx = |
|
As a consequence, HEVEA 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 LATEX but it is more strict in HEVEA, 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.
Users should remember that HEVEA is not TEX or LATEX and that HEVEA 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.
| = |
|
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 TEX box placement.
Users can get an idea on how HEVEA combines elements in display mode
by giving the -dv command-line option, which
instructs HEVEA to add
borders to the table
elements introduced by displays.
By contrast with formulas, which HEVEA attempts to render with
text-level elements only when they appear inside paragraphs, LATEX arrays
always translate to the
block-level element table
, 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.
Consider the following source:
This is a small array: \begin{tabular}{|cc|} \hline item-1 & item-2 \\ \hline\end{tabular}. Next sentence.
We get:
This is a small array:. Next sentence.
item-1 item-2
However, since in some sense, all html tables are displayed, the
array
and tabular
environments implicitly open display
mode, thus allowing a satisfactory typesetting of formulas in
arrays. More precisely, array elements whose column format
specification is l
, c
or r
are typeset in display
mode (see section B.10.2).
When HEVEA 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.
In the following (silly) example, HEVEA gets nervous because of
the complicated length given as argument to \hspace
:
\newlength{\mylength}\setlength{\mylength}{5pt} \begin{tabular}{c@{\hspace{\mylength}}c} Before & After \end{tabular}
Running HEVEA on this input produces a warning:
# hevea manual.tex ... manual.tex:507: Warning: \hspace with arg '\mylength' ...
However the final rendering is correct:
Before After
Note that all warnings can be suppressed with the -s
(silent)
option.
When a warning reveals a real problem, it can often be cured by
writing a specific macro. The next two sections introduce HEVEA
macros, then section 4 describes how to proceed with
greater detail.
Just like LATEX, HEVEA 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.
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 HEVEA to their needs, but it remains a subtle task. Nevertheless, happy LATEX users should enjoy customizing HEVEA, since this is done by writing LATEX code.
LATEX and html differ in many aspects. For instance, LATEX allows fine control over text placement, whereas html does not. More symbols and font attributes are available in LATEX than in html. Conversely, html has font attributes, such as color, which standard LATEX has not.
Therefore, there are many situations where HEVEA just cannot
render the visual effect of LATEX constructions. Here some choices
have to be made. For instance, calligraphic letters (\mathcal
)
are rendered in red.
If you are not satisfied with HEVEA rendering of text style
declarations, then you
can choose your own, by redefining the \cal
macros, using \renewcommand
, the macro redefinition operator of
LATEX. The key point is that you need not worry about HEVEA
internals: just redefine the old-LATEX style text-style
declarations (i.e. \it
, \sc
, etc.) and everything should
get fine:
\renewcommand{\sc}{\Huge} \renewcommand{\cal}{\em}
(See sections 4 and 5 on how to make such changes while leaving your file processable by LATEX, and section 10.2 for a more thorough descripton of customizing type styles).
With such redefinitions, we get:
This is small caps and this is CALLIGRAPHIC LETTERS
Note that many of LATEX commands and environments are defined in the hevea.hva file that HEVEA loads before processing any input. These constructs are written using LATEX source code, in the end they invoke HEVEA internal commands.
Other LATEX constructs, such as
LATEX key constructs or HEVEA internal commands (see section 8.3),
that require special processing are defined
in HEVEA 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 \newcommand
for instance.
Most of the problems that occur during the translation of a given
LATEX file (say trouble.tex
) 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
trouble.hva) given as
argument to HEVEA.
# hevea trouble.hva trouble.tex
By doing so, the macros written specially for HEVEA are not
seen by LATEX. Even better, trouble.tex
is not changed
at all.
A worth-mentiong alternative is inserting \usepackage{trouble}
in the document preamble. Then, given HEVEA semantics for
\usepackage
(see Section B.5.2),
HEVEA-specific commands should be placed in
the file “trouble.hva” file, while LATEX-specific commands
should be placed in teh file “trouble.sty”.
Of course, adapting a document to HEVEA processing will be easier if the LATEX source is written in a generic style, using macros. Note that this style is recommended anyway, since it facilitates document maintenance.
Consider the following LATEX source excerpt:
You can \raisebox{.6ex}{\em raise} text.
LATEX typesets this as follows:
Since HEVEA does not know about \raisebox
,
it incorrectly processes this input. More precisely,
it first prints a warning message:
trouble.tex:34: Unknown macro: \raisebox
Then, it goes on by translating the arguments of \raisebox
as if
they were normal text. As a
consequence some .6ex
is finally found in the html output:
You can .6exraise text.
To correct this, you should provide a macro that has more or less the effect of
\raisebox
. It is impossible to write a generic
\raisebox
macro for HEVEA, because of html limitations.
However, in this case, the effect
of \raisebox
is to raise the box a little.
Thus, the first, numerical, argument to \raisebox
can be
ignored in a private \raisebox
macro defined in trouble.hva:
\newcommand{\raisebox}[2]{$^{\mbox{#2}}$}
Now, translating the document yields:
You can raise text a little.
Of course, this will work only when all \raisebox
commands in
the document raise text a little. Consider, the following
example, where text
is both raised a lowered a little:
You can \raisebox{.6ex}{\em raise} or \raisebox{-.6ex}{\em lower} text.
Which LATEX renders as follows:
Whereas, with the above definition of \raisebox
, HEVEA produces:
You can raise or lower text.
A solution is to add a new macro definition in the trouble.hva
file:
\newcommand{\lowerbox}[2]{$_{\mbox{#2}}$}
Then, trouble.tex
itself has to be modified a little.
You can \raisebox{.6ex}{\em raise} or \lowerbox{-.6ex}{\em lower} text.
HEVEA now produces a satisfying output:
You can raise or lower text.
Note that, for the document to remain LATEX-processable,
it should also contain the following definition for
\lowerbox
:
\newcommand{\lowerbox}[2]{\raisebox{#1}{#2}}
This definition can safely be placed anywhere in trouble.tex,
since by HEVEA semantics for \newcommand
(see
section B.8.1)
the new definition will not overwrite the old one.
Sometimes HEVEA 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, HEVEA does its best to issue warnings when such situations are likely to occur.
Consider, for instance, this definition of \blob
as a small
black square.
\newcommand{\blob}{\rule[.2ex]{1ex}{1ex}} \blob\ Blob \blob
Which LATEX typesets as follows:
HEVEA always translates \rule
as <hr>
, ignoring size
arguments.
Hence, it produces the following, wrong, output:
Blob
We may not be particularily commited to a square blob.
In that case, other small symbols would perfectly do the job
of \blob
, such as a bullet (\bullet
).
Thus, you may choose to give \blob
a definition in
trouble.hva
:
\newcommand{\blob}{\bullet}
This new definition yields the following, more satisfying output:
• Blob •
In case we do want a square blob, there are two alternatives.
We can have LATEX typeset some subparts of
the document and then to include them as images, section 6
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 \blob
as a numerical
character reference. Here, the character U+02588
seems ok.
\newcommand{\blob}{\@print@u{X2588}}
█ Blob █
However, beware that not all browsers display all of Unicode…
HEVEA failure may have many causes, including a bug. However, it may also stem from a wrong LATEX input. Thus, this section is to be read before reporting a bug…
In the following source, environments are not properly balanced:
\begin{flushright} \begin{quote} This is right-flushed quoted text. \end{flushright} \end{quote}
Such a source will make both LATEX and HEVEA choke. HEVEA issues the following error message that shows the LATEX environment that is not closed properly:
./trouble.tex:6: Environment nesting error: html: 'DIV' closes 'BLOCKQUOTE' ./trouble.tex:4: Latex environment 'quote' is pending Adios
Thus, when HEVEA crashes, it is a good idea to check that the input is correct by running LATEX on it.
Unfortunately, HEVEA may crash on input that does not affect LATEX. Such errors usually relate to environment or group nesting.
Consider for instance the following “optimized” version of a
quoteright
environment:
\newenvironment{quoteright}{\quote\flushright}{\endquote} \begin{quoteright} This a right-flushed quotation \end{quoteright}
The \quote
and \flushright
constructs
are intended to replace
\begin{quote}
and \begin{flushright}
,
while \endquote
stands for \end{quote}
.
Note that the closing \endflushright
is omitted, since it does nothing.
LATEX accepts such an input and produces a right-flushed quotation.
However, HEVEA usually translates LATEX environments to html
block-level elements and it requires
those elements to be nested properly.
Here, \quote
translates to <blockquote>
,
\flushright
translates to <div class="flushright">
and
\endquote
translates to </blockquote>
.
At that point, HEVEA refuses to generate obviously
non-correct html and it crashes:
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
Also notice that the error message above includes a backtrace showing the call-chain of commands.
In this case, the solution is easy: environments must be opened and closed consistently. LATEX style being recommended, one should write:
\newenvironment{quoteright} {\begin{quote}\begin{flushright}} {\end{flushright}\end{quote}}
And we get:
This is a right-flushed quotation
Unclosed LATEX groups ({
…) are another source
of nuisance to HEVEA.
Consider the following horreur.tex file:
\documentclass{article} \begin{document} In this sentence, a group is opened now {\em and never closed. \end{document}
LATEX accepts this file, although it produces a warning:
# 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).
By contrast, running HEVEA on horreur.tex yields a fatal error:
# 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
Thus, users should close opening braces where it belongs. Note that HEVEA error message “Latex environment ’env’ is pending” helps a lot in locating the brace that hurts.
If HEVEA crashes on LATEX source (not on TEX source), then you may have discovered a bug, or this manual is not as complete as it should. In any case, please report to Luc.Maranget@inria.fr.
To be useful, your bug report should include LATEX code that triggers the bug (the shorter, the better) and mention HEVEA version number.
A satisfactory translation from LATEX to html often requires giving instructions to HEVEA. Typically, these instructions are macro definitions and these instructions should not be seen by LATEX. Conversely, some source that LATEX needs should not be processed by HEVEA. Basically, there are three ways to make input vary according to the processor, file loading, the hevea package and comments.
HEVEA and LATEX treat files differently. Here is a summary of the main differences:
\input
, however when given the option -e
filename,
HEVEA does not load filename.
\documentstyle
and as arguments to \usepackage
,
but the files are searched by following different methods and
considering different file extensions.
As a consequence, for having a file latexonly loaded by
LATEX only, it suffices
to use \input{
latexonly}
in the source and to invoke HEVEA as follows:
# hevea
-e latexonly…Having heveaonly loaded by HEVEA only is more simple: it suffices to invoke HEVEA as follows:
# hevea
heveaonly…Finally, if one has an HEVEA equivalent style.hva for a LATEX style file style.sty, then one should load the file as follows:
\usepackage{
style}
This will result in, LATEX loading style.sty, while HEVEA loads style.hva. As HEVEA will not fail in case style.hva does not exist, this is another method for having a style file loaded by LATEX only.
Writing an HEVEA-specific file file.hva is the method of choice for supplying command definitions to HEVEA only. Users can then be sure that these definitions are not seen by LATEX and will not get echoed to the image file (see section 6).
The file file.hva can be loaded by either
supplying the command-line argument
file.hva, or by
\usepackage{
file}
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 file.hva are processed before the
ones from the document and will override them, provided
the document definitions are made using \newcommand
(or
\newenvironment
).
In the \usepackage
case, HEVEA loads file.hva
at the place where LATEX loads file.sty, hence
the definitions from file.hva replace
the definitions from file.sty in the strict sense.
The hevea.sty style file is intended to be loaded by LATEX
and not by HEVEA.
It provides LATEX with means to ignore or process some parts of the
document.
Note that HEVEA copes with the constructs defined in
the hevea.sty file by default.
It is important to notice that the hevea.sty style file from
the distribution is a package in LATEX 2є terms and that it
is not compatible with old LATEX. Moreover, the hevea
package loads the comment package which must be present.
Also notice that, for compatibility,
HEVEA reacts to
\usepackage{hevea}
by loading its own version
of the comment package (Section B.17.6).
HEVEA and LATEX perform the following actions on source inside
the latexonly
, verblatex
, htmlonly
, rawhtml
,
toimage
and verbimage
environments:
environment | HEVEA | LATEX | ||
latexonly | ignore, \end{ env}
constructs are processed (see section 5.2.2) | process | ||
verblatex | ignore | process | ||
htmlonly | process | ignore | ||
rawhtml | echo verbatim (see section 8.4) | ignore | ||
toimage | send to the image file, \end{ env}
constructs and macro characters are processed (see section 6) | process | ||
verbimage | send to the image file (see section 6) | process | ||
As an example, this is how some text can be typeset in purple by HEVEA and left alone by LATEX:
We get: \begin{htmlonly}% \purple purple rain, purple rain% \end{htmlonly} \begin{latexonly}% purple rain, purple rain% \end{latexonly}% \ldots
We get: purple rain, purple rain …
It is impossible to avoid the spurious space in HEVEA output
for the source above.
This extra spaces comes from the newline character that follows
\end{htmlonly}
. Namely this
construct must appear in a line of its own for
LATEX to recognize it. Anyway, better control over spaces
can be achieved
by using the hevea boolean register
or comments, see sections 5.2.3
and 5.3.
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 image and verbimage do not create scope. It takes a little practice of HEVEA to understand why this is convenient.
Some scanning and analysis of source is performed by HEVEA inside the latexonly environment, in order to allow latexonly to dynamically occur inside other environments.
More specifically, \end{
env}
macros
are recognized and their env argument is tested against
the name of the environment whose opening macro \
env
opened the latexonly environment.
In that case, macro expansion of \end
env is performed and
any further occurrence of \end{
env’}
is tested
and may get expanded if it matches a pending
\begin{
env’}
construct.
This enables playing tricks such as:
\newenvironment{latexhuge} {\begin{latexonly}\huge} {\end{latexonly}} \begin{latexhuge} This will appear in huge font in \LaTeX{} output only. \end{latexhuge}
LATEX output will be:
While there is no HEVEA output.
Since HEVEA somehow analyses input that is enclosed in the
latexonly environment,
it may choke.
However, this environment is intended to select processing by
LATEX only and might contain arbitrary source code.
Fortunately, it remains possible to have input processed by LATEX
only, regardless of what it is, by enclosing it in the
verblatex environment.
Inside this environment, HEVEA performs no other action
than looking for \end{verblatex}
. As a consequence,
the \begin{verblatex}
and \end{verblatex}
constructs
may only appear in the main flow of text or inside the same macro body,
a bit like LATEX verbatim environment.
Relations between toimage and verbimage are similar.
Additionally, formal parameters #
i are replaced by
actual arguments inside the toimage environment
(see end of section 6.3 for an example of this feature).
Boolean registers are provided by the ifthen package (see [LATEX, Section C.8.5] and section B.8.5 in this document). Both the hevea.sty style file and HEVEA define the boolean register hevea. However, this register initial value is false for LATEX and true for HEVEA.
Thus, provided, both the hevea.sty style file and the ifthen packages are loaded, the “purple rain” example can be rephrased as follows:
We get: {\ifthenelse{\boolean{hevea}}{\purple}{}purple rain, purple rain}\ldots
We get: purple rain, purple rain…
Another choice is using the TEX-style conditional macro
\ifhevea
(see Section B.16.1.4):
We get: {\ifhevea\purple\fi purple rain, purple rain}\ldots
We get: purple rain, purple rain…
HEVEA processes all lines that start with %HEVEA
, while
LATEX treats these lines as comments.
Thus, this is a last variation on the “purple rain” example:
We get %HEVEA{\purple purple rain, purple rain% %HEVEA}% \ldots
(Note how comments are placed at the end of some lines to avoid spurious spaces in the final output.)
We get: purple rain, purple rain…
Comments thus provide an alternative to loading the
hevea package. For user convenience, comment equivalents to
the latexonly
and toimage
environment are also provided:
environment | comment equivalent | |||
\begin{latexonly} … \end{latexonly} |
| |||
\begin{toimage} … \end{toimage} |
|
Note that LATEX, by ignoring comments, naturally performs the action
of processing text between %BEGIN
… and %END
… comments. However, no environment is opened and closed and no scope is
created while using comment equivalents.
Sometimes, HEVEA just cannot process its input, but it remains acceptable to have LATEX process it, to produce an image from LATEX output and to include a link to this image into HEVEA output. HEVEA provides a limited support for doing this.
While outputting doc.html, HEVEA echoes some of its input to the image file, doc.image.tex. Part of this process is done at the user’s request. More precisely, the following two constructs send text to the image file:
\begin{toimage}
\end{toimage}
%BEGIN IMAGE
%END IMAGE
Additionally, \usepackage
commands, top-level and global
definitions
are automatically echoed to the image file. This enables using
document-specific commands in text above.
Output to the image file builds up a current page, which is flushed
by the \imageflush
command.
This command has the following effect: it outputs a strict page break
in the image file, increments the image counter and
output a <img src="
pagename.png">
tag in HEVEA
output file, where pagename is build from the image counter
and HEVEA output file name.
Then the imagen
script has to be run by:
# imagen
doc
This will process the doc.image.tex file through LATEX, dvips, ghostscript and a few others tools, which must all be present (see section C.4.1), finally producing one pagename.png file per page in the image file.
The usage of imagen
is described at
section C.1.5. Note that imagen is a simple shell
script. Unix users can pass hevea the command-line option
-fix. Then hevea will
itself call imagen, when appropriate.
Consider the “blob” example from section 4.2. Here is the active part of a blob.tex file:
\newcommand{\blob}{\rule[.2ex]{1ex}{1ex}} \blob\ Blob \blob
This time, we would like \blob
to produce a small black square, which
\rule[.2ex]{1ex}{1ex}
indeed does in LATEX.
Thus we can write:
\newcommand{\blob}{% \begin{toimage}\rule[.2ex]{1ex}{1ex}% \end{toimage}% \imageflush} \blob\ Blob \blob
Now we issue the following two commands:
# hevea blob.tex # imagen blob
And we get:
Blob
![]()
Observe that the trick can be used to replace missing symbols by small
.png 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 \savebox
, but the other problems remain.
In this section, a technique to transform included Postscript images into included bitmap images is described. Note that this technique is used by HEVEA implementation of the graphics package (see section B.14.1), which provides a more standard manner to include Postscript images in LATEX documents.
Included images are easy to manage: it suffices to let LATEX do the job. Let round.ps be a Postscript file, which is included as an image in the source file round.tex (which must load the epsf package):
\begin{center} \epsfbox{round.ps} \end{center}
Then, HEVEA can have this image translated into a inlined (and centered) .png image by modifying source as follows:
\begin{center} %BEGIN IMAGE \epsfbox{round.ps} %END IMAGE %HEVEA\imageflush \end{center}
(Note that the round.tex file
still can be processed by LATEX, since comment equivalents
of the toimage environment are used and that
the \imageflush
command is inside
a %HEVEA
comment — see section 5.3.)
Then, processing round.tex through HEVEA and imagen yields:
It is important to notice that things go smoothly because the
\usepackage{epsf}
command gets echoed to the
image file. In more complicated cases, LATEX may fail
on the image file because it does not load the right
packages or define the right macros.
However, the above solution implies modifying the original LATEX
source code.
A better solution is to define the \epsfbox
command, so that HEVEA echoes \epsfbox
and its argument to
the image file and performs \imageflush
:
\newcommand{\epsfbox}[1]{% \begin{toimage} \epsfbox{#1} \end{toimage} \imageflush}
Such a definition must be seen by HEVEA only. So, it is best put
in a separate file whose name is given as an extra argument on
HEVEA command-line (see section 5.1).
Putting it in the document source
protected inside an %HEVEA
comment is a bad idea, because it might then get echoed to the image file
and generate trouble when LATEX is later run by imagen.
Observe that the above definition of \epsfbox
is a definition
and not a redefinition (i.e. \newcommand
is used and not
\renewcommand
),
because HEVEA does not know about \epsfbox
by default.
Also observe that this not a recursive definition, since
commands do not get expanded inside the toimage
environment.
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 8.2 for a description of this more adequate technique.
Some programs extend LATEX capabilities using a filter principle. In such a scheme, the document contains source fragments for the program. A first run of the program on LATEX source changes these fragments into constructs that LATEX (or a subsequent stage in the paper document production chain, such as dvips) can handle. Here again, the rule of the game is keeping HEVEA away from the normal process: first applying the filter, then making HEVEA send the filter output to the image file, and then having imagen do the job.
Consider the gpic filter, for making drawings.
Source for gpic is enclosed in .PS
….PE
,
then the result is available to subsequent LATEX source as a TEX
box \box\graph
.
For instance the following source, from a smile.tex file,
draws a “Smile!” logo as a centered
paragraph:
.PS ellipse "{\Large\bf Smile!}" .PE \begin{center} ~\box\graph~ \end{center}
Both the image description (.PS
… .PE
) and usage (\box\graph
)
are for the image file, and they should be
enclosed by %BEGIN IMAGE
… %END IMAGE
comments.
Additionally, the image link is put where it belongs by an
\imageflush
command:
%BEGIN IMAGE .PS ellipse "{\Large\bf Smile!}" .PE %END IMAGE \begin{center} %BEGIN IMAGE ~\box\graph~ %END IMAGE %HEVEA\imageflush \end{center}
The gpic filter is applied first, then come hevea and imagen:
# gpic -t < smile.tex > tmp.tex # hevea tmp.tex -o smile.html # imagen smile
And we get:
Observe how the -o
argument to HEVEA is used and that
imagen argument is HEVEA output basename (see
section C.1.1.2 for the full definition of HEVEA output basename).
In the gpic 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 gpic pictures in LATEX:
\newenvironment{centergpic}{}{\begin{center}~\box\graph~\end{center}}
Source code will now be as follows:
\begin{centergpic} .PS ellipse "{\Large\bf Smile!}" .PE \end{centergpic}
HEVEA will process this source correctly, provided it is given its
own definition for the centergpic
environment beforehand:
\newenvironment{centergpic} {\begin{toimage}} {\box\graph\end{toimage}\begin{center}\imageflush\end{center}}
Assuming that the definition above is in a smile.hva file, the command sequence for translating smile.tex now is:
# 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
The warnings above are normal: they are issued when HEVEA runs
across the LATEX-intended definition of the centergpic
environment and refuses to override its own definition for that
environment.
HEVEA outputs a single .html file. This file can be cut into pieces at various sectional units by HACHA
First generate your html document by applying HEVEA:
Then cut doc.html into pieces by the command:
This will generate a simple root file index.html. 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 section in the article style and chapter in the book style. The name of those files are doc001.html, doc002.html, etc.
Additionally, one level of sectioning below the cutting unit (i.e. subsections in the article style and sections in the book style) is shown as an entry in the table of contents. Sectional units above the cutting section (i.e. parts in both article and book styles) close the current table of contents and open a new one. Cross-references are properly handled, that is, the local links generated by HEVEA are changed into remote links.
The name of the root file can be changed using the
-o
option:
Some of HEVEA output get replicated in all the files generated by HACHA. Users can supply a header and a footer, which will appear at the begining and end of every page generated by HACHA. It suffices to include the following commands in the document preamble:
\htmlhead{
header}
\htmlfoot{
footer}
HACHA also makes every page it generates a clone of its input as
regards attributes to the <body ...>
opening tag and
meta-information from the <head>
… <\head>
block. See section B.2 for examples of this replication
feature.
By contrast, style information specified in the style
elements
from rom the <head>
… <\head>
block is not replicated. Instead, all style definitions are collected into an
external style sheet file whose name is doc.css,
and all generated html files adopt doc.css as
an external style sheet.
It is important to notice that, since version 1.08, HEVEA produces
a style
element by itself, even if users do not explicitely
use styles. As a consequence,
HACHA normally produces a
file doc.css, which should not be forgotten while
copying files to their final destination after a run of HACHA.
HACHA behaviour can be altered from the document source, by using a counter and a few macros.
A document that explicitly includes cutting macros still can be typeset by
LATEX, provided it loads the
hevea.sty style file from the HEVEA distribution.
(See section 5 for details on this style file).
An alternative to loading the hevea package is to put
all cutting instructions in comments starting with %HEVEA
.
HACHA recognizes all sectional units, ordered as follows, from top to bottom: part, chapter, section, subsection, subsubsection, paragraph and subparagraph.
At any point between \begin{document}
and
\end{document}
,
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.
At document start, the root file and the output file are HACHA output file (i.e. index.html). The cutting unit and the cutting depth are set to default values that depend on the document style.
The following cutting instructions are for use in the document preamble. They command the cutting scheme of the whole document:
\renewcommand{\cuttingunit}{
secname}
.
\setcounter{cuttingdepth}{
numvalue}
.
A cutting depth of zero means no other entries than the cutting units
in the table of contents.
Other cutting instructions are to be used after
\begin{document}
. They all generate html comments in HEVEA
output.
These comments then act as instructions to HACHA.
\cuthere
appears.
\cutdef
. The cutting unit and cutting depth are
restored.
Note that \cutdef
and \cutend
must be properly balanced.
Commands \cuthere
and \cutend
have starred variants,
which behave identically except for footnotes (see 7.3.6).
Default settings work as follows:
\begin{document}
performs
\cutdef*[\value{cuttingdepth}]{\cuttingunit}
and \end{document}
performs \cutend*
.
All sectioning commands perform \cuthere
,
with the sectional unit name as first argument and the (optional, if
present) sectioning
command argument (i.e. the section title) as second argument.
Note that starred versions of the sectioning commands also perform
cutting instructions.
A table of links generated by HACHA 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.
More precisely, let A be a certain sectional unit (e.g. “part”), let B be just below A (e.g. “section”), and let C be just below C (e.g. “subsection”). Further assume that cutting is performed at level B with a depth of more than one. Then, every unit A holds a one or several tables of links to generated files, and each generated file normally holds a B unit. Sublists with links to C units inside B units normally appear in the tables of links of level A. The command-line options -tocbis and -tocter instruct hacha to put sublists at other places. With -tocbis sublists are duplicated at the beginning of the B level files; while with -tocter sublist only appear at the beginning of the B level files.
In my opinion, default style is appropriate for documents with short B units; while -tocbis style is appropriate for documents with long B units with a few sub-units; and -tocter style is appropriate for documents with long B units with a lot of sub-units. As you may have noticed, this manual is cut by following the -tocbis style.
Whatever the style is, if a B unit is cut
(e.g. because its text is enclosed in
\cutdef{
C}
… \cutend
),
then every C unit goes into its own file and there is no sublist
after the relevant B level entry in the A level table of links.
Consider, for instance, a book document with a long chapter that you want to cut at the section level, showing subsections:
\chapter{A long chapter} ..... \chapter{The next chapter}
Then, you should insert a \cutdef
at chapter start and a
\cutend
at chapter end:
\chapter{A long chapter} %HEVEA\cutdef[1]{section} ..... %HEVEA\cutend \chapter{The next chapter}
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 \section
already
performs the appropriate \cuthere{section}{...}
commands,
which were ignored by default.
(Also note that cutting macros are placed inside %HEVEA
comments,
for LATEX not to be disturbed).
The \cuthere
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:
\documentclass{article} \begin{document} \begin{abstract} A big abstract \end{abstract} ...
Then, you make the abstract go to its own file as it was a cutting unit by typing:
\documentclass{article} \usepackage{hevea} \begin{document} \cuthere{\cuttingunit}{Abstract} \begin{abstract} A big abstract \end{abstract} ...
(Note that, this time, cutting macros appear unprotected in the source. However, LATEX still can process the document, since the hevea package is loaded).
In some situations it may be appropriate to produce many
pages from one source files.
More specifically, loading the deepcut package will put
all sectioning units of your document (from \part
to
\subsection
in their own file.
Similarly, loading the figcut package will make all figures and tables go into their own file. The figcut package accepts two options, show and noshow. The former, which is the default, instructs HEVEA to repeat the caption into the main flow of text, with a link to the figure. The latter option disables the feature.
In this section we show how to alter some details of HACHA behaviour. This includes controlling output file names and the title of generated web pages and introducing arbitrary cuts.
When invoked as hacha doc.html,
HACHA produces a index.html table of links file that
points into doc001.html,
doc002.html, etc. content files.
This is not very convenient when one wishes to point inside the
document from outside.
However, the \cutname{
name}
command
sets the name of the current output file name as name.
Consider a document cut at the section level, which contains the following important section:
\section{Important\label{important} section} ...
To make the important section goes into file important.html, one writes:
\section{Important\label{important} section}\cutname{important.html} ...
Then, section “Important section” can be referenced from an HEVEA unaware html page by:
In this document, there is a very <a href="important.html#important">important section</a>.
If you are reading the html version of this manual, you may check
that you are now reading file cutname.html.
This particular file name has been specified from the source
using \cutname{cutname.html}
.
When HACHA 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 HACHA”.
It is possible to insert some text at the beginning of all page
titles, by using the \htmlprefix
command.
Hence, by writing
\htmlprefix{\hevea{} Manual: }
in the document,
the title of this page would become:
“HEVEA Manual: Cutting your document into pieces with HACHA”
and the title of all other pages would show the same prefix.
The command \toplinks{
prev}{
up}{
next}
instructs HACHA to put links to a
“previous”, “up” and “next” page in the root file.
The following points are worth noticing:
\toplink
command must appear in the document preamble
(i.e. before \begin{document}
).
This feature can prove useful to relate documents that are generated independently by HEVEA and HACHA.
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
\setlinkstext{
prev}{
up}{
next}
,
where prev, up and next are some LATEX
source.
For instance the default behaviour is equivalent to:
\setlinkstext {\imgsrc[alt="Previous"]{previous_motif.svg}} {\imgsrc[alt="Up"]{contents_motif.svg}} {\imgsrc[alt="Next"]{next_motif.svg}}
Command \setlinkstext
behaves as \toplinks
does.
That is, it must occur in document preamble, arguments are processed
and empty arguments yield no effect (i.e. defaults apply).
Part of a document goes to a separate file when enclosed in a
cutflow
environment:
\begin{cutflow}{
title}
…\end{cutflow}
The content “…” will go into a file of its own, while the argument title is used as the title of the introduced html page.
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 cutflow
environment.
This will occur naturally when the content of the cutflow
environment.
contains a \label
construct.
This look natural in the following quiz example:
\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}
The example yields:
Answers in section 7.3.5.
However,introducing html hyperlink targets and
references with the \aname
and \ahrefloc
commands
(see section 8.1.1)
will be more practical most of the time.
The starred variant environment
cutflow*
is the same
as cutflow
, save for the html header and footer (see
Section 7.1) which are not replicated in the introduced
page.
Footnote texts (given as arguments either to \footnote
or
\footnotetext
) do not go directly to output.
Instead, footnote texts accumulate internally in a buffer,
awaiting to be flushed.
The flushing of notes is controlled by the means of a current
flushing unit, which is a sectional unit name or
document — a fictional unit above all units.
At any point, the current flushing unit is the value of the
command \@footnotelevel
.
In practice, the flushing of footnote texts is performed by two commands:
\flushdef{
secname}
simply sets
the flushing unit to secname.
\footnoteflush{
secname}
acts
as follows:
The article style file performs \flushdef{document}
,
while the book style file performs \flushdef{chapter}
.
At the end of processing, \end{document}
performs
\footnoteflush{\@footnotelevel}
, so as to flush any pending notes.
Cutting commands interact with footnote flushing as follows:
\cuthere{
secname}
executes \footnoteflush{
secname}
.
Remember that all sectioning commands perform
\cuthere
with their sectional unit name as argument.
\cutdef{
secname}
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 secname
(by performing \flushdef{
secname}
).
\cutend
first flushes any pending texts
(by performing \footnoteflush
with the current flushing unit
as argument), and restores the flushing unit and footnote text buffer saved
by the matching \cutdef
.
\cutdef*
and \cutend*
perform
no operation that is related to footnotes.
Later, when running across footnote texts in its input file, HACHA
sometimes put notes in a separate file.
More precisely, HACHA has knowledge of the
current cutting level, the current sectional unit where
cuts occur — as given by the relevant \cutdef
.
Moreover, HACHA knows the current section level —
that is, the last sectional command processed.
Besides, HACHA extracts the note level from the comments
that surround the notes (as given by the command
\footnoteflush
that produced the notes).
Then, HACHA 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
(e.g. the current level is document while the cutting
level is chapter).
As a result, notes should stay where they are when they occur at the end of
HACHA output file and otherwise go to a separate file.
To make a complicated story even more complicated,
footnotes in minipage environments or in the arguments
to \title
or \author
have a different, I guess satisfactory,
behaviour.
Given the above description, footnotes are managed by default as follows.
In case you wish to adopt a book-like behaviour for
an article (footnotes at the end of sections),
it suffices to insert \flushdef{section}
in the document
preamble.
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 \cutdef{subsubsection}
/\cutend
pair.
As a result the text of footnotes appear at the end of the
subsubsection pages.
A note in a subsubsection, flushed at subsubsections.1
Another note in a subsubsection, flushed at subsubsections.2
The following two subsubsections are sent to their own files by
the means of a \cutdef*{subsubsection}
/\cutend*
pair.
As a result, the text of footnotes in the subsections appear
at the end of the current section page.3
A note in a subsubsection, flushed at sections.4
Another note in a subsubsection, flushed at sections.5
Finally, to send the footnotes in subsubsections
to a separate web page, one should use
a \cutdef{subsubsection}
/\cutend
pair
(to create a proper buffer for subsubsection notes),
redefine the flushing unit, and flush notes explicitly.
\cutdef{subsubsection}\flushdef{document}% \subsubsection{...} ... \footnoteflush{document}\cutend
A note in a subsubsection flushed at document level.6
Another note in a subsubsection at document level.7
HEVEA output language being html, it is normal for users to insert hypertext constructs their documents, or to control colours.
HEVEA 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 HEVEA internals.
A few commands for hyperlink management and included images are provided, all these commands have appropriate equivalents defined by the hevea package (see section 5.2). Hence, a document that relies on these high-level commands still can be typeset by LATEX, provided it loads the hevea package.
Macro | HEVEA | LATEX | |
\ahref{ url}{ text} | make text an hyperlink to url | echo text | |
\footahref{ url}{ text} | make text an hyperlink to url | make url a footnote to text, url is shown in typewriter font | |
\ahrefurl{ url} | make url an hyperlink to url. | typeset url in typewriter font | |
\ahrefloc{ label}{ text} | make text an hyperlink to label inside the document | echo text | |
\aname{ label}{ text} | make text an hyperlink target with label label | echo text | |
\mailto{ address} | make address a “mailto” link to address | typeset address in typewriter font | |
\imgsrc[ attr]{ url} | insert url as an image, attr are attributes in the html sense | do nothing | |
\home{ text} | produce a home-dir url both for output and links, output aspect is: “~text” |
It is important to notice that all arguments
are processed.
For instance, to insert a link to
my home page, (http://pauillac.inria.fr/~maranget/index.html
),
you should do something like this:
\ahref{http://pauillac.inria.fr/\home{maranget}/index.html}{his home page}
Given the frequency of ~
, #
etc. in urls,
this is annoying. Moreover, the immediate solution, using \verb
,
\ahref{\verb" ... /~maranget/..."}{his home page}
does not work, since LATEX forbids verbatim formatting
inside command arguments.
Fortunately, the url package provides a very convenient
\url
command that acts like \verb
and can appear in
other command arguments
(unfortunately, this is not the full story, see section B.17.11).
Hence, provided the url package is loaded,
a more convenient reformulation of the example above is:
\ahref{\url{http://pauillac.inria.fr/~maranget/index.html}}{his home page}
Or even better:
\urldef{\lucpage}{\url}{http://pauillac.inria.fr/~maranget/index.html} \ahref{\lucpage}{his home page}
It may seem complicated, but this is a safe way to have a document processed both by LATEX and HEVEA. 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, HEVEA (optionally) depends on only one third party package: url, which is as correct as it can be and well-written.
In case the \url
command is undefined
at the time \begin{document}
is processed, the commands
\url
, \oneurl
and \footurl
are defined as
synonymous for
\ahref
, \ahrefurl
and \footahref
, thereby
ensuring
some compatibility with older versions of HEVEA.
Note that this usage of \url
is deprecated.
Specifying colours both for LATEX and HEVEA should be done using the color package (see section B.14.2). However,one can also specify text color using special type style declarations. The hevea.sty style file define no equivalent for these declarations, which therefore are for HEVEA consumption only.
Those declarations follow html conventions for colours. There are sixteen predefined colours:
\black ,
\silver ,
\gray ,
\white ,
\maroon ,
\red ,
\fuchsia ,
\purple ,
\green ,
\lime ,
\olive ,
\yellow ,
\navy ,
\blue ,
\teal ,
\aqua
|
Additionally, the current text color can be
changed by the declaration \htmlcolor{
number}
,
where number is a six digit hexadecimal number specifying a
color in the RGB space. For instance, the declaration
\htmlcolor{404040}
changes font color to dark gray,
The \imgsrc
command becomes handy when one has images both in
Postscript and GIF (or PNG or JPG) format. As explained in
section 6.3, Postscript images can be included in
LATEX documents by using the \epsfbox
command from the
epsf package. For instance, if screenshot.ps is an
encapsulated Postscript file, then a doc.tex document can
include it by:
\epsfbox{screenshot.ps}
We may very well also have a GIF version of the screenshot image
(or be able to produce one easily using image converting tools),
let us store it in a screenshot.ps.gif file.
Then, for HEVEA to include a link to the GIF image in its
output, it suffices
to define the \epsfbox
command in the macro.hva file
as follows:
\newcommand{\epsfbox}[1]{\imgsrc{#1.gif}}
Then HEVEA has to be run as:
# hevea macros.hva doc.tex
Since it has its own definition of \epsfbox
, HEVEA will
silently include a link the GIF image and not to the Postscript image.
If another naming scheme for image files is preferred, there are
alternatives.
For instance, assume that Postscript files are of the kind
name.ps, while GIF files are of the kind
name.gif.
Then, images can be included using
\includeimage{
name}
, where
\includeimage
is a specific user-defined command:
\newcommand{\includeimage}[1]{\ifhevea\imgsrc{#1.gif}\else\epsfbox{#1.ps}\fi}
Note that this method uses the hevea boolean register (see section 5.2.3). If one does not wish to load the hevea.sty file, one can adopt the slightly more verbose definition:
\newcommand{\includeimage}[1]{% %HEVEA\imgsrc{#1.gif}% %BEGIN LATEX \epsfbox{#1.ps} %END LATEX }
When the Postscript file has been produced by
translating a bitmap file, this simple method of making a bitmap image and
using the \imgsrc
command
is the most adequate.
It should be preferred over using the more automated image file
mechanism (see section 6),
which will translate the image back from
Postscript to bitmap format and will thus degrade it.
In this section a few of HEVEA internal macros are described. Internal macros occur at the final expansion stage of HEVEA and invoke Objective Caml code.
Normally, user source code should not use them, since their behaviour may change from one version of HEVEA to another and because using them incorrectly easily crashes HEVEA. However:
The general principle of HEVEA is that LATEX environments
\begin{
env}
…
\end{
env}
get
translated into html block-level elements <
block
attributes>
… </
block>
.
More specifically, such block level elements are opened by the
internal macro \@open
and closed by the internal macro
\@close
.
As a special case, LATEX groups {
… }
get translated into html groups, which are shadow block-level
elements with neither opening nor closing tag.
In the following few paragraphs, we sketch the interaction of
\@open
…\@close
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.
Paragraphs are rendered by p
elements, which are opened and
closed automatically.
More specifically, a first p
is opened after
\begin{document}
, then paragraph breaks close the active
p
and open a new one.
The final \end{document}
closes the last p
.
In any occasion, paragraphs consisting only of space characters
are discarded silently.
Following html “normative reference [HTML-5a]”, block-level
elements cannot occur inside p
; more precisely,
block-level opening tags implicitly close any active p
.
As a consequence,
HEVEA closes the active p
element when it processes
\@open
and opens a new p
when it processes the matching
\@close
.
Generally, no p
element is opened by default inside block-level
elements, that is, HEVEA does not immediately open p
after having
processed \@open
.
However, if a paragraph break occurs later, then a new p
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 p
element.
That alone probably prevents the consistent styling
of paragraphs with style sheets.
Groups behave differently, opening or closing them does
not close nor open p
elements.
However, processing paragraph breaks inside groups involves temporarily
closing all groups up to the nearest enclosing p
, closing it,
opening a new p
and finally re-opening all groups.
Opening a block-level element inside a group, similarly
involves closing the active p
and opening a new p
when the matching \@close
is processed.
Finally, display mode (as introduced by $$
) is also
complicated. Displays basically are table
elements with one row
(tr
), and HEVEA manages to introduce table cells (td
)
where appropriate. Processing \@open
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 \@close
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.
It is important to notice that primitive arguments are
processed (except for the \@print
primitive, and for some of
the basic style primitives). Thus,
some characters cannot be given directly (e.g. #
and
%
must be given as \#
and \%
).
SIZE=3 HOSHADE
), while width and
height are length arguments given in the LATEX style
(e.g. 2pt
or .5\linewidth
).
\@open
and \@close
must be properly balanced.
p
element,
that is if a <p>
opening tag is active,
\@out@par
first closes it (by emitting </p>
),
then formats arg, and then re-open a p
element.
Otherwise \@out@par
simply formats arg.
This command is adequate when
formatting arg produces block-level elements.
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 LATEX “text-style declarations” — namely,
\itshape
, \em
etc.
Block-level elements (and html groups)
delimit the effect of such declarations.
span
(with given attributes)
as active.
The text-level element span
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 span
before them, and re-opening span
(with given attributes)
inside them.
The following text-level constructs exhibit similar behaviour with respect
to block-level elements.i
, tt
, etc.;
warning:most of font style elements are depreciated in html5,
and some of them are no longer valid, prefer CSS in span
tags)
or phrase elements (em
, etc.) in the html terminology.\@span
and \@style
,
as both a text-level element name name and attributes are specified.
More specifically,
\@span{
attr}
can be seen as a shorthand for
\@styleattr{span}{
attr}
;
while
\@style{
name}
can be seen as
a shorthand for
\@styleattr{
name}{}
.span
with attribute
style="font-size:
font-size"
as active.
The argument
int must be a small integer in the range
1,2, … , 7.
hevea computes font-size, a CSS fontsize value,
from int.
More specifically, font-size will
range from x-small
to 120%
included in
a xx-large
, 3 being the default size medium
.
Notice that \@fontsize
is deprecated in favour of
\@span
with proper fontsize declarations:
\@span{style="font-size=xx-small"}
,
\@span{style="font-size=x-small"}
,
\@span{style="font-size=small"}
,
etc.span
with attribute
"style=
color"
as active.
The argument color must be a color attribute value in the html
style. That is either one of the sixteen conventional colours
black
, silver
etc, or a RGB hexadecimal color specification
of the form
#
XXXXXX.
Note that the argument color is processed, as a consequence
numerical color arguments should be given as \#
XXXXXX.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 “style” attributes of html elements, most noticeably
of the span elements.
For instance, to get italics in old versions of html one used
the text-level “i” element as in
<i>
…</i>
. Now, for the same results of getting
italics one may write:
<span style="font-style:italic">
…</span>
.
An indeed hevea styles text in that manner,
starting from version 2.00.
Such (verbose) declarations are then abstracted into style class declarations
by HEVEA optimiser esponja, which is invoked by hevea
when given option “-O”.
Notice that style attributes can be given to elements other than span.
However, combining style attributes requires a little care as only one style
attribute is allowed.
Namely <cite style="font-weight:bold" style="color:red">
is illegal and should be written
<cite style="font-weight:bold;color:red">
.
For instance:
Das Kapital.
The command \@addtyle
can be handy for adding style to
already style elements:
style
attribute is added if necessary. Examples:
\@addstyle{color:red}{href="#"}
will produce
href="#" style="color:red"
, and
\@addstyle{color:red}{href="#" style="font-style:italic"}
will
produce href="#" style="font-style:italic;color:red"
. Note
that an unnecessary extra space can be added in some cases.
As an example, consider the following definition of a command for typesetting citation in bold, written directly in html:
\newcommand{\styledcite}[2][] {{\@styleattr{cite}{\@addstyle{#1}{style="font-weight:bold"}}#2}}
The purpose of the optional argument is to add style to specific citations, as in:
Two fundamental works: \styledcite{The Holy Bible} and \styledcite[color:red]{Das Kapital}.
We get: Two fundamental works: The Holy Bible and Das Kapital.
Notice that the example is given for illustrating the usage of the
\@addstyle
macros, which is intended for package writers.
A probably simpler way to proceed would be to use
LATEX text-style declarations:
\newcommand{styledcite}[2][]{{\@style{cite}#1\bf{}#2}} Two fundamental works: \styledcite{The Holy Bible} and \styledcite[\color{red}]{Das Kapital}.
We get: Two fundamental works: The Holy Bible and Das Kapital.
Any text enclosed between \begin{rawhtml}
and
\end{rawhtml}
is echoed verbatim into the html output file.
Similarly, \rawhtmlinput{
file}
echoes the
contents of file file.
In fact, rawhtml
is the environment counterpart of the
\@print
command, but experience showed it to be much more
error prone.
When HEVEA was less sophisticated then it is now, rawhtml was quite convenient. But, as time went by, numerous pitfalls around rawhtml showed up. Here are a few:
é
or é
for é.\begin{rawhtml}<table>\end{rawhtml}
…
\begin{rawhtml}</table>\end{rawhtml}
is
dangerous, because HEVEA is not informed about opening and closing
the block-level element table. In that case, one should use
the internal macros \@open
and \@close
.\begin{rawhtml}
text\end{rawhtml}
fragments that
contain block-level elements will almost certainly mix poorly with
p
elements (introduced by paragraph breaks) and with active
style declaration (introduced by, for instance, \it
).
Safe usage will most of the time means using the internal macros
\@nostyle
and \@out@par
.As a conclusion, do not use the rawhtml environment! A much safer option is to use the htmlonly environment and to write LATEX code. For instance, in place of writing:
\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}
One can write:
\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}
A list of links:
If HEVEA is targeted to text or info files (see
Section 11).
The text inside rawhtml environments is ignored.
However there exists a rawtext environment (and a
\rawtextinput
command) to echo text verbatim in text or info
output mode.
Additionally, the raw environment and a \rawinput
command echo their contents verbatim, regardless of HEVEA output
mode. Of course, when HEVEA produces html,
the latter environment and command suffer from
the same drawbacks as rawhtml.
As a first example of using internal macros, consider the following
excerpt from the hevea.hva file that
defines the center
environment:
\newenvironment{center}{\@open{div}{style="text-align:center"}}{\@close{div}}
Notice that the code above is no longer present and is given here
for explanatory purpose only.
Now HEVEA uses style-sheets and the actual definition of the
center
environment is as follows:
\newstyle{.center}{text-align:center;margin-left:auto;margin-right:auto;}% \setenvclass{center}{center}% \newenvironment{center} {\@open{div}{\@getprint{class="\getenvclass{center}"}} {\@close{div}}%
Basically environments \begin{center}
…\end{center}
will, by
default, be translated into blocks
<div class="center">
…</div>
.
Additionally, the style class associated to center
environments
is managed through an indirection, using the
commands \setenvclass
and \getenvclass
.
See section 9.3 for more explanations.
Another example is the definition of the \purple
color declaration (see section 8.1.2):
\newcommand{\purple}{\@fontcolor{purple}}
HEVEA 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:
\renewcommand{\em}{\@styleattr{em}{style="text-decoration:blink"}}
Here is an example of this questionable blinking feature:
Then, here is the definition of a simplified \imgsrc
command (see section 8.1.1), without its optional argument:
\newcommand{\imgsrc}[1] {\@print{<img src="}\@getprint{#1}\@print{">}}
Here, \@print
and \@getprint
are used to output
html text, depending upon whether this text requires processing or not.
Note that \@open{img}{src="#1"}
is not correct,
because the element img
consists in a single tag, without a
closing tag.
Another interesting example is the definition of the command
\@doaelement
,
which HEVEA uses internally to output A elements.
\newcommand{\@doaelement}[2] {{\@nostyle\@print{<a }\@getprint{#1}\@print{>}}{#2}{\@nostyle\@print{</a>}}
The command \@doaelement
takes two arguments: the first
argument contains the opening tag attributes; while the second element is
the textual content of the A
element.
By contrast with the \imgsrc
example above,
tags are emitted inside groups where styles are cancelled by using the
\@nostyle
declaration.
Such a complication is needed, so as to avoid breaking proper nesting
of text-level elements.
Here is another example of direct block opening. The bgcolor environment from the color package locally changes background color (see section B.14.2.1). This environment is defined as follows:
\newenvironment{bgcolor}[2][style="padding:1em"] {\@open{table}{}\@open{tr}{}% \@open{td}{\@addstyle{background-color:\@getcolor{#2}}{#1}}} {\@close{td}\@close{tr}\@close{table}}
The bgcolor environment operates by opening a html table
(table
) with only one row (tr
) and cell (td
) 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.
The one cell background color is forced with a background-color
property in a style
attribute.
Note that the mandatory argument to \begin{bgcolor}
is the
background color expressed as a high-level color, which therefore
needs to be translated into a low-level color by using the
\@getcolor
internal macro from the color package.
Additionally, \begin{bgcolor}
takes html attributes
as an optional argument. These attributes are the ones of the
table
element.
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 \@print@u
command.
For instance, “blackboard sigma” is Unicode U+02140 (hexa).
Hence you can define the command \bbsigma
as follows:
\newcommand{\bbsigma}{\@print@u{X2140}}
Then, “\bbsigma
” will output “⅀”
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.
To account for that fact, html pages usually specify a document charset that defines a translation from a flow of bytes to a flow of characters. For instance, the byte 0xA4 means Unicode 0x00A4 (¤) in the ISO-8859-1 (or latin1) encoding, and 0x20AC (€) in the ISO-8859-15 (or latin9) encoding. Notice that HEVEA has no difficulty to output both symbols, in fact they are defined as Unicode characters:
\newcommand{\textcurrency}{\@print@u{XA4}} \newcommand{\texteuro}{\@print@u{X20AC}}
But the \@print@u
command may output the specified character as
a byte, when possible, by the means of the output translator.
If not possible, \@print@u
outputs a numerical character
references (for instance €
).
Of course, the document charset and the output translator
must be synchronised. The command \@def@charset
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 ISO-8859-n where n is a
number in 1…15,
KOI8-R, US-ASCII (the
default),
windows-n where n is
1250, 1251, 1252 or 1257,
or macintosh, or UTF-8.
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 US-ASCII works everywhere!
Input encoding of source files is another, although
related, issue — see Section B.17.4.
If wished so, the charset can be extracted from the current locale environment, provided this yields a valid (to HEVEA) charset name. This operation is performed by a companion script: xxcharset.exe. It thus suffices to launch HEVEA as:
Starting with version 1.08, HEVEA offers support for style sheets (of the CSS variant see [CSS-2]).
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.
However, style sheets mostly offer an additional mechanism to customise their documents to HEVEA users. To do so, users should probably get familiar with how HEVEA uses style sheets in the first place.
HEVEA interest for style sheets is at the moment confined to
block-level elements (div
, table
, H<
n>
,
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
class="name" attribute, where name is the
command or environment name.
As an example the LATEX command \subsection
is implemented with the element h3
, resulting in
html output of the form:
<h3 class="subsection"> ... </h3>
By default, most styles are undefined, and default rendering of
block-level elements applies. However, some packages (such as, for
instance fancysection, see Section B.16.4) may
define them.
If you wish to change the style of section headers, loading the
fancysection package may prove appropriate (see B.16.4).
However, one can also proceed more directly, by appending new
definitions to the document style
sheet, with the command \newstyle
.
For instance, here is a \newstyle
to add style for subsections.
\newstyle{.subsection}{padding:1ex;color:navy;border:solid navy;}
This declaration adds some style element to the subsection 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
\subsection*{A styled subsection heading}
should yield:
The following points are worth noticing:
\newstyle
commands must appear
in the document preamble, i.e. before \begin{document}
.
\newstyle
commands are processed.
In this very document, all verbatim 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.
\newstyle{.verbatim}{margin:1ex 1ex;padding:1ex;background:\#ccffcc;}
Observe that, in the explicit numerical color argument above, the hash character “#” has to be escaped.
One can also change the style class attached to a given instance of an environment and thus control styling of environments more precisely.
As a matter of fact, the name of the class attribute of
environment env is referred to through an indirection, by
using the command \getenvclass{
env}
.
The class attribute can be changed with the command
\setenvclass{
env}{
class}
.
The \setenvclass
command internally defines a command
\
env@class
, whose content is read
by the \getenvclass
command. As a consequence, the class
attribute of environments follows normal scoping rules.
For instance, here is how to change the style of one verbatim
environment.
{\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}}
Observe how the class of environment verbatim is changed from its default value to the new value myverbatim. The change remains active until the end of the current group (here, the “}” at the end). Then, the class of environment verbatim is restored to its default value — which happen to be verbatim.
This example also shows two new ways to specify colours in style
definition, with a
conventional html color name (here maroon) or as
a high-level color (see Section B.14.2), given as an argument to
the \@getstylecolor
internal command
(here Apricot from the named color model).
A good way of specifying style class changes probably is by defining new environments.
\newenvironment{flashyverbatim} {\setenvclass{verbatim}{myverbatim}\verbatim} {\endverbatim}
Then, we can use \begin{flashyverbatim}
…
\end{flashyverbatim}
to get verbatim environments style with
the intended myverbatim style class.
This text is typeset inside the environment \emph{flashyverbatim}, and hence with the \emph{myverbatim} style.
Generally, the styling of environment env is performed through
the commands
\getenvclass{
env}
and \setenvclass{
env}{
…}
,
with \getenvclass{
env}
producing the
default value of env.
Concretely, this means that most of the environments are styled through an homonymous style class. Here is a non-exhaustive list of such environments
figure, table, itemize, enumerate, list, description, trivlist, center, flushleft, flushright, quote, quotation, verbatim, abstract, mathpar (cf Section B.17.15), lstlisting (cf. Section B.17.13), etc.
All sectioning commands (\part
, \section
etc.)
output H<
n>
block-level elements, which are styled
through style classes named part, section, etc.
List making-environment introduce extra style classes for items.
More specifically, for list-making environments
itemize and enumerate,
li
elements are styled as follows:
<ul class="itemize"> <li class="li-itemize"> ... </ul> | <ol class="enumerate"> <li class="li-enumerate"> ... </ol> |
That is, li
elements are styled as environments, the key name
being li-env.
The description, trivlist and list environments (which all get translated into DL elements) are styled in a similar way, internal DT and DD elements being styles through names dt-env and dd-env respectively.
The command \maketitle
formats the document
title within a table
element, with
class title, for display. The name of the title is displayed
inside block h1
, with class titlemain, while all other
information (author, date) are displayed inside block h3
, with class
titlerest.
<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>
Users can impact on title formatting by adding style in the appropriate style classes. For instance the following style class definitions:
\newstyle{.title} {text-align:center;margin:1ex auto;color:navy;border:solid navy;} \newstyle{.titlerest}{font-variant:small-caps;}
will normally produce a title in dark blue, centered in a box, with author and date in small-caps.
TitleDateAuthor |
At the moment, due to the complexity of the task, environments
tabular and array 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 divstyle environment.
The opening command \begin{divstyle}{
class}
takes the name of a class as
an argument, and translates to <div class="
class">
.
Of course the closing command \end{divstyle}
translates to
</div>
.
The limitation is that the enclosed part may generate more html
blocks, and that not all style attribute defined in class class
class will apply to those inner blocks.
As an example consider the style class definition below.
\newstyle{.ruled}{border:solid black;padding:1ex;background:\#eeddbb;color:maroon}
The intended behaviour is to add a black border around the inner block (with some padding), and to have maroon text over a light brown background.
If we, for instance, enclose an itemize environment, the resulting effect is more or less what we have expected:
\begin{divstyle}{ruled} \begin{itemize} \item A ruled itemize \item With two items. \end{itemize} \end{divstyle}
However, enclosing a centered tabular environment in a divstyle{ruled} one is less satisfactory.
\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}
English | French |
Good Morning | Bonjour |
Thank You | Merci |
Good Bye | Au Revoir |
In the html version of this document, one sees that the brown background extend on all the width of the displayed page.
This problem can be solved by introducing an extra table. We first open an extra centered table and then only open the divstyle environment.
\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}
This works because of the rules that
govern the width of html table
elements, which yield
minimal width. This trick is used in
numerous places by HEVEA, for instance in document titles, and looks
quite safe.
|
Another solution is to specify the display property of the styling div block as being inline-block:
\newstyle{.ruledbis} {border:solid black;padding:1ex;background:\#eeddbb;color:maroon;display:inline-block;}
English | French |
Good Morning | Bonjour |
Thank You | Merci |
Good Bye | Au Revoir |
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 one of this document.
The text above is typeset from the following LATEX source.
\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}
For simplicity, we assume a limit of four over the nesting depth of
toc environment.
We first define four style classes toc1, toc2,
toc3 and toc4 in the document preamble.
Since those classes are similar, a command \newtocstyle
is
designed.
\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}}
The toc environment uses a counter to record nesting depth.
Notice how the style class of the itemize environment is
redefined before \begin{itemize}
.
\newcounter{toc} \newenvironment{toc} {\stepcounter{toc}\setenvclass{itemize}{toc\thetoc}\begin{itemize}} {\addtocounter{toc}{-1}\end{itemize}}
The outputted html is:
<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 class="li-itemize">Section I.2 ... </ul> </ul>
HACHA now produces an additional file: a style sheet, which is shared by all the html files produced by HACHA. Please refer to section 7.1 for details.
By default, style declarations defined with
\newstyle
go into the header of the html document
doc.html.
However, one can send those declaration into an external style file,
whose name is doc.css.
Then, HEVEA automatically relates doc.html to
its style sheet doc.css.
To achieve this behaviour, it suffices to set the value of the boolean
register externalcss to true, by issuing the command
\externalcsstrue
in the preamble of the source document.
Notice that HEVEA output still can be processed by HACHA, with
correct behaviour.
The HEVEA command \loadcssfile{
url}
allows the
user to link to an external style sheet (like the link option for
HTML). The command takes an url of the external
sheet as argument and emits the HTML text to
link to the given external style sheet. As an example, the command
\loadcssfile{../abc.css}
produces the following html text in the head
of the document.
<link rel="stylesheet" type="text/css" href="../abc.css">
To yield some effect, \loadcssfile
must appear in the document
preamble. Several \loadcssfile
commands can be issued. Then
the given external style sheets appear in the output, following source
order.
Notice that the argument to \loadcssfile
is processed. Thus, if it
contains special characters such as “#” or “$”, those must be specified
as \#
and \$
respectively.
A viable alternative would be to quote
the argument using the \url
command from the url
package (see Section B.17.11).
At the moment, style class definitions cumulate, and appear
in the style
element in the order they are given in the
document source. There is no way to cancel the default class
definitions performed by HEVEA before it starts to process the
user’s document.
Additionally, external style sheets specified with \loadcssfile
appear before style classes defined with \newstyle
.
As a consequence (if I am right), styles
declared by \newstyle
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.
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 HEVEA.
HEVEA can be controlled by writing LATEX code. In this section, we examine how users can change HEVEA default behaviour or add functionalities. In all this section we assume that a document doc.tex is processed, using a private command file macros.hva. That is, HEVEA is invoked as:
# hevea macros.hva doc.tex
The general idea is as follows: one redefines LATEX constructs in macros.hva, using internal commands. This requires a good working knowledge of both LATEX and html. Usually, one can avoid internal commands, but then, all command redefinitions interact, sometimes in very nasty ways.
Users can easily change the rendering of some constructs. For instance, assume that all quotations in a text should be emphasised. Then, it suffices to put the following re-declaration in macros.hva:
\renewenvironment{quote} {\@open{blockquote}{}\@style{em}} {\@close{blockquote}}
The same effect can be achieved without using any of the internal commands:
\let\oldquote\quote \let\oldendquote\endquote \renewenvironment{quote}{\oldquote\em}{\oldendquote}
In some sense, this second
solution is easier, when one already knows
how to customise LATEX. However, this is less safe, since the definition of
\em
can be changed elsewhere.
There is yet another solution that takes advantage of style sheets. One can also add this line to the macros.hva file:
\newstyle{.quote}{font-style:oblique;}
This works because the environment quote is styled through
style class quote (see Section 9.2).
Notice that this solution has very little to do with
“emphasising” in the proper sense, since here we
short-circuit the implicit path from \em
to oblique fonts.
HEVEA default rendering of type style changes is described in section B.15.1. For instance, the following example shows the default rendering for the font shapes:
\itshape italic shape \slshape slanted shape \scshape small caps shape \upshape upright shape
By default, \itshape
is italics, \slshape
is oblique
italics, \scshape
is small-caps (thanks to style sheets) and \upshape
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).
italic shape slanted shape small caps shape upright shape
If one wishes to change the rendering of some of the shapes (say slanted
caps), then one should redefine the old-style \sl
declaration.
For instance, to render slanted as Helvetica (why so?), one should
redefine \sl
by \renewcommand{\sl}{\@span{style="font-family:Helvetica"}}
in
macros.hva.
And now, the shape example above gets rendered as follows:
italic shape slanted shape small caps shape upright shape
Redefining the old-style \sl
is compatible with the cancellation
mechanism, redefining \slshape
is not.
Thus, redefining directly LATEX 2є \slshape
with
\renewcommand{\slshape}{}
would yield:
italic shape slanted shape small caps shape upright shape
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.
Assume for instance that the base style of doc.tex is
jsc (the
Journal of Symbolic Computation style for articles).
For running HEVEA, the jsc style can be replaced by
article
style, but for a few commands whose calling interface is changed.
In particular, the \title
command
takes an extra optional argument (which HEVEA should ignore
anyway).
However, HEVEA can process the document as it stands.
One solution to insert the following lines into macros.hva:
\input{article.hva}% Force document class 'article' \let\oldtitle=\title \renewcommand{\title}[2][]{\oldtitle{#2}}
The effect is to replace \title
by a new command which
calls HEVEA \title
with the appropriate argument.
HEVEA fully implements LATEX 2є \newcommand
.
That is, users can define commands with an optional argument.
Such a feature permits to write a \epsfbox
command that
has the same interface as the LATEX command and
echoes itself as it is invoked to the image file.
To do this, the HEVEA \epsfbox
command has to check
whether it is invoked with an optional argument or not.
This can be achieved as follows:
\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}
Semi-automatic generation of included images is described in
section 6.
Links to included images are generated by the \imageflush
command, which calls the \imgsrc
command:
\newcommand{\imageflush}[1][] {\@imageflush\stepcounter{image}\imgsrc[#1]{\hevaimagedir\jobname\theimage\heveaimageext}}
That is, you may supply a html-style attribute to the included image,
as an optional argument to the \imageflush
command.
By default, images are PNG images stored in .png files. HEVEA provides support for the alternative GIF image file format. It suffices to invoke hevea as:
Then imagen must be run with option -gif:
A convenient alternative is to invoke hevea as:
Then hevea will invoke imagen with the appropriate
option when it thinks images need to be rebuild.
An even more convenient alternative is to load gif.hva
from within document source, for instance with the \usepackage
command.
HEVEA also provides support for the alternative SVG image file format. As for GIF images, it is more convenient to use option -fix to combine hevea and imagen invocations:
Notice that imagen production chain of SVG images always call pdflatex, even when not given the -pdf command-line option. Hence the source code of images must be processable by pdflatex. This precludes using latex-only packages such as pstricks for instance.
As not all browsers display SVG images, hevea and
imagen are bit special:
imagen produces both PNG8 and SVG images; while hevea offers both image sources,
letting client browser select the most appropriate one by the means of
teh srcset
attribute of the img
element.
By redefining the \heveaimagedir
command, users can specify a
directory for images.
More precisely, if the following redefinition occurs in the document
preamble.
\renewcommand{\heveaimagedir}{
dir}
Then, all links to images in the produced html file will be as “dir/…”. Then imagen must be invoked with option - todir:
As usual, hevea will invoke imagen with the appropriate option, provided it is passed the -fix option.
The internal command
\@addimagenopt{
option}
add
the text option to imagen command-line options, when
launched automatically by hevea (i.e. when
hevea is given the -fix command-line option).
For instance, to instruct hevea/imagen to reduce all images by a factor of √2, it suffices to state:
\@addimagenopt{-mag 707}
See section C.1.5 for the list of command-line options accepted by imagen.
It is possible to translate LATEX 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 (LATEX) input file.
The LATEX file is processed and converted into a plain text formatted file. It allows some pretty-printing in plain text.
To translate into text, invoke HEVEA as follow:
# hevea -text [-w <width>] myfile.tex
Then, HEVEA produces myfiles.txt a plain text translation of myfile.tex.
Additionally, the optional argument -w <number> sets the width of the output for text formatting. By default, The text will be 72 characters wide.
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.
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.
Tables with borders are rendered in the same spirit as in LATEX. 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 -w command-line option.
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, x2 will be rendered as x^2
, but ∫01f(x)dx will
yield something like : int01f(x)dx
.
The file format info is also supported. Info files are text files with limited hypertext links, they can be read by using emacs info mode or the info program. Please note that HEVEA translates plain LATEX to info, and not TeXinfo.
You can translate your LATEX files into info file(s) as follows:
# hevea -info [-w <width>] myfile.tex
Then, HEVEA produces the file myfile.info, an info translation of myfile.tex. However, if the resulting file is too large, it is cut into pieces automatically, and myinfo.info now contains references for all the nodes in the others files, which are named myfile.info-1, myfile.info-2,…
The optional argument -w
has the same meaning as for text output.
The text will be organised in nodes that follow the pattern of LATEX sectioning commands. Menus are created to navigate through the sections easily
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, i.e. in HEVEA case, to sectional units. As a consequence all cross references lead to sectional unit headers.
Part B |
This part follows the pattern of the LATEX reference manual [LATEX, Appendix C].
LATEX comments that start with “%
” and end at end of line are ignored and produce no output.
Usually, HEVEA ignore such comments. However, HEVEA processes
text that follows “%HEVEA
” and some other comments have a specific meaning to it (see
section 5.3).
Command names follow strict LATEX syntax. That is, apart from
#
, $
, ~
, _
and ^
, they either are
“\
” followed by a single non-letter character or
“\
” followed by a sequence of letters.
Additionally, the letter sequence may be preceded by “@
”
(and this is the case of many of HEVEA internal commands), or
terminated by “*
” (starred variants are implemented as plain
commands).
Users are strongly advised to follow strict LATEX syntax for
arguments. That is, mandatory arguments are enclosed in curly braces
{
… }
and braces inside arguments must be properly
balanced.
Optional arguments are enclosed in square brackets [
…
]
.
However, HEVEA does its best to read arguments even when they are
not enclosed in curly braces.
Such arguments are a single, different from “\
”, “{
”
and “
”, character or
a command name.
Thus, constructs such as \'ecole
,
$a_1$
or $a_\Gamma$
are
recognized and processed as école a1 and aΓ.
By contrast, a^\mbox{...}
is not recognized
and must be written a^{\mbox{...}}
.
Also note that, by contrast with LATEX, comments are parsed during argument scanning, as an important consequence brace nesting is also checked inside comments.
With respect to previous versions, HEVEA 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, HEVEA correctly processes the following source:
\newcommand{\boite}{\textbf} \boite{In bold}
The definition of \boite
makes it reduces as
\textbf
and HEVEA succeeds in fetching the argument
“{In bold}
”. We get
In bold
The above example arguably is no “legal” LATEX, but HEVEA handles it. Of course, there remains numerous “clever” LATEX tricks that exploits TEX internal behaviour, which HEVEA does not handle. For instance consider the following source:
\newcommand{\boite}[1]{\textbf#1} \boite{{In bold}, Not in Bold.}
LATEX typesets the text “In bold” using bold font, leaving the rest of the text alone. While HEVEA typesets everything using bold font. Here is HEVEA output:
In bold, Not in Bold.
Note that, in most similar situations, HEVEA will likely crash.
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 TEX way.
Environment opening and closing is performed like in LATEX, with
\begin{
env}
and
\end{
env}
.
The *
-form of an environment is a plain environment.
It is not advised to use \
env and
\end
env in place of \begin{
env}
and
\end{
env}
.
Fragile commands are not relevant to HEVEA and \protect
is
defined as a null command.
Scope rules are the same as in LATEX.
I am a bit lost here. However spaces in the output should correspond to users expectations. Note that, to HEVEA being invisible commands is a static property attached to command name.
The \\
and \\*
commands are the same, they perform a
line break, except inside arrays where they end the current row.
Optional arguments to \\
and \\*
are ignored.
Document structure is a bit simplified with respect to LATEX, since
documents consist of only two parts.
The preamble starts as soon as HEVEA starts to operate and
ends with the \begin{document}
construct.
Then, any input occurring before
\end{document}
is translated to html.
However, the preamble is processed
and the preamble comprises the content of the files given as command-line
arguments to HEVEA, see section C.1.1.1).
As a consequence, command and environment definitions that
occur before \begin{document}
are performed.
and they remain
valid during all the processing.
In particular one can define a header and a footer, by using the
\htmlhead
and \htmlfoot
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 HEVEA output is later cut into pieces by
HACHA, since both header and footer are replicated
at the start and end of any file generated by HACHA.
For instance, to append a copyright notice at the end of all the html
pages, it suffices to invoke the \htmlfoot
command as follows
in the document preamble:
\htmlfoot{\copyright to me}
The \htmlhead
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 HEVEA default (empty) attribute of
the opening <body ...>
tag by redefining
\@bodyargs
.
For instance, you get black text on a white background, when the
following declaration occurs before \begin{document}
:
\renewcommand{\@bodyargs}{style="color:black;background:white"}
Since version 1.08, a recommended alternative is to use style sheets:
\newstyle{body}{color:black; background:white;}
One can also change the default (empty) attribute of the opening
<html ...>
tag by redefining
\@htmlargs
. For instance you can set the language attribute
of the whole document by issuing the following redefinition in
the document preamble:
\renewcommand{\@htmlargs}{lang=en}
Similarly, some elements can be inserted into the output file
head
element by redefining the \@meta
command
(Such elements typically are meta
, link
, etc.).
As such text is pure html, it should be included in a
rawhtml
environment. For instance, you can specify
author information as follows:
\let\oldmeta=\@meta \renewcommand{\@meta}{% \oldmeta \begin{rawhtml} <meta name="Author" content="Luc Maranget"> \end{rawhtml}}
Note how \@meta
is first bound to
\oldmeta
before being redefined and how \oldmeta
is
invoked in the new definition of \@meta
.
Namely, simply overriding the old definition of \@meta
would
imply not outputting default meta-information.
The \@charset
command holds the value of the (html) document character
set. By default, this value is US-ASCII.
In previous versions of HEVEA, one could change the
value of the document character set by simply redefining
\@charset
. Then, it was users responsability to provide a
(LATEX) document in the correspounding encoding.
This is no longer so, and users should not redefine
\@charset
directly. Please, see Section 8.6 for details.
Generally speaking, spaces (and single newline characters) in the source are echoed in the output. Browser then manage with spaces and line-breaks. Following LATEX behaviour, spaces after commands are not echoed. Spaces after invisible commands with arguments are not echoed either.
However this is no longer true in math mode, see section B.7.7 on spaces in math mode.
New paragraphs are introduced by one blank line or more.
Paragraphs are not indented. Thus the macros \indent
and
\noindent
perform no action.
Paragraph are rendered by p
elements.
In some occasions, this technique may produce spurious paragraphs
(see 3.1.1).
The commands \footnote
,
\footnotetext
and \footnotemark
(with or without
optional arguments) are supported.
The footnote
counter exists and (re)setting it or redefining
\thefootnote
should work properly.
When footnotes are issued by a combination of \footnotemark
and
\footnotetext
, a \footnotemark
command must be issued
first, otherwise some footnotes may get numbered incorrectly or disappear.
Footnotes appear at document end in the article style and
at chapters end in the book style.
See section 7.3.6 for a description of how footnotes are flushed.
Thanks to Unicode character references, HEVEA can virtually output any symbol. It may happen that HEVEA does not known about a particular symbol, that is, most of the time, HEVEA 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 4.2 for an example of this technique).
Commands for making accents used in non-English languages, such as
\'
, work when applied to accent-less (i.e. 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”:
``\'Ecole'' works as in \LaTeX, while ``\'h'' does not.
HEVEA output will be “École” works as in LATEX, while “h” does not. And a warning will be issued.
./tmp.tex:3741: Warning: Application of '\'' on 'h' failed
Observe that using input encodings is a convenient alternative to accent commands — see Section B.17.4.
Sectioning commands from \part
down to
\subparagraph
are defined in base style files.
They accept an optional argument and have starred versions.
The non-starred sectioning commands from \part
down to
\subsubsection
show section numbers in sectional unit headings,
provided their level is greater than or equal to the current
value of the secnumdepth
counter.
Sectional unit levels and the default value of the secnumdepth
counter
are the same as in LATEX.
Furthermore, given a sectional unit secname, the
counter secname exists and the appearance of sectional units
numbers can be changed by redefining \the
secname.
For instance, the following redefinition turn the numbering of
chapters into alphabetic (uppercase) style:
\renewcommand{\thechapter}{\Alph{chapter}}
When jumping to anchors, browsers put the targeted line on top of display. As a consequence, in the following code:
\section{A section} \label{section:section} ... See Section~\ref{section:section}
Clicking on the link produced by
\ref{section:section}
will result in not displaying the
targeted section title.
A fix is writing:
\section{\label{section:section}A section} ... See Section~\ref{section:section}
Starting with version 2.04, HEVEA and HACHA will use the label name
(section:section
above) for the table of contents they generate.
For instance, the source code for the next sectioning command just
below is:
\subsection{The \label{appendix}Appendix}
As a consequence, the link to the next section on top of this page should read as:
<a href="sectioning.html#appendix">The Appendix</a>
That is, HEVEA used the label name given in source as
an anchor.
Notice that this behaviour applies to the \label
command
that occurs first in the sectioning command argument.
The \appendix
command exists and should work as in LATEX.
HEVEA now generates a table of contents, using a procedure similar
to the one of LATEX(a .htoc file is involved).
One inserts this table of contents in the main document by issuing
the command \tableofcontents
.
Table of contents is controlled by the counter tocdepth
.
By default, the table of contents shows sectioning units down to the
subsubsection level in article style and down to the subsection level
in book (or report) style. To include more or less
sectioning units in the
table of contents, one should increase or decrease the tocdepth
counter.
It is important to notice that HEVEA produces such a table of
contents, only when it has total control over cross-references.
More precisely, HEVEA cannot produce the table of contents when it
reads LATEX-produced .aux files.
Instead, it should read its own .haux files.
This will naturally occur if no .aux files are present,
otherwise these .aux files should be deleted, or HEVEA
should be instructed not to read them with the command-line option
-fix
(see Sections B.11.1 and C.1.1.4).
One can also add extra entries in the table of contents by using
the command \addcontentslines
, in a way similar
to LATEX 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 \addcontentsline
:
\subsection*{\aname{no:number}{Use \hacha{}}} \addcontentsline{toc}{subsection}{\ahrefloc{no:number}{Use \hacha{}}}
(See Section 8.1.1 for details on commands related to hyperlinks.)
There is no list of figures nor list of tables.
However, HEVEA has a more sophisticated way of producing a kind of map w.r.t. the sectioning of the document. A later run of HACHA on HEVEA output file splits it in smaller files organized in a tree whose nodes are tables of links. By contrast with LATEX, 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 7 explains how to control HACHA.
Both LATEX 2є \documentclass
and old LATEX
\documentstyle
are accepted.
Their argument style is interpreted by attempting to load a
style.hva file.
Presently, only the style files article.hva, seminar.hva,
book.hva and report.hva exist, the latter two
being equivalent.
If one of the recognized styles has already been loaded at the time when
\documentclass
or
\documentstyle
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 HEVEA as a command
line argument (see 2.2).
Conversely, if HEVEA attempt to load style.hva fails, then a fatal error is flagged, since it can be sure that the document cannot be processed.
HEVEA reacts to
\usepackage[
options]{
pkg}
in
the following way:
\usepackage
command with its arguments gets echoed to the
image file (see 6).
Note that HEVEA will not fail if it cannot load pkg.hva and that no warning is issued in that case.
The HEVEA distribution contains implementations of some packages, such as verbatim, colors, graphics, etc.
In some situations it may not hurt at all if HEVEA does not implement a package, for instance HEVEA does not provide an implementation for the fullpage package.
Users needing an implementation of a package that is widely used and available are encouraged to contact the author. Experienced users may find it fun to attempt to write package implementations by themselves.
All title related commands exist, with the following peculiarities:
\title
command appears
in the html document header. As a consequence, titles should
remain simple. Normal design (as regards HEVEA) is for
\title
to occur in the document preamble, so that the title
is known at the time when the document header is emitted (while
processing \begin{document}
). However, there are two subtleties.If no \title
command occurs in document preamble and that one \title
command appears in the document, then the title is saved into the
.haux file for a next run of HEVEA to put it in the
html document header.
If \title
commands are present both in preamble and after
\begin{document}
, then the former takes precedence.
\today
command generates will work properly
only if hevea is invoked with the -exec xxdate.exe
option. Otherwise \today
generates nothing and a warning is
issued.
The abstract
environment is present is all base styles,
including the book style.
The titlepage
environment does nothing.
Displayed-paragraph environments translate to block-level elements.
In addition to the environments described in this section,
HEVEA implements the center
, flushleft
and
flushright
environments.
HEVEA also implements the corespondant TEX style declaration
\centering
\raggedright
and \raggedleft
,
but these declarations may not work as expected, when they do not
appear directly inside a displayed-paragraph environment or inside an array
element.
The quote
and quotation
environments are the same thing: they
translate to BLOCKQUOTE
elements.
The verse
environment is not supported.
The itemize
, enumerate
and description
environments translate to the ul
, ol
, and
DL
elements and this is the whole story.
As a consequence, no control is allowed on the appearances of these
environments. More precisely optional arguments to \item
do not
function properly inside itemize
and enumerate
. Moreover, item
labels inside itemize
or numbering style inside enumerate
are browser dependent.
However, customized lists can be produced by using the the list environment (see next section).
The list
environment translates to the
DL
element.
Arguments to \begin{list}
are handled as follows:
\begin{list}{
default_label}{
decls}
The first argument default_label is the label generated by an
\item
command with no argument.
The second argument, decls is a sequence of declarations.
In practice, the following declarations are relevant:
\refstepcounter
by every \item
command with no argument, before it does
anything else.
\item
executes
\makelabel{
label}
, where label is the item
label, to print its label.
Thus, users can change label formatting by redefining
\makelabel
.
The default definition of \makelabel
simply echoes label.
As an example, a list with an user-defined counter can be defined as follows:
\newcounter{coucou} \begin{list}{\thecoucou}{% \usecounter{coucou}% \renewcommand{\makelabel}[1]{\textbf{#1}.}} ... \end{list}
This yields:
The trivlist
environment is also supported. It is equivalent to
the description
environment.
The verbatim
and verbatim*
environments translate to
the PRE
element.
Inside verbatim*
, spaces are replaced by underscores (“_
”).
Similarly, \verb
and \verb*
translate to the CODE
text element.
The alltt
environment is supported.
The three ways to use math mode ($
…$
,
\(
…\)
and
\begin{math}
…\end{math}
) are supported.
The three ways to use display math mode ($$
…$$
,
\[
…\]
and
\begin{displaymath}
… \end{displaymath}
) are also
supported.
Furthermore, \ensuremath
behaves as expected.
The equation
, eqnarray
, eqnarray*
environments
are supported.
Equation labelling and numbering is performed in the first two
environments, using the equation
counter.
Additionally, numbering can be suppressed in one row of an
eqnarray
, using the \nonumber
command.
Math mode is not as powerful in HEVEA as in LATEX. 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
HEVEA 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 HEVEA renders
$\frac{1}{\sum_{i=1}^{\infty} i$
as: 1/∑i=1∞ i, and
$$\frac{1}{\sum_{i=1}^{\infty} i$$
as:
|
HEVEA admits, subscript (_
), superscripts (^
) and
fractions (\frac{
numer}{
denom}
).
The best effect is obtained in display mode, where html
table
element is extensively used.
By contrast, when not in display mode, HEVEA uses only
SUB
and SUP
text-level elements to render superscrits
and subscript, and the result may not be very satisfying.
However,
simple subscripts and superscripts, such as x_i
or x^2
,
are always rendered using the SUB
and SUP
text-level elements and their appearance should be correct
even in in-text formulas.
When occurring outside math mode, characters _
and ^
act as
ordinary characters and get echoed to the output. However, a warning
is issued.
An attempt is made to render all ellipsis constructs (\ldots
,
\cdots
, \vdots
and \ddots
). The effect may be
strange for the latter two.
The nth root command \sqrt
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 \sqrt
command is
defined as follows:
\newcommand{\sqrt}[3][2]{\left(#2\right)^{1/#1}}
Then, the source
fragment: $$\sqrt[5]{\frac{1}{n!}} + \sqrt[3]{\pi} + \sqrt{\pi}$$
gets rendered
as follows:
| + | ∛ |
| + | √ |
|
The support for unicode symbols offered by modern browsers allows to translate almost all math symbols correctly.
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
\limits
and \nolimits
commands.
Big delimiters are also handled.
The commands \stackrel
, \underline
and \overline
are recognized.
They produce sensible output in display mode.
In text mode, these macros call the \textstackrel
,
\textunderline
and \textoverline
macros.
These macros perform the following default actions
U
text-level element.
The command \boxed
works well both in display and normal math mode. Input of the form \boxed{\frac{\pi}{2}}
produces π/2 in normal math, and
|
in display-math mode. The commands \bigl,\bigr
etc. are also rendered well. Some examples can be found here.
Math accents that have coresponding text accents
(\hat
, \tilde
, etc.) are
handled by default. They in fact act as the
corresponding text-mode accents (Section B.3.4).
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 HEVEA 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.
\renewcommand{\hat}[1]{\mathop{#1}\limits^{\textasciicircum}\nolimits} Displayed: $$ \hat{\mu} = \hat{\Delta}. $$ In text: $\hat{\mu} = \hat{\delta}$
An you get, displayed:
| = |
| . |
In text: µ^ = δ^.
Whereas, with the default of \hat
being \^
,
you get “µ = δ”, with the following warnings:
./tmp.tex:4652: Warning: Application of '\^' on '\mu' failed ./tmp.tex:4652: Warning: Application of '\^' on '\delta' failed
The \vec
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.
\vec{u} in text mode: u→, \vec{u} in display mode: |
|
Most “extensible accents” (\widetilde
, \widehat
, etc.)
are not even defined.
There are a few exceptions: line “accents”:
|
Brace “accents”:
|
And arrow “accents”:
|
By contrast with LATEX, space in the input matters in math mode.
One or more spaces are translated to one space.
Furthermore,
spaces after commands (such as \alpha
) are echoed
except for invisible commands (such as \tt
).
This allows users to control space in their formulas, output being
near to what can be expected.
Explicit spacing commands (\,
, \!
, \:
and
\;
) are recognized, the first two commands do nothing, while
the others two output one space.
Letters are italicized inside math mode and this cannot be
changed. The appearance of
other symbols can be changed using
LATEX 2є style changing commands (\mathbf
, etc.).
The commands \boldmath
and \unboldmath
are not
recognized. Whether symbols belonging to the symbol font are affected
by style changes or not is browser dependent.
The \cal
declaration and the \mathcal
command (that
yield calligraphic letters in LATEX) exist. They yield red letters by
default.
Observe that this does not corresponds directly to how LATEX manage style in math mode and that, in fact, style cannot really change in math mode.
Math style changing declarations \displaystyle
and
\textstyle
do nothing when HEVEA is already in the requested
mode,
otherwise they issue a warning.
This is so because HEVEA 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 \displaystyle
are to be taken seriously.
The commands \scriptstyle
and \scriptscriptstyle
perform type size changes.
HEVEA understands command definitions given in LATEX style. Such
definitions are made using
\newcommand
, \renewcommand
and \providecommand
.
These three constructs accept the same arguments and have the same
meaning as in LATEX, in particular it is possible to define an user
command with one optional argument.
However, HEVEA is more tolerant: if command
name already exists, then a subsequent \newcommand{
name}
…is ignored. If macro name does not exists, then
\renewcommand{
name}
…performs a definition of name. In both cases, LATEX would crash, HEVEA just issues
warnings.
The behaviour of \newcommand
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 HEVEA (see section 5.1).
Conversely, changes of base macros (i.e. the ones that HEVEA
defines before loading any user-specified file) must be performed
using \renewcommand
.
Scoping rules apply to macros, as they do in LATEX. Environments and groups define a scope and command definition are local to the scope they occur.
It is worth noticing that HEVEA also partly implements TEX definitions
(using \def
) and bindings (using \let
), see
section B.16.1 for details.
HEVEA accepts environment definitions and redefinitions
by \newenvironment
and \renewenvironment
.
The support is complete and should conform
to [LATEX, Sections C.8.2].
Environments define a scope both for commands and environment definitions.
New theorem-like environments can also be introduced and redefined,
using \newtheorem
and \renewtheorem
.
Note that, by contrast with plain environments definitions, theorem-like environment definitions are global definitions.
LATEX counters are (fully ?) supported.
In particular, defining a counter cmd with
\newcounter{
cmd}
creates a macro
\the
cmd that outputs the counter value.
Then the \the
cmd command can be redefined.
For instance, section numbering can be turned into alphabetic style by:
\renewcommand{\thesection}{\alph{section}}
Note that TEX style for counters is not supported at all and that using this style will clobber the output. However, HEVEA implements the calc package that makes using TEX style for counters useless in most situations (see section B.17.3).
The ifthen package is partially supported.
The one unsupported construct is the
\lengthtest
test expression, which is
undefined.
As a consequence, HEVEA accepts the following example from the LATEX manual:
\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}
For example: Gcd(54,30) = gcd(24, 30) = gcd(24, 6) = gcd(18, 6) = gcd(12, 6) = gcd(6, 6) = 6.
Additionally, a few boolean registers are defined by HEVEA. Some of them are of interest to users.
Finally, note that HEVEA also recognised à la TEX conditional macros (see section B.16.1.4). Such macros are fully compatible with the boolean registers of the ifthen package, as it is the case in LATEX.
Figures and tables are put where they appear in source, regardless of
their placement arguments.
They are outputted inside a BLOCKQUOTE
element and they are
separated from enclosing text by two
horizontal rules.
Captions and cross referencing are handled.
However captions are not moved at end of figures: instead, they appear
where the \caption
commands occur in source code.
The \suppressfloats
command does nothing and the
figure related counters (such as topnumber
) exist but are useless.
Marginal notes are handled in an HEVEA specific way.
By default, all notes go in the right margin.
Issuing \reversemarginpar
causes the notes to go in the left
margin. Unsurprisingly, issuing \normalmarginpar
reverts to
default behaviour.
The \marginpar
command has an optional argument.
\marginpar[
left_text]{
right_text}
If optional argument left_text is present and that notes
go in the left margin, then left_text is the text of the
note. Otherwise, right_text is the text of the note.
As a conclusion, marginal notes in HEVEA always go to a fixed side
of the page, which side being controlled by the commands
\normalmarginpar
(right side) and \reversemarginpar
(left side). This departs form LATEX that selects a default side
depending on the parity of the page counter.
Marginal notes are styled by the means of two environment style
classes (see Section 9.3) :
marginpar
and marginparside
.
The latter marginparside
takes care of margins and placement as
a float, its value is marginparright
for notes in the right
margin and marginparleft
for notes in the left margin.
Users are not expected to alter those.
The marginpar
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 marginpar
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.
\newstyle{.mynote}{width:10\%; color:red;} \setenvclass{marginpar}{mynote}
Limited support is offered.
The tabbing environment translate to a flexible tabular-like
environment.
Inside this environment, the command \kill
ends a row, while
commands
\=
and \>
start a new column.
All other tabbing commands do not even exist.
These environments are supported, using html
table
element, rendering is satisfactory in most (not too
complicated) cases.
By contrast with LATEX,
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 l
, c
and r
specifications open display mode
while the remaining p
and @
do not.
The l
, c
,r
and @
specifications
disable word wrap, while the p
specification enables it.
Entries in a column whose specification is l
(resp. c
or
r
) 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 p{
wd}
, see below).
Otherwise, vertical alignment is unspecified.
Entries in a column whose specification is p{
wd}
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
HEVEA makes a distinction between LR-mode and paragraph mode.
Also observe that the length argument wd to the p
specification is ignored.
Some LATEX array features are not supported at all:
\begin{array}
and
\begin{tabular}
are ignored.
\vline
does not exists.
Some others are partly rendered:
@
formatting specifications in \multicolumn
argument are ignored.
|
appears somewhere in the column formatting
specification, then the array is shown with borders.
\hline
does nothing if the array has borders
(see above). Otherwise, an horizontal rule is outputted.
\cline
ignores its argument and is equivalent
to \hline
.
\extracolsep
issues a warning and ignores its argument.
Additionally, the tabular*
environment is
recognised and gets rendered as an html table with an advisory
width attribute.
By default, HEVEA implements the array package
(see [LATEX-bis, Section 5.3] and section B.17.2 in this
document), which significantly extends the
array
and tabular
environments.
In some situations, HEVEA uses some of the ancillary files generated by LATEX. More precisely, while processing file doc.tex, the following files may be read:
\ref
command. If the .aux
file is not present, or if the hevea command is given the
-fix option, HEVEA will instead use .haux
files.
\bibliography
command.\bibliography
command.HEVEA does not fail when it cannot find an auxiliary file. When another run of HEVEA is needed, a warning is issued, and it is user’s responsibility to rerun HEVEA. However, the convenient -fix command-line option instructs HEVEA to rerun itself, until it believes it has reached stable state.
The LATEX commands \label
and \ref
are changed by HEVEA
into html anchors and local links, using the “a
” element.
Additionally, numerical references to sectional units, figures,
tables, etc. are shown, as they would appear in the .dvi file.
Numerical references to pages (such as generated by \pageref
)
are not shown; only an link is generated.
The anchor used is the label argument to
\label{
label}
.
More precisely, \label{
label}
translates to
<a id="
label"></a>
;
while \ref{
label}
translates to <a name="#
label">
nnn</a>
,
where nnn is the appropriate numerical reference to a section.
As a consequence spaces are better avoided in label.
Starting with HEVEA version 2.04,
the html anchors used by \label
and \ref
cannot
differ from the arguments to these commands anymore.
Moreover,
when \label{
label}
occurs
inside the argument of a sectioning command (i.e. in section title,
as recommended by section B.4.1),
then HEVEA and HACHA will use label
as the “id” attribute of the corresponding section.
For instance, the LATEX source of this very section is:
\subsection{Cross-References\label{cross-reference}}
It translates to html similar to
<h3 class="subsection" id="cross-reference">B.11.2  Cross-References</h3>
Notice that no <a id="cross-reference"></a>
appears above.
Instead id="cross-reference"
appears
in the enclosing h3
header element.
While processing a document doc.tex, cross-referencing information can be computed in two different, mutually exclusive, ways, depending on whether LATEX has been previously run or not:
The second option is recommended.
When using its own doc.haux file, HEVEA will output a new doc.haux file at the end of its processing. This new doc.haux file contains actualised cross referencing information. Hence, in that case, HEVEA may need to run twice to get cross-references right. Note that, just like LATEX, HEVEA 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 doc.haux does not exist.
Observe that if a non-correct doc.aux file is present, then cross-references will apparently be wrong. However the links are correct.
The \cite
macro is supported. Its optional argument is
correctly handled. Citation labels are extracted from the
.aux file if present, from the .haux file otherwise.
Note that these labels are put there by LATEX in the first case,
and by HEVEA in the second case, when they process the
\bibitem
command.
All BibTEX related commands exist and echo the appropriate information into the .haux file.
In particular, the \bibliography
command exists and attempts to load the
formatted bibliography, i.e. to load the .hbbl file.
The .hbbl file is produced from the .haux file by
the companion program bibhva (see C.1.4).
To include the bibliographic references extracted from .bib
databases, it should normally suffice to do:
# hevea doc.tex # bibhva doc # hevea doc.tex
In case no .hbbl file exists,
the \bibliography
command attempts to load
the .bbl file normally used while combining LATEX and
BibTEX. Thus, another way to extract bibliographic references from
.bib databases is:
# latex doc.tex # bibtex doc # hevea doc.tex
In case both files exist, notice that loading the .hbbl file has priority over loading the .bbl file.
The \input
and \include
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 C.1.1.1 on how HEVEA searches files.
However, in the case of the \include
command, the file is
searched only when previously given as an argument to
the \includeonly
command.
\input
is not supported. That is,
one should write \input{
filename}
.
\input{
filename}
and
\include{
filename}
commands into the
image file. This sounds complicated, but this is what you want!
The \listfiles
command is a null command.
Glossaries are not handled (who uses them ?).
While processing a document doc.tex, index
entries go into the file doc.hidx, while
the formatted index gets written into the file
doc.hind.
As with LATEX, two runs of HEVEA are normally needed to format
the index.
However, if all index producing commands (normally \index
)
occur before the index formatting command (normally
\printindex
), then only one run is needed.
As in LATEX, index processing is not enabled by default and some package has to be loaded explicitly in the document preamble. To that aim, HEVEA provides the standard package makeidx, and two extended packages that allow the production of several indexes (see section B.17.7).
Formatting of indexes in HEVEA departs from LATEX behaviour.
More precisely the theindex
environment does not exist.
Instead, indexes are formatted using special
indexenv 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 indexcols counter (default value
is two).
The \typeout
command echos its argument on the
terminal, macro parameter #
i are replaced by their values.
The \typein
command is not supported.
The advisory line breaking command \linebreak
will produce a line break if it has no argument or if its optional
argument is 4.
The \nolinebreak
command is a null command.
The \\
and \\*
commands output a <BR>
tag,
except inside arrays where the close the current row.
Their optional argument is ignored.
The \newline
command outputs a <BR>
tag.
All other line breaking commands, declarations or environments are silently ignored.
They are no pages in the physical sense in html. Thus, all these commands are ignored.
All length commands are ignored, things go smoothly when LATEX syntax is
used (using the \newlength
, \setlength
, etc. commands,
which are null macros).
Of course, if lengths are really important to the document, rendering
will be poor.
Note that TEX length syntax is not at all recognised. As a
consequence, writing things like \textwidth=10cm
will clobber
the output.
Users can correct such misbehaviour by adopting LATEX syntax, here
they should write
\setlength{\textwidth}{10cm}
.
The \hspace
, \vspace
and \addvspace
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 1em
or 1ex
is one space or one
line-break. For other length units, a simple conversion based upon a
10pt font is used.
HEVEA cannot interpret more complicated length arguments or perform negative spacing. In these situations, a warning is issued and no output is done.
Spacing commands without arguments are recognised.
The \enspace
, \quad
and \qquad
commands output
one, two and four non-breaking spaces, while the \smallskip
,
\medskip
and \bigskip
output one, one, and two line
breaks.
Stretchable lengths do not exist, thus the \hfill
and
\vfill
macros are undefined.
Box contents is typeset in text mode (i.e. non-math and non-display
mode).
Both LATEX boxing commands \mbox
and \makebox
commands exist.
However \makebox
generates a specific warning, since HEVEA
ignore the length and positioning instructions given as optional
argument.
Similarly, the boxing with frame \fbox
and \framebox
commands are recognised and
\framebox
issues a warning.
When in display mode, \fbox
frames its argument by
enclosing it in a
table with borders. Otherwise, \fbox
calls the \textfbox
command, which issues a warning and typesets its argument
inside a \mbox
(and thus no frame is drawn).
Users can alter the behaviour of \fbox
in non-display mode by
redefining \textfbox
.
Boxes can be saved for latter usage by storing them in bins.
New bins are defined by \newsavebox{
cmd}
.
Then some text can be saved into cmd by
\sbox{
cmd}{
text}
or
\begin{lrbox}{
cmd}
text \end{lrbox}
.
The text is translated to html, as if it was inside a \mbox
and the resulting output is stored.
It is retrieved (and outputted) by the command
\usebox{
cmd}
.
The \savebox
command reduces to \sbox
, ignoring its
optional arguments.
The \rule
commands translate to a html horizontal rule
(<HR>
) regardless of its arguments.
All other box-related commands do not exist.
It is possible to have pictures and graphics processed by imagen (see section 6.1). In the case of the picture environment it remains users responsibility to explicitly choose source chunks that will get rendered as images. In the case of the commands from the graphics package, this choice is made by HEVEA.
For instance consider the following picture:
\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}
Users should enclose all picture elements in a toimage
environment (or inside %BEGIN IMAGE
… %END IMAGE
comments) and insert an \imageflush
command, where they want
the image to appear in html output:
%BEGIN IMAGE \newcounter{cms} \setlength{\unitlength}{1mm} \begin{picture}(50,10) ... \end{picture} %END IMAGE %HEVEA\imageflush
This will result in normal processing by LATEX and image inclusion by HEVEA:
All commands from the graphics package are implemented using the
automatic image inclusion feature.
More precisely, the outermost invocations of
the \includegraphics
, \scalebox
,
etc. commands are sent to the image image file and there will
be one image per outermost invocation of these commands.
For instance, consider a document doc.tex that loads the graphics package and that includes some (scaled) images by:
\begin{center} \scalebox{.5}{\includegraphics{round.ps}} \scalebox{.75}{\includegraphics{round.ps}} \includegraphics{round.ps} \end{center}
Then, issuing the following two commands:
# hevea doc.tex # imagen doc
yields html that basically consists in three image links, the images being generated by imagen.
Since the advent of pdflatex,
using \includegraphics
to insert bitmap images
(e.g. .gif or .jpg)
became frequent.
In that case, users are advised not to use HEVEA default
implementation of the graphics package.
Instead, they may use a simple variation of
the technique described in Section 8.2.
HEVEA partly implements the color package.
Implemented commands are \definecolor
, \color
,
\colorbox
,
\textcolor
, \colorbox
and \fcolorbox
.
Other commands do not exist.
At startup,
colours black, white,
red, green, blue,
cyan, yellow and magenta are
pre-defined.
Colours are defined by
\definecolor{
name}{
model}{
spec}
,
where name is the color name, model is the color
model used, and spec is the color specification according to
the given model.
Defined colours are used by the declaration
\color{
name}
and by the command
\textcolor{
name}{
text}
, which
change text color.
Please note that, the \color
declaration
accepts color specifications directly
when invoked as
\color[
model]{
spec}
.
The \textcolor
command has a similar feature.
As regards color models, HEVEA implements the rgb, cmyk, hsv and hls color models. In those models, color specifications are floating point numbers less than one. For instance, here is the definition for the red color:
\definecolor{red}{rgb}{1, 0, 0}
The named color model is also supported, in this model color specification are just names… Named colours are the ones of dvips.
There are at least three ways to use colours from the named model.
\color
and \textcolor
.
That is:
\definecolor{rouge-brique}{named}{BrickRed}\textcolor{rouge-brique}{Text as a brick}
.
\textcolor[named]{BrickRed}{Text as another brick}
.
\textcolor{BrickRed}{Text as another brick}
.
Which yields:
HEVEA also implements the \colorbox
and \fcolorbox
commands.
\colorbox{red}{Red background}, \fcolorbox{magenta}{red}{Red background, magenta border}.
Those two commands accept an optional first argument that specifies
the color model, as \textcolor
does:
\fcolorbox[named]{RedOrange}{Apricot}{Apricot background, RedOrange border}.
Colours should be used carefully. Too many colours hinders clarity and some of the colours may not be readable on the document background color.
With respect to the LATEX color package, HEVEA features
an additional
bgcolor environment, for changing the background color of some
subparts of the document.
The bgcolor environment is a displayed environment and it
normally starts a new line.
Simple usage is \begin{bgcolor}{
color}
…
\end{bgcolor}
, where
color is a color defined with \definecolor
.
Hence the following source yield a paragraph with a red background:
\begin{bgcolor}{red} \color{yellow}Yellow letters on a red backgroud \end{bgcolor}
Yellow letters on a red background |
The bgcolor environment is implemented by one-cell
table
element, it takes an
optional argument that is used as an attribute for the inner td
element (default value is style="padding:1em"
).
Advanced users may change the default, for instance as:
\begin{bgcolor}[style="padding:0"]{yellow} \color{red}Red letters on a yellow backgroud \end{bgcolor}
The resulting output will be red letters on a yellow background and no padding:
Red letters on a yellow background, no padding |
High-level colours are color names
defined with \definecolor
.
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
"#XXXXXX"
.
One changes the high-level high-color into a low-level color by
\@getcolor{
high-color}
.
Low-level colours are appropriate inside html attributes and as
arguments to the \@fontcolor
internal macro.
An example of \@getcolor
usage can be found at the end of
section 8.5.
There is also \@getstylecolor
command that acts
like\@getcolor
, 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 [CSS-2]. See
Section 9.3 for an example.
All LATEX 2є declarations and environments for changing type style are recognised. Aspect is rather like LATEX 2є output, but there is no guarantee.
As html does not provide the same variety of type styles as LATEX does. However css provide a wide variety of font properties. HEVEA uses generic properties, proper rendering will then depend upon user agent. For instance, it belongs to the user agent to make a difference between italics (rendered by the font style “italic”) and slanted (rendered by the font style “oblique”).
Here is how HEVEA implements text-style declarations by default:
|
|
|
Text-style commands also exists, they are defined as
\mbox{\
decl…}
. For instance,
\texttt
is defined as a command with one argument whose body is
\mbox{\ttfamily#1}
.
Finally, the \emph
command for emphasised text also exists,
it yields text-level em
elements.
As in LATEX, type styles consists in three components: shape, series and family. HEVEA 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:
{\itshape italic shape \slshape slanted shape \scshape small caps shape \upshape upright shape}
Then, in the rendering below, “small caps shape” appears in small caps shape only and not in italics:
italic shape slanted shape small caps shape upright shape
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
“{\sl\sc slanted and small caps}
” yields “slanted”
small caps: “slanted and small caps”.
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 10.2 for a more thorough description.
All declarations, from \tiny
to \Huge
are recognised.
Output is not satisfactory inside headers elements
generated by sectioning commands.
The \symbol{
num}
outputs character number num
(decimal) from the Unicode character set.
This departs from LATEX, which output symbol number num in
the current font.
This section describes HEVEA functionalities that extends on plain LATEX, as defined in [LATEX]. Most of the features described here are performed by default.
Normally, HEVEA does not recognise constructs that are specific to TEX. However, some of the internal commands of HEVEA are homonymous to TEX macros, in order to enhance compatibility. Note that full compatibility with TEX is not guaranteed.
The \def
construct for defining commands is supported.
It is important to
notice that HEVEA semantics for \def
follows TEX semantics.
That is, defining a command that already
exists with \def
succeeds.
Delimiting characters in command definition are somehow supported. Consider the following example from the TEX Book:
\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.
It yields: And $lookabLookLook cx5.
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 \{
.
One can include \{
in a command argument by using the grouping
characters {
… }
:
\def\frenchquote(#1){\guillemotleft~\emph{#1}~\guillemotright{} (in French)} he said \frenchquote(Alors cette accolade ouvrante {``\{''}~?).
Yields: he said « Alors cette accolade ouvrante “{” ? » (in French).
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 not be handled properly by HEVEA:
\def\x% #1{y}
Such TEX source should be rewritten as \def\x#1{y}
.
Another source of incompatibility with TEX is that substitution of macros parameters is not performed at the same moment by HEVEA and TEX. 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 LATEX and in HEVEA:
\def\cs#1A{``#1''} \def\othercs#1{\cs#1A} \othercs{coucouA}
LATEX output is “coucou”A, while HEVEA output is “coucouA”. For instance, here is HEVEA output: “coucouA”. Please note that in most situations this discrepancy will make HEVEA crash.
HEVEA also processes a
limited version of \let
:
\let
macro-name1 = macro-name2
The effect is to bind macro-name1 to whatever macro-name2
is bound to at the time \let
is processed. This construct may
prove very useful in situations where
one wishes to slightly modify basic commands.
See sections 10.3 and B.2 for examples of using
\let
in such a situation.
It is possible to escape scope and to make global definitions
and bindings by using the TEX construct \global
.
The \global
construct is significant before
\def
and \let
constructs.
Also note that \gdef
is equivalent to \global\def
.
The \newif\if
name, where name is made of letters
only, creates three macros:
\if
name, \
nametrue
and
\
namefalse
.
The latter two set the name condition to true and
false, respectively.
The \if
name command tests the condition name:
\if
name\else
\fi
Text text1 is processed when name is
true, otherwise text2 is processed.
If text2 is empty, then the \else
keyword can be
omitted.
Note that HEVEA also implements LATEX ifthen package and that TEX simple conditional macros are fully compatible with LATEX boolean registers. More precisely, we have the following correspondences:
TEX | LATEX | |
\newif\if name | \newboolean{ name} | |
\ nametrue | \setboolean{ name}{true} | |
\ namefalse | \setboolean{ name}{false} | |
\if name text1\else
text2\fi | \ifthenelse{\boolean{ name}}{ text1}{ text2} |
HEVEA implements the macros \unskip
and \endinput
.
It also supports the \csname
… \endcsname
construct.
If one strictly follows the LATEX manual, only commands with no
arguments can be defined inside other commands.
Parameters (i.e. #
n) occurring inside command bodies
refer to the outer definition, even when they appear in nested
command definitions.
That is, the following source:
\newcommand{\outercom}[1]{\newcommand{\insidecom}{#1}\insidecom} \outercom{outer}
yields this output:
Nevertheless, nested commands with arguments are allowed.
Standard parameters #
n still refer to the outer
definition, while nested parameters ##
n refer to the
inner definition.
That is, the source:
\newcommand{\outercom}[1]{\newcommand{\insidecom}[1]{##1}\insidecom{inner}} \outercom{outer}
yields this output:
Date and time support is not enabled by default, for portability and simplicity reasons.
However, HEVEA source distribution includes a simple (sh) shell script xxdate.exe that activates date and time support. The hevea command, should be invoked as:
# hevea -exec xxdate.exe ...
This will execute the script xxdate.exe, whose output is then
read by HEVEA.
As a consequence, standard LATEX counters year
,
month
, day
and
time
are defined and
LATEX command \today
works properly.
Additionally the following counters and commands are defined:
Counter weekday | day of week, 0…6 (e.g. 3) | |
Counter Hour | hour, 00…11 (e.g. 03) | |
Counter hour | hour, 00…23 (e.g. 15) | |
Counter minute | minute, 00…59 (e.g. 20) | |
Counter second | second, 00…619(e.g. 45) | |
Command \ampm | AM or PM (e.g. PM) | |
Command \timezone | Time zone (e.g. CEST) | |
Command \heveadate | Output of the date Unix command, (e.g. Wed Jul 4 15:20:45 CEST 2018) | |
Note that I chose to add an extra option (and not an extra
\@exec
primitive) for security reasons. You certainly do
not want to enable HEVEA to execute silently an arbitrary program
without being conscious of that fact.
Moreover, the hevea program does not execute
xxdate.exe by default since it is difficult to write such
a script in a portable manner.
Windows users should enjoy the same features with the version of xxdate.exe included in the Win32 distribution.
Loading the fancysection.hva 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.
Note : 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 9 for details.
The fancysection.hva file is intended to be loaded after
the document base style.
Hence the easiest way to load the fancysection.hva file
is by issuing \usepackage{fancysection}
in the document preamble.
To allow processing by LATEX, one may for instance create
an empty fancysection.sty file.
As an alternative, to use fancy section style in doc.tex whose base style is article you should issue the command:
# hevea article.hva fancysection.hva doc.tex
You can also make a doc.hva file that contains the two lines:
\input{article.hva} \input{fancysection.hva}
And then launch hevea as:
# hevea doc.hva doc.tex
Sectioning command background colours can be changed by redefining the corresponding colours (part, chapter, section,…). For instance, you get various mixes of red and orange by:
\input{article.hva} \input{fancysection.hva} \definecolor{part}{named}{BrickRed} \definecolor{section}{named}{RedOrange} \definecolor{subsection}{named}{BurntOrange}
(See section B.14.2 for details on the named color model that is used above.)
Another choice is issuing the command
\colorsections{
hue}
, where
hue is a hue value to be interpreted in the HSV model.
For instance,
\input{article.hva} \input{fancysection.hva} \colorsections{20}
will yield sectional headers on a red-orange background.
HEVEA distribution features another style for fancy sectioning commands: the undersection package provides underlined sectional headers.
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 HEVEA.
One of the most salient shortcomings is the inability to display sub-elements
for big brackets, braces and parenthesis, which HEVEA normally
outputs when it processes \left[
, \right\}
etc.
We (hopefully) expect Windows fonts to display more of Unicode easily in a foreseeable future. As a temporary fix, we provide a style file winfonts.hva. Authors concerned by producing pages that do not look too ugly when viewed through Windows browsers are thus advised to load the file winfonts.hva. For instance they can invoke HEVEA as:
# hevea winfonts.hva ...
At the moment, loading winfonts.hva only changes the rendering of LATEX big delimiters, avoiding the troublesome Unicode entities. As an example, here are some examples of rendering.
|
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 (e.g. use \leq
[≤]
in place of \preceq
[≼]) and, above all,
they should control the rendering of their documents using several browsers.
MathJax support is enabled by loading the mathjax package. Two operating mode modes are provided: explicit and automatic. Notice that HEVEA distribution includes a innocuous mathjax.sty for LATEX compatibility — see also Sec. C.4.2.
Explicit mode is enabled when \usepackage{mathjax}
appears in the document preamble,
or when HEVEA is invoked as “hevea mathjax.hva
…”.
Basic consists in one environment displayjax
and one command \textjax
.
The environment is appropriate for displayed maths.
As an example, the following source
A displayed formula: \begin{displayjax} \frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} + \frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right] \end{displayjax}
is displayed as follows:
The \textjax
command is appropriate for inline mathematical contents.
For instance, the following source
``A nice inline formula: \textjax{\frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} + \frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right]}.''
is typeset as: “A nice inline formula: \(\frac{\pi}{4} = \left[1 - \frac{1}{3} + \frac{1}{5} - \frac{1}{7} + \frac{1}{9} + \cdots + \frac{(-1)^n}{2n+1} + \cdots \right]\).”
Advanced support consists in the mathjax environment. Source code
enclosed in \begin{mathjax}\ldots\end{mathjax}
will be
reproduced into output for the MathJax script to handle it.
However, HEVEA does not start any other action.
Thanks to this feature, users can have any (recognised by MathJax)
displayed math environment processed by MathJax. For instance,
the following source
\begin{mathjax} \begin{eqnarray*} z^2 & = & x^2 + y^2\\ \end{eqnarray*} \end{mathjax}
will be displayed as:
Finally, notice that a document that uses the explicit MathJax
constructs can be processed by LATEX, provided
it loads the mathjax.sty file present in HEVEA distribution.
This can be done simply by having the line \usepackage{mathjax}
in
teh document preamble. Then, HEVEA and LATEX will react appropriately
(see sections 2.3.2 and B.5.2).
Automatic mode is enabled when \usepackage[auto]{mathjax}
appears in the document preamble,
or when HEVEA is invoked as “hevea mathjaxauto.hva
…”.
In automatic mode, HEVEA will pass all mathematical text to MathJax. This mode seems by far the most practical, but beware:
\mbox
, are not handled
by MathJax.
By default HEVEA insert a reference to the “default”
MathJax script
with “default” configuration parameters.
Advanced users can change this setting by redefining the \jax@meta
command, which must contain the appropriate <script>
element.
See the file html/mathjax.hva
for details.
HEVEA distribution includes .hva packages that are implementations of LATEX packages. Packages described in the “Blue Book” (makeidx, ifthen, graphics —and graphicx!—, color, alltt) 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 [LATEX-bis], in your local LATEX installation or in a TeX CTAN-archive.
At the moment, most package options are ignored, except for the babel package, where it is essential.
HEVEA amsmath package defines some of the constructs of the
amsmath package. At the moment, supported constructs are
the cases
environment and matrix
environments [LATEX-bis, Section 8.4], the
environments for multi-line displayed
equations (gather
,
split
,…) [LATEX-bis, Section 8.5] and the
\numberwithin
command [LATEX-bis, Section 8.6.2].
HEVEA provides support for the amssymb symbols using
Unicode. I found Unicode equivalent for most symbols. However, a few symbols
remain undefined (e.g. \varsubsetneqq
).
The array
package is described in
[LATEX-bis, Section 5.3] and in the local documentation of modern LATEX
installations.
It is a compatible extension of LATEX arrays (see B.10.2).
Basically, it provides new column specifications
and a \newcolumntype
construct for user-defined column
specifications.
Table 1 gives a summary of the new column
specifications and of how HEVEA
implements them.
m{
width}
Equivalent to the p
column specification (the width 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.b{
width}
Equivalent to the p
column specification, except that the entries are bottom-aligned vertically.>{
decl}
Can be used before l
,c
,r
,p{
…}
,m{
…}
orb{
…}
. It inserts decl in front of the entries in the corresponding column.<{
decl}
Can be used after l
,c
,r
,p{
…}
,m{
…}
orb{
…}
. It inserts decl after entries in the corresponding column.!{
decl}
Equivalent to @{
decl}
Note that centered, top-aligned or bottom-aligned
in the vertical direction, do not
have exactly the same meaning in LATEX and in html. However, the
aspect is the same when all columns agree w.r.t. vertical alignment.
Ordinary column types (c
, l
and r
)
do not specify vertical alignment, which therefore becomes browser
dependent.
The >{
decl}
and <{
decl}
constructs permit the encoding of TEX \cases
macro as follows:
\def\cases#1{\left\{\begin{array}{l>{$}l<{$}}#1\end{array}\right.}
(This is an excerpt of the latexcommon.hva file.)
New column specifications are defined by the \newcolumntype
construct:
\newcolumntype{
col}[
narg]{
body}
Where col is one letter, the optional narg is a
number (defaults to 0), and body is built up with
valid column specifications and macro-argument references
(#
int).
Examples are:
\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}
The column specification
C means that entries will be typeset centered and using bold
font, while the column specifications E{
num}
stands for num centered columns. We get:
one | two | three | four |
five | six | seven | eight |
HEVEA implements column specifications with commands defined in the
\newcommand
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 macro.hva specific
file, overrides the document definition.
The tabularx
package [LATEX-bis, Section 5.3.5] provides a new tabular
environment tabularx
and a new column type X
. HEVEA
makes the former equivalent to tabular
and the latter
equivalent to p{
ignored}
. By contrast with the
subtle array formatting that the tabularx package performs,
this may seem a crude implementation. However, rendering is usually
correct, although different.
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 HEVEA 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 HEVEA 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.
The calc
package enables using traditional, infix, notation for
arithmetic operations
inside the num argument to the
\setcounter{
name}{
num}
and \addtocounter{
name}{
num}
constructs (see [LATEX-bis, Section A.4])
The calc package provides a similar extension of the syntax
of the len argument to the \setlength
and
\addtolength
constructs.
HEVEA does not implement this extension, since it does not
implement length registers in the first place.
The inputenc
package enables LATEX to process a file
according to various 8 bits encodings, plus UTF-8.
The one used encoding is specified as an option while loading the package
\usepackage[
encoding]{inputenc}
.
At the moment, HEVEA recognises ten latin encodings
(from latin1 to latin10),
the koi8-r encoding,
the ascii encoding,
four windows encodings, the applemac encoding, and the
utf8 encoding.
It is important to notice that loading the inputenc
package
alters the html document charset.
For instance if the latin9 input encoding is selected by:
\usepackage[latin9]{inputenc}
Then, the document charset is ISO-8859-15
, which is an
enhanced version of ISO-8859-1
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.
However, one can change the document charset (and the output
translator) by using the internal command \@def@charset
.
For instance, one can specify latin1 encoding, while
producing html pages in ascii:
\usepackage[latin1]{inputenc} %HEVEA\@def@charset{US-ASCII}
See section 8.6 for a more thorough description of html charset management.
The inputenc package also provides the
command \inputcoding{
encoding}
that
changes the input encoding at any time.
The argument encoding can be any of the options accepted
by \usepackage[
encoding]{inputenc}
.
The command \inputcoding
of HEVEA
follows the behaviour of its LATEX counterpart, it the sense
that it obeys scope rules.
Notice that \inputcoding
does not change the document output
encoding and charset.
HEVEA implements the following packages: latexsym amssymb, textcomp (a.k.a. “Text companion”) and eurosym (a nice € symbol in LATEX).
The comment package provides two commands,
\excludecomment
and \includecomment
, 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.
HEVEA supports several simultaneous indexes, following the scheme of the index package, which is present in modern LATEX distributions. This scheme is backward compatible with the standard indexing scheme of LATEX.
Support is not complete, but the most useful commands are available. More precisely, HEVEA knows the following commands:
\renewindex
commands that takes the same arguments and that can be
used to redefine previously declared indexes.
\newindex{default}{idx}{ind}{Index}
.
\index
command except that the information
extracted from arg goes to the tag index.
The tag argument defaults to default
, thereby yielding
standard LATEX behaviour for the \index
command without an
optional argument.
There also exists a stared-variant \index*
that Additionally
typesets arg.
default
.
The multind package is supported to some extend, but index is definitely to be preferred.
LATEX version of natbib is present in modern installations.
Implementation is quite complete and compatible
with version 8.0 of the natbib package
(with the keyval style command \setcitestyle
).
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.
HEVEA provides a slightly incomplete implementation of the
multibib package. The one non-implemented feature is the
simultaneous definition of more than one bibliography.
That is one cannot invoke \newcites
as follows:
\newcites{suf1, suf2}{Title1, Title2}
Instead, one should perform to calls to the \newcites
command:
\newcites{suf1}{Title1}\newcites{suf2}{Title2}
A basic implementation is provided. At the moment, you can
define one bibliography per included file and no toplevel
bibliography.
HEVEA implementation of this package recognises the option
sectionbib
and provides the command \sectionbib
to change the sectioning command introduced by bibliographies.
HEVEA offers support for the LATEX package babel. When it reads the command
\usepackage[lang-list]{babel}
it loads babel.hva, and sends it the saved lang-list. The file babel.hva then looks at each language (say x) in it, and loads x.hva, which offers support for the language x. As in LATEX, the last language in the list is selected as default. As an example the command
\usepackage[english,french,german]{babel}
would load babel.hva, then the files english.hva,french.hva,german.hva containing the respective definitions, and finally activate the definitions in german.hva and sets the current language to german.
The following babel commands for changing and querying the language work as in LATEX :
\selectlanguage
: to change the language
\iflanguage
: to branch after comparing with current language
The language specific details are described in the corresponding
.hva
file, just as in the .sty
file for LATEX. 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.
american | austrian | brazil | catalan |
check | croatian | danish | dutch |
english | esperanto | finnish | french |
galician | german | italian | magyar |
norsk | nynorsk | polish | portuguese |
romanian | russian | slovak | slovene |
spanish | swedish | turkish |
The languages for which .hva files are available with the distribution are english, french, german, austrian, czech and portuguese. These may need to be modified as not all accents and hyphenation techniques are supported.
They can be written/modified as simple TEX files (see the section B.16.1.1 on writing TEX macros for details). As an example, one may also take a look at the file french.hva, which describes the details for french.
Note how all definitions are inside the definition for
\french@babel
, which is the command that
\selectlanguage{french}
would call. Similar commands need to be
provided (i.e. \x@babel
in \x.hva
for language
x
).
Notice that it is wise to write the \x.hva
in plain ascii only.
Some definitions may involve specifying Unicode characters, for doing
so, using the \@print@u
is recommended (cf. Section 8.3).
The definition of Unicode characters can be found at
http://www.unicode.org/charts/.
Most language specific Unicode characters can be found in the first
few files.
LATEX source.
This package in fact provides a enhanced \verb
command that
can appear inside other command arguments.
This command is named \url
,
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
LATEX active characters:
This is a complicated url: \url{http://foo.com/~user#label%coucou}.
which gets typeset as: “This is a complicated url: http://foo.com/~user#label%coucou.”
The main use for the \url
command is to specify urls as arguments to
HEVEA commands for hyperlinks (see section 8.1.1):
\hevea{} home page is \ahrefurl{\url{http://hevea.inria.fr/}}
It yields: “HEVEA home page is http://hevea.inria.fr/”.
However the \url
command is fragile, as a consequence it
cannot be used inside \footahref
first argument (This is a
LATEX problem, not an HEVEA one).
The url package solves this problem by providing the
\urldef
command
for defining commands whose body is typeset by using \url
:
\urldef{\heveahome}{\url}{http://hevea.inria.fr/}
Such a source defines the robust command \heveahome
as the
intended url.
Hence the following source works as expected:
Have a look at \footahref{\heveahome}{\hevea{} home page}
It yields: “Have a look at HEVEA home page”.
Using \url
inside command definitions with a
#
i argument is a bad idea, since
it gives “verbatim” a rather random meaning.
Unfortunately, in some situations (e.g, no %
, no #
),
it may work in LATEX. By
contrast, it does not work in HEVEA. In such situations,
\urldef
should be used.
HEVEA implementation is somehow compatible at the “programming level”.
Thus, users can define new commands whose argument is understood
verbatim. The urlhref.hva style file
from the distribution
takes advantage of this to define the \url
command, so that it both
typesets an url and inserts a link to it.
\input{urlhref.hva} Have a look at \url{http://hevea.inria.fr/}
It yields “Have a look at http://hevea.inria.fr/”.
The urlhref.hva
style file (which is an HEVEA style file and not a LATEX
style file) can be adequate for bibliographic references,
which often use \url
for its typesetting power.
Of course, loading urlhref.hva only makes sense when
all arguments to \url
are urls…
These two packages provide new commands and environments for processing verbatim text. I recommend using moreverb rather than verbatim, since HEVEA implementation is more advanced for the former package.
I strongly recommend the listings package. Learning the user interface requires a little effort, but it is worth it.
HEVEA features a quite compatible implementation, please refer to the original package documentation. Do not hesitate to report discrepancies. Note that HEVEA does not produce very compact html in case you use this package. This can be cured by giving hevea the command-line option -O (see C.1.1.4).
The lstlisting environment is styled through
an homonymous style class (see 9.2 and 9.3) and
most lstlisting environments get translated to div
elements with the appropriate \getenvclass{lstlisting}
class,
which, by default is lstlisting.
A few points deserve mention:
font-family:monospace;
and white-space:pre;
, which, more or less,
specify non-proportional font and mandatory line breaks.
In case you replace lstlisting by another style class (by
\setenvclass{lstlisting}{
another one}
), 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 \lstnewenvironment
:
\lstdefinestyle{colors}{keywordstyle={\bf\color{blue}}, commentstyle={\em\color{magenta}}} \lstnewenvironment{clisting} {\setenvclass{lstlisting}{clisting}\lstset{language=C, style=colors}} {}The command
\lstnewenvironment{
name}{
starting
code}{
ending code}
is from the
listings package, with similar semantics.
In the starting code above, the fragment
\setenvclass{lstlisting}{clisting}
instructs HEVEA to
use the style class clisting locally (notice that it could just
be another name). The style class clisting is defined in
the document preamble as follows:
\newstyle{.clisting}{font-family:monospace;white-space:pre; border-left:solid black;padding-left:2ex;margin-left:2ex;}Typesetting a C listing with a black border on the left is then as simple as:
\begin{clisting} /* Compute, guess what! */ int fact(int n) { int r = 1 ; for ( ; n > 0 ; n--) { r *= n ; } return r ; } \end{clisting}The final result is:
div
elements.
Instead they get translated to one cell tables whose td
and table
elements
are styled through style classes lstlisting and
lstframe, respectively. Of course, those two style classes
follow the usual \setenvclass
/\getenvclass
mechanism.
That way, one can for instance center all framed listings by issuing
the following declaration in the document preamble:
\newstyle{.lstframe}{margin:auto;}Notice that the default style class lstframe is empty.
white-space:pre;
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 listings, you can, by issuing the command
\lstavoidwhitepre
in the document preamble. Then,
white-space:pre;
is not used any longer: spaces get rendered
by non-breaking space entities and line-breaks by <BR>
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.
LATEX source for the longtable and supertabular packages.
Those two packages provide LATEX users with the possibility to typeset tabular material over several pages [LATEX-bis, Section 5.4]. Of course, HEVEA does not care much about physical pages. Thus the supertabular and longtable environments are rendered more or less as tabular environments inside table environments.
The mathpartir package, authored by D. Rémy, essentially provides two features:
\inferrule
(and its starred variant) for
typesetting inferences rules.
We give a short description, focussing on HEVEA-related details. Users are encouraged to refer to the original documentation of the package.
In the following, comments on rule typesetting apply to HEVEA output and not to LATEX output.
In its LATEX version, the mathpar environment is a “paragraph mode for formulas”. It allows to typeset long list of formulas putting as many as possible on the same line:
\begin{mathpar}
A-Formula \and
Longer-Formula \and
And \and The-Last-One
\end{mathpar} |
|
In the example above, formulas are separated with \and
. The
LATEX implementation also changes the meaning of paragraph breaks
(either explicit as a \par
command or implicit as a blank line)
to act as \and
. It also redefines the command \\
as
an explicit line-break in the flow of formulas.
\begin{mathpar}
\int_0^2 xdx = \frac{3}{2}
\\
\int_0^3 xdx = \frac{5}{2}
\end{mathpar} |
|
The HEVEA version is simplistic:
Formulas are typeset in math display
mode,
\and
separators always produce horizontal space, while
\\
always produce line-breaks.
However, when prefixed by \hva
the meaning of explicit
separators is reversed: that is,
\hva\and
produces a line-break, while \hva\\
produces horizontal space.
Hence, we can typeset the previous example on two lines:
\begin{mathpar}
A-Formula \and
Longer-Formula \hva\and
And \and The-Last-One
\end{mathpar} |
|
It is to be noticed that the LATEX version of the package defines
\hva
as a no-op, so as to allow explicit instructions given to
HEVEA not to impact on the automatic typesetting performed by LATEX.
The \inferrule
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
\\
.
A simple example of its use is
\inferrule [label] {one \\ two \\ three \\ or \\ more \\ premises} {and \\ any \\ number \\ of \\ conclusions \\ as \\ well}
which gives the following rendering:
|
Again, HEVEA is simplistic. Where LATEX performs
actual typesetting, interpreting \\
as horizontal or
vertical breaks, HEVEA always interpret \\
as an
horizontal break. In fact HEVEA interpret all separators
(\\
, \and
) as horizontal breaks, when
they appear in the arguments of the \inferrule
command.
Nevertheless prefixing separators with \hva
yields vertical
breaks:
\inferrule
{aa \hva\\ bb}
{dd \\ ee \\ ff} |
|
The color of the horizontal rule that separates the premises and
conclusions can be changed by redefining the command
\mpr@hhline@color
. This color must be specified as a low-level
color (cf. Section B.14.2.2).
By default, lines are centered in inference rules. However, this can be changed either by using \mprset{flushleft}
or \mprset{center}
, as shown below.
$$\mprset{flushleft}
\inferrule
{a \\ bbb \hva\\ ccc \\ dddd}
{e \\ ff \hva\\ gg}
$$ |
|
The mathpartir package provides a starred variant
\inferrule*
. In LATEX, the boxes
produced by \inferrule
and \inferrule*
differ as regards
their baseline, the second being well adapted to derivation trees.
All this is irrelevant to HEVEA,
but \inferrule*
remains of interest because of its interface:
the optional argument to the \inferrule*
command is a list of
key=value pairs in the style of
keyval.
This makes the variant command much more flexible.
|
Additionally, the value-less key center
centers premises and
conclusions (this is
the default), while flushleft
commands left alignment of
premises and conclusions (as \mprset{flushleft}
does).
Other keys defined by the LATEX package exist and are parsed, but
they perform no operation.
As an example, the code
produces the following output:
|
|
This package should be present in modern latex installations. Basically, the package defines a boolean register pdf, whose value is true for tools that produce PDF (such as pdflatex) and false for tools that produce DVI (such as latex).
The hevea version of the package simply defines the boolean
register pdf with initial value true. Command-line option
-pdf is also added to imagen command-line
options (by using the command \@addimagenopt
, see
Section 10.7). As a result, imagen will
normally call pdflatex in place of latex.
In case standard latex processing in imagen is
wished, one can issue the command \pdffalse
after loading the
ifpdf package and before \begin{document}
. Then, no
command line option is added.
Hence, to achieve latex processing of the image
file, while still loading the ifpdf package, one writes:
\usepackage{ifpdf} %HEVEA\pdffalse
HEVEA features an implementation of Andrew Seagar’s technique for Thai in LATEX, by the means of the package thai.hva in the distribution.
As regards input encoding, Thai users of HEVEA could (perhaps) use
\usepackage[utf8]{inputenc}
.
However, the typesetting of Thai is more subtle than just proper
characters. For that reason, Thai in LATEX is better performed by
another technique, which HEVEA supports. See this specific
document.
The hanging package is implemented. HEVEA implementation consists of no-ops, except for the hangparas environment, which is partially implemented. Assume the following usage of hangparas:
\begin{hangparas}{
wd}{
n}
…\end{hangparas}
where wd is a length that makes sense both for LATEX and CSS (typically 2ex). Then html output will reproduce LATEX output for n=1, regardless of the given value of argument n. That is, in any paragraph inside the environment, all lines except the first get indented by wd.
The cleveref package
attempts (and mostly succeeds) typesetting references
cleverly. Its main feature is a \cref
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 HEVEA implementation is quite complete, but it does not support some
of the subtleties of the LATEX implementations, especially as regards
customisation.
The fancyverb and colortbl packages are partly implemented.
The xspace package is implemented, in simple cases, rendering is satisfactory, but beware: HEVEA differs significantly from TEX, and discrepancies are likely.
The chngcntr package is implemented. This package provides commands to connect (and disconnect) counters once they are created (see http://www.tex.ac.uk/cgi-bin/texfaq2html?label=addtoreset).
The import package is partially implemented: all starred commands are missing.
The booktabs package is implemented. This package provides nicer rulers in tables as specific commands. HEVEA defines those as no-ops.
Part C |
The hevea command has two operating modes, normal mode and filter mode. Operating mode is determined by the nature of the last command-line argument.
The hevea command interprets its arguments as names of files and attempts to process them. Given an argument filename there are two cases:
In all attempts, implicit filenames are searched along hevea search path, which consist in:
The hevea library directory is fixed at compile-time
(this is where hevea library files are installed)
and typically is /usr/local/lib/hevea.
However, this compile-time value can be overridden
by setting the HEVEADIR shell environment variable.
In all cases, the value of hevea library directory can
be accessed from the processed document as the value of the command
\@hevealibdir
.
If the last argument has an extension that is different from
.hva or has no extension,
then it is interpreted as the name of the main input file.
The main input file is the document to be translated and normally
contains the \documentclass
command.
In that case two basenames are defined:
-o
option (see below).
HEVEA will attempt to load the main input file.
Ancillary files from a previous run of LATEX
(i.e. .aux, .bll and .idx files)
will be searched as basein.
ext.
The output base name governs all files produced by HEVEA.
That is, html output of HEVEA normally goes to the file
baseout.html,
while cross-referencing information goes into
baseout.haux. Furthemore,
if an image file is generated (cf. section 6), its
name will be baseout.image.tex.
Thus, in the simple case where the hevea command is invoked as:
# hevea file.tex
The input basename is file and the output basename also is file. The main input file is searched once along hevea search path as file.tex. html output goes into file file.html, in the current directory. In the more complicated case where the hevea command is invoked as:
# hevea ./dir/file
The input base name is ./dir/file and the output basename is file. The main input file is loaded by first attempting to open file ./dir/file.tex, then file ./dir/file. html output goes into file file.html, in the current directory.
Finally, the output base name can be a full path, but you have to use option -o. For instance, we consider:
# hevea -o out/out.html file.tex
Then, html output goes into out/out.html — notice that directory out must exist. Furthermore, hevea output base name is out/out. This means that hevea generates files out/out.haux, out/out.image.tex etc.
The article.hva, seminar.hva, book.hva and
report.hva
base style files from HEVEA library are special.
Only the first base style file is loaded and the
\documentclass
command has no effect when a base style file is
already loaded. This feature allows to override the document base style.
Thus, a document file.tex can be translated using the
article base style as follows:
# hevea article.hva file.tex
If there is no command-line argument, or if the last command-line
argument has the extension .hva, 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 \begin{document}
.
In other words hevea acts as a filter.
Please note that this operating mode is just for translating
isolated LATEX constructs.
The normal way to translate a full document file.tex
being
“hevea
file.tex
” and not
“hevea <
file.tex >
file.html
”.
The hevea command recognises the following options:
div
and p
are bordered,
while the structure of displayed material is also shown.
The following options control the html code produced by hevea. By default, hevea outputs a page encoded in US-ASCII with most symbols rendered as html or numerical Unicode entities.
<PRE>
… </PRE>
, which are otherwise performed.
The following options select and control alternative output formats (see section 11):
Part A of this document is a tutorial introduction to HEVEA, while Part B is the reference manual of HEVEA.
The hacha command interprets its argument base.html as the name of a html source file to cut into pieces.
It also recognises the following options:
\t
file” line per anchor.
This information may be needed by other tools.
Section 7 of the user manual explains how to alter HACHA default behaviour.
The program esponja is part of HEVEA and is designed to optimise hevea output. However, esponja can also be used alone to optimise text-level elements in html files. Since esponja fails to operate when it detects incorrect html, it can be used as a partial html validator.
The program esponja interprets its arguments as names of files and attempt to process them. It is important to notice that esponja will replace files by their optimised versions, unless instructed not to do so with option -n.
Invoking esponja as
# esponja foo.html
will alter foo.html. Of course, if esponja does not succeed in making foo.html any smaller or if esponja fails, the original foo.html is left unchanged. Note that this feature allows to optimise all html files in a given directory by:
# esponja *.html
The command esponja recognises the following options:
The program bibhva is a simple wrapper, which basically forces bibtex into accepting a .haux file as input and producing a .hbbl file as output. Usage is bibhva bibtex-options basename.
The command imagen is a simple shell script that translates a LATEX document into many .png images. The imagen script relies on much software to be installed on your computer, see Section C.4.1.
It is a companion program of HEVEA, which must have been previously run as:
In both cases, base is HEVEA output basename. When told to do so (see section 6) HEVEA echoes part of its input into the base.image.tex file.
The imagen script should then be run as:
The imagen script produces one basennn.png image file per page in the base.image.tex file.
This is done by first calling latex on base.image.tex, yielding one dvi file. Then, dvips 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 dvips. Postscript files are interpreted by ghostscript (gs) that outputs ppm images, which are then fed into a series of transformations that change them into .png files.
The imagen script recognises the following options:
The first three options enable users to correct some misbehaviours. For instance, when the document base style is seminar, image orientation may be wrong and the images are too small. This can be cured by invoking imagen as:
Notice that hevea calls imagen by itself,
when given the command-line option -fix.
In that situation, the command-line options of imagen can
be controlled from source file by using the
command \@addimagenopt
(see Section 10.7).
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 Makefile’s for similar situations.
We translate a file doc.tex that requires a specific style file doc.hva. The file is first translated into doc.html by hevea, which also reads the specific style file doc.hva. Then, hacha cuts doc.html into several, doc001.html, doc002.html, etc. also producing the table of links file index.html.
# hevea -fix doc.hva doc.tex # hacha doc.html
Thanks to the command-line option -fix, hevea runs the appropriate number of times automatically. In case hevea produces a non-empty doc.image.tex file, then hevea calls imagen by itself (because of option -fix). Hence, the above sequence of two commands is also appropriate in that situation.
In case some problem occurs, it is sometime convenient to run imagen by hand. It is time not to use the option -fix.
# rm -f doc.image.tex # hevea doc.hva doc.tex
Now, hevea normally has shown the imagen
command line that it would have run, if it had been given
the option -fix.
For instance, if doc.hva includes \input{gif.hva}
, then
hevea shows the following warning:
HeVeA Warning: images may have changed, run 'imagen -gif doc'
Now, one can run imagen as it should be.
It is sometime convenient not to clobber the source directory with numerous target files. It suffices to instruct hevea and hacha to output files in a specific directory, say doc.
# hevea -fix -o doc/doc.html doc.hva doc.tex # hacha -o doc/index.html doc/doc.html
Notice that hevea does not create the target directory doc: it must exist before hevea runs. Again, in case hevea calls imagen, image generation should proceed smoothly and the final files doc001.png, doc002.png, … should go into directory doc.
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 (index.html), contents files (doc001.html, doc002.html, etc.) and images (doc001.png, doc002.png, etc.), one should not forget the arrow images and the style sheet generated by hacha (contents_motif.gif, next_motif.gif, previous_motif.gif and doc.css).
As a consequence, producing all files into the subdirectory doc may be a good idea, since then one easily install all relevant files by copying doc to a public destination.
# cp -r doc $(HOME)/public_html
However, one then also installs the auxiliary files of hevea, and hevea output file doc.html, which is no longer useful once hacha has run. Hence, those should be erased beforehand.
# rm -f doc/doc.h{tml,aux,ind,toc} doc/doc.image.tex # cp -r doc $(HOME)/public_html
Here is a typical Makefile, which is appropriate when no images are produced.
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
Note that the clean rule removes all the doc001.html, doc002.html, etc. and doc.css files produced by hacha. Also note that make clean also removes the doc.haux, doc.hind and doc.htoc files, which are HEVEA auxiliary files.
When the image file feature is used, one can use the following, extended, Makefile:
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
Observe that the clean rule now also gets rid of doc.image.tex and of the various files produced by imagen.
With the following Makefile, hevea, imagen, hacha all output their files into a specific directory DIR.
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)/*
The above Makefile directly produces html and PNG files
into the final directory $(HOME)/public_html/$(DOC)
.
The new partialclean entry erases files that are not
useful anymore, once imagen and hacha have
performed their tasks.
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.
... #document base name DOC=doc DIR=$(DOC) BASE=$(DIR)/$(DOC) INSTALLDIR=$(HOME)/public_html/$(DOC) ... install: partialclean cp $(DIR)/* $(INSTALLDIR) ...
By default, HEVEA does not anymore use the FACE=symbol
attribute to the <FONT ...>
tag. As a consequence, browser
configuration is no longer needed.
HEVEA now extensively outputs Unicode entities. This first means that HEVEA targets modern browsers with decent unicode support, and only those.
In case your browser is recent and that you nevertheless experience display problems on HEVEA-generated pages, see the excellent Alan Wood’s Unicode Resources. It may help to understand display problems and even to solve them by configuring browsers or installing some fonts.
HEVEA home page is http://hevea.inria.fr/. It contains links to the on-line manual and to the distribution.
The author can be contacted at Luc.Maranget@inria.fr.
HEVEA can be freely used and redistributed without modifications. Modifying and redistributing HEVEA implies a few constraints. More precisely, HEVEA is distributed under the terms of the Q Public License, but HEVEA binaries include the Objective Caml runtime system, which is distributed under the Gnu Library General Public License (LGPL). See the LICENSE file for details.
The manual itself is distributed under the terms of the Free Document Dissemination Licence.
The programs hevea and hacha are written in Objective Caml. 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 HEVEA home page.
HEVEA users may instruct the program not to process a
part of the input (see section 6). Instead, this part is
processed into a bitmap file and HEVEA outputs a link to the image file.
LATEX source is changed into .png
images by the imagen
script, which basically calls, LATEX, dvips,
ghostscript
and the convert command from the image processing package
ImageMagick.
To benefit from the full functionality of HEVEA, you need all this software. However, HEVEA runs without them, but then you will have to produce images by yourself.
The details are given in the README file from the distribution. Basically, HEVEA should be given a library directory. The installation procedure stores the hevea.hva and base style files in this directory. There are two compilation modes, the opt mode selects the native code OCaml compiler ocamlopt, while the byte mode selects the bytecode OCaml compiler ocamlc. In HEVEA case, ocamlopt produces code that is up to three times as fast as the one produced by ocamlc. Thus, default compilation mode is opt, however it may be the case on some systems that only ocamlc is available.
Note that, when installing HEVEA from the source distribution, the hevea.sty (and mathjax.sty) style files are simply copied to HEVEA library directory. It remains users (and package maintainers) responsibility to make those files accessible to LATEX.
This short section gives pointers to a few other translators. I performed not extensive testing and make no thorough comparison.
lex
output is available).
Additionally, TTH insist on not using any kind of LATEX
generated information and will show proper cross-reference labels,
even when no .aux file is present.
TTH output is a single document,
whereas HACHA can cut the output of HEVEA into several files.
(however there exists a commercial
version of TTH that provides this extra functionality).
TTH can be found at
The following people contributed to HEVEA development:
alltt
environment.
-text
and -info
output modes (see section 11).
|
|
This document was translated from LATEX by HEVEA.