DITA 1.2 Implementation Notes

This document captures issues raised during the DITA 1.2 draft preparation that pertain more to implementations than to specifications. The end goal may be to formalize an Implementer's Guide or other best practices document that is ancillary to the spec, proper. The format may change; for now, this is simply a means to log issues separated out as the result of TC reviews of the 1.2 draft spec.

Hazard Statement Width

The main issue here is citation of relevant authorities for values that might be built into editing assist tools by implementers. Chris Kravogel is the owner of this issue.

* http://lists.oasis-open.org/archives/dita/200903/msg00008.html (Kravogel suggested actions)

From DITA TC minutes: "After a discussion of whether the issue was user error or a styling issue and whether the DITA spec should refer to the ANSI spec moved, seconded, and approved to have the spec contain language along the lines of setting the hazard symbol width to be larger the hazard statement width is an error; an implementation might (but need not) generate an error message, and the an implementation might (but need not) recover from the error condition."

Use of <term>

From DITA TC minutes:

* http://lists.oasis-open.org/archives/dita/200903/msg00028.html (Kravogel, and following)

"After a discussion of whether to expose this item on dita.xml.org (or hand it off to the Adoption Committee), Don Day moved to strike the sentence from current draft and add the content of note #34 to new implementation-issues page. Seconded by Gershon Joseph and approved by acclamation."

Note 34:

I see no harm in the spec giving indications to vendors as to what they should be developing.

This is an important function that's been in my requirements doc for six years or more, with no vendor supporting it. Process as follows: Writer marks an item in a topic with <term>. Processing harvests every <term> in all the topics in a map (or other aggregation). If a given <term>-tagged item also appears in an associated glossary document (associated in the publishing environment), it is included in a glossary for the publication that is assembled and published as part of that document, and appropriately linked in online renditions. If a given <term>-tagged item does not appear in the glossary, a flag is raised for someone to create a glossary entry for it, and until then that item is not rendered as a glossary item (link, etc.) or in any special way.

At present, glossaries are labor intensive, error prone, and often omitted although desired.

This is an example of how use cases may not be being communicated to vendors, and the spec can help close that loop. Relevance to adoption is obvious.