[rfc-i] draft-iab-styleguide-02 on referencing STDs

Julian Reschke julian.reschke at gmx.de
Thu Apr 10 23:57:58 PDT 2014


This text is new, and I think it has lots or problems:

> 4.8.6.3. Referencing STDs and BCPs
>
>
>    Standards (STDs) and Best Current Practices (BCPs) may consist of a
>    single RFC or multiple RFCs.  When an STD or BCP that contains
>    multiple RFCs is referenced, the reference entry should include ALL
>    of the RFCs comprising that subseries.  The authors should refer to

Does that imply that the reference by STD number is *mandatory*?

>    specific RFC numbers as part of the text (not as citations) and cite
>    the subseries number.  Inclusion of the URI to the STD or BCP info
>    page is now recommended.  The text should appear as follows:
>
>       See RFC 1034 [STD13].

That ruins hyperlinking in the generated output formats. Also, it'll 
make linking to specific sections and marking that information up in a 
readable way a headache.

...augmenting a reference with the information that it is part of a STD 
is good, but pretending it *is* the reference is bad.

>    For an STD or BCP that contains one RFC:
>
>       [STDXXX]  Last name, First initial., Ed. (if applicable)
>                 "RFC Title", BCP/FYI/STD ##, RFC ####, Date of
>                 Publication.
>                 <http://www.rfc-editor.org/info/std####>
>
>       Example:
>
>       [STD72]   Gellens, R. and J. Klensin, "Message Submission
>                 for Mail", STD 72, RFC 6409, November 2011.
>                 <http://www.rfc-editor.org/info/std72>

So if I want to reference Section 3 of RFC 6409, through how many 
indirections will the reader have to go to actual get to the referenced 
text???

>    For an STD or BCP that contains two or more RFCs:
>
>
>       [STDXXX]  Last name, First initial., Ed. (if applicable)
>                 "RFC Title", BCP/FYI/STD ##, RFC ####, Date of
>                 Publication.
>
>                 Last name, First initial., Ed. (if applicable)
>                 and First initial. Last name, Ed. (if applicable)
>                 "RFC Title", BCP/FYI/STD ##, RFC ####, Date of
>                 Publication.
>
>                 <http://www.rfc-editor.org/info/std###>
>
>      Example:
>
>       [STD13]    Mockapetris, P., "Domain names - concepts and
>                  facilities", STD 13, RFC 1034, November 1987.
>
>                  Mockapetris, P., "Domain names - implementation and
>                  specification", STD 13, RFC 1035, November 1987.
>
>                  <http://www.rfc-editor.org/info/std13>

I find it very confusing that the STD itself doesn't have a title.

It's also confusing that the individual entries do not follow the 
proposed RFC format.

It's also not clear why we are repeating the STD13 information here.

So I believe this would better be:


       [STD13]    "Domain Names", STD 13,
                   <http://www.rfc-editor.org/info/std13>. Consisting
                  of:

                  Mockapetris, P., "Domain names - concepts and
                  facilities", RFC 1034, November 1987.
                  <http://www.rfc-editor.org/info/rfc1034>

                  Mockapetris, P., "Domain names - implementation and
                  specification", RFC 1035, November 1987.
                  <http://www.rfc-editor.org/info/rfc1035>

a) Yes, we'd need names for the STDs and BCPs.

b) It still makes it hard to reference something specific in the series 
contents.

This absolutely needs much more work, please don't rush it out.

Best regards, Julian


More information about the rfc-interest mailing list