[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Replying to Leigh: Summary of Leigh White's comments on the Lightweight DITA Committee Note
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."
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 6/19/2017 12:35 PM, Kristen James Eberlein wrote:
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)
Page 15
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?
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)
On 6/19/2017 11:36 AM, Leigh White wrote:
Hi all,
Apologies…posted originally in error to
Adoption Committee.
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!
Best,
Leigh
Leigh White
DITA Specialist
825, Querbes suite 200
| Montreal, Quebec, Canada, H2V 3X1
toll free: + 1 877 279-4942
leigh.white@ixiasoft.com/ www.ixiasoft.com
---------------------------------------------------------------------
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]