Re: [dita-lightweight-dita] Need to make decisions around LwDITA and specialization

[Michael Priestley <mfcpriestley@gmail.com>]

I think the original scope for specialization in LWDITA was something like:

- structural specialization down to the block level (ie from topic and body down through section/ul/ol/dl/simpletable/p)
- domain specialization for ph, data, and metadata attributes

We can simplify further by removing the data element (I was defending it last call, but I don't have a full mapping worked out for HTML or MDITA, and I think having it in XDITA alone would be worse than not having it at all), and forgettingÂabout metadata attribute specialization - everyone can just useÂ@props orÂ@data-props.Â

That leaves us withÂ@data-class as the method for declaring specialization hierarchy in HDITA, using a simplified syntax that omits the base element (with the exception of cases where the base element is required to differentiate between multiple uses of the same HTML element, like the <div> examples you shared).

I know I still need to go through the list of all XDITA elements and declare which ones should have an equivalent data-class available to them in HDITA.Â

The distinction between XDITA and the others should not be the ability to express specializations, but the ability to express their rules/relationships. In other words, we can support having a specialized topic in HDITA, but we are not going to differentiate domain vs structural specializations, or declare the list of specializations used in the header etc. - the job of validating the content is left as an exercise for the developer. We are not reinventing DTDs or schemas for HTML and Markdown.Â

Michael

On Tue, Dec 20, 2022 at 5:20 AM Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

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

Â