OASIS Darwin Information Typing Architecture (DITA) TC

  • 1.  processing-role: open items

    Posted 05-18-2009 13:27 
    Last week we agreed that processing-role will default to "resource-only" on
the


  • 2.  RE: [dita] processing-role: open items

    Posted 05-19-2009 13:45 
    Hi Robert,

Thanks for summarizing the open issues and helping us move this forward.

I'd like to understand the possible use cases of #4 more clearly. I'm
wondering whether the example here should be considered an error
condition processors should generate an error on. If the parent is only
a resource, what's the logic in permitting normal topics inside it? If
the TC feels the stated behavior is good, then I'm fine with that too.
I'm just asking the TC to think through some use cases where this may
apply, and what the "correct" behavior logically would be in such use
cases.

While we're considering use cases, perhaps one or more for #5 would be
helpful for our discussions too.

Does anyone have practical use cases for these scenarios they'd like us
to consider while discussing these?

Gershon


    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 3.  RE: [dita] processing-role: open items

    Posted 05-19-2009 13:54 
    Robert,

Thanks for this summary.

I believe we'll have agreement on most of what you say here,
but there are some subtleties that still need to be discussed,
and unfortunately I have to miss today's TC telcon, so I'd
ask that the TC make no final decision on this topic just yet.

We (Jeff, Dave, and I) plan to send email in response to further
the discussion as soon as we can.

paul 

> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 4.  RE: [dita] processing-role: open items

    Posted 05-19-2009 14:29 
    










    


    Robert,
    


     
    


    As Paul said in his note,
what you proposed looks pretty good to us.  Here are a few comments,
questions, or requests for clarification.
    


     
    


    Just to confirm: @processing-role
doesn't have a default value specified in the DTD or schema for most elements,
but when there is a DTD or schema default, that is the value that applies
unless a value is explicitly given on the element.  And when there is no explicit
value, no default value in the DTD or schema, and no value that cascades from
ancestors, then the processor supplied default for @processing-role is
"normal".
    


     
    


    OK, so far?
    


     
    


    You proposed:
    


     
    


    2) A related question was, would it
cascade from <keydef> as well? I think this one is clearer - we've
established elsewhere that a defaulted attribute cascades the same as an
explicit attribute. That is, the attributes are all normalized based on the
priority defined elsewhere (explicit attributes, defaulted attributes,
controlled values file, etc). Once they are normalized, any attribute that
cascades does so regardless of where it came from.
    


     
    


    This seems fine, but we
just want to clarify that @processing-role cascades within a map, but does not
cascade from map to map.  Is that your understanding?
    


     
    


    Dave and I share the
concern that Gershon expressed in his note.  I wonder if one way to handle
this is to go forward with what you proposed, but add something along these
lines:
    


     
    


    Processors
MAY, but are not required to, produce a warning when the effective value for
@processing-role conflicts with or will override explicit settings for @toc,
@print, @search, or @linking on a particular element.
    


     
    


      -Jeff
    


     
    


    > 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 5.  RE: [dita] processing-role: open items

    Posted 05-26-2009 15:28 

    Hi Jeff,

    >This seems fine, but we just
want to clarify that @processing-role cascades within a map, but does not
cascade from map to map.  Is that your understanding?

    I think processing-role should be able
to cascade map-to-map, as should print, toc, etc. Otherwise someone reusing
a map can't change its processing role without editing it.

    Example: someone's defined a TOC map
with key definitions. Someone else wants to use the key definitions to
resolve references, but doesn't want to get the TOC, linking etc. They
should be able to set processing-role=resourceonly on the mapref to get
this result.

    This is also parallel to existing support
for toc, print, etc. as noted by Robert:
    > > 1) Does the attribute cascade
to nested topicrefs or through
    > > references to
    > > other maps? My thought is
yes -- all of the related
    > > attributes that authors
    > > would view as processing
attributes already do so (print, toc).

    So I think map-to-map cascade for processing-role
is not only useful, but also consistent with other behaviors, and would
be surprising if absent.

    Michael Priestley, Senior Technical
Staff Member (STSM)
    
Lead IBM DITA Architect
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25


    

    

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

    05/19/2009 10:17 AM

    		

    

    


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

    


    cc
    
    		"Grosso, Paul" <pgrosso@ptc.com>,
