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] Proposal 12017 - consistency between map & topic metadataand 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?


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:


    The abstract element occurs between the topic title and the topic body, as the initial content of a topic.

    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


France Baril wrote:
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


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

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