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

Julian Reschke julian.reschke at gmx.de
Mon Mar 24 10:20:19 PDT 2014


On 2014-03-24 17:33, Heather Flanagan (RFC Series Editor) wrote:
> On 3/14/14, 4:09 AM, Julian Reschke wrote:
>>     Guidance provided by this document will not be applied until
>>     published as an RFC.  Please send your comments about the contents of
>>     this document to <rfc-interest at rfc-editor.org>.
>>
>> The last sentence shouldn't be part of the abstract (but an Editorial
>> Note).
>
> It won't be part of the document at all, when published.
>
>>
>>     *  When a sentence ended by a period is immediately followed by
>>        another sentence, there should be two blank spaces after the
>>        period.
>>
>> This is a rule that (IMHO) only makes sense for plain text renderings.
>> It requires heuristics in the generator tools to detect line ends. We
>> really should get rid of it.
>
> Its utility largely depends on the fonts used.  I don't know of any font
> where two spaces versus one after a period causes difficulty in reading,
> whereas with some fonts it is helpful.  If it does no harm, and some
> good, I would rather keep this rule.

Well, in HTML two spaces display actually like a single space; so you'd 
have to convert to something else (like a nbsp).

Also, it does harm in that it makes processing harder by requiring 
heuristics on the input document.

> ...
>>        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.
>
> Yes.  Some of the guidance in the new Style Guide will require changes
> in the tools in order to fully implement.

Or maybe we can align the style guide with reality? :-)

> ...
>>     To simply specify a necessary logical relationship, the normal
>>     lowercase words should be used.  On the other hand, if the
>>     capitalized words are used in a document, choose and use them
>>     carefully and consistently.
>>
>> This seems to contradict advice from BCP14: "These words are often
>> capitalized." Note: "often", not "always".
>
> If an author referred to RFC 2119 and yet did not use capitalized words,
> the RFC Editor would definitely question and push back.  RFC 2119
> language without that subtle clue of ALL CAPS would not fit under the
> guiding principles of readability, clarity, consistency, and uniformity.

By all means can you please discuss this with the IESG? I don't really 
care about what rule we follow as long as it's the same rule everywhere.

> ...
>>     If a dated URL is available for a referenced web page, its use is
>>     required.
>>
>> Define "dated".
>
> dat·ed
> adjective
>
> 1:  provided with a date <a dated document>

Is this about a date *within* the URL, or as additional data in the 
citation?

> ...
>> 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.
>
> Yes, but changing it means that RFC 2026 itself has to be updated, and
> that can't be done with an Informational RFC like the Style Guide.  We
> should tackle that as a separate issue.

Please. ASAP.

>>     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.
>>
>> 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?
>
> The errata system is slated for a pretty extensive overhaul as part of
> the fallout from the upcoming format changes.  I suggest leaving the
> Style Guide guidance as is for now, noting that it will change
> significantly in the next 12-24 months.

-1. This is new text. Either don't have it at all, or get it right now.

>>     [BCP14]    Bradner, S., "Key words for use in RFCs to Indicate
>>                Requirement Levels", BCP 14, RFC 2119, March 1997,
>>                <http://www.rfc-editor.org/info/bcp14>.
>>
>> Why is there a URI in here?
>
> Where we do have known, stable URIs, such as for RFCs and associated
> subseries, we are including the URI in the reference.

You are not consistent with this right now. Either do it for all RFCs or 
don't. Also, it then should be part of the style guide for RFC 
references, not introduced silently.

Also, I don't think pointing readers at the info page does them a favor 
right now, as the thing they likely want to see is the actual document, 
not the metadata about it.


>>     [FYI90]    Malkin, G. and J. Reynolds, "FYI on FYI: Introduction to
>>                the FYI Notes", FYI Notes, RFC 1150, March 1990.
>>
>>                Housley, R., "Conclusion of FYI RFC Sub-Series", RFC 6360,
>>                August 2011.
>>
>>                <http://www.rfc-editor.org/info/fyi90>
>>
>> Another format xml2rfc can't easily produce...
>
> Yes, but the code can change and the editors can add the URI when necessary.

The point being: if the style guide requires a format that xml2rfc 
currently can't generate then you ought to bring that up as a feature 
request.

> ...

Best regards, Julian


More information about the rfc-interest mailing list