Re: In support of symbolic references

[Julian Reschke <julian.reschke at gmx.de>]

John C Klensin schrieb:
> --On Thursday, 05 April, 2007 15:48 -0400 Sam Hartman
> <hartmans-ietf at mit.edu> 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.

+1 on that one.

> 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. 

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]..."

> 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.

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).

> 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.

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





_______________________________________________
Ietf mailing list
Ietf at ietf.org
https://www1.ietf.org/mailman/listinfo/ietf