INTERNET-DRAFT H. Flanagan
Intended Status: Informational S. Ginoza
Expires: December 22, 2013 RFC Editor
June 20, 2013
RFC Style Guide
draft-flanagan-style-01
Abstract
This document is a summary of the style conventions and editorial
policies that apply to the RFC document series. It captures the RFC
Editor's fundamental requirements and offers guidance regarding the
format and structure of an RFC. While in Internet-Draft format, it
should be considered for discussion purposes only. Guidance in from
this document will not be applied until published as an RFC. Please
send your comments 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) 2013 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
Flanagan & Ginoza Expires December 22, 2013 [Page 1]
INTERNET DRAFT RFC Style Guide June 20, 2013
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 . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. RFC Editorial Philosophy . . . . . . . . . . . . . . . . . . . 3
3. RFC Style Conventions . . . . . . . . . . . . . . . . . . . . 4
3.1. Language . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Punctuation . . . . . . . . . . . . . . . . . . . . . . . 5
3.3. Capitalization . . . . . . . . . . . . . . . . . . . . . . 5
3.4. Citations . . . . . . . . . . . . . . . . . . . . . . . . 6
3.5. Abbreviation Rules . . . . . . . . . . . . . . . . . . . . 6
3.6. Protocol Data Definitions . . . . . . . . . . . . . . . . 7
4. Structure of an RFC Document . . . . . . . . . . . . . . . . . 7
4.1. First-Page Header . . . . . . . . . . . . . . . . . . . . 8
4.2. Full Title . . . . . . . . . . . . . . . . . . . . . . . . 10
4.3. Abstract . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.4. RFC Editor or Stream Manager Notes . . . . . . . . . . . . 11
4.5. Status of This Memo . . . . . . . . . . . . . . . . . . . 11
4.6. Copyright, Licenses, and IPR Boilerplate . . . . . . . . . 11
4.7. Table of Contents . . . . . . . . . . . . . . . . . . . . 11
4.8. Body of the Memo . . . . . . . . . . . . . . . . . . . . . 11
4.9. "Author's Address" Section . . . . . . . . . . . . . . . . 17
4.10. Running Headers and Footers . . . . . . . . . . . . . . . 17
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18
6. Security Considerations . . . . . . . . . . . . . . . . . . . 18
Appendix A. Related Procedures . . . . . . . . . . . . . . . . . 18
A.1. Dispute Resolution . . . . . . . . . . . . . . . . . . . . 18
A.2. Returning an I-D to the Stream Manager . . . . . . . . . . 18
A.3. Revising This Document and Associated Web Pages . . . . . . 19
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Informative References . . . . . . . . . . . . . . . . . . . . . . 19
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 21
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22
Flanagan & Ginoza Expires December 22, 2013 [Page 2]
INTERNET DRAFT RFC Style Guide June 20, 2013
1. Introduction
The ultimate goal of the RFC publication process is to produce
documents that are readable, clear, consistent, and reasonably
uniform. This document describes the fundamental and unique style
conventions and editorial policies for the RFC document series
[RFC4844]. It is intended as a stable, infrequently-updated
reference for authors, editors, and reviewers. The RFC Editor also
maintains a more fluid document providing guidelines about
conventions and policies that are not as fundamental to the RFC
document series, that are less stable, or that change more frequently
[StyleWebDRAFT]; see Appendix A for more details.
Style rules referred to in this document are considered fundamental
to the RFC series; the RFC Editor will work to ensure these rules are
met before publication. For example, an RFC must be correctly
formatted, it must have the necessary boilerplate, and it must
generally have the "appearance" of previous RFCs in the series.
Where there is more flexibility in the application of the RFC Style
Guide, that information will be recorded on the RFC Editor website.
The basic format conventions for RFCs were established in the 1970s
by the original RFC Editor, Jon Postel [Postel] [RFC2555]. Postel's
instructions to authors were quite simple: read a recent RFC and
emulate its style. However, it has been found necessary to formalize
and document the RFC style rules and provide more guidance to authors
in order to maintain the consistency and readability of the
documents in the Series.
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 where they are required.
All RFCs begin as an Internet-Draft, and a well-written and properly
constructed Internet-Draft [IDGuide] 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:
Flanagan & Ginoza Expires December 22, 2013 [Page 3]
INTERNET DRAFT RFC Style Guide June 20, 2013
- Prepare the document to RFC style and format.
- Make the document as clear, consistent, and readable as possible.
- Look for larger content/clarity issues; flag any unclear passages
for author review.
- Point out inconsistencies (e.g., terms that appear in various
forms, text that appears multiple times, or inconsistent
capitalization).
We strive for consistency within:
a. the document,
b. a set of documents, 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 manager (e.g., the ISE, IESG, IRSG,
or IAB Chair) to determine if the changes have an impact on the
technical meaning in the document. If the original wording is a more
accurate representation of the technical content being described in
the document, it takes precedence over editorial conventions.
In the world at large, 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. We refer
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 will be returned to the stream for revision.
3. RFC Style Conventions
3.1. Language
* The RFC publication language is English. This may be either
American or British as long as an individual document is
Flanagan & Ginoza Expires December 22, 2013 [Page 4]
INTERNET DRAFT RFC Style Guide June 20, 2013
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
* No overstriking (or underlining) is allowed.
* When a sentence ended by a period is immediately followed by
another sentence, there should 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.
* Angle brackets are required around URIs [RFC3986], e.g.,
<http://example.com/>.
Note that URIs must not be used in place of proper references.
* The author's choice on hyphenation of compound words (e.g.,
"multi-tier" vs. "multitier") is generally followed, as long as it
is consistent and the word does not appear in the dictionary
[WEBSTERS] unhyphenated. The usage must be consistent within the
document.
Do not use hyphenation at the right margin to split existing
words. However, hyphenated word sequences (e.g., "Internet-
Draft") may be split at the hyphen across successive lines.
3.3. Capitalization
Flanagan & Ginoza Expires December 22, 2013 [Page 5]
INTERNET DRAFT RFC Style Guide June 20, 2013
* Capitalization must be consistent within the document and
should be consistent with related RFCs. Refer to the online
"Table of decisions on consistent usage of terms in RFCs"
[PubProcess].
* Per CMOS guidelines, the major words in RFC titles and section
titles should be capitalized (this is sometimes called "title
case"). Minor words such as articles or prepositions should be
lower-cased (e.g., "and", "of"). Typically, all words in a title
will be capitalized, except for internal articles, prepositions,
and conjunctions.
* 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.4. 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 ("[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."
3.5. Abbreviation Rules
Abbreviations must be expanded in document titles and upon first use
in the body of the document, which includes the Abstract. 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 FTP. 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
Flanagan & Ginoza Expires December 22, 2013 [Page 6]
INTERNET DRAFT RFC Style Guide June 20, 2013
sometimes reflects discussions with authors, WG chairs, and/or
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".
3.6. Protocol Data Definitions
The RFC series adopted a diagrammatic approach to representing data
structures such as protocol headers. Furthermore, the research
community adopted the "big-endian" [IEN137] convention, in which the
bits and bytes are shown in network byte order, byte zero is the
first byte shown, and bit zero is the most significant bit in a word
or a field. This is also known as "network byte order". Protocol
definitions should be displayed in this format.
For example, RFC 791 [RFC791] contains the following definition of
the IP header format.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|Version| IHL |Type of Service| Total Length |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Identification |Flags| Fragment Offset |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Time to Live | Protocol | Header Checksum |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Source Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Destination Address |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Options | Padding |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Example Internet Datagram Header
4. Structure of an RFC Document
A published RFC will 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. The rules for each of these elements are
described in more detail below.
Flanagan & Ginoza Expires December 22, 2013 [Page 7]
INTERNET DRAFT RFC Style Guide June 20, 2013
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. Security Considerations [Required]
9. 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 may be made with the approval of the stream
manager. 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:
Author/Editor
The determination of who should be listed as an author or editor
on an RFC is dependent on Stream policy. The RFC Editor provides
guidelines for number and format of the author-related components
of an RFC.
Flanagan & Ginoza Expires December 22, 2013 [Page 8]
INTERNET DRAFT RFC Style Guide June 20, 2013
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 as long
as the author maintains a consistent name format for all RFCs.
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 manager
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 header
and Authors' Address section. These are the individuals that must
sign off on the document during the AUTH48 process and respond to
inquiries, such as errata.
Organization
The author's organization, 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", "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.
"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.
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 December 22, 2013 [Page 9]
INTERNET DRAFT RFC Style Guide June 20, 2013
If the document updates or obsoletes more than one document,
numbers will be listed in ascending order.
Authors often also include a statement in the Introduction that
reads similarly to the following:
This document obsoletes RFC XXXX.
This helps clarify the status of the document and its relation to the
RFC it has updated or obsoleted.
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.4).
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 title may be subject to policy considerations in addition to
the requirement that it provide a concise and technically sound
summary of the document contents. For example, at various times in
the history of the IETF, the word "Policies" as well as the phrase
"The Directory" were banned from RFC titles, for various reasons.
An RFC 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
Every RFC must have an Abstract of a maximum of 20 lines.
The Abstract should provide 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
Flanagan & Ginoza Expires December 22, 2013 [Page 10]
INTERNET DRAFT RFC Style Guide June 20, 2013
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.
4.4. RFC Editor or Stream Manager Notes
The RFC Editor or a stream manager may request that an editorial note
be added to an RFC. A note is generally added to explain anything
unusual about the process that led to the document's publication or
to note a correction.
Additionally, the RFC Editor may choose to include a note to
highlight special circumstances surrounding an RFC.
4.5. Status of This Memo
The RFC Editor will supply an appropriate "Status of This Memo"
section as defined in RFC 5741 [RFC5741].
4.6. Copyright, Licenses, and IPR Boilerplate
The full copyright and license notices are available on the IETF
Trust Legal Provisions Documents website. [IETFTrust]
4.7. Table of Contents
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
Following the TOC is the body of the memo.
Flanagan & Ginoza Expires December 22, 2013 [Page 11]
INTERNET DRAFT RFC Style Guide June 20, 2013
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.
o Introduction
The Introduction section should always be the first section
following the TOC (except in the case of MIB module documents).
While we recommend "Introduction", authors sometimes choose
alternate titles such as "Overview" or "Background".
For MIB module documents, common practice has been for "The
Internet-Standard Management Framework" [MIBboiler] text to appear
as Section 1.
o Requirement Words (RFC 2119)
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.
Flanagan & Ginoza Expires December 22, 2013 [Page 12]
INTERNET DRAFT RFC Style Guide June 20, 2013
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.
To forestall confusion between uppercase conformance terms and
their lowercase equivalents, some authors use words and phrases
such as "mandatory", "ought to", and "might" instead of "MUST",
"SHOULD", and "MAY".
o 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, we recommend the use of "TBD1",
"TBD2", etc., 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.
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).
o Security Considerations Section
All RFCs must contain a section that discusses the security
considerations relevant to the specification; see [BCP72] for more
information.
o Appendices
Many RFC documents have Appendices, which may be extensive. We
recommend placing references after the Appendices.
Flanagan & Ginoza Expires December 22, 2013 [Page 13]
INTERNET DRAFT RFC Style Guide June 20, 2013
o References
[This sentence to be removed upon publication] This section is
still under considerable discussion.
The reference list is solely for recording reference entries.
Introductory text is strongly discouraged.
The RFC style uses one of the many variants on reference styles.
See the examples in this document, and note the ordering for
multiple authors: the last author listed is treated differently
when referencing RFCs and I-Ds.
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). It is acceptable for an obsoleted document
to be listed as long as the most recent document is referenced
also.
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: 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. For
example, the reference section might 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.
Flanagan & Ginoza Expires December 22, 2013 [Page 14]
INTERNET DRAFT RFC Style Guide June 20, 2013
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 replace the reference by
an RFC reference and publish both documents simultaneously.
URLs and DNS Names in RFCs
The use of URLs in references is acceptable as long as the URL
is the most stable and direct reference possible. The URL will
be verified as valid during the RFC editorial process.
Personal web pages are not considered stable and will not be
accepted as a reference.
DNS names, whether or not in URLs, that are used as generic
examples in RFCs should use the particular examples defined in
RFC 2606 [RFC2606], "Reserved Top-Level DNS Names", to avoid
accidental conflicts.
If a dated URL is available for a referenced webpage, its use
is required.
Referencing RFCs
The following format is required for citing RFCs.
For 1 Author:
[RFCXXXX] Last name, First initial., "RFC Title",
BCP/FYI/STD ## (if applicable), RFC ####,
Date of Publication.
Example:
[RFC3080] Rose, M., "The Blocks Extensible Exchange
Protocol Core", RFC 3080, March 2001.
For 2 Authors:
[RFCXXXX] Last name, First initial. and First initial,
Last name, "RFC Title", BCP/FYI/STD ##
(if applicable), RFC ####, Date of Publication.
Example:
[RFC6323] Renker, G. and G. Fairhurst, "Sender RTT
Estimate Option for the Datagram Congestion
Control Protocol (DCCP)", RFC 6323, July 2011.
Flanagan & Ginoza Expires December 22, 2013 [Page 15]
INTERNET DRAFT RFC Style Guide June 20, 2013
For 3 or more Authors:
[RFCXXXX] Last name, First initial., Last name, First
initial., and First initial. Last name, "RFC
Title", BCP/FYI/STD ## (if applicable),
RFC ####, Date of Publicaiton.
Example:
[RFC6429] Bashyam, M., Jethanandani, M., and A. Ramaiah,
"TCP Sender Clarification for Persist
Condition", RFC 6429, December 2011.
Referencing Internet-Drafts
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 the phrase
"Work in Progress". If the I-D referenced has a version
published as an RFC, references must also include the RFC.
Example:
[RFC-STYLE] Flanagan, H., "RFC Style Guide",
draft-flanagan-style-01 (work in progress), June
2013.
Referencing Errata
The following format is required when a reference to an errata
report is necessary:
[Err1912] RFC Errata, Errata ID 1912, RFC 2978,
<http://www.rfc-editor.org>.
o 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.
o Contributors Section
This optional section lists those contributors who deserve
Flanagan & Ginoza Expires December 22, 2013 [Page 16]
INTERNET DRAFT RFC Style Guide June 20, 2013
significant credit for the document. When a long author list is
represented by a subset in the document header, the displaced
authors can be properly and fully acknowledged in the Contributors
section.
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 determined by stream policy.
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 information is formatted in the Author's Address section.
4.9. "Author's Address" Section
This required section gives contact information for the author(s)
listed in the first-page header.
Contact information must include at least one, and ideally would
include all, of a postal address including the ISO 3166 country
code, a telephone number, and a long-lived email address
[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. Note that some professional
societies offer long-lived email addresses for their members. Use
of these long-lived addresses is recommended.
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. The practice of address
munging makes it more difficult to contact the authors of a
document and has not proven advantageous in deterring spam.
Therefore, address munging is not allowed in RFCs.
4.10. Running Headers and Footers
[This section to be removed when new formats are tested.] RFCs
always include running headers and footers (except that the first
page has no running header). These are generally extracted from
Flanagan & Ginoza Expires December 22, 2013 [Page 17]
INTERNET DRAFT RFC Style Guide June 20, 2013
the standard header for the stream.
o Running Headers
The running header in one line (on page 2 and all subsequent
pages) has the RFC number on the left (RFC nnnn), the title
(possibly an abbreviated title) in the center, and the publication
date (Month Year) on the right.
o Running Footers
All pages contain a one-line running footer, with the author's
last name on the left, the category centered, and the page number
on the right as "[Page nn]".
If there is one author, the author's last name appears as "name".
If there are two authors, the form "name & name" may be used; for
more than two authors, use the form "name, et al."
The headers and footers must be separated from the body by at
least one and preferably two blank lines.
5. IANA Considerations
No IANA actions required
6. Security Considerations
No security considerations.
Appendix A. Related Procedures
The following procedures are related to the application and updating
of the RFC Style Guide.
A.1. Dispute Resolution
At times, an author may have a disagreement with the RFC Editor over
the application of the style guide conventions. In such a case, the
RFC Series Editor will, with input from the appropriate stream
manager, 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 Stream Manager
For a given document, if the RFC Editor determines that it cannot be
edited without serious risk of altering the meaning of the technical
Flanagan & Ginoza Expires December 22, 2013 [Page 18]
INTERNET DRAFT RFC Style Guide June 20, 2013
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
manager 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" [StyleWebDRAFT].
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.
References
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.
[BCP26] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[BCP72] Rescorla, E. and B. Korver, "Guidelines for Writing RFC
Text on Security Considerations", BCP 72, RFC 3552, July
2003.
[BCP78] Bradner, S., Ed., and J. Contreras, Ed., "Rights
Contributors Provide to the IETF Trust", BCP 78, RFC 5378,
Flanagan & Ginoza Expires December 22, 2013 [Page 19]
INTERNET DRAFT RFC Style Guide June 20, 2013
November 2008.
[BCP79] Bradner, S., Ed., "Intellectual Property Rights in IETF
Technology", BCP 79, RFC 3979, March 2005.
Narten, T., "Clarification of the Third Party Disclosure
Procedure in RFC 3979", BCP 79, RFC 4879, April 2007.
[CMOS] Chicago Manual of Style, v.16. 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.
[PubProcess]
RFC Editor, "Publication Process", <http://www.rfc-
editor.org/pubprocess.html>.
[IDGuide] IETF, "Guidelines to Authors of Internet Drafts".
Available as 1id-guidelines.txt at <http://www.ietf.org>.
[IEN137] Cohen, D. "On Holy Wars and a Plea for Peace", Internet
Experimental Note (IEN) 137, 1 April 2980. A longer
version is published in IEEE Computer Magazine, pp 47-55,
October 1981.
[IETFTrust] IETF Trust, "Trust Legal Provisions (TLP) Documents",
<http://trustee.ietf.org/license-info/>.
[ISO3166] ISO, "Country Codes - ISO 3166",
<http://www.iso.org/iso/country_codes>.
[ISO3297] Technical Committee ISO/TC 46, Information and
documentation, Subcommittee SC 9, Identification and
description., "Information and documentation -
International standard serial number (ISSN)", 09 2007.
[POLICY] RFC Editor, "RFC Editorial Guidelines and Procedures",
<http://www.rfc-editor.org/policy.html>.
[Postel] Jon Postel, original RFC Editor: see
<http://www.isoc.org/postel>.
[RFC20] Cerf, V., "ASCII format for network interchange", RFC 20,
October 1969.
Flanagan & Ginoza Expires December 22, 2013 [Page 20]
INTERNET DRAFT RFC Style Guide June 20, 2013
[RFC791] Postel, J., "Internet Protocol", RFC 791, September 1981.
[RFC1311] Postel, J., "Introduction to the STD Notes", RFC 1311,
March 1992.
[RFC1818] Postel, J., Li, T., and Y. Rekhter, "Best Current
Practices", RFC 1818, August 1995.
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision
3", BCP 9, RFC 2026, October 1996.
[RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors",
RFC 2223, October 1997.
[RFC2555] RFC Editor, et al., "30 Years of RFCs", RFC 2555, April
1999.
[RFC2606] Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS
Names", BCP 32, RFC 2606, June 1999.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005.
[RFC4844] Daigle, L., Ed., and Internet Architecture Board, "The RFC
Series and RFC Editor", RFC 4844, July 2007.
[RFC5741] Daigle, L., Ed., and Kolkman, O., Ed., and IAB, "RFC
Streams, Headers, and Boilerplates", RFC 5741, December
2009.
[RFC6635] Kolkman, O., Ed., Halpern, J., Ed., and IAB, "RFC Editor
Model (Version 2)", RFC 6635, June 2012.
[RFCcopy] RFC Editor, "COPYRIGHTS AND PATENT RIGHTS IN RFCs",
<http://www.rfc-editor.org/copyright.html>.
[MIBboiler] IETF OPS Area, "Boilerplate for IETF MIB Documents",
<http://www.ops.ietf.org/mib-boilerplate.html>.
[StyleWebDRAFT] (TBD)
[WEBSTERS] Merriam-Webster Online, <http://www.m-w.com/>.
Acknowledgements
This document refers heavily to RFC 2223 and RFC 2223bis, and as such
Flanagan & Ginoza Expires December 22, 2013 [Page 21]
INTERNET DRAFT RFC Style Guide June 20, 2013
we are grateful to the authors of that document for their time and
effort in to the RFC Series.
Robert T. Braden
USC Information Sciences Institute
Joyce Reynolds
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 December 22, 2013 [Page 22]