idnits 2.17.1 draft-flanagan-7322bis-00.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 : ---------------------------------------------------------------------------- -- The abstract seems to indicate that this document obsoletes RFC7322, but the header doesn't have an 'Obsoletes:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (March 10, 2017) is 2597 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'RFC6146' is mentioned on line 270, but not defined == Missing Reference: 'RFC6147' is mentioned on line 271, but not defined == Missing Reference: 'RFC6144' is mentioned on line 272, but not defined == Missing Reference: 'RFC6959' is mentioned on line 277, but not defined == Missing Reference: 'Required' is mentioned on line 419, but not defined == Missing Reference: 'RFCXXXX' is mentioned on line 773, but not defined == Missing Reference: 'RFC3080' is mentioned on line 753, but not defined == Missing Reference: 'RFC6323' is mentioned on line 766, but not defined == Missing Reference: 'RFC6429' is mentioned on line 781, but not defined ** Obsolete undefined reference: RFC 6429 (Obsoleted by RFC 9293) == Missing Reference: 'STD13' is mentioned on line 825, but not defined == Missing Reference: 'STDXXX' is mentioned on line 812, but not defined == Missing Reference: 'STD72' is mentioned on line 806, but not defined == Missing Reference: 'SYMBOLIC-TAG' is mentioned on line 894, but not defined == Missing Reference: 'RFC-STYLE' is mentioned on line 850, but not defined == Missing Reference: 'ErrNumber' is mentioned on line 858, but not defined == Missing Reference: 'Err1912' is mentioned on line 860, but not defined == Missing Reference: 'IEEE802.1Q' is mentioned on line 900, 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 4844 (Obsoleted by RFC 8729) -- Obsolete informational reference (is this intentional?): RFC 5741 (Obsoleted by RFC 7841) -- Obsolete informational reference (is this intentional?): RFC 6635 (Obsoleted by RFC 8728) Summary: 1 error (**), 0 flaws (~~), 19 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group H. Flanagan 3 Internet-Draft S. Ginoza 4 Intended status: Informational RFC Editor 5 Expires: September 11, 2017 March 10, 2017 7 RFC Style Guide 8 draft-flanagan-7322bis-00 10 Abstract 12 This document describes the fundamental and unique style conventions 13 and editorial policies currently in use for the RFC Series. It 14 captures the RFC Editor's basic requirements and offers guidance 15 regarding the style and structure of an RFC. Additional guidance is 16 captured on a website that reflects the experimental nature of that 17 guidance and prepares it for future inclusion in the RFC Style Guide. 18 This document obsoletes RFC 7322, "RFC Style Guide". 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on September 11, 2017. 37 Copyright Notice 39 Copyright (c) 2017 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. RFC Editor's Philosophy . . . . . . . . . . . . . . . . . . . 3 56 3. RFC Style Conventions . . . . . . . . . . . . . . . . . . . . 4 57 3.1. Language . . . . . . . . . . . . . . . . . . . . . . . . 5 58 3.2. Punctuation . . . . . . . . . . . . . . . . . . . . . . . 5 59 3.3. DNS Names and URIs . . . . . . . . . . . . . . . . . . . 5 60 3.4. Capitalization . . . . . . . . . . . . . . . . . . . . . 5 61 3.5. Citations . . . . . . . . . . . . . . . . . . . . . . . . 6 62 3.6. Abbreviation Rules . . . . . . . . . . . . . . . . . . . 6 63 3.7. RFCs as Compounds . . . . . . . . . . . . . . . . . . . . 7 64 3.8. Images and Figures . . . . . . . . . . . . . . . . . . . 7 65 4. Structure of an RFC . . . . . . . . . . . . . . . . . . . . . 8 66 4.1. First-Page Header . . . . . . . . . . . . . . . . . . . . 10 67 4.1.1. Author/Editor . . . . . . . . . . . . . . . . . . . . 10 68 4.1.2. Organization . . . . . . . . . . . . . . . . . . . . 10 69 4.1.3. ISSN: 2070-1721 . . . . . . . . . . . . . . . . . . . 11 70 4.1.4. Updates and Obsoletes . . . . . . . . . . . . . . . . 11 71 4.2. Full Title . . . . . . . . . . . . . . . . . . . . . . . 11 72 4.3. Abstract Section . . . . . . . . . . . . . . . . . . . . 12 73 4.4. RFC Editor or Stream Notes Section . . . . . . . . . . . 12 74 4.5. Status of This Memo Section . . . . . . . . . . . . . . . 12 75 4.6. Copyright, Licenses, and IPR Boilerplate Section . . . . 12 76 4.7. Table of Contents Section . . . . . . . . . . . . . . . . 13 77 4.8. Body of the Memo . . . . . . . . . . . . . . . . . . . . 13 78 4.8.1. Introduction Section . . . . . . . . . . . . . . . . 13 79 4.8.2. Requirements Language Section . . . . . . . . . . . . 13 80 4.8.3. IANA Considerations Section . . . . . . . . . . . . . 14 81 4.8.4. Internationalization Considerations Section . . . . . 14 82 4.8.5. Security Considerations Section . . . . . . . . . . . 14 83 4.8.6. References Section . . . . . . . . . . . . . . . . . 15 84 4.9. Appendices Section . . . . . . . . . . . . . . . . . . . 20 85 4.10. Index . . . . . . . . . . . . . . . . . . . . . . . . . . 20 86 4.11. Acknowledgements Section . . . . . . . . . . . . . . . . 20 87 4.12. Contributors Section . . . . . . . . . . . . . . . . . . 20 88 4.13. Author's Address or Authors' Addresses Section . . . . . 21 89 5. Security Considerations . . . . . . . . . . . . . . . . . . . 21 90 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 91 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 92 7.1. Normative References . . . . . . . . . . . . . . . . . . 22 93 7.2. Informative References . . . . . . . . . . . . . . . . . 22 94 Appendix A. Related Procedures . . . . . . . . . . . . . . . . . 25 95 A.1. Dispute Resolution . . . . . . . . . . . . . . . . . . . 25 96 A.2. Returning an I-D to the Document Stream . . . . . . . . . 25 97 A.3. Revising This Document and Associated Web Pages . . . . . 25 98 Appendix B. Contributors . . . . . . . . . . . . . . . . . . . . 26 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 101 1. Introduction 103 The ultimate goal of the RFC publication process is to produce 104 documents that are readable, clear, consistent, and reasonably 105 uniform. The basic formatting conventions for RFCs were established 106 in the 1970s by the original RFC Editor, Jon Postel. This document 107 describes the fundamental and unique style conventions and editorial 108 policies currently in use for the RFC Series [RFC4844]. It is 109 intended as a stable, infrequently updated reference for authors, 110 editors, and reviewers. 112 The RFC Editor also maintains a web portion of the Style Guide (see 113 Appendix A.3) that describes issues as they are raised and indicates 114 how the RFC Editor intends to address them. As new style issues 115 arise, the RFC Editor will first address them on the web portion of 116 the Style Guide [STYLE-WEB]. These topics may become part of the RFC 117 Style Guide when it is revised. 119 The world of technical publishing has generally accepted rules for 120 grammar, punctuation, capitalization, sentence length and complexity, 121 parallelism, etc. The RFC Editor generally follows these accepted 122 rules as defined by the Chicago Manual of Style (CMOS) [CMOS], with a 123 few important exceptions to avoid ambiguity in complex technical 124 prose and to handle mixtures of text and computer languages, or to 125 preserve historical formatting rules. This document presents these 126 exceptions as applied or recommended by the RFC Editor. 128 All RFCs begin as Internet-Drafts (also referred to as I-Ds), and a 129 well-written and properly constructed Internet-Draft [ID-GUIDE] 130 provides a strong basis for a good RFC. The RFC Editor accepts 131 Internet-Drafts from specified streams for publication [RFC4844] and 132 applies the rules and guidelines for the RFC Series during the 133 editorial process. 135 2. RFC Editor's Philosophy 137 Authors may find it helpful to understand the RFC Editor's goals 138 during the publication process, namely to: 140 o Prepare the document according to RFC style and format. 142 o Make the document as clear, consistent, and readable as possible. 144 o Correct larger content/clarity issues; flag any unclear passages 145 for author review. 147 o Fix inconsistencies (e.g., terms that appear in various forms, 148 text that appears multiple times, or inconsistent capitalization). 150 We strive for consistency within: 152 a. the document, 154 b. a cluster of documents [CLUSTER], and 156 c. the series of RFCs on the subject matter. 158 The editorial process of the RFC Editor is not an additional 159 technical review of the document. Where the RFC Editor may suggest 160 changes in wording for clarity and readability, it is up to the 161 author, working group, or stream-approving body to determine whether 162 the changes have an impact on the technical meaning of the document 163 [RFC4844]. If the original wording is a more accurate representation 164 of the technical content being described in the document, it takes 165 precedence over editorial conventions. 167 The activity of editing sometimes creates a tension between author 168 and editor. The RFC Editor attempts to minimize this conflict for 169 RFC publication while continually striving to produce a uniformly 170 excellent document series. The RFC Editor refers to this fundamental 171 tension as "editorial balance,"" and maintaining this balance is a 172 continuing concern for the RFC Editor. There is a prime directive 173 that must rule over grammatical conventions: do not change the 174 intended meaning of the text. 176 If the RFC Editor cannot edit a document without serious risk of 177 altering the meaning, it may be returned to the stream-approving body 178 for review. See Appendix A.2 for more information. 180 3. RFC Style Conventions 182 This Style Guide does not use terminology as defined in RFC 2119 183 [BCP14]. In this document, lowercase use of "must" and "should" 184 indicates changes the RFC Editor will make automatically to conform 185 with this Style Guide versus those that may be questioned if not 186 applied. The lowercase "must" indicates those changes that will be 187 applied automatically and are not at the discretion of the authors. 188 The lowercase "should" indicates the RFC Editor's recommended use, 189 but conformance with the recommendations is not required; the RFC 190 Editor may question whether the guidance may be applied. 192 3.1. Language 194 The RFC publication language is English. Spelling may be either 195 American or British, as long as an individual document is internally 196 consistent. Where both American and British English spelling are 197 used within a document or cluster of documents, the text will be 198 modified to be consistent with American English spelling. 200 3.2. Punctuation 202 o A comma is used before the last item of a series, e.g., 204 "TCP service is reliable, ordered, and full duplex" 206 o When quoting literal text, punctuation is placed outside quotation 207 marks, e.g., 209 Search for the string "Error Found". 211 When quoting general text, such as general text from another RFC, 212 punctuation may be included within the quotation marks, e.g., 214 RFC 4844 indicates that "RFCs are available free of charge to 215 anyone via the Internet. " 217 Quotation marks are not necessary when text is formatted as a 218 block quotation. 220 3.3. DNS Names and URIs 222 DNS names, whether or not in URIs, that are used as generic examples 223 in RFCs should use the particular examples defined in "Reserved Top 224 Level DNS Names" [BCP32], to avoid accidental conflicts. 226 Angle brackets are strongly recommended around URIs [STD66], e.g., 228 230 The use of HTTPS rather than HTTP is strongly encouraged. 232 3.4. Capitalization 234 o Capitalization must be consistent within the document and ideally 235 should be consistent with related RFCs. Refer to the online table 236 of decisions on consistent usage of terms in RFCs [TERMS]. 238 o Per CMOS guidelines, the major words in RFC titles and section 239 titles should be capitalized (this is sometimes called "title 240 case"). Typically, all words in a title will be capitalized, 241 except for internal articles, prepositions, and conjunctions. 243 o Section titles that are in sentence form will follow typical 244 sentence capitalization. 246 o Titles of figures may be in sentence form or use title case. 248 3.5. Citations 250 o References and citations must match. That is, there must be a 251 reference for each citation used, and vice versa. 253 o Citations must be enclosed in square brackets (e.g., "[CITE1]"). 255 o A citation/reference tag must not contain spaces. 257 * Example: "[RFC2119]" rather than "[RFC 2119]" 259 o However, the proper textual naming of an RFC contains a space. 261 * Example: "See RFC 2119 [BCP14] for more information." 263 o Cross-references within the body of the memo and to other RFCs 264 must use section numbers rather than page numbers, as pagination 265 may change per format and device. 267 o An in-text citation may a) follow the subject for which it is 268 being cited or b) be read as part of the text. For example: 270 * a) As part of the transition to IPv6, NAT64 [RFC6146] and DNS64 271 [RFC6147] technologies will be utilized by some access networks 272 to provide IPv4 connectivity for IPv6-only nodes [RFC6144]. 274 or 276 b) Note that SAVI raises a number of important privacy 277 considerations that are discussed more fully in [RFC6959]. 279 We recommend using a) and strongly recommend consistent use of one 280 style throughout. 282 3.6. Abbreviation Rules 284 Abbreviations should be expanded in document titles and upon first 285 use in the document. The full expansion of the text should be 286 followed by the abbreviation itself in parentheses. The exception is 287 an abbreviation that is so common that the readership of RFCs can be 288 expected to recognize it immediately; examples include (but are not 289 limited to) TCP, IP, SNMP, and HTTP. The online list of 290 abbreviations [ABBR] provides guidance. Some cases are marginal, and 291 the RFC Editor will make the final judgment, weighing obscurity 292 against complexity. 294 Note: The online list of abbreviations is not exhaustive or 295 definitive. It is a list of abbreviations appearing in RFCs and 296 sometimes reflects discussions with authors, Working Group Chairs, 297 and/or Area Directors (ADs). Note that some abbreviations have 298 multiple expansions. Additionally, this list includes some terms 299 that look like abbreviations but that are actually fixed names for 300 things and hence cannot and should not be expanded. These are noted 301 as "No Expansion". 303 3.7. RFCs as Compounds 305 Whenever possible: 307 o Hyphenated compounds formed with RFC numbers should be avoided; 308 this can be accomplished by: rewording the sentence (e.g., 309 [RFC5011]-style rollover -> rollover as described in RFC 5011). 311 o adding a note in either the Terminology or Conventions section 312 mentioning the RFC so that other occurrences throughout the text 313 will be understood by the reader to be in the style of said RFC 314 (e.g., This document uses the term "rollover" as defined in RFC 315 5011.). 317 If use of an RFC number in attributive position is unavoidable, the 318 preferred form should appear as in the example "RFC 5011-style 319 rollover". That is: 321 o no hyphen between "RFC" and the number (don't use RFC-5011-style 322 rollover) 324 o avoid hyphenating citations with text (don't use [RFC5011]-style 325 rollover) 327 3.8. Images and Figures 329 The goal of having images within an RFC is to convey information. A 330 good diagram or image expresses information quickly, clearly, and 331 with low chance of misunderstanding. Technically correct but 332 confusing images get in the way of understanding and implementation. 334 o Images should be legible when displayed on a standard screen 335 (1920x1080) and printed on either A4 or US Letter paper. Any text 336 within the diagram should be readable at that resolution. 338 o Authors should use black on white, not white on black. No color 339 or greyscale [RFC7990][RFC7996] 341 o Keep your diagrams as simple as possible. If an object in the 342 diagram is not immediately relevant, leave it out. If you have 343 several ideas you want to convey, consider using more than one 344 diagram. 346 o San-serif fonts are generally considered more readable for digital 347 material. [citation needed] 349 o The style of diagrams within an RFC should be consistent (fonts, 350 shapes, lines). For example, if you you use a dashed line to 351 indicate a certain type of packet flow, then continue to use that 352 style of line consistently. This is encouraged within a single 353 RFC and also within a cluster of RFCs. 355 o Line styles, including thickness, color, and arrow types, are easy 356 methods to convey a particular meaning to the reader. 357 Consistently use the same line styles to convey a particular 358 meaning throughout all diagrams within an RFC in order to avoid 359 confusing the reader. 361 o Flowcharts: avoid crossing the lines if possible. 363 4. Structure of an RFC 365 A published RFC will largely contain the elements in the following 366 list. Some of these sections are required, as noted. Those sections 367 marked with "*" will be supplied by the RFC Editor during the 368 editorial process when necessary. Sections are allowed to contain 369 nothing but subsections. The rules for each of these elements are 370 described in more detail below. 372 First-page header * [Required] 374 Title [Required] 376 Abstract [Required] 378 RFC Editor or Stream Note * [Upon request] 380 Status of This Memo * [Required] 381 Copyright Notice * [Required] 383 Table of Contents * [Required] 385 Body of the Memo [Required] 387 1. Introduction [Required] 389 2. Requirements Language (RFC 2119) 391 3. ... 393 MAIN BODY OF THE TEXT 395 6. ... 397 7. IANA Considerations [Required] 399 8. Internationalization Considerations 401 9. Security Considerations [Required] 403 10. References 405 10.1. Normative References 407 10.2. Informative References 409 Appendix A. 411 Appendix B. 413 Index 415 Acknowledgements 417 Contributors 419 Author's Address [Required] 421 Within the body of the memo, the order shown above is strongly 422 recommended. Exceptions may be questioned. Outside the body of the 423 memo, the order above is required. The section numbers above are for 424 illustrative purposes; they are not intended to correspond to 425 required numbering in an RFC. 427 The elements preceding the body of the memo should not be numbered. 428 Typically, the body of the memo will have numbered sections and the 429 appendices will be labeled with letters. Any sections that appear 430 after the appendices should not be numbered or labeled (e.g., see 431 "Contributors" above). 433 4.1. First-Page Header 435 Headers will follow the format described in "RFC Streams, Headers, 436 and Boilerplates" [RFC5741] and its successors. In addition, the 437 following conventions will apply. 439 4.1.1. Author/Editor 441 The determination of who should be listed as an author or editor on 442 an RFC is made by the stream. 444 The author's name (initial followed by family name) appears on the 445 first line of the heading. Some variation, such as additional 446 initials or capitalization of family name, is acceptable. Once the 447 author has selected how their name should appear, they should use 448 that display consistently in all of their documents. 450 The total number of authors or editors on the first page is generally 451 limited to five individuals and their affiliations. If there is a 452 request for more than five authors, the stream-approving body needs 453 to consider if one or two editors should have primary responsibility 454 for this document, with the other individuals listed in the 455 Contributors or Acknowledgements section. There must be a direct 456 correlation of authors and editors in the document header and the 457 Authors' Addresses section. These are the individuals that must sign 458 off on the document during the AUTH48 process and respond to 459 inquiries, such as errata. 461 4.1.2. Organization 463 The author's organization is indicated on the line following the 464 author's name. 466 For multiple authors, each author name appears on its own line, 467 followed by that author's organization. When more than one author is 468 affiliated with the same organization, the organization can be 469 "factored out," appearing only once following the corresponding 470 Author lines. However, such factoring is inappropriate when it would 471 force an unacceptable reordering of author names. 473 If an author cannot or will not provide an affiliation for any 474 reason, "Independent", "Individual Contributor", "Retired", or some 475 other term that appropriately describes the author's affiliation may 476 be used. Alternatively, a blank line may be included in the document 477 header when no affiliation is provided. 479 4.1.3. ISSN: 2070-1721 481 The RFC Series has been assigned an International Standard Serial 482 Number of 2070-1721 [ISO3297]. It will be included by the RFC 483 Editor. 485 4.1.4. Updates and Obsoletes 487 When an RFC obsoletes or updates a previously published RFC or RFCs, 488 this information is included in the document header. For example: 490 "Updates: nnnn" or "Updates: nnnn, ..., nnnn" 492 "Obsoletes: nnnn" or "Obsoletes: nnnn, ..., nnnn" 494 If the document updates or obsoletes more than one document, numbers 495 will be listed in ascending order. 497 4.2. Full Title 499 The title must be centered below the rest of the heading, preceded by 500 two blank lines and followed by one blank line. 502 Choosing a good title for an RFC can be a challenge. A good title 503 should fairly represent the scope and purpose of the document without 504 being either too general or too specific and lengthy. 506 Abbreviations in a title must generally be expanded when first 507 encountered (see Section 3.6 for additional guidance on 508 abbreviations). 510 It is often helpful to follow the expansion with the parenthesized 511 abbreviation, as in the following example: 513 Encoding Rules for the 514 Common Routing Encapsulation Extension Protocol (CREEP) 516 The RFC Editor recommends that documents describing a particular 517 company's private protocol should bear a title of the form "Foo's ... 518 Protocol" (where Foo is a company name), to clearly differentiate it 519 from a protocol of more general applicability. 521 4.3. Abstract Section 523 Every RFC must have an Abstract that provides a concise and 524 comprehensive overview of the purpose and contents of the entire 525 document, to give a technically knowledgeable reader a general 526 overview of the function of the document. 528 Composing a useful Abstract generally requires thought and care. 529 Usually, an Abstract should begin with a phrase like "This memo ..." 530 or "This document ..." A satisfactory Abstract can often be 531 constructed in part from material within the Introduction section, 532 but an effective Abstract may be shorter, less detailed, and perhaps 533 broader in scope than the Introduction. Simply copying and pasting 534 the first few paragraphs of the Introduction is allowed, but it may 535 result in an Abstract that is both incomplete and redundant. Note 536 also that an Abstract is not a substitute for an Introduction; the 537 RFC should be self-contained as if there were no Abstract. 539 Similarly, the Abstract should be complete in itself. It will appear 540 in isolation in publication announcements and in the online index of 541 RFCs. Therefore, the Abstract must not contain citations. 543 4.4. RFC Editor or Stream Notes Section 545 A stream-approving body may approve the inclusion of an editorial 546 note to explain anything unusual about the process that led to the 547 document's publication or to note a correction. In this case, a 548 stream note section will contain such a note. 550 Additionally, an RFC Editor Note section may contain a note inserted 551 by the RFC Editor to highlight special circumstances surrounding an 552 RFC. 554 4.5. Status of This Memo Section 556 The RFC Editor will supply an appropriate "Status of This Memo" as 557 defined in RFC 5741 [RFC5741] and "Format for RFCs in the IAB Stream" 558 [IAB-FORM]. 560 4.6. Copyright, Licenses, and IPR Boilerplate Section 562 The full copyright and license notices are available on the IETF 563 Trust Legal Provisions documents website [IETF-TRUST]. 565 4.7. Table of Contents Section 567 A Table of Contents (TOC) is required in all RFCs. It must be 568 positioned after the Copyright Notice and before the Introduction. 570 4.8. Body of the Memo 572 Following the TOC is the body of the memo. 574 Each RFC must include an Introduction section that (among other 575 things) explains the motivation for the RFC and (if appropriate) 576 describes the applicability of the document, e.g., whether it 577 specifies a protocol, provides a discussion of some problem, is 578 simply of interest to the Internet community, or provides a status 579 report on some activity. The body of the memo and the Abstract must 580 be self-contained and separable. This may result in some duplication 581 of text between the Abstract and the Introduction; this is 582 acceptable. 584 4.8.1. Introduction Section 586 The Introduction section should always be the first section following 587 the TOC (except in the case of MIB module documents). While 588 "Introduction" is recommended, authors may choose alternate titles 589 such as "Overview" or "Background". These alternates are acceptable. 591 For MIB module documents, common practice has been for "The Internet- 592 Standard Management Framework" [MIB-BOILER] text to appear as 593 Section 1. 595 4.8.2. Requirements Language Section 597 Some documents use certain capitalized words ("MUST", "SHOULD", etc.) 598 to specify precise requirement levels for technical features. RFC 599 2119 [BCP14] defines a default interpretation of these capitalized 600 words in IETF documents. If this interpretation is used, RFC 2119 601 must be cited (as specified in RFC 2119) and included as a normative 602 reference. Otherwise, the correct interpretation must be specified 603 in the document. 605 This section must appear as part of the body of the memo (as defined 606 by this document). It must appear as part of, or subsequent to, the 607 Introduction section. 609 These words are considered part of the technical content of the 610 document and are intended to provide guidance to implementers about 611 specific technical features, generally governed by considerations of 612 interoperability. RFC 2119 says: 614 Imperatives of the type defined in this memo must be used with care 615 and sparingly. In particular, they MUST only be used where it is 616 actually required for interoperation or to limit behavior which has 617 potential for causing harm (e.g., limiting retransmisssions) For 618 example, they must not be used to try to impose a particular method 619 on implementers where the method is not required for 620 interoperability. 622 4.8.3. IANA Considerations Section 624 For guidance on how to register IANA-related values or create new 625 registries to be managed by IANA, see "Guidelines for Writing an IANA 626 Considerations Section in RFCs" [BCP26]. 628 The RFC Editor will update text accordingly after the IANA 629 assignments have been made. It is helpful for authors to clearly 630 identify where text should be updated to reflect the newly assigned 631 values. For example, the use of "TBD1", "TBD2", etc., is recommended 632 in the IANA Considerations section and in the body of the memo. 634 If the authors have provided values to be assigned by IANA, the RFC 635 Editor will verify that the values inserted by the authors match 636 those that have actually been registered on the IANA site. When 637 writing a given value, consistent use of decimal or hexadecimal is 638 recommended. 640 If any of the IANA-related information is not clear, the RFC Editor 641 will work with IANA to send queries to the authors to ensure that 642 assignments and values are properly inserted. 644 4.8.4. Internationalization Considerations Section 646 All RFCs that deal with internationalization issues should have a 647 section describing those issues; see "IETF Policy on Character Sets 648 and Languages" [BCP18], Section 6, for more information. 650 4.8.5. Security Considerations Section 652 All RFCs must contain a section that discusses the security 653 considerations relevant to the specification; see "Guidelines for 654 Writing RFC Text on Security Considerations" [BCP72] for more 655 information. 657 Note that additional boilerplate material for RFCs containing MIB and 658 YANG modules also exists. See "Security Guidelines for IETF MIB 659 Modules" [MIB-SEC] and "yang module security considerations" 660 [YANG-SEC] for details. 662 4.8.6. References Section 664 The reference list is solely for recording reference entries. 665 Introductory text is not allowed. 667 The RFC style allows the use of any of a variety of reference styles, 668 as long as they are used consistently within a document. However, 669 where necessary, some reference styles have been described for use 670 within the Series. See the examples in this document. 672 The RFC Editor ensures that references to other RFCs refer to the 673 most current RFC available on that topic (unless provided with a 674 reason not to do so). When referring to an obsoleted document, it is 675 common practice to also refer to the most recent version. 677 A reference to an RFC that has been assigned an STD [RFC1311], BCP 678 [RFC1818], or FYI [FYI90] sub-series number must include the sub- 679 series number of the document. Note that the FYI series was ended by 680 RFC 6360. RFCs that were published with an FYI sub-series number and 681 still maintain the FYI number must include the sub-series number in 682 the reference. 684 Reference lists must indicate whether each reference is normative or 685 informative, where normative references are essential to implementing 686 or understanding the content of the RFC and informative references 687 provide additional information. More information about normative and 688 informative references may be found in the IESG's statement 689 "Normative and Informative References" [REFS]. When both normative 690 and informative references exist, the references section should be 691 split into two subsections: 693 Templates are available on the RFC Editor website for the XML format 694 of certain references [REFEXAMPLE]. 696 s. References 698 s.1. Normative References 700 xxx 701 ... 702 xxx 704 s.2. Informative References 706 xxx 707 ... 708 xxx 710 References will generally appear in alphanumeric order by citation 711 tag. Where there are only normative or informative references, no 712 subsection is required; the top-level section should say "Normative 713 References" or "Informative References". 715 Normative references to Internet-Drafts will cause publication of the 716 RFC to be suspended until the referenced draft is also ready for 717 publication; the RFC Editor will then update the entry to refer to 718 the RFC and publish both documents simultaneously. 720 4.8.6.1. URIs in RFCs 722 The use of URIs in references is acceptable, as long as the URI is 723 the most stable (i.e., unlikely to change and expected to be 724 continuously available) and direct reference possible. The URI will 725 be verified as valid during the RFC editorial process. 727 If a dated URI (one that includes a timestamp for the page) is 728 available for a referenced web page, its use is required. 730 Note that URIs may not be the sole information provided for a 731 reference entry. 733 The use of HTTPS rather than HTTP is strongly encouraged. 735 4.8.6.2. Referencing RFCs 737 The following format is required for referencing RFCs. The Stream 738 abbreviation should be used; when no stream is available, as with 739 legacy RFCs, this may be left blank. 741 Note the ordering for multiple authors: the format of the name of the 742 last author listed is different than that of all previous authors in 743 the list. 745 For one author or editor: 747 [RFCXXXX] Last name, First initial., Ed. (if applicable), "RFC 748 Title", Stream, Sub-series number (if applicable), RFC number, DOI, 749 Date of publication, http://www.rfc-editor.org/info/rfc# . 751 Example: 753 [RFC3080] Rose, M., "The Blocks Extensible Exchange Protocol Core," 754 IETF, RFC 3080, DOI 10.17487/RFC3080, March 2001, http://www.rfc- 755 editor.org/info/rfc3080 . 757 For two authors or editors: 759 [RFCXXXX] Last name, First initial., Ed. (if applicable) and First 760 initial. Last name, Ed. (if applicable), "RFC Title", Stream, Sub- 761 series number (if applicable), RFC number, DOI, Date of publication, 762 http://www.rfc-editor.org/info/rfc# . 764 Example: 766 [RFC6323] Renker, G. and G. Fairhurst, "Sender RTT Estimate Option 767 for the Datagram Congestion Control Protocol (DCCP)", IETF, RFC 6323, 768 DOI 10.17487/RFC6323, July 2011, http://www.rfc-editor.org/info/ 769 rfc6323 . 771 For three or more authors or editors: 773 [RFCXXXX] Last name, First initial., Ed. (if applicable), Last name, 774 First initial., Ed. (if applicable), and First initial. Last name, 775 Ed. (if applicable), "RFC Title", Stream, Sub-series number (if 776 applicable), RFC number, DOI, Date of publication, http://www.rfc- 777 editor.org/info/rfc# . 779 Example: 781 [RFC6429] Bashyam, M., Jethanandani, M., and A. Ramaiah, "TCP Sender 782 Clarification for Persist Condition", IETF, RFC 6429, DOI 10.17487/ 783 RFC6429, December 2011, http://www.rfc-editor.org/info/rfc6429 . 785 4.8.6.3. Referencing STDs and BCPs 787 Internet Standards (STDs) and Best Current Practices (BCPs) may 788 consist of a single RFC or multiple RFCs. When an STD or BCP that 789 contains multiple RFCs is referenced, the reference entry should 790 include ALL of the RFCs comprising that sub-series. The authors 791 should refer to specific RFC numbers as part of the text (not as 792 citations) and cite the sub-series number. Inclusion of the URI to 793 the STD or BCP info page (see Section 3.2.3 of [RFC5741]) is 794 recommended. The text should appear as follows: 796 See RFC 1034 [STD13]. 798 For an STD or BCP that contains one RFC: 800 [STDXXX] Last name, First initial., Ed. (if applicable), "RFC 801 Title", Stream, Sub-series number, RFC number, DOI, Date of 802 publication, http://www.rfc-editor.org/info/std# . 804 Example: 806 [STD72] Gellens, R. and J. Klensin, "Message Submission for Mail", 807 IETF, STD 72, RFC 6409, DOI 10.17487/RFC6409, November 2011, 808 http://www.rfc-editor.org/info/std72 . 810 For an STD or BCP that contains two or more RFCs: 812 [STDXXX] Last name, First initial., Ed. (if applicable), "RFC 813 Title", Stream, Sub-series number, RFC number, DOI, Date of 814 publication. 816 Last name, First initial., Ed. (if applicable) 817 and First initial. Last name, Ed. (if applicable), 818 "RFC Title", Stream, Sub-series number, RFC number, DOI, 819 Date of publication. 821 823 Example: 825 [STD13] Mockapetris, P., "Domain names - concepts and facilities", 826 STD 13, RFC 1034, DOI 10.17487/RFC1034, November 1987. 828 Mockapetris, P., "Domain names - implementation and 829 specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, 830 November 1987. 832 834 4.8.6.4. Referencing Internet-Drafts 836 References to Internet-Drafts may only appear as informative 837 references. Given that several revisions of an I-D may be produced 838 in a short time frame, references must include the posting date 839 (month and year), the full Internet-Draft file name (including the 840 version number), and the phrase "Work in Progress". Authors may 841 reference multiple versions of an I-D. If the referenced I-D was 842 also later published as an RFC, then that RFC must also be listed. 844 [SYMBOLIC-TAG] Last name, First initial., Ed. (if applicable) and 845 First initial. Last name, Ed. (if applicable), "I-D Title", Work in 846 Progress, draft-string-NN, Month Year. 848 Example: 850 [RFC-STYLE] Flanagan, H. and S. Ginoza, "RFC Style Guide", Work in 851 Progress, draft-flanagan-style-01, June 2013. 853 4.8.6.5. Referencing Errata 855 The following format is required when a reference to an erratum 856 report is necessary: 858 [ErrNumber] RFC Errata, Erratum ID number, RFC number, . 860 [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, xxx. 862 4.8.6.6. Referencing Other Standards Development Organizations (SDOs) 864 The following format is suggested when referencing a document or 865 standard from another SDO in which authors are listed: 867 [SYMBOLIC-TAG] 869 Last name, First initial. and First initial. Last name, 871 "Document Title", Document reference number, Date of 873 publication, . 875 [W3C.REC-xml11] 877 Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., 879 Yergeau, F., and J. Cowan, "Extensible Markup Language 881 (XML) 1.1 (Second Edition)", W3C Recommendation 883 REC-xml11-20060816, August 2006, 885 . 887 The order of authors in the list is the same as the order shown on 888 the actual document and that the common, abbreviated form of the SDO 889 is used. 891 Alternatively, when no list of authors is available, the following 892 format is recommended: 894 [SYMBOLIC-TAG] Organization, "Document Title", Document 895 reference number, Date of publication, 896 . 898 Example: 900 [IEEE802.1Q] IEEE, "Local and Metropolitan Area 901 Networks -- Media Access Control (MAC) 902 Bridges and Virtual Bridged Local Area 903 Networks", IEEE Std 802.1Q-2011, August 2011, 904 907 Per the IEEE coordination team, listing dates for IEEE standards is 908 not recommended unless there is a need to cite a particular section, 909 in which case the dated reference is appropriate. An RFC with a 910 dated IEEE reference suggests that the RFC only applies to that 911 specific IEEE specification. 913 4.8.6.7. Referencing Email on Mailing Lists 915 When referencing emails to mailing lists, the template provided here 916 should be used: 918 [reftag] Sender, A., "Subject: Subject line", message to the 920 listname mailing list, DD Month YYYY, . 922 4.9. Appendices Section 924 The RFC Editor recommends placing references before the Appendices. 925 Appendices should be labeled as "Appendix A. Title", "A.1. Title", 926 "Appendix B. Title", etc. 928 4.10. Index 930 If included, an index appears directly after any appendices and 931 before the Acknowledgements (if any). Where applicable, it appears 932 before the "IAB Members at the Time of Approval" section. 934 4.11. Acknowledgements Section 936 This optional section may be used instead of, or in addition to, a 937 Contributors section. It is often used by authors to publicly thank 938 those who have provided feedback regarding a document and to note any 939 documents from which text was borrowed. 941 4.12. Contributors Section 943 This optional section acknowledges those who have made significant 944 contributions to the document. 946 In a similar fashion to the Author�s Address section, the RFC 947 Editor does not make the determination as to who should be listed as 948 a contributor to an RFC. The determination of who should be listed 949 as a contributor is made by the stream. 951 The Contributors section may include brief statements about the 952 nature of particular contributions (e.g., "Sam contributed 953 Section 3"), and it may also include affiliations of listed 954 contributors. At the discretion of the author(s), contact addresses 955 may also be included in the Contributors section, for those 956 contributors whose knowledge makes them useful future contacts for 957 information about the RFC. The format of any contact information 958 should be similar to the format of information in the Author�s 959 Address section. 961 4.13. Author's Address or Authors' Addresses Section 963 This required section gives contact information for the author(s) 964 listed in the first-page header. 966 Contact information must include a long-lived email address and 967 optionally may include a postal address and/or telephone number. If 968 the postal address is included, it should include the country name, 969 using the English short name listed by the ISO 3166 Maintenance 970 Agency [ISO_OBP]. The purpose of this section is to (1) 971 unambiguously define author identity (e.g., the John Smith who works 972 for FooBar Systems) and (2) provide contact information for future 973 readers who have questions or comments. 975 The practice of munged email addresses (i.e., altering an email 976 address to make it less readable to bots and web crawlers to avoid 977 spam) is not appropriate in an archival document series. Author 978 contact information is provided so that readers can easily contact 979 the author with questions and/or comments. Address munging is not 980 allowed in RFCs. 982 5. Security Considerations 984 This document has no security considerations. 986 6. IANA Considerations 988 This document has no IANA considerations. 990 7. References 991 7.1. Normative References 993 [STYLE-WEB] 994 RFC Editor, "Web Portion of the Style Guide", 995 . 997 7.2. Informative References 999 [ABBR] RFC Editor, "RFC Editor Abbreviations List", 1000 . 1003 [BCP14] Bradner, S., "Key words for use in RFCs to Indicate 1004 Requirement Levels", BCP 14, RFC 2119, March 1997, 1005 . 1007 [BCP18] Alvestrand, H., "IETF Policy on Character Sets and 1008 Languages", BCP 18, RFC 2277, January 1998, 1009 . 1011 [BCP26] Alvestrand, H. and T. Narten, "Guidelines for Writing an 1012 ANA Considerations Section in RFCs", BCP 26, RFC 5226, May 1013 2008, . 1015 [BCP32] Eastlake 3rd, D. and A. Panitz, "Reserved Top Level DNS 1016 Names", BCP 32, RFC 2606, June 1999, . 1019 [BCP72] Rescorla, E. and B. Korver, "Guidelines for Writing RFC 1020 Text on Security Considerations", BCP 72, RFC 3552, July 1021 2003, . 1023 [CLUSTER] RFC Editor, "Clusters in the RFC Editor Queue", 1024 . 1026 [CMOS] University of Chicago Press, 2010, "Chicago Manual of 1027 Style, 16th ed.", 2010. 1029 [FYI90] Malkin, G. and J. Reynolds, "FYI on FYI: Introduction to 1030 the FYI Notes", FYI 90, RFC 1150, March 1990, 1031 . 1033 Housley, R., "Conclusion of FYI RFC Sub-Series", RFC 6360, 1034 August 2011. 1036 [IAB-FORM] 1037 IAB, "Format for RFCs in the IAB Stream", 1038 . 1041 [ID-GUIDE] 1042 IETF, "Guidelines to Authors of Internet Drafts", 1043 . 1045 [IETF-TRUST] 1046 IETF Trust, "Trust Legal Provisions (TLP)", 1047 . 1049 [ISO3297] Technical Committee ISO/TC 46, Information and 1050 documentation, Subcommittee SC 9, "Identification and 1051 description, Information and documentation - International 1052 standard serial number (ISSN)", September 2007. 1054 [ISO_OBP] ISO, "Online Browsing Platform (OBP)", 1055 . 1057 [MIB-BOILER] 1058 IETF OPS Area, "Boilerplate for IETF MIB Documents", 1059 . 1061 [MIB-SEC] IETF OPS Area, "Security Guidelines for IETF MIB Modules", 1062 . 1065 [REFEXAMPLE] 1066 RFC Editor, "Reference Examples", . 1069 [REFS] IESG, "IESG Statement: Normative and Informative", 1070 . 1073 [RFC1311] Postel, J., "Introduction to the STD Notes", RFC 1311, 1074 DOI 10.17487/RFC1311, March 1992, 1075 . 1077 [RFC1818] Postel, J., Li, T., and Y. Rekhter, "Best Current 1078 Practices", RFC 1818, DOI 10.17487/RFC1818, August 1995, 1079 . 1081 [RFC4844] Daigle, L., Ed. and Internet Architecture Board, "The RFC 1082 Series and RFC Editor", RFC 4844, DOI 10.17487/RFC4844, 1083 July 2007, . 1085 [RFC5741] Daigle, L., Ed., Kolkman, O., Ed., and IAB, "RFC Streams, 1086 Headers, and Boilerplates", RFC 5741, 1087 DOI 10.17487/RFC5741, December 2009, 1088 . 1090 [RFC6635] Kolkman, O., Ed., Halpern, J., Ed., and IAB, "RFC Editor 1091 Model (Version 2)", RFC 6635, DOI 10.17487/RFC6635, June 1092 2012, . 1094 [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990, 1095 DOI 10.17487/RFC7990, December 2016, 1096 . 1098 [RFC7996] Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", 1099 RFC 7996, DOI 10.17487/RFC7996, December 2016, 1100 . 1102 [STD66] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1103 Resource Identifier (URI): Generic Synta", STD 66, 1104 RFC 3986, January 2005, . 1107 [TERMS] RFC Editor, "Terms List", . 1110 [YANG-SEC] 1111 IETF Ops Area, "yang module security considerations", 1112 . 1115 Appendix A. Related Procedures 1117 The following procedures are related to the application and updating 1118 of the RFC Style Guide. 1120 A.1. Dispute Resolution 1122 There are competing rationales for some of the rules described in 1123 this Guide, and the RFC Editor has selected the ones that work best 1124 for the Series. However, at times, an author may have a disagreement 1125 with the RFC Production Center (RPC) over the application of Style 1126 Guide conventions. In such cases, the authors should discuss their 1127 concerns with the RPC. If no agreement can be reached between the 1128 RPC and the authors, the RFC Series Editor will, with input from the 1129 appropriate stream-approving body, make a final determination. If 1130 further resolution is required, the dispute resolution process as 1131 described in the RFC Editor Model [RFC6635] will be followed. 1133 A.2. Returning an I-D to the Document Stream 1135 For a given document, if the RFC Editor determines that it cannot be 1136 edited without serious risk of altering the meaning of the technical 1137 content or if the RFC Editor does not have the resources to provide 1138 the level of editing it needs, it may be sent back to the stream- 1139 approving body with a request to improve the clarity, consistency, 1140 and/or readability of the document. This is not to be considered a 1141 dispute with the author. 1143 A.3. Revising This Document and Associated Web Pages 1145 The RFC Series is continually evolving as a document series. This 1146 document focuses on the fundamental and stable requirements that must 1147 be met by an RFC. From time to time, the RFC Editor may offer less 1148 formal recommendations that authors may apply at their discretion; 1149 these recommendations may be found on the RFC Editor website 1150 "Guidelines for RFC Style" [STYLE-WEB]. 1152 When a new recommendation is made regarding the overall structure and 1153 formatting of RFCs, it will be published on that page and accepted 1154 for a period of time before the RFC Editor determines whether it 1155 should become part of the fundamental requirements in the RFC Style 1156 Guide or remain as a less formal recommendation. That period of time 1157 will vary, in part depending on the frequency with which authors 1158 encounter and apply the guidance. 1160 Appendix B. Contributors 1162 Alice Russo RFC Production Center 1164 Authors' Addresses 1166 Heather Flanagan RFC Series Editor 1168 EMail: rse@rfc-editor.org 1170 Sandy Ginoza RFC Production Center 1172 EMail: rfc-editor@rfc-editor.org 1174 Authors' Addresses 1176 Heather Flanagan 1177 RFC Editor 1179 EMail: rse@rfc-editor.org 1180 URI: https://orcid.org/0000-0002-2647-2220 1182 Sandy Ginoza 1183 RFC Editor 1185 EMail: rfc-editor@rfc-editor.org 1186 URI: https://www.rfc-editor.org