├── Makefile ├── README.md ├── draft-flanagan-7322bis-07.xml └── draft-rpc-rfc7322bis.xml /Makefile: -------------------------------------------------------------------------------- 1 | # make readable versions 2 | 3 | all: draft-flanagan-7322bis-07.html draft-flanagan-7322bis-07.txt 4 | 5 | 6 | draft-flanagan-7322bis-07.html: draft-flanagan-7322bis-07.xml 7 | xml2rfc --html $< 8 | 9 | 10 | draft-flanagan-7322bis-07.txt: draft-flanagan-7322bis-07.xml 11 | xml2rfc --text $< 12 | 13 | 14 | 15 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # draft-rpc-rfc7322bis 2 | 3 | Draft updates to the RFC Style Guide. 4 | -------------------------------------------------------------------------------- /draft-flanagan-7322bis-07.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | RFC Style Guide 15 | 16 | 17 | Temporary RFC Series Project Manager 18 |
19 | standards@standcore.com 20 | http://orcid.org/0000-0001-7553-5024 21 |
22 |
23 | 24 | RFC Editor 25 |
26 | rfc-editor@rfc-editor.org 27 | https://www.rfc-editor.org 28 |
29 |
30 | 31 | 32 | This document describes the fundamental and unique style conventions 33 | and editorial policies currently in use for the RFC Series. It 34 | captures the RFC Editor's basic requirements and offers guidance 35 | regarding the style and structure of an RFC. Additional guidance is 36 | captured on a website that reflects the experimental nature of that 37 | guidance and prepares it for future inclusion in the RFC Style Guide. 38 | This document obsoletes RFC 7322, "RFC Style Guide". 39 | 40 |
41 | 42 |
43 | Introduction 44 | The ultimate goal of the RFC publication process is to produce 45 | documents that are readable, clear, and consistent. The basic formatting 46 | conventions for RFCs were established 47 | in the 1970s by the original RFC Editor, Jon Postel. This document 48 | describes the fundamental and unique style conventions and editorial 49 | policies currently in use for the RFC Series and is 50 | intended as a stable, infrequently updated reference for authors, 51 | editors, and reviewers. 52 | The RFC Editor also maintains a web portion of the Style Guide (see 53 | Appendix A.3) that describes issues as they are raised and indicates 54 | how the RFC Editor intends to address them. As new style issues 55 | arise, the RFC Editor will first address them on the web portion of 56 | the Style Guide . These topics may become part of the RFC 57 | Style Guide when it is revised. 58 | The world of publishing has generally accepted rules for 59 | grammar, punctuation, capitalization, sentence length and complexity, etc. 60 | The RFC Editor generally follows these accepted 61 | rules as defined by the Chicago Manual of Style (CMOS) , with a 62 | few important exceptions to avoid ambiguity in complex technical 63 | prose and to handle mixtures of text and computer languages, or to 64 | preserve historical formatting rules. This document presents these 65 | exceptions as applied or recommended by the RFC Editor. 66 | All RFCs begin as Internet-Drafts (also referred to as I-Ds), and a 67 | well-written and properly constructed Internet-Draft 68 | provides a strong basis for a good RFC. The RFC Editor accepts 69 | Internet-Drafts from specified streams for publication [RFC4844] and 70 | applies the rules and guidelines for the RFC Series during the 71 | editorial process. 72 |
73 |
74 | RFC Editor's Philosophy 75 | Authors may find it helpful to understand the RFC Editor's goals 76 | during the publication process, namely to: 77 |
    78 |
  • Prepare the document according to RFC style and format.
  • 79 |
  • Make the document as clear, consistent, and readable as possible.
  • 80 |
  • Correct larger content/clarity issues; flag any unclear passages 81 | for author review.
  • 82 |
  • Fix inconsistencies (e.g., terms that appear in various forms, 83 | inconsistent capitalization, discrepancies between a figure and the text that 84 | describes it).
  • 85 |
86 | We strive for consistency within: 87 | a. the document, 88 | b. a cluster of documents , and 89 | c. the series of RFCs on the subject matter. 90 | The editorial process of the RFC Editor is not an additional 91 | technical review of the document. Where the RFC Editor may suggest 92 | changes in wording for clarity and readability, it is up to the 93 | author, working group, or stream-approving body to determine whether 94 | the changes have an impact on the technical meaning of the document 95 | [RFC4844]. If the original wording is a more accurate representation 96 | of the technical content being described in the document, it takes 97 | precedence over editorial conventions. 98 | The activity of editing sometimes creates a tension between author 99 | and editor. The RFC Editor attempts to minimize this conflict for 100 | RFC publication while continually striving to produce a uniformly 101 | excellent document series. The RFC Editor refers to this fundamental 102 | tension as "editorial balance," and maintaining this balance is a 103 | continuing concern for the RFC Editor. There is a prime directive 104 | that must rule over grammatical conventions: do not change the 105 | intended meaning of the text. 106 | If the RFC Editor cannot edit a document without serious risk of 107 | altering the meaning, it may be returned to the stream-approving body 108 | for review. See Appendix A.2 for more information. 109 |
110 |
111 | RFC Style Conventions 112 | This Style Guide does not use terminology as defined in RFC 2119 113 | . In this document, lowercase use of "must" and "should" 114 | indicates changes the RFC Editor will make automatically to conform 115 | with this Style Guide versus those that may be questioned if not 116 | applied. The lowercase "must" indicates those changes that will be 117 | applied automatically and are not at the discretion of the authors. 118 | The lowercase "should" indicates the RFC Editor's recommended use, 119 | but conformance with the recommendations is not required; the RFC 120 | Editor may question whether the guidance may be applied. 121 |
122 | Language 123 | The RFC publication language is English. Spelling may be either 124 | American or British, as long as an individual document is internally 125 | consistent. Where both American and British English spelling are 126 | used within a document or cluster of documents, the text will be 127 | modified to be consistent with American English spelling. 128 |
129 |
130 | Punctuation 131 |
  1. 132 | A comma is used before the last item of a series, e.g., 133 | 134 | "TCP service is reliable, ordered, and full duplex" 135 |
  2. 136 |
  3. 137 | When quoting literal text, punctuation is placed outside quotation 138 | marks, e.g., 139 | 140 | Search for the string "Error Found". 141 | 142 | When quoting general text, such as general text from another RFC, 143 | punctuation may be included within the quotation marks, e.g., 144 | 145 | RFC 4844 indicates that "RFCs are available free of charge to 146 | anyone via the Internet." 147 | 148 | Quotation marks are not necessary when text is formatted as a 149 | block quotation. 150 |
  4. 151 |
152 |
153 | RFCs as Compounds 154 | Whenever possible: 155 | 156 |
    157 |
  • Hyphenated compounds formed with RFC numbers should be avoided; 158 | this can be accomplished by: rewording the sentence (e.g., change "[RFC5011]-style 159 | rollover" to "rollover as described in RFC 5011").
  • 160 |
  • adding a note in either the Terminology or Conventions section mentioning 161 | the RFC so that other occurrences throughout the text will be understood by 162 | the reader to be in the style of said RFC (e.g., This document uses the term 163 | "rollover" as defined in RFC 5011.).
  • 164 |
165 | If use of an RFC number in attributive position is unavoidable, the 166 | preferred form should appear as in the example "RFC 5011-style rollover". 167 | That is: 168 | 169 |
    170 |
  • no hyphen between "RFC" and the number (don't use RFC-5011-style rollover)
  • 171 |
  • avoid hyphenating citations with text (don't use [RFC5011]-style rollover)
  • 172 |
173 |
174 |
175 |
176 | DNS Names and URIs 177 | DNS names, whether or not in URIs, that are used as generic examples 178 | in RFCs should use the particular examples defined in "Reserved Top 179 | Level DNS Names" , to avoid accidental conflicts. 180 | Angle brackets are strongly recommended around URIs , e.g., 181 | <https://example.com/> 182 | The use of HTTPS rather than HTTP is strongly encouraged. 183 |
184 |
185 | Capitalization 186 |
  1. Capitalization must be consistent within the document and ideally 187 | should be consistent with related RFCs. Refer to the online table 188 | of decisions on consistent usage of terms in RFCs .
  2. 189 |
  3. Per CMOS guidelines, the major words in RFC titles and section 190 | titles should be capitalized (this is sometimes called "title 191 | case"). Typically, all words in a title will be capitalized, 192 | except for internal articles, prepositions, and conjunctions.
  4. 193 |
  5. Section titles that are in sentence form will follow typical 194 | sentence capitalization.
  6. 195 |
  7. Titles of figures may be in sentence form or use title case.
  8. 196 |
  9. Some terms related to the various roles or parts of the streams authoring 197 | RFCs should be used consistently. For example, when the term 'working group' 198 | or 'research group' is used as part of a 199 | specific group name, it will be capitalized (e.g., kitten Working Group, 200 | Crypto Forum Research Group). When used to generally refer to groups, it 201 | will be downcased.
  10. 202 |
203 |
204 |
205 | Citations 206 | The most important function of a citation is to point to a reference so that 207 | a reader may follow up on additional material that is important in some way to 208 | understanding or implementing the content in an RFC. This section offers guidance 209 | on the requirements and recommendations for citation format within an RFC. 210 |
  1. References and citations must match. That is, there must be a 211 | reference for each citation used, and vice versa.
  2. 212 |
  3. Citations must be enclosed in square brackets (e.g., "[CITE1]").
  4. 213 |
  5. Citations are restricted to ASCII-only characters, as described in "The Use 214 | of Non-ASCII Characters in RFCs" .
  6. 215 |
  7. 216 | Citations must begin with a number or a letter, and may contain digits, letters, 217 | colons, hyphens, underscores, or dots. 218 | 219 |
      220 |
    • Example: "[IEEE.802.15.4]" rather than "[.802.15.4]"
    • 221 |
    • Example: "[RFC2119]" rather than "[RFC 2119]"
    • 222 |
    223 |
  8. 224 |
  9. 225 | Citations may not include spaces, commas, quotation marks, or other 226 | punctuation (!, ?, etc.), and should be in-line with the normal line of type. 227 | 228 |
      229 |
    • Example: "See RFC 2119 for more information."
    • 230 |
    231 |
  10. 232 |
  11. Cross-references within the body of the memo and to other RFCs 233 | must use section numbers rather than page numbers, as pagination 234 | may change per format and device.
  12. 235 |
  13. 236 | A citation may A) follow the subject to which the citation applies 237 | or B) be read as part of the text. For example: 238 | 239 |
    1. As part of the transition to IPv6, NAT64 [RFC6146] and DNS64 240 | [RFC6147] technologies will be utilized by some access networks to 241 | provide IPv4 connectivity for IPv6-only nodes [RFC6144].
    2. 242 |
    3. Note that SAVI raises a number of important privacy considerations 243 | that are discussed more fully in [RFC6959].
    4. 244 |
    245 |
  14. 246 |
  15. For a document referenced multiple times in running text, the citation anchor must 247 | be at first use outside the abstract. Additional citations are allowed at the author's 248 | discretion.
  16. 249 |
