Jesper Tverskov, April 27, 2007

The TOC freak show at W3C and OASIS

The W3C and the OASIS web sites have hundreds of specs with TOCs designed in all sorts of ways. Most of them are pseudo web design using break elements and non breaking spaces for indention or CSS margin-left. They all have additional problems like including the number of the list item in the link, or not having a period after the first level.

I have also published a tutorial for how to generate and style a Table of Contents, TOC for XHTML with XSLT. The sections about XHTML markup and CSS should be useful for most web designers. In the "freak show" article, you are reading, we document how bad most TOCs are today as an introduction to the tutorial.

1. The TOCs at W3C

The specs of W3C are true web documents with unique functionality that makes them better online than printed. Even if we dislike the specs as documents, we must admit that they are ambitious and inspiring experiments of cross linking. The TOCs of the specs are a mixed bag from a webdesign point of view.

1.1 CSS

The CSS level 1 spec has one of the worst TOCs ever made. The number is included as content of the a element and with too much whitespace between the number and the rest of the content. No indention of the levels. The first level has no period.

The source code of the CSS spec is a shame of br elements and none breaking spaces for indention.

1.2 XSLT

The TOC of XSLT 2.0 looks OK except that I prefer a period after the first level.

The source code of the XSLT 2.0 spec is still pseudo web design of br elements and none breaking spaces for indention.

Note that the content of the headers is used for fragment identifier. This is not best practice. We could easily have several subsections with the same heading content. In an article about holiday destinations we could have several headings with the content "Places to see". Always go for generic solution that will work for any document.

1.3 XHTML

At a first glance the TOC of XHTML 1.0 looks perfect also having a period after the first level. Then you spot that all levels ends with a period. How difficult can it be!

The markup of the TOC of the XHTML 1.0 spec uses nested ul/li elements.

Note that only parts of the content of the headings are used for fragment identifiers. We must check all headings over and over again for not making up the same fragment identifier twice. It is much better to use the section number.

1.4 SMIL

The TOC of the SMIL 2.1 spec uses period after first level but the numbers are included in the a elements making the underlining too dominating. The first level is enough emphasized by being the first level. It is not necessary to make it also strong.

The TOC of SMIL 2.1 uses nested ul/li elements. We must live with the fact that the old lax SGML tradition of HTML 4.1 "loose" is used. The list elements are not terminated.

See my tutorial for a discussion of ordered contra unordered lists.

1.5 OWL

In the TOC for the OWL Web Ontology Language Reference the numbers are included as content of the a element making the underlinings too long but at least we have a period after the first level.

The markup uses nested ul/li elements. Parts of the content of the heading is used for fragment identifier. It is much better to use the always unique section number.

In the source code above and in all other examples in this article, the number is added as content. For a discussion of how and when to use CSS counters to generate the numbers, see my tutorial.

1.6 SISR

The TOC for Semantic Interpretation for Speech Recognition is the best I have been able to find at the W3C web site. I would have liked a period after the first level.

The markup is made with nested list elements. The generated heading numbers are also used for ID and fragment identifier. This is one of the very few TOCs at W3C doing it right.

Considering that the spec was published 2007-04-05, it should not have been necessary to use class attributes in all the list elements of the TOC. See my tutorial for much nicer markup and CSS. Likewise we should use id attributes in the heading element (not shown) and not the deprecated anchor element with id and name attribute.

2. The TOCs at OASIS

OASIS is the other big standard organization for web technologies. The web documents at OASIS is not even mediocre from a web design point of view but disgustingly bad. I have always tried to ignore OASIS for that reason. We will use two TOC examples from OASIS in order to present some of the worst TOCs of the web.

2.1 UBL

It is nice that the TOC of the UBL 2.0 spec has a period after first level, but less nice that it always has a period after the number. And the numbers should not have been included in the a elements giving us very long underlinings.

The source code is a chock of stupidities using nested definition lists probably only as a mean to get indention. From a logical point of view such use of definition lists is beyond comprehension and will sound awful in a screen reader.

2.2 ODF

The TOC for ODF 1.1 has no period after the first level and includes the number in the a element. To avoid making the underlining too long they are simply removed but not for visited link making the TOC extremely confusing to look at if you follow a couple of links. Note that we even have meaningless page numbers in the TOC items! Who really cares, nothing happens if we try to follow a link, the TOC is all dead.

The source code is even worse. Not h2 but the b element is used for the TOC heading. CSS margin-left is used for indention, not nested list elements. The fragment identifiers must not start with a digit, probably the reason why the links are not working.

Note that even "inch" is used as CSS unit. How can we trust a standard organization for web technologies that don't give a damn about web design?

3. TOC of my article

The "TOC freak show of W3C and OASIS" has ended. I will now give you my bid for a good TOC. Why not use the TOC of this article as example.

Note that the TOC has a period also for the first level. No underlining is used for the links to make the TOC less dominant. Instead the TOC uses navy blue for link color and alternating background-color to make it sufficiently distinct and easy to read. Also note that the numbers are not included in the links and that a smaller font-size is used for the numbers.

The TOC uses nested list elements also making sense in a screen reader. The item number is used for fragment identifier. Span elements are used to make it possible to use alternating background-color and to style the number on its own.

For a detailed discussion of how to markup and style TOCs, and how to generate them, see my tutorial, TOC for XHTML with XSLT. The tutorial also deals with important issues like the IE focus bug not covered in this short introduction.

Updated 2009-06-12