DTD for XR: XML representation of textual XML files

This software is part of the gloss system. Author: Richard Kaye, 2006-7, copyright reserved. Licence: This software may be used under the conditions of the latest version of the GPL. No warranty.

XML documents exist in many ways in a computer system, notably as in-memory infosets and as textual files. An in-memory XML infoset does not itself determine a unique textual representation or serialization of the XML document, though other applications, especially a non-XML text-based application may require a particular textual format for an XML file. This DTD sets out to define an accurate XML represention of an external textual XML file.

Valid XML documents matching one of the three main elements here (document, document-fragment and dtd) will be called XR documents. XR documents may exist in any form, such as in memory, or in a file with a particular character encoding, but it is expected that they will in the main be created or transformed in memory, and printed with a special program similar to an XSLT stylesheet. (For technical reasons due to the way character data must be escaped, it is infeasible to write an XSLT stylesheet to print out such data.)

The GLOSS system contains such a program, uk.ac.bham.gloss.XRPrinter. This DTD and its documentation defines the relationships and content model of the XR elements and the way a processing program should output each type of node of an XR documents.

An additional program, uk.ac.bham.gloss.XRNormalizer, provides a pre-processing stage for an XML document loosing conforming to this specification to be transformed to one exactly matching the specification.

The current scope and progress of the work here is as follows:

This DTD is designed to be used as a standalone DTD or to be included in other DTDs. The standard prefix is xr but this may be redefined using DTD parameters in the usual way. This documentation will refer to elements in this namespace with the xr: prefix, but this prefix may be altered by the usual mechanisms.

xr.nsprefix defines the prefix for these elements; redefine this to use another prefix.

xr.namespace defines the namespace for these elements.

xr.prefixed is INCLUDE or IGNORE as to whether these elements should be prefixed.

This is a list of element names defined here. Items on this list describe features in the output XML file.

Parameter entity xr.reference lists elements allowed for a reference; since such references are not expanded and may be internal characters these are allowed by this DTD in text or attribute values. However, further XML well-formedness and validity constraints may apply to the resulting document.

Parameter entity xr.corpi lists elements allowed more-or-less anywhere in a document; it maps to comment or processing-instruction.

Parameter entity xr.dtd-content lists all elements allowed at top level in a (full) DTD.

Parameter entity xr.intdtd-content lists all elements allowed at top level in an internal DTD.

Parameter entity xr.element-content lists elements allowed in the content of an element.

The document element is a top level element representing an XML document and its xml declaration. Attribute xmldecl="include" or "omit" determines if the XML declaration <?xml ... ?> should be present, and attributes version, encoding and standalone provide the additional data for this declaration. When version is required, "1.0" is the default.

The attribute bom provides a suggestion to the processing application whether to insert a Byte-Order-Mark (\uFEFF) in the output. This may be overriden by the application, for example it is expected that a BOM will always be included where it is manditory irrespective of the value of the bom attribute.

Output encoding is UTF-8 by default, but is selected by the encoding attribute. Legal values for encoding depend on the platform, but should include

The dtd element is a top level element representing an XML DTD and its xml encoding declaration. Attribute xmldecl="include" or "omit" determines if the encoding declaration <?xml ... ?> should be present and attributes version and encoding provide further data for this declaration. When version is required, "1.0" is the default. Attribute "bom" is used as for the "document" element. Output encoding is UTF-8 by default, but is selected by the encoding attribute as for document.

The document-fragment element is a top level element representing an XML text declaration for a document fragment. Attribute xmldecl="include" or "omit" determines if the encoding declaration <?xml ... ?> should be present and attributes version and encoding provide further data for this declaration. When version is required, "1.0" is the default. Attribute "bom" is used as for the "document" element. Output encoding is UTF-8 by default, but is selected by the encoding attribute as for document.

The docype element represents the DOCTYPE declaration of an XML document. Attributes define the name of the root element, the PUBLIC identifier and the SYSTEM identifier. The root element name is determined automatically if not present, and it is recommended that it is omitted where possible. The content of the node represents the internal DTD subset (if any). Standard XML rules apply to DTDs. See the section on DTDs for more information.

