Styleguide for i18n specifications

General points

Which elements to use or not use

For Internationalization Activity documents, inside a div1 element you should only use elements described in the document Notes on use of the xmlspec-i18n dtd. There are other elements available, but if you want to use them you should ask first. Some such elements are for WAI Domain support (eg. wai-technique), others are deprecated in favour of new elements (eg. graphic).

Setting language

The language of W3C specifications is en-US. This should be set on the spec element using xml:lang, as well as in the langusage/language element. The latter is not used by the XSLT.

Editors-copy setting

You should set spec/@role to editors-copy while working on a document. This will introduce, in various places, text and javascript appropriate to a document that is being edited. Remove this value before publication and everything will disappear.

Local CSS style sheets

The XSLT inserts markup that calls an external CSS style sheet called local.css. You should declare any CSS that is specific to your type of document in a CSS file of this name. 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).

Strings introduced in the XSLT

Strings introduced in the XSLT (such as "Figure X: " before figure captions) are to be found in the file strings.xml. You will not need to do anything about this. These are maintained in a separate file (called strings.xml) with the XSLT.

Externalising strings in this way allows for easier translation, and also permits easier rearrangement of variables during translation.

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

Examples

Use the example element for non-inline examples.

You should always provide a value for the id attribute, on the example element (not the head). (See how to refer to examples from the text.)

In the generated XHTML, examples have a caption "Example X: " plus optional 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.

If you want to add text to the caption, write it in the head element.

The eg element should only be used within an example element, and when a 'pre'-like behaviour is absolutely necessary. Preferably, the code element should be used with breaks or within paragraphs.

Notes

To create a block-type note use the note element. The XSLT will automatically provide the lead in text 'Note: '. If the note begins with a paragraph, the text 'Note: ' will appear inline. Otherwise, it will be in a separate paragraph.

Set ids on the note element.

Headings

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

Set the id on the div1, div2, etc, element, rather than on the head element. (See how to refer to sections or techniques from the text.)

Graphics, tables and figures

The implementation of graphics deviates slightly from XMLSpec standard usage. A figure element has also been provided.

All tables and all non-inline pictures should be enclosed in a figure element after the preceding paragraph.

In the generated XHTML, figures can have a caption. If, and only if, a caption is supplied, it will start with "Figure X: " in the XTHML, where X is the sequential number of the figure in the document. The text "Figure X: " is generated by the XSLT, and you must not add that to the XML. The use of captions is encouraged.

You should always provide a value for the id attribute, on the example element (not the head). (See how to refer to figures from the text.)

All graphic images included in the text, whether in a figure or within a paragraph, should be created with an image element. The graphic element that comes with xmlspec must not be used. The image element has two children, img and alt. img has attributes width and height and you are encouraged to use them; img has no alt attribute, since an alt element is provided as a child of image. This approach assists translators, but also allows the alt text to be marked up (eg. with bidi or language information, or ins or del tags). You should always provide alt text.

All graphics files should be stored in the images directory (eg. the source attribute would point to images/graphicName.gif).

Note that alt text should describe the picture so that someone unable to see it can derive the same conclusions as someone who can. This generally means describing the point being made by the picture rather than the visual elements.

Abbreviations and acronyms

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

Referring to examples and figures

Use the specref element to point to the example or figure. The specref element will be replaced by the sequential number of the example or figure in the document, so you will need additional text to introduce it. Here are a couple of examples:

The markup in Example <specref ref="ri20050131.133504872"/> lends itself...

This becomes: "The markup in Example 14 lends itself ...".

... show links to translated alternatives (see Figure <specref ref="ri20050131.132916912"/>).

This becomes: "... show links to translated alternatives (see Figure 1)."

Referring to sections and 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?."

For details of how to use language codes, see <specref ref="ri20030218.131140352"/>.

This becomes: "For details of how to use language codes, see Section 7: How to choose language values."

Lists

Lists following a paragraph that ends with a colon should be included within the p element.

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

Until we properly enable the diff attribute provided by XMLSpec, two new elements should be used to show changes to the text: ins and del. These are inline elements, and in some cases they allow for a faster, simpler, and more accurate application of change marks.

The editor's copy of the document will show change marks, but if the role="editors-copy" is removed from the spec element, so will these be removed from the document.

Editorial notes

Use the ednote element.

Bidirectional overrides

Although the DTD allows the use of its:dir="rlo/lro" on any element, there are problems transposing this to XHTML. If you wish to override the bidirectional algorithm, please use its:dir="rlo/lro" inside a phrase element. (its:dir="rtl/ltr" can still be used on any element.)

References

References should appear in Appendix A. Normative references, if any, should appear first, in a dedicated subsection.

The XSLT allows you to use a long list containing many more references than are actually used in the document. This only works, however, when no distinction is made between normative and non-normative references. A typical approach when taking advantage of this feature is to keep the references in separate file which is included into your document as an external entity. This approach is applicable for techniques documents and other notes, which do not have normative references, and allows for easy re-use and maintenance of references. To take advantage of this approach you MUST use @role="unfiltered" on the div that contains your references. (Note that this means that you must not use this value otherwise.) This alerts the XSLT processor to search the document for a list of bibrefs, and filter out documents in the references section that are not referenced in the current document. Note that the entries are reordered alphetically by the reference name by the XSLT.