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 LwDITA.
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 Markdown)
* 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 LwDITA?
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: