Table of Contents

1. Introduction
    1.1 Notational Conventions
    1.2 Namespaces
2. Applying the unit-dictionary convention
3. UnitList Element
    3.1 Unit
    3.2 Children
4. Unit Elements
    4.1 Children
5. Example Unit Dictionary

Appendices

A. References
B. Acknowledgements

1. Introduction

There is already a mature convention for units. The simpleUnit convention is a toy example used in an article to help explain how conventions are constructed, tested and specified.

The following is typical text intoducing why a convention is required, what is is used for and how it should be used.

Units are required throughout CML and are usually indicated using the units attribute. Each unit needs to have a unique identifier and be defined in such a way that they can be understood by both humans and machines.

Lists of units are similar to dictionaries but require more information for each "entry" such as their relationship to a standard (SI) base unit or what type of unit they are i.e. the units metre, angstrom and picometre are all of type length whilst the unit Kelvin is of type temperature. The phrases "unit list" and "unit dictionary" are used interchangably; the only reason for choosing one term over the other is for readability.

Where units are already defined in the standard unit dictionaries (see http://www.xml-cml.org/unit/) these units SHOULD be used, rather than redefining the concepts in another unit dictionary.

1.1 Notational Conventions

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [ IETF RFC 2119 ].

The terms "element", "attribute", "child" and "parent" in this document are to be interpreted as described in the W3C Recommendation for Extensible Markup Language (XML) [ W3C XML ].

The use of fonts is as follows:

• Schema terms, including elements and attributes, are written in this font.

1.2 Namespaces

This specification uses the following namespaces and prefixes to indicate those namespaces:

2. Applying the simpleUnit convention

The simpleUnit convention MUST be specified using the convention attribute on a unitList element.

3. UnitList Element

3.1 Unit

The unitList element MUST contain at least one unit child element.

3.2 Children

A unitList element MAY contain child elements from the CML namespace or from foreign namespaces.

<?xml version="1.0" encoding="UTF-8" ?>
<unitList xmlns="http://www.xml-cml.org/schema"
     xmlns:convention="http://www.xml-cml.org/convention/"
     xmlns:xhtml="http://www.w3.org/1999/xhtml"
     convention="convention:simpleUnit"
     <description>
         <xhtml:p>
            This is an example unit list for demonstration purposes
         </xhtml:p>
     </description>
     <unit>
     <!-- rest of document omitted -->
     </unit>
</unitList>

4. Unit Elements

4.1 Children

A unit element MAY contain child elements from the CML namespace or from foreign namespaces.

5. Example Dictionary

<?xml version="1.0" encoding="UTF-8" ?>
<unitList
        xmlns:convention="http://www.xml-cml.org/convention/"
        xmlns="http://www.xml-cml.org/schema"
        xmlns:h="http://www.w3.org/1999/xhtml"
        convention="convention:simpleUnit"
        >
    <unit>
    </unit>
    <unit />
</unitList>

A. References

[RFC2119]

IETF RFC 2119: Key words for use in RFCs to Indicate Requirement Levels , S. Bradner, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.

[XML]

Extensible Markup Language (XML) 1.0 (Fifth Edition) , T. Bray, J. Paoli, C.M. Sperberg-McQueen E. Maler and F. Yergeau, Editors. World Wide Web Consortium. 26 October 2008. This version is http://www.w3.org/TR/2008/REC-xml-20081126. latest version of XML is available at http://www.w3.org/TR/REC-xml.

B. Acknowledgements

• Joe Townsend