idnits 2.17.1 draft-iab-styleguide-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 9, 2014) is 3663 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'StyleWeb' is mentioned on line 129, but not defined == Missing Reference: 'Required' is mentioned on line 333, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 678, but not defined == Missing Reference: 'RFC3080' is mentioned on line 657, but not defined == Missing Reference: 'RFC6323' is mentioned on line 671, but not defined == Missing Reference: 'RFC6429' is mentioned on line 687, but not defined ** Obsolete undefined reference: RFC 6429 (Obsoleted by RFC 9293) == Missing Reference: 'STD13' is mentioned on line 732, but not defined == Missing Reference: 'STDXXX' is mentioned on line 719, but not defined == Missing Reference: 'STD72' is mentioned on line 713, but not defined == Missing Reference: 'SYMBOLIC-TAG' is mentioned on line 793, but not defined == Missing Reference: 'RFC-STYLE' is mentioned on line 757, but not defined == Missing Reference: 'ErrNNNN' is mentioned on line 766, but not defined == Missing Reference: 'Err1912' is mentioned on line 768, but not defined == Missing Reference: 'IEEE802.1Q' is mentioned on line 799, but not defined == Missing Reference: 'ISO3166' is mentioned on line 847, but not defined -- Obsolete informational reference (is this intentional?): RFC 5226 (ref. 'BCP26') (Obsoleted by RFC 8126) -- Obsolete informational reference (is this intentional?): RFC 1150 (ref. 'FYI90') (Obsoleted by RFC 6360) -- Obsolete informational reference (is this intentional?): RFC 2223 (Obsoleted by RFC 7322) -- Obsolete informational reference (is this intentional?): RFC 4844 (Obsoleted by RFC 8729) -- Duplicate reference: RFC4844, mentioned in 'RFC5741', was also mentioned in 'RFC4844'. -- Obsolete informational reference (is this intentional?): RFC 4844 (ref. 'RFC5741') (Obsoleted by RFC 8729) -- Obsolete informational reference (is this intentional?): RFC 6635 (Obsoleted by RFC 8728) Summary: 1 error (**), 0 flaws (~~), 16 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT H. Flanagan 3 RFC Editor 4 Intended Status: Informational S. Ginoza 5 Expires: October 11, 2014 RFC Editor 6 April 9, 2014 8 RFC Style Guide 9 draft-iab-styleguide-02 11 Abstract 13 This document describes the fundamental and unique style conventions 14 and editorial policies currently in use for the RFC Series. It 15 captures the RFC Editor's basic requirements and offers guidance 16 regarding the style and structure of an RFC. Additional guidance is 17 captured on a website that reflects the experimental nature of that 18 guidance and prepares it for future inclusion in the RFC Style guide. 20 Guidance provided by this document will not be applied until 21 published as an RFC. Please send your comments about the contents of 22 this document to . 24 Status of this Memo 26 This Internet-Draft is submitted to IETF in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF), its areas, and its working groups. Note that 31 other groups may also distribute working documents as 32 Internet-Drafts. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 The list of current Internet-Drafts can be accessed at 40 http://www.ietf.org/1id-abstracts.html 42 The list of Internet-Draft Shadow Directories can be accessed at 43 http://www.ietf.org/shadow.html 45 Copyright and License Notice 47 Copyright (c) 2014 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 2. RFC Editorial Philosophy . . . . . . . . . . . . . . . . . . . 4 64 3. RFC Style Conventions . . . . . . . . . . . . . . . . . . . . 5 65 3.1. Language . . . . . . . . . . . . . . . . . . . . . . . . . 5 66 3.2. Punctuation . . . . . . . . . . . . . . . . . . . . . . . 5 67 3.3. DNS Names and URIs . . . . . . . . . . . . . . . . . . . . 6 68 3.4. Capitalization . . . . . . . . . . . . . . . . . . . . . . 6 69 3.5. Citations . . . . . . . . . . . . . . . . . . . . . . . . 7 70 3.6. Abbreviation Rules . . . . . . . . . . . . . . . . . . . . 7 71 4. Structure of an RFC . . . . . . . . . . . . . . . . . . . . . 7 72 4.1. First-Page Header . . . . . . . . . . . . . . . . . . . . 9 73 4.1.1. Author/Editor . . . . . . . . . . . . . . . . . . . . 9 74 4.1.2. Organization . . . . . . . . . . . . . . . . . . . . . 10 75 4.1.3. "ISSN: 2070-1721" . . . . . . . . . . . . . . . . . . 10 76 4.1.4. Updates and Obsoletes . . . . . . . . . . . . . . . . 10 77 4.2. Full Title . . . . . . . . . . . . . . . . . . . . . . . . 11 78 4.3. Abstract Section . . . . . . . . . . . . . . . . . . . . . 11 79 4.4. RFC Editor or Stream Notes Section . . . . . . . . . . . . 12 80 4.5. Status of This Memo Section . . . . . . . . . . . . . . . 12 81 4.6. Copyright, Licenses, and IPR Boilerplate Section . . . . . 12 82 4.7. Table of Contents Section . . . . . . . . . . . . . . . . 12 83 4.8. Body of the Memo Section . . . . . . . . . . . . . . . . . 12 84 4.8.1. Introduction Section . . . . . . . . . . . . . . . . . 12 85 4.8.2. Requirement Words Section . . . . . . . . . . . . . . 13 86 4.8.3. IANA Considerations Section . . . . . . . . . . . . . 13 87 4.8.4. Internationalization Considerations Section . . . . . 14 88 4.8.5. Security Considerations Section . . . . . . . . . . . 14 89 4.8.6. References Section . . . . . . . . . . . . . . . . . . 14 90 4.8.6.1. URIs in RFCs . . . . . . . . . . . . . . . . . . . 15 91 4.8.6.2. Referencing RFCs . . . . . . . . . . . . . . . . . 15 92 4.8.6.3. Referencing STDs and BCPs . . . . . . . . . . . . 16 93 4.8.6.4. Referencing Internet-Drafts . . . . . . . . . . . 17 94 4.8.6.5. Referencing Errata . . . . . . . . . . . . . . . . 18 95 4.8.6.6. Referencing Other Standards Development 96 Organizations (SDOs) . . . . . . . . . . . . . . . 18 97 4.9. Appendices Section . . . . . . . . . . . . . . . . . . . . 19 98 4.10. Acknowledgments Section . . . . . . . . . . . . . . . . . 19 99 4.11. Contributors Section . . . . . . . . . . . . . . . . . . 19 100 4.12. "Author's Address" or "Authors' Addresses" Section . . . 20 101 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 102 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 103 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 104 7.1. Normative References . . . . . . . . . . . . . . . . . . . 21 105 7.2. Informative References . . . . . . . . . . . . . . . . . . 21 106 Appendix A. Related Procedures . . . . . . . . . . . . . . . . . 24 107 A.1. Dispute Resolution . . . . . . . . . . . . . . . . . . . . 24 108 A.2. Returning an I-D to the Document Stream . . . . . . . . . 24 109 A.3. Revising This Document and Associated Web Pages . . . . . 24 110 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . 24 111 Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 112 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 114 1. Introduction 116 The ultimate goal of the RFC publication process is to produce 117 documents that are readable, clear, consistent, and reasonably 118 uniform. The basic format conventions for RFCs were established in 119 the 1970s by the original RFC Editor, Jon Postel. This document 120 describes the fundamental and unique style conventions and editorial 121 policies currently in use for the RFC Series [RFC4844]. It is 122 intended as a stable, infrequently updated reference for authors, 123 editors, and reviewers. 125 The RFC Editor also maintains a web portion of the Style Guide (see 126 Appendix A) that describes issues as they are raised and indicates 127 how the RFC Editor intends to address them. As new style issues 128 arise, the RFC Editor will first address them on the web portion of 129 the Style Guide [StyleWeb]. These may become part of the RFC Style 130 Guide when it is revised. 132 The world of technical publishing has generally accepted rules for 133 grammar, punctuation, capitalization, sentence length and complexity, 134 parallelism, etc. The RFC Editor generally follows these accepted 135 rules as defined by the Chicago Manual of Style (CMOS) [CMOS], with a 136 few important exceptions to avoid ambiguity in complex technical 137 prose and to handle mixtures of text and computer languages. This 138 document presents these exceptions as applied or recommended by the 139 RFC Editor. 141 All RFCs begin as Internet-Drafts, and a well-written and properly 142 constructed Internet-Draft [ID-GUIDE] provides a strong basis for a 143 good RFC. The RFC Editor accepts Internet-Drafts from specified 144 streams for publication [RFC4844] and applies the rules and 145 guidelines for the RFC Series during the editorial process. 147 2. RFC Editorial Philosophy 149 Authors may find it helpful to understand the RFC Editor's goals 150 during the publication process, namely: 152 - Prepare the document according to RFC style and format. 154 - Make the document as clear, consistent, and readable as possible. 156 - Correct larger content/clarity issues; flag any unclear passages 157 for author review. 159 - Fix inconsistencies (e.g., terms that appear in various forms, 160 text that appears multiple times, or inconsistent 161 capitalization). 163 We strive for consistency within: 165 a. the document, 167 b. a cluster of documents [CLUSTER], and 169 c. the series of RFCs on the subject matter. 171 The editorial process of the RFC Editor is not an additional 172 technical review of the document. Where the RFC Editor may suggest 173 changes in wording for clarity and readability, it is up to the 174 author, working group, or stream approving body to determine whether 175 the changes have an impact on the technical meaning of the document 176 [RFC4844]. If the original wording is a more accurate representation 177 of the technical content being described in the document, it takes 178 precedence over editorial conventions. 180 The activity of editing often creates a tension between author and 181 editor. The RFC Editor attempts to minimize this conflict for RFC 182 publication, while continually striving to produce a uniformly 183 excellent document series. The RFC Editor refers to this fundamental 184 tension as "editorial balance", and maintaining this balance is a 185 continuing concern for the RFC Editor. There is a prime directive 186 that must rule over grammatical conventions: do not change the 187 intended meaning of the text. 189 If a document is submitted to the RFC Editor that proves to be 190 uneditable due to consistently unclear and poorly written text, the 191 document may be returned to the stream for revision. See more 192 details in Appendix A.2. 194 3. RFC Style Conventions 196 This Style guide does not use RFC 2119 terminology. Terms such as 197 lowercase "must" and "should" refer to guidance that the RFC Editor 198 will either apply automatically ("must") or query the authors if the 199 authors have not followed that guidance ("should"). 201 3.1. Language 203 The RFC publication language is English. This may be either American 204 or British as long as an individual document is internally 205 consistent. Where both American and British English are used within 206 a document or cluster of documents, the text will be modified to be 207 consistent with American English. 209 3.2. Punctuation 210 * No overstriking (or underlining) is allowed. 212 * When a sentence ended by a period is immediately followed by 213 another sentence, there must be two blank spaces after the period. 215 * A comma is used before the last item of a series, e.g., 217 "TCP service is reliable, ordered, and full-duplex" 219 * When quoting literal text, punctuation is placed outside quotation 220 marks, e.g., 222 'Search for the string "Error Found"'. 224 When quoting general text, such as general text from another RFC, 225 punctuation may be included within the quotation marks, e.g., 227 RFC 4844 indicates that "RFCs are available free of charge to 228 anyone via the Internet." 230 Quotes are not necessary when block quotes are used. 232 3.3. DNS Names and URIs 234 DNS names, whether or not in URIs, that are used as generic 235 examples in RFCs should use the particular examples defined in 236 "Reserved Top-Level DNS Names" [RFC2606], to avoid accidental 237 conflicts. 239 Angle brackets are strongly recommended around URIs [STD66], e.g., 241 243 3.4. Capitalization 245 * Capitalization must be consistent within the document and ideally 246 should be consistent with related RFCs. Refer to the online 247 "Table of decisions on consistent usage of terms in RFCs" [PUB- 248 PROCESS]. 250 * Per CMOS guidelines, the major words in RFC titles and section 251 titles should be capitalized (this is sometimes called "title 252 case"). Typically, all words in a title will be capitalized, 253 except for internal articles, prepositions, and conjunctions. 255 * Section titles that are in sentence form will follow typical 256 sentence capitalization. 258 * Titles of figures may be in sentence form or use title case. 260 3.5. Citations 262 * References and citations must match. That is, there must be a 263 reference for each citation used, and vice versa. 265 * Citations must be enclosed in square brackets, e.g., "[CITE1]". 267 * A citation/reference tag must not contain spaces or hyphens. 269 Example: "[RFC2119]", not "[RFC 2119]". 271 However, the proper textual naming of an RFC contains a space. 273 Example: "See RFC 2119 [BCP14] for more information." 275 * Cross-references within the body of the text and to other RFCs 276 must use section numbers rather than page numbers, as pagination 277 may change per format and device. 279 3.6. Abbreviation Rules 281 Abbreviations should be expanded in document titles and upon first 282 use in the document. The full expansion of the text should be 283 followed by the abbreviation itself in parentheses. The exception 284 is abbreviations that are so common that the readership of RFCs can 285 be expected to recognize them immediately; examples include (but are 286 not limited to) TCP, IP, SNMP, and HTTP. The online list of 287 abbreviations [ABBR] provides guidance. Some cases are marginal, and 288 the RFC Editor will make the final judgment, weighing obscurity 289 against complexity. 291 Note: The online list of abbreviations is not exhaustive or 292 definitive. It is a list of abbreviations appearing in RFCs and 293 sometimes reflects discussions with authors, Work Group (WG) 294 chairs, and/or Area Directors (ADs). Note that some abbreviations 295 have multiple expansions. Additionally, this list includes some 296 terms that look like abbreviations but are actually fixed names 297 for things, and hence cannot and should not be expanded. These 298 are noted as "No expansion". 300 4. Structure of an RFC 302 A published RFC will contain the elements in the following list. 304 Some of these sections are required, as noted. Those sections marked 305 with "*" will be supplied by the RFC Editor during the editorial 306 process when necessary. Sections are allowed to contain nothing but 307 subsections. The rules for each of these elements are described in 308 more detail below. 310 First-page header * [Required] 311 Title [Required] 312 Abstract [Required] 313 RFC Editor or Stream Note * [Upon request] 314 Status of this Memo * [Required] 315 Copyright and License Notice * [Required] 316 Table of Contents [Required] 317 Body of the Memo [Required] 318 1. Introduction [Required] 319 2. Requirement Words (RFC 2119) 320 3. ... 321 MAIN BODY OF THE TEXT 322 6. ... 323 7. IANA Considerations [Required in I-D] 324 8. Internationalization Considerations 325 9. Security Considerations [Required] 326 10. References 327 10.1. Normative References 328 10.2. Informative References 329 Appendix A. 330 Appendix B. 331 Acknowledgments 332 Contributors 333 Author's Address [Required] 335 Within the body of the memo, the order shown above is strongly 336 recommended. Exceptions will be questioned. Outside the body of the 337 memo, the order above is required. The section numbers above are for 338 illustrative purposes; they are not intended to correspond to 339 required numbering in an RFC. 341 The elements preceding the body of the memo should not be numbered. 342 Typically, the body of the memo will have numbered sections and the 343 appendices will be labeled with letters. Any sections that appear 344 after the appendices should not be numbered or labeled (e.g., see 345 "Contributors" above). 347 4.1. First-Page Header 349 Headers will follow the format as described in "RFC Streams, Headers, 350 and Boilerplates" [RFC5741] and its successors. In addition, the 351 following conventions will apply. 353 4.1.1. Author/Editor 355 The determination of who should be listed as an author or editor on 356 an RFC is made by the stream. 358 The author's name (initials followed by family name) appears on the 359 first line of the heading. Some variation, such as additional 360 initials or capitalization of family name, is acceptable but the 361 author should be consistent once they've selected a name format. 363 The total number of authors or editors on the first page is generally 364 limited to five individuals and their affiliations. If there is a 365 request for more than five authors, the stream approving body needs 366 to consider if one or two editors should have primary responsibility 367 for this document, with the other individuals listed in the 368 Contributors or Acknowledgements sections. There must be a direct 369 correlation of authors and editors in the header and Author's Address 370 section. These are the individuals that must sign off on the 371 document during the AUTH48 process and respond to inquiries, such as 372 errata. 374 4.1.2. Organization 376 The author's organization is indicated on the line following the 377 author's name. 379 For multiple authors, each author name appears on its own line, 380 followed by that author's organization. When more than one author is 381 affiliated with the same organization, the organization can be 382 "factored out", appearing only once following the corresponding 383 Author lines. However, such factoring is inappropriate when it would 384 force an unacceptable reordering of author names. 386 If an author cannot or will not provide an affiliation for any 387 reason, "Independent", "Individual Contributor", "Retired", or some 388 other term that appropriately describes the author's affiliation may 389 be used. Alternatively, a blank line may be included in the 390 document header when no affiliation is provided. 392 4.1.3. "ISSN: 2070-1721" 394 The RFC Series has been assigned an International Standard Serial 395 Number of 2070-1721 [ISO3297]. It will be included by the RFC 396 Editor. 398 4.1.4. Updates and Obsoletes 400 When an RFC obsoletes or updates a previously published RFC or RFCs, 401 this information is in the header. For example: 403 "Updates: nnnn" or "Updates: nnnn, ..., nnnn" 405 "Obsoletes: nnnn" or "Obsoletes: nnnn, ... , nnnn" 407 If the document updates or obsoletes more than one document, numbers 408 will be listed in ascending order. 410 4.2. Full Title 412 The title must be centered below the rest of the heading, preceded by 413 two blank lines and followed by one blank line. 415 Choosing a good title for an RFC can be a challenge. A good title 416 should fairly represent the scope and purpose of the document without 417 being either too general or too specific and lengthy. 419 Abbreviations or acronyms in a title must generally be expanded when 420 first encountered (see Section 3.5 for additional guidance on 421 acronyms). 423 It is often helpful to follow the expansion with the parenthesized 424 abbreviation, as in the following example: 426 Encoding Rules for the 427 Common Routing Encapsulation Extension Protocol (CREEP) 429 The RFC Editor recommends that documents a particular company's 430 private protocol should bear a title of the form "Foo's ... Protocol" 431 (where Foo is a company name), to clearly differentiate it from a 432 protocol of more general applicability. 434 4.3. Abstract Section 436 Every RFC must have an Abstract that provides a concise and 437 comprehensive overview of the purpose and contents of the entire 438 document, to give a technically knowledgeable reader a general 439 overview of the function of the document. 441 Composing a useful Abstract generally requires thought and care. 442 Usually an Abstract should begin with a phrase like "This memo ..." 443 or "This document ...". A satisfactory Abstract can often be 444 constructed in part from material within the Introduction section, 445 but an effective Abstract may be shorter, less detailed, and perhaps 446 broader in scope than the Introduction. Simply copying and pasting 447 the first few paragraphs of the Introduction is allowed, but it may 448 result in an Abstract that is both incomplete and redundant. Note 449 also that an Abstract is not a substitute for an Introduction; the 450 RFC should be self-contained as if there were no Abstract. 452 Similarly, the Abstract should be complete in itself. It will appear 453 in isolation in publication announcements and in the online index of 454 RFCs. Therefore, the Abstract must not contain citations. 456 4.4. RFC Editor or Stream Notes Section 458 At times, the stream approving body may approve inclusion of an 459 editorial note to explain anything unusual about the process that led 460 to the document's publication or to note a correction. In this case, 461 a Stream Note section will contain such a note. 463 Additionally, an RFC Editor Note section may contain a note inserted 464 by the RFC Editor to highlight special circumstances surrounding an 465 RFC. 467 4.5. Status of This Memo Section 469 The RFC Editor will supply an appropriate "Status of This Memo" as 470 defined in RFC 5741 [RFC5741]. 472 4.6. Copyright, Licenses, and IPR Boilerplate Section 474 The full copyright and license notices are available on the IETF 475 Trust Legal Provisions Documents website [IETF-TRUST]. 477 4.7. Table of Contents Section 479 A Table of Contents (TOC) is required in all RFCs. It must be 480 positioned after the Copyright notice and before the Introduction. 482 4.8. Body of the Memo Section 484 Following the TOC is the body of the memo. 486 Each RFC must include an "Introduction" section that (among other 487 things) explains the motivation for the RFC and (if appropriate) 488 describes the applicability of the document, e.g., whether it 489 specifies a protocol, provides a discussion of some problem, is 490 simply of interest to the Internet community, or provides a status 491 report on some activity. The body of the memo and the Abstract must 492 be self-contained and separable. This may result in some duplication 493 of text between the Abstract and the Introduction; this is 494 acceptable. 496 4.8.1. Introduction Section 498 The Introduction section should always be the first section following 499 the TOC (except in the case of MIB module documents). While 500 "Introduction" is recommended, authors may choose alternate titles 501 such as "Overview" or "Background". These alternates are acceptable. 503 For MIB module documents, common practice has been for "The Internet- 504 Standard Management Framework" [MIB-BOILER] text to appear as Section 505 1. 507 4.8.2. Requirement Words Section 509 Some documents use certain capitalized words ("MUST", "SHOULD", etc.) 510 to specify precise requirement levels for technical features. RFC 511 2119 [BCP14] defines a default interpretation of these capitalized 512 words in IETF documents. If this interpretation is used, RFC 2119 513 must be cited (as specified in RFC 2119) and included as a normative 514 reference. Otherwise, the correct interpretation must be specified 515 in the document. 517 This section must appear as part of the body of the text (as defined 518 by this document). It must appear as part of, or subsequent to, the 519 Introduction section. 521 These words are considered part of the technical content of the 522 document and are intended to provide guidance to implementers about 523 specific technical features, generally governed by considerations of 524 interoperability. RFC 2119 says: 526 Imperatives of the type defined in this memo must be used with 527 care and sparingly. In particular, they must only be used 528 where it is actually required for interoperation or to limit 529 behavior which has potential for causing harm (e.g., limiting 530 retransmissions). For example, they must not be used to try to 531 impose a particular method on implementers where the method is 532 not required for interoperability. 534 4.8.3. IANA Considerations Section 536 See "Guidelines for Writing an IANA Considerations Section in RFCs" 537 [BCP26]. 539 The RFC Editor will update text accordingly after the IANA 540 assignments have been made. It is helpful for authors to clearly 541 identify where text should be updated to reflect the newly assigned 542 values. For example, the use of "TBD1", "TBD2", etc., is recommended 543 in the IANA Considerations section and in the body of the document. 545 If the authors have provided values to be assigned by IANA, the RFC 546 Editor will verify that the values inserted by the authors match 547 those that have actually been registered on the IANA site. When 548 writing a given value, consistent use of decimal or hexadecimal is 549 recommended. 551 If any of the IANA-related information is not clear, the RFC Editor 552 will work with IANA to send queries to the authors to ensure that 553 assignments and values are properly inserted. 555 The RFC Editor will remove an IANA Considerations section that says 556 there are no IANA considerations (although such a section is required 557 in the Internet-Draft preceding the RFC). 559 4.8.4. Internationalization Considerations Section 561 All RFCs that deal with internationalization issues should have a 562 section describing those issues; see "IETF Policy on Character Sets 563 and Languages" [BCP18], Section 6, for more information. 565 4.8.5. Security Considerations Section 567 All RFCs must contain a section that discusses the security 568 considerations relevant to the specification; see "Guidelines for 569 Writing RFC Text on Security Considerations" [BCP72] for more 570 information. 572 Note that additional boilerplate for RFCs containing MIB and YANG 573 modules also exists. See "Security Guidelines for IETF MIB Modules" 574 [MIB-SEC] and "yang module security considerations" [YANG-SEC] for 575 details. 577 4.8.6. References Section 579 The reference list is solely for recording reference entries. 580 Introductory text is not allowed. 582 The RFC style allows the use of any of a variety of reference styles, 583 as long as they are used consistently within a document. However, 584 where necessary, in specific instances, some reference styles have 585 been described for use within the Series. See the examples in this 586 document. 588 The RFC Editor ensures that references to other RFCs refer to the 589 most current RFC available on that topic (unless provided with reason 590 not to do so). When referring to an obsoleted document, it is common 591 practice to also refer to the most recent version as well. 593 A reference to an RFC that has been assigned an STD [RFC1311], BCP 594 [RFC1818], or FYI [FYI90] sub-series number must include the sub- 595 series number of the document. Note that the FYI series was ended by 596 RFC 6360. RFCs that were published with an FYI sub-series number and 597 still maintain the FYI number must include the sub-series number in 598 the reference. 600 Reference lists must indicate whether each reference is normative or 601 informative, where normative references are essential to implementing 602 or understanding the content of the RFC, and informative references 603 provide additional information. When both normative and informative 604 references exist, the references section should be split into two 605 subsections: 607 s. References 609 s.1. Normative References 611 xxx 612 xxx 614 s.2. Informative References 616 xxx 617 xxx 619 References will generally appear in alphanumeric order by citation 620 tag. Where there are only normative or informative references, no 621 subsection is required; the top level section should say "Normative 622 References" or "Informative References". 624 Normative references to Internet-Drafts will cause publication of the 625 RFC to be suspended until the referenced draft is also ready for 626 publication; the RFC Editor will then update the entry to refer to 627 the RFC and publish both documents simultaneously. 629 4.8.6.1. URIs in RFCs 631 The use of URIs in references is acceptable as long as the URI is the 632 most stable (i.e., unlikely to change and expected to be continuously 633 available) and direct reference possible. The URI will be verified 634 as valid during the RFC editorial process. 636 If a dated URI (one that includes a timestamp for the page) is 637 available for a referenced web page, its use is required. 639 Note that URIs may not be the sole information provided for a 640 reference entry. 642 4.8.6.2. Referencing RFCs 644 The following format is required for citing RFCs. Note the ordering 645 for multiple authors: the last author listed is treated differently 646 than the already listed authors. 648 For 1 Author or Editor: 650 [RFCXXXX] Last name, First initial., Ed. (if applicable), 651 "RFC Title", BCP/FYI/STD ## (if applicable), 652 RFC ####, Date of Publication. 653 655 Example: 657 [RFC3080] Rose, M., "The Blocks Extensible Exchange 658 Protocol Core", RFC 3080, March 2001. 659 661 For 2 Authors or Editors: 663 [RFCXXXX] Last name, First initial., Ed. (if applicable) 664 and First initial. Last name, Ed. (if appropriate), 665 "RFC Title", BCP/FYI/STD ## (if applicable), 666 RFC ####, Date of Publication. 667 669 Example: 671 [RFC6323] Renker, G. and G. Fairhurst, "Sender RTT 672 Estimate Option for the Datagram Congestion 673 Control Protocol (DCCP)", RFC 6323, July 2011. 674 676 For 3 or more Authors or Editors: 678 [RFCXXXX] Last name, First initial., Ed. (if applicable), 679 Last name, First initial., Ed. (if appropriate) 680 and First initial. Last name, Ed. (if appropriate), 681 "RFC Title", BCP/FYI/STD ## (if applicable), 682 RFC ####, Date of Publication. 683 685 Example: 687 [RFC6429] Bashyam, M., Jethanandani, M., and A. Ramaiah, 688 "TCP Sender Clarification for Persist 689 Condition", RFC 6429, December 2011. 690 692 4.8.6.3. Referencing STDs and BCPs 694 Standards (STDs) and Best Current Practices (BCPs) may consist of a 695 single RFC or multiple RFCs. When an STD or BCP that contains 696 multiple RFCs is referenced, the reference entry should include ALL 697 of the RFCs comprising that subseries. The authors should refer to 698 specific RFC numbers as part of the text (not as citations) and cite 699 the subseries number. Inclusion of the URI to the STD or BCP info 700 page is now recommended. The text should appear as follows: 702 See RFC 1034 [STD13]. 704 For an STD or BCP that contains one RFC: 706 [STDXXX] Last name, First initial., Ed. (if applicable) 707 "RFC Title", BCP/FYI/STD ##, RFC ####, Date of 708 Publication. 709 711 Example: 713 [STD72] Gellens, R. and J. Klensin, "Message Submission 714 for Mail", STD 72, RFC 6409, November 2011. 715 717 For an STD or BCP that contains two or more RFCs: 719 [STDXXX] Last name, First initial., Ed. (if applicable) 720 "RFC Title", BCP/FYI/STD ##, RFC ####, Date of 721 Publication. 723 Last name, First initial., Ed. (if applicable) 724 and First initial. Last name, Ed. (if applicable) 725 "RFC Title", BCP/FYI/STD ##, RFC ####, Date of 726 Publication. 728 730 Example: 732 [STD13] Mockapetris, P., "Domain names - concepts and 733 facilities", STD 13, RFC 1034, November 1987. 735 Mockapetris, P., "Domain names - implementation and 736 specification", STD 13, RFC 1035, November 1987. 738 740 4.8.6.4. Referencing Internet-Drafts 741 References to Internet-Drafts can only appear as Informative 742 references. Given that several revisions of an I-D may be produced 743 in a short time frame, references must include the publication date 744 (month and year), the full Internet-Draft file name (including the 745 version number), and the use of the phrase "Work in Progress". If 746 the I-D referenced has a version published as an RFC, references must 747 also include the RFC. Authors may reference multiple versions of an 748 I-D. 750 [SYMBOLIC-TAG] Last name, First initial. and First 751 initial. Last name, Ed. (if applicable) 752 "I-D Title", Work in Progress, 753 draft-string-NN, Month Year. 755 Example: 757 [RFC-STYLE] Flanagan, H. and S. Ginoza, "RFC Style Guide", 758 Work in Progress, draft-flanagan-style-01, 759 August 2013. 761 4.8.6.5. Referencing Errata 763 The following format is required when a reference to an erratum 764 report is necessary: 766 [ErrNNNN] RFC Errata, Erratum ID NNNN, RFC MMMM. 768 [Err1912] RFC Errata, Erratum ID 1912, RFC 2978. 770 4.8.6.6. Referencing Other Standards Development Organizations (SDOs) 772 The following format is suggested when referencing a document or 773 standard from another SDO in which authors are listed: 775 [SYMBOLIC-TAG] 776 Last name, First initial. and First initial. Last name, 777 "Document Title", Document reference number, date of 778 publication, . 780 [W3C.REC-xml11] 781 Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., 782 Yergeau, F., and J. Cowan, "Extensible Markup Language 783 (XML) 1.1 (Second Edition)", W3C Recommendation 784 REC-xml11-20060816, August 2006, . 787 Note that the list of authors is ordered as on the actual document 788 and the common, abbreviated form of the SDO is used. 790 Alternatively, when no list of authors is available, the following 791 format is recommended: 793 [SYMBOLIC-TAG] Organization, "Document Title", Document 794 reference number, date of publication, 795 . 797 Example: 799 [IEEE802.1Q] IEEE, "Local and Metropolitan Area 800 Networks -- Media Access Control (MAC) 801 Bridges and Virtual Bridged Local Area 802 Networks", IEEE Std 802.1Q-2011, August 2011, 803 . 806 4.9. Appendices Section 808 The RFC Editor recommends placing references before the Appendices. 809 Appendices should be labeled as "Appendix A. Appendix A Title", 810 "A.1. Appendix A.1 Title", "Appendix B. Appendix B Title", etc. 812 4.10. Acknowledgments Section 814 This optional section may be used instead of or in addition to a 815 Contributors section. It is often used by authors to publicly thank 816 those who have provided feedback regarding a document and to note any 817 documents from which text was borrowed. 819 4.11. Contributors Section 821 This optional section acknowledges those who have made significant 822 contributions to the document. 824 In a similar fashion to the Author section, the RFC Editor does not 825 make the determination as to who should be listed as a contributor to 826 an RFC. The determination of who should be listed as a contributor 827 on an RFC is made by the stream. 829 The Contributors section may include brief statements about the 830 nature of particular contributions ("Sam contributed Section 3"), and 831 it may also include affiliations of listed contributors. At the 832 discretion of the author(s), contact addresses may also be included 833 in the Contributors section, for those contributors whose knowledge 834 makes them useful future contacts for information about the RFC. Any 835 contact information should be formatted similar to how the 836 information is formatted in the Author's Address section. 838 4.12. "Author's Address" or "Authors' Addresses" Section 840 This required section gives contact information for the author(s) 841 listed in the first-page header. 843 Contact information must include a long-lived email address and 844 optionally may include a postal address and/or telephone number. If 845 the postal address is included, it should include the country name 846 using the English short name listed by the ISO 3166 Maintenance 847 Agency [ISO3166]. The purpose of this section is to (1) 848 unambiguously define author identity (e.g., the John Smith who works 849 for FooBar Systems) and to (2) provide contact information for future 850 readers who have questions or comments. 852 The practice of munged addresses (i.e., altering an email address to 853 make it less readable to bots and web crawlers to avoid spam) is not 854 appropriate in an archival document series. Author contact 855 information is provided so that readers can easily contact the author 856 with questions and/or comments. Address munging is not allowed in 857 RFCs. 859 5. IANA Considerations 861 No IANA actions required. 863 6. Security Considerations 865 No security considerations. 867 7. References 869 7.1. Normative References 871 [STYLE-WEB] RFC Editor, "Web Portion of the Style Guide", 872 . 874 7.2. Informative References 876 [ABBR] RFC Editor Abbreviations List, 877 . 880 [BCP14] Bradner, S., "Key words for use in RFCs to Indicate 881 Requirement Levels", BCP 14, RFC 2119, March 1997, 882 . 884 [BCP18] Alvestrand, H., "IETF Policy on Character Sets and 885 Languages", BCP 18, RFC 2277, January 1998, 886 . 888 [BCP26] Narten, T. and H. Alvestrand, "Guidelines for Writing an 889 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 890 May 2008, . 892 [BCP72] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 893 Text on Security Considerations", BCP 72, RFC 3552, July 894 2003, . 896 [CLUSTER] RFC Editor, "Clusters in the RFC Editor Queue", 897 899 [CMOS] Chicago Manual of Style, 16th ed. Chicago: University of 900 Chicago Press, 2010. 902 [FYI90] Malkin, G. and J. Reynolds, "FYI on FYI: Introduction to 903 the FYI Notes", FYI Notes, RFC 1150, March 1990. 905 Housley, R., "Conclusion of FYI RFC Sub-Series", RFC 6360, 906 August 2011. 908 910 [ID-GUIDE] IETF, "Guidelines to Authors of Internet Drafts", 911 . 913 [IETF-TRUST] 914 IETF Trust, "Trust Legal Provisions (TLP) Documents", 915 . 917 [ISO_OBP] ISO, "Online Browsing Platform", 918 . 920 [ISO3297] Technical Committee ISO/TC 46, Information and 921 documentation, Subcommittee SC 9, Identification and 922 description, "Information and documentation - 923 International standard serial number (ISSN)", September 924 2007. 926 [MIB-BOILER] 927 IETF OPS Area, "Boilerplate for IETF MIB Documents", 928 . 930 [MIB-SEC] IETF OPS Area, "Security Guidelines for IETF MIB 931 Modules", 932 935 [PUB-PROCESS] 936 RFC Editor, "Publication Process", 937 . 939 [RFC1311] Postel, J., "Introduction to the STD Notes", RFC 1311, 940 March 1992, http://www.rfc-editor.org/info/rfc1311 942 [RFC1818] Postel, J., Li, T., and Y. Rekhter, "Best Current 943 Practices", RFC 1818, August 1995, 944 . 946 [RFC2223] Postel, J. and J. Reynolds, "Instructions to RFC Authors", 947 RFC 2223, October 1997, . 950 [RFC2606] Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS 951 Names", BCP 32, RFC 2606, June 1999, 952 . 954 [RFC4844] Daigle, L., Ed., and Internet Architecture Board, "The RFC 955 Series and RFC Editor", RFC 4844, July 2007, 956 . 958 [RFC5741] Daigle, L., Ed., and Kolkman, O., Ed., and IAB, "RFC 959 Streams, Headers, and Boilerplates", RFC 5741, December 960 2009, . 962 [RFC6635] Kolkman, O., Ed., Halpern, J., Ed., and IAB, "RFC Editor 963 Model (Version 2)", RFC 6635, June 2012, 964 . 966 [STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 967 Resource Identifier (URI): Generic Syntax", STD 66, RFC 968 3986, January 2005, 969 . 971 [YANG-SEC] IETF OPS Area, "yang module security considerations", 972 975 Appendix A. Related Procedures 977 The following procedures are related to the application and updating 978 of the RFC Style Guide. 980 A.1. Dispute Resolution 982 There are competing rationales for some of the rules described in 983 this Guide, and the RFC Editor has selected the ones that work best 984 for the Series. However, at times, an author may have a disagreement 985 with the RFC Production Center (RPC) over the application of style 986 guide conventions. In such cases, the authors should discuss their 987 concerns with the RPC. If no agreement can be reached between the 988 RPC and the authors, the RFC Series Editor will, with input from the 989 appropriate stream approving body, make a final determination. If 990 further resolution is required, the dispute resolution process as 991 described in the RFC Editor Model [RFC6635] will be followed. 993 A.2. Returning an I-D to the Document Stream 995 For a given document, if the RFC Editor determines that it cannot be 996 edited without serious risk of altering the meaning of the technical 997 content or if the RFC Editor does not have the resources to provide 998 the level of editing it needs, it may be sent back to the stream 999 approving body with a request to improve the clarity, consistency, 1000 and/or readability of the document. This is not to be considered a 1001 dispute with the author. 1003 A.3. Revising This Document and Associated Web Pages 1005 The RFC Series is continually evolving as a document series. This 1006 document focuses on the fundamental and stable requirements that must 1007 be met by an RFC. From time to time, the RFC Editor may offer less 1008 formal recommendations that authors may apply at their discretion; 1009 these recommendations may be found on the RFC Editor website 1010 "Guidelines for RFC Style" [STYLE-WEB]. 1012 When a new recommendation is made regarding the overall structure and 1013 formatting of the RFCs, it will be published on that page and 1014 accepted for a period of time before the RFC Editor determines 1015 whether it should become part of the fundamental requirements in the 1016 RFC Style Guide or remain as a less formal recommendation. That 1017 period of time will vary in part depending on the frequency with 1018 which authors encounter and apply the guidance. 1020 Acknowledgements 1021 This document refers heavily to RFC 2223 [RFC2223] and draft-rfc- 1022 editor-rfc2223bis-08; as such, we are grateful to the authors of 1023 those documents for their time and effort in to the RFC Series. 1025 Robert T. Braden 1026 USC Information Sciences Institute 1028 Joyce Reynolds 1030 Jon Postel 1032 Contributors 1034 Alice Russo 1035 RFC Production Center 1037 Authors' Addresses 1039 Heather Flanagan 1040 RFC Series Editor 1042 EMail: rse@rfc-editor.org 1044 Sandy Ginoza 1045 RFC Production Center 1047 EMail: rfc-editor@rfc-editor.org