addendum to <unknown> design

[Erik Hennum <ehennum@us.ibm.com>]

Hi, Vigorous Committee Members:

I've revised last week's note to provide a more complete summary of the discussions as an addendum to Eric Sirois's original write up:

http://www.oasis-open.org/apps/org/workgroup/dita/download.php/15123/IssueNumber35.html

Many thanks to Paul Prescod, Eric Sirois, and Michael Priestley for working through the disagreements.


Erik Hennum
ehennum@us.ibm.com


The <unknown> element is an open extension point for the DITA architecture to allow communities of interest to share standard vocabularies for non-textual content.

Illustrative examples of such standard vocabularies include ChemML, MathML, and SVG.  In most cases, the enabler for a foreign vocabulary  will want to specialize the <unknown> element so that the contexts for the foreign vocabulary can be validated.  The specialization of <unknown> provides a container element for the foreign vocabulary with DITA class, conref, and selection attributes.  (One can think of the specialized <unknown> element as the DITA adapter for the foreign vocabulary.)

The <unknown> element is not an extension point for textual discourse.  Adding new element names for textual markup by specializing from <unknown> is an abuse of the DITA architecture. For instance, a DITA adopter who wishes to create valid DITA topics but use element names from the NewsML vocabulary must specialize the DITA textual elements like <section>, <p>, and <ph>.  This requirement ensures broad interoperability (including both tool reuse and content sharing) for the textual news content.

Here's the definition for <unknown> in Schema syntax:

<xs:element name="unknown" type="unknown.class"/>
<xs:complexType name="unknown.class">
    <xs:choice minOccurs="0" maxOccurs="unbounded">
        <xs:any processContents="lax"/>
    </xs:choice>
    <xs:attribute name="outputclass" type="xs:string"/>
    <xs:attributeGroup ref="univ-atts"/>
    <xs:attributeGroup ref="global-atts"/>
    <xs:attribute ref="class" default="- topic/unknown "/>
</xs:complexType>

Here's the equivalent definition in DTD syntax:

<!ELEMENT unknown ANY>
<!ATTLIST unknown
             %univ-atts;
             outputclass  CDATA  #IMPLIED
             %global-atts;
             class CDATA "- topic/unknown ">

The enabler of the foreign vocabulary must provide the processing by overriding the base processing for <unknown>.

The base processing for <unknown> ignores the contents of <unknown> except for the first instance of a DITA <desc>, <object>, or <image> element (or specialization thereof).  Within a specialization of <unknown>, the specializer should typically define a content model that enforces this requirement so the writer doesn't create base content that is ignored by base processing.  Where appropriate, the specializer may specialize a nested <desc> element to provide alternate content that is valid in the contexts for the <unknown> specialization.

If an instance of the <unknown> element doesn't contain a <desc>, <object>, or <image> element, the base processing may emit a warning about the absence of processable content.

The <unknown> element can appear in the following contexts:

• The end of content models for metadata containers such as the <prolog>, <metadata>, and <topicmeta> elements. For instance, someone could specialize <unknown> to support Learning Object Metadata (http://ltsc.ieee.org/wg12/files/IEEE_1484_12_03_d8_submitted.pdf) for topics.
  
• Any block context within the body of topics. For instance, someone could specialize <unknown> to support inline SVG as a peer of the <p> or <ul> elements.
  
• Any textual keyword context. For instance, someone could specialize <unknown> to support MathML phrases as a peer of the <keyword> element (though not within the <keywords> element).
  
• Within the <data> element so properties can make use of unknown vocabularies for their values.
  
• Within the <object> element after the <param> element. The base processing for <object> emits the content of <unknown> as a file at the location specified by the data attribute of the <object> element. Thus, the output for the <object> element gets the data from the inline content at runtime. Because of this special treatment of the container, base processing ignores any DITA elements within the <unknown> element.

Footnote:  In a future DITA version, the Technical Committee should work on cascading fallbacks for unknown or external objects (either sequential as in DocBook or nested as in HTML).