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
