Web Portion of the Style Guide
The following style issues have been raised with the RFC Production Center since RFC 7322, “RFC Style Guide”, has been published. These will be considered for the greater Style Guide when it is revised. Note that a revision draft is in GitHub. This page will be updated to reflect current usage.
Note that the RFC Production Center follows these guidelines but will edit and ask questions as needed.
MUSTs
The following conventions are required in RFCs. Updates will be made to text to follow these guidelines during the editing process. We appreciate compliance in submitted drafts.
Topic | Requirement |
---|---|
Referencing RFCs | The Digital Object Identifier (DOI) is now listed in each reference to an RFC. The first example in Section 4.8.6.2 of RFC 7322 is updated as follows. For one author or editor: [RFCXXXX] Last name, First initial., Ed. (if applicable), “RFC Title”, Sub-series number (if applicable), RFC number, DOI, Date of publication, <https://www.rfc-editor.org/info/rfc#>. Example: |
Referencing STDs and BCPs | This guidance overrides Section 4.8.6.3 of RFC 7322.
Internet Standards (STDs) and Best Current Practices (BCPs) may consist of a single RFC or multiple RFCs. When an STD or BCP 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. The URI to the STD or BCP info page is to be included. The text should appear as follows: See RFC 3552 [BCP72]. An STD reference should be formatted as follows: Last name, First initial., Ed. (if applicable), “RFC Title”, STD XXX, RFC number, DOI number, Date of publication, <https://www.rfc-editor.org/info/rfc#>. Example: Cerf, V., “ASCII format for network interchange”, STD 80, RFC 20, DOI 10.17487/RFC0020, October 1969, <https://www.rfc-editor.org/info/rfc20>: A BCP reference should be formatted as follows: Last name, First initial., Ed. (if applicable) and First initial. Last name, Ed. (if applicable), “RFC Title”, BCP XXX, RFC number, DOI number, Date of publication, <https://www.rfc-editor.org/info/rfc#>. |
Referencing Errata | The format for errata references described in Section 4.8.6.5 of RFC 7322 is updated as follows: [ErrNumber] RFC Errata, Erratum ID number, RFC number, <URI>. Example: For more details, see the announcement on the RFC interest list. Errata in the Reported state should not be referenced; they are not considered stable. |
Referencing IANA Registries | Use the following form to reference IANA registries. Note that the top-level URL is used when referring to a group of registries and/or specific registries within the group.
[NAME] IANA, “Registry Group or Registry Name”, <URL>. Example for a registry group: Example for a specific registry within the group: Note: This guidance was developed in coordination with IANA. |
Referencing Internet-Drafts | The format for references to Internet-Drafts described in Section 4.8.6.4 of RFC 7322 is updated to include the day of posting (in addition to the month and year), the word “Internet-Draft”, and the URL of the HTML file.
Example: |
Referencing Web-Based Public Code Repositories (e.g., GitHub) | Used for Informative References only.
Format of reference entries:
Examples: [linuxlite] “Linux Lite”, March 2018, <https://sourceforge.net/projects/linuxlite/>. |
Referencing Email on Mailing Lists | When referencing emails to mailing lists, use the following template:
[reftag] Sender, A., “Subject: Subject line”, message to the |
Index Placement | If included, an index appears directly before the Authors’ Addresses Section. |
RECOMMENDED
The following practices are recommended. Updates may be made to text to follow these guidelines during the editing process.
Topic | Recommendation |
---|---|
Inclusive Language | Because each stream has chosen to follow the IESG statement on Inclusive Language, the RFC Editor encourages authors to apply the guidance described in “Guidance for NIST Staff on Using Inclusive Language in Documentary Standards”. See Table 1 on the NIST website for an expanded list of potentially biased language along with possible substitutions. |
Double Negatives | Double negatives are discouraged. |
RFCs Citations as Compounds | Avoid forming compounds by hyphenating RFC numbers; this can be accomplished by
|
Abbreviations as Verbs | Avoid using abbreviations as verbs when possible. If unavoidable, suffixes should be affixed without punctuation, for example, “XORed” (not XOR’ed) and “NATed” (not NAT-ed). |
Expanding Abbreviations upon First Use | Once an abbreviation has been introduced, the abbreviated form should be used thereafter. |
In-text Citations (bracketed citation) | An in-text citation may a) follow the subject for which it is being cited as a silent pointer to the referenced document or b) be read as part of the text.
For example: a) As part of the transition to IPv6, NAT64 [RFC6146] and DNS64 [RFC6147] technologies will be utilized by some access networks to provide IPv4 connectivity for IPv6-only nodes [RFC6144]. or b) Note that SAVI raises a number of important privacy considerations that are discussed more fully in [RFC6959]. We recommend using a) and strongly recommend consistent use of one style throughout. |
URIs | HTTPS URIs should be used when possible. |
Author Choice
The following items are left to the authors’ discretion.
Topic | Description |
---|---|
RFC 2119 Keywords in Quoted Text | A reference is not required if the keywords are only used in quoted text. |
Terms | You may format terms as you see fit by using capitalization, quotation marks, emphasis, etc. However, consistency within the document and within the Series is strongly recommended. Please provide any style guidance to the RFC Production Center when your document enters the queue. |
Terminology Sections | Terminology sections are recommended for docs that are terminology/abbreviation heavy, but documents should point to existing definitions when possible. |
Didactic Capitalization | Use of didactic capitalization is not needed. Example: Extensible Markup Language (XML) (not EXtensible Markup Language (XML) or eXtensible Markup Language (XML)) |
Length of Sections | We suggest that the length of a section or subsection be limited to allow for easily referenced objects. |
XML Formatting
The following formatting conventions are to be followed in RFCs.
Topic | Guidance |
---|---|
Use of non-ASCII characters | Per RFC 7997, non-ASCII characters may appear within the body of the document. The <u> element is required for cases where the non-ASCII characters are needed for correct protocol operation.
This is in keeping with the following statement (where “escaping” refers to using U+ notation or otherwise defining each character) in Section 3.1 of RFC 7997: “Where the use of non-ASCII characters is purely part of an example Note that ASCII equivalents are to be used for punctuation (e.g., smart quotes and em dashes). |
Document links | There is no hard limit on the number and frequency of links in documents. However, links introduce noise for people who use screen readers, and this reduces accessibility.
How frequently terms should be linked is circumstantial depending on context and (often) the length of a section and the document. We consider the following when thinking about links:
|
Last updated 20 February 2024