This document provides guidelines for editors of Rec-track or Note documents working in the W3C Internationalization Activity. It assumes familiarity with the XMLSpec documentation, and generally documents things not covered there
This should be read in conjunction with the DTD notes.
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).
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.
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.
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 (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.
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 |
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.
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.
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.)
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.
Use the abbr element for both of these. Spell out the full form in the title attribute.
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)."
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 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:
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:
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.
Use the ednote
element.
Although the DTD allows the use of dir="rlo/lro"
on any element, there are problems transposing this to XHTML. If you wish to override the bidirectional algorithm, please use dir="rlo/lro"
inside a phrase
element. (dir="rtl/ltr"
can still be used on any element.)
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.
When describing a resource in the resource-descn try to 'front-load' descriptions (ie. express the key distinguishing information about this resource as near as possible to the beginning of the description) and keep them as succinct as possible. For example, rather than saying:
This reference is a useful resource that advises you how to use the lang attribute on the html tag, and is important because it relates to Web content accessibility, being drawn from the Web Content Accessibility Techniques document relating to HTML.
Say:
Web Content Accessibility Techniques for HTML: advises on use of lang attribute on html tag.
Version: $Id: styleguide.html,v 1.4 2005/07/28 11:49:41 rishida Exp $