"Helfinstine, David" <dhelfinstine@ptc.com>

    


    Subject
    
    		RE: [dita] processing-role: open items

    

    

    






    Robert,
     
    As Paul said in his note, what
you proposed looks pretty good to us.  Here are a few comments, questions,
or requests for clarification.
     
    Just to confirm: @processing-role
doesn't have a default value specified in the DTD or schema for most elements,
but when there is a DTD or schema default, that is the value that applies
unless a value is explicitly given on the element.  And when there
is no explicit value, no default value in the DTD or schema, and no value
that cascades from ancestors, then the processor supplied default for @processing-role
is "normal".
     
    OK, so far?
     
    You proposed:
     
    2) A related question was, would it cascade
from <keydef> as well? I think this one is clearer - we've established
elsewhere that a defaulted attribute cascades the same as an explicit attribute.
That is, the attributes are all normalized based on the priority defined
elsewhere (explicit attributes, defaulted attributes, controlled values
file, etc). Once they are normalized, any attribute that cascades does
so regardless of where it came from.
     
    This seems fine, but we just want
to clarify that @processing-role cascades within a map, but does not cascade
from map to map.  Is that your understanding?
     
    Dave and I share the concern that
Gershon expressed in his note.  I wonder if one way to handle this
is to go forward with what you proposed, but add something along these
lines:
     
    Processors MAY, but are not required
to, produce a warning when the effective value for @processing-role conflicts
with or will override explicit settings for @toc, @print, @search, or @linking
on a particular element.
     
      -Jeff
     
    > 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message
                                                
    
                                                
    > From: Grosso, Paul [mailto:pgrosso@ptc.com]
    > Sent: Tuesday, May 19, 2009 9:51
AM
    > To: Robert D Anderson; dita
    > Subject: RE: [dita] processing-role:
open items
    > 
    > Robert,
    > 
    > Thanks for this summary.
    > 
    > I believe we'll have agreement
on most of what you say here,
    > but there are some subtleties
that still need to be discussed,
    > and unfortunately I have to miss
today's TC telcon, so I'd
    > ask that the TC make no final
decision on this topic just yet.
    > 
    > We (Jeff, Dave, and I) plan to
send email in response to further
    > the discussion as soon as we can.
    > 
    > paul
    > 
    > > 
    Original Message-----
    > > From: Robert D Anderson [mailto:robander@us.ibm.com]
    > > Sent: Monday, 2009 May 18
8:27
    > > To: dita
    > > Subject: [dita] processing-role:
open items
    > >
    > >
    > > Last week we agreed that
processing-role will default to
    > > "resource-only"
on
    > > the <keydef> element.
From what I can tell in scanning the
    > > email archives,
    > > the open items are:
    > >
    > > 1) Does the attribute cascade
to nested topicrefs or through
    > > references to
    > > other maps? My thought is
yes -- all of the related
    > > attributes that authors
    > > would view as processing
attributes already do so (print, toc).
    > >
    > > 2) A related question was,
would it cascade from <keydef> as
    > > well? I think
    > > this one is clearer - we've
established elsewhere that a defaulted
    > > attribute cascades the same
as an explicit attribute. That is, the
    > > attributes are all normalized
based on the priority defined elsewhere
    > > (explicit attributes, defaulted
attributes, controlled values
    > > file, etc).
    > > Once they are normalized,
any attribute that cascades does so
    > > regardless of
    > > where it came from.
    > >
    > > 3) Exactly what attributes
will processing-role interact with? When
    > > processing-role=normal, there
is no change from today. When
    > > processing-role="resource-only",
the topic will not be included in any
    > > rendered form of the map;
so, we've established that toc is
    > > forced to "no",
    > > print is forced to "no".
Jeff also mentioned that linking and
    > > search come
    > > to mind; I'd agree that linking
is forced to "none" for that
    > > topic, and
    > > search is forced to "no".
    > >
    > > 4) The processing-role attribute
forces other attributes to
    > > take values
    > > such as toc="no".
Does toc then become an explicit attribute
    > > that cascades
    > > to other values? My thought
is no, mostly based on my guess
    > > at what would
    > > astonish people the least.
