OASIS Darwin Information Typing Architecture (DITA) TC

 View Only
Back to discussions
Expand all | Collapse all

Issue 12055 Map referencing behaviors

  • 1.  Issue 12055 Map referencing behaviors

    Posted 08-30-2007 21:56 
    This is in reference to the proposal posted here:
http://www.oasis-open.org/committees/download.php/24910/IssueNumber12055.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


  • 2.  Re: [dita] Issue 12055 Map referencing behaviors

    Posted 09-05-2007 21:28 
    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,


  • 3.  Re: [dita] Issue 12055 Map referencing behaviors

    Posted 09-10-2007 13:29 
    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,


  • 4.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-10-2007 15:27 
    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


  • 5.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-10-2007 16:07 

    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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


    

    

    
"Grosso, Paul"
<pgrosso@ptc.com> 

    09/10/2007 11:27 AM

    		

    

    


    To
    
    		<dita@lists.oasis-open.org>

    


    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 6.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-10-2007 19:06 
    










    


    My own thought here is that we have three options:
    


     
    


      
 
    1. Define standard behavior that applies to all cases, no
     exceptions.
      2. 

    


     
    


      
 
    1. Say that the behavior is implementation dependent,
     possibly giving an example of a desired behavior that may be implemented.
      2. 

    


     
    


      
 
    1. Provide a standard behavior and a way to designate
     exceptions to that standard behavior.
      2. 

    


     
    


    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:mpriestl@ca.ibm.com]
    
Sent: Monday, September 10, 2007
12:06 PM
    
To: Grosso, Paul
    
Cc: dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25

    

    


    
 
    
  
  
    "Grosso, Paul"
  <pgrosso@ptc.com> 
    
  
    09/10/2007 11:27 AM 
    
      		
  
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        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)
    
> > >
    
> >
    
>


  • 7.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-10-2007 19:18 

    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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:05 PM

    		

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA,
"Grosso, Paul" <pgrosso@ptc.com>

    


    cc
    
    		<dita@lists.oasis-open.org>

    


    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:mpriestl@ca.ibm.com]

    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25
    
    

    

    

    
"Grosso, Paul"
<pgrosso@ptc.com> 

    09/10/2007 11:27 AM



    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 8.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-10-2007 19:57 
    










    


    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:mpriestl@ca.ibm.com]
    
Sent: Monday, September 10, 2007
3:17 PM
    
To: Ogden, Jeff
    
Cc: dita@lists.oasis-open.org;
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25

    

    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/10/2007 03:05 PM 
    
      		
  
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA,
    "Grosso, Paul" <pgrosso@ptc.com> 
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Grosso, Paul"
  <pgrosso@ptc.com> 
    
  
    09/10/2007 11:27 AM 
    
      		
  
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 9.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-10-2007 22:03 
    Hi Jeff,

I don't want to put words in Michael's mouth, I'll give my own take on
this.

The toolkit has several overrides for specializations, although I think
that probably covers under a third of them. Offhand, I do not remember if
any of these are done to meet definitions in the spec, although I would
rather expect not. Also, I'd agree that the spec does not define a standard
method to share processing behaviors - it just defines how the class
attribute can and should be used to handle specialized processing.

That said -- there are many cases where a user defining a specialized
element reasonably expects to be able to get processing that does not match
the default fallback. I've seen several cases where specializations are
created in order to provide standard headers, text formatting or both. The
DITA spec does not forbid this, and does not provide a way to share those
modified behaviors among implementations. That is, there is no way for me
to define a specialized table such that all processors know that the first
column should have a (locale specific) default heading, although this is
not an uncommon thing to want.

I think that the proposal I originally submitted just goes much further
than the rest of the spec in pointing out that users may want a behavior
from their specialization that does not match the element from which
they've specialized. My own feeling is that this is not something new - it
has always been the case that a behavior might change due to
specialization. I probably just gave more details about it because, at the
time of writing, I had already seen several examples of that in practice.

