## 9 Support for style sheets

- Overview
- Changing the style of all instances of an environment
- Changing the style of some instances of an environment
- Which class affects what
- A few examples
- Miscellaneous

### 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 other, discrete, maybe unnoticeable, similar enhancements.

However, style sheets mostly offer an additional mechanism to customize 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:

### 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. Thus, these commands 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.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.

### 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.

# Title

### Date

### Author

#### 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 `\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: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 `\begin{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.

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&nbsp;A
    <UL CLASS="toc2"><LI CLASS="li-itemize">
    Chapter&nbsp;I
    <UL CLASS="toc3"><LI CLASS="li-itemize">
    Section&nbsp;I.1
    <LI CLASS="li-itemize">Section&nbsp;I.2
      ...
    </UL>
    </UL>

### 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 Producing an external style sheet

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 behavior, it suffices to set the value of the boolean register `externalcss` to true, by issuing the command `\externalcsstrue` in the premable of the source document. Notice that HEVEA output still can be processed by HACHA, with correct behavior.

#### 9.6.3 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. 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).

#### 9.6.4 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 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.