RE: [dita] <shortdesc> in a DITA map

I am a late-comer to this discussion so I apologize if this is
coming from left field.

 

I am a firm believer that the <shortdesc> is not strictly
metadata but rather content used as metadata. In fact, the <shortdesc>
may very well be the most important content in the topic on par with the title.
I can see instances where the title needs to be overridden to produce parallel
entries in a map where the topic is used outside of its original context but I
see a real problem where the <shortdesc> is overridden.

 

Looking forward to work we are doing in BusDocs, I envision the
<shortdesc> specialized to provide highly-relevant semantic information
for some of the topic types we are examining.

 

I strongly argue for correcting the spec for 1.2 to conform with
the current behavior of the OT. Let’s not further disambiguate the use of
<shortdesc>. We can dream up some future metadata element to handle the
Option B use case in DITA 1.3.

 

Cheers,

Rob Hanna

 

From: Ogden, Jeff [mailto:] 

Sent: August 19, 2009 4:04 PM

To: Kristen James Eberlein; DITA TC

Subject: RE: [dita] <shortdesc> in a DITA map

 

I think I’m going to argue that we shouldn’t try to
resolve this for DITA 1.2 and leave it as something to be addressed for DITA
1.3.  I guess this may be option C.

 

Here is my thinking on this:

 

·        
The DITA 1.1 spec. is ambiguous about how shortdesc in a map
should be handled.

·        
But an argument can be made that the DITA 1.1 spec. comes
closest to calling for option A (link preview only).

·        
But option A that makes shortdesc processing a special case when
compared to how other metadata in a map is processed.

·        
I think it would be better to be consistent and to treat
shortdesc in the same way that we treat other metadata elements (option B).

·        
I think this will make it easier for users to remember.

·        
I also think it will avoid additional questions about the interaction
of @lockmeta and @keyref processing with shortdesc processing.

·        
But option B is a bigger departure from the DITA 1.1 spec. and
as such, it isn’t a decision we should make in a rush or something that
we should force on implementers late in the development of the DITA 1.2 spec.

·        
And if we were to go with option B, then we’d be
immediately confronted with the question of adding a new element, perhaps
<linkpreview>, for the purposes of specifying link preview text in a map
without overriding shortdesc in a topic.  And that would likely delay
finalizing work on DITA 1.2 even further.

·        
And so deferring resolution of this to DITA 1.3 seems to be the
best course of action at this time.

 

   -Jeff

 

From: Kristen James Eberlein
[mailto:] 

Sent: Wednesday, August 19, 2009 1:23 PM

To: DITA TC

Subject: [dita] <shortdesc> in a DITA map

 

The review of the DITA 1.2 architectural spec has generated
some disagreement about how the content of the <shortdec> element in a
DITA map is used. Everyone agrees that the content of the <shortdesc>
element is used for link previews, but there is disagreement about whether or
not the content of the <shortdesc> element, when used in a DITA map,
overrides the content of the <shortdec> element in the DITA topic.

(If you want to read the Wiki comments about this, go to http://wiki.oasis-open.org/dita/ditaMaps
and search on <shortdesc>.)

Both the DITA 1.1 architectural spec and language reference contained
contradictory information about how the content of the <shortdesc>
element is used (emphasis added):

Architectural spec

 
"Metadata inheritance between maps and
     topics" states that the content of the <shortdesc> element is
     "not added to the topic; applies to links created based on
     this occurrence in the map".

     http://docs.oasis-open.org/dita/v1.1/OS/archspec/topicmetainheritance.html

 
"Common DITA map attributes and
     metadata" states "When a set of topics is transformed using a
     map, duplicate topic versions can be created using the copy-to attribute.
     The copied topic will have a new file name or location as provided in the
     copy-to attribute, and the map can override the default title and
     shortdesc for this particular copy by providing values for them in the
     map using the topicref's navtitle and shortdesc."

     http://docs.oasis-open.org/dita/v1.1/OS/archspec/dita_spec_23_common.html

Language reference

 
"shortdesc" states "When used
     within a DITA map, the short description of the <topicref> can be
     used to override the short description in the topic."

     http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/shortdesc.html

 
"abstract" states that the
     <abstract> element "can contain paragraph-level content as well
     as one or more shortdesc elements which can be used for providing link
     previews or summaries. The <abstract> element cannot be overridden
     by maps, but its contained <shortdesc> elements can be, for the
     purpose of creating link summaries or previews."

     http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/abstract.html

How do we want to handle this? Currently the DITA OT and
IBM's implementation use the content of a <shortdesc>, when used in a
DITA map, only for link previews. IBM has created a specialized element
(<overrideShortdesc>) to enable people editing a DITA map to force
content into the DITA topic.

I see three possible choices:

 
A: The content of the <shortdesc> element, when
     used in a DITA map, is used only for link previews.

 
B: The content of the <shortdesc> element,
     when used in a DITA map, overrides the content of  the
     <shortdesc> element in the DITA topic.

 
C: The content of the <shortdesc> element,
     when used in a DITA map, may or may not override the content of the
     <shortdesc> element in the DITA topic; the behavior varies depending
     on the implementation.

Thoughts? I like A, personally.

Kris

---------------------------------------------------------------------
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