In terms of encoding the behaviors in the DTD or Schema - I do not think
that the behaviors are simple enough to encode. A lot of the examples I've
seen come from Erik Hennum, so perhaps he can provide use cases here, but
an attribute that lists element names seems too simple. There is more than
one possible behavior that can be overridden for a map reference, so a
simple inherit/notinherit value probably won't cover many of the use cases.
I'm going to rely on Erik to provide those more complex examples.

To summarize, I think that it is normal for a specialized element to desire
processing that differs from its ancestor. Perhaps the proposal 12055 as
submitted went overboard in anticipating behaviors, and implying that
processors had to be ready to deal with them. Would it be better to simply
define the defaults, and state that as with any specialization, these
behaviors may change, but that achieving such changes are up to
implementation specific solutions?

Thanks for the discussion -

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit
(507) 253-8787, T/L 553-8787 (Good Monday & Thursday)


                                                                           
             "Ogden, Jeff"


  • 10.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-11-2007 14:36 

    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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:57 PM

    		

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA

    


    cc
    
    		<dita@lists.oasis-open.org>, "Grosso,
Paul" <pgrosso@ptc.com>

    


    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:mpriestl@ca.ibm.com]

    
Sent:     Monday, September 10, 2007 3:17 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25
    
    

    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:05 PM



    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA,
"Grosso, Paul" <pgrosso@ptc.com>


    


    cc
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Grosso, Paul"
<pgrosso@ptc.com> 

    09/10/2007 11:27 AM


    		 


    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 11.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-11-2007 16:59 
    











    


    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. 
 
    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. 
 
    3. processes the “transformed” topics for
     styling issues, and
      4. 
 
    4. produces the desired final output.
      5. 

    


     
    


    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:mpriestl@ca.ibm.com]
    
Sent: Tuesday, September 11, 2007
10:36 AM
    
To: Ogden, Jeff
    
Cc: dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25

    

    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/10/2007 03:57 PM 
    
      		
  
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA
    
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org>, "Grosso, Paul" <pgrosso@ptc.com> 
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 3:17 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/10/2007 03:05 PM 
    
      		
  
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA, "Grosso, Paul" <pgrosso@ptc.com> 
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Grosso, Paul"
  <pgrosso@ptc.com> 
    
  
    09/10/2007 11:27 AM 
    
      		
  
  
      
    
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 12.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-11-2007 17:29 

    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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/11/2007 12:58 PM

    		

    

    


    To
    
    		<dita@lists.oasis-open.org>

    


    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:mpriestl@ca.ibm.com]

    
Sent:     Tuesday, September 11, 2007 10:36 AM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25
    
    

    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:57 PM



    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA


    


    cc
    
    		<dita@lists.oasis-open.org>, "Grosso,
Paul" <pgrosso@ptc.com>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 3:17 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:05 PM


    		 


    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA,
"Grosso, Paul" <pgrosso@ptc.com>


    


    cc
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Grosso, Paul"
<pgrosso@ptc.com> 

    09/10/2007 11:27 AM


    		  

     


    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 13.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-11-2007 18:56 
    











    


    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:mpriestl@ca.ibm.com]
    
Sent: Tuesday, September 11, 2007
1:29 PM
    
To: Ogden, Jeff
    
Cc: dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25

    

    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/11/2007 12:58 PM 
    
      		
  
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Tuesday, September 11, 2007 10:36 AM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/10/2007 03:57 PM 
    
      		
  
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA
    
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org>, "Grosso, Paul" <pgrosso@ptc.com> 
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 3:17 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/10/2007 03:05 PM 
    
      		
  
  
      
    
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA, "Grosso, Paul" <pgrosso@ptc.com> 
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Grosso, Paul"
  <pgrosso@ptc.com> 
    
  
    09/10/2007 11:27 AM 
    
      		
  
  
      
    
  
      
    
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 14.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-11-2007 19:03 

    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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/11/2007 02:56 PM

    		

    

    


    To
    
    		<dita@lists.oasis-open.org>

    


    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:mpriestl@ca.ibm.com]

    
