LwDITA
Formatting expectations
When present, the content of the short description component is
displayed as the first paragraph of a topic. It may also be used
for other purposes, such as link previews and summaries.
DITA 2.0
Usage information
When present in topics, the content of the shortdesc element
is the first paragraph of the topic. It also is used for link
previews and search results.
When present in maps, the shortdesc element is associated with
topicref elements. This enables map authors to accomplish the
following goals:
- Associate a short description with a non-DITA object.
- Provide a short description that is specific to the map
context and used for link previews.
- Override the short description located in the associated
DITA topic, when the copy-to attribute is specified.
Processors might not implement this behavior.
When a shortdesc element applies to an entire DITA map, it
serves as description only.
Processing expectations
Processors SHOULD render the content of the shortdesc element as
the initial paragraph of the topic.
When processors generate link previews that are based on the
map context, they SHOULD use the content of the shortdesc that
is located in the map rather than the shortdesc that is located
in the DITA topic. However, processors SHOULD use the content of
the shortdesc element in the DITA topic when they render the
topic itself, unless the copy-to attribute is specified on the
topic reference to the element.
KJE commentary
LwDITA
and DITA 2.0 specs must make
the same normative statements about how processors render
shortdesc in a topic.
Markup that would enable
single sourcing
<section id="usage-information">
ÂÂÂÂÂ <title>Usage information</title>
ÂÂÂÂÂ <p>When present in topics, the content of the
<ph keyref="shortdesc-element"/> is the first
ÂÂÂÂÂÂÂ paragraph of the topic. It also is used for link
previews and search results.</p>
ÂÂÂÂÂ <p props="dita">When present in maps, the
<xmlelement>shortdesc</xmlelement> element is
ÂÂÂÂÂÂÂ associated with
<xmlelement>topicref</xmlelement> elements. This
enables map authors to
ÂÂÂÂÂÂÂ accomplish the following goals:</p>
ÂÂÂÂÂ <ul props="dita">
ÂÂÂÂÂÂÂ <li>Associate a short description with a
non-DITA object.</li>
ÂÂÂÂÂÂÂ <li>Provide a short description that is specific
to the map context and used for link
ÂÂÂÂÂÂÂÂÂ previews.</li>
ÂÂÂÂÂÂÂ <li>Override the short description located in
the associated DITA topic, when the
ÂÂÂÂÂÂÂÂÂÂÂ <xmlatt>copy-to</xmlatt> attribute is
specified. Processors might not implement this
ÂÂÂÂÂÂÂÂÂ behavior.</li>
ÂÂÂÂÂ </ul>
ÂÂÂÂÂ <p props="dita">When a
<xmlelement>shortdesc</xmlelement> element applies
to an entire DITA
ÂÂÂÂÂÂÂ map, it serves as description only.</p>
ÂÂÂ </section>
ÂÂÂ <section id="processing-expectations">
ÂÂÂÂÂ <title>Processing expectations</title>
ÂÂÂÂÂ <p>Processors <ph
outputclass="RFC-2119">SHOULD</ph> render the content
of the <ph
ÂÂÂÂÂÂÂÂÂ keyref="shortdesc-element"/> as the initial
paragraph of the topic.</p>
ÂÂÂÂÂ <p props="dita">When processors generate link
previews that are based on the map context, they
ÂÂÂÂÂÂÂÂÂ <term
outputclass="RFC-2119">SHOULD</term> use the content
of the
ÂÂÂÂÂÂÂÂÂ <xmlelement>shortdesc</xmlelement> that
is located in the map rather than the
ÂÂÂÂÂÂÂÂÂ <xmlelement>shortdesc</xmlelement> that
is located in the DITA topic. However, processors
ÂÂÂÂÂÂÂÂÂ <term
outputclass="RFC-2119">SHOULD</term> use the content
of the
ÂÂÂÂÂÂÂÂÂ <xmlelement>shortdesc</xmlelement>
element in the DITA topic when they render the topic
ÂÂÂÂÂÂÂ itself, unless the
<xmlatt>copy-to</xmlatt> attribute is specified on
the topic reference to
ÂÂÂÂÂÂÂ the element.</p>
ÂÂÂ </section>
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 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
|