This is a proposal for community consideration; W3C has not yet adopted this proposal. These conventions have been gathered from some existing documents. To achieve them, editors should use the markup and CSS described below.
Please note that these conventions are intended as optional additions, not as publication requirement. Editors who already have an investment in other specification-generation systems need not adopt these conventions (though of course, they are welcome to!).
Note: The actual presentation of these conventions in a work in progress, and may change over time to suit the broader needs of editors.
These are proposed markup and style conventions for W3C Technical Reports, including Working Group Notes, Recommendation-Track specifications, and other applicable documents. This is a compilation of best practices exercised by some W3C working groups. The aim in standardizing these conventions is to promote more precise specification practices, to make it easier for authors, implementers, and reviewers to read and understand specifications, and to more easily allow automatic processing of specifications (e.g. mining them for terms, markup features, or APIs).
These conventions are not about the typography, layout, or an particular aspect of appearance, but rather about the semantics of a specification. Having shared concepts is an implicit classification or loose ontology; the appearance is simply an affordance to allow readers to understand more easily what is being described. Reuse of these conventions is intended to help promote a consistency in how editors put together specs.
These conventions are established through the use of markup in the document and specific class names, which may be styled by including a link to a supplementary CSS stylesheet. The style definitions are in a separate stylesheet than the base W3C stylesheet, thus do not conflict with older specifications which may have used different typographic conventions or class names. A link to this typographic convention stylesheet should be placed before the link to the base stylesheet, like this:
<link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-TR.css" />
<link rel="stylesheet" type="text/css" href="http://www.w3.org/StyleSheets/TR/W3C-ED.css" />
Note that the element-level markup is important for accessibility affordance. The colors used in the stylesheet are named colors, to account for lack of support for numerical color codes in assistive technology; additionally, user stylesheets specifically for particular accessibility needs may also be designed.
The styling applied in this document may not be suitable for every specification. However, specification authors are encouraged to adopt the markup and class names, even if they change the associated styles, because this consistency of use makes each instance more valuable. Specification editors should also use any additional styling needed to convey the content of their specification clearly.
id attributeFor many categories of content described in this document, it is important to assign an id attribute value (e.g., for defining instances, notes, warnings, issues, etc.), which is called out in each appropriate section. The very fact that it is noteworthy indicates that people may wish to link to it, and an id enables this.
The id value chosen should be short and meaningful as well as unique, not simply a numerical index or hyphenated truncated version of the text content. Note: This document uses only placeholder id values in the examples, not meaningful values, and these id values are not intended to be emulated.
title attributeThe title attribute should be used to provide additional context information about a term, such as the particular element an attribute is applied to, or interface that a property is part of, or whether an attribute is the syntax or DOM representation. Where the value of the title attribute is the same as the text content of the term, the title attribute may be omitted.
The title attribute may be used in the definition of a term, or in a reference to that defining term.
These are typographic conventions for W3C Recommendations and Recommendation-Track specifications.
These are general conventions for discrete aspects of a specification.
It is important to assign an id to each defining instance of a term, element, attribute, or property, but not to references to that term.
The defining instance of a term is marked up like this:
<dfn id="term">term</dfn>
<dl>
<dt><dfn id="glossary-term">glossary-term</dfn></dt>
<dd>glossary-term defintion</dd>
</dl>
which is rendered like this in the supplementary style sheet:
termReferences to a defining term are marked up like this:
<a class="term-ref" href="#term">term</a>
<a class="term-ref" href="#glossary-term">glossary-term</a>
which is rendered like this in the supplementary style sheet:
termElements are marked up in the following manner, for defining instances:
<code class="element"><dfn id="element-name">element-name</dfn></code>
which is rendered like this in the supplementary style sheet:
element-name
References to the defining instances of an element are marked up in the following manner:
<a href="#element-name"><code class="element">element-name</code></a>
which is rendered like this in the supplementary style sheet:
element-name
Attributes and attribute values are marked up in the following manner, for defining instances:
<code class="attr"><dfn id="attribute-name">attribute-name</dfn></code>
=<code class="attr-value"><dfn id="attribute-value">'attribute-value'</dfn></code>
which is rendered like this in the supplementary style sheet:
attribute-name='attribute-value'
References to these defining instances of attributes and attribute values are marked up in the following manner:
<a href="#attribute-name"><code class="attr">attribute-name</code></a>
=<a href="#attribute-value"><code class="attr-value">'attribute-value'</code></a>
which is rendered like this in the supplementary style sheet:
attribute-name='attribute-value'
Aspects of markup are marked up in the following manner, for defining instances:
<code class="prop"><dfn id="property-name">property-name</dfn></code>
=<code class="prop-value"><dfn id="property-value">'property-value'</dfn></code>
which is rendered like this in the supplementary style sheet:
property-name='property-value'
References to these defining instances are marked up in the following manner:
<a href="#property-name"><code class="prop">property-name</code></a>
=<a href="#property-value"><code class="prop-value">'property-value'</code></a>
which is rendered like this in the supplementary style sheet:
property-name='property-value'
Variables are marked up like this (with optional id):
<var id="var-variableName">variableName</var>
which is rendered like this in the supplementary style sheet:
variableNameCode blocks are marked up like this (see also Examples and Interfaces):
<pre><code>
<svg xmlns="http://www.w3.org/2000/svg">
<circle cx="75" cy="25" r="20" fill="orange" stroke="red" />
</svg>
</code></pre>
which is rendered like this in the supplementary style sheet:
<svg xmlns="http://www.w3.org/2000/svg">
<circle cx="75" cy="25" r="20" fill="orange" stroke="red" />
</svg>
Other code fragments are marked up like this:
<code>//some code here</code>
which is rendered like this in the supplementary style sheet:
//some code here
This convention is used to indicate that special attention should be paid to a section that may not be immediately intuitive. This is often used to indicate why a particular decision was made when other alternatives were examined during the course of designing the feature, and may be informative.
It is important to assign an id to each note.
Block:
<p class="note" id="note-block-1"><strong>Note:</strong> This is a single-paragraph block note.</p>
Note: This is a single-paragraph block note.
<div class="note" id="note-block-2">
<p><strong>Note:</strong> This is a multi-part block note, with some code:</p>
<pre><code>
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
</code></pre>
</div>
Note: This is a multi-part block note, with some code:
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
Inline:
<p>This is some prefatory material before the note. <i class="note" id="note-2"><strong>Note:</strong> This is
an inline note.</i></p>
This is some prefatory material before the note. Note: This is an inline note.
This is some prefatory material before the note. Note: This is an inline note which spans several lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This convention is used to mark security concerns or deprecated features. It is important to assign an id to each warning.
Block:
<p class="warning" id="warning-block-1"><strong>Warning!</strong> This is a single-paragraph block warning.</p>
Warning! This is a single-paragraph block warning.
<div class="warning" id="warning-block-2">
<p><strong>Warning!</strong> This is a multi-part block warning, with some code:</p>
<pre><code>
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
</code></pre>
</div>
Warning! This is a multi-part block warning, with some code:
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
Inline:
<p>This is some prefatory material before the warning.
<i class="warning" id="warning-2"><strong>Warning!</strong> This is an inline warning.</i></p>
This is some prefatory material before the warning. Warning! This is an inline warning.
This is some prefatory material before the warning. Warning! This is an inline warning which spans several lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
It is useful, but not required, to assign an id to each example.
Block:
<p class="example" id="example-block-1"><strong>Example:</strong> This is a short single-paragraph block example.</p>
Example: This is a short single-paragraph block example.
<p class="example" id="example-block-2"><strong>Example:</strong> This is a single-paragraph block example
which spans several lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
nisi ut aliquip ex ea commodo consequat.</p>
Example: This is a single-paragraph block example which spans several lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
<div class="example" id="example-block-3">
<p><strong>Example:</strong> This is a multi-part block example, with some code:</p>
<pre><code>
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
</code></pre>
</div>
Example: This is a multi-part block example, with some code:
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
Inline:
<p>This is some prefatory material before the example. <i class="example" id="example-2"><strong>Example:</strong> this
is an inline example.</i></p>
This is some prefatory material before the example. Example: this is an inline example.
For ease of reading, it is also acceptable to omit the leading "Example:" in favor of a prose parenthetical expression, such as "For instance," "As an example," "To illustrate," etc. In these cases, the example class name should still be retained.
<p>This is some prefatory material before the example. <i class="example" id="example-2">For example, this is
an inline example.</i></p>
This is some prefatory material before the example. For example, this is an inline example.
This is some prefatory material before the example. For instance, this is an inline example which spans several lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This convention is used to mark up Interface Definition Language blocks, such as Web IDL or OMG IDL. It is important to assign an id to each interface, and often to individual parts of an interface.
<pre class="idl" id="idl-interface-BaseInterface"><code>
// this is an IDL example
interface <a href="#style-BaseInterface">BaseInterface</a> : <a href="#style-DerivedInterface">DerivedInterface</a> {
// ConstCode
const unsigned long <a href="#style-UNICORN">UNICORN</a> = 0x00;
const unsigned long <a href="#style-PONY">PONY</a> = 0x01;
const unsigned long <a href="#style-DAHUT">DAHUT</a> = 0x02;
readonly attribute boolean <a href="#style-invisible">isInvisible</a>;
readonly attribute DOMString <a href="#style-pink">pink</a>;
readonly attribute unsigned long <a href="#style-sparkly">sparkly</a>;
boolean <a href="#style-method1">methodName</a>(in DOMString string);
void <a href="#style-method2">methodNameAlso</a>(in DOMString stringArg,
in boolean isBooleanArg,
in interface::InterfaceName interfaceArg);
};
</code></pre>
// this is an IDL example
interface BaseInterface : DerivedInterface {
// ConstCode
const unsigned long UNICORN = 0x00;
const unsigned long PONY = 0x01;
const unsigned long DAHUT = 0x02;
readonly attribute boolean isInvisible;
readonly attribute DOMString pink;
readonly attribute unsigned long sparkly;
boolean methodName(in DOMString string);
void methodNameAlso(in DOMString stringArg,
in boolean isBooleanArg,
in interface::InterfaceName interfaceArg);
};
Note: This section needs more work, especially as regards treatment of Web IDL.
These are typographic conventions for W3C Working Drafts, intended to call out specific features for commenters. These conventions and styles are intended to be temporary, and must be removed before the specification goes to Recommendation status.
This convention is used to indicate a feature or section of the specification which is unresolved, either because an adequate solution has not been found, because a choice has not be made between multiple options, or because a reviewer has objected to some aspect of the section in question. All sections marked as issues must be resolved before the specification moves to Candidate Recommendation status.
It is important to assign an id to each issue, so it can be identified explicitly in reviews.
Block:
<p class="issue" id="issue-block-1"><strong>Issue:</strong> This is a single-paragraph block issue.</p>
Issue: This is a single-paragraph block issue.
<div class="issue" id="issue-block-2">
<p><strong>Issue:</strong> This is a multi-part block issue, with some code:</p>
<pre><code>
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
</code></pre>
</div>
Issue: This is a multi-part block issue, with some code:
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
Inline:
<p>This is some prefatory material before the issue. <i class="issue" id="issue-2"><strong>Issue:</strong> This is
an inline issue.</i></p>
This is some prefatory material before the issue. Issue: This is an inline issue.
This is some prefatory material before the issue. Issue: This is an inline issue, with a link.
This is some prefatory material before the example. Issue: This is an inline issue which spans several lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Issues may also be used in early drafts to indicate a blank section which must be filled in, as such:
<p class="issue"><strong>To Do:</strong> Research this and define this behavior.</p>
To Do: Research this and define this behavior.
This convention is used for Commit-Then-Review specification editing, where the editor updates the specification for reviewers to see the proposed prose in context and possibly veto it, as opposed to Review-Then-Commit editing where the editor must first get group consensus before including the prose in the specification. All sections marked as proposals must be resolved before the specification moves to Candidate Recommendation status.
It is important to assign an id to each proposal, so it can be identified explicitly in reviews.
Block:
<p class="proposal" id="proposal-1">This is a block proposal.</p>
This is a block proposal.
This is a block proposal, with some code:
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
Inline:
<p>This is some prefatory material before the proposal. <i class="proposal" id="proposal-3">This is
an inline proposal.</i></p>
This is some prefatory material before the proposal. This is an inline proposal.
This is some prefatory material before the proposal. This is an inline proposal which spans several lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This convention is used for features or sections that are proposed to be dropped or deprecated. A section may be marked at-risk before moving into Candidate Recommendation phase pending implementer feedback, and may be dropped if there are not sufficient interoperable implementations to exit CR without the specification having to return to Last Call. All sections marked as at-risk must be resolved before the specification moves to Candidate Recommendation status.
It is important to assign an id to each section marked at-risk, so it can be identified explicitly in reviews.
Block:
<p class="atrisk" id="atrisk-1">This is a block at-risk feature.</p>
This is a block at-risk feature.
This is a block at-risk feature, with some code:
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
Inline:
<p>This is some prefatory material before the at-risk feature. <i class="atrisk" id="atrisk-3">This is
an inline at-risk feature.</i></p>
This is some prefatory material before the at-risk feature. This is an inline at-risk feature.
This is some prefatory material before the at-risk feature. This is an inline at-risk feature which spans several lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
This convention is used to indicate passages or features which have changed from the previous published draft. This is particularly useful for tracking changes based on review feedback. This should only be used for major changes, not typo corrections or other editorial alterations. All sections marked as changes must be resolved before the specification moves to Candidate Recommendation status.
Marking changes between versions is at the editor's discretion, but is easy and aids review. It is not necessary to add an id specifically for sections with changes, nor to add undue markup. Ideally, the change class name can be used as a supplementary value along with other class name.
It is important to assign an id to each change, so it can be identified explicitly in reviews. In many cases, new sections may already have an id, in which case it is unnecessary to add another.
Block:
<p class="change">This is a block change.</p>
This is a block change.
This is a block change, with some code:
function Init(event)
{
var el = event.target;
if ( null == el ) {
el = document.createElement("foo");
}
}
Inline:
<p>This is some prefatory material before the change. <span class="change">This is
an inline change.</span></p>
This is some prefatory material before the change. This is an inline change.
This is some prefatory material before the change. This is an inline change which spans several lines. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
We would like to thank the following people for their contributions to this document: Karl Dubost (for proposing the initial version), Ian Jacobs, Michael(tm) Smith, Gregory J. Rosmaita (for accessibility review), Bert Bos, Sandro Hawke, Art Barstow, Robin Berjon, Anne van Kesteren, Ian Hickson, Marcos Caceres, Liam Quin, Fantasai, Richard Ishida, Michael Cooper.
For comments or questions, contact Doug Schepers, or comment on spec-prod@w3.org.
Last Update: $Date: 2010/02/21 21:08:28 $ by $Author: schepers $