Feel free to suggest some other wording
that you think works better.
Why couldn’t a processor do real
generalization here? They don’t have to, but they could, couldn’t
they? As long as the result is valid DITA markup as validated against the
referencing map’s DTD or schema, the aggregated result should be fine.
And that might even include a modified class attribute. I guess there is always
the chance that none of the generalized results will be valid and in that case
you fall back to the referencing element, so that is a little different than
typical generalization, but regular generalization would be a subset.
-Jeff
From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Wednesday, June 24, 2009
3:01 PM
To: Ogden, Jeff
Cc: dita
Subject: RE: [dita] topicref to
map - draft of recommended behavior
The class of an element is confusing with the class
attribute, but that's not a bad thing - in fact the class of an element is
determined by its class attribute, even more than its element type. I was
suggesting we use element class vs element class semantics... but this whole
thing is getting trickier by the minute. I'm going to sleep on it.
re
generalization - if we want to use the word, we get to qualify the heck out of
it. Because we don't mean with preservation of class attributes, and we don't
mean to any valid ancestor, and we don't mean with selective generalization of
any mismatched domains. We don't mean generalization in the sense that it is
used when conreffing between document types, where one is the specialization of
the other. We just mean "don't know what to do with this, so going to make
it topicrefs - you've been warned. This may or may not be valid, but at least
it's expected".
Michael
Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
I think context is what was used in 12055, but
I’d be happy with using something else if we can figure out a good term.
Class would seem to conflict with the existing class attribute in much the same
way as type conflicts with @type. But having said this I’m not
feeling very creative and can’t come up with other terms that I like.
Perhaps we can reword to avoid the issue. Or perhaps we need to use
a short phrase rather than a single word term? Some possibilities:
Element type
Type of element
Element class
I don’t agree with the comment about not knowing enough
about the referencing element’s content model to be able to generalize.
We may know enough and we aren’t requiring generalization, just allowing
the possibility.
So here is a reworded version:
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 (part, chapter, topicref, …) typically determines the DITA type context of the elements
being pulled in to be included should be preserved 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 element type 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 element type information 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.
-Jeff
From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Tuesday, June 23, 2009 9:16 PM
To: Ogden, Jeff
Cc: dita
Subject: RE: [dita] topicref to map - draft of recommended behavior
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