France--
I'm new to this issue, and must admit I'm a bit confused too.
Apparently shortdesc used to be intended for one thing, and now it's
doing double or triple duty thanks to its new roles in maps and
abstracts.
Could someone more involved with the 1.1 changes to these elements
please explain the current situation to the rest of us? The spec seems
a little contradictory.
--Dana
France Baril wrote:
Hi Dana and Erik,
How would this translate in
maps? Obviously, following the discussion on transitional text, the
short descriptions in maps are not going to be the first paragraph of
anything. Are they, therefore, to be used as link previews only (what I
called rollovers in my previous emails)? Then again, if maps are only
containers, there should not be any links to them, except from the
table or content. Then why would I even need short descriptions?
I thought abstract would provide
a better opportunity for metadata. I can include information that will
help me find and retrieve maps in my database and I can be consistent
in the way I use elements: full sentences in abstracts, partial
sentences in shortdescriptions.
Maybe we only need to define the
purpose of shortdesc in maps + how it is intended to be used, and then
document it. I find it a bit confusing right now.
Regards,
France
From: Dana
Spradley [mailto:]
Sent: Tuesday, June 19, 2007 12:31 PM
To: France Baril
Cc:
Subject: Re: [dita] Proposal 12017 - consistency between map
& topic metadata and abstract vs shortdesc
Hi France--
Actually, when used alone, and not inside an abstract, shortdesc is
meant to figure as the first paragraph of the topic body:
The short description (<shortdesc>)
element occurs between the topic title and the topic body, as the
initial paragraph-like content of a topic... Use the <shortdesc>
element when the first paragraph of topic content is simple enough to
be suitable for use as a link preview or for summaries.... In cases
where a topic contains only one paragraph, then it is preferable to
include this text in the <shortdesc> and leave the topic body
empty.
While an abstract would appear first in a topic, I assume it would be
set off as an executive summary or some such, and not appear as part of
the body of a topic, as shortdesc alone would.
Erik and I have had some ex parte communication on this, which I
reproduce for the group below:
Hi Erik et al--
Thanks for the links - I downloaded the latest pdf and reviewed as
well. I guess I hadn't been keeping up on the abstract documentation,
and had only seen it for shortdesc.
Nevertheless, I think France still has a point.
While abstract is the first content of the topic, I assume it's
intended to be set off as an abstract, and not figure as part of the
body of the topic. shortdesc, on the other hand, when used alone, is
meant to figure as the first paragraph of the body.
It would seem, then, that abstract is more a kind of "topic metadata"
than shortdesc. And while it's unlikely one would want to override the
first paragraph of the body of a topic based on its inclusion in a
certain collection of topics - it's much more likely one might want to
override a topic's introductory abstract or executive summary based on
the collection's parameters.
BTW - there seems to be a bit of a contradiction built into shortdesc
now - it's the first paragraph of the body when used alone - but when
embedded in an abstract, does it's content also figure as the first
paragraph(s) in the body?
--Dana
Erik Hennum wrote:
Hi, Dana and France:
As background for revisting whether <abstract> should get pulled
into the map, here are the existing definitions of the elements:
http://docs.oasis-open.org/dita/v1.1/CD02/langspec/langref/abstract.html
The abstract element occurs between the topic title and the topic body,
as the initial content of a topic.
http://docs.oasis-open.org/dita/v1.1/CD02/langspec/langref/shortdesc.html
The short description, which represents the purpose or theme of the
topic, is also intended to be used as a link preview and for searching.
At least, I believe these are the latest versions of the specification.
Hoping that's useful,
Erik Hennum
--Dana
France Baril wrote:
Link
to proposal 12017: http://www.oasis-open.org/apps/org/workgroup/dita/download.php/24420/IssueNumber12017.html
With
this proposal, the committee is making an effort to increase
concistency between maps and topics. However, it also states: The map metadata will still have
several elements that are not present in topic prologs: linktext,
searchtitle, shortdesc, and (assuming that implementation of item
#12018 results in this element) navtitle.
With
the arrival of abstracts in DITA 1.1 topics, the proposed usage
of <abstract/> and <shortdesc/> is as follow:
* Abstract: Full sentences that can be used for automated overviews,
summaries. They are also the topics' first paragraph.
* Shortdesc: Phrases, sentence segments that provide 'hints' when users
roll over related links or xrefs.
Keeping
shortdesc instead of including abstract in the map metadata may lead to
inconsistency on the way people use the shortdesc element in maps and
topics. Are shortdesc elements in map used for 'roll over' purposes
only? I'm not sure a partial sentence is very useful, even as metadata.
Since
this may bring up the whole transitional text discussion, the
committee has moved to accept proposal 12017 as is, but has suggested
that we bring up this discussion on the list. So here it is: should we
introduce abstract in map metadata for the sake of consistency in the
way elements are used?
France Baril
Documentation
Architect/Architecte documentaire
IXIASOFT
tel.:
+ 1 514 279-4942 x350
+ 1 877 279-IXIA x350
fax:
+ 1 514 279-3947
[ www.ixiasoft.com
]
Let's Talk XML
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.5.472 / Virus Database: 269.9.0/853 - Release Date:
6/18/2007 3:02 PM
No virus found in this incoming message.
Checked by AVG Free Edition.
Version: 7.5.472 / Virus Database: 269.9.1/854 - Release Date:
6/19/2007 1:12 PM
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.5.472 / Virus Database: 269.9.1/854 - Release Date:
6/19/2007 1:12 PM
