Re: [dita] Detail for bug fix item 7: Add mapref to map

[Don Day <dond@us.ibm.com>]

The previous message on this thread (http://lists.oasis-open.org/archives/dita/200412/msg00031.html) contained the rationale and markup examples for the #7. mapref proposal. Here are the details for the actual proposed markup.

Issue in a nutshell: Navref implies a way to refer to another map; conref provides a way to instance parts of another map, but neither is truly satisfactory for aggregating one or more maps within a parent map. The proposed mapref fix has the content model and properties to enable this desired level of structured regrouping. Navref does not go away, but it is no longer a core element; it can be added back into map as a constrained specialization of mapref.

To make this change, we:

1. Remove the navref declarations from map.mod; revise into a specialization of mapref (see item 5)
2. Define the %mapref; replaceable entity
3. Insert %mapref; into content models in place of %navref; (navref will get picked up by the redefined %mapref;)
4. Insert the following mapref declarations in the original locations of navref in map.mod
5. Insert the revised navref specialization into mapgroup.mod and adjust the DTD and ents for the addition

<!ENTITY % mapref      "mapref">
...
<!ELEMENT mapref          ((%topicmeta;)?)>
<!ATTLIST mapref
                          href         CDATA     #IMPLIED
                          mapref       CDATA     #IMPLIED
                          keyref       CDATA     #IMPLIED
                          title        CDATA     #IMPLIED
                          search       (yes|no)  #IMPLIED
                          linking (normal|none)  #IMPLIED
                          toc          (exclude|include|link) #IMPLIED
                          print        (yes|no)  #IMPLIED
                          format       CDATA     #IMPLIED
                          scope        (internal|external|peer) #IMPLIED
                          %id-atts;
                          %select-atts;
>
...
<!ATTLIST mapref %global-atts; class CDATA "- map/mapref ">

The attributes of mapref have the following explanations and processing:

@href		points to the map
@mapref	points to the map (instead of href). Already deprecated, only there for navref support.
@keyref	key for alternate resources
@title		no processing intent. Present as a hint to what you're pointing at.
@search	no processing intent. Present to match @search on map and topicrefs
@linking="normal | none". Processing default=normal.
		linking=normal means that the hierarchy and reltables in the map will generate links.
		linking=none means no links will be generated based on the target map.
@toc="exclude | include | link". Processing default = include.
		toc=exclude means the map will not be part of your navigation
		toc=include means the map will be part of your navigation
		toc=link means we will generate a link, to be resolved at run-time. This is the current navref support.
@print="yes | no". If @print=no, the map will not be retrieved or used for PDF. Processing default=yes.
@format 	CDATA field, suggested value is ditamap. Could also point to an Eclipse toc.
@scope="internal | external | peer". Processing default=internal.
		scope=internal means the map is available, and should be used
		scope=peer means it is part of your product, but cannot be accessed
		scope=external means it is external to your information, and cannot be accessed
id-atts:		@id, @conref
select-atts:	@audience, @platform, @product, @otherprops, @rev, @importance, @status

Separately, global-atts and class="- map/mapref "



The relocated navref-as-domain will go into mapgroup.mod.  The attlist retains @mapref for compatibility, but this attribute is deprecated in favor of @href, both of which should be supported equivalently by 1.0-level processors.  

<!-- NOTE: @mapref is deprecated; retained for now for compatibility.
Please plan to migrate your sources from @mapref to @href. -->
<!ELEMENT navref          EMPTY>
<!ATTLIST navref
		href         CDATA #IMPLIED
		mapref       CDATA #IMPLIED
		toc          CDATA #FIXED "link"
		linking      (normal|none) "none"
		%select-atts;
>
...
<!ATTLIST navref %global-atts; class CDATA "+ map/mapref mapgroup/navref ">

The constrained attlist from mapref has the following explanations and processing:
 
@href		replaces @mapref
@mapref	deprecated
@toc		#FIXED as "link"
@linking	#DEFAULT value of "none", but should allow "normal | none"
select-atts:	@audience, @platform, @product, @otherprops, @rev, @importance, @status

Separately, global-atts and class="+ map/mapref navref/mapgroup "


Regards,
--
Don Day <dond@us.ibm.com>
Chair, OASIS DITA Technical Committee
IBM Lead DITA Architect
11501 Burnet Rd., MS 9037D018, Austin TX 78758
Ph. 512-838-8550   (T/L 678-8550)

"Where is the wisdom we have lost in knowledge?
Where is the knowledge we have lost in information?"
        --T.S. Eliot