[rfc-i] feedback on draft-iab-styleguide-02

Julian Reschke julian.reschke at gmx.de
Thu Apr 10 23:38:59 PDT 2014

...based on my earlier review, looking at the diffs...:

 >     *  When a sentence ended by a period is immediately followed by
>        another sentence, there should be two blank spaces after the
>        period.

-> What Paul said.

>        First-page header                      * [Required]
>        Title                                    [Required]
>        Abstract                                 [Required]
>        RFC Editor or Stream Manager Note      * [Upon request]
>        Status of this Memo                    * [Required]
>        Copyright and License Notice           * [Required]
>        Table of Contents                        [Required]
>        Body of the Memo                         [Required]
>          1.  Introduction                       [Required]
>          2.  Requirement Words (RFC 2119)
>          3.  ...
>              MAIN BODY OF THE TEXT
>          6.  ...
>          7.  IANA Considerations                [Required in I-D]
>          8.  Internationalization Considerations
>          9.  Security Considerations            [Required]
>          10.  References
>          10.1.  Normative References
>          10.2.  Informative References
>          Appendix A.
>          Appendix B.
>        Acknowledgments
>        Contributors
>        Author's Address                         [Required]

"Acknowledgements" and "Contributors" are usually just a section (not 
appendix), because that's the only form xml2rfc can generate. We should 
  align the tools with the style guide or vice versa. I'll also note 
that this practice currently isn't followed, so maybe we could just 
align the style guide with reality?

>     If an author cannot or will not provide an affiliation for any
>     reason, "Independent", "Retired", or some other term that
>     appropriately describes the author's affiliation may be used.
>     Alternatively, a blank line may be included in the document header
>     when no affiliation is provided.
> I believe that's new, and the xml2rfc processors may not support that yet.

So is this something we need to discuss as extension of the <author> 
element? If so, please bring it up in the v3 discussions.

>     most stable (i.e., unlikely to change and expected to be continuously
>     available) and direct reference possible.  The URL will be verified
>     as valid during the RFC editorial process.  Personal web pages and
>     web caching services are not considered stable and will not be
>     accepted as a normative reference.  Informative references to blogs
>     are acceptable if they are an organizational blog and not a personal
>     space.
> ...

The next text about URIs is an improvement, but this

"Note that URIs may not be the sole information provided for a	reference 

make me uncomfortable, because I know of cases where it hasn't been 
followed in the past. What if you *really* don't have any information 
except the URI???? Or do you count the title as sufficient extra 

New text:

   "For 1 Author or Editor"

That implies that author != editor, whereas my understanding is that 
"editor" is just a role (essentially a flag).

>       [RFCXXXX] Last name, First initial., Ed. (if applicable),
>                 "RFC Title", BCP/FYI/STD ## (if applicable),
>                 RFC ####, Date of Publication.
>                 <http://www.rfc-editor.org/info/rfc####>

Why do we have the restriction to "first initial"?

Also, I continue to believe that including a URI here that is *not* the 
URI of the actual document is very very misleading.

>     References to Internet-Drafts can only appear as Informative
>     references. Given that several revisions of an I-D may be produced in
>     a short time frame, references must include the publication date
>     (month and year), the full Internet-Draft file name (including the
>     version number), and the use the phrase "Work in Progress".  If the
> ...

WRT to "Work in Progress" - this has been discussed a lot, including in 
  an RSE-appointed team, and the outcome was that this needs to be 
relaxed, as "Work in Progress" is totally misleading for historic drafts.

> ...
>     The following format is required when a reference to an errata report
>     is necessary:
>        [ErrNNNN]  RFC Errata, Errata ID NNNN, RFC NNNN,
>                   <http:/www.rfc-editor.org>.
>        [Err1912]  RFC Errata, Errata ID 1912, RFC 2978,
>                   <http://www.rfc-editor.org>.
> Big -1. The RFC Editor should provide stable URIs for errata, and they
> should be used in the reference.

I note that the URI has been removed (good), but not replaced by 
something useful.

> Also, the format is very misleading. The erratum is not the RFC, so this
> is a case where the notation deviates from what we use elsewhere.
> Can we make it "RFC Erratum RFCXXXX-NNNN", so we can drop the "RFC NNNN"
> entry?


>        [W3C.REC-xml11]
>                Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E.,
>                Yergeau, F., and J. Cowan, "Extensible Markup Language
>                (XML) 1.1 (Second Edition)", W3C Recommendation
>                REC-xml11-20060816, August 2006, <http://www.w3.org/TR/
>                2006/REC-xml11-20060816>.
> The format recommended by the W3C is different. See
> <http://greenbytes.de/tech/webdav/rfc2629xslt/w3c-references.html>.


> 4.9.  Appendices
>     The RFC Editor recommends placing references before the Appendices.
>     Appendices should be labeled as "Appendix A.  Appendix A Title",
>     "A.1.  Appendix A.1 Title", "Appendix B.  Appendix B Title", etc.
> That reads weird, maybe use a different string for the title.


> Another format xml2rfc can't easily produce...
>     [ISO3297]  Technical Committee ISO/TC 46, Information and
>                documentation, Subcommittee SC 9, Identification and
>                description, "Information and documentation -
>                International standard serial number (ISSN)", 09 2007.
> s/09/September/?


> ...

Best regards, Julian

More information about the rfc-interest mailing list