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:
reads and resolves information from various maps,
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,
processes the “transformed” topics for
styling issues, and
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
>
