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



Rob Hanna


From: Ogden, Jeff [mailto:jogden@ptc.com]
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.




From: Kristen James Eberlein [mailto:keberlein@pobox.com]
Sent: Wednesday, August 19, 2009 1:23 PM
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".
  • "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."

Language reference

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.


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

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