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 descriptionused 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;)*

  • %common.att;
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;)*

  • %common.att;
technique
description

groups paragraphs, examples, and other stuff describing the rule associated with a particular technique

(%obj.mix;)*

  • %common.att;
technique
ua-issues

groups a number of ua-issue elements

(ua-issue)+

  • %common.att;
technique
ua-issue

describes a feature wrt UA support for a particular technique and a particular browser

(%obj.mix;)*

  • @name: the name of the browser
  • @version: the version(s) of the browser that exhibit(s) this feature
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)*

  • %common.att;
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;)*

  • %common.att;
resources
tech-source

A single pointer to source material used to develop the technique.

(%hdr.mix;)*

  • %common.att;
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;)*

  • %common.att;
%local.div.mix;

Grouping and block elements

element descriptionused 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?)

  • %common.att;
%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

  • %common.att;
  • %simple-xlink.att;
  • %auto-embed.att;
  • @source: uri for the image file
  • @height: the height of the image
  • @width: the width of the image
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;)*

  • %common.att;
image
include

Used to point to text in the database that will be included at this point in the template.

(%head.pcd.mix;)*

  • %common.att;
  • @doc: the document containing the text to be included
  • @idref: the id of the element containing the text to be included
  • @mode: (technique|rule|link) There may be additional alternatives here in time. The mode setting carries a message to the xslt regarding what type of information is required - the specific items of information extracted and the structure given to them depends on the xslt template that corresponds to a match such as include¬†[mode='technique']. Currently, the HTML Authoring template will not extract short-name or resource information for inclusion in the template at the point where the include element appears with mode set to technique. Rule would extract just the rule - it is not yet used, but may soon be used to create a checklist type template. The link mode is currently used for resources in a resource list, although many such resources are still just cut and paste at the moment.
%local.div.mix; %local.obj.mix;

Phrase elements

element descriptionused 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;)*

  • @xml:lang
  • @dir: (ltr|rtl) The intended directionality.
%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;)*

  • %common.att;
%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;)*

  • %common.att;
%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;)*

  • %common.att;
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;)*

  • %common.att;
  • @expansion: the expanded form of the abbreviation.
%termdef.class
uname

Surrounds Unicode character names to allow styling, eg. COMBINING LONG SOLIDUS OVERLAY.

(%tech.pcd.mix;)*

  • %common.att;
%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;)*

  • %common.att;
%local.emph.class
del

See the description for ins above.

(%p.pcd.mix;)*

  • %common.att;
%local.emph.class

Additional changes made for CharMod

element descriptionused 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 )

  • No attributes.
%tech.class
reqlist

See the description of req above

(req-type+ , req-text , (%list.class;)?)

  • No attributes.
%div.mix
req-text

The text of a requirement.

(%p.pcd.mix;)*

  • %common.att;
req, req-list
req-type

One of the letters 'S', 'I' or 'C' - standing for specifications, implementations and content, respectively.

(%tech.pcd.mix;)*

  • %common.att;
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.

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.


Richard Ishida, 7 feb 2003