Subject: [port-srv-reg] Reference style

From: Stuart Cheshire <[email-masked]>
Date: Wed, 18 Nov 2009 22:14:16 -0800

Another request to others working on this document:

Despite common habit of many RFC writers, references are a  
*supplement* to grammatically correct prose, not a *substitute* for  
it. Write a grammatically correct sentence that makes sense first,  
and then add supporting references if necessary.

To explain what I mean, consider a reader who doesn't have all the  
RFC numbers memorized (especially the ones from 20 years ago). To  
that reader, any RFC number is equivalent to "blah":

> This document updates IANA's allocation guidelines for UDP and TCP  
> port numbers by obsoleting Sections 8 and 9.1 of [blah]. (Note that  
> different sections of [blah] were updated in February 2008 by  
> [blah].)  This document also updates the IANA allocation procedures  
> for DCCP as defined in [blah].  It updates [blah] to clarify what a  
> service name is and how it is registered, because [blah] simply  
> refers to [blah] when defining service names, which in turn  
> contains now-obsolete copies [blah] of various IANA registries.

Now, compare that with the new text:

> This document updates IANA's procedures for UDP and TCP port  
> numbers by obsoleting Sections 8 and 9.1 of the IANA allocation  
> guidelines [RFC2780].  (Note that different sections of the IANA  
> allocation guidelines, relating to the protocol field values in  
> IPv4 header, were also updated in February 2008 [RFC5237].)  This  
> document also updates the IANA allocation procedures for DCCP  
> [RFC4340].
>
> This document also updates the DNS SRV specification [RFC2782] to  
> clarify what a service name is and how it is registered, because  
> that specification merely makes a brief mention that the symbolic  
> names of services are defined in "Assigned Numbers" [RFC1700],  
> without stating to which section of that 230-page document it  
> refers.  The DNS SRV specification may have been referring to the  
> list of Port Assignments (known as /etc/services on Unix), or to  
> the "Protocol And Service Names" section, or to both, or to some  
> other section.  Furthermore, "Assigned Numbers" is now obsolete  
> [RFC3232] and has now been replaced by on-line registries [PORTREG] 
> [PROTSERVREG].

Here the references serve to *clarify* the text, but the text alone  
is still meaningful grammatically-correct sentences.

Stuart Cheshire <[email-masked]>
* Wizard Without Portfolio, Apple Inc.
* Internet Architecture Board
* www.stuartcheshire.org