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
[email protected]
http://dita.xml.org/blog/25
| "Ogden, Jeff"
<[email protected]>
09/11/2007 06:34 PM |
|
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:[email protected]]
Sent: Tuesday, September 11, 2007 3:02 PM
To: Ogden, Jeff
Cc: [email protected]
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
[email protected]
http://dita.xml.org/blog/25
| "Ogden, Jeff"
<[email protected]>
09/11/2007 02:56 PM |
|
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:[email protected]]
Sent: Tuesday, September 11, 2007 1:29 PM
To: Ogden, Jeff
Cc: [email protected]
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
[email protected]
http://dita.xml.org/blog/25
| "Ogden, Jeff"
<[email protected]>
09/11/2007 12:58 PM |
|
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:[email protected]]
Sent: Tuesday, September 11, 2007 10:36 AM
To: Ogden, Jeff
Cc: [email protected]; 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
[email protected]
http://dita.xml.org/blog/25
| "Ogden, Jeff"
<[email protected]>
09/10/2007 03:57 PM |
|
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:[email protected]]
Sent: Monday, September 10, 2007 3:17 PM
To: Ogden, Jeff
Cc: [email protected]; 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
[email protected]
http://dita.xml.org/blog/25
| "Ogden, Jeff"
<[email protected]>
09/10/2007 03:05 PM |
|
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:[email protected]]
Sent: Monday, September 10, 2007 12:06 PM
To: Grosso, Paul
Cc: [email protected]
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
[email protected]
http://dita.xml.org/blog/25
| "Grosso, Paul"
<[email protected]>
09/10/2007 11:27 AM |
|
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
>