[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] ITEM: Meaningful Values for type= on xref and topicref
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" <jogden@ptc.com> wrote:
> 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-----
>
>> From: Eliot Kimber [mailto:ekimber@reallysi.com]
>
>> Sent: Friday, July 10, 2009 3:41 PM
>
>> To: Ogden, Jeff; dita
>
>> Subject: Re: [dita] ITEM: Meaningful Values for type= on xref and
>
>> topicref
>
>>
>
>> 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>
>
>
>
----
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>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]