OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [dita] Summary: Status of review of the DITA2.0/LwDITA intersection topics


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


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]