I think users would be startled to
    > > have child
    > > removed from the toc in the
following example:
    > > <topicref href="parent"
processing-role="resource-only">
    > >   <topicref href="child"
processing-role="normal"/>
    > > </topicref>
    > >
    > > 5) What does it mean to say
processing-role="resource-only"
    > > print="yes"? My
    > > thought is that @print is
ignored on that element, but that
    > > both values
    > > cascade, such that print
may become useful further down. I
    > > find the use
    > > case for this somewhat hard
to imagine, but in this contrived
    > > example it
    > > would ensure that the child
is printed:
    > > <topicref href="grandparent"
print="no">
    > >   <topicref href="parent"
processing-role="resource-only" print="yes">
    > >     <topicref
href="child" processing-role="normal"/>
    > >   </topicref>
    > > </topicref>
    > >
    > > Of course, the TC's answer
to #4 could invalidate my
    > > suggestion for #5.
    > >
    > > Thanks -
    > >
    > > Robert D Anderson
    > > IBM Authoring Tools Development
    > > Chief Architect, DITA Open
Toolkit
    > >
    > >
    > > ---------------------------------------------------------------------
    > > To unsubscribe from this
mail list, you must leave the OASIS TC that
    > > generates this mail.  Follow
this link to all your TCs in OASIS at:
    > > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr
    > oups.php
    > >
    > >
    > 
    > ---------------------------------------------------------------------
    > To unsubscribe from this mail
list, you must leave the OASIS TC that
    > generates this mail.  Follow
this link to all your TCs in OASIS at:
    > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
     


  • 6.  RE: [dita] processing-role: open items

    Posted 05-27-2009 19:19 
    










    


    Among other things Michael wrote: 
    


    I think processing-role
should be able to cascade map-to-map, as should print, toc, etc. Otherwise
someone reusing a map can't change its processing role without editing it.
    


     
    


    I guess it depends on if we want
@processing-role to behave like @toc, @print, and similar attributes or like
@scope and @format.
    


     
    


    Allowing @processing-role to cascade from
map to map the same way that @print, @toc, and other similar attributes cascade
would be OK. It  means that
@processing-role would cascade within a map, and from a topicref in a
referencing map to the map element or the top element in a referenced branch,
and from there it would cascade within the referenced map or branch. In the
referenced map, it would override any @processing-role value on the map element
or parent topicref of a branch within the map. It would not override any other
explicit @processing-role values specified in the referenced map or default
values for @processing-role specified in a DTD or XML Schema. 
    


     
    


    Since @processing-role has a default value
of “resource-only” for the keydef element, that value will never be
overridden by cascading values within the referenced map or from a referencing
map. And if a keydef element is used to reference a map, then
@processing-role=”resource-only” will always cascade from the
referencing map to the referenced map or branch unless
@processing-role=”normal” is explicitly specified on the keydef in
the referencing map.
    


     
    


    Have I got this right?
    


     
    


    Do we want @processing-role to work like
@toc, @print, and other similar attributes or like @scope and @format? 
    


     
    


    I’m fine with it either way.
Robert’s note called for the @toc, @print, … behavior, and Michael
wants map to map cascading. Also the @toc, @print, … cascading behavior
is probably better because @processing-role, @toc, @print all exist on the map
element unlike @scope and @format which do not. So unless someone feels
strongly about this in the other direction, we should probably go with the
@print, @toc, … behavior.
    


     
    


       -Jeff
    


     
    


     
    


    


    


    


    


    


    From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]
    
Sent: Tuesday, May 26, 2009 11:28
AM
    
To: Ogden, Jeff
    
Cc: Helfinstine, David; dita;
Grosso, Paul
    
Subject: RE: [dita]
processing-role: open items
    


    


     
    



    
    Hi Jeff,

    
>This seems fine, but we just want to clarify that
@processing-role cascades within a map, but does not cascade from map to map.
 Is that your understanding?

    
I
think processing-role should be able to cascade map-to-map, as should print,
toc, etc. Otherwise someone reusing a map can't change its processing role
without editing it.

    
Example:
someone's defined a TOC map with key definitions. Someone else wants to use the
key definitions to resolve references, but doesn't want to get the TOC, linking
etc. They should be able to set processing-role=resourceonly on the mapref to
get this result.

    
This
is also parallel to existing support for toc, print, etc. as noted by Robert:
    
