Styleguide for i18n notes

General points

Edit the document editme.html. This is then converted to Overview.html using XSLT. The XSLT will add such things as numbering for sections and examples, table of contents, etc., removing a lot of tedious work from your editing.

Setting language

The language of W3C specifications is en-US. This should be set on the html element using lang and xml:lang.

Local CSS style sheets

You should declare any CSS that is specific to your type of document in local.css. If you don't have anything to include in such a file, you should have an empty file called local.css in the same directory as your document (to avoid problems with some user agents).

Placeholder for toc

Just below the status section, place the following markup. The XSLT will generate a table of contents from the sections in the document.

<div class="toc">
     <h2><a name="contents" id="contents"></a>Table of Contents</h2>
     <div class="autotoc">
     </div>

 

In-line element conventions

The following table outlines conventions for markup and presentation used for in-line labeling. The presentation column applies to the English version. Any translated version may change the presentation (eg. a Japanese version may substitute underlining for bold).

Note: you should never have to type in quotation marks. If you have chosen the appropriate element, they will be provided by the XSL style sheet.

Type of in-line label	Example	Markup to use
emphasis (general)	In keyboard input it is not always the case that...	em
emphasis (stronger)	you must absolutely not do that!	strong
new term introduction	The set of characters is called a repertoire.	span class=term
document title	see Requirements for String Identity Matching.	span class=titleref
quoted term	The word 'character' is used in many contexts.	span class=qterm
quoted term / phrase expressing dubious usage	ie. numeric "positions" within a string	span class=quote
quoted text	such as "...as it may from time to time be revised or amended."	q
quoted character (refers to typically one, but occasionally more, specific characters).	'ç'	span class=qchar
quoted sample output (cf. HTML SAMP)	The string "articulo" is subject to different representations	q
quoted code	sucçon	code
quoted keyboard input (cf. HTML KBD)	a user typing çé on a traditional French-Canadian keyboard	span class=qchar
element name	a user agent that looks for articulo elements	span class=el (NOTE: do not add < and >)
attribute name or value		span class=kw
function name		span class=kw
key word in a markup or programming language	the IANA charset value	span class=kw
variable name		var
conformance related word based on rfc2119	All references to Unicode MUST refer to...	span class=rfc2119
acronyms & abbreviations	More and more APIs are defined,	abbr
Unicode name	COMBINING LONG SOLIDUS OVERLAY	span class=uname

Examples

Use the following markup for non-inline examples.

<div class="exampleOuter">
<div class="exampleHeader"><a id="...">...</a></div>
<p>...</p>
...
</div>

In the generated XHTML, examples can have a title "Example X: " plus optional title text, where X is the sequential number of the example in the document. The text "Example X: " is generated by the XSLT, and you must not add that to the XML. When an example has a caption like this, you can refer to it from the text, and the XSLT will automatically keep the numbering of reference and example correct.

To set this up, use the div with class exampleHeader in your code. You should always provide a value for the id attribute, on the a element inside .exampleHeader. If you want to add a title to your example, put that title inside the a element. Otherwise, use &nbsp; inside the element.

You can also omit the exampleHeader div, but then you won't be able to refer to the example by number from the text.

To refer to an example in the text, use the following markup.

As <a class="example-ref" href="#...">the following example</a> shows, ... 

The href attribute should contain the id of the example you are referring to after the #. The content of the a element can be anything. It will be replaced by the number of the example pointed to. If this is the second example, the generated file it will read "As Example 2 shows, ...". (Using text such as 'the following example' can make the editme file more readable.)

Notes

To create a block-type note use markup such as the following.

<div class="note"><span class="note-head">Note: </span>Two  non-embedding directional control characters provided by Unicode do 
not have corresponding markup and should be used. These are U+200F <span class="uname">RIGHT-TO-LEFT MARK</span> (RLM) and U+200E 
<span class="uname">LEFT-TO-RIGHT MARK</span> (LRM).</div>

Headings

Do not supply numbering for section headings. These will be provided automatically by the XSLT.

Here is sample markup for a heading.

<div class="h3section">
<h3><a href="#contents"><img src="images/topOfPage.gif" class="toclink" title="Go to the table of contents." alt="Go to the table 
of contents."></a><a id="id_goes_here">Adding escapes to the content</a></h3>
...
</div>

In this heading we have added a graphic to point back to the table of contents. The graphics will be floated to the right of the heading.

Always add an id value to the second a element. This will be used by the XSLT to allow you to refer to a heading from the text. The content of that a element is the heading text itself.

Heading elements must always appear inside a div (this is how the XSLT works out how to number the headings). H2 elements must always follow <div class="h2section">. H3 elements always follow <div class="h3section">, and so on.

The following shows how you would refer to a heading from the text.

see the issues associated with escapes in the section <a class="section-ref" href="#id_goes_here">Adding escapes to the content</a>.) 
		

The href value uses the id of the section heading you want to point to after the #. The content of the .technique-ref element can be anything you like. It will be replaced by the XHTML with the text of the heading at the time the XSLT is run. This ensures that changes to headings are correctly rendered in the final document.

Abbreviations and acronyms

Use the abbr element for both of these. Spell out the full form in the title attribute.

Referring to techniques

Use the specref element to point to the section or technique. The specref element will be replaced by the text "Section" or "Technique" followed by the sequential number of the section or technique in the document, and the title of the section or short title of the technique. Here are a couple of examples:

For details of which language attribute to use, see <specref ref="ri20040429.092928424"/>.

This becomes: "For details of which language attribute to use, see Technique 4: Should I use the lang or xml:lang attribute?."

Lists

A colon should be used for a sentence that leads into the list.

If a list is expressed as a single sentence each list item should begin with a lower case letter and end with a comma or ", and".  The last list item should end with a full stop.

Example:

Every W3C specification MUST:

1. conform to the requirements applicable to specifications,
2. specify that implementations MUST conform to the requirements applicable to software, and
3. specify that content created according to that specification MUST conform to the requirements applicable to content.

Otherwise, each list element should begin with an uppercase letter and end with a full stop.

Example:

Some aspects of Unicode that require additional specification for the Web include:

• Choice of encoding forms (UTF-8, UTF-16, UTF-32).
• Counting characters, measuring string length in the presence of variable-length encodings and combining characters).
• Duplicate encodings (e.g. precomposed vs decomposed).
• Use of control codes for various purposes (e.g. bidirectionality control, symmetric swapping, etc.).

Change markup

To show changes to the text use ins and del.

Editorial notes

Use span class=ednote.