DITA Proposed Feature #12047

Conveniences for map references.

Longer description

The DITA <topicref> element can refer to a map or a portion of a map so a container map can compose a hierarchy by reference to contained maps or portions of contained maps. To take advantage of this capability, however, the writer must know to set the attributes on the reference and, in some cases, the target.

Because composition of maps is critical for modular creation of navigation and other collections, DITA would benefit from conveniences that alert the writer to the availability of map composition capabilities and make it easy to compose maps including:

For an earlier version of this proposal, see the message http://lists.oasis-open.org/archives/dita/200703/msg00065.html.

Statement of Requirement

Use Cases

Scope

Minor; adding four elements that set default values of attributes.

Technical Requirements

The conveniences for map composition consist of the following four elements:

<mapref>
Supports a reference to a child map by defaulting the format attribute to the "ditamap" value. The hierarchy of the child map is merged into the container map at the position of the reference and the relationship tables of the child map are added to the parent map.

Here is an example of a <mapref> that imports map navigation:

<map id="lib">
  <topicref href="netlib.dita"/>
  <topicref href="dblib.dita"/>
  ...
</map>
...
<topichead navtitle="Developing with standard libraries">
  <mapref href="lib.ditamap"/>
  ...
</topichead>
<topicset>
Supports definition of a referenceable and reusable branch of navigation by defaulting the chunk attribute to the "to-navigation" value and by requiring a value in the id attribute.

A <topicset> defines a complete unit of content (a supertopic) that can stand independent of the containing, prior, and following content within the navigation. A <topicset> can aggregate other <topicset> units as part of its content, which is particularly useful for task composition in which larger tasks that are composed indefinitely of smaller tasks.

<topicsetref>
Supports reuse of a branch of navigation defined as a <topicset> by defaulting the format attribute to the "ditamap" value and the type attribute to the "topicset" value. The referenced <topicset> can be defined in the current map or another map.

A <topicsetref> differs from a conref, which copies a branch, in that the referenced branch of navigation retains its identity. That is, a single collection of topics can appear in multiple locations within a navigation instead of having multiple copies of a collection that could have been authored independently. That is, in the same way that a <topicref> preserves the identity of the referenced topic during reuse and a <navref> preserves the identify of a referenced map during reuse, a <topicsetref> preserves the identity of a <topicset>.

Here is an example of a <topicsetref> that imports a <topicset> navigation fragment:

<topicset id="sqlbasics" href="sqlOverview.dita">
   <topicref href="sqlSelection.dita"/>
  <topicref href="sqlJoin.dita"/>
  <topicref href="sqlFilter.dita"/>
  ...
</topicset>
...
<topichead navtitle="Mastering JDBC">
  <topicsetref href="#sqlbasics"/>
  <topicref href="jdbcPrepare.dita"/>
  ...
</topichead>
<anchorref>
Copies the contained navigation onto an <anchor> element by defaulting the format attribute to the "ditamap" value, the type attribute to the "anchor" value, and the chunk attribute to the "to-navigation" value. The referenced <anchor> can be defined in the current map or another map. The copied child elements can be suppressed in the current context by setting the toc attribute on the child elements to "yes" and on the <anchorref> element to "no".

This element expresses an intent similar to the existing anchorref attribute of the <map> element but instead of attaching an entire map, this element attaches the contents of the <anchorref> element to the referenced anchor. The value is in providing flexibility and convenience for defining source collections independently of output collections.

Here is an example of an <anchorref> that pushes a list of topics to an anchor:

<topicref href="carPrep.dita">
  <anchor id="prepDetail"/>
  ...
</topicref>
...
<anchorref href="#prepDetail">
  <topicref href="astroChecklist.dita"/>
  ...
</anchorref>

New or Changed Specification Language

This proposal requires the following changes and updates to the DITA specification and declarations:

Costs

Benefits