>
> 1) Does the attribute cascade to nested topicrefs or through
    
>
> references to
    
>
> other maps? My thought is yes -- all of the related
    
>
> attributes that authors
    
>
> would view as processing attributes already do so (print, toc).

    
So
I think map-to-map cascade for processing-role is not only useful, but also
consistent with other behaviors, and would be surprising if absent.

    
Michael
Priestley, Senior Technical Staff Member (STSM)
    
Lead IBM DITA Architect
    
mpriestl@ca.ibm.com
    
http://dita.xml.org/blog/25

    

    


    
 
    
  
  
    "Ogden, Jeff"
  <jogden@ptc.com> 
    
  
    05/19/2009 10:17 AM 
    
      		
  
  
    
   
    
    
    
    To
    
        		
    
    
    "dita"
    <dita@lists.oasis-open.org> 
    
        		
   
    
   
    
    
    
    cc
    
        		
    
    
    "Grosso, Paul"
    <pgrosso@ptc.com>, "Helfinstine, David"
    <dhelfinstine@ptc.com> 
    
        		
   
    
   
    
    
    
    Subject
    
        		
    
    
    RE: [dita] processing-role: open items
    
        		
   
    
  
    
  
     
    
  
    
   
    
    
    
     
    
        		
    
    
     
    
        		
   
    
  
    
  
    
  
    		
 
    

    





    
    Robert,
    
 
    
As Paul said in his note, what you proposed looks pretty good
to us.  Here are a few comments, questions, or requests for clarification.
    
 
    
Just to confirm: @processing-role doesn't have a default
value specified in the DTD or schema for most elements, but when there is a DTD
or schema default, that is the value that applies unless a value is explicitly
given on the element.  And when there is no explicit value, no default
value in the DTD or schema, and no value that cascades from ancestors, then the
processor supplied default for @processing-role is "normal".
    
 
    
OK, so far?
    
 
    
You proposed:
    
 
    
2) A
related question was, would it cascade from <keydef> as well? I think
this one is clearer - we've established elsewhere that a defaulted attribute
cascades the same as an explicit attribute. That is, the attributes are all
normalized based on the priority defined elsewhere (explicit attributes,
defaulted attributes, controlled values file, etc). Once they are normalized,
any attribute that cascades does so regardless of where it came from.
    
 
    
This seems fine, but we just want to clarify that
@processing-role cascades within a map, but does not cascade from map to map.
 Is that your understanding?
    
 
    
Dave and I share the concern that Gershon expressed in his
note.  I wonder if one way to handle this is to go forward with what you
proposed, but add something along these lines:
    
 
    
Processors MAY, but are not required to, produce a warning
when the effective value for @processing-role conflicts with or will override
explicit settings for @toc, @print, @search, or @linking on a particular
element.
    
 
    
  -Jeff
    
 
    
>

    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message
                                                
    
                                                
    
>
From: Grosso, Paul [mailto:pgrosso@ptc.com]
    
>
Sent: Tuesday, May 19, 2009 9:51 AM
    
>
To: Robert D Anderson; dita
    
>
Subject: RE: [dita] processing-role: open items
    
>

    
>
Robert,
    
>

    
>
Thanks for this summary.
    
>

    
>
I believe we'll have agreement on most of what you say here,
    
>
but there are some subtleties that still need to be discussed,
    
>
and unfortunately I have to miss today's TC telcon, so I'd
    
>
ask that the TC make no final decision on this topic just yet.
    
>

    
>
We (Jeff, Dave, and I) plan to send email in response to further
    
>
the discussion as soon as we can.
    
>

    
>
paul
    
>

    
>
> 
    Original Message-----
    
>
> From: Robert D Anderson [mailto:robander@us.ibm.com]
    
>
> Sent: Monday, 2009 May 18 8:27
    
>
> To: dita
    
>
> Subject: [dita] processing-role: open items
    
>
>
    
>
>
    
>
> Last week we agreed that processing-role will default to
    
>
> "resource-only" on
    
>
> the <keydef> element. From what I can tell in scanning the
    
