Subject: In support of symbolic references

From: Sam Hartman <[email-masked]>
Date: Thu, 5 Apr 2007 15:48:26 -0400 (EDT)

Hi.  I'm sitting here reviewing changes to a document to see if I can
last call it.

As part of a response to AD review comments, one of the references
were changed.  This document uses numeric references.  Starting at
reference 16, everything was renumbered.  That makes the diff a pain.

For this and many other reasons, I strongly encourage people to avoid
numeric references in their documents.

_______________________________________________
Ietf mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: Simon Josefsson <[email-masked]>
Date: Thu, 05 Apr 2007 22:19:11 +0200

> numeric references in their documents.

That makes sense, but I believe the default for the xml2rfc tool is to
produce numeric references.  Does xml2rfc support symbolic references?
If the defaults in xml2rfc is changed to symbolic references, I think
we'd see that a lot of documents would adopt the new approach.

/Simon

---

From: "Steven M. Bellovin" <[email-masked]>
Date: Thu, 5 Apr 2007 16:57:46 -0400

On Thu, 05 Apr 2007 22:19:11 +0200
Simon Josefsson <[email-masked]> wrote:

> > Hi.  I'm sitting here reviewing changes to a document to see if I
> > can last call it.
> >
> > For this and many other reasons, I strongly encourage people to
> > avoid numeric references in their documents.
> 
Use the line

	<?rfc symrefs="yes" ?>

to get symbolic references.

		--Steve Bellovin, http://www.cs.columbia.edu/~smb

---

From: Simon Josefsson <[email-masked]>
Date: Thu, 05 Apr 2007 23:00:24 +0200

> to get symbolic references.

Neat.  Maybe we can lobby for it to become the default.  Is there some
IDNit rule that suggest or imply that references should be numeric?  A
lot of documents have numeric references, so I could imagine that it
is used in some examples, and therefor used by default by tools.

/Simon

---

From: "Steven M. Bellovin" <[email-masked]>
Date: Thu, 5 Apr 2007 20:17:17 -0400

On Thu, 05 Apr 2007 23:00:24 +0200

> is used in some examples, and therefor used by default by tools.
No, there's no such rule; symbolic references are explicitly
permitted.  See Section 2.7 of
ftp://ftp.rfc-editor.org/in-notes/rfc-editor/instructions2authors.txt

---

From: John C Klensin <[email-masked]>
Date: Thu, 05 Apr 2007 21:26:25 -0400

--On Thursday, 05 April, 2007 15:48 -0400 Sam Hartman
<[email-masked]> wrote:

> Hi.  I'm sitting here reviewing changes to a document to see
> if I can last call it.
> 
> As part of a response to AD review comments, one of the
> references were changed.  This document uses numeric
> references.  Starting at reference 16, everything was
> renumbered.  That makes the diff a pain.
> 
> For this and many other reasons, I strongly encourage people
> to avoid numeric references in their documents.

Sam,

While I'm sympathetic to this, after all the statements of
support, let me play devil's advocate for a moment.  

For whatever it is worth, I've used symbolic references in some
recent documents and numeric references in others, depending on
circumstances.  Where numeric references are used, I generally
try to make it clear from context what is being referenced.  For
example, I prefer "...as seen in RFC2223 [1]..." to "...as seen
in [1]..." or "...as seen in [RFC2223]...", _both_ of which
violate the rules of most of the style manuals of which I'm
aware.  The fourth possibility "...as seen in RFC 2223
[RFC2223]..." doesn't violate any rules other than the metarule
against general redundant ugliness. 

More generally, there are at least two reasons to use numeric
references, especially in conjunction with xml2rfc.   

First, the decision to split normative and informative
references left us with a situation in which numerical
references are easy to find, while symbolic ones imply a need to
look, separately, in two different places.  If we had wanted to
optimize symbolic references _and_ a distinction between
normative and informative references, we would have included the
distinction by notation in each reference, not made it by
creating reference subsections.

