RE: [dita] Proposal 12017 - consistency between map & topic metadata and abstract vs shortdesc

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