>
> email archives,
    
>
> the open items are:
    
>
>
    
>
> 1) Does the attribute cascade to nested topicrefs or through
    
>
> references to
    
>
> other maps? My thought is yes -- all of the related
    
>
> attributes that authors
    
>
> would view as processing attributes already do so (print, toc).
    
>
>
    
>
> 2) A related question was, would it cascade from <keydef> as
    
>
> well? I think
    
>
> this one is clearer - we've established elsewhere that a defaulted
    
>
> attribute cascades the same as an explicit attribute. That is, the
    
>
> attributes are all normalized based on the priority defined elsewhere
    
>
> (explicit attributes, defaulted attributes, controlled values
    
>
> file, etc).
    
>
> Once they are normalized, any attribute that cascades does so
    
>
> regardless of
    
>
> where it came from.
    
>
>
    
>
> 3) Exactly what attributes will processing-role interact with? When
    
>
> processing-role=normal, there is no change from today. When
    
>
> processing-role="resource-only", the topic will not be included
in any
    
>
> rendered form of the map; so, we've established that toc is
    
>
> forced to "no",
    
>
> print is forced to "no". Jeff also mentioned that linking and
    
>
> search come
    
>
> to mind; I'd agree that linking is forced to "none" for that
    
>
> topic, and
    
>
> search is forced to "no".
    
>
>
    
>
> 4) The processing-role attribute forces other attributes to
    
>
> take values
    
>
> such as toc="no". Does toc then become an explicit attribute
    
>
> that cascades
    
>
> to other values? My thought is no, mostly based on my guess
    
>
> at what would
    
>
> astonish people the least. I think users would be startled to
    
>
> have child
    
>
> removed from the toc in the following example:
    
>
> <topicref href="parent"
processing-role="resource-only">
    
>
>   <topicref href="child"
processing-role="normal"/>
    
>
> </topicref>
    
>
>
    
>
> 5) What does it mean to say processing-role="resource-only"
    
>
> print="yes"? My
    
>
> thought is that @print is ignored on that element, but that
    
>
> both values
    
>
> cascade, such that print may become useful further down. I
    
>
> find the use
    
>
> case for this somewhat hard to imagine, but in this contrived
    
>
> example it
    
>
> would ensure that the child is printed:
    
>
> <topicref href="grandparent" print="no">
    
>
>   <topicref href="parent"
processing-role="resource-only" print="yes">
    
>
>     <topicref href="child"
processing-role="normal"/>
    
>
>   </topicref>
    
>
> </topicref>
    
>
>
    
>
> Of course, the TC's answer to #4 could invalidate my
    
>
> suggestion for #5.
    
>
>
    
>
> Thanks -
    
>
>
    
>
> Robert D Anderson
    
>
> IBM Authoring Tools Development
    
>
> Chief Architect, DITA Open Toolkit
    
>
>
    
>
>
    
>
> ---------------------------------------------------------------------
    
>
> To unsubscribe from this mail list, you must leave the OASIS TC that
    
>
> generates this mail.  Follow this link to all your TCs in OASIS at:
    
>
> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgr
    
>
oups.php
    
>
>
    
>
>
    
>

    
>
---------------------------------------------------------------------
    
>
To unsubscribe from this mail list, you must leave the OASIS TC that
    
>
generates this mail.  Follow this link to all your TCs in OASIS at:
    
>
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
    
 


  • 7.  RE: [dita] processing-role: open items

    Posted 05-29-2009 13:36 
    Hi Jeff - everything you've said there sounds right to me.

My reasons for coming down on map->map cascading are:
*) It directly impacts @toc, @print, @linking, and @search. All of these
cascade, so it feels right to group processing-role with those here.
*) @format='something' indicates the target is not DITA and DITA processors
can't work with it; @scope=external indicates the target is unavailable and
again DITA processors can't work with it. However, @processing-role is used
when we do in fact want to work with the (usually DITA) target. So again,
to me, it feels right to grab the map, push the value thru, and keep going.

Anyway - that's how I defend the behavior to myself.

Robert D Anderson
IBM Authoring Tools Development
Chief Architect, DITA Open Toolkit


                                                                           
             "Ogden, Jeff"


Related Content