Notes on use of the i18n techniques dtd

A grouping element for information related to a technique

(short-name, checklist-item+, description, ua-issues*, resources*, test*, admin*, scripts?, ua-applicability)

• @id: a unique id to identify the technique (I currently generate these through scripting as <authors-initials><date yyyymmdd><time to milliseconds>)

TBD: remove the * from ua-issues and resources (and maybe also from test and admin?)

A brief summary of the content of a technique, visible in the html version of the repository for quick scanning, not visible in the view but used for content of include elements to clarify what they point to.

(%head.pcd.mix;)*

• %common.att;

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

• %common.att;

groups paragraphs, examples, and other stuff describing the checklist-item associated with a particular technique

(%obj.mix;)*

• %common.att;

groups a number of ua-issue elements

(ua-issue)+

• %common.att;

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

This element should be used only in repository files.

Groups a number of pointers to additional resources associated with a given technique.

(resource)*

• %common.att;

TBD: Note that the above is not totally truthful. The real content model is (resource*, (see-also | tech-source)*), but I have phased out the see-also and tech-source elements in favour of resources elements with appropriate resource-type attributes.

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 refs.xml file. If this is a simple web page that doesn't merit an unique entry in the refs.xml file, point to the URL entry in refs.xml. If you have not yet added the entry you can temporarily point to the TBD entry in the refs.xml file.

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)

• @resource-type (source | background | implementation | other): identifies the type of resource. This information will be used for grouping and ordering resources in the XSLT-generated view data. source refers to sources for the information included in a technique; background refers to useful background reading related to this technique; implementation refers to information such as instructions that helps you take the next step and implement the recommendation in the technique; other is a catch-all, and may be split into other categories in the future.
• @id: a unique id for this resource pointer

TBD: Consider whether other should be split into additional categories. For example, should the current xref element become <resource resource-type="xref">?

For use in the view only. Used at the end of a section.

Its presence indicates that you wish to create a list of resources at the end of the section. It may also contain cross-references to other sections in the view. Do not include any resources or resource elements in this element.

(xref-list?, resource*, (%obj.mix;)*)

• no attributes

TBD: Remove everything but the xref-list.

TBD: Ensure that an empty one of these triggers the XSLT to include the resources in the repository.

Used only in views.

Groups a number of cross-references.

(xref+)

• no attributes

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+)

• no attributes

Describes the target of a link.

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

• no attributes

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.

Indicates scripts for which this technique is relevant.

Choose either [a] 'all' or [b] 'na' or [c] one or more script types.

( all | na | (latin | alpha | arabic | hebrew | fareast | seasia | indic )+)

• no attributes

Values for the scripts element. These are elements rather than attribute values so that it is easy to ensure that only valid alternatives are being used. The element alpha represents Latin plus other alphabetic scripts, such as Greek, Cyrillic, Armenian, Cherokee, etc. fareast represents Chinese, Japanese and Korean scripts. seasia refers to Thai and similar scripts.

EMPTY

• no attributes

Provides information about which user agents, and which versions of those, support the recommendation in the technique.

This element should contain only one instance of any particular subelement. If there is no information about a particular user agent, simply leave out the subelement for that ua.

(ie|nn|op)*

• no attributes

Each element represents a user agent, and if present indicates that the technique is applicable to that user agent, or a specific version of that user agent.

ie stands for Internet Explorer (Windows). nn stands for Netscape Navigator. op stands for Opera. Other elements may be added as information becomes available (eg. ie-mac, safari, etc.).

EMPTY

• @version: 'Y' if the earliest version of that browser we are concerned with supports the recommendation of the technique, or if the technique is not browser specific. '-' if the browser does not support this recommendation. A number if only a later version of the browser (above the earliest versions we are concerned with) supports the recommendation (eg. '6' as the version for an ie element indicates that this is supported only for IE version 6 and above).

Copied from WCAG but currently not used by GEO.

Copied from WCAG but currently not used by GEO.

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;

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

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

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;

Used to point to text in the repository that will be included at this point in the view.

(%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 view will not extract short-name or resource information for inclusion in the view at the point where the include element appears with mode set to technique. Rule would extract just the checklist-item - it is not yet used, but may soon be used to create a checklist type view. 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.

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.

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;

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;

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;

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.

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

(%tech.pcd.mix;)*

• %common.att;

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;

See the description for ins above.

(%p.pcd.mix;)*

• %common.att;

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.

See the description of req above

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

• No attributes.

The text of a requirement.

(%p.pcd.mix;)*

• %common.att;

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

(%tech.pcd.mix;)*

• %common.att;