dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [dita] topicref to map - draft of recommended behavior
- From: Michael Priestley <mpriestl@ca.ibm.com>
- To: "Ogden, Jeff" <jogden@ptc.com>
- Date: Tue, 23 Jun 2009 21:16:24 -0400
Some wording quibbles:
- context vs type vs semantic - I can
understand not using type, but context for me is too broad - context could
just mean the surroundings of the element, its attributes etc. The main
need is to distinguish when we mean element type/class vs other way of
preserving semantics - how about using the word class when we mean element
type, and semantics for the general case?
- generalization: don't want to use
the word generalization here because that has really specific meaning which
we're not implying (we don't know enough about the referencing element's
content model to usefully generalize to any particular ancestor)
Michael Priestley, Senior Technical
Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
"Ogden, Jeff"
<jogden@ptc.com>
06/23/2009 02:14 PM
|
To
| Michael Priestley/Toronto/IBM@IBMCA,
"dita" <dita@lists.oasis-open.org>
|
cc
|
|
Subject
| RE: [dita] topicref to map - draft of
recommended behavior |
|
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]