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: Wed, 24 Jun 2009 17:00:04 -0400
> Why
couldn’t a processor do real generalization here? They don’t have
to, but they could, couldn’t they?
They could - but if the class
attributes are preserved, then it could break DITA processors in exactly
the same way as including literal elements could.
>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.
But generalization doesn't
guarantee this, in this context. You could be generalizing into a place
that doesn't allow the generalized element. Unless the referencing element
is the same as the target's generalized element - in which case it's the
same rule we already have, ie use the referencing element, and I don't
see the need to bring generalization into it. Except maybe for the children
of the referenced element.
>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.
How do you decide when to fall back?
The only way to determine validity would be to try it, validate, and then
rerun the process if you get an error. That's a higher bar than most DITA
publishing processes require. I'm thinking the rule is - use the referencing
element, and if there are unknown child elements, generalize those - but
with the knowledge that you may be creating something invalid, but at least
predictable and thus preventable/codeable by processors. (per the instructions
in the third para).
Here's another take on the wording for
the second para - going with element type after all, and warily using generalization
in a more limited way:
When a topicref points to a map and
either or both elements are specialized or contain specializations, the
element type of the referencing element (part, chapter, topicref, …)
should be preserved in the aggregated
result. For example, a <chapter> reference to a map implies that
the target's top-level topicrefs will act as <chapter> elements.
However, processing should also allow the preservation of the referenced
map's element types in some other form, in any DITA-valid aggregated result.
For example, a <topicref> to a bookmap could be resolved into a set
of topicrefs with outputclass="bookmap/chapter". Typically
processing should use the element types of the referencing element rather
than the types of the referenced elements because the referencing element
type is known to be valid at the referencing location. When the referenced
elements contain further unknown elements, a processor may choose to generalize
them to their base classes, discarding the specialized class values and
instead preserving the class values in some other form, for example as
outputclass values. Specialized topicrefs that can point to maps and that
that do not allow generic element children will typically require specialized
processing to produce valid aggregated results. When the aggregated result
does not need to be DITA-valid, processors are free to use other means
to preserve the referencing and referenced element type information.
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/24/2009 04:21 PM
|
To
| Michael Priestley/Toronto/IBM@IBMCA
|
cc
| "dita" <dita@lists.oasis-open.org>
|
Subject
| RE: [dita] topicref to map - draft of
recommended behavior |
|
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
"Ogden, Jeff"
<jogden@ptc.com>
06/24/2009 02:32 PM
|
To
| Michael Priestley/Toronto/IBM@IBMCA
|
cc
| "dita" <dita@lists.oasis-open.org>
|
Subject
| RE: [dita] topicref to map - draft of
recommended behavior |
|
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
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]