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.