OASIS Darwin Information Typing Architecture (DITA) TC

 View Only

  • 1.  RE: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-07-2009 13:44 
    We can argue if this was or wasn't a "bug" in the approved DITA 1.0 and 1.1 specifications, but it doesn't really matter since the "fix" being proposed is incompatible with what that DITA 1.0 and 1.1 called for. We shouldn't be making incompatible changes in a 1.x version and certainly not at this late stage in the DITA 1.2 cycle.  Something like this requires a full proposal, dissuasion, and a vote.

Note that this is not just an issue for implementors.  @type is something that can be set by authors.  And the proposal that is currently on the table would make existing documents that use what are perfectly valid values such as "fig" or "fn" rather than "topic/fig" or "topic/fn" invalid.  We can't do that.

We might be able to allow both the old and new values, but I think even that would be better left until DITA 1.3.

   -Jeff


  • 2.  Re: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-07-2009 15:03 
    On 7/7/09 8:43 AM, "Ogden, Jeff"


  • 3.  RE: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-07-2009 15:22 
    OK, what if a user has set @type="myfig" where myfig is a specialization
of fig? That is what the DITA 1.0 and DITA 1.1 specs call for. Doesn't
that become invalid with your proposal?

And what about specialized elements that are part of a DITA TC defined
specialization (task, concept, hazardstatement, ...), but not part of
the base topic or map definitions?  How are those different from user
defined specializations in terms of uniqueness?

    -Jeff

> 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 4.  Re: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-07-2009 17:04 
    On 7/7/09 10:20 AM, "Ogden, Jeff"


  • 5.  RE: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-07-2009 20:01 
    










    


    I
went back and looked at Eliot’s original e-mail on this and found the
note from 10:05 AM on June 30th (included below).
    


    


    If
I apply your suggested change to the draft Language Reference, I get the
following (the addition is underlined and in blue):
    


    


    If the type attribute is
specified when referencing DITA content, it should match one of the values in
the target's class attribute. For example, if type="topic", the link
could be to a generic topic, or any specialization of topic, including concept,
task, and reference. Applications may, but need not, issue a warning when the
specified or inherited type attribute value does not match the target (or a
specialization ancestor of the target). When
referencing elements within topics, the value of the type attribute should
specify the fully-qualified class value for the target element, e.g. "my-list-d/my-li-type".
For element classes defined by standard DITA vocabulary modules, the module
name and separator may be omitted (e.g. "li" rather than
"topic/li").
    


    


    And
that just doesn’t sound like it is “allowing, but not requiring qualification”
to me. 
    


    


    I’d
be OK with rewording this to read something like this (changes underlined/bold/orange and deletions in red strikethrough):
    


    


    If the type attribute is
specified when referencing a DITA
contenttopic
or map, it shouldMUST match one of the values in the target's
class attribute. For example, if type="topic", the link could be to a
generic topic, or any specialization of topic, including concept, task, and
reference. Applications may, but need not, issue a warning when the specified
or inherited type attribute value does not match the target (or a
specialization ancestor of the target). When
referencing elements within DITA topics or maps, the value of the type attribute
shouldMUST
specify the fully-qualified class value for the target element, e.g. "my-list-d/my-li-type"
or an unqualified element name from the
target’s class attribute. For
element classes defined by standard DITA vocabulary modules, the module name
and separator may be omitted (e.g. "li"
rather than "topic/li").
    


    


    If
we go down this path, I’d think we’d also need to change this from
the last paragraph in the same section:
    


    


    Processing is only required to
support the above list or specializations of types in that list. Supporting
additional types as targets may require the creation of processing overrides.
    


    


    Since
the current list consists of unqualified element names (fig, table, li, fn, …).
Do we want/need to require processors to support the qualified names for items
on this list or should we add the qualified names to the list so that
processors are required to support both?  Are we comfortable putting new
requirements on processors at this late stage of DITA 1.2?
    


    


    While
I’d be OK with the above, because we are so far along in the DITA 1.2
cycle I’d also be OK with putting this off until DITA 1.3.
    


    


      
 -Jeff
    


    


    > 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 6.  Re: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-10-2009 14:12 
    I'm happy with with Jeff's modifications to the language as I proposed it.

Jeff asks:

> Since the current list consists of unqualified element names (fig, table, li,
> fn, Š). Do we want/need to require processors to support the qualified names
> for items on this list or should we add the qualified names to the list so
> that processors are required to support both?  Are we comfortable putting new
> requirements on processors at this late stage of DITA 1.2?
  
