Kris/Carlos,
Thanks for your replies. I think we've articulated the somewhat
opposing expectations, goals, and constraints here, along with the
compatibility requirement.
Kris -- thanks for your tips on spec verbiage and markup.
Take care,
-Alan
On 1/26/19 6:05 PM, Carlos Evia wrote:
I am coming out of my no-email Saturday to comment on
this:
It will be very difficult to reuse more than short
descriptions from 2.0 in the LwDITA spec. We have made
experiments and an extended alignment of sections makes the
topics XML-centered, and the references to DITA-specific
behaviors are hard to hide. For a quick example, LwDITA has
components instead of elements, and the 1.3 to 2.0 drafts
use the term "element" quite frequently.
Since we started working with LwDITA in its current three
authoring formats, we decided to avoid an "XML goes first"
approach, and sharing more than short descriptions will make
XML the queen and HTML5 and Markdown the ugly stepsisters.
And, worst, that would set back the development of the
LwDITA spec. If we start from the existing 2.0 draft topics
and extend/adapt them to a) represent XDITA and b) include
HDITA and MDITA.... it will be 2020 at least.
So... I look forward to Monday's conversation and we can
take a look at the draft LwDITA component topics and see if
there's a compromise for alignment (we already have the
short descriptions) that does not mean repeating
XML-oriented processing expectations and examples.
Best,
Carlos
--Â
Carlos Evia, Ph.D.
Associate Professor of
Communication
Chair, Hispanic/Latino Faculty
& Staff Caucus
Virginia Tech
Blacksburg, VA 24061-0112
(540)200-8201
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.
Usage
information
TheÂ<ph> Âelement
often is used to enclose a phrase for reuse or
conditional processing.
TheÂ<ph> Âelement
frequently is used as a specialization base, to
create phrase-level markup that can provide
additional semantic meaning or trigger specific
processing or formatting. For example, all
highlighting domain elements are specializations ofÂ<ph> .
I think this content is
germane to both DITA 2.0 and LwDITA. Obviously, the
2nd paragraph is only germane to XDITA. How would LwDITA spec editors
rephrase the first paragraph to remove the mention
of "element"?
- 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
---------------------------------------------------------------------
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
--
Alan Houser
Group Wellesley, Inc.
Consultant and Trainer, Technical Publishing
arh on Twitter
412-450-0532
|