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>