From HTML WG Wiki
Jump to: navigation, search

Issue 89 remove idioms section


Remove Section 4.13 Common Idioms completely from the HTML5 specification.


Currently, the Idioms section[1] contains suggested markup and CSS to create a web page tag cloud, a conversation, and footnotes. This section is only suggested markup: there are no author or implementation conformance requirements, no new attributes or elements introduced, and no changes to either HTML/XHTML syntax, or the DOM. It is nothing more than the HTML5 Editor's suggestion about what people can use.

According to the HTML5 Editor, Ian Hickson, the rationale[2] given for keeping this section is:

   This section was added at the request of authors who wanted to know 
   what the spec suggested for the topics it mentions. Therefore removing 
   it would be doing authors a disservice, and authors take priority.

I checked in email archives for both WhatWG and the W3C, and can find no author requests for including this material. I did find questions that people asked on the WhatWG email list about recommendations of syntax to use, and scattered requests for a new dialog element, a tagcloud attribute, and something specific to footnotes, but none resulted in additional elements/attributes[3]. Asking for new elements or advice on how to use the new HTML5 syntax is a different thing than asking that recommended markup use be included in the HTML5 specification.

What is the purpose of this section? If it was created specifically in response to people asking for a dialog or footnote element, a better approach would be to provide a detailed rationale for why such requests were refused, and then point people to this when asked again. If people disagree, we have a Decision process in place where they can escalate the item to an issue and provide a change proposal. Providing a how-to section is not the way to basically tell people, "No".

In addition, there can be no author or implementation conformance tests for the section. The suggestions are just that, suggestions. A person is just as welcome to ignore the suggestions, as not. Yet by being included in the HTML5 specification, there's a real risk of such suggestions being codified as requirements—rather than help authors, such suggestions could end up causing problems for authors.

As an example of the problem of including this type of material in the specification, there have been discussions about dialog markup[4], supposedly related to the HTML WG deprecating the use of the dl element for dialog. The use of the dl to mark up dialog, though, was only a suggestion made in the HTML4 specification, in a manner very similar to what we now have in Section 4.13. How can this group deprecate that which was never anything more than a suggestion?

If the use of dl in HTML4 was nothing more than a suggestion, and we don't want to encourage such use in the future, then don't repeat the suggestion in HTML5. End of story. If people want to continue using dl, OK. If people don't, well, that's OK too. No interoperability or other problem is introduced if people use different markup.

A better approach is for markup for a specific purpose to occur organically, becoming a best practice over time. We've seen this happen with menus. There is no requirement that menus be unordered lists—it is a best practice that grew over time, to the point where we rarely see web page menus now that aren't unordered lists. And if there are people who prefer to use another markup? That's fine, too.


Remove Section 4.13 and any references to it. As an ancillary suggestion, I would also strongly recommend removing the note in the dl element section that states the following:

   Note: The dl element is inappropriate for marking up dialogue. 
   Examples of how to mark up dialogue are shown below.

It's not up to us to tell people what markup to use for what, aside from there being a rationale for providing such a guideline. Unless we're planning on making the use of dl for dialog non-conforming, in addition to making another use of markup conforming for dialog, and providing a good rationale for doing both, we should just drop any reference to dialog markup. Let the market determine best practice.


Positive Effects

Removing this section prevents possible future confusion about what is a requirement, and what is one suggestion out of the pool of possible suggestions. This change also ensures that the best markup to use for specific purposes is allowed to develop organically, and the best practices emerge naturally.

Negative Effects

Change requires Editor time to implement within the specification.

Conformance Classes Changes



By removing this text from the document, someone unfamiliar with past discussions about dialog and footnote elements may ask for such elements in the future. The risk can be offset if they are directed to the past discussions. If they persist in wanting these elements, they should be encouraged to submit a bug, and push the item through the Decision Process. Future requests can then be directed to the formally recorded rationale for rejecting a special purpose dialog and footnote elements.