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

[Eliot Kimber <ekimber@reallysi.com>]

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" <jogden@ptc.com> wrote:

> Comments below.
> 
>  
> 
>    -Jeff
> 
>  
> 
>> -----Original Message-----
> 
>> From: Eliot Kimber [mailto:ekimber@reallysi.com]
> 
>> Sent: Friday, July 10, 2009 10:12 AM
> 
>> To: Ogden, Jeff; dita
> 
>> Subject: Re: [dita] ITEM: Meaningful Values for type= on xref and
> 
>> topicref
> 
>> 
> 
>> I'm happy with with Jeff's modifications to the language as I proposed
> it.
> 
> [JeffO:] Whew!
> 
>  
> 
>> 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?
> 
> [JeffO:] I think we mean processors MUST recognize
> 
>  
> 
>> I think the current language is a bit underspecified,
> 
> [JeffO:] I agree, but I'm not so sure that what would be specified here
> doesn't fall more into the realm of output processing behavior that we
> don't often specify.  There are a few specific exceptions, such as "fn".
> 
>  
> 
>> 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.
> 
> [JeffO:] Isn't this section more general than that and isn't @type used
> with "linking" elements other than xref? I guess sub-element references
> are limited to xref or possibly xref and non-DITA references.
> 
>> 
> 
>> 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.
> 
> [JeffO:] I didn't think that validation was required here. There is
> already language that says "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".
> 
>> 
> 
>> I think it would be better to separate these two processing aspects so
> we
> 
>> can make the conformance requirements clear.
> 
> [JeffO:] I agree.
> 
>  
> 
>> 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
> 
>> <xref>, not @type.
> 
> [JeffO:] You could move it, but I also think that the current wording
> with a few fix ups of the sort we've been talking about is fine where it
> is.
> 
>  
> 
>> Moving it there would make it clear that the
> 
>> conformance and processing requirements there are a function of the
> 
>> type referenced, not the validation of @type-defined constraints.
> 
>> 
> 
>> In the @type attribute itself, the question becomes "are conforming
> 
>> processors required to validate @type at all?"
> 
>> 
> 
>> I think the answer is "yes".
> 
> [JeffO:] I disagree because of the existing wording that says "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".
> 
>  
> 
>> But since current behavior is that the
> 
>> processing for ambiguous @type references is undefined, I think its
> 
>> reasonable to say that, for DITA 1.2, processors are not required to
> 
>> support qualified names in @type values and can either ignore them
> 
>> entirely or treat them as unqualified names.
> 
> [JeffO:] I think we need to split the question into what are processors
> REQUIRED to recognize and what are they REQUIRED to do once something is
> recognized.
> 
>  
> 
> [JeffO:] I think processors MUST recognize the unqualified names that
> are already on the list, that they SHOULD recognize the qualified names
> for the unqualified names already on the list, and that we should say
> that it is likely that processors will be REQUIRED to recognize the
> qualified names in a future version of the DITA specification.
> 
>  
> 
> [JeffO:] I don't think we should add anything new about what processors
> MUST or SHOULD do when they recognize a name beyond what was already
> included in the DITA 1.1 spec. or what is said in a previously approved
> DITA 1.2 proposal.
> 
>  
> 
> [JeffO:] And validation of @type values against referenced types should
> continue to be allowed, but not required.
> 
>> 
> 
>> Cheers,
> 
>> 
> 
>> E.
> 

----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>