250 | We recommend using A) and strongly recommend consistent use of one style throughout. 251 |
252 |
253 | Abbreviation Rules 254 | Abbreviations should be expanded in document titles and upon first 255 | use in the document. The full expansion of the text should be 256 | followed by the abbreviation itself in parentheses. The exception is 257 | an abbreviation that is so common that the readership of RFCs can be 258 | expected to recognize it immediately; examples include (but are not 259 | limited to) TCP, IP, SNMP, and HTTP. The online list of 260 | abbreviations provides guidance. Some cases are marginal, and 261 | the RFC Editor will make the final judgment, weighing obscurity 262 | against complexity. 263 | Note: The online list of abbreviations is not exhaustive or 264 | definitive. It is a list of abbreviations appearing in RFCs and 265 | sometimes reflects discussions with authors, Working Group Chairs, 266 | and/or Area Directors (ADs). Note that some abbreviations have 267 | multiple expansions. Additionally, this list includes some terms 268 | that look like abbreviations but that are actually fixed names for 269 | things and hence cannot and should not be expanded. These are 270 | noted as "No Expansion". 271 |
272 |
273 | Images and Figures 274 | The goal of having images within an RFC is to convey information. A good 275 | diagram or image expresses information quickly, clearly, and with low chance 276 | of misunderstanding. Technically correct but confusing images get in the 277 | way of understanding and implementation. 278 |
  1. Images should be legible when displayed on a standard screen (1920x1080) 279 | and printable on either A4 or US Letter paper. Any text within the diagram 280 | should be readable at that resolution.
  2. 281 |
  3. Authors should use black on white, not white on black. No color or 282 | greyscale
  4. 283 |
  5. Keep your diagrams as simple as possible. If an object in the diagram 284 | is not immediately relevant, leave it out. If you have several ideas you 285 | want to convey, consider using more than one diagram.
  6. 286 |
  7. San-serif fonts are generally considered more readable for digital 287 | material. [citation needed]
  8. 288 |
  9. The style of diagrams within an RFC should be consistent both within a 289 | single RFC and within a cluster of RFCs (fonts, shapes, 290 | lines). For example, if you you use a dashed line to indicate a certain 291 | type of packet flow, then continue to use that style of line consistently. 292 |
  10. 293 |
  11. Line styles, including thickness, color, and arrow types, are easy 294 | methods to convey a particular meaning to the reader. Consistently use 295 | the same line styles to convey a particular meaning throughout all 296 | diagrams within an RFC in order to avoid confusing the reader.
  12. 297 |
  13. Flowcharts: avoid crossing the lines if possible.
  14. 298 |
  15. Captions or alternative text are encouraged for all figures, diagrams, 299 | and other artwork. 300 |
  16. 301 |
302 |
303 |
304 |
305 | Structure of an RFC 306 | A published RFC will largely contain the elements in the following 307 | list. Some of these sections are required, as noted. Those sections 308 | marked with "*" will be supplied by the RFC Editor during the 309 | editorial process when necessary. The rules for each of these elements are 310 | described in more detail below. 311 | 341 | Within the body of the memo, the order shown above is strongly 342 | recommended. Exceptions may be questioned. Outside the body of the 343 | memo, the order above is required. The section numbers above are for 344 | illustrative purposes; they are not intended to correspond to 345 | required numbering in an RFC. 346 | The elements preceding the body of the memo should not be numbered. 347 | Typically, the body of the memo will have numbered sections and the 348 | appendices will be labeled with letters. Any sections that appear 349 | after the appendices should not be numbered or labeled (e.g., see 350 | "Contributors" above). 351 |
352 | First-Page Header 353 | Headers will follow the format described in "RFC Streams, Headers, 354 | and Boilerplates" and its successors. In addition, the 355 | following conventions will apply. 356 |
357 | Author/Editor 358 | The final determination of who should be listed as an author or editor on 359 | an RFC is made by the stream, as is whether or not including author 360 | affiliation is required. 361 | The author's name (initial followed by family name) appears on the 362 | first line of the heading. Some variation, such as additional 363 | initials or capitalization of family name, is acceptable. Once the 364 | author has selected how their name should appear, they should use 365 | that display consistently in all of their documents. 366 | The total number of authors or editors on the first page is generally 367 | limited to five individuals and their affiliations. If there is a 368 | request for more than five authors, the stream-approving body needs 369 | to consider if one or two editors should have primary responsibility 370 | for this document, with the other individuals listed in the 371 | Contributors or Acknowledgements section. There must be a direct 372 | correlation of authors and editors in the document header and the 373 | Authors' Addresses section. These are the individuals that must sign 374 | off on the document during the AUTH48 process and respond to 375 | inquiries, such as errata. 376 |
377 |
378 | Organization 379 | The author's organization is indicated on the line following the 380 | author's name. 381 | For multiple authors, each author name appears on its own line, 382 | followed by that author's organization. When more than one author is 383 | affiliated with the same organization, the organization can be 384 | "factored out," appearing only once following the corresponding 385 | Author lines. However, such factoring is inappropriate when it would 386 | force an unacceptable reordering of author names. 387 | If an author cannot or will not provide an affiliation for any 388 | reason, "Independent", "Individual Contributor", "Retired", or some 389 | other term that appropriately describes the author's affiliation may 390 | be used. Alternatively, a blank line may be included in the document 391 | header when no affiliation is provided. 392 |
393 |
394 | ISSN: 2070-1721 395 | The RFC Series has been assigned an International Standard Serial 396 | Number of 2070-1721 . It will be included by the 397 | RFC Editor. 398 |
399 |
400 | Digital Object Identifier 10.17487 401 | The RFC Series has been assigned a Digital Object Identifier prefix of 402 | 10.17487 . A DOI will be assigned and included by the 403 | RFC Editor. 404 |
405 |
406 | Updates and Obsoletes 407 | When an RFC obsoletes or updates a previously published RFC or RFCs, 408 | this information is included in the document header. For example: 409 | "Updates: nnnn" or "Updates: nnnn, ..., nnnn" 410 | "Obsoletes: nnnn" or "Obsoletes: nnnn, ..., nnnn" 411 | If the document updates or obsoletes more than one document, numbers 412 | will be listed in ascending order. 413 |
414 |
415 |
416 | Document Title 417 | The title must be centered below the rest of the heading, preceded by 418 | two blank lines and followed by one blank line. 419 | Choosing a good title for an RFC can be a challenge. A good title 420 | should fairly represent the scope and purpose of the document without 421 | being either too general or too specific and lengthy. 422 | Abbreviations in a title must generally be expanded when first 423 | encountered (see Section 3.6 for additional guidance on 424 | abbreviations). 425 | It is often helpful to follow the expansion with the parenthesized 426 | abbreviation, as in the following example: 427 | 431 | The RFC Editor recommends that documents describing a particular 432 | company's private protocol should bear a title of the form "Foo's ... 433 | Protocol" (where Foo is a company name), to clearly differentiate it 434 | from a protocol of more general applicability. 435 |
436 |
437 | Abstract Section 438 | Every RFC must have an Abstract that provides a concise and comprehensive 439 | overview of the purpose and contents of the entire document, to give a 440 | technically knowledgeable reader a general overview of the function of the 441 | document and some context with regards to its relationship (in particular, 442 | whether it updates or obsoletes) any other RFCs. In addition to its function in 443 | the RFC itself, the Abstract section text will appear in publication 444 | announcements and in the online index of RFCs. 445 | Composing a useful Abstract generally requires thought and care. Usually, 446 | an Abstract should begin with a phrase like "This memo ..." or "This document ..." 447 | A satisfactory Abstract can often be constructed in part from material within 448 | the Introduction section, but an effective Abstract may be shorter, less 449 | detailed, and perhaps broader in scope than the Introduction. Simply copying 450 | and pasting the first few paragraphs of the Introduction is allowed, but it may 451 | result in an Abstract that is overly long, incomplete, and redundant. 452 | An Abstract is not a substitute for an Introduction; the RFC should be 453 | self-contained as if there were no Abstract. Similarly, the Abstract should be 454 | complete in itself. Given that the Abstract will appear independently in 455 | announcements and indices, mentions of other RFCs within the Abstract should 456 | include both an RFC number and either the full or short title. Any documents 457 | that are Updated or Obsoleted by the RFC must be mentioned in the Abstract if those 458 | documents offer important provisions of, or reasons for, the RFC. 459 | These may be presented in a list format if that improves readability. 460 |
461 |
462 | RFC Editor or Stream Notes Section 463 | A stream-approving body may approve the inclusion of an editorial 464 | note to explain anything unusual about the process that led to the 465 | document's publication or to note a correction. In this case, a 466 | stream note section will contain such a note. 467 | Additionally, an RFC Editor Note section may contain a note inserted 468 | by the RFC Editor to highlight special circumstances surrounding 469 | an RFC. 470 |
471 |
472 | Status of This Memo Section 473 | The RFC Editor will supply an appropriate "Status of This Memo" as 474 | defined in RFC [RFC7841] and "Format for RFCs in the IAB Stream" 475 | . 476 |
477 |
478 | Copyright, Licenses, and IPR Boilerplate Section 479 | The full copyright and license notices are available on the IETF 480 | Trust Legal Provisions documents website . 481 |
482 |
483 | Table of Contents Section 484 | A Table of Contents (TOC) is required in all RFCs. It must be 485 | positioned after the Copyright Notice and before the Introduction. 486 |
487 |
488 | Body of the Memo 489 | Following the TOC is the body of the memo. 490 | Each RFC must include an Introduction section that (among other 491 | things) explains the motivation for the RFC and (if appropriate) 492 | describes the applicability of the document, e.g., whether it 493 | specifies a protocol, provides a discussion of some problem, is 494 | simply of interest to the Internet community, or provides a status 495 | report on some activity. The body of the memo and the Abstract must 496 | be self-contained and separable. This may result in some duplication 497 | of text between the Abstract and the Introduction; this is 498 | acceptable. 499 |
500 | Introduction Section 501 | The Introduction section should always be the first section following 502 | the TOC (except in the case of MIB module documents). While 503 | "Introduction" is recommended, authors may choose alternate titles 504 | such as "Overview" or "Background". These alternates are acceptable. 505 | For MIB module documents, common practice has been for "The 506 | Internet-Standard Management Framework" text to appear 507 | as Section 1. 508 |
509 |
510 | Requirements Language Section 511 | Some documents use certain capitalized words ("MUST", "SHOULD", etc.) 512 | to specify precise requirement levels for technical features. 513 | RFC 2119 defines a default interpretation of these 514 | capitalized words in IETF documents. If this interpretation is used, 515 | RFC 2119 must be cited (as specified in RFC 2119) and included as a 516 | normative reference. Otherwise, the correct interpretation must be 517 | specified in the document. 518 | This section must appear as part of the body of the memo (as defined 519 | by this document). It must appear as part of, or subsequent to, the 520 | 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: 525 | Imperatives of the type defined in this memo must be used with 526 | care and sparingly. In particular, they MUST only be used where 527 | it is actually required for interoperation or to limit behavior 528 | which has potential for causing harm (e.g., limiting 529 | retransmisssions) For example, they must not be used to try to 530 | impose a particular method on implementers where the method is not 531 | required for interoperability. 532 |
533 |
534 | IANA Considerations Section 535 | For guidance on how to register IANA-related values or create new 536 | registries to be managed by IANA, see "Guidelines for Writing an IANA 537 | Considerations Section in RFCs" . 538 | The RFC Editor will update text accordingly after the IANA 539 | assignments have been made. It is helpful for authors to clearly 540 | identify where text should be updated to reflect the newly assigned 541 | values. For example, the use of "TBD1", "TBD2", etc., is recommended 542 | in the IANA Considerations section and in the body of the memo. 543 | If the authors have provided values to be assigned by IANA, the 544 | RFC Editor will verify that the values inserted by the authors match 545 | those that have actually been registered on the IANA site. When 546 | writing a given value, consistent use of decimal or hexadecimal is 547 | recommended. 548 | If any of the IANA-related information is not clear, the RFC Editor 549 | will work with IANA to send queries to the authors to ensure that 550 | assignments and values are properly inserted. 551 |
552 |
553 | Internationalization Considerations Section 554 | All RFCs that deal with internationalization issues should have a 555 | section describing those issues; see "IETF Policy on Character Sets 556 | and Languages" , Section 6, for more information. 557 |
558 |
559 | Security Considerations Section 560 | All RFCs must contain a section that discusses the security 561 | considerations relevant to the specification; see "Guidelines for 562 | Writing RFC Text on Security Considerations" for more 563 | information. 564 | Note that additional boilerplate material for RFCs containing MIB and 565 | YANG modules also exists. See "Security Guidelines for IETF MIB 566 | Modules" and "yang module security considerations" 567 | for details. 568 |
569 |
570 | References Section 571 | The reference list is solely for recording reference entries. 572 | Introductory text or annotations beyond necessary translations are not allowed. 573 | The RFC style allows the use of any of a variety of reference styles, 574 | as long as they are used consistently within a document. However, 575 | where necessary, some reference styles have been described for use 576 | within the Series. See the following subsections as well as the References 577 | section of this document. 578 | Reference lists must indicate whether each reference is normative or 579 | informative, where normative references are essential to implementing 580 | or understanding the content of the RFC and informative references 581 | provide additional information. More information about normative and 582 | informative references may be found in the IESG's statement 583 | "Normative and Informative References" . When both normative 584 | and informative references exist, the references section should be 585 | split into two subsections: 586 | Templates are available on the RFC Editor website for the XML format of 587 | certain references . 588 | s. References 589 | s.1. Normative References 590 | 595 | s.2. Informative References 596 | 601 | References will generally appear in alphanumeric order by citation 602 | tag. Where there are only normative or informative references, no 603 | subsection is required; the top-level section should say "Normative 604 | References" or "Informative References". 605 | Normative references to Internet-Drafts will cause publication of the 606 | RFC to be suspended until the referenced draft is also ready for 607 | publication; the RFC Editor will then update the entry to refer to 608 | the RFC and publish both documents simultaneously. 609 |
610 | Referencing RFCs 611 | The following format is required for referencing RFCs. The Stream 612 | abbreviation should be used; when no stream is available, as with legacy RFCs, 613 | this may be left blank. 614 | Note the ordering for multiple authors: the format of 615 | the name of the last author listed is different than that of all previous 616 | authors in the list. 617 | For one author or editor: 618 | [RFCXXXX] Last name, First initial., Ed. (if applicable), 619 | "RFC Title", Stream, Sub-series number (if applicable), 620 | RFC number, RFC DOI, Date of publication, 621 | <https://www.rfc-editor.org/info/rfc#>. 622 | Example: 623 | [RFC3080] Rose, M., "The Blocks Extensible Exchange 624 | Protocol Core," IETF, RFC 3080, DOI 10.17487/RFC3080, March 2001, 625 | <https://www.rfc-editor.org/info/rfc3080>. 626 | [RFC8157] Leymann, N., Heidemann, C., Zhang, M., Sarikaya, B., and M. 627 | Cullen, "Huawei's GRE Tunnel Bonding Protocol", independent, 628 | RFC 8157, DOI 10.17487/RFC8157, May 2017, 629 | <https://www.rfc-editor.org/info/rfc8157>. 630 | For two authors or editors: 631 | [RFCXXXX] Last name, First initial., Ed. (if applicable) 632 | and First initial. Last name, Ed. (if applicable), 633 | "RFC Title", Stream, Sub-series number (if applicable), 634 | RFC number, RFC DOI, Date of publication, 635 | <https://www.rfc-editor.org/info/rfc#>. 636 | Example: 637 | [RFC6323] Renker, G. and G. Fairhurst, "Sender RTT 638 | Estimate Option for the Datagram Congestion 639 | Control Protocol (DCCP)", IETF, RFC 6323, DOI 10.17487/RFC6323, July 2011, 640 | <https://www.rfc-editor.org/info/rfc6323>. 641 | For three or more authors or editors: 642 | [RFCXXXX] Last name, First initial., Ed. (if applicable), 643 | Last name, First initial., Ed. (if applicable), 644 | and First initial. Last name, Ed. (if applicable), 645 | "RFC Title", Stream, Sub-series number (if applicable), 646 | RFC number, RFC DOI, Date of publication, 647 | <https://www.rfc-editor.org/info/rfc#>. 648 | Example: 649 | [RFC6429] Bashyam, M., Jethanandani, M., and A. Ramaiah, 650 | "TCP Sender Clarification for Persist 651 | Condition", IETF, RFC 6429, DOI 10.17487/RFC6429, December 2011, 652 | >https://www.rfc-editor.org/info/rfc6429 <. 653 |
654 |
655 | Referencing RFC(s) in a Subseries (STDs, BCPs, and FYIs 656 | Internet Standards (STDs) and Best Current Practices (BCPs) may consist of 657 | a single RFC or multiple RFCs. Authors should carefully consider whether they 658 | want to point the reader to the specific RFC or the sub series group. In the 659 | former case, references should appear as described in Section 660 | 4.8.6.2. In the latter case, the sub series number should take precedence as, 661 | for example, the citation tag, even in cases where the sub series currently 662 | contains only one RFC. 663 | When an STD or BCP that contains multiple RFCs is referenced as a sub series 664 | group, the reference entry should include ALL of the RFCs comprising that 665 | sub-series in a reference grouping under a single citation tag [is it helpful to 666 | point them to 7991 or the like on how to do this here?]. The authors should 667 | refer to the specific RFC numbers as part of the text in the body of the 668 | document and cite the sub series number (for example, "see RFC 2119 of 669 | [BCP14]"). Inclusion of the URI to the STD or BCP info page (see Section 3.2.3 670 | of [RFC5741]) is recommended. The text should appear as follows: 671 | See RFC 1034 [STD13]. 672 | For an STD or BCP that contains one RFC: 673 | [STDXXX] Last name, First initial., Ed. (if applicable), "RFC 674 | Title", Stream, Sub-series number, RFC number, RFC DOI, Date of 675 | publication, <https://www.rfc-editor.org/info/std#>. 676 | Example: 677 | [STD72] Gellens, R. and J. Klensin, "Message Submission 678 | for Mail", IETF, STD 72, RFC 6409, DOI 10.17487/RFC6409, November 2011, 679 | <https://www.rfc-editor.org/info/std72>. 680 | For an STD or BCP that contains two or more RFCs: 681 | [STDXXX] Last name, First initial., Ed. (if applicable), 682 | "RFC Title", Stream, Sub-series number, RFC number, RFC DOI, Date 683 | of publication. 684 | 691 | ]]> 692 | Example: 693 | [STD13] Mockapetris, P., "Domain names - concepts and 694 | facilities", IETF, STD 13, RFC 1034, November 1987. 695 | 701 | ]]> 702 | Note - some RFCs contain an FYI sub-series number however, the FYI 703 | series was ended by RFC 6360. RFCs that were published with an FYI sub-series 704 | number and still maintain the FYI number must include the sub-series number in 705 | the reference and may otherwise be treated in the same manner as STDs and 706 | BCPs. 707 | Grouping references to RFCs or other materials that are not part of a 708 | sub-series is discouraged. 709 |
710 |
711 | Referencing Internet-Drafts 712 | References to Internet Drafts may only appear as informative 713 | references. Given that several revisions of an I-D may be produced 714 | in a short time frame, references must include the posting date 715 | (month and year), the full Internet-Draft file name (including the 716 | version number), and the phrase "Internet Draft". Authors may 717 | reference multiple versions of an I-D. If the referenced I-D was 718 | also later published as an RFC, then that RFC must also be listed. 719 | The reference should include a stable URL for the draft, if available. 720 | [SYMBOLIC-TAG] Last name, First initial., Ed. (if applicable) 721 | and First initial. Last name, Ed. (if 722 | applicable), "I-D Title", Work in Progress, Internet-Draft, 723 | draft-string-NN, Day Month Year, https://datatracker.ietf.org/doc/html/draft-something. 724 | 725 | Example: 726 | [RFC-STYLE] Flanagan, H. and S. Ginoza, "RFC Style Guide", Work in Progress, 727 | Internet-Draft, draft-flanagan-style-04, 728 | 27 September 2019, https://datatracker.ietf.org/doc/html/draft-flanagan-style-04. 729 | 730 |
731 |
732 | Referencing Errata 733 | The following format is required when a reference to an erratum 734 | report is necessary: 735 | [ErrNumber] RFC Errata, Erratum ID number, RFC number, <https://www.rfc-editor.org/errata/eid#>. 736 | [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, <https://www.rfc-editor.org/errata/eid1912>. 737 |
738 |
739 | Referencing IANA Registries 740 | IANA registries may appear in normative or informative reference sections. 741 | 742 | [IANA-SYMBOLIC-TAG] 743 | 744 |
    745 |
  • IANA, "Registry Name", <URL>.
  • 746 |
747 |
748 |
749 | Referencing Other Standards Development Organizations (SDOs) 750 | The following format is suggested when referencing a document or 751 | standard from another SDO in which authors are listed: 752 | [SYMBOLIC-TAG] 753 | 754 |
    755 |
  • Last name, First initial. and First initial. Last name,
  • 756 |
  • "Document Title", Document reference number, Date of
  • 757 |
  • publication, <URI if available>.
  • 758 |
759 | [W3C.REC-xml11] 760 | 761 |
    762 |
  • Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E.,
  • 763 |
  • Yergeau, F., and J. Cowan, "Extensible Markup Language
  • 764 |
  • (XML) 1.1 (Second Edition)", W3C Recommendation
  • 765 |
  • REC-xml11-20060816, August 2006,
  • 766 |
  • <https://www.w3.org/TR/2006/REC-xml11-20060816>.
  • 767 |
768 | The order of authors in the list is the same as the order 769 | shown on the actual document and that the common, abbreviated form of 770 | the SDO is used. 771 | Alternatively, when no list of authors is available, the following 772 | format is recommended: 773 | . 776 | ]]> 777 | Example (undated; see note below): 778 | . 782 | ]]> 783 | Example (dated; see note below): 784 | 790 | ]]> 791 | Per the IEEE coordination team, listing dates for IEEE standards is not 792 | recommended unless there is a need to cite a particular section, in which case 793 | the dated reference is appropriate. An RFC with a dated IEEE reference suggests 794 | that the RFC only applies to that specific IEEE specification. 795 |
796 |
797 | Referencing Webpages 798 | References to webpages acceptable in either the normative or informative 799 | sections, as long as the URL provided is the most stable (i.e., unlikely to 800 | change and expected to be continuously available) and direct reference 801 | possible. The URL will be verified as valid during the RFC editorial process. 802 | If a dated URI (one that includes a timestamp for the page) is 803 | available for a referenced web page, its use is required. 804 | Note that the URL may not be the sole information provided for a 805 | reference entry. 806 | The use of HTTPS rather than HTTP is strongly encouraged. 807 | Example: 808 | [SYMBOLIC-TAG] Author (if available), "Page Title (if available)", <URL>. 809 | 812 | ]]> 813 |
814 |
815 | Referencing Email on Mailing Lists 816 | When referencing emails to mailing lists, the template provided here should be used: 817 | 818 |
    819 |
  • [reftag] Sender, A., "Subject: Subject line", message to the
  • 820 |
  • listname mailing list, DD Month YYYY, <URL>.
  • 821 |
