This seems good. I suggest a few
minor changes below.
I’m concerned that the phrase “DITA
type” may be confused with @type, when they are different things.
I’ve softened some of the language
to make it clear that processors have more latitude when they are not creating
DITA-valid aggregates.
-Jeff
A generic topicref to a generic map may be used to
create an aggregated result, incorporating the contents of the referenced map
into the referencing map. When the topicref is to a whole map, rather than an
individual branch, then an aggregating process may achieve a DITA -valid
aggregated result by pulling the target map's top-level topicrefs into the
location of the referencing topicrefs, with any reltables moved to the end of
the referencing map to avoid having reltable elements at invalid locations.
(see
dita 1.1: http://docs.oasis-open.org/dita/v1.1/OS/langspec/common/theformatattribute.html)
When
a topicref points to a map and either or both elements are specialized or
contain specializations, the type of the referencing element typically
determines the DITA type
context of the
elements being pulled in to be included in the aggregated result.
For example, a <chapter> reference to a map implies that the target's
top-level topicrefs will become
act as <chapter>
elements. However, it may be desirable to and processing should allow the preserve preservation of the semantics context implied by of the referenced map's elements in any
DITA-valid aggregated result. For example, a <topicref> to a bookmap
could be resolved into a set of topicrefs with outputclass="chapter".
Typically an aggregating
process would not include literal elements from unknown specializations, since
it faces the risk of including specialized elements that are not valid in the
referencing context. Typically processing should not unconditionally include
literal elements from unknown specializations in an aggregated result when the elements
are not valid in the referencing context. Instead the referencing element or a
generalized version of the referenced element may be included to create a
DITA-valid aggregated result, with the referencing and referenced context
information preserved by other means. Processors are free to use other means to
preserve the referencing and referenced contexts when they are creating an intermediate
result that is not necessarily a DITA-valid aggregate.
When
you create processing for a new specialization of topicref, be aware of the
following considerations:
-
should it be able to reference other maps?
-
should it be able to referency any type of map?
-
is it valid for the target's top-level topicrefs to be pulled into the
reference's location, becoming multiple instances of the referencing element
type? (as described in the previous paragraph)
-
is it appropriate for the children of the target element to be pulled in as
generic topicrefs, with any additional semantics preserved in some other manner
(for example, outputclass)? (as described in the previous paragraph)
If
the answer to all of these is yes, then the base-level aggregation policies
should be appropriate. Otherwise you will need to create overriding processing
to ensure the aggregated result is appropriate for your needs.
From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Tuesday, June 23, 2009 1:20
PM
To: dita
Subject: [dita] topicref to map -
draft of recommended behavior
Here's what I think we agreed on in today's call -
making it three paras, one to provide descrip of existing default behavior, one
to provide guidance for specialized processing, and finally one to provide
explicit guidance to specializers. I expect this will require more tinkering,
and hope I haven't missed any points - if I have I welcome corrections:
--------------------------------
A
generic topicref to a generic map may be used to create an aggregated result,
incorporating the contents of the referenced map into the referencing map. When
the topicref is to a whole map, rather than an individual branch, then an
aggregating process may achieve a DITA -valid aggregated result by pulling the
target map's top-level topicrefs into the location of the referencing
topicrefs, with any reltables moved to the end of the referencing map to avoid
having reltable elements at invalid locations.
(see
dita 1.1: http://docs.oasis-open.org/dita/v1.1/OS/langspec/common/theformatattribute.html
When
a topicref points to a map and either or both elements are specialized or
contain specializations, the type of the referencing element typically
determines the DITA type of the elements being pulled in. For example, a
<chapter> reference to a map implies that the target's top-level
topicrefs will become <chapter> elements. However, it may be desirable to
preserve the semantics of the referenced map's elements in any DITA-valid
aggregated result. For example, a <topicref> to a bookmap could be resolved
into a set of topicrefs with outputclass="chapter". Typically
an aggregating process would not include literal elements from unknown
specializations, since it faces the risk of including specialized elements that
are not valid in the referencing context.
When
you create processing for a new specialization of topicref, be aware of the
following considerations:
-
should it be able to reference other maps?
-
should it be able to referency any type of map?
-
is it valid for the target's top-level topicrefs to be pulled into the
reference's location, becoming multiple instances of the referencing element
type? (as described in the previous paragraph)
-
is it appropriate for the children of the target element to be pulled in as
generic topicrefs, with any additional semantics preserved in some other manner
(for example, outputclass)? (as described in the previous paragraph)
If
the answer to all of these is yes, then the base-level aggregation policies
should be appropriate. Otherwise you will need to create overriding processing
to ensure the aggregated result is appropriate for your needs.
Michael
Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25