|
"http://www.w3.org/TR/REC-html40/loose.dtd">
A note on style
Spacing in the HTML document reflects the original source spacing.
More precisely, any sequence of spaces is outputed as one
space, whereas a single newline is replicated in the output.
However one blank line (i.e., two newlines in a row) or more
introduce a paragraph break.
Whether the tabulation character is a space or not
is random, so avoid tabs in your source document.
Paragraphs are rendered by a blank line and there is no paragraph
indentation.
HEVEA is a bit simplistic in breaking paragraphs and extra paragraph
breaks may be present in the final HTML documents.
This can usually be corrected by modifying the source, without
altering LATEX output. For instance, some blank line before or
after a comment or macro definition can be deleted.
Space after macros with no argument is skipped (as in LATEX) ---
however this is not true in math mode, as explained in
section 3.2.1 below.
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 behavior 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}
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.
| 3.2.1 |
Spacing in math mode |
|
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.
\alpha\rightarrow\beta |
: |
a®b |
\alpha \rightarrow \beta |
: |
a ® b |
Figure 1: Symbol font in X
Outputting symbols is performed using an HTML extension:
the now standard FACE attribute to the FONT
element instruct the browser to switch to a symbol font.
HEVEA assumes this choice for the symbol font to be
as shown by figure 1.
A browser correctly displays HEVEA symbols when
figure 1 resembles the HTML page located
at symbol.html in HEVEA on-line documentation
directory.
Some browsers
do not know about symbol fonts by default and
need to be configured (see section C.2).
For authors that do not want to generate 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 -nosymb flag.
Replacement text is in English, unless
HEVEA is also given the -francais flag. In that case
replacement text is in French.
For instance. the ``Î'' symbol is replace by ``in'' (or by ``appartient
à'' if French mode is selected).
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:
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 -v option comand line option twice, which
instructs HEVEA to add a
border to the TABLE elements introduced by displays.
| 3.2.4 |
Arrays and display mode |
|
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.
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:
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 behavior 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, the calligraphic letters (\mathcal)
are rendered in red (<FONT COLOR=red>), and the small caps
(\scshape) are rendered in bold font (<B>).
If you are not satisfied with HEVEA rendering of text style
declarations, then you
can choose your own, by redefining the \cal and \sc
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 9.2 for a more thourough descriton 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.4),
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.
|