822 |
823 |
824 | Referencing Code Repositories 825 | References to online code repositories such as GitHub or SourceForge 826 | should be used as informative references only. The reference entry should 827 | include the repository title, commit hash or similar release marker if 828 | available, date of last commit, and URL. 829 | Examples: 830 | . 832 | 833 | [linuxlite] "Linux Lite", 9 March 2018, 834 | . 835 | ]]> 836 |
837 |
838 |
839 |
840 | Appendices Section 841 | The RFC Editor recommends placing references before the Appendices. 842 | Appendices should be labeled as "Appendix A. Title", "A.1. Title", 843 | "Appendix B. Title", etc. 844 |
845 |
846 | Acknowledgements Section 847 | This optional section may be used instead of, or in addition to, a 848 | Contributors section. It is often used by authors to publicly thank 849 | those who have provided feedback regarding a document and to note any 850 | documents from which text was borrowed. 851 |
852 |
853 | Contributors Section 854 | This optional section acknowledges those who have made significant 855 | contributions to the document. 856 | In a similar fashion to the Author's Address section, the RFC Editor 857 | does not make the determination as to who should be listed as a 858 | contributor to an RFC. The determination of who should be listed as 859 | a contributor is made by the stream. 860 | The Contributors section may include brief statements about the 861 | nature of particular contributions (e.g., "Sam contributed Section 3"), and 862 | it may also include affiliations of listed contributors. At the 863 | discretion of the author(s), contact addresses may also be included 864 | in the Contributors section, for those contributors whose knowledge 865 | makes them useful future contacts for information about the RFC. The 866 | format of any contact information should be similar to the format of 867 | information in the Author's Address section. 868 |
869 |
870 | Index 871 | If included, an index appears at the end of the document, immediately 872 | before Author's Address section. 873 |
874 |
875 | Author's Address or Authors' Addresses Section 876 | This required section gives contact information for the author(s) 877 | listed in the first-page header. 878 | Contact information must include a long-lived email address and 879 | optionally may include a postal address and/or telephone number. If 880 | the postal address is included, it should include the country name, 881 | using the English short name listed by the ISO 3166 Maintenance 882 | Agency . The purpose of this section is to 883 | (1) unambiguously define author identity (e.g., the John Smith who 884 | works for FooBar Systems) and (2) provide contact information for 885 | future readers who have questions or comments. 886 | The practice of munged email addresses (i.e., altering an email 887 | address to make it less readable to bots and web crawlers to avoid 888 | spam) is not appropriate in an archival document series. Author 889 | contact information is provided so that readers can easily contact 890 | the author with questions and/or comments. Address munging is not 891 | allowed in RFCs. 892 |
893 |
894 |
895 | Security Considerations 896 | This document has no security considerations. 897 |
898 |
899 | IANA Considerations 900 | This document has no IANA considerations. 901 |
902 |
903 | Change Log 904 | This section to be removed before publication. 905 | 906 |
    907 |
  • -00 to -01: Citation tag requirements more tightly specified; index 908 | moved; new errata URI added; capitalization of working/research group 909 | specified
  • 910 |
  • -01 to -02: update Abstract guidance
  • 911 |
  • -02 to -03: updated citation section; changed list styles; added angle 912 | brackets to reference examples; changed I-D reference format; clarified 913 | sub-series reference format; added guidance on referencing code 914 | repositories
  • 915 |
  • -03 to -04: updated Reference Section guidance; added information on alt text
  • 916 |
  • -04 to -05: change author, add acknowledgement
  • 917 |
