|
I want to address a few points that Alan raises:
Role of the LwDITA committee note
An OASIS committee note is (by definition) a non-standards track
work product. As such, a committee note cannot provide a
"canonical definition." However, I do think the LwDITA committee
note presents a clear description of the LwDITA design that is
more than adequate for implementers to use to develop LwDITA
applications and implementations.
Terminology that the DITA TC uses in formal OASIS documents
What terminology we can use is very context-driven. OASIS
publications are divided into two tracks, and the terminology that
we can use differs, I think, based on the track:
- Standards track
OASIS specifications define an OASIS standard. They must follow
the OASIS-provided template that covers both what a
specification must contain and how it is formatted.
Specifications must contain normative references, use keywords
from either [RFC2119] or [ISO/IEC Directives], and include
conformance clauses that refer to the normative statements (made
using [RFC2119] or [ISO/IEC Directives]) that appear in the body
of the specification.
What terminology can (or perhaps must) we use in specifications?
This has not been explored or tested. One approach might be that
we must use the vocabulary that is used in the specifications
that are the normative references: DITA, XHTML, and XML
specifications. We may well need to get OASIS Technical
Advisory Board involved to help us here.
- Non-standards track
OASIS committee notes provide ancillary information to assist in
understanding and implementing the Standards Track work. They
must follow the OASIS-provided template that covers both what a
committee note must contain and how it is formatted. Committee
notes must not contain normative information.
I'd argue that committee notes have greater latitude in the
vocabulary used. If LwDITA advocates want to use the generic
term "component," that is OK, although I wonder if the term
"structural component" might be more precise.
Note that I am avoiding the term vocabulary, since I think
it overlaps with meaning of what structural components (elements
and attributes) are permitted in LwDITA.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 2/7/2019 9:37 AM, Alan Houser 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
Â
|