Need to make decisions around LwDITA and specialization

[Kristen James Eberlein <kris@eberleinconsulting.com>]

In order for work on LwDITA to progress, the subcommittee needs to make decisions about specialization. I’ll try to lay out the choices clearly, complete with the associated work items.

 

XDITA and specialization

Is specialization supported for XDITA? If the answer is yes, is it supported for all XDITA elements or only a subset of elements? If it is supported for a subset of elements, what elements are in the subset?

 

If specialization is supported, what about element configuration (constraint and expansion)?

 

Associated work items:

• Currently, the .mod files only use entities for the <data> and <ph> elements. If specialization is supported for XDITA, then entities need to be used for elements that can be specialized.
• DITA topic about “Specialization in LwDITA”

 

HDITA and specialization

Is specialization supported for HDITA? If the answer is yes, is it supported for all HDITA elements or only a subset of elements? (Obviously specialization cannot be accommodated by HDITA components where the information is conveyed by attributes, such as alternate text -- @alt on <img> -- and cross reference -- @href on <a>.) If specialization is supported for a subset of elements, what elements are in the subset?

 

If specialization is supported, what is the syntax used to convey the specialization hierarchy? The corollary to the XDITA @class attribute is the HDITA @data-class attribute. Currently, the @data-class attribute is used in the syntax only to differentiate between the various HDITA components that are based on <div> and <span>, for example:

 

• Key definition: <div data-class=”keydef”>
• Key text: <div data-class=”keytext”
• Note: <div data-class=”note”>

 

MDITA and specialization

If specialization supported for a subset of use cases using HDITA markup? If yes, what subset of use cases, for example, specializations of <section>?

 

Here’s what the committee note (2018) said about specialization:

 

4.6 LwDITA specialization

LwDITA follows the same specialization architecture as DITA 1.3, although there are some limitations and special rules.

Because LwDITA is a proposed standard that spans multiple authoring formats, coordination of the same specialization rules across markup languages poses some unique challenges compared to DITA XML. Therefore, not all LwDITA formats will support specialization to the same degree.

• In XDITA, authors can build new elements and attributes following the base architecture of LwDITA. Authors cannot add elements from DITA 1.3 to an XDITA specialization. For example, authors working in LwDITA cannot create an element <training-video> specialized from the DITA 1.3 element <object>. They must specialize it from the XDITA element <video>.
• In HDITA, an author can express specialized relationships for any content element using HTML5 custom data attributes.
• In MDITA, the lack of structuring tags does not allow authors to assign reliable attributes to particular elements within a piece of content. As a result, specialization within MDITA is limited to a subset of use cases (for example, section-level specialization) using raw HDITA syntax.

A general recommendation for LwDITA specializations is to keep in mind the lightweight nature of the proposed standard and avoid complicated content structures. Authors who need robust specialization for complex scenarios should use DITA 1.3.

Here’s what the current LwDITA draft spec states about specialization:

Caveat: I’m told this test was authored by Carlos Evia, but not reviewed or approved by the subcommittee. Emphasis added:

“LwDITA follows the same specialization architecture as DITA, although there are some limitations. Because LwDITA spans multiple authoring formats, coordination of the same specialization rules across markup languages poses some unique challenges. Not all LwDITA formats will support specialization to the same degree. For example, XDITA, the LwDITA authoring format based on XML, defines a default class attribute value for each component. This class attribute can be used as basis for specialization. In HDITA and MDITA—the LwDITA authoring formats based on HTML5 and Markdown, respectively—, there is no mechanism for specialization.”

Best,

Kris

 

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Owner, Eberlein Consulting LLC
kris@eberleinconsulting.com

Skype: kriseberlein; voice: +1 (919) 622-1501