Supporting LwDITA Implementors Quickly

[Eliot Kimber <ekimber@contrext.com>]

Given that Lightweight DITA is a proper subset of DITA plus a mapping from HTML and markdown syntax, the important definition of LwDITA is:

- The set of elements and attributes used from full DITA 
- The syntactic and semantic mapping from HTML and markdown to those elements (including illustrative examples)

Both of these things appear to be adequately defined in the published committee note.

As long as both the subset and the mappings are stable then the committee note is sufficient for implementors and the TC can communicate that to the community.

So that raises the question: How confident are we that the subset and mappings are stable?  I'm assuming that the SC is happy with the current state of the LwDITA definition and does not intend to change it but is that true? We have working implementations of MDITA and HDITA processing, which suggests that the mapping as define in the committee note is good.

The committee note is not a formal specification, so we still need that, but I don't see the existence of that specification as being a prerequisite for implementations as long as what is specified in the committee note is stable. The committee note certainly presents itself as "this is what LwDITA is", not "this is kind of what we have in mind for LwDITA". 

I will also observe that the GitHub markdown specification referenced in the committee note is defined in terms of the mapping from markdown to HTML so it certainly presumes an understanding of angle bracketed things by the target audience of that document, which clearly includes markdown processing implementors as well as authors (there's a lot of language in that spec about processing, including a whole section on parsing strategies). Likewise the HTML5 recommendation uses the term "element". I've always understood the markdown community to understand that it is fundamentally a syntax for representing HTML, not a thing that exists in isolation.

One of the challenges with discussing markdown is that it does not have a one-to-one correspondence between significant syntax strings and the HTML elements they imply. Given that, there is no single term that will work for both markdown syntax as well as HTML and XML elements.

That is, markdown is *not* a markup language, it's a set of keyboarding shortcuts for HTML (what in SGML were "short tags" and that we explicitly removed from XML to make parsing it simple enough and to make the syntax invariant). I have never seen any discussion of any form of abstract data model representation of markdown, only its mapping to HTML.

So it seems reasonable to me to continue to use the term "element" in general and find a more precise language to describe the markdown representation of LwDITA documents.

It might make sense, for example, to have a standalone specification or committee note that is only the MDITA specification, more in line with the GitHub markdown spec, rather than having only an all-in-one specification.

That is, if one of the goals is to make LwDITA most accessible to markdown-primary implementors and authors, it seems like a markdown-specific specification or committee note would be the best way to do that. That specification or committee note could then simply make reference to the separate full DITA specification or to a separate XDITA/HDITA specification that provides the LwDITA-specific reference entries for the LwDITA elements. The main LwDITA specification would still need to formally define the mapping from markdown strings to elements and attributes, as well as additional mechanisms required to capture things that markdown can't represent directly.

Cheers,

E.
--
Eliot Kimber
http://contrext.com