918 |
919 |
920 | 921 | 922 | References 923 | 924 | Normative References 925 | 926 | 927 | Web Portion of the Style Guide 928 | 929 | RFC Editor 930 | 931 | 932 | 933 | 934 | 935 | 936 | Informative References 937 | 938 | 939 | RFC Editor Abbreviations List 940 | 941 | RFC Editor 942 | 943 | 944 | 945 | 946 | 947 | 948 | Understanding Success Criterion 1.3.1: Info and Relationships 949 | 950 | W3C 951 | 952 | 953 | 954 | 955 | 956 | 957 | Key words for use in RFCs to Indicate Requirement Levels 958 | 959 | 960 | 961 | 962 | 963 | 964 | 965 | 966 | IETF Policy on Character Sets and Languages 967 | 968 | 969 | 970 | 971 | 972 | 973 | 974 | 975 | Guidelines for Writing an ANA Considerations Section in RFCs 976 | 977 | 978 | 979 | 980 | 981 | 982 | 983 | 984 | 985 | Reserved Top Level DNS Names 986 | 987 | 988 | 989 | 990 | 991 | 992 | 993 | 994 | 995 | Guidelines for Writing RFC Text on Security Considerations 996 | 997 | 998 | 999 | 1000 | 1001 | 1002 | 1003 | 1004 | 1005 | Clusters in the RFC Editor Queue 1006 | 1007 | RFC Editor 1008 | 1009 | 1010 | 1011 | 1012 | 1013 | 1014 | Chicago Manual of Style, 16th ed. 1015 | 1016 | University of Chicago Press, 2010 1017 | 1018 | 1019 | 1020 | 1021 | 1022 | 1023 | FYI on FYI: Introduction to the FYI Notes 1024 | 1025 | 1026 | 1027 | 1028 | 1029 | 1030 | 1031 | Housley, R., "Conclusion of FYI RFC Sub-Series", RFC 6360, 1032 | August 2011. 1033 | 1034 | 1035 | 1036 | 1037 | Format for RFCs in the IAB Stream 1038 | 1039 | IAB 1040 | 1041 | 1042 | 1043 | 1044 | 1045 | 1046 | Guidelines to Authors of Internet Drafts 1047 | 1048 | IETF 1049 | 1050 | 1051 | 1052 | 1053 | 1054 | 1055 | Trust Legal Provisions (TLP) 1056 | 1057 | IETF Trust 1058 | 1059 | 1060 | 1061 | 1062 | 1063 | 1064 | Online Browsing Platform (OBP) 1065 | 1066 | ISO 1067 | 1068 | 1069 | 1070 | 1071 | 1072 | 1073 | Identification and description, Information and documentation - International standard serial number (ISSN) 1074 | 1075 | Technical Committee ISO/TC 46, Information and documentation, Subcommittee SC 9 1076 | 1077 | 1078 | 1079 | 1080 | 1081 | 1082 | 1083 | Boilerplate for IETF MIB Documents 1084 | 1085 | IETF OPS Area 1086 | 1087 | 1088 | 1089 | 1090 | 1091 | 1092 | Security Guidelines for IETF MIB Modules 1093 | 1094 | IETF OPS Area 1095 | 1096 | 1097 | 1098 | 1099 | 1100 | 1101 | Reference Examples 1102 | 1103 | RFC Editor 1104 | 1105 | 1106 | 1107 | 1108 | 1109 | 1110 | IESG Statement: Normative and Informative 1111 | 1112 | IESG 1113 | 1114 | 1115 | 1116 | 1117 | 1118 | 1119 | The RFC Series and RFC Editor 1120 | 1121 | 1122 | 1123 | 1124 | Internet Architecture Board 1125 | 1126 | 1127 | 1128 | This document describes the framework for an RFC Series and an RFC Editor function that incorporate the principles of organized community involvement and accountability that has become necessary as the Internet technical community has grown, thereby enabling the RFC Series to continue to fulfill its mandate. This memo provides information for the Internet community. 1129 | 1130 | 1131 | 1132 | 1133 | 1134 | 1135 | 1136 | RFC Streams, Headers, and Boilerplates 1137 | 1138 | 1139 | 1140 | 1141 | 1142 | 1143 | 1144 | 1145 | 1146 | 1147 | 1148 | RFC documents contain a number of fixed elements such as the title page header, standard boilerplates, and copyright/IPR statements. This document describes them and introduces some updates to reflect current usage and requirements of RFC publication. In particular, this updated structure is intended to communicate clearly the source of RFC creation and review. This document obsoletes RFC 5741, moving detailed content to an IAB web page and preparing for more flexible output formats. 1149 | 1150 | 1151 | 1152 | 1153 | 1154 | 1155 | 1156 | RFC Editor Model (Version 2) 1157 | 1158 | 1159 | 1160 | 1161 | 1162 | 1163 | 1164 | IAB 1165 | 1166 | 1167 | 1168 | The RFC Editor model described in this document divides the responsibilities for the RFC Series into three functions: the RFC Series Editor, the RFC Production Center, and the RFC Publisher. Internet Architecture Board (IAB) oversight via the RFC Series Oversight Committee (RSOC) is described, as is the relationship between the IETF Administrative Oversight Committee (IAOC) and the RSOC. This document reflects the experience gained with "RFC Editor Model (Version 1)", documented in RFC 5620, and obsoletes that document. This document is not an Internet Standards Track specification; it is published for informational purposes. 1169 | 1170 | 1171 | 1172 | 1173 | 1174 | 1175 | 1176 | RFC Format Framework 1177 | 1178 | 1179 | 1180 | 1181 | 1182 | In order to improve the readability of RFCs while supporting their archivability, the canonical format of the RFC Series will be transitioning from plain-text ASCII to XML using the xml2rfc version 3 vocabulary; different publication formats will be rendered from that base document. With these changes comes an increase in complexity for authors, consumers, and the publisher of RFCs. This document serves as the framework that provides the problem statement, lays out a road map of the documents that capture the specific requirements, and describes the transition plan. 1183 | 1184 | 1185 | 1186 | 1187 | 1188 | 1189 | 1190 | The "xml2rfc" Version 3 Vocabulary 1191 | 1192 | 1193 | 1194 | 1195 | 1196 | This document defines the "xml2rfc" version 3 vocabulary: an XML-based language used for writing RFCs and Internet-Drafts. It is heavily derived from the version 2 vocabulary that is also under discussion. This document obsoletes the v2 grammar described in RFC 7749. 1197 | 1198 | 1199 | 1200 | 1201 | 1202 | 1203 | 1204 | SVG Drawings for RFCs: SVG 1.2 RFC 1205 | 1206 | 1207 | 1208 | 1209 | 1210 | This document specifies SVG 1.2 RFC -- an SVG profile for use in diagrams that may appear in RFCs -- and considers some of the issues concerning the creation and use of such diagrams. 1211 | 1212 | 1213 | 1214 | 1215 | 1216 | 1217 | 1218 | The Use of Non-ASCII Characters in RFCs 1219 | 1220 | 1221 | 1222 | 1223 | 1224 | In order to support the internationalization of protocols and a more diverse Internet community, the RFC Series must evolve to allow for the use of non-ASCII characters in RFCs. While English remains the required language of the Series, the encoding of future RFCs will be in UTF-8, allowing for a broader range of characters than typically used in the English language. This document describes the RFC Editor requirements and gives guidance regarding the use of non-ASCII characters in RFCs. 1225 | This document updates RFC 7322. Please view this document in PDF form to see the full text. 1226 | 1227 | 1228 | 1229 | 1230 | 1231 | 1232 | 1233 | Uniform Resource Identifier (URI): Generic Syntax 1234 | 1235 | 1236 | 1237 | 1238 | 1239 | 1240 | 1241 | 1242 | 1243 | 1244 | Terms List 1245 | 1246 | RFC Editor 1247 | 1248 | 1249 | 1250 | 1251 | 1252 | 1253 | yang module security considerations 1254 | 1255 | IETF Ops Area 1256 | 1257 | 1258 | 1259 | 1260 | 1261 | 1262 | 1263 |
1264 | Related Procedures 1265 | The following procedures are related to the application and updating 1266 | of the RFC Style Guide. 1267 |
1268 | Dispute Resolution 1269 | There are competing rationales for some of the rules described in 1270 | this Guide, and the RFC Editor has selected the ones that work best 1271 | for the Series. However, at times, an author may have a disagreement 1272 | with the RFC Production Center (RPC) over the application of Style 1273 | Guide conventions. In such cases, the authors should discuss their 1274 | concerns with the RPC. If no agreement can be reached between the 1275 | RPC and the authors, the RFC Series Editor will, with input from the 1276 | appropriate stream-approving body, make a final determination. If 1277 | further resolution is required, the dispute resolution process as 1278 | described in the RFC Editor Model will be followed. 1279 |
1280 |
1281 | Returning an I-D to the Document Stream 1282 | For a given document, if the RFC Editor determines that it cannot be 1283 | edited without serious risk of altering the meaning of the technical 1284 | content or if the RFC Editor does not have the resources to provide 1285 | the level of editing it needs, it may be sent back to the stream- 1286 | approving body with a request to improve the clarity, consistency, 1287 | and/or readability of the document. This is not to be considered a 1288 | dispute with the author. 1289 |
1290 |
1291 | Revising This Document and Associated Web Pages 1292 | The RFC Series is continually evolving as a document series. This 1293 | document focuses on the fundamental and stable requirements that must 1294 | be met by an RFC. From time to time, the RFC Editor may offer less 1295 | formal recommendations that authors may apply at their discretion; 1296 | these recommendations may be found on the RFC Editor website 1297 | "Guidelines for RFC Style" . 1298 | When a new recommendation is made regarding the overall structure and 1299 | formatting of RFCs, it will be published on that page and accepted 1300 | for a period of time before the RFC Editor determines whether it 1301 | should become part of the fundamental requirements in the RFC Style 1302 | Guide or remain as a less formal recommendation. That period of time 1303 | will vary, in part depending on the frequency with which authors 1304 | encounter and apply the guidance. 1305 |
1306 |
1307 |
1308 | Acknowledgements 1309 | Much of this document was written by Heather Flanagan during her term as RFC Editor. 1310 |
1311 |
1312 |
1313 | -------------------------------------------------------------------------------- /draft-rpc-rfc7322bis.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 5 | 6 | 7 | 8 | ]> 9 | 10 | 11 | 12 | RFC Style Guide 13 | 14 | 15 | RFC Production Center 16 |
17 | sginoza@staff.rfc-editor.org 18 |
19 |
20 | 21 | 22 | RFC Production Center 23 |
24 | jmahoney@staff.rfc-editor.org 25 |
26 |
27 | 28 | 29 | RFC Production Center 30 |
31 | arusso@staff.rfc-editor.org 32 |
33 |
34 | 35 | 36 | 37 | 38 | This document describes the fundamental and unique style conventions 39 | and editorial policies currently in use for the RFC Series. It 40 | captures the RFC Editor's basic requirements and offers guidance 41 | regarding the style and structure of an RFC. Additional guidance is 42 | captured on a website that reflects the experimental nature of that 43 | guidance and prepares it for future inclusion in the RFC Style Guide. 44 | This document obsoletes RFC 7322, "RFC Style Guide". 45 | Note: This draft is being developed and discussed in the GitHub repo 46 | , 47 | but any substantive change should be discussed on . 48 | 49 |
50 | 51 |
52 | Introduction 53 | The ultimate goal of the RFC publication process is to produce 54 | documents that are readable, clear, and consistent. The basic formatting 55 | conventions for RFCs were established 56 | in the 1970s by the original RFC Editor, Jon Postel. This document 57 | describes the fundamental and unique style conventions and editorial 58 | policies currently in use for the RFC Series and is 59 | intended as a stable, infrequently updated reference for authors, 60 | editors, and reviewers. 61 | The RFC Editor also maintains a web portion of the Style Guide (see 62 | Appendix A.3) that describes issues as they are raised and indicates 63 | how the RFC Editor intends to address them. As new style issues 64 | arise, the RFC Editor will first address them on the web portion of 65 | the Style Guide . These topics may become part of the RFC 66 | Style Guide when it is revised. 67 | The world of publishing has generally accepted rules for 68 | grammar, punctuation, capitalization, sentence length and complexity, etc. 69 | The RFC Editor generally follows these accepted 70 | rules as defined by the Chicago Manual of Style (CMOS) , with a 71 | few important exceptions to avoid ambiguity in complex technical 72 | prose and to handle mixtures of text and computer languages, or to 73 | preserve historical formatting rules. This document presents these 74 | exceptions as applied or recommended by the RFC Editor. 75 | All RFCs begin as Internet-Drafts (also referred to as I-Ds), and a 76 | well-written and properly constructed Internet-Draft 77 | provides a strong basis for a good RFC. The RFC Editor accepts 78 | Internet-Drafts from specified streams for publication [RFC4844] and 79 | applies the rules and guidelines for the RFC Series during the 80 | editorial process. 81 |
82 |
83 | RFC Editor's Philosophy 84 | Authors may find it helpful to understand the RFC Editor's goals 85 | during the publication process, namely to: 86 |
    87 |
  • Prepare the document according to RFC style and format.
  • 88 |
  • Make the document as clear, consistent, and readable as possible.
  • 89 |
  • Correct larger content/clarity issues; flag any unclear passages 90 | for author review.
  • 91 |
  • Fix inconsistencies (e.g., terms that appear in various forms, 92 | inconsistent capitalization, discrepancies between a figure and the text that 93 | describes it).
  • 94 |
