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

Okay, Erik, I think I understand the situation better now. Thanks for the explanation.

So an abstract isn't really an abstract - it's just the first few paragraphs of the topic body, with embedded shortdesc elements to contain search preview.

Similarly shortdesc when used alone isn't really a short description separate from the topic body - it's the first paragraph of the topic body, when that's considered short and summary enough to serve for a search preview.

Given that we're going against convention here with the names - especially abstract - I think perhaps the spec should be a little clearer that both of these are part of the topic body, and not separate from it.

The offending verbiage is as follows:
The abstract element occurs between the topic title and the topic body...
The short description (<shortdesc>) element occurs between the topic title and the topic body...
These locutions seem to imply that abstract and shortdesc don't form a part of the topic body proper - when in fact they do, even if they aren't part of the relevant <body> element. That's where the confusion creeps in.

Maybe we could say something like:
The abstract element contains the first paragraph-level elements of a topic's body text; the remainder appears in the topic's body element...
Something like that would be less confusing I think.


Erik Hennum wrote:

Hi, Dana and France:

Maybe the name <abstract> is creating expectations different from what is specified.

From DITA 1.0 onward, the short description provides a summary of the content of a topic. This summary appears at the top of the topic (encouraging inverted pyramid writing) and in linking contexts including search results lists as a preview.

The purpose of <shortdesc> in the <topicmeta> for <topicref> is similar to the navtitle attribute for <topicref>: to override the default linking text specified by the topic in one linking context. That is, two navigation contexts can override the title and short description for the same topic in different ways.

DITA 1.1 added <abstract> because adopters wanted to have a brief linking summary but a longer introductory block. DITA 1.1 still supports the DITA 1.0 practice but, in addition, allows embedding <shortdesc> within an introductory <abstract>, as in:

<topic id="libraryGoals">
... <title>The goals of the library</title>
... <abstract><shortdesc>A library should support what each reader wants to accomplish.</shortdesc> The
....... core principles are:
....... <ul>
....... <li>Books are for use.</li>
....... <li>Every person his or her book.</li>
....... <li>Every book its reader.</li>
....... <li>Save the time of the reader.</li>
....... <li>The library is a growing organism.</li>
....... </ul>
... </abstract>
... <body>
....... <p>When S. R. Ranganathan first identified these core principles, ...</p>
... </body>

In linking contexts, the default description (which a map context can override) for this topic is "A library should support what each reader wants to accomplish."

In the flow, the <title> is followed by the <abstract> and then the <body>.

Regarding map metadata, I wouldn't think that a block like <abstract> would be a good way to express metadata. The <data> element could represent any kind of data including metadata. Also, references to definitions can express metadata (but that's maybe a discussion for the controlled values proposal).

Hoping that clarifies,

Erik Hennum

Dana Spradley <dana.spradley@oracle.com> wrote on 06/20/2007 08:36:28 AM:

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

> How would this translate in maps?
> 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.

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