Sent:     Tuesday, September 11, 2007 1:29 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25
    
    

    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/11/2007 12:58 PM



    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Tuesday, September 11, 2007 10:36 AM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:57 PM


    		 


    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA


    


    cc
    
    		<dita@lists.oasis-open.org>, "Grosso,
Paul" <pgrosso@ptc.com>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 3:17 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:05 PM


    		  

     


    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA,
"Grosso, Paul" <pgrosso@ptc.com>


    


    cc
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Grosso, Paul"
<pgrosso@ptc.com> 

    09/10/2007 11:27 AM


    		  

      

     


    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 15.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-11-2007 22:34 
    











    


    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:mpriestl@ca.ibm.com]
    
Sent: Tuesday, September 11, 2007
3:02 PM
    
To: Ogden, Jeff
    
Cc: dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25

    

    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/11/2007 02:56 PM 
    
      		
  
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Tuesday, September 11, 2007 1:29 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Ogden, Jeff" <jogden@ptc.com> 
    
  
    09/11/2007 12:58 PM 
    
      		
  
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Tuesday, September 11, 2007 10:36 AM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/10/2007 03:57 PM 
    
      		
  
  
      
    
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA
    
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org>, "Grosso, Paul" <pgrosso@ptc.com> 
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 3:17 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/10/2007 03:05 PM 
    
      		
  
  
      
    
  
      
    
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA, "Grosso, Paul" <pgrosso@ptc.com> 
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25     
    


    
 
    
  
  
    "Grosso, Paul"
  <pgrosso@ptc.com> 
    
  
    09/10/2007 11:27 AM 
    
      		
  
  
      
    
  
      
    
  
      
    
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org>
    
    
        		
   
    
   
    
    
    
    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 16.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-11-2007 23:45 

    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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/11/2007 06:34 PM

    		

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA

    


    cc
    
    		<dita@lists.oasis-open.org>

    


    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:mpriestl@ca.ibm.com]

    
Sent:     Tuesday, September 11, 2007 3:02 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25
    
    

    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/11/2007 02:56 PM



    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Tuesday, September 11, 2007 1:29 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/11/2007 12:58 PM


    		 


    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Tuesday, September 11, 2007 10:36 AM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:57 PM


    		  

     


    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA


    


    cc
    
    		<dita@lists.oasis-open.org>, "Grosso,
Paul" <pgrosso@ptc.com>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 3:17 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:05 PM


    		  

      

     


    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA,
"Grosso, Paul" <pgrosso@ptc.com>


    


    cc
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com] 
    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25    


    

    

    
"Grosso, Paul"
<pgrosso@ptc.com> 

    09/10/2007 11:27 AM


    		  

      

      

     


    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 17.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-12-2007 14:59
      |   view attached



  • 18.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-12-2007 17:51 
    











    


    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:ehennum@us.ibm.com]
    
Sent: Wednesday, September 12,
2007 11:00 AM
    
To: Michael Priestley
    
Cc: dita@lists.oasis-open.org;
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
    