95 | We strive for consistency within: 96 | a. the document, 97 | b. a cluster of documents , and 98 | c. the series of RFCs on the subject matter. 99 | The editorial process of the RFC Editor is not an additional 100 | technical review of the document. Where the RFC Editor may suggest 101 | changes in wording for clarity and readability, it is up to the 102 | author, working group, or stream-approving body to determine whether 103 | the changes have an impact on the technical meaning of the document 104 | [RFC4844]. If the original wording is a more accurate representation 105 | of the technical content being described in the document, it takes 106 | precedence over editorial conventions. 107 | The activity of editing sometimes creates a tension between author 108 | and editor. The RFC Editor attempts to minimize this conflict for 109 | RFC publication while continually striving to produce a uniformly 110 | excellent document series. The RFC Editor refers to this fundamental 111 | tension as "editorial balance," and maintaining this balance is a 112 | continuing concern for the RFC Editor. There is a prime directive 113 | that must rule over grammatical conventions: do not change the 114 | intended meaning of the text. 115 | If the RFC Editor cannot edit a document without serious risk of 116 | altering the meaning, it may be returned to the stream-approving body 117 | for review. See Appendix A.2 for more information. 118 |
119 |
120 | RFC Style Conventions 121 | This Style Guide does not use terminology as defined in and . In this document, lowercase use of "must" and "should" 122 | indicates changes the RFC Editor will make automatically to conform 123 | with this Style Guide versus those that may be questioned if not 124 | applied. The lowercase "must" indicates those changes that will be 125 | applied automatically and are not at the discretion of the authors. 126 | The lowercase "should" indicates the RFC Editor's recommended use, 127 | but conformance with the recommendations is not required; the RFC 128 | Editor may question whether the guidance may be applied. 129 |
130 | Language 131 | The RFC publication language is English. Spelling may be either 132 | American or British, as long as an individual document is internally 133 | consistent. Where both American and British English spelling are 134 | used within a document or cluster of documents, the text will be 135 | modified to be consistent with American English spelling. 136 |
137 |
138 | Punctuation 139 |
  1. 140 | A comma is used before the last item of a series, e.g., 141 | 142 | "TCP service is reliable, ordered, and full duplex" 143 |
  2. 144 |
  3. 145 | When quoting literal text, punctuation is placed outside quotation 146 | marks, e.g., 147 | 148 | Search for the string "Error Found". 149 | 150 | When quoting general text, such as general text from another RFC, 151 | punctuation may be included within the quotation marks, e.g., 152 | 153 | RFC 4844 indicates that "RFCs are available free of charge to 154 | anyone via the Internet." 155 | 156 | Quotation marks are not necessary when text is formatted as a 157 | block quotation. 158 |
  4. 159 |
160 |
161 | RFC Citations as Compounds 162 | Whenever possible: 163 | 164 |
    165 |
  • Hyphenated compounds formed with RFC numbers should be avoided; 166 | this can be accomplished by: rewording the sentence (e.g., change "[RFC5011]-style 167 | rollover" to "rollover as described in RFC 5011 [RFC5011]").
  • 168 |
  • adding a note in either the Terminology or Conventions section mentioning 169 | the RFC so that other occurrences throughout the text will be understood by 170 | the reader to be in the style of said RFC (e.g., This document uses the term 171 | "rollover" as defined in RFC 5011.).
  • 172 |
173 | If use of an RFC number in attributive position is unavoidable, the 174 | preferred form should appear as in the example "RFC 5011-style rollover". 175 | That is: 176 | 177 |
    178 |
  • no hyphen between "RFC" and the number (don't use RFC-5011-style rollover)
  • 179 |
  • avoid hyphenating citations with text (don't use [RFC5011]-style rollover)
  • 180 |
181 |
182 |
183 |
184 | DNS Names and URIs 185 | DNS names, whether or not in URIs, that are used as generic examples 186 | in RFCs should use the particular examples defined in "Reserved Top 187 | Level DNS Names" , to avoid accidental conflicts. 188 | Angle brackets are strongly recommended around URIs , e.g., 189 | <https://example.com/> 190 | The use of HTTPS rather than HTTP is strongly encouraged. 191 |
192 |
193 | Capitalization 194 |
  1. Capitalization must be consistent within the document and ideally 195 | should be consistent with related RFCs. Refer to the online table 196 | of decisions on consistent usage of terms in RFCs .
  2. 197 |
  3. Per CMOS guidelines, the major words in RFC titles and section 198 | titles should be capitalized (this is sometimes called "title 199 | case"). Typically, all words in a title will be capitalized, 200 | except for internal articles, prepositions, and conjunctions.
  4. 201 |
  5. Section titles that are in sentence form will follow typical 202 | sentence capitalization.
  6. 203 |
  7. Titles of figures may be in sentence form or use title case.
  8. 204 |
  9. Some terms related to the various roles or parts of the streams authoring 205 | RFCs should be used consistently. For example, when the term 'working group' 206 | or 'research group' is used as part of a 207 | specific group name, it will be capitalized (e.g., kitten Working Group, 208 | Crypto Forum Research Group). When used to generally refer to groups, it 209 | will be downcased.
  10. 210 |
211 |
212 |
213 | Citations 214 | The most important function of a citation is to point to a reference so that 215 | a reader may follow up on additional material that is important in some way to 216 | understanding or implementing the content in an RFC. This section offers guidance 217 | on the requirements and recommendations for citation format within an RFC. 218 |
  1. References and citations must match. That is, there must be a 219 | reference for each citation used, and vice versa.
  2. 220 |
  3. Citations must be enclosed in square brackets (e.g., "[CITE1]").
  4. 221 |
  5. Citations are restricted to ASCII-only characters, as described in "The Use 222 | of Non-ASCII Characters in RFCs" .
  6. 223 |
  7. 224 | Citations must begin with a number or a letter, and may contain digits, letters, 225 | colons, hyphens, underscores, or dots. 226 | 227 |
      228 |
    • Example: "[IEEE.802.15.4]" rather than "[.802.15.4]"
    • 229 |
    • Example: "[RFC2119]" rather than "[RFC 2119]"
    • 230 |
    231 |
  8. 232 |
  9. 233 | Citations may not include spaces, commas, quotation marks, or other 234 | punctuation (!, ?, etc.), and should be in-line with the normal line of type. 235 | 236 |
      237 |
    • Example: "See RFC 2119 for more information."
    • 238 |
    239 |
  10. 240 |
  11. Cross-references within the body of the memo and to other RFCs 241 | must use section numbers rather than page numbers, as pagination 242 | may change per format and device.
  12. 243 |
  13. 244 | A citation may A) follow the subject to which the citation applies 245 | or B) be read as part of the text. For example: 246 | 247 |
    1. As part of the transition to IPv6, NAT64 [RFC6146] and DNS64 248 | [RFC6147] technologies will be utilized by some access networks to 249 | provide IPv4 connectivity for IPv6-only nodes [RFC6144].
    2. 250 |
    3. Note that SAVI raises a number of important privacy considerations 251 | that are discussed more fully in [RFC6959].
    4. 252 |
    253 |
  14. 254 |
  15. For a document referenced multiple times in running text, the citation anchor must 255 | be at first use outside the abstract. Additional citations are allowed at the author's 256 | discretion.
  16. 257 |
258 | We recommend using A) and strongly recommend consistent use of one style throughout. 259 |
260 |
261 | Abbreviation Rules 262 | Abbreviations should be expanded in document titles and upon first 263 | use in the document. It may be appropriate to include an Abbreviations or Terminology section if the document introduces abbreviations and concepts that are relied on heavily throughout the document. Note that abbreviations should be still be expanded in the body of the document if "first use" appears prior to the Abbeviations/Terminology section. The full expansion of the text should be 264 | followed by the abbreviation itself in parentheses. The exception is 265 | an abbreviation that is so common that the readership of RFCs can be 266 | expected to recognize it immediately; examples include (but are not 267 | limited to) TCP, IP, SNMP, and HTTP. The online list of 268 | abbreviations provides guidance. Some cases are marginal, and 269 | the RFC Editor will make the final judgment, weighing obscurity 270 | against complexity. 271 | Note: The online list of abbreviations is not exhaustive or 272 | definitive. It is a list of abbreviations appearing in RFCs and 273 | sometimes reflects discussions with authors, Working Group Chairs, 274 | and/or Area Directors (ADs). Note that some abbreviations have 275 | multiple expansions. Additionally, this list includes some terms 276 | that look like abbreviations but that are actually fixed names for 277 | things and hence cannot and should not be expanded. These are 278 | noted as "No Expansion". 279 |
280 |
281 | Images and Figures 282 | The goal of having images within an RFC is to convey information. A good 283 | diagram or image expresses information quickly, clearly, and with low chance 284 | of misunderstanding. Technically correct but confusing images get in the 285 | way of understanding and implementation. 286 |
  1. Images should be legible when displayed on a standard screen (1920x1080) 287 | and printable on either A4 or US Letter paper. Any text within the diagram 288 | should be readable at that resolution.
  2. 289 |
  3. Authors should use black on white, not white on black. No color or 290 | greyscale
  4. 291 |
  5. Keep your diagrams as simple as possible. If an object in the diagram 292 | is not immediately relevant, leave it out. If you have several ideas you 293 | want to convey, consider using more than one diagram.
  6. 294 |
  7. San-serif fonts are generally considered more readable for digital 295 | material. [citation needed]
  8. 296 |
  9. The style of diagrams within an RFC should be consistent both within a 297 | single RFC and within a cluster of RFCs (fonts, shapes, 298 | lines). For example, if you you use a dashed line to indicate a certain 299 | type of packet flow, then continue to use that style of line consistently. 300 |
  10. 301 |
  11. Line styles, including thickness, color, and arrow types, are easy 302 | methods to convey a particular meaning to the reader. Consistently use 303 | the same line styles to convey a particular meaning throughout all 304 | diagrams within an RFC in order to avoid confusing the reader.
  12. 305 |
  13. Flowcharts: avoid crossing the lines if possible.
  14. 306 |
  15. Captions or alternative text are encouraged for all figures, diagrams, 307 | and other artwork. 308 |
  16. 309 |
