Re: [dita] Supporting LwDITA Implementors Quickly

[Eliot Kimber <ekimber@contrext.com>]

I didn't mean to imply that a formal LwDITA spec should be deferred, only to point out that the current committee note serves the needs of implementors today *as long as* there is not likely to be drastic change in the LwDITA design, so having a formal spec take whatever amount of time it takes should not be an issue in practice for people who want to implement or use LwDITA today.

My assumption that the LwDITA design is stable is precisely for the reasons Alan gives: the subset was carefully thought out and is in any case an arbitrary choice that, having been set, doesn't really need to be changed for the very reason that you can always move to full DITA using the LwDITA design as your base and add (or remove) anything you want using normal DITA configuration mechanisms. 

That makes LwDITA as much a marketing exercise as anything: like XML itself, it's simply codifying a subset that anyone was always free to define, but by doing so makes the idea clear and allows it to be marketed to groups for whom the idea of "just a subset of DITA" would either not make sense or would not have the same appeal as a ready-defined thing. 

That and the working out of the mappings from HTML5 and markdown, which is significant technical work that will have value to the DITA community generally.

But the power of standards is really having been written down, not having been formally approved, and in that context the committee note is a good as an approved spec as far as adoption and implementation are concerned. (And if you need any more evidence of that look at markdown itself which is the most under-specified authoring format I can think of and yet is widely adopted simply because it is so useful.)

Cheers,

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

ïOn 2/7/19, 8:37 AM, "Alan Houser" <dita@lists.oasis-open.org on behalf of arh@groupwellesley.com> wrote:

    I'm always grateful for Eliot's insights, and I think the TC's recent 
    discussion of LwDITA has been helpful in framing the vision of the 
    LwDITA spec editors and SC and (ultimately and hopefully) aligning the 
    SC's vision with that of the full TC. To address these points:
    
    - I disagree that the TC should defer a formal LwDITA spec, and position 
    the committee note as the canonical definition of LwDITA. But that's 
    probably a longer discussion.  :-)
    
    - Re: the SC's confidence in the LwDITA vocabulary -- I'll posit that 
    Eliot has been in the standards business long enough to know that this 
    is impossible to answer. Having said that:
    
         + The LwDITA vocabulary was chosen carefully, with input from 
    representatives of the target audiences.
    
         + At the risk of speaking for other SC members, we have high 
    confidence in the LwDITA vocabulary.
    
         + LwDITA avoids the strategic mistake made by other vocabulary 
    subsets, of omitting a major use case explicitly to encourage use of the 
    "full" vocabulary. I have in mind Simplified DocBook, which punted on 
    content aggregation, which it could have very easily supported. I'll 
    also acknowledge that I was not on the DocBook TC, but this was my 
    perception from the outside.
    
         + Any subset will have feature boundaries, and we expect (and have 
    begun to see) tension around this. "Why doesn't LwDITA support X?". To 
    this question, our answer should be "You should use DITA". I'll note 
    that these questions tend to come from adopters who have DITA 
    experience, not members of our newer LwDITA target audiences.
    
    - I would caution against efforts to align or modify LwDITA terminology 
    to match any particular authoring format. LwDITA has the goal of being 
    source-format agnostic. We chose the term "components" carefully. This 
    term was tested pretty heavily in the committee note reviews. We got 
    some pushback from "XML-centric" reviewers, but these individuals 
    appeared to come on-board when we explained the term. The term "works" 
    for the three initial authoring formats, and will work for other 
    mappings as they come.
    
    HTH!
    
    -Alan
    
    On 2/5/19 12:37 PM, Eliot Kimber wrote:
    > 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
    >   
    >
    -- 
    Alan Houser
    Group Wellesley, Inc.
    Consultant and Trainer, Technical Publishing
    arh on Twitter
    412-450-0532
    
    
    ---------------------------------------------------------------------
    To unsubscribe from this mail list, you must leave the OASIS TC that 
    generates this mail.  Follow this link to all your TCs in OASIS at:
    https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php