[xml2rfc] References feature

ned.freed at mrochek.com (Ned Freed) Fri, 30 June 2006 15:04 UTC

From: ned.freed at mrochek.com (Ned Freed)
Date: Fri, 30 Jun 2006 15:04:35 +0000
Subject: [xml2rfc] References feature
In-Reply-To: "Your message dated Fri, 30 Jun 2006 14:48:09 -0700 (PDT)" <Pine.LNX.4.10.10606301443160.6820-100000@shell4.bayarea.net>
References: <01M48MPYZAVW0008CX@mauve.mrochek.com> <Pine.LNX.4.10.10606301443160.6820-100000@shell4.bayarea.net>
Message-ID: <01M48NPH8U2I0008CX@mauve.mrochek.com>
X-Date: Fri Jun 30 15:04:35 2006

> HI,

> I'm not sure I follow the logic.

Again, I see the status of a reference as cumulative. I don't see a specific
place where a reference appears as having any  particular meaning in terms
of its normative status. 

I suppose that in theory every xref could be seen as having it's own
status, but this just isn't how documents are developed in practice,
in my experience at least.

> It seems like if I make a bunch of citations, and mark each
> with "it's 'normative' or 'informative'" that it would be
> easy to put the reference in the 'normative' section if
> any citation was normative. Later on, if the 'normative'
> citation was removed (or perhaps changed to 'informative')
> then the reference would auto-magically move to the
> proper section.

Only if you find all the places and change them. Why would I want
to wade through the entire document doing that?

				Ned
>From ned.freed at mrochek.com  Fri Jun 30 17:05:25 2006
From: ned.freed at mrochek.com (Ned Freed)
Date: Fri Jun 30 16:12:48 2006
Subject: [xml2rfc] References feature
In-Reply-To: "Your message dated Fri, 30 Jun 2006 23:16:42 +0100"
 <8537.1151705802.245982@peirce.dave.cridland.net>
References: <01M48MPYZAVW0008CX@mauve.mrochek.com>
 <Pine.LNX.4.10.10606301443160.6820-100000@shell4.bayarea.net>
 <01M48NPH8U2I0008CX@mauve.mrochek.com>
 <8537.1151705802.245982@peirce.dave.cridland.net>
Message-ID: <01M48Q3ZG7N60008CX@mauve.mrochek.com>

> On Fri Jun 30 22:59:59 2006, Ned Freed wrote:
> > > It seems like if I make a bunch of citations, and mark each
> > > with "it's 'normative' or 'informative'" that it would be
> > > easy to put the reference in the 'normative' section if
> > > any citation was normative. Later on, if the 'normative'
> > > citation was removed (or perhaps changed to 'informative')
> > > then the reference would auto-magically move to the
> > > proper section.
> >
> > Only if you find all the places and change them. Why would I want
> > to wade through the entire document doing that?

> No, you don't have to - the idea would be that if you removed the
> only normative xref (ie, <xref ... thing='normative'/>) leaving only
> informative ones (ie, <xref ... thing='informative'/>) then it'd
> automagically happen. No wading required - I'm sure an amusing
> reference to Dallas can be made here.

