9 Support for style sheets
9.1 Overview
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 others, discrete, maybe
unnoticeable, similar enhancements.
However, style sheet mostly provides HEVEA users with an additional
mechanism to customize their documents. 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 get 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 package (such as, for
instance fancysection, see Section B.16.5) may
define them.
If you wish to change the style of section headers, loading the
fancysection package is the most appropriate solution.
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 class
“subsection” (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 :
A styled subsection heading
The following points are worth noticing:
-
To yield some effect,
\newstyle
commands must appear
in the document preamble, i.e. before \begin{document}
.
- Arguments to
\newstyle
commands are processed.
- The hevea package defines all style sheet related
commands as no-ops. As a consequence, these command do not affect
document processing by LATEX.
9.2 Changing the style of all instances of an environment
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.
9.3 Changing the style of some instances of an environment
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 colors 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.
9.4 Which class affects what
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.12), lstlisting
(cf. Section B.17.11), etc.
All sectioning commands (\part
, \section
etc.)
output H<
n>
block-level elements, which are styled
through style classes named part, section, etc.
Users are advised not to alter those styles
themselves, but rather to rely on the package fancysection
(Section B.16.5).
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.
9.5 A few examples
9.5.1 The title of the document
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>
<H1 ALIGN=center CLASS="titlemain">..title here..</H1>
<H3 ALIGN=center CLASS="titlerest">..author here..</H3>
<H3 ALIGN=center 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;padding:2ex;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.
9.5.2 Enclosing things in a styled DIV
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 \open{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:marron}
The intended behavior 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}
-
A ruled itemize
- With two items.
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 |
We have two problems here: first the text is black, and second,
the brown background extend on all the width of the displayed page.
The second problem is 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.
English |
French |
Good Morning |
Bonjour |
Thank You |
Merci |
Good Bye |
Au Revoir |
|
As regards text color, one can rely on explicit color change.
For instance, one can add a \maroon
declaration, after the
opening command \open{divstyle}{ruled}
.
Then we get:
English |
French |
Good Morning |
Bonjour |
Thank You |
Merci |
Good Bye |
Au Revoir |
|
But then, we do not use style sheets anymore.
9.5.3 Enclosing things in a styled cell
Given the differences in styling DIV
and table elements, HEVEA
provides a mean to issue a one-cell TABLE
element with one cell,
with style applied to the outer TABLE
element and the inner
TD
element.
For instance, the previous example can be styled as follows, thereby
avoiding the outer tabular environment.
\begin{center}
\begin{cellstyle}{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{cellstyle}
\end{center}
English |
French |
Good Morning |
Bonjour |
Thank You |
Merci |
Good Bye |
Au Revoir |
|
9.5.4 Styling the itemize environment
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.
-
Part A
-
Chapter I
- Chapter II
-
Section II.1
- Section II.2
- Chapter III
- Part B
-
Chapter IV
-
Section IV.1
-
Section IV.1.a
- Section IV.1.b
- Section IV.2
- Chapter V
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>
9.6 Miscellaneous
9.6.1 HACHA and style sheets
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.
9.6.2 Linking to external style sheets
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.
When several \loadcss
commands are issued. The given external
style sheets appear in the output, following source order.
Notice that the argument of \loadcssfile
are
are 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.9).
9.6.3 Limitations
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 does 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.