RE: [dita-adoption] Groups - DITA 1.2 Feature Article: Convenience Elements (DITA12ConvenienceArticle.pdf) uploaded

["Bruce Nevin (bnevin)" <bnevin@cisco.com>]

I had hoped to address this during this week, but there have been too many loose ends to chase (including installing an editor because of recent PC refresh, and job offers that evaporated), and tomorrow is my last day at Cisco unless lightning strikes twice. So with regret and apology I must leave this for someone else.

	/Bruce

-----Original Message-----
From: Nitchie, Chris [mailto:cnitchie@ptc.com] 
Sent: Monday, August 01, 2011 3:26 PM
To: dita-adoption@lists.oasis-open.org
Cc: Helfinstine, David
Subject: RE: [dita-adoption] Groups - DITA 1.2 Feature Article: Convenience Elements (DITA12ConvenienceArticle.pdf) uploaded

Dave Helfinstine and I have been reviewing this document, and we have some concerns. Specifically, the discussion of topicset and topicsetref strikes us as not quite correct. From the list of convenience elements:

"<mapref> includes an entire map by reference"
A mapref may also include a branch inside a map if the URI of the href specifies a fragment identifier.

"<topicset> defines a group of <topicref> elements as a referenceable branch of a map."
Any topicref can be a referenceable branch so long as it specifies an ID. A topicset identifies a topic structure that can stand on its own. (I'm not entirely clear on what the processing implications of <topicset>, or <topicref chunk="to-navigation">, are, but I'm confident that this description isn't quite complete.)

"<topicsetref> includes a submap by reference to a branch of a map defined by the <topicset> element."
Any branch can be included by reference via <mapref> (which is just <topicref format="ditamap">) so long as the href specifies the ID of the branch. A topicsetref allows you to reuse a topicset without re-specifying its structure.

"<topicgroup> specifies attributes and linking characteristics to be shared by a group of <topicref> elements in a map."
A topicgroup can also be used to specify a referenceable set of sibling topics without affecting the TOC structure.

The section on mapref, topicsetref, and topicset proceeds from the above descriptions of those elements, which we don't feel are correct. For example, here are some statements that I think are wrong or misleading.

"Use the <topicssetref> element to incorporate just part of a map into the current map."
You'd use a mapref for this purpose, pointing to any topicref with an ID in the target map. Again, topicsetref allows you to reuse the contiguous topic structure specified by a topicset.

"When a map that contains <topicset> is processed, the <topicset> element is effectively invisible, as though it were not there."
While true for <topicgroup>, this is absolutely not true for <topicset>. The topicset is rendered in the output, and the topic it references is the top-level topic in the contiguous topic structure described by the topicset and its children.

One important point that's never explicitly made is that all of these convenience elements (with the possible exception of topicgroup) derive their behavior from the way their attributes are defined in the DTD, not because of their names.

<mapref/> == <topicref format="ditamap"/> <topicset/> == <topicref chunk="to-navigation"/> <topicsetref/> == <topicref format="ditamap"/> <topicgroup/> == <topicref/>* (a topicgroup can't have @href or a @navtitle. This is the only one whose name/@class gives it special behavior, as a topicgroup is "invisible" in the TOC/document structure even if it contains topicmeta with a navtitle.)

There are also numerous errors and typos in the example markup throughout the document, as well as a few other relatively minor issues. I've attached Dave Helfinstine's marked-up PDF, which points these out.

Chris

-----Original Message-----
From: joann.hackos@comtech-serv.com [mailto:joann.hackos@comtech-serv.com]
Sent: Thursday, July 07, 2011 4:01 PM
To: dita-adoption@lists.oasis-open.org
Subject: [dita-adoption] Groups - DITA 1.2 Feature Article: Convenience Elements (DITA12ConvenienceArticle.pdf) uploaded

The document revision named DITA 1.2 Feature Article: Convenience Elements
(DITA12ConvenienceArticle.pdf) has been submitted by Dr. JoAnn Hackos to the OASIS DITA Adoption TC document repository.  This document is revision
#1 of DITA12ConvenienceArticle.pdf.

Document Description:
A number of &quot;convenience elements&quot; have been specialized in DITA
1.2 to simplify the work of creating and maintaining maps and to make it easier for a map author to read and understand them.. -- Authored by Bruce Nevin

View Document Details:
http://www.oasis-open.org/committees/document.php?document_id=42842

Download Document:  
http://www.oasis-open.org/committees/download.php/42842/DITA12ConvenienceArticle.pdf

Revision:
This document is revision #1 of DITA12ConvenienceArticle.pdf.  The document details page referenced above will show the complete revision history.


PLEASE NOTE:  If the above links do not work for you, your email application may be breaking the link into two pieces.  You may be able to copy and paste the entire link address into the address field of your web browser.

-OASIS Open Administration