Here is an e-mail discussion that Paul and
Robert started two weeks or so ago. I don’t know that we’ve
completely settled on the answer yet, but it seems likely that we will make a
change to item #21 in the keyref proposal (issue #1207) that the TC approved last
December. I don’t think the change is a big deal. It is all about how we
handle a fairly obscure error condition. I don’t know that this change
requires a vote by the TC since it will be included in the DITA 1.2 specification
which will eventually be voted on when the spec. is approved. But, I
wanted to let the TC know about the likely change and put something into the public
archive.
-Jeff
From: Ogden, Jeff
Sent: Tuesday, September 23, 2008
8:53 AM
To: 'Michael Priestley'
Cc: Grosso, Paul; 'Robert D
Anderson'; 'Eliot Kimber'
Subject: RE: DITA 1.2 reviews of
Commonly Referenced Attributes and Specialization Elements
Here is the wording of item #21 from
version 8b of issue 1207 (17 December 2007):
Key
references are not allowed on and will be treated as an error if used with href
or conkeyref attributes on topicref elements that reference maps or portions of
maps that define keys.
In the above “href” should
have been changed to “keyref”.
I’d be OK with a change requiring
(MUST) that keys defined in sub-maps that are referenced using keyrefs be
ignored. I guess it is just the presence of the @keyref or @conkeyref
that causes the sub-map key definitions to be ignored and that key definitions
in sub-maps should be ignored even if the href or conref is used as a fallback
because the keyref or conkeyref can’t be resolved.
Do we require (MUST), suggest (SHOULD),
allow (MAY), or prohibit (MUST NOT) issuing error or warning messages when keys
in sub-maps referenced using keys are ignored? I’d be OK with MUST or
SHOULD. I’d be uncomfortable with MAY or MUST NOT.
I think we need to mention this to the
DITA TC since it is a change to what they approved.
The new wording for item 21 might be:
When
keyref or conkeyref attributes are present on topicref elements or
specializations that reference maps or portions of maps any key definitions
made in the referenced maps MUST be ignored and processors SHOULD issue an
error or warning message.
-Jeff
From: Michael
Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Monday, September 22, 2008
9:19 PM
To: Ogden, Jeff
Cc: Grosso, Paul; Robert D
Anderson
Subject: RE: DITA 1.2 reviews of
Commonly Referenced Attributes and Specialization Elements
Hi Jeff,
Belatedly
realizing I never sent my reply to this:
I
think disallowing keys on map references is going too far. There are lots of
cases where someone might want a key on a topic to be repointed to a branch of
topics, and vice versa, when the need for a particular subject gets
expanded/reduced for a new audience or context. For example, in my map I only
need a single topic to define "foobars" but someone else reusing my
map needs to expand the foobar topic (referenced by key) into a whole
chapter/set of topics. So they repoint the foobar key from my foobar topic to
their foobar submap, which then gets pulled in where the foobar topic used to
appear.
In an
ideal world, there would be no difference between maps pulled in by keyref and
by href. But we don't live in an ideal world, so the compromise (to avoid
requiring processors to thrash on key mapping/keyref resolution recursively)
was to say that keys in maps pulled in by keyref would be ignored (since they
are being discovered after keys have already been harvested). That solution is
friendly to processors, and still allows flexibility for authors since they
could choose to include the same map by href in a no-toc etc. setting to
discover the keys if they need them.
Michael
Priestley
Lead IBM DITA Architect
mpriestl@ca.ibm.com
http://dita.xml.org/blog/25
|
"Ogden, Jeff"
<jogden@ptc.com>
09/10/2008
11:24 AM
|
|
To
|
"Robert D Anderson"
<robander@us.ibm.com>, "Grosso, Paul"
<pgrosso@ptc.com>
|
|
cc
|
Michael Priestley/Toronto/IBM@IBMCA
|
|
Subject
|
RE: DITA 1.2 reviews of Commonly Referenced Attributes
and Specialization Elements
|
|
My
thinking is along these lines:
It is an error to use keys to reference ditamaps.
That is what the
proposal calls for and it is the only thing
related to this that the
proposal is clear about. Not treating this as an
error is likely to
produce results that are different from what users
were expecting and it
may be difficult for them to understand why.
That we always want to tell the users about the
error.
How processors do or don't recover from the error
is up to the
processors. Different implementations will have
different philosophies
about this with some thinking the right thing to
do is to stop following
certain types of errors to avoid producing may
other errors or warnings
that are caused by the first error and others
thinking that it is better
to try to continue following errors in order to
find additional problems
in a single run even if some of those problems may
be caused by the
original error.
That as long as processors issue a message about
the error so users can
fix it, it doesn't really matter if different
implementations give
different results following such an error.
We only need to worry about
getting the same or at least very similar results
when there are no
errors.
If we adopted the approach that implementations
are free to not produce
an error message and that implantations are free
to ignore key
definitions in maps referenced using keys, that
that is effectively
saying that the use of keys for map references
isn't an error. And I
don't think we want to do that.
-Jeff
> -----Original Message-----
> From: Robert D Anderson
[mailto:robander@us.ibm.com]
> Sent: Wednesday, September 10, 2008 11:06 AM
> To: Grosso, Paul
> Cc: Ogden, Jeff; Michael Priestley
> Subject: RE: DITA 1.2 reviews of Commonly
Referenced Attributes and
> Specialization Elements
>
> I'm not entirely sure about this one.
>
> We say that it is an error to use (keyref |
conkeyref) to pull in
> additional key definitions. Jeff's suggestion
is that apps *should*
> generate a message, and *may* recover by
ignoring the definitions. It is
> starting to feel like those may be backwards.
If we say that they *may*
> ignore the definitions, doesn't that mean
some apps will ignore them, and
> others will not, meaning that the same
content in two apps will end up
> with different links
/ text / etc?
>
> I'm starting to wonder if the correct
approach is:
> * Apps may or may not generate a message
> * Apps should ignore additional key
definitions in the target map, so that
> apps at least give the same end result
>
> Or do we really want to say - it is an error
to define something this
> way,
but applications may recover by allowing it?
>
> Thanks -
>
> Robert D Anderson
> IBM Authoring Tools Development
> Chief Architect, DITA Open Toolkit
> (507) 253-8787, T/L 553-8787 (Good Monday
& Thursday)
>
>
>
>
"Grosso, Paul"
>
<pgrosso@ptc.com>
>
To
>
09/08/2008 02:01 "Ogden,
Jeff" <jogden@ptc.com>
>
PM
cc
>
Robert D
>
Anderson/Rochester/IBM@IBMUS,
>
"Michael Priestley"
>
<mpriestl@ca.ibm.com>
>
Subject
>
RE: DITA 1.2 reviews of
Commonly
>
Referenced Attributes and
>
Specialization Elements
>
>
>
>
>
>
>
>
>
>
> I'm happy to step back from this. Like
I said, I've been speaking
> standardeze for too long.
>
> Per ftp://ftp.ietf.org/rfc/rfc2119.txt.:
>
> 3. SHOULD This word, or the adjective
"RECOMMENDED", mean that there
> may exist valid reasons in
particular circumstances to ignore a
> particular item, but the full
implications must be understood and
> carefully weighed before
choosing a different course.
> 5. MAY This word, or the adjective
"OPTIONAL", mean that an item is
> truly optional. One vendor
may choose to include the item because
a
> particular marketplace requires
it or because the vendor feels that
> it enhances the product while
another vendor may omit the same
item.
> I have seen both standard writers and users
point to a SHOULD and say
that
> an implementation that doesn't implement a
SHOULD is less than
compliant
> if
> the only reason they didn't implement it is
because "a particular
> marketplace requires it or because the vendor
feels that it enhances
the
> product" (which is language from MAY
above).
>
> paul
>
> From: Ogden, Jeff
> Sent:, Monday, 2008 September 08 13:50
> To: Grosso, Paul; 'Robert D Anderson'
> Cc: 'Michael Priestley'
> Subject: RE: DITA 1.2 reviews of Commonly
Referenced Attributes and
> Specialization Elements
>
> Doesn't the difference between SHOULD and
MUST cover this? SHOULD is
> encouraging a particular behavior, but falls
short of REQUIRING that
> behavior if the implementer has a good reason
to do something
different.
> And we do want most implantations to produce
an error message.
Certainly
> editors and composition processing should.
>
> I guess that some display time processing
could omit messages. I
don't
> have much experience with that sort of
implementation and probably
have
> too
> much of an Editor or composition mindset.
>
> Given this discussion I am happy to leave the
final decision to
Robert.
> I'll make sure that whatever he puts in the
language reference and
> whatever
> I put in the Architecture Spec agree.
>
> -Jeff
>
>
> From: Grosso, Paul
> Sent: Monday, September 08, 2008 2:38 PM
> To: Ogden, Jeff; 'Robert D Anderson'
> Cc: 'Michael Priestley'
> Subject: RE: DITA 1.2 reviews of Commonly
Referenced Attributes and
> Specialization Elements
>
> I think I've been involved in
"standardeze" for a decade or two too
long.
>
> If we do what you are suggesting here, then
it seems we would need to
look
> at other cases where we use this wording and
see if it should also
change.
>
> The wording as written was specifically
designed to allow an
> implementation
> to realize that this is an error condition
and bail which is what it
means
> to not give a message and not recover.
(By definition, not recovering
> from
> an error means to bail.) So what you
say "wouldn't be good" is
precisely
> one of the things that the current wording is
trying to allow.
>
> And, on the other hand, the real point of
having MAY instead of SHOULD
> regarding issuing error messages is that some
implementations don't
want
> to
> bother the user with such messages and just
want to quietly ignore the
key
> definition. If you change it from MAY
to SHOULD, then an
implementation
> whose philosophy is to be as liberal as
possible in what it accepts
(like
> most HTML browsers tend to be--they certainly
don't give error
messages
> for
> bad markup) could be considered "less
than perfectly compliant" for
not
> doing what it "should".
>
> So that's why I think the current wording
says what I think it should
say.
> But if we decide we want it to say something
else, I can live with
that.
> I
> just don't want to think we're making simply
editorial changes when I
> think
> we're really changing what we are saying.
>
> And, yes, I noted you were making other more
important suggested
changes
> to
> which I have no objection.
>
> paul
>
>
> From: Ogden, Jeff
> Sent:, Monday, 2008 September 08 12:43
> To: Grosso, Paul; 'Robert D Anderson'
> Cc: 'Michael Priestley'
> Subject: RE: DITA 1.2 reviews of
Commonly Referenced Attributes and
> Specialization Elements
> I don't have a problem with "MAY
(but need not)" in general. And we
> would
> still use the phrase in my suggested
rewording. We'd just use it once
> rather than twice.
>
> I agree SHOULD is different from
"MAY (but need not)". In this
specific
> case I think SHOULD is better. If we
stick with "MAY (but need not)"
for
> both cases, in the extreme case an
implementation could produce no
error
> message and not recover. That wouldn't
be good. And we are using
SHOULD
> rather than MUST, so implementers still
have some flexibility.
>
> Using SHOULD isn't really a change in
the spec. since this has never
been
> included in the spec. before and the
proposal wasn't specific about
error
> recovery following the error.
>
> And while I prefer SHOULD over
"MAY (but need not)" here, I could
live
> with either.
>
> No matter how we end up with SHOULD vs.
"MAY (but need not)", there
were
> some other more important changes in
the suggested wording (ignoring
key
> references vs. ignoring key
definitions).
>
> I did miss one other item with my name
on it. I'll send a separate
> message about that in a few minutes.
>
> -Jeff
>
>
> From: Grosso, Paul
> Sent: Monday, September 08, 2008 1:02
PM
> To: Ogden, Jeff; 'Robert D Anderson'
> Cc: 'Michael Priestley'
> Subject: RE: DITA 1.2 reviews of
Commonly Referenced Attributes and
> Specialization Elements
>
> Regarding the "may but need
not" language, we've used that in the
spec in
> a variety of places (and it's in DITA
1.1 too). (In fact, I believe
I
> stole that language from the XSL spec.)
It's never seemed unclear to
me.
> The second "may but need not"
modifies the immediately following word
> "recover", and the "by
ignoring" is how one recovers. I don't see
that
> that wording needs changing.
>
> SHOULD is different from MAY as far as
RFC 2119 is concerned, so if
we go
> that route, we are changing the spec.
>
> There was also another "I think
Jeff and/or Michael need to clarify."
> point below. Jeff, did you have
any comments on that, or does your
first
> response below cover that point too?
>
> paul
>
>
> From: Ogden, Jeff
> Sent:, Monday, 2008 September 08 11:46
> To: Grosso, Paul; 'Robert D Anderson'
> Cc: 'Michael Priestley'
> Subject: RE: DITA 1.2 reviews of
Commonly Referenced Attributes and
> Specialization Elements
> Some responses to comments that seemed
to have my name on them.
>
> -Jeff
>
> >> Re: the required behavior
"Keys are defined in maps and not in
> topics."
> >> This is present because it
was listed as one in the keyref
proposal.
> >> I think it was intended to
highlight the requirement, but I'm not
> sure
> >> whether it should be removed
or modified.
>
> >As I indicated in my comments, I'm
not sure either. I think Jeff
and
> >Michael need to discuss.
>
> This was included in the proposal to
help make it clear to members
of
> the
> TC who read the proposal how things
worked, but I don't think it
needs
> to
> stay and certainly not in the same
form as the proposal.
>
> I think this could come out of the
language reference and I'll
include
> the information in the Architecture
Spec.
>
> > > It is an error for a
key reference to occur along with with
href
> > > or conkeyref
attributes on topicref elements that reference
maps
> > > or portions of maps
that define keys. In such a case, an
> > > implementation may
(but need not) give an error message, and
may
> > > (but need not) recover
from this error condition by ignoring
the
> > > key reference.
> > >
> > > I have only left this item
open because I think this may be the
same
> > > item on which Jeff helped
create new wording a few weeks ago,
and I
> > > want to make sure I did not
lose that.
> >
> > Jeff?
>
> We need to change "href" to
"keyref". Rereading this now, I think it
is
> a
> little unclear. What is the
second "may (but need not)" referring
to?
> May (but need not) recover? May (but
need not) ignore the key
reference?
> I think it is the key definitions in
the referenced map rather than
the
> key references that MUST be ignored.
Not completely sure how to word
> this
> so that it is clear. And I
wonder if we should mandate things a bit
> more
> here.
>
> Perhaps something like this would
work:
>
> It is an error
for key references (the keyref and conkeyref
> attributes) to be
used on topicref elements or specializations
> that
> reference maps or
portions of maps when the referenced maps
define
> keys. In such
cases the key definitions from the referenced
maps
> are not used, an
implementation SHOULD give an error message,
and
> MAY (but need
not) recover from the error condition by
ignoring
> the
> key definitions.
>
> -Jeff
>
>
> > -----Original Message-----
> > From: Grosso, Paul
> > Sent: Monday, September 08, 2008
10:37 AM
> > To: Robert D Anderson
> > Cc: Ogden, Jeff
> > Subject: RE: DITA 1.2 reviews of
Commonly Referenced Attributes
and
> > Specialization Elements
> >
> >
> >
> > > -----Original Message-----
> > > From: Robert D Anderson
[mailto:robander@us.ibm.com]
> > > Sent: Friday, 2008 September
05 17:22
> > > To: Grosso, Paul
> > > Cc: Ogden, Jeff; Grosso,
Paul
> > > Subject: RE: DITA 1.2
reviews of Commonly Referenced
> > > Attributes and
Specialization Elements
> > >
> > > Hi Paul - just an FYI that I
got to most of the comments
> > > today. I listed
> > > all of them (aside from a
few comma typos) on the wiki page:
> > > http://wiki.oasis-
> >
open.org/dita/Language_specification_comments_from_Paul_Grosso
> > >
> > > There are a couple that I'm
still unsure of
> >
> > Here are my comments on the
unresolved ones:
> >
> > > For image/@align, suggestion
that we remove the "(processor
> validated)
> > > values left, right, center,
or current". Agreed that it is not
good
> > > as it stands - but I wonder
if common values should still be
listed?
> > > For example, "Common
values include left, right, and center" in
> order)
> > > to give processors an idea
of what to expect? Or leave it out
> entirely?
> >
> > My first question would be, why
can't this be an enumerated type?
> > How many kinds of alignment do we
need? In most DTDs (e.g., CALS,
> > DocBook), such an attribute would
have its allowable values,
> > enumerated. Why couldn't we
have left, right, center, and
> > -dita-use-conref-target?
> >
> > If we need to keep it #CDATA,
then I'm fine with deleting the text
> > that is there and saying
"Common values include left, right, and
> center".
> >
> > > Used the suggested
re-wording for %display-atts; -- but does
anybody
> > > know how / why the display
attributes scale/frame/expanse would
> affect.
> > > the selection of a topic by
search tools? It says that now but
the
> > > entity set is typically used
by items like <fig> and <image>,
not by
> > > topics, and I'm unclear what
the description means.
> >
> > Good point. I'd delete
"or its selection by search tools".
> >
> > > I'm not sure about updating
the @format description to say it is
> > > unavailable in
topicref-atts-without format; same issue for the
> > > default of @type with topicref-atts-without-format.
Those
> definitions
> > > are reused many times,
including several cases where they are
not
> > > part of any entity group. I
wonder whether a <note> above the
table
> > > would be a better way to highlight
the issue? The review
comments
> > > already suggest removing
similar language - perhaps we could
> simplify
> > > it and turn it from
<p> into <note>.
> >
> > Given we're talking mostly an
editorial issue rather than a
> > technical one, I'm willing to
give you editor's privilege to
> > come up with something you think
works. If, when I see it,
> > I can suggest something I think
it better, I'll do so, but as
> > long as I don't think it is
confusing, I'll probably be happy.
> >
> > > Re: the required behavior
"Keys are defined in maps and not in
> topics."
> > > This is present because it
was listed as one in the keyref
proposal.
> > > I think it was intended to
highlight the requirement, but I'm
not
> > > sure whether it should be
removed or modified.
> >
> > As I indicated in my comments,
I'm not sure either. I think
> > Jeff and Michael need to discuss.
> >
> >
> > > For the item "An href
attribute in a key definition is resolved
> > > relative to ..." - I've
used the suggested rewording, rather
than
> > > removing the point, as this
issue has been a point of confusion
> > > in the past.
> >
> > Fine.
> >
> > > For this item and comment:
"Key definitions, once made, cannot
be
> > > redefined. Given the
previous list item, maybe we should say
"cannot
> > > be redefined within the same
map", since they can clearly be
> redefined
> > > in other maps." I'm not
sure of the point of this item (it came
from
> > > the proposal) - it either
means that they cannot be redefined in
the
> > > same map, or that once it is
established for a given situation
it
> > > cannot be redefined (also
true), or both. Hoping that Jeff can
help
> > > clarify the wording.
> >
> > I think Jeff and/or Michael need
to clarify.
> >
> > > For the final point in the
key requirements, as suggested, I've
> > > changed the wording from
> > >
> > > Key references are not
allowed on and will be treated as an
error
> > > if used with href or
conkeyref attributes on topicref elements
> > > that reference maps or
portions of maps that define keys.
> > >
> > > to
> > >
> > > It is an error for a
key reference to occur along with with
href
> > > or conkeyref
attributes on topicref elements that reference
maps
> > > or portions of maps
that define keys. In such a case, an
> > > implementation may
(but need not) give an error message, and
may
> > > (but need not) recover
from this error condition by ignoring
the
> > > key reference.
> > >
> > > I have only left this item
open because I think this may be the
same
> > > item on which Jeff helped
create new wording a few weeks ago,
and I
> > > want to make sure I did not
lose that.
> >
> > Jeff?
> >
> > paul?
|