Internet DRAFT - draft-iab-styleguide
draft-iab-styleguide
INTERNET-DRAFT H. Flanagan
RFC Editor
Intended Status: Informational S. Ginoza
Expires: October 11, 2014 RFC Editor
April 9, 2014
RFC Style Guide
draft-iab-styleguide-02
Abstract
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.
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@rfc-editor.org>.
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
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."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/1id-abstracts.html
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html
Copyright and License Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
Flanagan & Ginoza Expires October 11, 2014 [Page 1]
INTERNET DRAFT RFC Style Guide April 9, 2014
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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. RFC Editorial Philosophy . . . . . . . . . . . . . . . . . . . 4
3. RFC Style Conventions . . . . . . . . . . . . . . . . . . . . 5
3.1. Language . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Punctuation . . . . . . . . . . . . . . . . . . . . . . . 5
3.3. DNS Names and URIs . . . . . . . . . . . . . . . . . . . . 6
3.4. Capitalization . . . . . . . . . . . . . . . . . . . . . . 6
3.5. Citations . . . . . . . . . . . . . . . . . . . . . . . . 7
3.6. Abbreviation Rules . . . . . . . . . . . . . . . . . . . . 7
4. Structure of an RFC . . . . . . . . . . . . . . . . . . . . . 7
4.1. First-Page Header . . . . . . . . . . . . . . . . . . . . 9
4.1.1. Author/Editor . . . . . . . . . . . . . . . . . . . . 9
4.1.2. Organization . . . . . . . . . . . . . . . . . . . . . 10
4.1.3. "ISSN: 2070-1721" . . . . . . . . . . . . . . . . . . 10
4.1.4. Updates and Obsoletes . . . . . . . . . . . . . . . . 10
4.2. Full Title . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3. Abstract Section . . . . . . . . . . . . . . . . . . . . . 11
4.4. RFC Editor or Stream Notes Section . . . . . . . . . . . . 12
4.5. Status of This Memo Section . . . . . . . . . . . . . . . 12
4.6. Copyright, Licenses, and IPR Boilerplate Section . . . . . 12
4.7. Table of Contents Section . . . . . . . . . . . . . . . . 12
4.8. Body of the Memo Section . . . . . . . . . . . . . . . . . 12
4.8.1. Introduction Section . . . . . . . . . . . . . . . . . 12
4.8.2. Requirement Words Section . . . . . . . . . . . . . . 13
4.8.3. IANA Considerations Section . . . . . . . . . . . . . 13
4.8.4. Internationalization Considerations Section . . . . . 14
4.8.5. Security Considerations Section . . . . . . . . . . . 14
4.8.6. References Section . . . . . . . . . . . . . . . . . . 14
4.8.6.1. URIs in RFCs . . . . . . . . . . . . . . . . . . . 15
4.8.6.2. Referencing RFCs . . . . . . . . . . . . . . . . . 15
4.8.6.3. Referencing STDs and BCPs . . . . . . . . . . . . 16
4.8.6.4. Referencing Internet-Drafts . . . . . . . . . . . 17
4.8.6.5. Referencing Errata . . . . . . . . . . . . . . . . 18
4.8.6.6. Referencing Other Standards Development
Organizations (SDOs) . . . . . . . . . . . . . . . 18
4.9. Appendices Section . . . . . . . . . . . . . . . . . . . . 19
Flanagan & Ginoza Expires October 11, 2014 [Page 2]
INTERNET DRAFT RFC Style Guide April 9, 2014
4.10. Acknowledgments Section . . . . . . . . . . . . . . . . . 19
4.11. Contributors Section . . . . . . . . . . . . . . . . . . 19
4.12. "Author's Address" or "Authors' Addresses" Section . . . 20
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
6. Security Considerations . . . . . . . . . . . . . . . . . . . 20
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.1. Normative References . . . . . . . . . . . . . . . . . . . 21
7.2. Informative References . . . . . . . . . . . . . . . . . . 21
Appendix A. Related Procedures . . . . . . . . . . . . . . . . . 24
A.1. Dispute Resolution . . . . . . . . . . . . . . . . . . . . 24
A.2. Returning an I-D to the Document Stream . . . . . . . . . 24
A.3. Revising This Document and Associated Web Pages . . . . . 24
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 24
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25
Flanagan & Ginoza Expires October 11, 2014 [Page 3]
INTERNET DRAFT RFC Style Guide April 9, 2014
1. Introduction
The ultimate goal of the RFC publication process is to produce
documents that are readable, clear, consistent, and reasonably
uniform. The basic format 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) 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 [StyleWeb]. These 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. This
document presents these exceptions as applied or recommended by the
RFC Editor.
All RFCs begin as Internet-Drafts, 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.
2. RFC Editorial Philosophy
Authors may find it helpful to understand the RFC Editor's goals
during the publication process, namely:
- Prepare the document according to RFC style and format.
- Make the document as clear, consistent, and readable as possible.
- Correct larger content/clarity issues; flag any unclear passages
for author review.
- Fix inconsistencies (e.g., terms that appear in various forms,
text that appears multiple times, or inconsistent
capitalization).
Flanagan & Ginoza Expires October 11, 2014 [Page 4]
INTERNET DRAFT RFC Style Guide April 9, 2014
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 often 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 a document is submitted to the RFC Editor that proves to be
uneditable due to consistently unclear and poorly written text, the
document may be returned to the stream for revision. See more
details in Appendix A.2.
3. RFC Style Conventions
This Style guide does not use RFC 2119 terminology. Terms such as
lowercase "must" and "should" refer to guidance that the RFC Editor
will either apply automatically ("must") or query the authors if the
authors have not followed that guidance ("should").
3.1. Language
The RFC publication language is English. This may be either American
or British as long as an individual document is internally
consistent. Where both American and British English are used within
a document or cluster of documents, the text will be modified to be
consistent with American English.
3.2. Punctuation
Flanagan & Ginoza Expires October 11, 2014 [Page 5]
INTERNET DRAFT RFC Style Guide April 9, 2014
* No overstriking (or underlining) is allowed.
* When a sentence ended by a period is immediately followed by
another sentence, there must be two blank spaces after the period.
* A comma is used before the last item of a series, e.g.,
"TCP service is reliable, ordered, and full-duplex"
* When quoting literal text, punctuation is placed outside quotation
marks, e.g.,
'Search for the string "Error Found"'.
When quoting general text, such as general text from another RFC,
punctuation may be included within the quotation marks, e.g.,
RFC 4844 indicates that "RFCs are available free of charge to
anyone via the Internet."
Quotes are not necessary when block quotes are used.
3.3. DNS Names and URIs
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" [RFC2606], to avoid accidental
conflicts.
Angle brackets are strongly recommended around URIs [STD66], e.g.,
<http://example.com/>
3.4. Capitalization
* Capitalization must be consistent within the document and ideally
should be consistent with related RFCs. Refer to the online
"Table of decisions on consistent usage of terms in RFCs" [PUB-
PROCESS].
* Per CMOS guidelines, the major words in RFC titles and section
titles should be capitalized (this is sometimes called "title
case"). Typically, all words in a title will be capitalized,
except for internal articles, prepositions, and conjunctions.
Flanagan & Ginoza Expires October 11, 2014 [Page 6]
INTERNET DRAFT RFC Style Guide April 9, 2014
* Section titles that are in sentence form will follow typical
sentence capitalization.
* Titles of figures may be in sentence form or use title case.
3.5. Citations
* References and citations must match. That is, there must be a
reference for each citation used, and vice versa.
* Citations must be enclosed in square brackets, e.g., "[CITE1]".
* A citation/reference tag must not contain spaces or hyphens.
Example: "[RFC2119]", not "[RFC 2119]".
However, the proper textual naming of an RFC contains a space.
Example: "See RFC 2119 [BCP14] for more information."
* Cross-references within the body of the text and to other RFCs
must use section numbers rather than page numbers, as pagination
may change per format and device.
3.6. Abbreviation Rules
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 abbreviations that are so common that the readership of RFCs can
be expected to recognize them 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, Work Group (WG)
chairs, and/or Area Directors (ADs). Note that some abbreviations
have multiple expansions. Additionally, this list includes some
terms that look like abbreviations but are actually fixed names
for things, and hence cannot and should not be expanded. These
are noted as "No expansion".
4. Structure of an RFC
A published RFC will contain the elements in the following list.
Flanagan & Ginoza Expires October 11, 2014 [Page 7]
INTERNET DRAFT RFC Style Guide April 9, 2014
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.
Flanagan & Ginoza Expires October 11, 2014 [Page 8]
INTERNET DRAFT RFC Style Guide April 9, 2014
First-page header * [Required]
Title [Required]
Abstract [Required]
RFC Editor or Stream 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]
Within the body of the memo, the order shown above is strongly
recommended. Exceptions will 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).
4.1. First-Page Header
Headers will follow the format as described in "RFC Streams, Headers,
and Boilerplates" [RFC5741] and its successors. In addition, the
following conventions will apply.
4.1.1. Author/Editor
The determination of who should be listed as an author or editor on
an RFC is made by the stream.
Flanagan & Ginoza Expires October 11, 2014 [Page 9]
INTERNET DRAFT RFC Style Guide April 9, 2014
The author's name (initials 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 but the
author should be consistent once they've selected a name format.
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 sections. There must be a direct
correlation of authors and editors in the header and Author's Address
section. These are the individuals that must sign off on the
document during the AUTH48 process and respond to inquiries, such as
errata.
4.1.2. Organization
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.
4.1.3. "ISSN: 2070-1721"
The RFC Series has been assigned an International Standard Serial
Number of 2070-1721 [ISO3297]. It will be included by the RFC
Editor.
4.1.4. Updates and Obsoletes
When an RFC obsoletes or updates a previously published RFC or RFCs,
this information is in the header. For example:
"Updates: nnnn" or "Updates: nnnn, ..., nnnn"
"Obsoletes: nnnn" or "Obsoletes: nnnn, ... , nnnn"
Flanagan & Ginoza Expires October 11, 2014 [Page 10]
INTERNET DRAFT RFC Style Guide April 9, 2014
If the document updates or obsoletes more than one document, numbers
will be listed in ascending order.
4.2. Full Title
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 or acronyms in a title must generally be expanded when
first encountered (see Section 3.5 for additional guidance on
acronyms).
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 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.
4.3. Abstract Section
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.
Flanagan & Ginoza Expires October 11, 2014 [Page 11]
INTERNET DRAFT RFC Style Guide April 9, 2014
4.4. RFC Editor or Stream Notes Section
At times, the stream approving body may approve 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.
4.5. Status of This Memo Section
The RFC Editor will supply an appropriate "Status of This Memo" as
defined in RFC 5741 [RFC5741].
4.6. Copyright, Licenses, and IPR Boilerplate Section
The full copyright and license notices are available on the IETF
Trust Legal Provisions Documents website [IETF-TRUST].
4.7. Table of Contents Section
A Table of Contents (TOC) is required in all RFCs. It must be
positioned after the Copyright notice and before the Introduction.
4.8. Body of the Memo Section
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.
4.8.1. Introduction Section
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-
Flanagan & Ginoza Expires October 11, 2014 [Page 12]
INTERNET DRAFT RFC Style Guide April 9, 2014
Standard Management Framework" [MIB-BOILER] text to appear as Section
1.
4.8.2. Requirement Words Section
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 text (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
retransmissions). For example, they must not be used to try to
impose a particular method on implementers where the method is
not required for interoperability.
4.8.3. IANA Considerations Section
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 document.
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.
Flanagan & Ginoza Expires October 11, 2014 [Page 13]
INTERNET DRAFT RFC Style Guide April 9, 2014
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.
The RFC Editor will remove an IANA Considerations section that says
there are no IANA considerations (although such a section is required
in the Internet-Draft preceding the RFC).
4.8.4. Internationalization Considerations Section
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.
4.8.5. Security Considerations Section
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 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.
4.8.6. References Section
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, in specific instances, 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 reason
not to do so). When referring to an obsoleted document, it is common
practice to also refer to the most recent version as well.
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.
Flanagan & Ginoza Expires October 11, 2014 [Page 14]
INTERNET DRAFT RFC Style Guide April 9, 2014
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. When both normative and informative
references exist, the references section should be split into two
subsections:
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.
4.8.6.1. URIs in RFCs
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.
4.8.6.2. Referencing RFCs
The following format is required for citing RFCs. Note the ordering
for multiple authors: the last author listed is treated differently
than the already listed authors.
Flanagan & Ginoza Expires October 11, 2014 [Page 15]
INTERNET DRAFT RFC Style Guide April 9, 2014
For 1 Author or Editor:
[RFCXXXX] Last name, First initial., Ed. (if applicable),
"RFC Title", BCP/FYI/STD ## (if applicable),
RFC ####, Date of Publication.
<http://www.rfc-editor.org/info/rfc####>
Example:
[RFC3080] Rose, M., "The Blocks Extensible Exchange
Protocol Core", RFC 3080, March 2001.
<http://www.rfc-editor.org/info/rfc3080>
For 2 Authors or Editors:
[RFCXXXX] Last name, First initial., Ed. (if applicable)
and First initial. Last name, Ed. (if appropriate),
"RFC Title", BCP/FYI/STD ## (if applicable),
RFC ####, 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)", RFC 6323, July 2011.
<http://www.rfc-editor.org/info/rfc6323>
For 3 or more Authors or Editors:
[RFCXXXX] Last name, First initial., Ed. (if applicable),
Last name, First initial., Ed. (if appropriate)
and First initial. Last name, Ed. (if appropriate),
"RFC Title", BCP/FYI/STD ## (if applicable),
RFC ####, 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", RFC 6429, December 2011.
<http://www.rfc-editor.org/info/rfc6429>
4.8.6.3. Referencing STDs and BCPs
Standards (STDs) and Best Current Practices (BCPs) may consist of a
single RFC or multiple RFCs. When an STD or BCP that contains
Flanagan & Ginoza Expires October 11, 2014 [Page 16]
INTERNET DRAFT RFC Style Guide April 9, 2014
multiple RFCs is referenced, the reference entry should include ALL
of the RFCs comprising that subseries. The authors should refer to
specific RFC numbers as part of the text (not as citations) and cite
the subseries number. Inclusion of the URI to the STD or BCP info
page is now 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", BCP/FYI/STD ##, RFC ####, Date of
Publication.
<http://www.rfc-editor.org/info/std####>
Example:
[STD72] Gellens, R. and J. Klensin, "Message Submission
for Mail", STD 72, RFC 6409, 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", BCP/FYI/STD ##, RFC ####, Date of
Publication.
Last name, First initial., Ed. (if applicable)
and First initial. Last name, Ed. (if applicable)
"RFC Title", BCP/FYI/STD ##, RFC ####, Date of
Publication.
<http://www.rfc-editor.org/info/std###>
Example:
[STD13] Mockapetris, P., "Domain names - concepts and
facilities", STD 13, RFC 1034, November 1987.
Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, November 1987.
<http://www.rfc-editor.org/info/std13>
4.8.6.4. Referencing Internet-Drafts
Flanagan & Ginoza Expires October 11, 2014 [Page 17]
INTERNET DRAFT RFC Style Guide April 9, 2014
References to Internet-Drafts can 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 publication date
(month and year), the full Internet-Draft file name (including the
version number), and the use of the phrase "Work in Progress". If
the I-D referenced has a version published as an RFC, references must
also include the RFC. Authors may reference multiple versions of an
I-D.
[SYMBOLIC-TAG] Last name, First initial. 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,
August 2013.
4.8.6.5. Referencing Errata
The following format is required when a reference to an erratum
report is necessary:
[ErrNNNN] RFC Errata, Erratum ID NNNN, RFC MMMM.
[Err1912] RFC Errata, Erratum ID 1912, RFC 2978.
4.8.6.6. Referencing Other Standards Development Organizations (SDOs)
The following format is suggested when referencing a document or
standard from another SDO in which authors are listed:
[SYMBOLIC-TAG]
Last name, First initial. and First initial. Last name,
"Document Title", Document reference number, date of
publication, <URI if available>.
[W3C.REC-xml11]
Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E.,
Yergeau, F., and J. Cowan, "Extensible Markup Language
(XML) 1.1 (Second Edition)", W3C Recommendation
REC-xml11-20060816, August 2006, <http://www.w3.org/TR/
2006/REC-xml11-20060816>.
Note that the list of authors is ordered as on the actual document
Flanagan & Ginoza Expires October 11, 2014 [Page 18]
INTERNET DRAFT RFC Style Guide April 9, 2014
and 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>.
4.9. Appendices Section
The RFC Editor recommends placing references before the Appendices.
Appendices should be labeled as "Appendix A. Appendix A Title",
"A.1. Appendix A.1 Title", "Appendix B. Appendix B Title", etc.
4.10. Acknowledgments 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.
4.11. Contributors Section
This optional section acknowledges those who have made significant
contributions to the document.
In a similar fashion to the Author 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
on an RFC is made by the stream.
The Contributors section may include brief statements about the
nature of particular contributions ("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. Any
contact information should be formatted similar to how the
Flanagan & Ginoza Expires October 11, 2014 [Page 19]
INTERNET DRAFT RFC Style Guide April 9, 2014
information is formatted in the Author's Address section.
4.12. "Author's Address" or "Authors' Addresses" 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 [ISO3166]. The purpose of this section is to (1)
unambiguously define author identity (e.g., the John Smith who works
for FooBar Systems) and to (2) provide contact information for future
readers who have questions or comments.
The practice of munged 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.
5. IANA Considerations
No IANA actions required.
6. Security Considerations
No security considerations.
Flanagan & Ginoza Expires October 11, 2014 [Page 20]
INTERNET DRAFT RFC Style Guide April 9, 2014
7. References
7.1. Normative References
[STYLE-WEB] RFC Editor, "Web Portion of the Style Guide",
<http://www.rfc-editor.org/rfc-style-guide/part2.html>.
7.2. Informative References
[ABBR] RFC Editor Abbreviations List,
<http://www.rfc-editor.org/rfc-style-guide/
abbrev.expansion.txt>.
[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>.
[BCP18] Alvestrand, H., "IETF Policy on Character Sets and
Languages", BCP 18, RFC 2277, January 1998,
<http://www.rfc-editor.org/info/bcp18>.
[BCP26] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008, <http://www.rfc-editor.org/info/bcp26>.
[BCP72] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
Text on Security Considerations", BCP 72, RFC 3552, July
2003, <http://www.rfc-editor.org/info/bcp72>.
[CLUSTER] RFC Editor, "Clusters in the RFC Editor Queue",
<http://www.rfc-editor.org/cluster_def.html>
[CMOS] Chicago Manual of Style, 16th ed. Chicago: University of
Chicago Press, 2010.
[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>
[ID-GUIDE] IETF, "Guidelines to Authors of Internet Drafts",
<http://www.ietf.org/ietf-ftp/1id-guidelines.txt>.
[IETF-TRUST]
IETF Trust, "Trust Legal Provisions (TLP) Documents",
Flanagan & Ginoza Expires October 11, 2014 [Page 21]
INTERNET DRAFT RFC Style Guide April 9, 2014
<http://trustee.ietf.org/license-info/>.
[ISO_OBP] ISO, "Online Browsing Platform",
<https://www.iso.org/obp/ui/>.
[ISO3297] Technical Committee ISO/TC 46, Information and
documentation, Subcommittee SC 9, Identification and
description, "Information and documentation -
International standard serial number (ISSN)", September
2007.
[MIB-BOILER]
IETF OPS Area, "Boilerplate for IETF MIB Documents",
<http://www.ops.ietf.org/mib-boilerplate.html>.
[MIB-SEC] IETF OPS Area, "Security Guidelines for IETF MIB
Modules",
<http://trac.tools.ietf.org/area/ops/trac/wiki/mib-
security>
[PUB-PROCESS]
RFC Editor, "Publication Process",
<http://www.rfc-editor.org/pubprocess.html>.
[RFC1311] Postel, J., "Introduction to the STD Notes", RFC 1311,
March 1992, http://www.rfc-editor.org/info/rfc1311
[RFC1818] Postel, J., Li, T., and Y. Rekhter, "Best Current
Practices", RFC 1818, August 1995,
<http://www.rfc-editor.org/info/rfc1818>.
[RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors",
RFC 2223, October 1997, <http://www.rfc-
editor.org/info/rfc2223>.
[RFC2606] Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS
Names", BCP 32, RFC 2606, June 1999,
<http://www.rfc-editor.org/info/rfc2606>.
[RFC4844] Daigle, L., Ed., and Internet Architecture Board, "The RFC
Series and RFC Editor", RFC 4844, July 2007,
<http://www.rfc-editor.org/info/rfc4844>.
[RFC5741] Daigle, L., Ed., and Kolkman, O., Ed., and IAB, "RFC
Streams, Headers, and Boilerplates", RFC 5741, December
2009, <http://www.rfc-editor.org/info/rfc4844>.
Flanagan & Ginoza Expires October 11, 2014 [Page 22]
INTERNET DRAFT RFC Style Guide April 9, 2014
[RFC6635] Kolkman, O., Ed., Halpern, J., Ed., and IAB, "RFC Editor
Model (Version 2)", RFC 6635, June 2012,
<http://www.rfc-editor.org/info/rfc6635>.
[STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.
[YANG-SEC] IETF OPS Area, "yang module security considerations",
<http://trac.tools.ietf.org/area/ops/trac/wiki/yang-
security-guidelines>
Flanagan & Ginoza Expires October 11, 2014 [Page 23]
INTERNET DRAFT RFC Style Guide April 9, 2014
Appendix A. Related Procedures
The following procedures are related to the application and updating
of the RFC Style Guide.
A.1. Dispute Resolution
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.
A.2. Returning an I-D to the Document Stream
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.
A.3. Revising This Document and Associated Web Pages
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 the 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.
Acknowledgements
Flanagan & Ginoza Expires October 11, 2014 [Page 24]
INTERNET DRAFT RFC Style Guide April 9, 2014
This document refers heavily to RFC 2223 [RFC2223] and draft-rfc-
editor-rfc2223bis-08; as such, we are grateful to the authors of
those documents for their time and effort in to the RFC Series.
Robert T. Braden
USC Information Sciences Institute
Joyce Reynolds
Jon Postel
Contributors
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
Flanagan & Ginoza Expires October 11, 2014 [Page 25]
