Re: In support of symbolic references

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



John C Klensin schrieb:

--On Thursday, 05 April, 2007 15:48 -0400 Sam Hartman
<hartmans-ietf@xxxxxxx> 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@xxxxxxxx
https://www1.ietf.org/mailman/listinfo/ietf

[Index of Archives]     [IETF Annoucements]     [IETF]     [IP Storage]     [Yosemite News]     [Linux SCTP]     [Linux Newbies]     [Fedora Users]