Re: [apps-discuss] WGLC on draft-ietf-appsawg-rfc5451bis-00

[Barry Leiba <[e-mail]>]

>> 2. Have I told you how unhappy I am with the citation style you use?
>
> Not until now!
>
>> It's generally not something I'm willing to argue about, preferring to
>> defer to the authors' style of citations

OK, so let me be clear.  Let's please not discuss this further in this
thread, though; if we want to pursue it, let's do it in a separate
thread, or, even better, on the rfc-interest list.

I prefer for citations to be maximally useful, without requiring the
reader to go to the bottom of the document and look at the references
for everything.  That means that the style "[AR-ORIG]" is truly
sub-optimal, because it gives *no* useful information until it's been
looked up at least once.  It also means that "[RFC5451]", by itself,
isn't great either, because, while it tells you where to find the
cited document, it doesn't tell you what it is.  Consider these:

1. "According to [RFC5321], the MAIL FROM command <...etc...>"

2. "According to [SMTP], the MAIL FROM command <...etc...>"

3. "According to SMTP [RFC5321], the MAIL FROM command <...etc...>"

4. "According to Simple Mail Transfer Protocol (SMTP) [RFC5321], the
MAIL FROM command <...etc...>"

In cases (1) and (2), you're requiring the reader to know what RFC
5321 or "SMTP" are, or forcing them to go look up the reference.  In
cases 3 and 4, you give more information: you're citing *both* SMTP
and RFC 5321, and it's much more likely that a reader will know what's
being cited without having to look at the reference.

For citations to this document (well, or the original version, for
now) from elsewhere, one might say something like this:

"The description of the Message Authentication Status header field
[RFC5451], specifies that <...etc...>"

... which seems far superior to citations that simply use bare
"[RFC5451]" or something like "[AUTH-STAT]".

Barry