310 |
311 |
312 |
313 | Structure of an RFC 314 | A published RFC will largely contain the elements in the following 315 | list. Some of these sections are required, as noted. Those sections 316 | marked with "*" will be supplied by the RFC Editor during the 317 | editorial process when necessary. The rules for each of these elements are 318 | described in more detail below. 319 | 349 | Within the body of the memo, the order shown above is strongly 350 | recommended. Exceptions may be questioned. Outside the body of the 351 | memo, the order above is required. The section numbers above are for 352 | illustrative purposes; they are not intended to correspond to 353 | required numbering in an RFC. 354 | The elements preceding the body of the memo should not be numbered. 355 | Typically, the body of the memo will have numbered sections and the 356 | appendices will be labeled with letters. Any sections that appear 357 | after the appendices should not be numbered or labeled (e.g., see 358 | "Contributors" above). 359 |
360 | First-Page Header 361 | Headers will follow the format described in "RFC Streams, Headers, 362 | and Boilerplates" and its successors. In addition, the 363 | following conventions will apply. 364 |
365 | Author/Editor 366 | The final determination of who should be listed as an author or editor on 367 | an RFC is made by the stream, as is whether or not including author 368 | affiliation is required. 369 | The author's name (initial followed by family name) appears on the 370 | first line of the heading. Some variation, such as additional 371 | initials or capitalization of family name, is acceptable. 372 | It is recommended that an author name be consistent from RFC to RFC. 373 | However, an author may update their name on subsequent RFCs. 374 | The total number of authors or editors on the first page is generally 375 | limited to five individuals and their affiliations. If there is a 376 | request for more than five authors, the stream-approving body needs 377 | to consider if one or two editors should have primary responsibility 378 | for this document, with the other individuals listed in the 379 | Contributors or Acknowledgements section. There must be a direct 380 | correlation of authors and editors in the document header and the 381 | Authors' Addresses section. These are the individuals that must sign 382 | off on the document during the AUTH48 process and respond to 383 | inquiries, such as errata. 384 |
385 |
386 | Organization 387 | The author's organization is indicated on the line following the 388 | author's name. 389 | For multiple authors, each author name appears on its own line, 390 | followed by that author's organization. When more than one author is 391 | affiliated with the same organization, the organization can be 392 | "factored out," appearing only once following the corresponding 393 | Author lines. However, such factoring is inappropriate when it would 394 | force an unacceptable reordering of author names. 395 | If an author cannot or will not provide an affiliation for any 396 | reason, "Independent", "Individual Contributor", "Retired", or some 397 | other term that appropriately describes the author's affiliation may 398 | be used. Alternatively, a blank line may be included in the document 399 | header when no affiliation is provided. 400 |
401 |
402 | ISSN: 2070-1721 403 | The RFC Series has been assigned an International Standard Serial 404 | Number of 2070-1721 . It will be included by the 405 | RFC Editor. 406 |
407 |
408 | Digital Object Identifier 10.17487 409 | The RFC Series has been assigned a Digital Object Identifier prefix of 410 | 10.17487 . A DOI will be assigned and included by the 411 | RFC Editor. 412 |
413 |
414 | Updates and Obsoletes 415 | When an RFC obsoletes or updates a previously published RFC or RFCs, 416 | this information is included in the document header. For example: 417 | "Updates: nnnn" or "Updates: nnnn, ..., nnnn" 418 | "Obsoletes: nnnn" or "Obsoletes: nnnn, ..., nnnn" 419 | If the document updates or obsoletes more than one document, numbers 420 | will be listed in ascending order. 421 |
422 |
423 |
424 | Document Title 425 | The title must be centered below the rest of the heading, preceded by 426 | two blank lines and followed by one blank line. 427 | Choosing a good title for an RFC can be a challenge. A good title 428 | should fairly represent the scope and purpose of the document without 429 | being either too general or too specific and lengthy. 430 | Abbreviations in a title must generally be expanded when first 431 | encountered (see Section 3.6 for additional guidance on 432 | abbreviations). 433 | It is often helpful to follow the expansion with the parenthesized 434 | abbreviation, as in the following example: 435 | 439 | The RFC Editor recommends that documents describing a particular 440 | company's private protocol should bear a title of the form "Foo's ... 441 | Protocol" (where Foo is a company name), to clearly differentiate it 442 | from a protocol of more general applicability. 443 |
444 |
445 | Abstract Section 446 | Every RFC must have an Abstract that provides a concise and comprehensive 447 | overview of the purpose and contents of the entire document, to give a 448 | technically knowledgeable reader a general overview of the function of the 449 | document and some context with regards to its relationship (in particular, 450 | whether it updates or obsoletes) any other RFCs. In addition to its function in 451 | the RFC itself, the Abstract section text will appear in publication 452 | announcements and in the online index of RFCs. 453 | Composing a useful Abstract generally requires thought and care. Usually, 454 | an Abstract should begin with a phrase like "This memo ..." or "This document ..." 455 | A satisfactory Abstract can often be constructed in part from material within 456 | the Introduction section, but an effective Abstract may be shorter, less 457 | detailed, and perhaps broader in scope than the Introduction. Simply copying 458 | and pasting the first few paragraphs of the Introduction is allowed, but it may 459 | result in an Abstract that is overly long, incomplete, and redundant. 460 | An Abstract is not a substitute for an Introduction; the RFC should be 461 | self-contained as if there were no Abstract. Similarly, the Abstract should be 462 | complete in itself. Given that the Abstract will appear independently in 463 | announcements and indices, uncommon abbreviations should be expanded, and mentions of other RFCs within the Abstract should 464 | include both an RFC number and either the full or short title. It should not include in-text citations or refer to sections within the document. Any documents 465 | that are Updated or Obsoleted by the RFC must be mentioned in the Abstract if those 466 | documents offer important provisions of, or reasons for, the RFC. 467 | These may be presented in a list format if that improves readability. 468 |
469 |
470 | RFC Editor or Stream Notes Section 471 | A stream-approving body may approve the inclusion of an editorial 472 | note to explain anything unusual about the process that led to the 473 | document's publication or to note a correction. In this case, a 474 | stream note section will contain such a note. 475 | Additionally, an RFC Editor Note section may contain a note inserted 476 | by the RFC Editor to highlight special circumstances surrounding 477 | an RFC. 478 |
479 |
480 | Status of This Memo Section 481 | The RFC Editor will supply an appropriate "Status of This Memo" as 482 | defined in RFC [RFC7841] and "Format for RFCs in the IAB Stream" 483 | . 484 |
485 |
486 | Copyright, Licenses, and IPR Boilerplate Section 487 | The full copyright and license notices are available on the IETF 488 | Trust Legal Provisions documents website . 489 |
490 |
491 | Table of Contents Section 492 | A Table of Contents (TOC) is required in all RFCs. It must be 493 | positioned after the Copyright Notice and before the Introduction. 494 |
495 |
496 | Body of the Memo 497 | Following the TOC is the body of the memo. 498 | Each RFC must include an Introduction section that (among other 499 | things) explains the motivation for the RFC and (if appropriate) 500 | describes the applicability of the document, e.g., whether it 501 | specifies a protocol, provides a discussion of some problem, is 502 | simply of interest to the Internet community, or provides a status 503 | report on some activity. The body of the memo and the Abstract must 504 | be self-contained and separable. This may result in some duplication 505 | of text between the Abstract and the Introduction; this is 506 | acceptable. 507 |
508 | Introduction Section 509 | The Introduction section should always be the first section following 510 | the TOC (except in the case of MIB module documents). While 511 | "Introduction" is recommended, authors may choose alternate titles 512 | such as "Overview" or "Background". These alternates are acceptable. 513 | For MIB module documents, common practice has been for "The 514 | Internet-Standard Management Framework" text to appear 515 | as Section 1. 516 |
517 |
518 | Requirements Language Section 519 | Some documents use certain capitalized words ("MUST", "SHOULD", etc.) 520 | to specify precise requirement levels for technical features. 521 | and define a default interpretation of these 522 | capitalized words in IETF documents. If this interpretation is used, 523 | RFCs 2119 and 8174 must be cited (as specified in RFCs 2119 and 8174) and included as a 524 | normative reference. Otherwise, the correct interpretation must be 525 | specified in the document. 526 | This section must appear as part of the body of the memo (as defined 527 | by this document). It must appear as part of, or subsequent to, the 528 | Introduction section. 529 | These words are considered part of the technical content of the 530 | document and are intended to provide guidance to implementers about 531 | specific technical features, generally governed by considerations of 532 | interoperability. RFC 2119 says: 533 | Imperatives of the type defined in this memo must be used with 534 | care and sparingly. In particular, they MUST only be used where 535 | it is actually required for interoperation or to limit behavior 536 | which has potential for causing harm (e.g., limiting 537 | retransmisssions) For example, they must not be used to try to 538 | impose a particular method on implementers where the method is not 539 | required for interoperability. 540 |
541 |
542 | IANA Considerations Section 543 | For guidance on how to register IANA-related values or create new 544 | registries to be managed by IANA, see "Guidelines for Writing an IANA 545 | Considerations Section in RFCs" . 546 | The RFC Editor will update text accordingly after the IANA 547 | assignments have been made. It is helpful for authors to clearly 548 | identify where text should be updated to reflect the newly assigned 549 | values. For example, the use of "TBD1", "TBD2", etc., is recommended 550 | in the IANA Considerations section and in the body of the memo. 551 | If the authors have provided values to be assigned by IANA, the 552 | RFC Editor will verify that the values inserted by the authors match 553 | those that have actually been registered on the IANA site. When 554 | writing a given value, consistent use of decimal or hexadecimal is 555 | recommended. 556 | If any of the IANA-related information is not clear, the RFC Editor 557 | will work with IANA to send queries to the authors to ensure that 558 | assignments and values are properly inserted. 559 |
560 |
561 | Internationalization Considerations Section 562 | All RFCs that deal with internationalization issues should have a 563 | section describing those issues; see "IETF Policy on Character Sets 564 | and Languages" , Section 6, for more information. 565 |
566 |
567 | Security Considerations Section 568 | All RFCs must contain a section that discusses the security 569 | considerations relevant to the specification; see "Guidelines for 570 | Writing RFC Text on Security Considerations" for more 571 | information. 572 | Note that additional boilerplate material for RFCs containing MIB and 573 | YANG modules also exists. See "Security Guidelines for IETF MIB 574 | Modules" and "yang module security considerations" 575 | for details. 576 |
577 |
578 | References Section 579 | The reference list is solely for recording reference entries. 580 | Introductory text or annotations beyond necessary translations are not allowed. 581 | The RFC style allows the use of any of a variety of reference styles, 582 | as long as they are used consistently within a document. However, 583 | where necessary, some reference styles have been described for use 584 | within the Series. See the following subsections as well as the References 585 | section of this document. 586 | Reference lists must indicate whether each reference is normative or 587 | informative, where normative references are essential to implementing 588 | or understanding the content of the RFC and informative references 589 | provide additional information. More information about normative and 590 | informative references may be found in the IESG's statement 591 | "Normative and Informative References" . When both normative 592 | and informative references exist, the references section should be 593 | split into two subsections: 594 | Templates are available on the RFC Editor website for the XML format of 595 | certain references . 596 | s. References 597 | s.1. Normative References 598 | 603 | s.2. Informative References 604 | 609 | References will generally appear in alphanumeric order by citation 610 | tag. Where there are only normative or informative references, no 611 | subsection is required; the top-level section should say "Normative 612 | References" or "Informative References". 613 | Normative references to Internet-Drafts will cause publication of the 614 | RFC to be suspended until the referenced draft is also ready for 615 | publication; the RFC Editor will then update the entry to refer to 616 | the RFC and publish both documents simultaneously. 617 |
618 | Referencing RFCs 619 | The following format is required for referencing RFCs. The Stream 620 | abbreviation should be used; when no stream is available, as with legacy RFCs, 621 | this may be left blank. 622 | Note the ordering for multiple authors: the format of 623 | the name of the last author listed is different than that of all previous 624 | authors in the list. 625 | For one author or editor: 626 | [RFCXXXX] Last name, First initial., Ed. (if applicable), 627 | "RFC Title", Stream, Subseries number (if applicable), 628 | RFC number, RFC DOI, Date of publication, 629 | https://www.rfc-editor.org/info/rfc#. 630 | Example: 631 | [RFC3080] Rose, M., "The Blocks Extensible Exchange 632 | Protocol Core," IETF, RFC 3080, DOI 10.17487/RFC3080, March 2001, 633 | https://www.rfc-editor.org/info/rfc3080. 634 | [RFC8157] Leymann, N., Heidemann, C., Zhang, M., Sarikaya, B., and M. 635 | Cullen, "Huawei's GRE Tunnel Bonding Protocol", independent, 636 | RFC 8157, DOI 10.17487/RFC8157, May 2017, 637 | https://www.rfc-editor.org/info/rfc8157. 638 | For two authors or editors: 639 | [RFCXXXX] Last name, First initial., Ed. (if applicable) 640 | and First initial. Last name, Ed. (if applicable), 641 | "RFC Title", Stream, Subseries number (if applicable), 642 | RFC number, RFC DOI, Date of publication, 643 | https://www.rfc-editor.org/info/rfc#. 644 | Example: 645 | [RFC6323] Renker, G. and G. Fairhurst, "Sender RTT 646 | Estimate Option for the Datagram Congestion 647 | Control Protocol (DCCP)", IETF, RFC 6323, DOI 10.17487/RFC6323, July 2011, 648 | https://www.rfc-editor.org/info/rfc6323. 649 | For three or more authors or editors: 650 | [RFCXXXX] Last name, First initial., Ed. (if applicable), 651 | Last name, First initial., Ed. (if applicable), 652 | and First initial. Last name, Ed. (if applicable), 653 | "RFC Title", Stream, Subseries number (if applicable), 654 | RFC number, RFC DOI, Date of publication, 655 | https://www.rfc-editor.org/info/rfc#. 656 | Example: 657 | [RFC6429] Bashyam, M., Jethanandani, M., and A. Ramaiah, 658 | "TCP Sender Clarification for Persist 659 | Condition", IETF, RFC 6429, DOI 10.17487/RFC6429, December 2011, 660 | https://www.rfc-editor.org/info/rfc6429. 661 |
662 |
663 | Referencing RFC(s) in a Subseries (STDs, BCPs, and FYIs 664 | Internet Standards (STDs) and Best Current Practices (BCPs) may consist of 665 | a single RFC or multiple RFCs. Authors should carefully consider whether they 666 | want to point the reader to the specific RFC or the sub series group. In the 667 | former case, references should appear as described in Section 668 | 4.8.6.2. In the latter case, the sub series number should take precedence as, 669 | for example, the citation tag, even in cases where the sub series currently 670 | contains only one RFC. 671 | When an STD or BCP that contains multiple RFCs is referenced as a sub series 672 | group, the reference entry should include ALL of the RFCs comprising that 673 | subseries in a reference grouping under a single citation tag [is it helpful to 674 | point them to 7991 or the like on how to do this here?]. The authors should 675 | refer to the specific RFC numbers as part of the text in the body of the 676 | document and cite the subseries number (for example, "see RFC 2026 of 677 | [BCP9]"). The URI to the STD or BCP info page (see Section 3.2.3 of [RFC5741]) is to be included. The text should appear as follows: 678 | See RFC 3552 [BCP72]. 679 | For an STD or BCP that contains one RFC: 680 | [STDXXX] Internet Standard XXX, 681 | https://www.rfc-editor.org/info/std#. At the time of writing, this STD comprises the following: 683 | Last name, First initial., Ed. (if applicable), "RFC 684 | Title", Stream, Subseries number, RFC number, RFC DOI, Date of 685 | publication, https://www.rfc-editor.org/info/rfc#. 687 | 688 | Example: 689 | [STD80] Internet Standard 80, 690 | https://www.rfc-editor.org/info/std80. 692 | At the time of writing, this STD comprises the following: 693 | 694 | Cerf, V., "ASCII format for network interchange", STD 80, 695 | RFC 20, DOI 10.17487/RFC0020, October 1969, 696 | https://www.rfc-editor.org/info/rfc20. 698 | 699 | For an STD or BCP that contains two or more RFCs: 700 | 701 | [BCPXXX] Best Current Practice XXX, https://www.rfc-editor.org/info/bcp#. 703 | At the time of writing, this BCP comprises the following: 704 | Last name, First initial., Ed. (if applicable), 705 | "RFC Title", Stream, Subseries number, RFC number, RFC DOI, Date 706 | of publication, https://www.rfc-editor.org/info/rfc#. 708 | Last name, First initial., Ed. (if applicable), 709 | "RFC Title", Stream, Subseries number, RFC number, RFC DOI, Date 710 | of publication, https://www.rfc-editor.org/info/rfc#. 712 | 713 | Example: 714 | [BCP72] Best Current Practice 72, https://www.rfc-editor.org/info/bcp72. 716 | At the time of writing, this BCP comprises the following: 717 | 718 | Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on 719 | Security Considerations", BCP 72, RFC 3552, 720 | DOI 10.17487/RFC3552, July 2003, 721 | https://www.rfc-editor.org/info/rfc3552. 723 | Gont, F. and I. Arce, "Security Considerations for Transient 724 | Numeric Identifiers Employed in Network Protocols", BCP 72, 725 | RFC 9416, DOI 10.17487/RFC9416, July 2023, 726 | https://www.rfc-editor.org/info/rfc9416. 728 | 729 | Note - some RFCs contain an FYI subseries number however, the FYI 730 | series was ended by RFC 6360. RFCs that were published with an FYI subseries 731 | number and still maintain the FYI number must include the subseries number in 732 | the reference and may otherwise be treated in the same manner as STDs and 733 | BCPs. 734 | Grouping references to RFCs or other materials that are not part of a 735 | subseries is discouraged. 736 |
737 |
738 | Referencing Internet-Drafts 739 | References to Internet Drafts may only appear as informative 740 | references. Given that several revisions of an I-D may be produced 741 | in a short time frame, references must include the posting date 742 | (month and year), the full Internet-Draft file name (including the 743 | version number), and the phrase "Internet Draft". Authors may 744 | reference multiple versions of an I-D. If the referenced I-D was 745 | also later published as an RFC, then that RFC must also be listed. 746 | The reference should include a stable URL for the draft, if available. 747 | [SYMBOLIC-TAG] Last name, First initial., Ed. (if applicable) 748 | and First initial. Last name, Ed. (if 749 | applicable), "I-D Title", Work in Progress, Internet-Draft, 750 | draft-string-NN, Day Month Year, <https://datatracker.ietf.org/doc/html/draft-something>. 751 | 752 | Example: 753 | [RFC-STYLE] Flanagan, H. and S. Ginoza, "RFC Style Guide", Work in Progress, 754 | Internet-Draft, draft-flanagan-style-04, 755 | 27 September 2019, <https://datatracker.ietf.org/doc/html/draft-flanagan-style-04>. 756 | 757 |
758 |
759 | Referencing Errata 760 | The following format is required when a reference to an erratum 761 | report is necessary: 762 | [ErrNumber] RFC Errata, Erratum ID number, RFC number, <https://www.rfc-editor.org/errata/eid#>. 763 | [Err1912] RFC Errata, Erratum ID 1912, RFC 2978, <https://www.rfc-editor.org/errata/eid1912>. 764 | Errata that are in the Reported state should not be referenced; they are not considered stable. 765 |
766 |
767 | Referencing IANA Registries 768 | IANA registries may appear in normative or informative reference sections. 769 | 770 | [IANA-SYMBOLIC-TAG] 771 | 772 |
    773 |
  • IANA, "Registry Name", <URL>.
  • 774 |
775 |
776 |
777 | Referencing Other Standards Development Organizations (SDOs) 778 | The following format is suggested when referencing a document or 779 | standard from another SDO in which authors are listed: 780 | [SYMBOLIC-TAG] 781 | 782 |
    783 |
  • Last name, First initial. and First initial. Last name, 784 | "Document Title", Document reference number, Date of 785 | publication, <URI if available>.
  • 786 |
787 | [W3C.REC-xml11] 788 | 789 |
    790 |
  • Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., 791 | Yergeau, F., and J. Cowan, "Extensible Markup Language 792 | (XML) 1.1 (Second Edition)", W3C Recommendation 793 | REC-xml11-20060816, August 2006, 794 | <https://www.w3.org/TR/2006/REC-xml11-20060816>.
  • 795 |
796 | The order of authors in the list is the same as the order 797 | shown on the actual document and that the common, abbreviated form of 798 | the SDO is used. 799 | Alternatively, when no list of authors is available, the following 800 | format is recommended: 801 | . 804 | ]]> 805 | Example (undated; see note below): 806 | . 810 | ]]> 811 | Example (dated; see note below): 812 | 818 | ]]> 819 | Per the IEEE coordination team, listing dates for IEEE standards is not 820 | recommended unless there is a need to cite a particular section, in which case 821 | the dated reference is appropriate. An RFC with a dated IEEE reference suggests 822 | that the RFC only applies to that specific IEEE specification. 823 |
824 |
825 | Referencing Webpages 826 | References to webpages acceptable in either the normative or informative 827 | sections, as long as the URL provided is the most stable (i.e., unlikely to 828 | change and expected to be continuously available) and direct reference 829 | possible. The URL will be verified as valid during the RFC editorial process. 830 | If a dated URI (one that includes a timestamp for the page) is 831 | available for a referenced web page, its use is required. 832 | Note that the URL may not be the sole information provided for a 833 | reference entry. 834 | The use of HTTPS rather than HTTP is strongly encouraged. 835 | Example: 836 | [SYMBOLIC-TAG] Author (if available), "Page Title (if available)", <URL>. 837 | 840 | ]]> 841 |
842 |
843 | Referencing Email on Mailing Lists 844 | When referencing emails to mailing lists, the template provided here should be used: 845 | 846 |
    847 |
  • [reftag] Sender, A., "Subject: Subject line", message to the
  • 848 |
  • listname mailing list, DD Month YYYY, <URL>.
  • 849 |