In this context, what does "support" mean? I think the current language is a
bit underspecified, since I think that the processing referred to by the
current paragraph is about xref resolution and reflection, that is,
generating meaningful link anchors for xrefs.

However, the processing I've been focusing on for @type is simply validating
that the reference target matches the @type value. That processing is
completely orthogonal to xref or link processing.

I think it would be better to separate these two processing aspects so we
can make the conformance requirements clear. In particular, the current
statement about supporting type isn't really about @type validation but
about xref processing, and that language belongs in the defintion of


  • 7.  RE: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-10-2009 18:20 
    










    


    Comments below.
    


    


       -Jeff
    


    


    > 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 8.  Re: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-10-2009 19:41 
    I think I realize where Jeff and I weren't communicating.

When a processor handles an xref or link it has to decide if the target
element is one it knows how to process for the purpose of xref or link
rendering. There are three ways it can decide:

1. Look *only* at the @type attribute and, if the value of @type is not one
it recognizes, say "no can do".

2. Ignore @type, resolve the reference, and *then* look to see if the result
is one it can process, using some pre-defined list of known types (e.g., a
hard-code switch, registered plugins, etc.).

3. Ignore @type, resolve the reference, and pass the element along a chain
of potential handlers until one handles it or the element falls through to a
default handler, which does whatever it does (produce a default result or
throw an exception or whatever).

In case (1) validation of @type is of secondary concern since you'd only
worry about that if you first recognized the named type as one you know how
to process.  However, in cases (2) and (3), validation of @type is more
important since you've got the targets in hand and therefore have an
obligation to make sure the request and the result match (that is, the
referenced elements match the specified type) before you try to process
them, and at least issue a warning, if not refuse to do the processing at
all.

I was not considering option (1) because I would always implement option
(3). But clearly some code implements options (1) and that needs to always
be an implementation option.

So that makes it clearer to me what Jeff's concern was all along: tools that
implement option (1) would have to update their code that makes that choice
based on @type values alone. Such a tool probably has some way to configure
what @type values it recognizes, so allowing different types of values could
mean a change to UIs, configuration files, etc., in addition to changes to
the @type value recognition logic itself.

For processors that already do (2) or (3) new @type values can't be a big
deal because it's trivial to implement type checking or update existing code
to handle qualified names. In case (3), everything is done through
delegation, e.g., the way the Open Toolkit HTML XSLTs work, so no
worries--you're already matching on @class values anyway, so @type is not
relevant once the resolved target has been validated (e.g., you're just
doing apply-templates in mode "handle-xref" and whatever happens happens).

So I have more sympathy now with Jeff's concern.

However, I think the current discussion of @type needs to be reworked,
regardless of a decision we make on the values @type can take: it needs to
clearly distinguish the two types of supported target discrimination
described above (@type only or referenced elements only) and say something
about the obligation to validate @type in addition to being able to use it
to decide to process the reference or not.

Given that language change, then we can say "processors must/should provide
xref and link processing for the listed types". Because that's what the
current language under @type is really saying--but wording it as "must
recognize" reflects a particular implementation, not the true requirement.

Or said another way: if processors are required to do xref and link
processing for all the listed types, then by necessity, if they use @type to
determine processability, any of those types specified on @type will always
succeed, so no need to say anything about recognition requirements.

Background for the above conclusions:

The way I've been thinking about @type-related processing is:

1. The processor resolve a reference to a set of elements.