ehennum@us.ibm.com


    
PS. By the way, credit in passing to my colleague, Darel Benysh, for the
templating approach.


    
Michael Priestley <mpriestl@ca.ibm.com>

    

    


    
 
    
  
  
    Michael
  Priestley <mpriestl@ca.ibm.com> 
    
  
    09/11/2007 04:43 PM
    
      		
  
  
    
   
    
    
    
    
    
    To
    
        		
    
    

    "Ogden,
    Jeff" <jogden@ptc.com>
    
        		
   
    
   
    
    
    
    
    
    cc
    
        		
    
    

    dita@lists.oasis-open.org
    
        		
   
    
   
    
    
    
    
    
    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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25 
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/11/2007
  06:34 PM 
    
      		
  
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA 
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org> 
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com]

    
Sent:     Tuesday, September 11, 2007 3:02 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25 
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/11/2007
  02:56 PM 
    
      		
  
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org> 
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com]

    
Sent:     Tuesday, September 11, 2007 1:29 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25 
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/11/2007
  12:58 PM 
    
      		
  
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org> 
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com]

    
Sent:     Tuesday, September 11, 2007 10:36 AM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25 
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/10/2007
  03:57 PM 
    
      		
  
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA 
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org>, "Grosso, Paul" <pgrosso@ptc.com> 
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com]

    
Sent:     Monday, September 10, 2007 3:17 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25 
    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    09/10/2007
  03:05 PM 
    
      		
  
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    Michael Priestley/Toronto/IBM@IBMCA, "Grosso, Paul" <pgrosso@ptc.com> 
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    <dita@lists.oasis-open.org> 
    
        		
   
    
   
    
    
    
    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:mpriestl@ca.ibm.com]

    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25 
    


    
 
    
  
  
    "Grosso, Paul"
  <pgrosso@ptc.com> 
    
  
    09/10/2007
  11:27 AM 
    
      		
  
  
     
    
  
    
   
    
    
    
    To
    
        		
    
    
    <dita@lists.oasis-open.org> 
    
        		
   
    
   
    
    
    
    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 19.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-12-2007 19:05 

    >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 is the crux of the matter. I don't
think Robert or I realized we were having that conversation until just
now :-)

    I don't think Robert's proposal calls
out this case one way or the other. It seems reasonable to me that a specializer
might decide to create some map-level metadata that shouldn't cascade normally,
and they should be able to create an override that hides it from the cascade.
But if they share the content with someone who doesn't have their specialization
or specialization override, the content will cascade according to the default
behavior.

    I'd be inclined to say that there's
nothing special about this case, and it should be treated the same way
as everything else - ie, specializers can override behavior for specialized
elements, including the suspension of the default cascading rules.

    I can't off-hand think of a reason someone
would want to do this, but I think the onus is on us to demonstrate why
we'd prevent them, since it's a pretty standard specialized-logic-overrides-inherited-logic
case. In other words, we have a general rule that applies here - what justifies
creating and documenting a class of exceptions to that rule, all the way
up to inventing new attributes to manage those exceptions?

    Michael Priestley
    
Lead IBM DITA Architect
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/12/2007 01:50 PM

    		

    

    


    To
    
    		"Erik Hennum" <ehennum@us.ibm.com>,
Michael Priestley/Toronto/IBM@IBMCA

    


    cc
    
    		<dita@lists.oasis-open.org>

    


    Subject
    
    		RE: [dita] Issue 12055 Map referencing
behaviors

    

    

    






    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:ehennum@us.ibm.com]

    
Sent:     Wednesday, September 12, 2007 11:00 AM
    
To:     Michael Priestley
    
Cc:     dita@lists.oasis-open.org; 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
    
ehennum@us.ibm.com


    
PS. By the way, credit in passing to my colleague, Darel Benysh, for the
templating approach.


    
    Michael
Priestley <mpriestl@ca.ibm.com>
    
    

    

    

    
Michael Priestley
<mpriestl@ca.ibm.com> 

    09/11/2007 04:43 PM


    

    

    



    To
    

    
"Ogden, Jeff" <jogden@ptc.com>    

    



    cc
    

    
dita@lists.oasis-open.org    

    



    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
    
mpriestl@ca.ibm.com
    
    http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/11/2007 06:34 PM



    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA


    


    cc
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com]

    
Sent:     Tuesday, September 11, 2007 3:02 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
    http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/11/2007 02:56 PM



    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com]

    
Sent:     Tuesday, September 11, 2007 1:29 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
    http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/11/2007 12:58 PM


    		 


    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com]

    
