This document provides a description of the extensions to xmlspec developed specifically to support the creation of i18n documents. The DTD developed for techniques document development (xmlspec-tech.dtd) has been revised to incorporate the latest version of xmlspec, and is now being made available for use with new documents by all working groups in the i18n Activity.
The version of xmlspec in use is version 2.9 of 6 May 2005. NOTE: this is all subject to constant change.
The xmlspec-i18n DTD contains some extensions that are specific to techniques documents as developed by the GEO WG, and others that are specific to Character Model documents developed by the Core WG. An attempt has been made below to clarify which is which. Note that the choice of elements used for a particular document rests with the author. There are other elements and additions that are valid for use in all types of document.
See also the document Styleguide for i18n specifications.
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.
Techniques documents of the i18n GEO Working Group are divided into subject areas, and can be read from end to end if desired (this is recommended for newcomers). The techniques document contains a number of techniques that have the same structural components. Each technique contains a tersely-stated directive similar in level to the WAI techniques, plus accompanying descriptions, explanations, references, etc.
In addition, there is an outline document covering techniques for a given set of technologies that lists the terse directives and summary information about user agent support, grouped into sections that are related to tasks that the user is likely to want to undertake. These outline documents may repeat the same directives in more than one section. The user can select a directive to link to more detailed information in the relevant techniques document.
Finally, there is a document with the same structure as each outline document that contains just resource information related to particular techniques. It is possible to link between the outline and the resources documents.
The outline and resources documents are generated using XSLT from a template and the xml form of the techniques document.
As of 9 July 2003 there was a single DTD in use to support techniques documents for both GEO and WCAG groups. Since the constituents of a technique contain different required elements for these two groups the former technique element was split into a geo-technique and a wai-technique element. Most of the remaining structural and phrasal elements are shared, although there are some elements that are used only by GEO, and vice versa. These should be identified in the DTD code. This document describes only the elements needed for GEO techniques.
The following are elements in xmlspec that it is ok to use inside a div1. Although a validating editor will make other choices
available to you, those choices may need special setup in the XSLT or CSS style sheet to work well, or may be deprecated for use with i18n activity
documents for other reasons. If you wish to use something that is not on this list, please place a request with Richard Ishida.
Elements that are native to xmlspec are shown on the left. Note that some special combinations of element plus attribute are also included (such as emph[@role="strong"]). Elements introduced to the DTD by the i18n activity are shown to the right. These are described further down this page.
| Type | xmlspec | i18n dtd |
|---|---|---|
| Sections |
div1 div2 div3 div1[@role="unfiltered"] * head | |
| Techniques |
geo-technique short-name checklist-item description ua-issues ua-issue resources resource xref resource-descn ua-applicability ua |
|
| Requirements |
req reqlist req-text req-type |
Notes:
| Type | xmlspec | i18n dtd |
|---|---|---|
| General blocks |
p note example eg * caption |
figure |
| Lists |
olist ulist item | |
| Tables |
table * tbody th td | |
| Images |
image * img alt |
|
| Bibliography |
bibl |
Notes:
| Type | xmlspec | i18n dtd |
|---|---|---|
| All-purpose | phrase | |
| Terms | termdef term | |
| Emphasis | emph emph[@role="strong"] * | |
| Quoting & demarcating | quote kw code | qterm qchar abbr uname |
| Linking | loc bibref specref termref titleref xspecref xtermref | |
| Special | sub sup | |
| Editorial |
ednote edtext |
ins del |
Notes:
The following tables describe elements and attributes that have been added to xmlspec.
Strongly emphasised attributes are required. Assume that attribute values are CDATA unless otherwise indicated. After the description the content model of the element is shown, followed by descriptions of any attributes.
| element | description | used by |
|---|---|---|
| figure |
Associates the table or image with a caption such that it can be manipulated as a unit by the stylesheet. Even without a caption, this is useful for recognition as a block with figure-specific positioning rules. ((table | image) , caption?)
| %local.illus.class |
| image |
This definition of image uses an element for the alt information. That allows the alt text to be tagged for bidi, language, etc. and makes translation easier. Note that this is intended to be used in-line. (img, alt) No attributes | %local.illus.class |
| img |
Displayed graphic. Replacement for the graphic element - removes the alt attribute (see image). EMPTY
| image |
| alt |
Text describing an image. Having the text in a separate element rather than an attribute a la HTML means that it can be given meta information such as lang, bidi, etc. (%obj.mix;)*
| image |
| element | description | used by |
|---|---|---|
| qterm |
Words or short phrases being referred to / quoted. eg. "The word 'character' is used...". Do not use quote marks! These are added, if required by the stylesheet. (%tech.pcd.mix;)*
| %local.tech.class |
| qchar |
One or a short sequence of characters/letters being referred to / quoted. eg. "The letter 'c' is the third..." Also serves for keyboard keys. Do not use quote marks! These are added, if required by the stylesheet. (%tech.pcd.mix;)*
| %local.tech.class |
| abbr |
Surrounds abbreviations and acronyms and stores the expansion of the abbreviation (which could be shown as say a tooltip, or pronounced by a voice synthesiser). (%tech.pcd.mix;)*
| %local.termdef.class |
| uname |
Surrounds Unicode character names to allow styling, eg. COMBINING LONG SOLIDUS OVERLAY. (%tech.pcd.mix;)*
| %local.tech.class |
| ins |
ins and del elements are for marking changes to the document. They were added here rather than using the @diff scheme provided by xmlspec because it was easier (quicker) to use for marking up phrase level text given the process in use for editing the Character Model (if using XMetal - just highlight the appropriate text and double-click the element in the element list). Using xslt, the elements were mapped very simply to elements of the same name in xhtml. (%p.pcd.mix;)*
| %local.emph.class |
| del |
See the description for ins above. (%p.pcd.mix;)*
| %local.emph.class |
This section describes the geo-technique element and its children. The geo-technique element is only used in techniques documents, and is what distinguishes them from other document types.
There is also a wai-technique element. This is used to support the slightly different needs of the WAI domain, whilst allowing them to use the same basic DTD.
| element | description | used by |
|---|---|---|
| geo-technique |
A grouping element for information related to a technique. Only used for GEO techniques related documents. (short-name, checklist-item+, description, ua-issues*, resources*, test*, admin*, scripts?, ua-applicability)
TBD: remove the * from ua-issues and resources (and maybe also from test and admin?) | %local.div.mix; |
| short-name |
A brief summary of the content of a technique, visible in the html version of the techniques documents, not visible in the outline and resources documents but used for content of include elements to clarify what they point to. (%head.pcd.mix;)*
| geo-technique |
| checklist-item |
The do or don't text that summarises a technique. This should normally be one paragraph (or even one sentence if possible), but it is also possible to use a list to combine two inseparable statements in a single checklist-item. (%hdr.mix;)*
| geo-technique |
| description |
Groups paragraphs, examples, and other stuff describing the checklist-item associated with a particular technique (%obj.mix;)*
| geo-technique |
| ua-issues |
Need to figure out the best usage for this element. Groups a number of ua-issue elements (ua-issue)+
| geo-technique |
| ua-issue |
Need to figure out the best usage for this element. Describes a feature wrt UA support for a particular technique and a particular browser (%obj.mix;)*
| ua-issues |
| resources |
Groups a number of pointers to additional resources associated with a given technique. (resource)*
| geo-technique |
| resource |
A single pointer to other useful information supporting the description of the technique. The type of resource is indicated by the resource-type attribute. Different types of resource can be specified in any order (they will be grouped and ordered later by the XSLT). The bibref element must point to one of the entries in the references. The bibliography may be entered directly into the document or included into the document via the use of an external entity. The content of the loc element (not described here because it is a standard xmlspec element) should specify the location of the resource as precisely as possible to help the reader. When pointing to large resources, such information may include the chapter heading and number, the page number (in a book), an indication of which paragraph to look for, etc. For small web pages, this can be the title of the page. (bibref, loc, resource-descn)
TBD: Consider whether other should be split into additional categories. | resources, resource-list |
| xref |
Need to look into the usage here. A cross-reference to another section in a view. These are currently expressed typically as "What if such-and-such is the case?" or "How do I do such-and-such?". (resource-descn, specref+)
| xref-list |
| resource-descn |
Describes the target of a link. Try to 'front-load' descriptions as much as possible, ie. express the key distinguishing information about this resource as near as possible to the beginning of the description, and keep them succinct. In an xref element, these are currently expressed typically as "What if such-and-such is the case?" or "How do I do such-and-such?". (%p.pcd.mix;)*
TBD: Should probably have common attributes. TBD: I can't remember whether different resource-descn content across techniques will create multiple pointers after XSLT processing. Need to check it out. | xref, resource |
| scripts |
Not currently in use. Indicates scripts for which this technique is relevant. Groups a number of script descriptions. Several script descriptions can be made by having several script elements as children of "scripts". There must be one "all" or one "na" element. (all | na | script+)
| geo-technique |
| script |
Content of the script element. EMPTY
| scripts |
| ua-applicability |
Provides information about which user agents, and which versions of those, present issues when it comes to implementing the recommendation in the technique. This element should not contain more than one instance of "ua" with the same value for the "ua-name" attribute. If there is no information about a particular user agent, simply leave out the subelement for that ua. (ua)*
| geo-technique |
| ua |
Each "ua" element represents a user agent, and if present indicates whether or not there are issues relating to the implementation of the current technique for that user agent either in the chosen base version and/or in the latest available version at the time of publication of the document. EMPTY
| ua-applicability |
| element | description | used by |
|---|---|---|
| req |
The req and req-list elements are used to highlight the actual requirements embedded in the (flowing) text. Each requirement is associated with one or more of S, I, or C (specifications, implementations, or content) to indicate relevance. This is rendered currently as yellow background, with relevance indicated by appropriate letters (S,I, or C) enclosed in square brackets at the beginning. (req-type+ , req-text )
| Top level element |
| reqlist |
See the description of req above (req-type+ , req-text , (%list.class;)?)
| %local.div.mix |
| req-text |
The text of a requirement. (%p.pcd.mix;)*
| req, req-list |
| req-type |
One of the letters 'S', 'I' or 'C' - standing for specifications, implementations and content, respectively. (%tech.pcd.mix;)*
| req, req-list |
The following attributes and entities are expected to be of use for any document.
Here are some technical details for those working on the DTD:
Version: $Id: xmlspec-i18n-dtd.html,v 1.8 2005/07/26 14:44:03 rishida Exp $