Second, because of the desire to create a universal naming
scheme in the bibliographical libraries, xml2rfc ends up with
symbolic references that look like
[I-D.rfc-editor-rfc2223bis] (one of the less unattractive ones)
or, potentially,
[I-D.draft-narten-iana-considerations-rfc2434-bis].  Those
things cause formatting problems, violate almost every known
style manual about forms for symbolic references, and so on.  If
our tools permitted us to use the forms that are recommended in
the rest of the world, such as "[Nart07a]" for the above, it
would be different.  But they don't permit doing so conveniently.

       john

---

From: "Eastlake III Donald-LDE008" <[email-masked]>
Date: Thu, 5 Apr 2007 23:17:01 -0400

I just use nroff and have no trouble creating whatever succinct symbolic
references I want.

Donald 

-----Original Message-----
From: John C Klensin [mailto:[email-masked]] 
Sent: Thursday, April 05, 2007 9:26 PM
To: Sam Hartman; [email-masked]
Subject: Re: In support of symbolic references

...

       john

---

From: "Bill Fenner" <[email-masked]>
Date: Thu, 5 Apr 2007 20:45:51 -0700

On 4/5/07, John C Klensin <[email-masked]> wrote:
> ... xml2rfc ends up with

I wrote an xsl transform that does this.

xml2rfc mydoc.xml mydoc-tmp.xml
xsltproc strip-id-references.xsl mydoc-tmp.xml > mydoc-tmp2.xml
xml2rfc mydoc-tmp2.xml mydoc.txt

http://rtg.ietf.org/~fenner/ietf/xml2rfc-xsl/strip-id-references.xsl

(Not to say that this is "convenient", but it's at least possible)

  Bill

---

From: Michael StJohns <[email-masked]>
Date: Fri, 06 Apr 2007 00:29:31 -0400

Going back to the original problem, it might be more useful to use an xml diff program than a text diff program since that's where the changes will be made (and visible). The anchors and targets will stay stable.

 Maybe we can have this added to the tool set?

---

From: Jari Arkko <[email-masked]>
Date: Fri, 06 Apr 2007 09:12:48 +0300

Simon,

> Maybe we can lobby for it to become the default.
+1

(I think it would be the right default, even if I agree with John
Klensin's concern.)

Jari

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 06 Apr 2007 09:21:54 +0200

> (I think it would be the right default, even if I agree with John

Putting symrefs into all the xml2rfc templates would not be a
bad idea. If you want to suggest a change in the default,
writing to [email-masked] is a good first move.

     Brian

---

From: Francis Dupont <[email-masked]>
Date: Fri, 06 Apr 2007 12:56:03 +0200

+1

=> +1 too

[email-masked]

---

From: Dave Cridland <[email-masked]>
Date: Sat, 07 Apr 2007 09:10:03 +0100

> I wrote an xsl transform that does this.

I also wrote some XSLT preprocessors that people may (or may not) 
find useful.

First, I have a XSL transform that allows me to import references 
from the library using any symbolic name I feel like, by adding an 
element <dwdrfc-ref anchor="KEYWORDS" 
src="bibxml/reference.RFC.2119"/> - this one is handled by:

http://svn.dave.cridland.net/svn/ietf-drafts/rfc2629-noinc.xml

(Which also pulls in any <?rfc include=""?> files too, and strips 
away the metadata mentioned below).

Second, I have a reference checking XSL, which simply outputs a 
fairly self-explanatory XML document with any reference errors in. 
This one uses an additional attribute on xref elements to indicate 
Normative references, flagging references where any of the following 
is true:

a) There's an xref, but no anchor. (The target doesn't exist).
b) There's a reference, but no xref. (Unused reference).
c) There's a normative reference, but no xref with the dwdrfc-type 
attribute set to 'norm'. (Based on a suggestion from the xml2rfc 
list, I forget whose idea this was now).

This one is at:

http://svn.dave.cridland.net/svn/ietf-drafts/rfc2629-refchk.xsl

Both use a non-DTD attribute rather than a namespaced one because 
otherwise xsltproc emits a namespace declaration even if I've 
stripped them out, which seemed to confuse xml2rfc, so I opted for 
the "hack that works" instead of a purist view. I make no claims that 
they work, or are good, but I find them useful and others are more 
than welcome to use them, or cherry-pick ideas. (And yes, no doubt 
the XSL is rubbish too).

