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

["Ogden, Jeff" <jogden@ptc.com>]

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:keberlein@pobox.com]
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