| CARVIEW |
Notes on use of the i18n techniques dtd
This document provides a description of the extensions to xmlspec developed specifically to support the creation of i18n techniques. NOTE: this is all subject to constant change.
Since this incorporates nearly all the changes made for the Character Model for the World Wide Web 1.0, for the sake of completeness I have also added a description of elements used in the Character Model but not for the techniques documents.
General points
The current approach to document development in the i18n GEO task force uses an XML file referred to as a 'database' to house a collection of 'techniques'. Each technique is a tersely-stated directive similar in level to the WAI techniques, and accompanying descriptions, explanations, references, etc. A database is likely to be focused on a specific w3c technology, eg. there are different databases for HTML and CSS. Documents to be read by the user are created as 'templates'. These templates provide headings and structure to meet the needs of the user, and at an appropriate level pull in content from a database. A template may repeat and reorder information in a database, and may pull in information from several databases, eg. a template aimed at HTML authors may pull content from HTML, CSS and Core databases.
Both database and template files currently use the same dtd, but some choices regarding structure are different between the two.
A database file should normally just have 2 levels of heading in the body of the text. Sections should only contain technique
elements. Resource information should be attached to each technique - not provided at the section level, ie. do not use the
resource-list element.
A template may contain whatever is necessary to assist the user. This may include introductory paragraphs at the beginning of sentences.
Resource information is currently (for the HTML Authoring template) gathered at the section level using the resource-list element.
As of 10 feb 2003, there is one (HTML) database, and one template (Authoring International HTML). An experiment is currently under way to generate a checklist document from the current template using an alternative xslt file.
Additional elements and attributes
The following tables describe elements and attributes that have been added to xmlspec and that are expected to be of use for techniques development. Bolded attributes are required. Assume that attribute values are CDATA unless otherwise indicated.
Structural elements
| element | description | used by |
|---|---|---|
| technique |
A grouping element for information related to a technique (short-name, rule+, description, ua-issues*, resources*, test*, admin*) No attributes | %div.mix; |
| short-name |
A brief summary of the content of a technique, visible in the html version of the database for quick scanning, not visible in the template but used for content of include elements to clarify what they point to. (%head.pcd.mix;)*
| technique |
| rule |
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 rule. (%hdr.mix;)*
| technique |
| description |
groups paragraphs, examples, and other stuff describing the rule associated with a particular technique (%obj.mix;)*
| technique |
| ua-issues |
groups a number of ua-issue elements (ua-issue)+
| technique |
| ua-issue |
describes a feature wrt UA support for a particular technique and a particular browser (%obj.mix;)*
| ua-issues |
| resources |
Groups a number of different types of resource pointers. These are currently not grouped by type, and only two types are specified. Additional types should be added: these may include such things as further information (questions the reader is likely to be asking themselves having read the technique), sources (the sources of the information written up), cross-references (other areas of potential interest), background reading, useful prereading, links to more detailed implementation advice, other related links. (see-also | tech-source)*
| technique |
| see-also |
A single pointer to other useful information supporting the description of the technique. These are currently expressed typically as "What if such-and-such is the case?" or "How do I do such-and-such?". (%hdr.mix;)*
| resources |
| tech-source |
A single pointer to source material used to develop the technique. (%hdr.mix;)*
| resources |
| test |
Copied from WCAG but currently not used. | resources |
| admin |
Copied from WCAG but currently not used. | resources |
| resource-list |
For use in the template only. Groups a number of resources related to a section that were originally attached to individual techniques in the database. This element has not been fully implemented. Many of the resources have so far been added by hand. In the future, these resources may be added automatically by the xslt grouping all resources for the techniques in the section and removing redundancy. (%obj.mix;)*
| %local.div.mix; |
Grouping and block elements
| 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?)
| %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 | %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 |
| include |
Used to point to text in the database that will be included at this point in the template. (%head.pcd.mix;)*
| %local.div.mix; %local.obj.mix; |
Phrase elements
| element | description | used by |
|---|---|---|
| bdo |
Used to override the Unicode bidi algorithm for bidirectional scripts. Very useful for conversion of Hebrew and Arabic text to x/html . (%p.pcd.mix;)*
| %local.emph.class |
| rfc2119 |
Not used yet, but we may use it to surround words like MUST, SHOULD, etc. used for conformance requirements. Permits various alternatives for styling. (Used widely in CharMod) (%tech.pcd.mix;)*
| %tech.class |
| 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;)*
| %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;)*
| image |
| 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;)*
| %termdef.class |
| uname |
Surrounds Unicode character names to allow styling, eg. COMBINING LONG SOLIDUS OVERLAY. (%tech.pcd.mix;)*
| %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 |
Additional changes made for CharMod
| 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 )
| %tech.class |
| reqlist |
See the description of req above (req-type+ , req-text , (%list.class;)?)
| %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 |
Other changes to xmlspec
The following tables describe elements and attributes that have been added to xmlspec and that are expected to be of use for techniques development. Bolded attributes are required.
- created %i18n.att (xml:lang, dir) and added to common.att and common-idreq.att . These have values identical to those in html.
- created %l10n.att (locn-note, locn-alert, translate) and added to common.att and common.idreq.att . locn-note is for designers to pass helpful notes to translators. locn-alert allows designers to pass notes to translators that must be read before the translator attempts a translation (the translation tool should pick up on these). translate can be set to (yes|no), and indicates whether the text should or should not be translated - the default is yes.
- added general entities: lrm, rlm, zwj, zwnj
- added %ubiquitous.phrase.class containing "|bdo|phrase|ins|del|emph". Added the entity to the definitions of code and loc elements.
Things still to be done
The following tables describe elements and attributes that have been added to xmlspec and that are expected to be of use for techniques development. Bolded attributes are required.
- change the name attribute in ua-issue to ua, and make it an enumerated list
- implement a method to point to a future w3c wide glossary
- add title to common attributes
- implement a database (xml) to house all link targets, then have pointers to that database within the xml. This means that if a page is moved you only have to make one change. It also reduces the possibility of corruption when adding many links to the techniques database.
- remove all localisable text and other from the xsl files, and keep in a special xml file. This makes translation and maintenance easier.
- find a better way of structuring the resources, and improve the richness of the vocabulary for dealing with them.
- add ruby markup.
- other things that crop up as we go...
Richard Ishida, 7 feb 2003