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

Since the mail archiver seems intent to strip out leading whitespace on proportional text, let's try it again in a mono font. I won't try again if this gets stripped in the archives.

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 <>

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