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
|