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.
--Dana
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>
</topic>
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
ehennum@us.ibm.com
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.
|