| Network Working Group | H. Flanagan |
| Internet-Draft | S. Ginoza |
| Intended status: Informational | RFC Editor |
| Expires: September 11, 2017 | March 10, 2017 |
RFC Style Guide
draft-flanagan-7322bis-00
This document describes the fundamental and unique style conventions and editorial policies currently in use for the RFC Series. It captures the RFC Editor's basic requirements and offers guidance regarding the style and structure of an RFC. Additional guidance is captured on a website that reflects the experimental nature of that guidance and prepares it for future inclusion in the RFC Style Guide. This document obsoletes RFC 7322, "RFC Style Guide".
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on September 11, 2017.
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The ultimate goal of the RFC publication process is to produce documents that are readable, clear, consistent, and reasonably uniform. The basic formatting conventions for RFCs were established in the 1970s by the original RFC Editor, Jon Postel. This document describes the fundamental and unique style conventions and editorial policies currently in use for the RFC Series [RFC4844]. It is intended as a stable, infrequently updated reference for authors, editors, and reviewers.
The RFC Editor also maintains a web portion of the Style Guide (see Appendix A.3) that describes issues as they are raised and indicates how the RFC Editor intends to address them. As new style issues arise, the RFC Editor will first address them on the web portion of the Style Guide [STYLE-WEB]. These topics may become part of the RFC Style Guide when it is revised.
The world of technical publishing has generally accepted rules for grammar, punctuation, capitalization, sentence length and complexity, parallelism, etc. The RFC Editor generally follows these accepted rules as defined by the Chicago Manual of Style (CMOS) [CMOS], with a few important exceptions to avoid ambiguity in complex technical prose and to handle mixtures of text and computer languages, or to preserve historical formatting rules. This document presents these exceptions as applied or recommended by the RFC Editor.
All RFCs begin as Internet-Drafts (also referred to as I-Ds), and a well-written and properly constructed Internet-Draft [ID-GUIDE] provides a strong basis for a good RFC. The RFC Editor accepts Internet-Drafts from specified streams for publication [RFC4844] and applies the rules and guidelines for the RFC Series during the editorial process.
Authors may find it helpful to understand the RFC Editor's goals during the publication process, namely to:
We strive for consistency within:
a. the document,
b. a cluster of documents [CLUSTER], and
c. the series of RFCs on the subject matter.
The editorial process of the RFC Editor is not an additional technical review of the document. Where the RFC Editor may suggest changes in wording for clarity and readability, it is up to the author, working group, or stream-approving body to determine whether the changes have an impact on the technical meaning of the document [RFC4844]. If the original wording is a more accurate representation of the technical content being described in the document, it takes precedence over editorial conventions.
The activity of editing sometimes creates a tension between author and editor. The RFC Editor attempts to minimize this conflict for RFC publication while continually striving to produce a uniformly excellent document series. The RFC Editor refers to this fundamental tension as "editorial balance,"" and maintaining this balance is a continuing concern for the RFC Editor. There is a prime directive that must rule over grammatical conventions: do not change the intended meaning of the text.
If the RFC Editor cannot edit a document without serious risk of altering the meaning, it may be returned to the stream-approving body for review. See Appendix A.2 for more information.
This Style Guide does not use terminology as defined in RFC 2119 [BCP14]. In this document, lowercase use of "must" and "should" indicates changes the RFC Editor will make automatically to conform with this Style Guide versus those that may be questioned if not applied. The lowercase "must" indicates those changes that will be applied automatically and are not at the discretion of the authors. The lowercase "should" indicates the RFC Editor's recommended use, but conformance with the recommendations is not required; the RFC Editor may question whether the guidance may be applied.
The RFC publication language is English. Spelling may be either American or British, as long as an individual document is internally consistent. Where both American and British English spelling are used within a document or cluster of documents, the text will be modified to be consistent with American English spelling.
DNS names, whether or not in URIs, that are used as generic examples in RFCs should use the particular examples defined in "Reserved Top Level DNS Names" [BCP32], to avoid accidental conflicts.
Angle brackets are strongly recommended around URIs [STD66], e.g.,
<http://example.com/ >
The use of HTTPS rather than HTTP is strongly encouraged.
or
We recommend using a) and strongly recommend consistent use of one style throughout.
Abbreviations should be expanded in document titles and upon first use in the document. The full expansion of the text should be followed by the abbreviation itself in parentheses. The exception is an abbreviation that is so common that the readership of RFCs can be expected to recognize it immediately; examples include (but are not limited to) TCP, IP, SNMP, and HTTP. The online list of abbreviations [ABBR] provides guidance. Some cases are marginal, and the RFC Editor will make the final judgment, weighing obscurity against complexity.
Note: The online list of abbreviations is not exhaustive or definitive. It is a list of abbreviations appearing in RFCs and sometimes reflects discussions with authors, Working Group Chairs, and/or Area Directors (ADs). Note that some abbreviations have multiple expansions. Additionally, this list includes some terms that look like abbreviations but that are actually fixed names for things and hence cannot and should not be expanded. These are noted as "No Expansion".
Whenever possible:
If use of an RFC number in attributive position is unavoidable, the preferred form should appear as in the example “RFC 5011-style rollover”. That is:
The goal of having images within an RFC is to convey information. A good diagram or image expresses information quickly, clearly, and with low chance of misunderstanding. Technically correct but confusing images get in the way of understanding and implementation.
A published RFC will largely contain the elements in the following list. Some of these sections are required, as noted. Those sections marked with "*" will be supplied by the RFC Editor during the editorial process when necessary. Sections are allowed to contain nothing but subsections. The rules for each of these elements are described in more detail below.
Within the body of the memo, the order shown above is strongly recommended. Exceptions may be questioned. Outside the body of the memo, the order above is required. The section numbers above are for illustrative purposes; they are not intended to correspond to required numbering in an RFC.
The elements preceding the body of the memo should not be numbered. Typically, the body of the memo will have numbered sections and the appendices will be labeled with letters. Any sections that appear after the appendices should not be numbered or labeled (e.g., see "Contributors" above).
Headers will follow the format described in "RFC Streams, Headers, and Boilerplates" [RFC5741] and its successors. In addition, the following conventions will apply.
The determination of who should be listed as an author or editor on an RFC is made by the stream.
The author's name (initial followed by family name) appears on the first line of the heading. Some variation, such as additional initials or capitalization of family name, is acceptable. Once the author has selected how their name should appear, they should use that display consistently in all of their documents.
The total number of authors or editors on the first page is generally limited to five individuals and their affiliations. If there is a request for more than five authors, the stream-approving body needs to consider if one or two editors should have primary responsibility for this document, with the other individuals listed in the Contributors or Acknowledgements section. There must be a direct correlation of authors and editors in the document header and the Authors' Addresses section. These are the individuals that must sign off on the document during the AUTH48 process and respond to inquiries, such as errata.
The author's organization is indicated on the line following the author's name.
For multiple authors, each author name appears on its own line, followed by that author's organization. When more than one author is affiliated with the same organization, the organization can be "factored out," appearing only once following the corresponding Author lines. However, such factoring is inappropriate when it would force an unacceptable reordering of author names.
If an author cannot or will not provide an affiliation for any reason, "Independent", "Individual Contributor", "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.
The RFC Series has been assigned an International Standard Serial Number of 2070-1721 [ISO3297]. It will be included by the RFC Editor.
When an RFC obsoletes or updates a previously published RFC or RFCs, this information is included in the document header. For example:
"Updates: nnnn" or "Updates: nnnn, ..., nnnn"
"Obsoletes: nnnn" or "Obsoletes: nnnn, ..., nnnn"
If the document updates or obsoletes more than one document, numbers will be listed in ascending order.
The title must be centered below the rest of the heading, preceded by two blank lines and followed by one blank line.
Choosing a good title for an RFC can be a challenge. A good title should fairly represent the scope and purpose of the document without being either too general or too specific and lengthy.
Abbreviations in a title must generally be expanded when first encountered (see Section 3.6 for additional guidance on abbreviations).
It is often helpful to follow the expansion with the parenthesized abbreviation, as in the following example:
Encoding Rules for the
Common Routing Encapsulation Extension Protocol (CREEP)
The RFC Editor recommends that documents describing a particular company's private protocol should bear a title of the form "Foo's ... Protocol" (where Foo is a company name), to clearly differentiate it from a protocol of more general applicability.
Every RFC must have an Abstract that provides a concise and comprehensive overview of the purpose and contents of the entire document, to give a technically knowledgeable reader a general overview of the function of the document.
Composing a useful Abstract generally requires thought and care. Usually, an Abstract should begin with a phrase like "This memo ..." or "This document ..." A satisfactory Abstract can often be constructed in part from material within the Introduction section, but an effective Abstract may be shorter, less detailed, and perhaps broader in scope than the Introduction. Simply copying and pasting the first few paragraphs of the Introduction is allowed, but it may result in an Abstract that is both incomplete and redundant. Note also that an Abstract is not a substitute for an Introduction; the RFC should be self-contained as if there were no Abstract.
Similarly, the Abstract should be complete in itself. It will appear in isolation in publication announcements and in the online index of RFCs. Therefore, the Abstract must not contain citations.
A stream-approving body may approve the inclusion of an editorial note to explain anything unusual about the process that led to the document's publication or to note a correction. In this case, a stream note section will contain such a note.
Additionally, an RFC Editor Note section may contain a note inserted by the RFC Editor to highlight special circumstances surrounding an RFC.
The RFC Editor will supply an appropriate "Status of This Memo" as defined in RFC 5741 [RFC5741] and "Format for RFCs in the IAB Stream" [IAB-FORM].
The full copyright and license notices are available on the IETF Trust Legal Provisions documents website [IETF-TRUST].
A Table of Contents (TOC) is required in all RFCs. It must be positioned after the Copyright Notice and before the Introduction.
Following the TOC is the body of the memo.
Each RFC must include an Introduction section that (among other things) explains the motivation for the RFC and (if appropriate) describes the applicability of the document, e.g., whether it specifies a protocol, provides a discussion of some problem, is simply of interest to the Internet community, or provides a status report on some activity. The body of the memo and the Abstract must be self-contained and separable. This may result in some duplication of text between the Abstract and the Introduction; this is acceptable.
The Introduction section should always be the first section following the TOC (except in the case of MIB module documents). While "Introduction" is recommended, authors may choose alternate titles such as "Overview" or "Background". These alternates are acceptable.
For MIB module documents, common practice has been for "The Internet-Standard Management Framework" [MIB-BOILER] text to appear as Section 1.
Some documents use certain capitalized words ("MUST", "SHOULD", etc.) to specify precise requirement levels for technical features. RFC 2119 [BCP14] defines a default interpretation of these capitalized words in IETF documents. If this interpretation is used, RFC 2119 must be cited (as specified in RFC 2119) and included as a normative reference. Otherwise, the correct interpretation must be specified in the document.
This section must appear as part of the body of the memo (as defined by this document). It must appear as part of, or subsequent to, the Introduction section.
These words are considered part of the technical content of the document and are intended to provide guidance to implementers about specific technical features, generally governed by considerations of interoperability. RFC 2119 says:
Imperatives of the type defined in this memo must be used with care and sparingly. In particular, they MUST only be used where it is actually required for interoperation or to limit behavior which has potential for causing harm (e.g., limiting retransmisssions) For example, they must not be used to try to impose a particular method on implementers where the method is not required for interoperability.
For guidance on how to register IANA-related values or create new registries to be managed by IANA, see "Guidelines for Writing an IANA Considerations Section in RFCs" [BCP26].
The RFC Editor will update text accordingly after the IANA assignments have been made. It is helpful for authors to clearly identify where text should be updated to reflect the newly assigned values. For example, the use of "TBD1", "TBD2", etc., is recommended in the IANA Considerations section and in the body of the memo.
If the authors have provided values to be assigned by IANA, the RFC Editor will verify that the values inserted by the authors match those that have actually been registered on the IANA site. When writing a given value, consistent use of decimal or hexadecimal is recommended.
If any of the IANA-related information is not clear, the RFC Editor will work with IANA to send queries to the authors to ensure that assignments and values are properly inserted.
All RFCs that deal with internationalization issues should have a section describing those issues; see "IETF Policy on Character Sets and Languages" [BCP18], Section 6, for more information.
All RFCs must contain a section that discusses the security considerations relevant to the specification; see "Guidelines for Writing RFC Text on Security Considerations" [BCP72] for more information.
Note that additional boilerplate material for RFCs containing MIB and YANG modules also exists. See "Security Guidelines for IETF MIB Modules" [MIB-SEC] and "yang module security considerations" [YANG-SEC] for details.
The reference list is solely for recording reference entries. Introductory text is not allowed.
The RFC style allows the use of any of a variety of reference styles, as long as they are used consistently within a document. However, where necessary, some reference styles have been described for use within the Series. See the examples in this document.
The RFC Editor ensures that references to other RFCs refer to the most current RFC available on that topic (unless provided with a reason not to do so). When referring to an obsoleted document, it is common practice to also refer to the most recent version.
A reference to an RFC that has been assigned an STD [RFC1311], BCP [RFC1818], or FYI [FYI90] sub-series number must include the sub-series number of the document. Note that the FYI series was ended by RFC 6360. RFCs that were published with an FYI sub-series number and still maintain the FYI number must include the sub-series number in the reference.
Reference lists must indicate whether each reference is normative or informative, where normative references are essential to implementing or understanding the content of the RFC and informative references provide additional information. More information about normative and informative references may be found in the IESG's statement "Normative and Informative References" [REFS]. When both normative and informative references exist, the references section should be split into two subsections:
Templates are available on the RFC Editor website for the XML format of certain references [REFEXAMPLE].
s. References
s.1. Normative References
xxx
...
xxx
s.2. Informative References
xxx
...
xxx
References will generally appear in alphanumeric order by citation tag. Where there are only normative or informative references, no subsection is required; the top-level section should say "Normative References" or "Informative References".
Normative references to Internet-Drafts will cause publication of the RFC to be suspended until the referenced draft is also ready for publication; the RFC Editor will then update the entry to refer to the RFC and publish both documents simultaneously.
The use of URIs in references is acceptable, as long as the URI is the most stable (i.e., unlikely to change and expected to be continuously available) and direct reference possible. The URI will be verified as valid during the RFC editorial process.
If a dated URI (one that includes a timestamp for the page) is available for a referenced web page, its use is required.
Note that URIs may not be the sole information provided for a reference entry.
The use of HTTPS rather than HTTP is strongly encouraged.
The following format is required for referencing RFCs. The Stream abbreviation should be used; when no stream is available, as with legacy RFCs, this may be left blank.
Note the ordering for multiple authors: the format of the name of the last author listed is different than that of all previous authors in the list.
For one author or editor:
[RFCXXXX] Last name, First initial., Ed. (if applicable), "RFC Title", Stream, Sub-series number (if applicable), RFC number, DOI, Date of publication, http://www.rfc-editor.org/info/rfc#.
Example:
[RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core," IETF, RFC 3080, DOI 10.17487/RFC3080, March 2001, http://www.rfc-editor.org/info/rfc3080.
For two authors or editors:
[RFCXXXX] Last name, First initial., Ed. (if applicable) and First initial. Last name, Ed. (if applicable), "RFC Title", Stream, Sub-series number (if applicable), RFC number, DOI, Date of publication, http://www.rfc-editor.org/info/rfc#.
Example:
[RFC6323] Renker, G. and G. Fairhurst, "Sender RTT Estimate Option for the Datagram Congestion Control Protocol (DCCP)", IETF, RFC 6323, DOI 10.17487/RFC6323, July 2011, http://www.rfc-editor.org/info/rfc6323.
For three or more authors or editors:
[RFCXXXX] Last name, First initial., Ed. (if applicable), Last name, First initial., Ed. (if applicable), and First initial. Last name, Ed. (if applicable), "RFC Title", Stream, Sub-series number (if applicable), RFC number, DOI, Date of publication, http://www.rfc-editor.org/info/rfc#.
Example:
[RFC6429] Bashyam, M., Jethanandani, M., and A. Ramaiah, "TCP Sender Clarification for Persist Condition", IETF, RFC 6429, DOI 10.17487/RFC6429, December 2011, http://www.rfc-editor.org/info/rfc6429.
Internet 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 sub-series. The authors should refer to specific RFC numbers as part of the text (not as citations) and cite the sub-series number. Inclusion of the URI to the STD or BCP info page (see Section 3.2.3 of [RFC5741]) is recommended. The text should appear as follows:
See RFC 1034 [STD13].
For an STD or BCP that contains one RFC:
[STDXXX] Last name, First initial., Ed. (if applicable), "RFC Title", Stream, Sub-series number, RFC number, DOI, Date of publication, http://www.rfc-editor.org/info/std#.
Example:
[STD72] Gellens, R. and J. Klensin, "Message Submission for Mail", IETF, STD 72, RFC 6409, DOI 10.17487/RFC6409, November 2011, http://www.rfc-editor.org/info/std72.
For an STD or BCP that contains two or more RFCs:
[STDXXX] Last name, First initial., Ed. (if applicable), "RFC Title", Stream, Sub-series number, RFC number, DOI, Date of publication.
Last name, First initial., Ed. (if applicable)
and First initial. Last name, Ed. (if applicable),
"RFC Title", Stream, Sub-series number, RFC number, DOI,
Date of publication.
<http://www.rfc-editor.org/info/std#>
Example:
[STD13] Mockapetris, P., "Domain names - concepts and facilities", STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987.
Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
November 1987.
<http://www.rfc-editor.org/info/std13>
References to Internet-Drafts may 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 posting date (month and year), the full Internet-Draft file name (including the version number), and the phrase "Work in Progress". Authors may reference multiple versions of an I-D. If the referenced I-D was also later published as an RFC, then that RFC must also be listed.
[SYMBOLIC-TAG] Last name, First initial., Ed. (if applicable) and First initial. Last name, Ed. (if applicable), "I-D Title", Work in Progress, draft-string-NN, Month Year.
Example:
[RFC-STYLE] Flanagan, H. and S. Ginoza, "RFC Style Guide", Work in Progress, draft-flanagan-style-01, June 2013.
The following format is required when a reference to an erratum report is necessary:
[ErrNumber] RFC Errata, Erratum ID number, RFC number, <URI>.
[Err1912] RFC Errata, Erratum ID 1912, RFC 2978, xxx.
The following format is suggested when referencing a document or standard from another SDO in which authors are listed:
[SYMBOLIC-TAG]
[W3C.REC-xml11]
The order of authors in the list is the same as the order shown on the actual document and that the common, abbreviated form of the SDO is used.
Alternatively, when no list of authors is available, the following format is recommended:
[SYMBOLIC-TAG] Organization, "Document Title", Document
reference number, Date of publication,
<URI if available>.
Example:
[IEEE802.1Q] IEEE, "Local and Metropolitan Area
Networks -- Media Access Control (MAC)
Bridges and Virtual Bridged Local Area
Networks", IEEE Std 802.1Q-2011, August 2011,
<http://standards.ieee.org/findstds/standard/
802.1Q-2011.html>
Per the IEEE coordination team, listing dates for IEEE standards is not recommended unless there is a need to cite a particular section, in which case the dated reference is appropriate. An RFC with a dated IEEE reference suggests that the RFC only applies to that specific IEEE specification.
When referencing emails to mailing lists, the template provided here should be used:
The RFC Editor recommends placing references before the Appendices. Appendices should be labeled as "Appendix A. Title", "A.1. Title", "Appendix B. Title", etc.
If included, an index appears directly after any appendices and before the Acknowledgements (if any). Where applicable, it appears before the “IAB Members at the Time of Approval” section.
This optional section may be used instead of, or in addition to, a Contributors section. It is often used by authors to publicly thank those who have provided feedback regarding a document and to note any documents from which text was borrowed.
This optional section acknowledges those who have made significant contributions to the document.
In a similar fashion to the Author�s Address section, the RFC Editor does not make the determination as to who should be listed as a contributor to an RFC. The determination of who should be listed as a contributor is made by the stream.
The Contributors section may include brief statements about the nature of particular contributions (e.g., "Sam contributed Section 3"), and it may also include affiliations of listed contributors. At the discretion of the author(s), contact addresses may also be included in the Contributors section, for those contributors whose knowledge makes them useful future contacts for information about the RFC. The format of any contact information should be similar to the format of information in the Author�s Address section.
This required section gives contact information for the author(s) listed in the first-page header.
Contact information must include a long-lived email address and optionally may include a postal address and/or telephone number. If the postal address is included, it should include the country name, using the English short name listed by the ISO 3166 Maintenance Agency [ISO_OBP]. The purpose of this section is to (1) unambiguously define author identity (e.g., the John Smith who works for FooBar Systems) and (2) provide contact information for future readers who have questions or comments.
The practice of munged email addresses (i.e., altering an email address to make it less readable to bots and web crawlers to avoid spam) is not appropriate in an archival document series. Author contact information is provided so that readers can easily contact the author with questions and/or comments. Address munging is not allowed in RFCs.
This document has no security considerations.
This document has no IANA considerations.
| [STYLE-WEB] | RFC Editor, "Web Portion of the Style Guide" |
The following procedures are related to the application and updating of the RFC Style Guide.
There are competing rationales for some of the rules described in this Guide, and the RFC Editor has selected the ones that work best for the Series. However, at times, an author may have a disagreement with the RFC Production Center (RPC) over the application of Style Guide conventions. In such cases, the authors should discuss their concerns with the RPC. If no agreement can be reached between the RPC and the authors, the RFC Series Editor will, with input from the appropriate stream-approving body, make a final determination. If further resolution is required, the dispute resolution process as described in the RFC Editor Model [RFC6635] will be followed.
For a given document, if the RFC Editor determines that it cannot be edited without serious risk of altering the meaning of the technical content or if the RFC Editor does not have the resources to provide the level of editing it needs, it may be sent back to the stream- approving body with a request to improve the clarity, consistency, and/or readability of the document. This is not to be considered a dispute with the author.
The RFC Series is continually evolving as a document series. This document focuses on the fundamental and stable requirements that must be met by an RFC. From time to time, the RFC Editor may offer less formal recommendations that authors may apply at their discretion; these recommendations may be found on the RFC Editor website "Guidelines for RFC Style" [STYLE-WEB].
When a new recommendation is made regarding the overall structure and formatting of RFCs, it will be published on that page and accepted for a period of time before the RFC Editor determines whether it should become part of the fundamental requirements in the RFC Style Guide or remain as a less formal recommendation. That period of time will vary, in part depending on the frequency with which authors encounter and apply the guidance.
Alice Russo RFC Production Center
Authors' Addresses
Heather Flanagan RFC Series Editor
EMail: rse@rfc-editor.org
Sandy Ginoza RFC Production Center
EMail: rfc-editor@rfc-editor.org