Dave.
-- 
Dave Cridland - mailto:[email-masked] - xmpp:[email-masked]
  - acap://acap.dave.cridland.net/byowner/user/dwd/bookmarks/
  - http://dave.cridland.net/
Infotrope Polymer - ACAP, IMAP, ESMTP, and Lemonade

---

From: Elwyn Davies <[email-masked]>
Date: Sat, 07 Apr 2007 14:17:29 +0100

Brian E Carpenter wrote:
> bad idea. 
The 'default; in the templates on the RFC Editor's webpage 
(http://www.rfc-editor.org/formatting.html) are already set to give 
symbolic references,
> If you want to suggest a change in the default,
There is an issue with 'no surprises' as Marshall has written on that list.

/Elwyn

---

From: Dave Crocker <[email-masked]>
Date: Sat, 07 Apr 2007 08:33:17 -0700

Michael StJohns wrote:
> Going back to the original problem, it might be more useful to use an xml
> diff program than a text diff program since that's where the changes will
> be made (and visible). The anchors and targets will stay stable.
> 

+1

d/
-- 

   Dave Crocker
   Brandenburg InternetWorking
   bbiw.net

---

From: Julian Reschke <[email-masked]>
Date: Sat, 07 Apr 2007 17:52:18 +0200

>> to avoid numeric references in their documents.

+1 on that one.

> against general redundant ugliness. 

Understood. It's not pretty, but I generally prefer it to the other 
forms mentioned above. In some cases, you can make it less ugly by 
saying something like

   "...as seen in HTTP/1.1 [RFC2616]..."

> creating reference subsections.

Correct. With symbolic references, you need to scan two lists (for 
symrefs, we really should make alphabetic sorting a requirement).

The downside of numerical references with respect to the split between 
normative and informative is that numbers change when you move a 
reference from one section to the other (I was just doing that in 
RFC2616bis, and we decided to convert to symbolic references just 
because of that).

> would be different.  But they don't permit doing so conveniently.

But that's only a problem if you insist to re-use the ID references 
provided by xml.resource.org verbatim. If you instead just paste them 
in, you can change the anchor to whatever you like.

In general, I think that referring to IDs by referencing the bib entry 
is very dangerous, because one may miss important changes like section 
numbering or changes in BNF names when the draft being referred to 
progresses.

Best regards, Julian

---

From: John C Klensin <[email-masked]>
Date: Sun, 08 Apr 2007 17:21:35 -0400

--On Saturday, April 07, 2007 5:52 PM +0200 Julian Reschke 
<[email-masked]> wrote:

>> [I-D.rfc-editor-rfc2223bis] (one of the less unattractive
>> ones) or, potentially,
>> style manual about forms for symbolic references, and so on.
>> If our tools permitted us to use the forms that are
>> recommended in the rest of the world, such as "[Nart07a]" for
>> the above, it would be different.  But they don't permit
>> doing so conveniently.
>
> But that's only a problem if you insist to re-use the ID
> references provided by xml.resource.org verbatim. If you
> instead just paste them in, you can change the anchor to
> whatever you like.
>
> In general, I think that referring to IDs by referencing the
> bib entry is very dangerous, because one may miss important
> changes like section numbering or changes in BNF names when
> the draft being referred to progresses.

Well, we agree and that is what I've generally been doing.  But, 
having recently had a colleague who took over a document 
carefully remove my pasted-in I-D references in order to replace 
them with library pointers just before forwarding to the RFC 
Editor, I'm a little sensitive to this one and suspect that some 
additional guidance to the community would be in order.

best,
      john

---

From: "Romascanu, Dan \(Dan\)" <[email-masked]>
Date: Mon, 9 Apr 2007 17:35:24 +0300

> From: Jari Arkko [mailto:[email-masked]] 
> Sent: Friday, April 06, 2007 9:13 AM
> To: Simon Josefsson
> Cc: Sam Hartman; [email-masked]; Steven M. Bellovin
> (I think it would be the right default, even if I agree with 
> John Klensin's concern.)
> 
> Jari
> 

Same here. 

I used symbolic references in all documents I authored or co-authored
recently and I have expressed my preference for symbolic references in
many reviews I performed in the past, although I was missing grounds to
make this a very strong recommendation.

Dan