Re: [apps-discuss] On citations in general

[SM <[e-mail]>]

Hi Barry,
At 08:06 25-04-2012, Barry Leiba wrote:
>While I'm on the topic of citations, let me throw something out to
>this crowd before sending it to the general IETF discussion list.

Peter already commented on rfc-interest.

>There are various styles of using citations, and various strongly held
>opinions about which ones are good, which evil, and which lie
>somewhere between.  I don't want to make this a religious argument,
>though I'm pretty sure it will be that, but here:

It's unfortunately going to turn into one.

>I consider that a citation in the text serves two purposes.  One is to
>explain where the information came from, and the other is to make it
>easy to get to the cited document.  As cute as it may be to say things
>like, "To use items defined in [EMAIL], one must additionally...", I
>find that it's not very helpful when I reading documents.

Yes.

>What I prefer to see -- what helps me the most as a reader -- is both
>short text and an RFC number.  Often, if the short text is properly
>chosen, I don't have to look at the referenced document at all.  And
>when I do, I can find it immediately from the RFC number in the
>citation, without having to bounce to the bottom of the doc and look
>at the references.  Of course, if there are repeated citations, I
>don't expect every one to have the full thing, and just the RFC
>citation is enough.

I find that having the RFC number makes the text for some RFCs more readable.

>It's also sometimes very useful to have section numbers in the
>citations, when one needs to be referred to a specific point in the
>cited document.  Consider this, from one of the httpbis documents:

Yes, especially for a long document.

BTW, this is more of a matter of style.

Regards,
-sm