[Docs] [txt|pdf] [Tracker] [Email] [Nits]

Versions: 00 01 02 03 draft-iab-styleguide

INTERNET-DRAFT                                               H. Flanagan
Intended Status: Informational                                 S. Ginoza
Expires: May 2, 2013                                          RFC Editor
                                                        October 29, 2012


                            RFC Style Guide
                        draft-flanagan-style-00

Abstract

   This document is a comprehensive 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) 2012 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



Flanagan & Ginoza         Expires May 2, 2012                   [Page 1]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


   (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 . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  RFC Editorial Philosophy . . . . . . . . . . . . . . . . . . .  3
   3.  RFC Style Conventions  . . . . . . . . . . . . . . . . . . . .  4
     3.1. Language  . . . . . . . . . . . . . . . . . . . . . . . . .  4
     3.2.  Punctuation  . . . . . . . . . . . . . . . . . . . . . . .  4
     3.3.  Capitalization . . . . . . . . . . . . . . . . . . . . . .  5
     3.4.  Citations  . . . . . . . . . . . . . . . . . . . . . . . .  6
     3.5.  Abbreviation Rules . . . . . . . . . . . . . . . . . . . .  6
     3.6.  Protocol Data Definitions  . . . . . . . . . . . . . . . .  6
     3.7.  Use of Definite Articles . . . . . . . . . . . . . . . . .  7
   4.  Structure of an RFC Document . . . . . . . . . . . . . . . . .  7
     4.1.  First-Page Header  . . . . . . . . . . . . . . . . . . . .  8
       4.1.1.  Updates and Obsoletes  . . . . . . . . . . . . . . . . 10
     4.2.  Full Title . . . . . . . . . . . . . . . . . . . . . . . . 11
     4.3.  Abstract . . . . . . . . . . . . . . . . . . . . . . . . . 11
     4.4.  RFC Editor or Stream Manager Notes . . . . . . . . . . . . 12
     4.5.  Status of This Memo  . . . . . . . . . . . . . . . . . . . 12
     4.6.  Copyright, Licenses, and IPR Boilerplate . . . . . . . . . 12
     4.7.  Table of Contents  . . . . . . . . . . . . . . . . . . . . 12
     4.8.  Body of the Memo . . . . . . . . . . . . . . . . . . . . . 12
     4.9.  "Author's Address" Section . . . . . . . . . . . . . . . . 18
     4.10.  Running Headers and Footers . . . . . . . . . . . . . . . 18
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 19
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 19
   Appendix A.  Related Procedures  . . . . . . . . . . . . . . . . . 19
     A.1. Dispute Resolution  . . . . . . . . . . . . . . . . . . . . 19
     A.2. Returning an I-D to the Stream Manager  . . . . . . . . . . 19
     A.3. Revising This Document and Associated Web Pages . . . . . . 20
   References . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
   Informative References . . . . . . . . . . . . . . . . . . . . . . 20
   Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 22
   Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 23








Flanagan & Ginoza         Expires May 2, 2012                   [Page 2]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


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 are met
   before publication. For example, an RFC must have correctly formatted
   headers and footers, it must have the necessary boilerplate, and it
   must generally have the "appearance" of previous RFCs in the series.
   Where there is more flexibility, 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.  More recently, it has been found necessary to
   formalize and document the RFC style rules and give guidelines to
   authors.

   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 certain Internet-Drafts for
   publication [RFC5741] and during the publication process applies the
   rules and guidelines for the RFC document series.


2.  RFC Editorial Philosophy

   Authors may find it helpful to understand the RFC Editor's goals
   during the publication process, namely:




Flanagan & Ginoza         Expires May 2, 2012                   [Page 3]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


   -  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 publication 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 such as the ISE, IESG, IRTF
   Chair, or IAB Chair to determine if that has 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.


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

3.2.  Punctuation




Flanagan & Ginoza         Expires May 2, 2012                   [Page 4]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


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

         "Memos in the Requests for Comments (RFC) document series
         contain technical and organizational notes about the Internet."

   *  Angle brackets are allowed around URIs [RFC3986], e.g.,

         <http://example.com/>.

   However, URIs must not be used in place of proper references.

   *  The author's choice on hyphenation of compound words (e.g., "on-
         line" vs. "online") 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

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

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



Flanagan & Ginoza         Expires May 2, 2012                   [Page 5]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


      "and", "of").  Typically, all words in a title will be
      capitalized, except for internal articles, prepositions, and
      conjunctions.

   *  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 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 in the Abstract
   and upon first use in the body of the document.  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
      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



Flanagan & Ginoza         Expires May 2, 2012                   [Page 6]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


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

   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


3.7.  Use of Definite Articles

   The definite article "the" should precede a protocol name when
   written out and used as a noun, but omitted when written as an
   acronym and used as a noun.

   Correct:

            The Transmission Control Protocol is ...
            The Transmission Control Protocol (TCP) is ...
            TCP is ...

   Incorrect:

            Transmission Control Protocol is ...
            Transmission Control Protocol (TCP) is ...
            The TCP is ...

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



Flanagan & Ginoza         Expires May 2, 2012                   [Page 7]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


   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.

      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 for docs with
                                                    10+ pgs]
      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]
        Appendix A.
        Appendix B.
      References
      Acknowledgments
      Contributors
      Author's Address                         [Required]

   Within the body of the memo, the order shown above is strongly
   recommended.  Exceptions may be made by request of the authors and
   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 body of the memo will normally have numbered sections; appendices
   may be numbered or labeled.  However, if the author chooses to label
   appendices, subsequent sections should not be numbered.  The elements
   preceding and following the body of the memo should be unnumbered.

4.1.  First-Page Header

   The first page contains no running header.  The top of the first page
   has the following items left-justified:

   Stream

      Identifies the stream in which the document originated and appears
      on the first line [RFC5741].  Currently, it will be one of the



Flanagan & Ginoza         Expires May 2, 2012                   [Page 8]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


      following:

      IETF
      IRTF
      IAB
      Independent Submission

   "Request for Comments: nnnn"

      Identifies this as an RFC and specifies the RFC number on the
      second line.  The actual number is assigned and filled in just
      prior to publication by the RFC Editor.

   "BCP: nn" or
   "STD: nn"

      One of these optional items indicates the sub-series number, if
      the RFC is a member of a sub-series [RFC1818] [RFC1311].

   "Category: xxxxxxxxxxxx"

      Required field specifying the category of this RFC.  The category
      may be one of: "Standards Track", "Best Current Practice",
      "Informational", "Experimental", or "Historic".  The category is
      determined by the stream manager and rules in [RFC2026] and
      [RFC5741].

   The following information appears right-justified in the header:

   Author/Editor

      [To be removed upon publication] This section still under
      considerable discussion.

      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.

      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



Flanagan & Ginoza         Expires May 2, 2012                   [Page 9]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


      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.

   Date

      The month and year of RFC publication appear on the line after the
      last organization.

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

   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.




Flanagan & Ginoza         Expires May 2, 2012                  [Page 10]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


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



Flanagan & Ginoza         Expires May 2, 2012                  [Page 11]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


   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.

   Abbreviations appearing in the Abstract should generally be expanded
   in parentheses, with the exceptions noted above (see Section 3.4).
   When in doubt, expand an abbreviation (refer to the online list of
   abbreviations [ABBR] for guidance).

4.4.  RFC Editor or Stream Manager Notes

   The RFC Editor or a stream manager such as the ISE, IESG, IRTF Chair,
   or IAB 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 RFCs longer than 10 pages
   and recommended for all RFCs.  It must be positioned after the
   Abstract and before the Introduction section.

   The TOC itself should not be too long or detailed, or it loses value.
    For example, if many successive TOC entries point to the same pages
   of the memo, the TOC granularity probably needs to be coarser.

4.8.  Body of the Memo




Flanagan & Ginoza         Expires May 2, 2012                  [Page 12]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


   Following the Table of Contents, if any, comes 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.

   o  Introduction

      The Introduction section should always be the first section
      following the Table of Contents (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.

      Avoid abuse of requirement-level words.  They 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



Flanagan & Ginoza         Expires May 2, 2012                  [Page 13]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


         not required for interoperability.

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



Flanagan & Ginoza         Expires May 2, 2012                  [Page 14]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


      non-RFC documents, authors often position Appendices at the very
      end, after the references.  However, RFCs that have large and
      dense technical Appendix sections make it difficult for a reader
      to find references that precede the Appendices.  In such cases,
      putting the references later is advisable.


   o  References

      [To be removed upon publication] This section is still under
      considerable discussion.

      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



Flanagan & Ginoza         Expires May 2, 2012                  [Page 15]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


      References will generally appear in alphanumeric order by citation
      tag.

      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



Flanagan & Ginoza         Expires May 2, 2012                  [Page 16]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


                         Estimate Option for the Datagram Congestion
                         Control Protocol (DCCP)", RFC 6323, July 2011.

         For 3 Authors or More:

            [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 exact
         publication date, the full Internet-Draft file name, 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", Work in
                        Progress, draft-flanagan-style-02, 01 March
                        2012.

      Referencing Errata

         The following format is recommended 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.




Flanagan & Ginoza         Expires May 2, 2012                  [Page 17]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


   o  Contributors Section

      This optional section lists those contributors who deserve
      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/Editor 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/contributor 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




Flanagan & Ginoza         Expires May 2, 2012                  [Page 18]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


      RFCs always include running headers and footers (except that the
      first page has no running header).  These are generally extracted
      from 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 [RFC6635]
   will be followed.

A.2. Returning an I-D to the Stream Manager




Flanagan & Ginoza         Expires May 2, 2012                  [Page 19]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


   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
   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., Korver, B., and Internet Architecture Board,
              "Guidelines for Writing RFC Text on Security
              Considerations", BCP 72, RFC 3552, July 2003.




Flanagan & Ginoza         Expires May 2, 2012                  [Page 20]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


   [BCP78]    Bradner, S. and J. Contreras, Ed., "Rights Contributors
              Provide to the IETF Trust", BCP 78, RFC 5378, 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 (need full citation)

   [FYI90]    Malkin, G. and J. Reynolds, "F.Y.I. on F.Y.I. --
              Introduction to the F.Y.I. Notes", FYI 1, 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]  Need full citation

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

   [RFC791]   Postel, J., "Internet Protocol", RFC 791, September 1981.

   [RFC1311]  Postel, J., "Introduction to the STD Notes", RFC 1311,



Flanagan & Ginoza         Expires May 2, 2012                  [Page 21]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


              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]  T. Berners-Lee, and R. Fielding, L. Masinter, "Uniform
              Resource Identifier (URI): Generic Syntax", RFC 3986,
              January 2005.

   [RFC4844]  Daigle, L., Ed., "The RFC Series and RFC Editor:, RFC
              4844, July 2007.

   [RFC5741]  Daigle, L. and O. Kolkman, Ed., and Internet Architecture
              Board, "RFC Streams, Headers, and Boilerplates", RFC 5741,
              December 2009.

   [RFC6635]

   [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]  http://www.rfc-
              editor.org/rse/wiki/doku.php?id=styleweb

   [WEBSTERS] Merriam-Webster Online, <http://www.m-w.com/>.


Acknowledgements

   This document refers heavily to RFC 2223 and RFC 2223bis, and as such
   we are grateful to the authors of that document for their time and
   effort in to the RFC Series.




Flanagan & Ginoza         Expires May 2, 2012                  [Page 22]


INTERNET DRAFT              RFC Style Guide             October 29, 2012


   Robert T. Braden

   USC Information Sciences Institute

   Joyce Reynolds

Contributors

   Alice Hagens
   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 May 2, 2012                  [Page 23]


Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/