850 |
851 |
852 | Referencing Code Repositories 853 | References to online code repositories such as GitHub or SourceForge 854 | should be used as informative references only. The reference entry should 855 | include the repository title, commit hash or similar release marker if 856 | available, date of last commit, and URL. 857 | Examples: 858 | . 860 | 861 | [linuxlite] "Linux Lite", 9 March 2018, 862 | . 863 | ]]> 864 |
865 |
866 |
867 |
868 | Appendices Section 869 | The RFC Editor recommends placing references before the Appendices. 870 | Appendices should be labeled as "Appendix A. Title", "A.1. Title", 871 | "Appendix B. Title", etc. 872 |
873 |
874 | Acknowledgements Section 875 | This optional section may be used instead of, or in addition to, a 876 | Contributors section. It is often used by authors to publicly thank 877 | those who have provided feedback regarding a document and to note any 878 | documents from which text was borrowed. 879 |
880 |
881 | Contributors Section 882 | This optional section acknowledges those who have made significant 883 | contributions to the document. 884 | In a similar fashion to the Author's Address section, the RFC Editor 885 | does not make the determination as to who should be listed as a 886 | contributor to an RFC. The determination of who should be listed as 887 | a contributor is made by the stream. 888 | The Contributors section may include brief statements about the 889 | nature of particular contributions (e.g., "Sam contributed Section 3"), and 890 | it may also include affiliations of listed contributors. At the 891 | discretion of the author(s), contact addresses may also be included 892 | in the Contributors section, for those contributors whose knowledge 893 | makes them useful future contacts for information about the RFC. The 894 | format of any contact information should be similar to the format of 895 | information in the Author's Address section. 896 |
897 |
898 | Index 899 | If included, an index appears at the end of the document, immediately 900 | before Author's Address section. 901 |
902 |
903 | Author's Address or Authors' Addresses Section 904 | This required section gives contact information for the author(s) 905 | listed in the first-page header. 906 | Contact information must include a long-lived email address and 907 | optionally may include a postal address and/or telephone number. If 908 | the postal address is included, it should include the country name, 909 | using the English short name listed by the ISO 3166 Maintenance 910 | Agency . The purpose of this section is to 911 | (1) unambiguously define author identity (e.g., the John Smith who 912 | works for FooBar Systems) and (2) provide contact information for 913 | future readers who have questions or comments. 914 | The practice of munged email addresses (i.e., altering an email 915 | address to make it less readable to bots and web crawlers to avoid 916 | spam) is not appropriate in an archival document series. Author 917 | contact information is provided so that readers can easily contact 918 | the author with questions and/or comments. Address munging is not 919 | allowed in RFCs. 920 |
921 |
922 |
923 | Security Considerations 924 | This document has no security considerations. 925 |
926 |
927 | IANA Considerations 928 | This document has no IANA considerations. 929 |
930 |
931 | Change Log 932 | This section to be removed before publication. 933 | 934 | Changes in draft-flanagan-style: 935 |
    936 |
  • RFC 7322 to -00: Removed requirement for two spaces after a period; 937 | clarified citation tag requirements; added guidance on avoiding RFCs as 938 | compounds; and added guidance on figures.
  • 939 |
  • -00 to -01: Moved placement of the Index; added 940 | new errata URI; specified capitalization of working/research group.
  • 941 |
  • -01 to -02: Updated Abstract guidance.
  • 942 |
  • -02 to -03: Updated citation section; changed list styles; added angle 943 | brackets to reference examples; changed I-D reference format; clarified 944 | subseries reference format; added guidance on referencing code 945 | repositories.
  • 946 |
  • -03 to -04: Updated Reference Section guidance; added information on alt text.
  • 947 |
  • -04 to -05: Changed author, added acknowledgement.
  • 948 |
  • -05 to -06: Put URLs inline.
  • 949 |
  • -06 to -07: Added DOI information.
  • 950 |
