Bert Bos,
style activity leadCopyright © 1994–2022 W3C® Privacy policy
The CSS level 2 specification and the various modules of CSS level 3 have specific mark-up beyond HTML. That mark-up allows the different kinds of information (names of properties, informative notes, examples, etc.) to be styled appropriately, but above all it allows various automated tools to read the specifications. Those tools can make an index of all properties, extract a machine-readable grammar, check all examples, etc. The following sections contain the details.
The mark-up of CSS2 and CSS3 are not the same. The CSS3 mark-up is several years younger and is an evolution of the CSS2 one. It is both more compact and richer in semantics.
The mark-up in the published texts of CSS is also not exactly the same as the mark-up that the authors used when writing the text. The latter has abbreviations that are expanded automatically before a document is published. For example, the authors almost never create links. Instead, they include a tag or a special character that indicates the role of a word (a property name, a technical term, a bibliographic reference, etc.) and each such word is automatically linked to its definition.
Less typing means fewer errors and more time to concentrate on the contents. Also, because it is the computer that adds the links and much of the oher mark-up, the final documents are more consistent. At the same time, the document the authors work on is still a complete HTML document that can be edited and viewed in any normal HTML tool. It just has fewer links and a little fewer colors than the final document.
Such consistent documents have several advantages. For example, the table of content, the index and the list of properties are all created automatically. Also, various automatic checks can be performed before publishing a document, e.g.: are all properties that occur in the text also defined? are all grammars complete? are all examples valid? are all bibliographic references defined?
The way the authors write the CSS3 modules is not always the way the documents appear once published. The mark-up that the authors use is included here, even though readers never see it.
Two important characteristics of this mark-up (and of the programs that work on it) are:
Properties are single words enclosed in single straight quotes, e.g.,
'font' 'text-indent'
That is all that the author has to type. Such quoted words automatically get enclosed in an <a> element with class “property” that links to the definition of the property:
<a class=property href="#font0">'font'</a> <a class=property href="#text-indent">'text-indent'</a>
All occurrences of property names are marked-up like this, except when they occur in an example or a some CSS code. The definition of the property also doesn't get quotes.
Inline CSS is also enclosed in single quotes or in two pairs of single quotes, e.g.:
'color: blue' ''display: none''
The author only types the quotes, the text is automatically wrapped in a <span> with class “css” during publication. If the quotes were doubled, one pair is removed:
<span class=css>'color: blue'</span> <span class=css>'display: none'</span>
CSS keywords (other than property names) must be typed by the author with a double pair of single quotes, in order to distinguish them from properties:
''none''
The result in the published document is a word with single quotes and a <span> as above:
<span class=css>'none'</span>
Value types are enclosed in angle brackets and in a <var> element. E.g.:
<var><integer></var> <var><color></var> <var><percentage></var>
[The mark-up of the definitions of such types has not been decided yet.]
The defining instance of a term is enclosed in a <dfn> element (which means it will also end up in the alphabetic index):
<dfn>dog</dfn>
To refer to the definition, the author only has to enclose the usage in some inline element (<em>, <span>, etc.) and the usage will automatically be wrapped in an <a> element that links to the defining instance.
If the usage and definition aren't literally the same, the title attribute can be used to give the exact term:
<dfn title="dog">dogs</dfn> <em>dog</em> <span title="dog">dog</span>
The result looks like this:
<dfn id=dogs0 title="dog">dogs</dfn> <em><a href="#gogs0">dog</a></em> <span title="dog"><a href="#dogs0">dog</a></span>
Property definitions consists of a table like this:
| Name: | padding |
|---|---|
| Value: | [ <length> | <percentage> ]{1,4} |
| Initial: | (see individual properties) |
| Applies to: | all elements |
| Inherited: | no |
| Animatable: | yes |
| Percentages: | width* of containing block |
| Media: | visual |
| Computed value: | see individual properties |
| Canonical order: | N/A |
| *) if the containing block is horizontal, otherwise the height | |
Which is created like this:
<table class=propdef>
<tr>
<th>Name:
<td><dfn>padding</dfn>
<tr>
<th>Value:
<td>[ <var><length></var>
| <var><percentage></var> ]{1,4}
<tr>
<th>Initial:
<td>(see individual properties)
<tr>
<th>Applies to:
<td>all elements
<tr>
<th>Inherited:
<td>no
<tr>
<th>Animatable:
<td>yes
<tr>
<th>Percentages:
<td>width* of containing block
<tr>
<th>Media:
<td>visual
<tr>
<th>Computed value:
<td>see individual properties
<tr>
<th>Canonical order:
<td>N/A
<tr>
<td colspan=2 class=footnote>*) if the
containing block is horizontal, otherwise
the height
</table>
The table has a class of “propdef” and the name of the property that is being defined is enclosed in <dfn> (but not in single quotes). When the document is published, an ID attribute is automatically added to the <dfn> and the property name is added to the alphabetical index and the index of properties.
The definition of descriptors (the characteristics of fonts, inside an @font-face rule) are similar. They look like this:
| Name: | x-height |
| Value: | <number> |
| Initial: | undefined |
| Media: | visual |
The table has a class of “descdef” and looks like this:
<table class="descdef"> <tr><td>Name: <td><dfn>x-height</dfn> <tr><td>Value: <td><number> <tr><td>Initial: <td>undefined <tr><td>Media: <td>visual </table>
There are two kinds of bibliographic references: normative ones and informative ones. The author types the former as
[[!CSS3BOX]] [[!UNICODE4]]
where “CSS3BOX” and “UNICODE4” are the labels of entries that are defined in an external refer(1) database. Informative references are the same, but without the exclamation mark:
[[SELECT]] [[MEDIAQ]]
It is possible to add entries to the bibliography without any occurrence of a corresponding [[…]] in the text, by putting the label inside {{…}} in a comment:
<!-- {{CSS3BG}} -->
In the published document, [[…]] references are expanded into links to the bibliography as follows:
<a href="#CSS3BOX"
rel=biblioentry>[CSS3BOX]<!--{{CSS3BOX}}--></a>
<a href="#UNICODE4"
rel=biblioentry>[UNICODE4]<!--{{UNICODE4}}--></a>
<a href="#SELECT"
rel=biblioentry>[SELECT]<!--{{SELECT}}--></a>
<a href="#MEDIAQ"
rel=biblioentry>[MEDIAQ]<!--{{MEDIAQ}}--></a>
The reason for the inclusion of the comment is that it allows the final document to be edited, without removing the <a> elements, and the bibliography to be regenerated, despite the lack of double square brackets. (In theory, published specifications are never changed, but practice and theory aren't always the same…)
The bibliography is generated automatically from the bibliographic references and the data in an external bibliographic database. The result is inserted at the place of the following two comments in the source:
<!--normative--> <!--informative-->
The former for the list of normative references, the latter for the informative references. The result in the published document looks like this:
<!--begin-normative-->
<!-- Sorted by label -->
<dl class=bibliography>
<dt style="display: none">
<!-- keeps the doc valid if the DL is empty -->
<!---->
<dt id=CSS3LINE>[CSS3LINE]
<dd>Michel Suignard; Eric A. Meyer. <cite>CSS3
module: line.</cite> 15 May 2002. W3C Working
Draft. (Work in progress.) URL: <a
href=".../WD-css3-linebox-20020515">
.../WD-css3-linebox-20020515</a>
</dd>
<!---->
<dt id=CSS3SYN>[CSS3SYN]
<dd>L. David Baron. <cite>CSS3 module:
Syntax.</cite> 13 August 2003. W3C
Working Draft. (Work in progress.) URL: <a
href=".../WD-css3-syntax-20030813">
.../WD-css3-syntax-20030813</a>
</dd>
<!---->
</dl>
<!--end-normative-->
The simplest mark-up that puts a word or phrase in the alphabetic index is a <span> with class “index”:
<span class=index>containing block</span>
When the term should appear in the index differently from the way it appears in the text, the title attribute holds the text for the index:
<span class=index title="box">boxes</span> <span class=index title="inherited value">inherit a value</span>
When the term should appear in the index under two or more different entries, the title attribute contains the various entries separated by vertical bars:
<span class=index title="outer edge|margin edge"> outer (margin) edge</span>
When the term should appear as a sub-entry of another term, the title attribute contains the entry and the sub-entry separated by two exclamation marks:
<span class=index title="edge!!outer"> outer edge</span> <span class=index title="edge!!inner"> inner edge</span>
Of course, sub-terms and multiple terms can be combined:
<span class=index title="edge!!outer|edge!!margin"> outer edge</span>
If an occurrence is considered the defining instance of the term, the element <dfn> replaces the span and the class is omitted:
<dfn>padding</dfn>
The title attribute can be put on the <dfn> element exactly as on the <span>.
All index terms automatically get an ID attribute.
The alphabetic index that is generated from the index terms is automatically inserted in the document at the place of the following comment:
<!--index-->
The expanded result looks like this:
<!--begin-index--> <ul class=indexlist> <li>anonymous, <a href="#anonymous0"><strong>#</strong></a> <li>'writing-mode', <a href="#writing-mode"><strong>#</strong></a> </ul> <!--end-index-->
Examples are marked-up with a class of “example” and they can be either <div> or <pre>. The former if the example includes explanatory text or images, the latter if the example consists of nothing but code:
<div class=example> ... </div> <pre class=example> ... </pre>
Figures normally have a caption. The figure and the caption are enclosed in a <div> with class “figure” like this:
<div class="figure"> <p><img src="box.png" alt="Boxes have four sides [schema]"> <p class=caption>Relation between four… </div>
The class “note” indicates a non-normative note. It is typically used on a <p>, <div> or <span>.
<p class=note>Note that the…
Section numbers are usually added automatically. They are enclosed in a span with class “secno” and look like this:
<span class=secno>1. </span>
Subsections are numbered 1.1., 1.1.1, etc.
A CSS3 module has only one <h1> element, which is the same as the <title> element (apart possibly from punctuation and abbreviations).
The table of contents is automatically generated and inserted at the place of the following comment:
<!--toc-->
The result looks like this:
<!--begin-toc--> <ul class=toc> <li><a href="#dependencies"><span class=secno>1. </span>Dependencies on other modules</a> <li><a href="#introduction"><span class=secno>2. </span>Introduction</a> </ul> <!--end-toc-->
[To do]
Since 2014, most CSS specifications are generated with Tab Atkin's Bikeshed.
Before that, the CSS WG used a variety of private tools to process, test and otherwise use the specifications that are marked-up as above. Some tools are CGI scripts, some are Perl programs or sed scripts, combined with various C tools in the HTML-XML utilities.
Bert Bos,
style activity lead