Re: [dita] Interoperability of DITA and LwDITA (Was "Re: [dita] Summary: Status of review of the DITA2.0/LwDITA intersection topics")

[Carlos Evia <cevia@vt.edu>]

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

On Sat, Jan 26, 2019 at 5:40 PM Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

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:

1. 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.
   
2. Examples: Lots of comments here
1. 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.
2. 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.
3. 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

Attachment: smime.p7s
Description: S/MIME Cryptographic Signature