951 | Changes to draft-rpc-rfc7322bis: 952 |
    953 |
  • draft-flanagan-style-07 to -00: Updated authors and references.
  • 954 |
  • -00 to -01: Updated description regarding how to reference RFCs 955 | that are part of a subseries; added guidance that errata in 956 | Reported state should not be referenced.
  • 957 |
  • -01 to -02: Clarified that an author may change their name on 958 | subsequent RFCs; clarified the example of avoiding the use of a 959 | citation in a compound; clarified the expansion of abbreviations.
  • 960 |
961 |
962 |
963 | 964 | 965 | References 966 | 967 | Normative References 968 | 969 | 970 | Web Portion of the Style Guide 971 | 972 | RFC Editor 973 | 974 | 975 | 976 | 977 | 978 | 979 | Informative References 980 | 981 | 982 | 983 | RFC Editor Abbreviations List 984 | 985 | RFC Editor 986 | 987 | 988 | 989 | 990 | 991 | 992 | Understanding Success Criterion 1.3.1: Info and Relationships 993 | 994 | W3C 995 | 996 | 997 | 998 | 999 | 1000 | 1001 | 1002 | 1003 | 1004 | 1006 | 1007 | 1009 | 1011 | 1013 | 1015 | 1017 | 1019 | 1021 | 1022 | 1023 | 1024 | 1025 | 1026 | IETF Policy on Character Sets and Languages 1027 | 1028 | 1029 | 1030 | 1031 | 1032 | 1033 | 1034 | 1035 | Guidelines for Writing an ANA Considerations Section in RFCs 1036 | 1037 | 1038 | 1039 | 1040 | 1041 | 1042 | 1043 | 1044 | 1045 | Reserved Top Level DNS Names 1046 | 1047 | 1048 | 1049 | 1050 | 1051 | 1052 | 1053 | 1054 | 1055 | Guidelines for Writing RFC Text on Security Considerations 1056 | 1057 | 1058 | 1059 | 1060 | 1061 | 1062 | 1063 | 1064 | 1065 | Clusters in the RFC Editor Queue 1066 | 1067 | RFC Editor 1068 | 1069 | 1070 | 1071 | 1072 | 1073 | 1074 | Chicago Manual of Style, 16th ed. 1075 | 1076 | University of Chicago Press, 2010 1077 | 1078 | 1079 | 1080 | 1081 | 1082 | 1083 | FYI on FYI: Introduction to the FYI Notes 1084 | 1085 | 1086 | 1087 | 1088 | 1089 | 1090 | 1091 | Housley, R., "Conclusion of FYI RFC Sub-Series", RFC 6360, 1092 | August 2011. 1093 | 1094 | 1095 | 1096 | 1097 | Format for RFCs in the IAB Stream 1098 | 1099 | IAB 1100 | 1101 | 1102 | 1103 | 1104 | 1105 | 1106 | Guidelines to Authors of Internet Drafts 1107 | 1108 | IETF 1109 | 1110 | 1111 | 1112 | 1113 | 1114 | 1115 | Trust Legal Provisions (TLP) 1116 | 1117 | IETF Trust 1118 | 1119 | 1120 | 1121 | 1122 | 1123 | 1124 | Online Browsing Platform (OBP) 1125 | 1126 | ISO 1127 | 1128 | 1129 | 1130 | 1131 | 1132 | 1133 | Identification and description, Information and documentation - International standard serial number (ISSN) 1134 | 1135 | Technical Committee ISO/TC 46, Information and documentation, Subcommittee SC 9 1136 | 1137 | 1138 | 1139 | 1140 | 1141 | 1142 | 1143 | Boilerplate for IETF MIB Documents 1144 | 1145 | IETF OPS Area 1146 | 1147 | 1148 | 1149 | 1150 | 1151 | 1152 | Security Guidelines for IETF MIB Modules 1153 | 1154 | IETF OPS Area 1155 | 1156 | 1157 | 1158 | 1159 | 1160 | 1161 | Reference Examples 1162 | 1163 | RFC Editor 1164 | 1165 | 1166 | 1167 | 1168 | 1169 | 1170 | IESG Statement: Normative and Informative 1171 | 1172 | IESG 1173 | 1174 | 1175 | 1176 | 1177 | 1178 | 1179 | The RFC Series and RFC Editor 1180 | 1181 | 1182 | 1183 | 1184 | Internet Architecture Board 1185 | 1186 | 1187 | 1188 | This document describes the framework for an RFC Series and an RFC Editor function that incorporate the principles of organized community involvement and accountability that has become necessary as the Internet technical community has grown, thereby enabling the RFC Series to continue to fulfill its mandate. This memo provides information for the Internet community. 1189 | 1190 | 1191 | 1192 | 1193 | 1194 | 1195 | 1196 | RFC Streams, Headers, and Boilerplates 1197 | 1198 | 1199 | 1200 | 1201 | 1202 | 1203 | 1204 | 1205 | 1206 | 1207 | 1208 | RFC documents contain a number of fixed elements such as the title page header, standard boilerplates, and copyright/IPR statements. This document describes them and introduces some updates to reflect current usage and requirements of RFC publication. In particular, this updated structure is intended to communicate clearly the source of RFC creation and review. This document obsoletes RFC 5741, moving detailed content to an IAB web page and preparing for more flexible output formats. 1209 | 1210 | 1211 | 1212 | 1213 | 1214 | 1215 | 1216 | RFC Editor Model (Version 2) 1217 | 1218 | 1219 | 1220 | 1221 | 1222 | 1223 | 1224 | IAB 1225 | 1226 | 1227 | 1228 | The RFC Editor model described in this document divides the responsibilities for the RFC Series into three functions: the RFC Series Editor, the RFC Production Center, and the RFC Publisher. Internet Architecture Board (IAB) oversight via the RFC Series Oversight Committee (RSOC) is described, as is the relationship between the IETF Administrative Oversight Committee (IAOC) and the RSOC. This document reflects the experience gained with "RFC Editor Model (Version 1)", documented in RFC 5620, and obsoletes that document. This document is not an Internet Standards Track specification; it is published for informational purposes. 1229 | 1230 | 1231 | 1232 | 1233 | 1234 | 1235 | 1236 | RFC Format Framework 1237 | 1238 | 1239 | 1240 | 1241 | 1242 | In order to improve the readability of RFCs while supporting their archivability, the canonical format of the RFC Series will be transitioning from plain-text ASCII to XML using the xml2rfc version 3 vocabulary; different publication formats will be rendered from that base document. With these changes comes an increase in complexity for authors, consumers, and the publisher of RFCs. This document serves as the framework that provides the problem statement, lays out a road map of the documents that capture the specific requirements, and describes the transition plan. 1243 | 1244 | 1245 | 1246 | 1247 | 1248 | 1249 | 1250 | The "xml2rfc" Version 3 Vocabulary 1251 | 1252 | 1253 | 1254 | 1255 | 1256 | This document defines the "xml2rfc" version 3 vocabulary: an XML-based language used for writing RFCs and Internet-Drafts. It is heavily derived from the version 2 vocabulary that is also under discussion. This document obsoletes the v2 grammar described in RFC 7749. 1257 | 1258 | 1259 | 1260 | 1261 | 1262 | 1263 | 1264 | SVG Drawings for RFCs: SVG 1.2 RFC 1265 | 1266 | 1267 | 1268 | 1269 | 1270 | This document specifies SVG 1.2 RFC -- an SVG profile for use in diagrams that may appear in RFCs -- and considers some of the issues concerning the creation and use of such diagrams. 1271 | 1272 | 1273 | 1274 | 1275 | 1276 | 1277 | 1278 | The Use of Non-ASCII Characters in RFCs 1279 | 1280 | 1281 | 1282 | 1283 | 1284 | In order to support the internationalization of protocols and a more diverse Internet community, the RFC Series must evolve to allow for the use of non-ASCII characters in RFCs. While English remains the required language of the Series, the encoding of future RFCs will be in UTF-8, allowing for a broader range of characters than typically used in the English language. This document describes the RFC Editor requirements and gives guidance regarding the use of non-ASCII characters in RFCs. 1285 | This document updates RFC 7322. Please view this document in PDF form to see the full text. 1286 | 1287 | 1288 | 1289 | 1290 | 1291 | 1292 | 1293 | Uniform Resource Identifier (URI): Generic Syntax 1294 | 1295 | 1296 | 1297 | 1298 | 1299 | 1300 | 1301 | 1302 | 1303 | 1304 | Terms List 1305 | 1306 | RFC Editor 1307 | 1308 | 1309 | 1310 | 1311 | 1312 | 1313 | yang module security considerations 1314 | 1315 | IETF Ops Area 1316 | 1317 | 1318 | 1319 | 1320 | 1321 | 1322 | 1323 | 1324 | Instructions to Request for Comments (RFC) Authors 1325 | 1326 | 1327 | 1328 | 1329 | 1330 | 1331 | 1332 | 1333 | 1334 | 1335 | 1336 | 1337 |
1338 | Related Procedures 1339 | The following procedures are related to the application and updating 1340 | of the RFC Style Guide. 1341 |
1342 | Dispute Resolution 1343 | There are competing rationales for some of the rules described in 1344 | this Guide, and the RFC Editor has selected the ones that work best 1345 | for the Series. However, at times, an author may have a disagreement 1346 | with the RFC Production Center (RPC) over the application of Style 1347 | Guide conventions. In such cases, the authors should discuss their 1348 | concerns with the RPC. If no agreement can be reached between the 1349 | RPC and the authors, the RFC Series Editor will, with input from the 1350 | appropriate stream-approving body, make a final determination. If 1351 | further resolution is required, the dispute resolution process as 1352 | described in the RFC Editor Model will be followed. 1353 |
1354 |
1355 | Returning an I-D to the Document Stream 1356 | For a given document, if the RFC Editor determines that it cannot be 1357 | edited without serious risk of altering the meaning of the technical 1358 | content or if the RFC Editor does not have the resources to provide 1359 | the level of editing it needs, it may be sent back to the stream- 1360 | approving body with a request to improve the clarity, consistency, 1361 | and/or readability of the document. This is not to be considered a 1362 | dispute with the author. 1363 |
1364 |
1365 | Revising This Document and Associated Web Pages 1366 | The RFC Series is continually evolving as a document series. This 1367 | document focuses on the fundamental and stable requirements that must 1368 | be met by an RFC. From time to time, the RFC Editor may offer less 1369 | formal recommendations that authors may apply at their discretion; 1370 | these recommendations may be found on the RFC Editor website 1371 | "Guidelines for RFC Style" . 1372 | When a new recommendation is made regarding the overall structure and 1373 | formatting of RFCs, it will be published on that page and accepted 1374 | for a period of time before the RFC Editor determines whether it 1375 | should become part of the fundamental requirements in the RFC Style 1376 | Guide or remain as a less formal recommendation. That period of time 1377 | will vary, in part depending on the frequency with which authors 1378 | encounter and apply the guidance. 1379 |
1380 |
1381 |
1382 | Acknowledgements 1383 | This document refers heavily to and ; as such, we are grateful to the authors of those documents for putting their time and effort into the RFC Series. 1384 | Much of this document was written by Heather Flanagan during her term as the RFC Series Editor (RSE). 1385 |
1386 |
1387 |
1388 | --------------------------------------------------------------------------------