Sent:     Tuesday, September 11, 2007 10:36 AM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
    http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:57 PM


    		 


    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA


    


    cc
    
    		<dita@lists.oasis-open.org>,
"Grosso, Paul" <pgrosso@ptc.com>


    


    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:mpriestl@ca.ibm.com]

    
Sent:     Monday, September 10, 2007 3:17 PM
    
To:     Ogden, Jeff
    
Cc:     dita@lists.oasis-open.org; 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
    
mpriestl@ca.ibm.com
    
    http://dita.xml.org/blog/25


    

    

    
"Ogden, Jeff"
<jogden@ptc.com> 

    09/10/2007 03:05 PM


    		 


    

    

    


    To
    
    		Michael Priestley/Toronto/IBM@IBMCA,
"Grosso, Paul" <pgrosso@ptc.com>


    


    cc
    
    		<dita@lists.oasis-open.org>


    


    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:mpriestl@ca.ibm.com]

    
Sent:     Monday, September 10, 2007 12:06 PM
    
To:     Grosso, Paul
    
Cc:     dita@lists.oasis-open.org
    
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
    
mpriestl@ca.ibm.com
    
    http://dita.xml.org/blog/25


    

    

    
"Grosso, Paul"
<pgrosso@ptc.com> 

    09/10/2007 11:27 AM


    		 


    

    

    


    To
    
    		<dita@lists.oasis-open.org>


    


    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

    
> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message
                                                
    
                                                    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)
    
> > >
    
> >
    
>


  • 20.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-10-2007 18:52 
    I've lost track.  Is the business about what happens for references
nested within references in the referenced maps included in the
"original proposal".  I think we agreed that this would be
implementation dependent.

    -Jeff

> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 21.  RE: [dita] Issue 12055 Map referencing behaviors

    Posted 09-28-2007 21:54 
    













    


    After some initial discussion on the DITA TC list a smaller group of
interested folks (Michael, Robert, Erik, PaulG, and me) have been continuing
the discussion about Issue 12055, “Map referencing behaviors”, among
ourselves. It is time to bring the issue back to the entire TC, have a
discussion of the issue during next week's DITA TC call, and if everything goes
well during that discussion, schedule a vote on this issue for the following
week.
    


     
    


    Robert's proposal is available at:
    


    http://www.oasis-open.org/committees/download.php/24910/IssueNumber12055.html
    


     
    


    There has been general agreement on most of this proposal all along.
The recent discussion has been about how much flexibility specializers have to
depart from the standard behavior described in the proposal and, if there is flexibility,
how this can be communicated (in a write-up for the specialization, as XSLT or
other implementation specific code, as something encoded in the DTD or schema, …). 
The feeling now is that the question of how much flexibility a specializer has and
how that information is communicated isn’t something that is limited to
map referencing behaviors, but is in fact a much larger question that should be
taken up by the TC in a separate discussion.
    


     
    


    So we would like to suggest that issue 12055 go forward for
consideration by the TC now with the understanding that the write-up that gets
added to the DITA Architecture Specification will “tone down” the
discussion of exceptions for specializations so that it is similar to other existing
sections of the Architecture Specification that deal with this same issue.
    


     
    


    And separately we want to bring the issue of exceptions for
specializations or really what parts of the DITA Standard are mandates and what
parts are descriptions of the expected default behavior up for discussion by
the DITA TC as a whole.
    


     
    


       -Jeff Ogden
    


        PTC/Arbortext DITA Development Lead
    


     
    


    > 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message
                                                
    
                                                
    


    > From: Robert D Anderson [mailto:robander@us.ibm.com]
    


    > Sent: Wednesday, September 05, 2007 5:28 PM
    


    > To: dita@lists.oasis-open.org
    


    > Subject: Re: [dita] Issue 12055 Map referencing behaviors
    


    > 
    


    > 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/IssueNumber12055.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)
    


    > >


Related Content