[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] Issue 12055 Map referencing behaviors
"Ogden, Jeff"
<jogden@ptc.com>
09/12/2007 01:50 PM |
|
Hi, Map Referencers:
First, I'd like to propose some terminology because this confusion comes
up quite regularly:
Michael Priestley
<mpriestl@ca.ibm.com>
09/11/2007 04:43 PM |
|
"Ogden, Jeff"
<jogden@ptc.com>
09/11/2007 06:34 PM |
|
"Ogden, Jeff"
<jogden@ptc.com>
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
"Ogden, Jeff"
<jogden@ptc.com>
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
"Ogden, Jeff"
<jogden@ptc.com>
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
"Ogden, Jeff"
<jogden@ptc.com>
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
"Grosso, Paul"
<pgrosso@ptc.com>
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
> -----Original Message-----
> From: Robert D Anderson [mailto:robander@us.ibm.com]
> Sent: Monday, 2007 September 10 8:29
> To: dita@lists.oasis-open.org
> Subject: Re: [dita] Issue 12055 Map referencing behaviors
>
> Hi everybody,
>
> There is still no response to this one, so my plan for
> tomorrow's meeting
> is to keep to the original proposal. The specification should describe
> default behaviors for references from one map to another map,
> but allow
> that specializations may define alternate behaviors as appropriate.
> Compliant DITA processors should be expected to follow any alternate
> behaviors for OASIS approved elements, because those behaviors must
be
> described as part of the specification. However, there is no
> mechanism for
> processors to automatically determine the non-default
> behaviors for other
> specializations.
>
> I would be happy to have a way to define non-default behaviors for
map
> references. However, I am not sure how to come up with one
> that is simple
> enough to use, so it is not a part of this proposal.
>
> Thanks,
>
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> (507) 253-8787, T/L 553-8787 (Good Monday & Thursday)
>
> Robert D Anderson/Rochester/IBM@IBMUS wrote on 09/05/2007 04:28:03
PM:
>
> > In an attempt to draw out more responses on this one ...
> >
> > The issue under discussion is how to define differences in
> behaviors. To
> > make it easier, I will give a specific example.
> >
> > We have a chapter element defined in bookmap. When this
> points to a map,
> it
> > casts the referenced material in the role of a chapter, or
> a sequence of
> > chapters if there are multiple top-level elements. Attributes
and
> metadata
> > will cascade to the referenced 'chapters'.
> >
> > Within IBM we have another specialization, <topicsetref>.
> This is used to
> > point to commonly reused branches on a map. The behavior
> here differs -
> the
> > referenced material clearly is not cast into the role of a
> topicsetref.
> > Additionally, the topicsetref element defaults @type to
> 'topicset', which
> > indicates the type of the referenced target but should not
> be passed to
> the
> > targets. So, the map referencing behavior differs between
> chapter and
> > topicsetref.
> >
> > Because map is the most general DITA collection structure, it
should
> allow
> > appropriate processing based on the type of the collection
> and the type
> of
> > the collected content objects. That is, standard DITA map
> processing
> > behaviors are defaults appropriate to default DITA topics but
don't
> > preclude other processing behaviors.
> >
> > Options mentioned so far for defining this are:
> > 1) We specializers must expect to override programs to get anything
> > different from the default.
> > 2) We define overridable behaviors; programs may try to
> make it easier to
> > supply overrides to implement alternate behaviors
> > 3) Any behavior that differs from the default must be
> encoded in the DTD
> or
> > Schema (using a new, to-be-defined notation)
> > 4) OASIS approved elements that differ from the default
> must define the
> > difference in the specification. Default support for these
> differences
> > should be expected in processors, but simple support for
> differences in
> > user-created specializations is not guaranteed
> >
> > My own preference is for #1, because a) I think that
> differences from the
> > default should be expected, and b) I think defining those
> behaviors in
> the
> > DTD or Schema will be prohibitively complex. I would also
> be happy with
> #2,
> > although I do not think we can come up with a full list of
> overrides,
> just
> > like we cannot come up with a full list of specializations.
> If somebody
> can
> > suggest a DTD or Schema notation that is expandable and
> simple enough to
> > use for any case that might come up, I would readily shift
> my allegiance
> to
> > #3.
> >
> > Thanks -
> >
> >
> > Robert D Anderson
> > IBM Authoring Tools Development
> > Chief Architect, DITA Open Toolkit
> > (507) 253-8787, T/L 553-8787 (Good Monday & Thursday)
> >
> > Robert D Anderson/Rochester/IBM@IBMUS wrote on 08/30/2007
> 04:56:00 PM:
> >
> > >
> > > This is in reference to the proposal posted here:
> > >
> >
> http://www.oasis-open.org/committees/download.php/24910/IssueN
> umber12055.html
>
> >
> > >
> > > As noted at Tuesday's meeting, there has been some
> discussion off the
> > list
> > > about this item, primarily related to default behaviors.
> This proposal
> > > states that the described behaviors (such as that for cascading
> metadata)
> > > may change in a given specialization. For example, in the
general
> > topicref
> > > case and in most specializations, metadata specified within
the
> > <topicref>
> > > applies to the referenced content. This means that a
> processor could
> > treat
> > > specified metadata as if it was specified in the target
> topicref's.
> > >
> > > In some cases, the topicref element may be specialized to
provide
> meaning
> > > about the referencing context, rather than the target. In
> that case it
> > may
> > > be possible to set metadata that should not cascade to
> the targets, but
> > > should only be used to evaluate the reference itself.
> > >
> > > As I understand it, the open question is - how should
> such overrides of
> > the
> > > default behavior be defined? If they are not defined
> within the DTD or
> > > Schema, how can a tool anticipate the desired behavior?
> If they are
> > defined
> > > within the DTD or Schema, how can that be done, in a manner
that
> > > anticipates all of the overrides? If the changes are
> simply defined in
> > the
> > > element documentation, then tools will be unable to automatically
> > > understand how to treat the elements, and they will
> require overrides.
> > >
> > > Another, I believe less urgent, open question is about
> the terminology
> of
> > > cascading versus inheritance. It has been suggested that
> the behaviors
> > > described here, as well as in much of the map processing,
is more
> > properly
> > > described as cascading rather than inheriting. The
> proposal here uses
> the
> > > term "cascade". When this goes into the specification,
it
> will use the
> > same
> > > terminology as the spec, whether that ends up being
> cascade or inherit.
> > >
> > > Thanks -
> > >
> > > Robert D Anderson
> > > IBM Authoring Tools Development
> > > Chief Architect, DITA Open Toolkit
> > > (507) 253-8787, T/L 553-8787 (Good Monday & Thursday)
> > >
> >
>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]