• Language Specification Design

Design thoughts for DITA 1.2 Language Reference

Common use cases that are not possible with the DITA 1.1 language reference:

1. The contains/contained by sections change with every doctype. Including a static version is a) misleading for readers of the spec because it implies an inflexible model, and b) difficult for specializers to work with. I want to reuse the spec documents that define each element, but have my users find correct contains/contained-by information that includes my domain.
2. For my applications, I need to add statements of support for a few elements. I want that information to appear in a logical spot my local copy of the spec.
3. I would like my copy of the spec to include additional examples that highlight local best practices.
4. I have specialized attributes, so my local copy of the spec needs those added.
5. ...any other use cases...?

Proposed Design

Take advantage of both keyref and conref push/replace, which are new DITA 1.2 features, as well as a standard template for defining elements in the spec. Specifically:

• Contains and contained by information may be stored in an appendix. The information is generated (like today). Unlike today, it will be published as a unit, instead of using conref to pull sections into each topic.

• Each topic will contain an <xref> with keyref in the contains/contained-by sections. The OASIS specification will be published with that keyref pointing to the OASIS appendix. Any user may generate a local copy of the appendix, including local domains and document types, and point to that instead.

• For those that still want all of the contained/contained-by info inline, the new "Conref replace" feature allows you to replace the section with the information you see today (rather than creating an appendix). Alternatively, if you want a short version of the guide with no contains/contained-by info, you can replace the section with empty content.
• The new "Conref push" feature can push implementation info into any element (see sample below).
• "Conref push" can also be used to push additional examples into any element.
• Specialized attributes can be handled in one of two ways:
  • If the attributes are common everywhere (all instances of p contain the same attributes), conref replace can insert a new table of attributes.
  • If the attributes differ (in one document type p uses @newAttr, and in others it doesn't) conref replace can either insert both tables with explanatory text, or it can link to an appendix like the contains/contained-by information.

Now that everyone is fully confused

Here is a sample of how this could work. The template for each element would be:

<reference id="element-name">
  <title>element-name</title>
  <shortdesc>Description of the element</shortdesc>
  <refbody>
    <!-- Additional description, if needed -->
    <section id="contains">
      <title>Contains</title>
      <p>The content model of this element may differ based on where it is used.
         Content model information is located here: <xref keyref="element-name-contains"></xref></p>
    </section>
    <section id="containedby">
      <title>Contained By</title>
      <p>The parents of this element may differ based on where it is used. Content model
         information is located here: <xref keyref="element-name-contained-by"></xref></p>
    </section>
    <section id="inheritance">
      <title>Inheritance</title>
      <p>- topic/element</p>
    </section>
    <example id="example"> example here </example>
    <section id="attributes"> 
      <simpletable id="attribute_table"> ... </simpletable>
    </section>
</reference>

Technical specifics

For reference, the description of Conref Push and Conref Replace is here: http://www.oasis-open.org/committees/download.php/26290/IssueNumber17e.html

Linking to contains/contained-by

The contains/contained by information will be generated as it is today. It is generated as an appendix (may be one file or many depending on the scenario). Each topic will contain a keyref with the format of "element-name-contains"; that key will be defined in the map as a link to the proper topic in the appendix. Formatters may chose how to render this information; the default OASIS distribution would likely be a simple link, but another implementation could render the information as pop-up help.

Adding implementation info

Every element will have a section with id="contains" following the description of the element. Conref push may be used to insert a new section with tool specific information before #element-name/contains (so it appears immediately after the standard description).

Adding examples

Every element will have an example, with id="example". Conref push may be used to insert additional example elements either before or after the common example.

Attribute updates

This is the trickiest item to work with. The attribute table and the section that contain it each contain a standard ID. If the revised set of attributes are always common (every instance of that element has the same attribute set), then "conref replace" may be used to replace the actual attribute table. If the attributes differ, such that an element has some attributes in one document type but others in a second document type, then conref replace may be used to replace the entire section. The new section can include a single attribute table with additional explanatory information, or multiple attribute tables, or a link to external information (similar to the contains and contained by sections).

Questions

• Are any use cases not yet met by this design?
• Any better way to handle attributes?
• Any better way to handle contains/contained-by?
• Any big un-noticed things that will keep this from working?