Your model for working with documents is completely different from mine then
(and having watched the process with lots of other people doing the editing, I
don't think your approach is the common one). In the rare edge cases where the
normative/informative status of a reference is a judgement call (most of the
time it's a nonbrainer and immutable), I make the decision baed on an
examination of the entire document and how it relates to the other
specification. The specific places where references occur are somewhere between
totally irrelevant and actively misleading.

If I had to mark all the references as to whether they were normative or
informative I would inevitably end up with a mish-mash in these corner cases.
THen when I decide to switch to informative, I have to wade through and find
they all. Not hard, but annoying, because the tendency will be to stop at the
first one.

> The actual reference elements would be thrown in a single container,
> and not marked normative or informative, xml2rfc figures out the
> normativeness of them by the presence of a normative xref. Any others
> get turned into informative references.

I understand the model you're proposing quite well. I just don't think it's an
improvement.

				Ned
>From ned.freed at mrochek.com  Fri Jun 30 18:33:30 2006
From: ned.freed at mrochek.com (Ned Freed)
Date: Fri Jun 30 17:46:25 2006
Subject: [xml2rfc] References feature
In-Reply-To: "Your message dated Sat, 01 Jul 2006 01:10:20 +0100"
 <8537.1151712620.883534@peirce.dave.cridland.net>
References: <01M48MPYZAVW0008CX@mauve.mrochek.com>
 <Pine.LNX.4.10.10606301443160.6820-100000@shell4.bayarea.net>
 <01M48NPH8U2I0008CX@mauve.mrochek.com>
 <8537.1151705802.245982@peirce.dave.cridland.net>
 <01M48Q3ZG7N60008CX@mauve.mrochek.com>
 <8537.1151712620.883534@peirce.dave.cridland.net>
Message-ID: <01M48TD4IEVO0008CX@mauve.mrochek.com>

> On Sat Jul  1 00:05:25 2006, Ned Freed wrote:
> > Your model for working with documents is completely different from
> > mine then
> > (and having watched the process with lots of other people doing the
> > editing, I
> > don't think your approach is the common one).

> Well, my approach is the same as yours right now. I don't know
> whether I'd change it - I suspect it'd vary according the the
> document.

> > The specific places where references occur are somewhere between
> > totally irrelevant and actively misleading.
> >
> >
> Well, that's an entirely different matter - it might be interesting
> if XML2RFC warned that a normative reference was only referenced
> within an informative appendix, say. But that again requires
> additional markup, and doesn't work the other way around.

> But it's *how* it's referenced, not where.


> > If I had to mark all the references as to whether they were
> > normative or
> > informative I would inevitably end up with a mish-mash in these
> > corner cases.

> I'm with you up to here.


> > THen when I decide to switch to informative, I have to wade through
> > and find
> > they all. Not hard, but annoying, because the tendency will be to
> > stop at the
> > first one.
> >
> >
> Okay, here I get lost. Why would you want to change a reference from
> being normative to informative?

it happens all the time in these edge cases. Remember, in the majority
of cases the status of a reference is clear and immutable, and you might
as well specify it in one common location. It's the edge cases where
all the tricky stuff might be of use. Trouble is, this particular trick
makes things more difficult, not less, IMO at least.

It would be one thing if the bias was towards making informative references
normative. But I have not observed such a bias in practice.

> The only case I can see for this is
> it you're changing the specification such that all the xrefs become
> informative. I suppose you might want to force this case for
> procedural reasons, but that's a reason to change the specification,
> not to simply downgrade the reference. Or am I being purist here?

All I can say is that when statuses change they change in both directions.

> >> The actual reference elements would be thrown in a single
> >> container,
> >> and not marked normative or informative, xml2rfc figures out the
> >> normativeness of them by the presence of a normative xref. Any
> >> others
> >> get turned into informative references.
> >
> > I understand the model you're proposing quite well. I just don't
> > think it's an
> > improvement.

> First off, it's not my proposal. I just thought that neither you nor
> Marshall seemed to grasp it, and any idea should only ever get shot
> down for the right reasons. It turns out I simply misunderstood your
> objection.

> Now, personally, I think there would be cases where the reference
> would be normative even though no xrefs were normative. I also
> suspect that even if you covered this, you'd end up with significant
> extra markup (for authors) and code (for implementors), and I'm not
> sure there's sufficient benefit to pay for this effort.

Well, this brings up another issue, which is that in order for something to be
in the references section there has to be an xref to it somewhere. (xml2rfc
isues a warning if you have such a dangling citation.) I happen to think this
is dumb - these are references, not footnotes - especially in the case of
informative references. But the RFC Editor disagrees, so that's that.

				Ned