The literal element can only contain text and signifies that the literal text be inserted into the output. White space is significant in the content of this element. There is no guarantee that the resulting output text is well-formed XML.

The attribute element provides an attribute to an element, the element defined by the parent node of this element. An attribute may be defined many times, in which case it is the first value that takes precidence.

Use as:

The name of the attribute is given in the "name" attribute. If the name of the attribute has a namespace-prefix the namespace MUST be provided in the ns attribute, and conversely, if the attribute has no prefix then the "ns" attribute must not be given. Processors should report any cases contrary to these rules as errors.

It is possible that a single prefix is associated with serveral conflicting namespaces by use of the "element" and "attribute" tags. Processors must signal all such errors.

The cdata element creates one (or more) cdata sections on the output. The data should be the text content of the element and on printing should be escaped by replacing all "]]>" with "]]]]><![CDATA[>". Therefore, any data may occur inside cdata but users should not expect a single cdata element to necessarily result from a single cdata node.

The comment element describes a comment to appear on the output. The data is the text content of the node (white space, as always, being significant) and escaped by replacing all the double-hyphen combinations "--" with "&#x2D;&#x2D;". (So for example "---" becomes "&#x2D;&#x2D;&#x2D;".) The data is normally wrapped with <!-- and -->, but the single space character in either of these combinations may be omitted if they precede (respectively follow) whitespace in the text.

The element element defines an element node with the name and namespace given. Except for the prefixes xml and xmlns, it is an error to omit the ns attribute if name has a prefix. It is an error to give two or more different ns values corresponding to same same prefix in an element and its attributes. Elements SHOULD be printed where feasable with the empty element syntax <name/> though it may not be possible to guarantee this.

The character-reference and entity-reference elements define a character reference or entity reference &amp;name;. The character-reference element and entity-reference are operationally identical, though character-reference should be used for explicit (hexadecimal or decimal) numerical characters whereas entity-reference should be used for a named reference to a sequence of 1 or more characters. Processors MUST NOT expand the reference and NEED NOT check that the name is valid. The string name is given by the name attribute.

The processing-instruction element represents a PI. The node should be printed as <?target data?> using value of attribute target as target and content data as default value. This data is the PCDATA content with any ?> in the content being transformed to ?&amp;lt; on output. The space separating target and data may be omitted if data starts with ' '.

The text node is is a place-holder for text, output as escaped PCDATA. The data is printed in a by escaping using XML escapes &amp; &le; &ge; &quot; and possibly also &quot;.

The group element is available to group together a section of an XR document. It is not permitted in any elements mentioned here, but is available for looser versions of this document type. (See other information on normalizing XR documents for more details.)

Marking-up DTDs presents a problem, as DTDs are conceptually text-based and use parameter entities as macros. Most DTD elements defined here allow a choice of either structured content or else very free dtd-text (e.g., using parameter entities). This encourages the free dtd-text to follow the maximum amount of general structure of the declarations. (Something that is required by the XML standards anyway.) It also enables the XML representation of the DTD to be as clear as possible about the structure of the DTD.

Avoiding use of the element dtdtext completely except in the austere form when dtdtext is only allowed to contain a parameter-entity-reference would aid DTD processing considerably, and would allow almost all extant DTDs to be written. This is allowed as an experimental DTD option here.

It was tempting to define this XML vocabulary with a syntax using attributes much more heavily, but this would have complicated the issues of processing considerably, and ordinary XML elements are much simpler.

XR mark-up for DTDs allows the source to simply provide plain DTD text as an alternative. (This is to cater for macro-like processing that the DTD processor does using parameter entities.) Users (or application software) are encouraged not to use plain text but to mark-up their DTDs as far as possible using the specific mark-up defined here. Occasionally there is no option, however.

