[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
>>> 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).

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.
>>>        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? :-)

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.

OK.

>
>> ...
>>>     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?

Date within the URI.  Example:

http://en.wikipedia.org/wiki/Request_for_Comments
vs.
http://en.wikipedia.org/w/index.php?title=Request_for_Comments&oldid=594755345

>
>> ...
>>> 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.

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,
>>>                <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.

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
canonical format.

>
>
>>>     [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.

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?

-Heather


More information about the rfc-interest mailing list