I’m getting more rather than less
confused as we talk more about this. When we started the discussion I
thought I understood what was being proposed in Issue 12055 pretty well. Now I’m
not so sure.
In his message Eric talks about cascading properties
within a navigation hierarchy. And Issue 12055 talks about cascading contexts.
Are these the same thing or different things? I’d been thinking
that they were different things.
So for this example:
BookMap1.ditamap
chapter à Map2.ditamap
Map2.ditamap
topicref à atopic.dita
Properties are attributes and metadata.
They cascade from chapter in BookMap1 to topicref in Map2 and from topicref in
Map2 to atopic. This is all spelled out in the DITA Architecture Specification.
Other than by including or omitting properties or using the lockmeta attribute,
the authors have no real control over this cascading of properties and the
cascading works the same for all maps, topics, and specializations. Specializations
could define or supply default values for attributes that are not specified or
are different from the values specified for the base elements.
Issue 12055 talks about contexts. The
proposal is that by default the chapter context from BookMap1 cascades to and
overrides the context for the topicref in Map2. So the question is what is a
context? I’ve been assuming that this is just the fact that output
processing should treat atopic.dita as a chapter. This would be independent of the
cascading of any of the other properties associated with these elements.
Or in a sense it is as if context is a new property that can cascade
independently of attributes or metadata. Or in an even simpler way of thinking
about it, it is as if the topicref in Map2 is replaced by a chapter element
from BookMap1. So the composed result would be as if we had composed the
following bookmap:
BookMap1.ditamap
chapter à atopic.dita
Am I thinking about this correctly so far?
And the discussion we’ve been having
is if specializers should be able to call for different treatment in the
cascading of context for map to map references where for some map
specializations or for some specialized map elements the referencing context
would not cascade and override the referenced context. This would allow you
to end up as if you had composed something like this:
BookMap1.ditamap
topicref à atopic.dita
And the questions are:
1)
Are exceptions of this
sort needed? In his last message Michael didn’t seem to think so.
2)
If they are needed, how
are they implemented?
a.
Entirely as part of
output processing.
b.
As something encoded into
the DTD or schema that can be used by output processing.
-Jeff
From: Erik Hennum
[mailto:]
Sent: Wednesday, September 12,
2007 11:00 AM
To: Michael Priestley
Cc: ;
Ogden, Jeff
Subject: RE: [dita] Issue 12055
Map referencing behaviors
Hi, Map
Referencers:
First, I'd like to propose some terminology because this confusion comes up
quite regularly:
"Inherit" refers to the type hierarchy.
A specialized element inherits base processing.
"Cascade" refers to the navigation
hierarchy (or any other containment hierarchy). A property on a
<topicref> cascades to contained <topicref> elements.
One case the issue surfaces is in templating -- that is, using a map to
populate a field in a template with a list of references to topics:
The <templateref> parent is a specialized
<topicref> that refers to an HTML page that's a template with
placeholder fields for lists of topics. The parent defaults the format
attribute to "html" and the type attribute to
"template" so processes can recognize the template.
The <fieldref> children are specialized
<topicref> elements that identify the placeholder fields and default
the toc attribute to "no" so the TOC processing skips the
fields. This element certainly shouldn't pick up any cascades from higher
in the navigation hierarchy.
The grandchildren are ordinary <topicref>
elements providing the topic references for listing in the field. They
certainly shouldn't pick up the defaulted format or type attributes from
the <templateref>, and it's arguable (given that they aren't really
part of the navigation hierarchy) that they shouldn't pick up any
cascades.
To summarize, a specializer might want to
Control cascades for specified or all properties
to a node.
Control cascades for specified or all properties
through a node to contained nodes.
To support specialization, a toolkit has to allow overrides of default behaviors.
I'd suggest that control over these behaviors can quite reasonably be handled
through the standard override approach rather than trying to encode this
special case in architectural attributes.
Hoping that's useful,
Erik Hennum
PS. By the way, credit in passing to my colleague, Darel Benysh, for the
templating approach.
Michael Priestley <>
Michael
Priestley <>
09/11/2007 04:43 PM
To
"Ogden,
Jeff" <>
cc
Subject
RE: [dita] Issue
12055 Map referencing behaviors
OK, I don't see anything in Robert's original proposal that would reverse the
normal precedence of map operations, so don't see the need for the exception
attributes either.
Is this a case of mutual misinterpretation of the terms "override"
and "inheritance"? I suspect Robert was using the terms relative to
specialization hierarchies, and it sounds like you may have been interpreting
them relative to map referential inheritance (the thing I am referencing
inherits the metadata of the topicref that is referencing it).
Michael Priestley
Lead IBM DITA Architect
http://dita.xml.org/blog/25
"Ogden, Jeff"
<>
09/11/2007
06:34 PM
To
Michael Priestley/Toronto/IBM@IBMCA
cc
<>
Subject
RE: [dita] Issue 12055 Map referencing behaviors
Do your maps look something like this?
Map1
glossaryref à Map2
Map2
topicref à glossentry1
topicref à glossentry2
. . .
I’m guessing that in this case you want the glossaryref context to
override the topicref contexts in the referenced map. This is the default
behavior (referencing context overrides referenced context) and so there is no
need for an exception and thus no need for the new architectural attributes.
-Jeff
From:
Michael Priestley [mailto:]
Sent: Tuesday, September 11, 2007 3:02 PM
To: Ogden, Jeff
Cc:
Subject: RE: [dita] Issue 12055 Map referencing behaviors
OK, I still don't understand the purpose of the attributes. I'll make up a
scenario:
- I create a specialized topicref called "glossaryref" that
references a map with nothing but glossary entries in it
- I create specialized behavior for that reference that alphabetizes the
entries and adds a layer of TOC navigation by letter, but keeps the actual
entries out of the TOC
What role would your specialized attributes play in this scenario?
Michael Priestley
Lead IBM DITA Architect
http://dita.xml.org/blog/25
"Ogden, Jeff"
<>
09/11/2007
02:56 PM
To
<>
cc
Subject
RE: [dita] Issue 12055 Map referencing behaviors
Actually I’d be happy with no flexibility and no new architectural
attribute. With that approach the referencing map would always override the
referenced map. But this makes it hard for me to come up with concrete
scenario’s that require flexibility.
I think Robert has cases where specializers don’t want the referencing
map context to override the referenced map context. And he thinks Erik has some
more complicated cases where simple inherit or not options aren’t enough.
This leads to the desire to allow exceptions and to give specializers some
flexibility.
So what we might do is have Robert or Erik provide the concrete case(s).
I’d be happy to plug those cases into the output processing pipeline
implementation and architectural attributes that I described in my previous
note.
-Jeff
From:
Michael Priestley [mailto:]
Sent: Tuesday, September 11, 2007 1:29 PM
To: Ogden, Jeff
Cc:
Subject: RE: [dita] Issue 12055 Map referencing behaviors
Hi Jeff, I'd still like a concrete scenario. If you can give me an end-to-end
example of:
- someone defines a map document type for purpose x, including your attributes
with values y and z
- the values get used when the map references topic types y and z, which gives
benefits a, b, c
Right now I still don't understand what slots into those letters :-) A concrete
example will help me.
Michael Priestley
Lead IBM DITA Architect
http://dita.xml.org/blog/25
"Ogden, Jeff"
<>
09/11/2007
12:58 PM
To
<>
cc
Subject
RE: [dita] Issue 12055 Map referencing behaviors
It is true that the specializers would need to add information for a new
architectural attribute to their new DTDs or schemas if they want to override
the default behavior, but are developing new DTDs or schemas anyway so this
does not seem like a bad thing or a large burden.
If we put the new architectural attribute on individual elements rather than on
the root element (more class-like rather than domain-like), doesn’t most
of the need to manage the attributes through generalization and conref
processing go away? Typically we’d just use the default value, if any,
from the DTD or schema for the current element (generalized or not). If for
some reason the architectural attribute is stored in the document instance, if
you have access to the DTD you’d just get the new value for the
“new” element during generalization and store that in the instance,
or if you don’t have access to the DTD or schema, you could simply delete
the architectural attribute from the instance and fallback to the default
behavior.
I guess my desire to add the additional information to the DTD or schema comes
from my desire to make the map to map referencing behaviors more of a
requirement of the DITA Standard and less of an optional set of behaviors that
is left fairly open and handled by output processing. Perhaps this is a mistake
on my part, but I think of the map to map referencing behavior as being
somewhat more complicated than most styling issues (ph as bold or not) that are
handled by output processing entirely or largely outside of anything in the
DITA Standard. The map to map referencing behavior seems somewhat similar to
the portions of the DITA spec. that talk about “Metadata elements and
common attributes” in that the information in one document is interacting
with and possibly overriding information in another. For the metadata case at
least the behavior isn’t optional, but something that is required by the
DITA Standard (things in maps can override things in topics). I’ve been
thinking about the map to map referencing behavior in a similar way. And adding
a new architectural attribute allows us to give specializers some flexibility
while still saying exactly what the behavior is in the standard.
Here is an example. Imagine an output processing pipeline that:
1. reads and resolves
information from various maps,
2. gathers and
“transforms” dita topics referenced from the maps, combining and
splitting topics, adding related-links, metadata and other contextual
information including map to map referencing context to the resulting topics or
collections of topics,
3. processes the
“transformed” topics for styling issues, and
4. produces the desired final
output.
The map to map referencing behaviors would likely be implemented in steps 1 and
2 (probably mostly step 2). Styling issues would be dealt with in step 3 or
possibly step 3 and 4. Steps 3 and 4 may never see information from a map
directly. Any reasonable output processing system will make it fairly easy for
someone to customize/style their documents in step 3. It may be much more
difficult or even impossible to add specialization specific customizations to
step 2. If we can include information about map referencing behavior in the DTD
or schema in some fashion, we can provide flexibility in step 2 without
requiring specializers to implement their own specialization specific
customization in step 2. And if this flexibility is provided as part of the
standard, there would be less work for specializers to do to actually use it.
The alternative is to leave the map to map behavior up to output processing
with a suggestion in the DITA spec. that suggests how this should work by
default. I could live with this approach, but for the reasons I stated earlier
I’d rather see this be defined as a requirement. If we do leave the map
to map referencing behavior up to output processing, we should make sure our
descriptions in the DITA spec. make that clear and we should probably work to
make the map to map description shorter as Robert suggested in an earlier
message.
So far I’m still thinking that the new architectural attribute here could
be pretty simple (inherit or not), but I look forward to seeing some more cases
from Erik Hennum or others.
-Jeff
From:
Michael Priestley [mailto:]
Sent: Tuesday, September 11, 2007 10:36 AM
To: Ogden, Jeff
Cc: ; Grosso, Paul
Subject: RE: [dita] Issue 12055 Map referencing behaviors
The specialized behaviors do not override something that is required by the
DITA standard. In fact, the reverse is true: many of the current DITA standard
specializations require processors to override inherited behavior. As a simple
example, look at the highlighting domain. Bold is not the default output from a
<ph> element.
If we're doing it within the spec when we specialize, we can certainly expect
others to do it when they add their own specializations outside the spec.
Re your option 3 below: Can you give me a scenario that would actually make use
of this proposal? I'm having a hard time understanding the need in the
abstract. My initial reaction is not positive, just because it adds a new
architectural attribute that needs to be set by specializers and
managed/preserved/adjusted through generalization and conref processes - so it
will turn this relatively modest proposal into a major proposal on the same
order of magnitude as constraints (or larger, given the recent reduction of
that proposal).
Michael Priestley
Lead IBM DITA Architect
http://dita.xml.org/blog/25
"Ogden, Jeff"
<>
09/10/2007
03:57 PM
To
Michael Priestley/Toronto/IBM@IBMCA
cc
<>, "Grosso, Paul" <>
Subject
RE: [dita] Issue 12055 Map referencing behaviors
OK, but for those cases where “the DITA Open Toolkit provides specialized
behaviors for about a third of the specialized elements in the DITA spec”
do the specialized behaviors provided override something that is required in
the DITA standard or do they override the processing for the base element as
implemented by the DITA Open Toolkit?
I see the “Specialization in processing” section of the DITA
specification as a collection of good practices for writing XSLT or CSS
stylesheets for use with DITA. I don’t think it defines a standard method
of sharing processing behaviors unless the sharing is being done using the same
processing system such as the DITA Open Toolkit.
The DITA Open Toolkit, like all output processing systems, implements portions
of the DITA standard as well as other things that have not been standardized
and very often we do not want to standardize. I guess a question we may need to
answer is, Are the behaviors being defined in Issue 12055 ones that we want to
include in the DITA Standard or are they ones that we want left open for
customization? And if we include them in the DITA Standard, how much force do
we want to give them? Are they requirements? Are they recommendations? Are they
examples?
Michael, do you see any harm in providing additional information in the DTD or
schema as I have been suggesting (my option #3)?
-Jeff
From:
Michael Priestley [mailto:]
Sent: Monday, September 10, 2007 3:17 PM
To: Ogden, Jeff
Cc: ; Grosso, Paul
Subject: RE: [dita] Issue 12055 Map referencing behaviors
Re:
>The reason I am uncomfortable with this is that it requires that someone
who wants to define a new specialization that requires exceptions provide both
the specialized elements and behavior. We have a standard way to provide the
specialized elements. We do not have a standard way to provide the specialized
behavior.
Actually we do - see the architectural spec section "Specialization in
processing".
>Without a standard way to provide the specialized behavior, someone will
need to reimplement the specialized behavior for different output processing
implementations. That will be extra work and seems likely to result in
different results as documents are moved from site to site and implementation
to implementation. We should avoid that if we can.
It's within the scope of normal DITA specialization to create a new specialized
element that has specialized processing. Some of the critics of specialization
have claimed that's the norm, which it's not, but it's not the exception
either. As one example, I believe the DITA Open Toolkit provides specialized
behaviors for about a third of the specialized elements in the DITA spec. I
believe most DITA users that are specializing DITA are also providing
specialized processing for at least some of their new elements.
Michael Priestley
Lead IBM DITA Architect
http://dita.xml.org/blog/25
"Ogden, Jeff"
<>
09/10/2007
03:05 PM
To
Michael Priestley/Toronto/IBM@IBMCA, "Grosso, Paul" <>
cc
<>
Subject
RE: [dita] Issue 12055 Map referencing behaviors
My own thought here is that we have three options:
1. Define standard behavior
that applies to all cases, no exceptions.
2. Say that the behavior is
implementation dependent, possibly giving an example of a desired behavior that
may be implemented.
3. Provide a standard behavior
and a way to designate exceptions to that standard behavior.
For this particular case I don’t think #3 would be too hard and so that
would seem to be a good way to go.
I am uncomfortable with the option that is being proposed which I take as
defining standard behavior, but allowing exceptions. The reason I am
uncomfortable with this is that it requires that someone who wants to define a
new specialization that requires exceptions provide both the specialized
elements and behavior. We have a standard way to provide the specialized
elements. We do not have a standard way to provide the specialized behavior.
Without a standard way to provide the specialized behavior, someone will need
to reimplement the specialized behavior for different output processing
implementations. That will be extra work and seems likely to result in
different results as documents are moved from site to site and implementation
to implementation. We should avoid that if we can.
I could live with option #1 (no exceptions). That puts the burden on the author
to use the “right” map elements when the behavior they want
isn’t the standard behavior.
I could live with option #2 (no standard). That is what we do for most output
processing today.
And as I said, I think option #3 is the best approach. I think all we need is
either:
a) a new attribute similar to domain on
the root element of a map that accepts a space separated list of topicref
specializations whose behavior should not be overridden when they are
referenced using a different element from a higher level map, or
b) a new attribute similar to class on
topicref and topicref specializations that indicates that this element’s
behavior should not be overridden when referenced from a higher level map.
In either case, like domain or class, the new attribute would usually appear
with its default value in a DTD or schema and not in the instance.
And, if we want to, rather than using a simple list or a single attribute
value, we might define a keyword or grouping syntax for the values so that we
could use the same attributes for other similar purposes in the future should
the need arise. Some possible approaches:
Simple list on the root element: norefoverride=”element1 element2 …
elementn”
Single valued attribute on the topicref element or specialization:
refoverride=”no”
Grouping syntax on the root element:
processing_exceptions=”norefoverride(element1 element2 … elementn)
somenewoption(somenewvalues)”
Keyword list on any element: processing_exceptions=”norefoverride
somenewoption someothernewoption”
-Jeff
From:
Michael Priestley [mailto:]
Sent: Monday, September 10, 2007 12:06 PM
To: Grosso, Paul
Cc:
Subject: RE: [dita] Issue 12055 Map referencing behaviors
I think the wording needs some clarification - I don't think what you're
reacting to is actually Robert's intent.
Robert, I'm going to try to paraphrase here:
If someone specializes a map to create a new map-referencing element, they can
define specialized processing for that element if they want. Applications that
are not customized or extended to provide special handling for the specialized
element should instead treat the specialized element according to its ancestry
(ie, according to whatever behavior is provided in the spec for that element).
I don't think Robert is saying more than the above, and that's true of all
specializations. He's just pointing out that the behavior defined in the spec
can be overridden by someone providing specialized elements and behavior.
Why is it worth calling out at all then? I think because there are some
behaviors that we consider architectural (eg conref, the class attribute...)
that need to be consistent across specializations because they are designed to
provide interoperability across specializations; there are other behaviors that
are implementation-specific, in which the behaviors we provide are defaults
that can be overridden, rather than normative for the class of all possible
DITA document types. I think map-referencing behaviors fall in the latter
class, and that's what Robert is trying to say.
Robert, correct me if I'm wrong. Paul, does that re-interpretation address your
concerns?
Michael Priestley
Lead IBM DITA Architect
http://dita.xml.org/blog/25
"Grosso, Paul"
<>
09/10/2007
11:27 AM
To
<>
cc
Subject
RE: [dita] Issue 12055 Map referencing behaviors
Robert,
If I understand correctly, you are suggesting that different
specializations can do different things based only on some
writeup in the standard.
Jeff and I have said that is the one choice we find unacceptable.
Either there needs to be some machine-readable way to determine
behavior (e.g., encode it in the DTD/XSDs), or all behavior must
be consistent. Having to hardwire potentially conflictly behavior
into an implementation for each specialization is not a good option.
Jeff and I will try to discuss this some more before tomorrow's
meeting, but I wanted to respond as soon as possible.
paul
>
