DITA Proposed Feature #12047
Conveniences for map references.
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.
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
- Pulling an entire map (including both hierarchy and reltables) into a
- Pulling a navigation branch from a map for reuse in another map context
while preserving the identity of the branch.
- Pushing a fragment of a map navigation onto an anchor placeholder within
For an earlier version of this proposal, see the message http://lists.oasis-open.org/archives/dita/200703/msg00065.html.
Statement of Requirement
- Enable easy composition of maps or fragments of maps.
- A team documenting a development tool needs to include the documentation
for the class libraries bundled with the development tool. The team uses a <mapref>
to import the maps for the class libraries into the map for the development
- A curriculum developer creates a lesson about selecting rows from a database
and reuses this lesson in a course about SQL basics and in another course
about mastering JDBC. The curriculum developer authors the lesson as a <topicset>
in one course and references it with a <topicsetref> in another course.
A learner takes and masters the course about SQL basics including the lesson
on selecting rows. The LMS (Learning Management System) records the lessons
taken by the learner. Later, the learner starts the course on JDBC. The LMS
recognizes that the learner has already read the lesson on selecting rows
and alerts the learner to that fact so the learner can confidently skip the
familiar portion of the course.
- A investment company provides trends and profiles to its brokers. Each
trend or profile is authored as a <topicset> consisting of multiple topics
(a booklet of sorts). When a broker searches for information, an intelligent
search engine recognizes when the distribution of hits indicates a good match
on a <topicset> as a whole rather than individual topics. The search engine
returns the <topicset> as a whole rather intermingle topics from multiple <topicset>
- A writer has written a map to define the end-to-end procedure for preparing
a car for rental. The procedure has <anchor> elements at appropriate extension
points for model-specific tasks as part of the procedure. Another writer has
written a map to define the tasks specific to maintaining an Astro. The Astro
map uses the <anchorref> element to attach the Astro-specific tasks to
the general car rental procedure so a complete, custom definition of the procedure
for a preparing an Astro for rental can be produced.
Minor; adding four elements that set default
values of attributes.
The conveniences for map
composition consist of the following four elements:
- 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:
<topichead navtitle="Developing with standard libraries">
- 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.
- 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>.
is an example of a <topicsetref> that imports a <topicset> navigation
<topicset id="sqlbasics" href="sqlOverview.dita">
<topichead navtitle="Mastering JDBC">
- 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:
New or Changed Specification Language
requires the following changes and updates to the DITA specification and declarations:
- Declaration of these elements in the mapgroup domain module.
- Documentation of these element types in the DITA language reference
- More complete discussion of using <topicref> to do non-conref composition
of maps in the DITA reference and/or architecture specification.
- Declarations: 2 hours
- Toolkit update: none required (no new processing expectations)
- Spec updates: 1-2 days
- Removes the need for people to ask "how do I link maps together?" and
makes it obvious that one can link maps together.
- Instead of being limited to a map as the unit of reuse or referencing
for collections, adopters can create and compose multiple fine-grained collections
of content within a single map. The <anchorref>, <topicset> and <topicsetref>
elements increase the flexibility and convenience for the writer in defining
source collections independently of output collections.