The xr.dtdreference entity lists elements allowed for references that may occur in a DTD. The element dtdtext can contain any DTD constructs. It is intended that dtdtext be used as a way of showing the structure, or of bracketing DTD constructs, i.e., content of dtdtext should be entire grammatical DTD constructs. This DTD cannot guarantee that, however.

The name element is used to mark-up the fact that the content is a valid name, usually the object being declared.

Many DTD constructs involve quoted strings. Quotes as plain text can be problematic. It is better to mark-up quoted strings with the q or qq elements. The XR printer will wrap these with ' ... ' or " ... " respectively.

Text or CDATA node children of dtdtext, name, q, qq are printed verbatim (i.e., unescaped) by the XR printer or other XR processors. This rule may not apply to other decendents other than immediate descendants. The usual rules for the standard xml:space attributes apply.

A pentity-reference contains the name of a parameter. The XR printer will wrap it with % ... ;. Only PCDATA is allowed as content; this should be white-space trimmed by processors, and the result should be a valid name.

We next have a complex set of declarations for element and attribute declarations, content specification, and attribute types and defaults. Entities children, contentspec, atttype, defaultdecl and attdef define valid child-content-specifications, content-specifications, attribute-types, attribute-default-declarations and attribute definitions, respectively. Each has dtdtext as a fall-back option.

These are used in the definitions of elementdecl and attlistdecl, the mark-up specifications for element-declarations and attribute-list-definitions. The definitions here should be self-explanatory. XR-processors or printers should wrap elementdecl with <!ELEMENT ... > and attlistdecl with <!ATTLIST ... >.

We now have a group of elements for element-content-specifications. These (and their intended display) are: clist resulting in ( child , child , ... , child ); calts resulting in ( child | child | ... | child ); copt resulting in child ?; crep resulting in child +; coptrep resulting in child *; mixed resulting in (#PCDATA| child | child | ... | child )*; ANY resulting in ANY; EMPTY resulting in EMPTY; PCDATA resulting in (#PCDATA). In some cases, the XR-processor not only wraps the child-content but ands a separator between children.

Next defined are the elements for mark-up of attribute defintions. Again, these are self-explanatory, with the following desplays intended: CDATA resulting in CDATA; ID resulting in ID; IDREF resulting in IDREF; IDREFS resulting in IDREFS; ENTITY resulting in ENTITY; ENTITIES resulting in ENTITIES; NMTOKEN resulting in NMTOKEN; NMTOKENS resulting in NMTOKENS; notationtype resulting in NOTATION ( name | name | ... | name ); enumeration resulting in ( name | name | ... | name ); REQUIRED resulting in #REQUIRED; IMPLIED resulting in #IMPLIED; FIXED resulting in #FIXED child.

The elements systemid, publicid and publiclit match grammar elements with the same names in the XML specification. They print out as SYSTEM data, PUBLIC pdata sdata and PUBLIC pdata repectively. (The difference beteen a public literal and a public identifier is that a fall-back system URI is not needed for the latter. Don't ask me, I didn't write the spec!) The data, pdata, sdata etc are quoted, so should be presented in q or qq elements. dtdtext presents a fall-back for nonstructured systemid, etc. (In other words you have to get it right yourself!)

The tags pentitydecl, entitydecl, notationdecl mark-up parameter-entity, entity and notation declarations. In all cases you can provided the content yourself with dtdtext content and the content will be printed wrapped with <!ENTITY % ... >, <!ENTITY ... >, or <!NOTATION ... >. Otherwise you must specify the name of the object being declared and its data. The data is either a string (marked-up with q or qq) or a system or public id, (in the case of entitydecl, optionally with an NDATA notation name) or (for notationdecl) a publiclit. ndata is marked-up content that resolved to an XML name, the name of a notation.

The tags INCLUDE, IGNORE, conditional mark-up conditional inclusions. Content should be provided as shown in dtd-content. The attribute "name" is the name of a parameter-entity controlling inclusion and in this form produces <![%name;[ ... ]]>. (If you want something more complicated than this you'll have to code it with dtdtext.)

See the documentation elsewhere for more about this DTD and the GLOSS XML representation.