Leigh, many thanks for taking the time to provide your review.
I did want to quickly address one area where I think you are
making a large cognitive mistake ...
You commented ""XDITA is really XHTML authored with an eye to
interchange with LwDITA". It absolutely is not. XDITA is a
lightweight version of DITA 1.3; it is the XML variant of
Lightweight DITA, not the XHTML variant of Lightweight DITA.
I do agree, off course, that "HDITA is really HTML5 authored with
an eye to interchange with LwDITA. MDITA is really Markdown
authored with an eye to interchange with LwDITA."
Thanks, Leigh. I'm going to provide a list of your comments to
make it easier for the team to view them:
3 What is Lightweight DITA? -- Last bullet
LW: Should be a level-2 bullet?
3.2 Support for non-XML formats -- "In its initial release,
LwDITA has three authoring formats:"
LW: I realize this is a core explanation of LwDITA but it's
troubled me since the beginning. And now that you're asking for
my opinion, well... :-)
It's potentially confusing, I think, to say that LWDITA has
three formats: XDITA, HDITA, and MDITA. Or to say that
"X/H/MDITA is the authoring format of LwDITA that uses
XHTML/HTML5/Markdown to structure information." This phrasing
risks the misconception that LwDITA has three separate
tagsets--one for interchange with XHTML, one for interchange
with HTML5, and another for interchange with Markdown. That's
not the case, not really.
XDITA is really XHTML authored with an eye to interchange with
LwDITA. HDITA is really HTML5 authored with an eye to
interchange with LwDITA. MDITA is really Markdown authored with
an eye to interchange with LwDITA. They are not variants of
To me, the LwDITA interchange with these other formats is
analgous to using Simplified English with an eye to translating
to Chinese. It would be misleading, then, to say that
"Simplified English is the authoring format of Chinese that
makes translation easier" (or vice versa).
This explanation also positions LwDITA as the content creation
medium and XHTML/HTML5/Markdown as the targets...implying that
you use one the "variants" of LwDITA to create content that will
be converted to one of the other formats. While this might be
the case, I think it's more common that the process will be
reversed--XHTML/HTML5/Markdown will be the authoring medium and
LwDITA the conversion target.
It's more accurate and clearer, I think, to say that "X/H/MDITA
represents a subset of the XHTML/HTML5/Markdown tagset that
facilitates interchange with LwDITA to structure information."
I think it comes down to...do we consider LwDITA to be:
* a specific tagset, i.e. a subset (mostly) of standard DITA
that has interoperability with subsets of the
XHTML/HTML5/Markdown tagsets (or markers in the case of
* specific DITA-based tagset but also the XHTML/HTML5/Markdown
tagsets, which although not defined in the LwDITA spec and not
explicitly part of the LwDITA tagset, are understood to come
under the same "interoperability umbrella," as it were.
The first option is much clearer to explain and easier for folks
to wrap their heads around, I think. There is one LwDITA tagset,
period. Folks who have been using DITA for some time are
accustomed to thinking of it as a solid thing--a certain set of
tags. When they are creating DITA content, they see those tags,
period. When considering LwDITA, they can easily understand that
LwDITA consists of a subset (mostly) of the standard DITA tags.
When creating a a LwDITA topic, they expect to see that subset.
If they were creating an HTML5 topic, they'd expect to see
*that* tagset available to them. If they were creating a
Markdown topic, they'd expect to see *those* markers available
to them. In their minds, they are creating one thing or another.
It's a weird and murky area to explain that, "No, actually
LwDITA is all of those things." A natural reaction might be,
"Well, then rather than calling LwDITA "Lw*DITA*" when it
actually means XHTML and HTML5 and Markdown and DITA, why not
come up with a name that covers all four, like
"MarkupInterchange" of which LwDITA is one aspect, rather than
expecting us to understand that DITA doesn't mean just DITA
anymore but a bunch of other stuff, unless you're talking about
*standard* DITA, in which case DITA still means just DITA."
But as we seem pretty heavily invested in this
explanation/concept, then an upfront explanation (and perhaps a
contrast with the first point) would be very helpful.
This point affects numerous places throughout this paper, which
I have not specifically marked.
Typo on page 10
Change other --> others
Missing period on page 12
5 LwDITA authoring formats -- Departments who want to
reduce the cost of developing and maintaining style sheets
LW: Honestly, while it's worth mentioning, I don't see this as
much of a driver. In my experience, groups are (unfortunately)
still not especially willing to compromise on output formatting.
They are happy to work with a more complex structure (sometimes
even adding complexity of their own) if it means their output
will be JUST SO. This may change as content becomes less
persistent (e.g. daily automated updates)
Correct indent in code sample
Page 16 -- "All XDITA topics are designed to be fully
compatible with DITA 1.3 topics."
LW: A bit misleading? I think it will be a very common
scenario to have LwDITA topics alongside standard DITA topics in
a standard ditamap. These multimedia elements are a glitch in
that scenario in that they are not present in standard DITA and
impede complete compatibility. What is the recommendation? That
groups specialize these elements from <object> in their
standard DITA DTDs, just as they have been specialized in
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
+1 919 682-2290; kriseberlein (skype)
On 6/19/2017 11:36 AM, Leigh White
Apologies…posted originally in error to
Per your request to review the note,
which Keith passed along, I’m attaching a commented version
of the note that I just read through. The crux of my
commentary is in the sticky note on p. 9. I noted a few
other minor things and typos as well. Being a bit gun-shy
about critiquing committee work, I’d like to stress that I
approached this note as if I were a naïve user…how much
sense would it make? Would the relationship between LwDITA,
XHTML, HTML5, and Markdown be clear? And, as I explain in
the note, I don’t think it would. As always, take this as my
two cents, to acknowledge or ignore. My continued thanks and
gratitude to the committee for all of your hard work!
825, Querbes suite 200 | Montreal,
Quebec, Canada, H2V 3X1
toll free: + 1 877 279-4942
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: