Internet DRAFT - draft-flanagan-style

draft-flanagan-style



 



INTERNET-DRAFT                                               H. Flanagan
                                                              RFC Editor
Intended Status: Informational                                 S. Ginoza
Expires: July 20, 2014                                        RFC Editor
                                                        January 16, 2014


                            RFC Style Guide 
                        draft-flanagan-style-03

Abstract

   This document is a summary of the style conventions and editorial
   policies that apply to the the RFC Series.  It captures the RFC
   Editor's fundamental requirements and offers guidance regarding the
   style and structure of an RFC. 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) 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
 


Flanagan & Ginoza        Expires July 20, 2014                  [Page 1]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


   (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  . . . . . . . . . . . . . . . . . . . . . . .  6
     3.3.  Capitalization . . . . . . . . . . . . . . . . . . . . . .  6
     3.4.  Citations  . . . . . . . . . . . . . . . . . . . . . . . .  7
     3.5.  Abbreviation Rules . . . . . . . . . . . . . . . . . . . .  7
   4.  Structure of an RFC  . . . . . . . . . . . . . . . . . . . . .  7
     4.1.  First-Page Header  . . . . . . . . . . . . . . . . . . . .  8
       4.1.1.  Author/Editor  . . . . . . . . . . . . . . . . . . . .  8
       4.1.2.  Organization . . . . . . . . . . . . . . . . . . . . .  9
       4.1.3.  "ISSN: 2070-1721"  . . . . . . . . . . . . . . . . . .  9
       4.1.4.  Updates and Obsoletes  . . . . . . . . . . . . . . . .  9
     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.8.1.  Introduction . . . . . . . . . . . . . . . . . . . . . 11
       4.8.2.  Requirement Words (RFC 2119) . . . . . . . . . . . . . 12
       4.8.3.  IANA Considerations Section  . . . . . . . . . . . . . 12
       4.8.4.  Security Considerations Section  . . . . . . . . . . . 13
       4.8.5.  References . . . . . . . . . . . . . . . . . . . . . . 13
         4.8.5.1.  URLs and DNS Names in RFCs . . . . . . . . . . . . 14
         4.8.5.2.  Referencing RFCs . . . . . . . . . . . . . . . . . 15
         4.8.5.3.  Referencing Internet-Drafts  . . . . . . . . . . . 15
         4.8.5.4.  Referencing Errata . . . . . . . . . . . . . . . . 16
         4.8.5.5.  Referencing Other Standards Development 
                   Organizations (SDOs) . . . . . . . . . . . . . . . 16
     4.9.  Appendices . . . . . . . . . . . . . . . . . . . . . . . . 17
     4.10.  Acknowledgments Section . . . . . . . . . . . . . . . . . 17
     4.11.  Contributors Section  . . . . . . . . . . . . . . . . . . 17
     4.12.  "Author's Address" Section  . . . . . . . . . . . . . . . 17
   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 18
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 18
 


Flanagan & Ginoza        Expires July 20, 2014                  [Page 2]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


   7.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 19
     7.1.  Normative References . . . . . . . . . . . . . . . . . . . 19
     7.2.  Informative References . . . . . . . . . . . . . . . . . . 19
   Appendix A.  Related Procedures  . . . . . . . . . . . . . . . . . 21
     A.1.  Dispute Resolution . . . . . . . . . . . . . . . . . . . . 21
     A.2.  Returning an I-D to the Stream Manager . . . . . . . . . . 21
     A.3.  Revising This Document and Associated Web Pages  . . . . . 21
   Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 21
   Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 22






































 


Flanagan & Ginoza        Expires July 20, 2014                  [Page 3]

INTERNET DRAFT              RFC Style Guide             January 16, 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 greater
   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 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: 

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

 


Flanagan & Ginoza        Expires July 20, 2014                  [Page 4]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


   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. 

   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

   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 generally follows 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. 

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. 
 


Flanagan & Ginoza        Expires July 20, 2014                  [Page 5]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


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 strongly recommended around URIs [STD66], e.g.,

         <http://example.com/>   

      Note that URIs may not be the sole information provided for a
      reference entry. 

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

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

   *  Section titles that are in sentence form will follow typical 
      sentence capitalization. 

   *  Titles of figures may be in sentence form or use title case.

 


Flanagan & Ginoza        Expires July 20, 2014                  [Page 6]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


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, 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
      should use section numbers rather than page numbers, as pagination
      may change per format and device.

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

4.  Structure of an RFC

   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 July 20, 2014                  [Page 7]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


      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  
        9.1.  Normative References
        9.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 dependent on Stream policy.  The RFC Editor provides
   guidelines for number and format of the author-related components of
   an RFC. 
 


Flanagan & Ginoza        Expires July 20, 2014                  [Page 8]

INTERNET DRAFT              RFC Style Guide             January 16, 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 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. 

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", "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 July 20, 2014                  [Page 9]

INTERNET DRAFT              RFC Style Guide             January 16, 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)

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


Flanagan & Ginoza        Expires July 20, 2014                 [Page 10]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


   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. 

   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




 


Flanagan & Ginoza        Expires July 20, 2014                 [Page 11]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


   The Introduction section should always be the first section following
   the TOC (except in the case of MIB module documents).  While
   "Introduction" is recommended, authors may choose alternate titles
   such as "Overview" or "Background".  These alternates are acceptable.

   For MIB module documents, common practice has been for "The Internet-
   Standard Management Framework" [MIBboiler] text to appear as Section
   1.

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

   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, authors are encouraged to use words and
   phrases such as "mandatory", "ought to", and "might" instead of
   "MUST", "SHOULD", and "MAY".

4.8.3.  IANA Considerations Section

 


Flanagan & Ginoza        Expires July 20, 2014                 [Page 12]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


   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.

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

4.8.5.  References

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


Flanagan & Ginoza        Expires July 20, 2014                 [Page 13]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


   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.

   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.5.1.  URLs and DNS Names in RFCs

   The use of URLs in references is acceptable as long as the URL is the
   most stable (i.e., unlikely to change and expected to be continuously
   available) and direct reference possible.  The URL will be verified
   as valid during the RFC editorial process.  Personal web pages and
   web caching services are not considered stable and will not be
   accepted as a normative reference.  Informative references to blogs
   are acceptable if they are an organizational blog and not a personal
   space.

   DNS names, whether or not in URLs, 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. 

   If a dated URL is available for a referenced web page, its use is
   required.
 


Flanagan & Ginoza        Expires July 20, 2014                 [Page 14]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


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

   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.

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

     Example:

      [RFC6429] Bashyam, M., Jethanandani, M., and A. Ramaiah, 
                "TCP Sender Clarification for Persist 
                Condition", RFC 6429, December 2011.

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


Flanagan & Ginoza        Expires July 20, 2014                 [Page 15]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


   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. 

     [SYMBOLIC-TAG]  Last name, First initial. and First 
                     initial, Last name, "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.5.4.  Referencing Errata

   The following format is required when a reference to an errata report
   is necessary:  

      [ErrNNNN]  RFC Errata, Errata ID NNNN, RFC NNNN, 
                 <http:/www.rfc-editor.org>.

      [Err1912]  RFC Errata, Errata ID 1912, RFC 2978,
                 <http://www.rfc-editor.org>.

4.8.5.5.  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:


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

   Example:
 


Flanagan & Ginoza        Expires July 20, 2014                 [Page 16]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


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

4.9.  Appendices

   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 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.12.  "Author's Address" Section

   This required section gives contact information for the author(s)
   listed in the first-page header. 

   Contact information must include a long-lived email address and
   optionally may include a postal address and/or telephone number.  If
   the postal address is included, it should include the country name
   using the English short name listed by the ISO 3166 Maintenance
   Agency [ISO3166].  The purpose of this section is to (1)
   unambiguously define author identity (e.g., the John Smith who works
 


Flanagan & Ginoza        Expires July 20, 2014                 [Page 17]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


   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 July 20, 2014                 [Page 18]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


7.  References

7.1.  Normative References

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

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

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

   [IDGuide]  IETF, "Guidelines to Authors of Internet Drafts",
              <http://www.ietf.org>.

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

   [ISO3297]  Technical Committee ISO/TC 46, Information and

 


Flanagan & Ginoza        Expires July 20, 2014                 [Page 19]

INTERNET DRAFT              RFC Style Guide             January 16, 2014


              documentation, Subcommittee SC 9, Identification and
              description, "Information and documentation -
              International standard serial number (ISSN)", 09 2007. 

   [MIBboiler] 
              IETF OPS Area, "Boilerplate for IETF MIB Documents",
              <http://www.ops.ietf.org/mib-boilerplate.html>.

   [PubProcess]
              RFC Editor, "Publication Process", 
              <http://www.rfc-editor.org/pubprocess.html>.

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

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

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






 


Flanagan & Ginoza        Expires July 20, 2014                 [Page 20]

INTERNET DRAFT              RFC Style Guide             January 16, 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 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
   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" [StyleWeb].

   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 July 20, 2014                 [Page 21]

INTERNET DRAFT              RFC Style Guide             January 16, 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 July 20, 2014                 [Page 22]