Support for style sheets
Author: Luc Maranget

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

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

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

# 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: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}

- 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

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.

English | French
Good Morning | Bonjour
Thank You | Merci
Good Bye | Au Revoir

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

#### 9.5.3 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
    - Section I.1
    - Section I.2
  - 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&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 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.

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