[rfc-i] feedback on draft-iab-styleguide-01
Heather Flanagan (RFC Series Editor)
rse at rfc-editor.org
Mon Mar 24 10:55:09 PDT 2014
On 3/24/14, 10:20 AM, Julian Reschke wrote:
> 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
>> 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
>>> 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).
I think the two spaces are helpful in a variety of situations, but if a
particular font or format doesn't display them properly, I don't see
this as a huge problem.
> Also, it does harm in that it makes processing harder by requiring
> heuristics on the input document.
The processing already knows how to handle this though, doesn't it?
>>> 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.
>>> 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? :-)
I'm aiming for a set of compromises here. The Style Guide isn't about
what the tools can do; it should provide guidance on how to write or
configure the tools. If the Style Guide is suggesting something that is
technically impossible (or really, really hard), however, I take that
into consideration and may adjust the guidance accordingly.
>>> 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
>>> Define "dated".
>> 1: provided with a date <a dated document>
> Is this about a date *within* the URL, or as additional data in the
Date within the URI. Example:
>>> 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
>> 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
>>> is necessary:
>>> [ErrNNNN] RFC Errata, Errata ID NNNN, RFC NNNN,
>>> [Err1912] RFC Errata, Errata ID 1912, RFC 2978,
>>> 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
>>> 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
>> 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.
I argue that the new text is, while not a complete answer to what we
need to do with errata, is still an improvement over what we have today.
>>> [BCP14] Bradner, S., "Key words for use in RFCs to Indicate
>>> Requirement Levels", BCP 14, RFC 2119, March 1997,
>>> 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.
Sandy and I have made some changes on this to include the URI in the
examples in Sections 4.8.6.*.
> 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.
Sandy and I talked about this, and felt that the info page was the best
choice for two main reasons:
- in the future, we will have multiple publication formats and people
will need to be sent to a location where they can choose the one they want
- this is the best way to make sure readers know that errata and IPR are
associated with an RFC; that's not something one can see in the current
>>> [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
>>> August 2011.
>>> Another format xml2rfc can't easily produce...
>> Yes, but the code can change and the editors can add the URI when
> 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
I think you and I are mostly disagreeing on what comes first - the Style
Guide or the changes in code. Is that an accurate statement?
More information about the rfc-interest