2. The processor examines each element in the set to see if its @class value
is consistent with the @type value (that is, the value of @type names a type
somewhere on the candidate element's @class hierarchy. This results in a
yes/no answer (type matches/type doesn't match).

3. If the type matches, processing of the referenced elements proceeds,
whatever it might be.

4. If the type doesn't match, the processor *may* issue an error or warning
message. The processor chooses whether to proceed with processing or not. If
it chooses to proceed, processing is applied, whatever it might be. This
choice could be made by examining the @type value ("oh, this is a type I
know how to do xref resolution for, I'll do it") or it could be made purely
on the result from step 2, or it could be a blanket "the type didn't match,
and I didn't recognize the type as one I know how to process, but there
might be extensions that do, so carry on". The current language as Jeff
points out allows all three of these possibilities.


Cheers,

E.


> are already on the list

On 7/10/09 1:19 PM, "Ogden, Jeff"


  • 9.  RE: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-10-2009 21:57 
    










    


    I hope the rest of the TC isn't going to want to kill
both Eliot and me.
    


    


    Eliot's analysis is interesting and pretty much right, I
think.  But it isn't what I've been worrying about in this discussion.
    


    


    My concern has been more about:
    


    ·        
not placing new requirements on existing
processors,
    


    ·        
not making existing document instances invalid,
    


    ·        
being clear about what values a processor is
REQUIRED to recognize,
    


    ·        
and therefore what values will always work for
document interchange and what values may not.
    


    


    Under some circumstances I think all processors need to
implement some form of Eliot's option #1 (Look *only* at the @type attribute)
because of this language in the DITA spec.:
    


    During output processing for
references to non-DITA objects (i.e., either scope is not “local”
or format is neither “dita” nor “ditamap”) or other
cases where the type of the referenced item cannot be determined from the item
itself, the explicit, inherited, or default value for the type attribute is
used without any validation.
    


    


    I think it is possible for a processor to implement just
option #1, but I don’t think that will be very common and most will
implement a mix of options.
    


    


    Eliot wrote:
    


    > … in cases (2) and (3), validation of @type is
more
    


    > important since you've got the targets in hand and
therefore have an
    


    > obligation to make sure the request and the result
match (that is, the
    


    > referenced elements match the specified type) before
you try to process
    


    > them, and at least issue a warning, if not refuse to
do the processing
    


    > at all.
    


    


    I don’t think there is an “obligation
to make sure that the request and the result match” because of this
wording in the DITA spec:
    


    … an implementation may
(but need not) give an error message, and may (but need not) recover from this
error condition by using the type attribute value.
    


    


    Eliot also wrote:
    


    > For processors that already do (2) or (3) new @type
values can't be a big
    


    > deal because it's trivial to implement type checking
or update existing code
    


    > to handle qualified names.
    


    


    I don’t think that Eliot or the DITA specification
is in a position to say what is or isn’t a big deal for other people’s
processors. It may be a simple code change, but it may not be an easy change to
make in a timely way due to release schedules, the availability of people
resources or other factors beyond just the code. Or it may be an easy change
for a programmer, but not an easy change for an author or other end user. 
Or it may be an easy change, but one that would need to be made to many existing
stylesheets, some of which are not under an implementer’s control.
    


    


    For our own DITA implementation here at PTC if we can or
cannot process a reference has more to do with the @format, @scope, and @href
values than it does with the @type value.  We can always provide some
basic default processing for @type values that we don’t recognize. We use
@type to modify the default processing in some cases, but hopefully never in a
way that would prevent the processing from occurring entirely. 
    


    


    What the list of values in the DITA spec. that MUST be
recognized accomplishes is to establish the common vocabulary that can be used
by authors and which will be recognized by processors. Authors are free to use
other values and a processor may or may not recognize them.  And even if a
value is recognized, there may or may not be any modification of behavior based
on the recognized value. So basically in our implementation the list of
recognized values is a bargain between content authors and stylesheet authors
that says that these are the values that can be counted upon to be recognized
if there is in fact any specific processing associated with the value. Full
stop. Nothing more.
    


    


    Or at least that is my thinking at the moment.
    


    


       -Jeff 
    


    


    > 
    
                                                
    
					
                                                    

        
                                                
				
    
                                                
    
                                                    
                                                        
                                                        Original Message


  • 10.  Re: [dita] ITEM: Meaningful Values for type= on xref and topicref

    Posted 07-10-2009 22:15 
    Re "recognition" of @type values: that can only be about whether or not the
processor can do useful processing of xrefs and links, yes? My point being
that "recognition" is a poorly-chosen way of expressing things, namely the
requirement to be able to process xrefs and links to a base set of types.

Maybe the reason my bug hasn't been an issue in practice, in addition to the
fact that use of specialization has been fairly limited before the last year
or so, is that most, if not all, processors don't in fact check the @type
value against reference targets, so the fact that there might have been an
ambiguous match was never noticed. It's also notable that one well-known
processor that *does* check @type, does so incorrectly (namely the OT before
1.5, which checked @type on topicrefs and only accepted exact matches).

So really we've forked two issues:

1. Original issue, should qualified names be allowed on @type?

2. New issue: language in definition of @type is poor at best, confusing at
worst and needs to be reworked to make the requirements clearer.

On the original issue, at this point I'm happy to allow it to slide to 1.3:
if nobody validates @type against targets, then my primary concern is moot
in practice. Processing of xrefs is either not affected by the use or
non-use of @type or processors wouldn't recognize qualified names anyway (or
at least wouldn't have to recognize them even if they were allowed).

On the language issue, I can address that through the normal review and
comment process, now that I better understand the implications of @type.

Cheers,

E.


On 7/10/09 4:55 PM, "Ogden, Jeff"


Related Content