In my opinion, LwDITA and DITA 2.0 specs must be aligned.
Elements need to have the same meaning -- and the same, basic
formatting and processing expectations. Otherwise we have
interoperability issues (and unexpected results). Obviously, since
DITA 2.0 is a richer architecture, there will be formatting and
processing expectations for it that do not apply to LwDITA.
Thoughts from other TC members?
Another comment: The DITA TC has previously decided that it CANNOT
EVER use normative language for formatting requirements in a
specification. Your suggested wording in the e-mail below violates
this principle.
Obviously, we might run into issues trying to do strict single
sourcing and so might need to be creative. Working together will
improve the quality and consistency of both specs.
A tagging tip: You'll want to tag your <ph> tags that
enclose normative phrases with an @outputclass value so that you
can easily locate them. For consistency with the DITA
specification, I suggest using a value of "RFC-2119".
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 1/26/2019 4:03 PM, Alan Houser
wrote:
Hi Kris,
Thanks! Replying here mainly to get this in front of the full
TC ... Carlos and I (and Robert, I believe?) have looked at
issues around sharing content between the LwDITA and DITA specs.
We've concluded that, for reasons of implementation, workflow,
schedule, and audience, sharing content beyond <shortdesc>
would be highly challenging, even problematic.
To address the question -- "How would LwDITA spec editors
rephrase the first paragraph to remove the mention of "element"?
The LwDITA spec favors the component name (in this case,
"Phrase"). So ... "The phrase component is used to enclose a
phrase for reuse, variable substitution, conditional processing,
or semantic tagging." Or perhaps just "Phrase is used ...".
Here's a snippet from the LwDITA spec that shows how we're
proposing to address rendering in the Processing Expectations
sections:
<p>In text, processors <ph>SHOULD</ph>
render the contents of <ph>bold text</ph> in
typographical bold. In audio and other rendering formats,
processors <ph>MAY</ph> distinguish the contents
of <ph>bold text</ph> in some other way.</p>
Looking forward to further discussion.
-Alan
On 1/26/19 1:22 PM, Kristen James
Eberlein wrote:
Thanks for the thoughtful response, and see <kje>
comments below
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 1/26/2019 12:09 PM, Alan Houser
wrote:
Thanks, Kris. Dispatching the DITAweb comments was
obviously a substantial amount of effort.
Just to run a couple of items up the flagpole --
- The use case for <ph> differs substantially between
DITA and Lightweight DITA. In DITA, <ph> is clearly a
basis for specialization. OTOH, specialization is not a
priority for Lightweight DITA 1.0, and <ph> is much
more likely to be used as a generic semantic wrapper, for
filtering or other purposes (or, in both specs, as a conref
container). We may want to consider conditional processing
on <shortdesc> content between the two specs (only for
<ph>), or punt on <shortdesc> reuse between the
specs for <ph>.
<kje>When we can, we need have a common short
description, and save conditional processing for the following
sections: "Usage information," "Formatting expectations," and
"Processing expectations." Elements must have the same basic
meaning in DITA 2.0 and LwDITA.
I've reworked the <ph> topic as follows; I also sent
e-mail regarding it to Carlos and Deb, who were the folks who
made comments in the DITAweb review:
<ph>
A phrase is a small group of words that
stand together as a unit, typically forming a component of a
clause.
- As I author topics for the LwDITA spec, I find the
"Formatting Expectations/Processing Expectations"
distinction to be more tedious than I anticipated.
"Formatting" _is_ "Processing". As I write LwDITA spec
content, I'm not assuming content will be rendered as text,
which further clouds the distinction. (I expect audio and
machine consumption will be increasingly popular use cases).
<kje>This brings up a good point; we probably need to
explicitly state "For text rendering" in the "Formatting
expectations." And think more in the DITA 2.0 spec about how
audio and machine consumption should affect spec topics ...
But, as we've mentioned in TC calls, we need to look at
single-sourcing material for sections other than the short
descriptions. Processors will need to handle elements the same
way, whether in LwDITA or DITA 2.0. Obviously there might be
more processing requirements for DITA 2.0.</kje>
Looking forward to our discussion Monday and beyond.
-Alan
On 1/26/19 8:40 AM, Kristen James
Eberlein wrote:
Remember the DITAweb review that was run in October 2018?
I've spent about 20 hours this work going through the
DITAweb review, resolving what I can, and compiling a list
of items that still need resolution.
Here's a summary:
- Short descriptions: 10 topics need discussion.
I've set up a meeting for noon - 1 PM ET on Monday, 28
January 2019; ping me if you want an invitation.
Currently, the attendees will be me, Robert, Carlos, and
Alan. Attached is an HTML summary of the comments that
we'll begin with.
- Examples: Lots of comments here
- We need to standardize the introductory paragraphs
that precede the code blocks. We need to decide what
is the best approach, and whether we will identify a
few patterns that can be used, or a single pattern.
- Concern that some of the examples are too US-centric
or inaccessible to ESL readers, for example, a
reference to Rotten Tomatoes and "How to purchase
SuperWidgets from the warehouse." We need to enhance
our guidelines for example.
- Suggestions of multiple additional examples. We need
to review our existing guidelines for examples and see
what they say. My gut sense is that many of the
proposed examples are too complex and do not belong in
element reference topics.
Two topics need to be reworked and reviewed: <fn>
and <ph>. Ughhh ...
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
--
Alan Houser
Group Wellesley, Inc.
Consultant and Trainer, Technical Publishing
arh on Twitter
412-450-0532
|