OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

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
search (yes|no) #IMPLIED
linking (normal|none) #IMPLIED
toc (exclude|include|link) #IMPLIED
print (yes|no) #IMPLIED
scope (internal|external|peer) #IMPLIED
<!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. -->
<!ATTLIST navref
toc CDATA #FIXED "link"
linking (normal|none) "none"
<!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 "

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

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]