idnits 2.17.1 draft-ribose-asciirfc-07.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 37 instances of too long lines in the document, the longest one being 24 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 15, 2018) is 2202 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Orb' is mentioned on line 4800, but not defined -- Looks like a reference, but probably isn't: '124' on line 4800 -- Looks like a reference, but probably isn't: '135' on line 4800 == Unused Reference: 'I-D.camelot-holy-grenade' is defined on line 3581, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-asciirfc-minimal-02 == Outdated reference: A later version (-01) exists of draft-camelot-holy-grenade-00 -- Obsolete informational reference (is this intentional?): RFC 7749 (Obsoleted by RFC 7991) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Tse 3 Internet-Draft N. Nicholas 4 Intended status: Informational J. Lau 5 Expires: October 17, 2018 P. Brasolin 6 Ribose 7 April 15, 2018 9 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc 10 draft-ribose-asciirfc-07 12 Abstract 14 This document describes an AsciiDoc syntax extension called AsciiRFC, 15 designed for authoring IETF Internet-Drafts and RFCs. 17 AsciiDoc is a human readable document markup language which affords 18 more granular control over markup than comparable schemes such as 19 Markdown. 21 The AsciiRFC syntax is designed to allow the author to entirely focus 22 on text, providing the full power of the resulting RFC XML through 23 the AsciiDoc language, while abstracting away the need to manually 24 edit XML, including references. 26 This document itself was written and generated into RFC XML v2 27 (RFC7749) and RFC XML v3 (RFC7991) directly through asciidoctor-rfc, 28 an AsciiRFC generator. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at https://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on October 17, 2018. 47 Copyright Notice 49 Copyright (c) 2018 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. Designed for authoring RFCs and Internet-Drafts . . . . . 3 63 1.2. Relationship between AsciiRFC, AsciiDoc and Asciidoctor . 4 64 1.3. Comparison with RFC XML tools based on Markdown variants 4 65 2. Conventions Used in This Document . . . . . . . . . . . . . . 6 66 3. Document Structure and Syntax . . . . . . . . . . . . . . . . 6 67 3.1. Unsupported features compared with Asciidoctor syntax . . 7 68 3.2. Mapping To RFC XML syntax . . . . . . . . . . . . . . . . 8 69 3.3. Example Illustrations . . . . . . . . . . . . . . . . . . 9 70 3.4. Simple Illustration . . . . . . . . . . . . . . . . . . . 9 71 4. Header And Document Attributes . . . . . . . . . . . . . . . 27 72 4.1. Title And Basic Attributes . . . . . . . . . . . . . . . 27 73 4.2. Detailed Author Information . . . . . . . . . . . . . . . 29 74 4.3. XML Processing Information . . . . . . . . . . . . . . . 33 75 4.4. AsciiRFC-specific Document Attributes . . . . . . . . . . 34 76 5. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 37 77 6. Sections and Paragraphs . . . . . . . . . . . . . . . . . . . 38 78 7. Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 79 8. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 80 8.1. Basic Lists . . . . . . . . . . . . . . . . . . . . . . . 46 81 8.2. List Continuation . . . . . . . . . . . . . . . . . . . . 51 82 9. Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . . 54 83 10. Notes And Asides . . . . . . . . . . . . . . . . . . . . . . 55 84 11. Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 85 12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . . 61 86 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts . 61 87 12.2. Formatting BCP 14 Keywords . . . . . . . . . . . . . . . 62 88 12.3. Escaping AsciiRFC Syntax . . . . . . . . . . . . . . . . 63 89 13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 90 14. Cross-References . . . . . . . . . . . . . . . . . . . . . . 65 91 14.1. Basic Referencing . . . . . . . . . . . . . . . . . . . 65 92 14.2. Referencing With Attributes . . . . . . . . . . . . . . 66 93 14.3. Indexing . . . . . . . . . . . . . . . . . . . . . . . . 67 94 15. Inclusions . . . . . . . . . . . . . . . . . . . . . . . . . 68 95 16. Encoding and Entities . . . . . . . . . . . . . . . . . . . . 69 96 17. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 71 97 17.1. Using Raw RFC XML . . . . . . . . . . . . . . . . . . . 71 98 17.2. Preprocessing Using "asciidoctor-bibliography" . . . . . 75 99 18. RFC XML features not supported in Asciidoctor . . . . . . . . 78 100 19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 78 101 19.1. Using the "rfc-asciirfc-minimal" template . . . . . . . 78 102 19.2. Installing AsciiRFC Backend Processors . . . . . . . . . 78 103 19.3. Iterating AsciiRFC Content . . . . . . . . . . . . . . . 79 104 20. Security Considerations . . . . . . . . . . . . . . . . . . . 79 105 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 80 106 22. References . . . . . . . . . . . . . . . . . . . . . . . . . 80 107 22.1. Normative References . . . . . . . . . . . . . . . . . . 80 108 22.2. Informative References . . . . . . . . . . . . . . . . . 80 109 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 83 110 A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" . . . . 83 111 A.1.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 84 112 A.1.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 91 113 A.2. Example 2: "The Holy Hand Grenade of Antioch" . . . . . . 96 114 A.2.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 97 115 A.2.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 114 116 A.3. Example 3: "An API For Calendar-Based Fortune Heuristics 117 Services" in AsciiRFC . . . . . . . . . . . . . . . . . . 132 118 A.3.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 132 119 A.4. Rendered as RFC XML v3 . . . . . . . . . . . . . . . . . 152 120 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 168 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 168 123 1. Introduction 125 This document describes a markup language called "AsciiRFC", 126 developed specifically for the purpose of generating RFC XML 127 document, based on Asciidoctor syntax. AsciiRFC can be used to 128 generate compliant RFC XML v2 and v3 documents through the usage of 129 an open source, MIT-licensed Ruby gem called "asciidoctor-rfc" 130 written by the authors [asciidoctor-rfc]. 132 1.1. Designed for authoring RFCs and Internet-Drafts 134 Internet-Drafts and RFCs intended for publication submission to the 135 IETF can be written in a multitude of formats today, including: 137 o XML: RFC XML v2 [RFC7749] and v3 [RFC7991] 139 o nroff: through [NroffEdit] 141 o Microsoft Word: through usage of [RFC5385] 142 o Lyx: through [lyx2rfc] 144 o Pandoc: [RFC7328], through [pandoc2rfc] or [draftr] 146 o Kramdown: through [kramdown-rfc2629] 148 o mmark: through [mmark] 150 Interestingly, the last three are Markdown [RFC7763] variants. 152 As specified in [RFC7990], the IETF intends for the canonical format 153 of RFCs to transition from plain-text ASCII to RFC XML v3 [RFC7991]. 154 While plain-text will continue to be accepted from authors by the 155 IETF, at least in the short- to medium-term, XML will be preferred 156 for submission, and any plain-text submissions will need to be 157 converted to RFC XML v3. 159 While this need is already met for RFC XML v2 [RFC7749] by the tools 160 specified above, the transition to RFC XML v3 [RFC7991] places added 161 onus on authors to generate compliant XML. 163 1.2. Relationship between AsciiRFC, AsciiDoc and Asciidoctor 165 [AsciiDoc] is a lightweight markup language and an alternative to 166 Markdown, with features that make it attractive as a markup language 167 for RFC with XML output. 169 [Asciidoctor] is an open source, MIT-licensed Ruby implementation of 170 [AsciiDoc] that provides an enhancement of the original AsciiDoc 171 markup language. 173 The variant of AsciiDoc syntax accepted by [Asciidoctor] is hereafter 174 called "Asciidoctor syntax". 176 AsciiRFC, as described in this document, is an AsciiDoc variant 177 developed on Asciidoctor syntax, created for the purpose of 178 generating RFC XML documents. 180 1.3. Comparison with RFC XML tools based on Markdown variants 182 Section 1.2 of [RFC7764] famously states that "there is no such thing 183 as 'invalid' Markdown, there is no standard demanding adherence to 184 the Markdown syntax, and there is no governing body that guides or 185 impedes its development." While there are contexts where that 186 flexibility is useful, the authoring of RFCs does have a standard and 187 a governing body, and there is such a thing as invalid RFC XML. A 188 more rigorous and extensible counterpart to Markdown, which still 189 preserves its basic approach to formatting, can generate RFC XML that 190 encompasses a fuller subset of the specification, and preempts 191 malformed RFC XML output. The proposed markup language and 192 associated Ruby gem has several advantages that we believe make it 193 worth considering as an approach to generating RFC XML. 195 o AsciiDoc was designed from the beginning as a publishing language: 196 it was initially intended as a plain-text alternative to the 197 DocBook XML schema. For that reason, Asciidoctor natively 198 supports the full range of formatting required by RFC XML 199 (including notes, tables, bibliographies, source-code blocks, and 200 definition lists), without resorting to embedded HTML or Markdown 201 "flavours". 203 o AsciiRFC covers the full range of elements in RFC XML v2 and RFC 204 XML v3. 206 o AsciiDoc in its Ruby-based Asciidoctor implementation is 207 extensible, with a well-defined API. (Extensions have been 208 harnessed to deal with bibliographic preprocessing for AsciiRFC.) 210 o AsciiRFC allows granular control of rendering, including user- 211 specified attributes of text blocks. 213 o The Asciidoctor implementation allows document inclusion, for 214 managing large-scale documentation projects. 216 o AsciiRFC allows granular control of permutations of block nesting, 217 such as source code within lists or definition lists within 218 unordered lists. 220 o As a more formal counterpart to Markdown, AsciiDoc is well-suited 221 to generating XML that needs to conform to a specified schema. 222 The asciidoctor-rfc Ruby gem developed around AsciiDoc validates 223 its RFC XML output against the RelaxNG schema defined for RFC XML, 224 and reports any issues to the end user. 226 o The asciidoctor-rfc Ruby gem incorporates validation not only of 227 the XML structure of the standard, but also of the IETF workgroups 228 it mentions against the latest listing online, and the 229 bibliographic entries for RFC and other standards registered on 230 . The gem also dynamically 231 fetches bibliographic entries from the xml2rfc site, and uses them 232 to populate the RFC XML document. 234 As with Markdown, there is a wide range of tools that can render 235 AsciiDoc; so AsciiRFC drafts of RFC documents can be previewed and 236 accessed without depending on the RFC tools ecosystem. Our 237 realisation of RFC XML in AsciiRFC has aimed to ensure that, as much 238 as possible, the markup language can be can be processed by generic 239 Asciidoctor tools. 241 The only exception to this as an add-on is the optional bibliography 242 module, which allows bibliographies to be assembled on the fly based 243 on citations in a document: see Section 17.2. 245 2. Conventions Used in This Document 247 The following terms and definitions apply to this document: 249 AsciiDoc 250 The AsciiDoc markup language generically, as described in 251 [AsciiDoc]. 253 Asciidoctor syntax 254 The enhanced AsciiDoc syntax implemented by the [Asciidoctor] Ruby 255 gem. 257 AsciiRFC 258 The AsciiDoc syntax developed for the purpose of generating RFC 259 XML document based on Asciidoctor syntax, as described in this 260 document. 262 3. Document Structure and Syntax 264 AsciiRFC consists of a subset of Asciidoctor syntax with the addition 265 of bibliographic macros (Section 17.2). Asciidoctor syntax is 266 presented in the Asciidoctor user manual [Asciidoctor-Manual]. 268 AsciiRFC syntax consists of: 270 o A document header, containing a title, a list of authors, and 271 document attributes in lines prefixed with ":". 273 o An optional document preamble, separated from the document header 274 by a blank line, and not containing any section titles. 276 o A number of sections, set off by a section title (a line prefixed 277 with two or more "=".) 279 A section may contain: 281 o Other sections, whose level of nesting is indicated by the number 282 of "=" in their header. 284 o Blocks of text. Blocks can have metadata (including a title, an 285 anchor for cross-references, and attributes.) 287 Blocks can be: 289 o Paragraphs, which are terminated by blank lines. 291 o Lists. List items are by default paragraphs, but can span over 292 multiple paragraphs. 294 o Delimited blocks (with a line delimiter on either side of them); 295 these include tables, notes, sidebars, source code, block quotes, 296 examples, and unprocessed content (e.g. raw XML). Delimited 297 blocks contain by default one or more paragraphs. 299 o List items can contain other blocks, including both nested lists 300 and delimited blocks. 302 o Some delimited blocks can contain other delimited blocks; for 303 example, examples can contain source code as well as discussion in 304 paragraphs. 306 o Blocks of text consist of inline text, which itself can contain 307 markup. 309 Inline markup includes: 311 o Text formatting: Bold, italic, superscript, subscript, monospace. 313 o Markup macros: the "bcp14" and "comment" macros. (Asciidoctor 314 syntax supports custom markup macros.) 316 o URLs, including display text to render. 318 o Inline anchors. 320 o Cross-references to anchors (IDs of blocks or spans of text), 321 including display text to render. 323 o Images: SVG only, as specified in [RFC7996]. 325 o Index terms. 327 3.1. Unsupported features compared with Asciidoctor syntax 329 Several features from Asciidoctor are not supported within AsciiRFC 330 due to the lack of support within RFC XML, including: 332 o Audio and video files are not supported in AsciiRFC as today's RFC 333 XML structure does not support audio or video. 335 o Equations are not supported as there is no current RFC XML 336 equivalent. Asciidoctor provides native support for [AsciiMathML] 337 and [TeX-LaTeX], via the [MathJax] tool. 339 o Footnotes are not supported in AsciiRFC as there is no equivalent 340 semantic representation in RFC XML. 342 These carved out features can be easily supported by AsciiRFC once 343 RFC XML allows these elements. 345 3.2. Mapping To RFC XML syntax 347 The Asciidoctor syntax document structure aligns with both the RFC 348 XML v2 and the RFC XML v3 structure. In the following, RFC XML v3 349 equivalences are given to the basic Asciidoctor structure. 351 Header 352 "" attributes, most "front" elements. 354 Preamble 355 "front/abstract" and "front/note". 357 Sections 358 "middle/section" elements. 360 Sections with bibliography style attribute 361 "back/references" elements. 363 Sections with appendix style attribute 364 "back/section" elements. 366 Paragraphs 367 "t" elements. 369 Lists 370 "ul", "ol", "dl" elements. 372 Delimited blocks 373 "artwork", "aside", "blockquote", "figure", "note", "sourcecode", 374 "table". 376 Inline markup 377 "bcp14", "br", "cref", "em", "eref", "iref", "relref", "strong", 378 "sub", "sup", "tt", "xref". 380 Full details of the mapping of AsciiRFC elements to RFC XML v2 and v3 381 elements, and of how to convert AsciiRFC documents to RFC XML, are 382 given in the documentation of [asciidoctor-rfc]. 384 3.3. Example Illustrations 386 This document utilizes example documents provided in Appendix A for 387 demonstration of AsciiRFC syntax and usage. The source files and 388 published versions (at the IETF Datatracker) of these example 389 documents are available in Appendix A. 391 o "A Minimal Internet-Draft In AsciiRFC" Appendix A.1.1 393 o "The Holy Hand Grenade of Antioch" Appendix A.2.1 395 o "An API For Calendar-Based Fortune Heuristics Services" 396 Appendix A.3.1 398 3.4. Simple Illustration 400 This section gives an overview of how to create an RFC XML document 401 in AsciiRFC, with some pitfalls to be aware of. 403 Illustrations are in RFC XML v3 and RFC XML v2. 405 A sample AsciiRFC document is provided in Figure 1, together with its 406 corresponding rendering in: 408 o RFC XML v3 (Figure 2) 410 o RFC XML v2 (Figure 3) 412 413 = A Minimal Internet-Draft In AsciiRFC 414 :doctype: internet-draft 415 :name: draft-asciirfc-minimal-02 416 :abbrev: AsciiRFC Example 417 :status: informational 418 :ipr: trust200902 419 :submissionType: individual 420 :area: Internet 421 :intended-series: full-standard 422 :revdate: 2018-04-12T00:00:00Z 423 :fullname: Josiah Stinkney Carberry 424 :lastname: Carberry 425 :forename_initials: J. S. 426 :organization: Brown University 427 :phone: +1 401 863 1000 428 :street: Box K, 69 Brown Street 429 :city: Providence 430 :code: 02912 431 :country: United States of America 432 :uri: https://www.brown.edu 433 :email: josiah.carberry@ribose.com 434 :fullname_2: Truman Grayson 435 :lastname_2: Grayson 436 :forename_initials_2: T. 437 :organization_2: Brown University 438 :phone_2: +1 401 863 1000 439 :street_2: Box G, 69 Brown Street 440 :city_2: Providence 441 :code_2: 02912 442 :country_2: United States of America 443 :uri_2: https://www.brown.edu 444 :email_2: truman.grayson@ribose.com 446 [abstract] 448 This document provides a template on how to author (or migrate!) 449 a new Internet-Draft / RFC in the AsciiRFC format. 451 This template requires usage of the `asciidoctor-rfc` Ruby gem. 453 [#introduction] 454 == Introduction 456 AsciiRFC <> is an extremely simple way to 457 author Internet-Drafts and RFCs without needing to manually 458 craft RFC XML conforming to <>. 460 This is a template specifically made for authors to easily 461 start with creating an Internet-Draft conforming to <> 462 and submittable to the IETF datatracker. 464 [#conventions] 465 == Terms and Definitions 467 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 468 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 469 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this 470 document are to be interpreted as described in BCP 14 471 <> <> when, and only when, they appear in 472 all capitals, as shown here. 474 This document also refers to the following terms and 475 definitions: 477 AsciiRFC:: 478 an AsciiDoc-derived syntax used for authoring RFCs and 479 Internet-Drafts, as defined in <>. 481 [#symbols] 482 == Symbols And Abbreviations 484 ADRFC:: 485 abbreviated form of AsciiRFC 487 [#security] 488 == Security Considerations 490 Any security considerations should be placed here. 492 As described in <
> (here's how you refer a local anchor), 493 local tools have to be installed before the document template 494 can be built. 496 Running of these local tools *MAY* produce unintended side 497 effects that impact security. 499 [#iana] 500 == IANA Considerations 502 This document does not require any action by IANA. 504 But if it does, such as proposing changes to IANA registries, 505 please include them here. 507 [bibliography] 508 == Normative References 510 //bibliography::norm[] 511 ++++ 513 515 516 Key words for use in RFCs to Indicate Requirement 517 Levels 518 519 520 521 522 523 In many standards track documents several words are 524 used to signify the requirements in the specification. 525 These words are often capitalized. This document defines 526 these words as they should be interpreted in IETF 527 documents. This document specifies an Internet Best 528 Current Practices for the Internet Community, and 529 requests discussion and suggestions for improvements. 530 531 532 533 534 535 536 538 540 541 The "xml2rfc" Version 3 Vocabulary 542 543 544 545 546 547 This document defines the "xml2rfc" 548 version 3 vocabulary: an XML-based language used for 549 writing RFCs and Internet-Drafts. It is heavily derived 550 from the version 2 vocabulary that is also under 551 discussion. This document obsoletes the v2 grammar 552 described in RFC 7749. 553 554 555 556 557 559 561 562 Ambiguity of Uppercase vs Lowercase in RFC 2119 563 Key Words 564 565 566 567 568 569 RFC 2119 specifies common key words that may be 570 used in protocol specifications. This document aims to 571 reduce the ambiguity by clarifying that only UPPERCASE 572 usage of the key words have the defined special 573 meanings. 574 575 576 577 578 579 580 ++++ 582 [bibliography] 583 == Informative References 585 //bibliography::info[] 586 ++++ 588 590 591 IETF Trust Legal Provisions (TLP) 592 593 IETF 594 595 596 597 599 600 601 RNP: A C library approach to OpenPGP 602 603 Ribose Inc. 604
605 606 Suite 1111, 1 Pedder Street 607 Central 608 Hong Kong 609 Hong Kong 610 611 open.source@ribose.com 612 https://www.ribose.com 613
614 615 616 617 619 620 621 622 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 This document describes an AsciiDoc syntax 639 extension called AsciiRFC, designed for authoring IETF 640 Internet-Drafts and RFCs. AsciiDoc is a human readable document 641 markup language which affords more granular control over markup 642 than comparable schemes such as Markdown. The AsciiRFC syntax 643 is designed to allow the author to entirely focus on text, 644 providing the full power of the resulting RFC XML through the 645 AsciiDoc language, while abstracting away the need to manually 646 edit XML, including references. This document itself was 647 written and generated into RFC XML v2 (RFC7749) and RFC XML v3 648 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC 649 generator. 650 651 652 653 655 657 659 660 Rights Contributors Provide to the IETF Trust 661 663 664 665 667 668 669 670 The IETF policies about rights in Contributions 671 to the IETF are designed to ensure that such Contributions 672 can be made available to the IETF and Internet communities 673 while permitting the authors to retain as many rights as 674 possible. This memo details the IETF policies on rights in 675 Contributions to the IETF. It also describes the 676 objectives that the policies are designed to meet. This 677 memo obsoletes RFCs 3978 and 4748 and, with BCP 79 and 678 RFC 5377, replaces Section 10 of RFC 2026. This document 679 specifies an Internet Best Current Practices for the 680 Internet Community, and requests discussion and 681 suggestions for improvements. 682 683 684 685 686 688 690 691 The OCB Authenticated-Encryption Algorithm 692 693 694 695 696 697 698 699 This document specifies OCB, a shared-key 700 blockcipher-based encryption scheme that provides 701 confidentiality and authenticity for plaintexts and 702 authenticity for associated data. This document is a product 703 of the Crypto Forum Research Group (CFRG). 704 705 706 707 708 ++++ 710 [appendix] 711 [#appendix-a] 712 == Examples 714 === Example 1 716 Here's an example of a properly wrapped code snippet in 717 accordance with rules specified in <>. 719 [source,json] 720 ---- 721 722 { 723 "code": { 724 "encoding": "ascii", 725 "type": "rfc", 726 "authors": [ "Josiah Carberry", "Truman Grayson" ] 727 } 728 } 729 730 ---- 732 [#acknowledgements] 733 == Acknowledgements 735 The authors would like to thank their families. 736 738 Figure 1: Sample Internet-Draft in AsciiRFC 740 The first block of text, from "= Template For Writing An Internet- 741 Draft In AsciiRFC" through to ":email_2: thomas.kandell@brown.edu", 742 is the document header. It contains a title in the first line, an 743 author attribution ("Josiah Carberry; Thomas Kandell"), and then a 744 set of document attributes, conveying information about the document 745 as well as information about its authors. This information ends up 746 in RFC XML either as attributes of the root "rfc" tag, elements of 747 the "front" tag, or processing instructions. 749 The following blocks of text, up until the first section header ("== 750 Introduction"), are the document preamble. They are treated by the 751 document converter as containing the document abstract ("abstract"), 752 followed by any notes if present. 754 Section headers delimit the sections of the main body of the 755 document, starting with "== Introduction". The document converter 756 treats the first section of the document as the start of the "middle" 757 section in RFC XML. The first section header is followed by a 758 paragraph, and other sections and paragraphs. The number of "=" 759 signs can be one higher than that of the preceding section header, 760 which indicates that they are subsections of that section; so "=== 761 Operators" is a subsection of the preceding "== Symbols And 762 Abbreviations". 764 The paragraphs contain some inline formatting (e.g. boldface: 765 "*MUST*", monospace: "`type`"), and sections can also contain blocks 766 other than normal paragraphs; the section "== Operators", for 767 example, contains a definition list (whose terms are delimited by 768 "::"), and the subsection "=== Example 1" contains a code snippet 769 (delimited by "----", and tagged with the style attribute 770 "[source,json]", indicating that this is a JSON sourcecode listing). 771 The document can also include comments ("//" for inline, "////" for 772 blocks), which are not rendered when the document is processed. 774 The introductory section in this example contains a citation of a 775 reference, which in this version of AsciiRFC is treated identically 776 to a cross-reference ("<>") -- the crossreference being to 777 the references section of the document. Sections and blocks of texts 778 within the document can also be the target of crossreferences; for 779 example, the section header "=== Operators" is preceded by the anchor 780 "[#operators]", and that anchor is already referenced in the section 781 "== Security Considerations". 783 The third last and second last section are tagged with the style 784 attribute "[bibliography]", which identifies them as references 785 containers; the document converter accordingly inserts them into the 786 "back" element under RFC XML. The contents of the references 787 sections are in this instance raw XML, delimited as a passthrough 788 block (with "++++"), which the converter does not alter. 790 The final section is tagged with the style attribute "[appendix]", 791 and is treated as such. 793 The RFC XML v3 document generated from this AsciiRFC document is: 795 796 797 798 799 800 801 802 803 804 805 806 808 809 A Minimal Internet-Draft In 810 AsciiRFC 811 813 815 817 Brown University 818
819 820 Box K, 69 Brown Street 821 Providence 822 02912 823 United States of America 824 825 +1 401 863 1000 826 josiah.carberry@ribose.com 827 https://www.brown.edu 828
829 830 831 Brown University 832
833 834 Box G, 69 Brown Street 835 Providence 836 02912 837 United States of America 838 839 +1 401 863 1000 840 truman.grayson@ribose.com 841 https://www.brown.edu 842
843 844 845 Internet 847 This document provides a template on how to author (or 848 migrate!) 849 a new Internet-Draft / RFC in the AsciiRFC format. 850 This template requires usage of the asciidoctor-rfc Ruby 851 gem. 852 853
IntroductionAsciiRFC is an extremely simple way to 856 author Internet-Drafts and RFCs without needing to manually 857 craft RFC XML conforming to . 858 This is a template specifically made for authors to easily 859 start with creating an Internet-Draft conforming to 861 and submittable to the IETF datatracker.
862
Terms and 863 DefinitionsThe key words "MUST", "MUST 864 NOT", "REQUIRED", "SHALL", 865 "SHALL NOT", "SHOULD", "SHOULD 866 NOT", "RECOMMENDED", 867 "NOT RECOMMENDED", "MAY", and 868 "OPTIONAL" in this 869 document are to be interpreted as described in BCP 14 870 when, and only when, 871 they appear in 872 all capitals, as shown here. 873 This document also refers to the following terms and 874 definitions: 875
876
AsciiRFC
877
an AsciiDoc-derived syntax used for authoring RFCs and 878 Internet-Drafts, as defined in .
880
881
882 Symbols And Abbreviations 883
884
ADRFC
885
abbreviated form of AsciiRFC
886
887
888
Main 889 contentThis is where you place the main content, and the 890 following 891 serves as a placeholder for your text. 892 Subsections are used here for demonstration purposes. 893
Getting 894 startedThe AsciiRFC and RFC toolchains MUST be 895 available locally to 896 build this document template. 897
AsciiRFC 898 toolchainYou will need to have: 899
    900
  • Ruby: for running the AsciiRFC toolchain
    • 901
  • asciidoctor-rfc gem: for converting AsciiRFC into XML RFC 902 (v2 or v3)
    • 903
904
XML RFC 905 toolchainYou will need to have: 906
    907
  • Python: for running xml2rfc
    • 908
  • xml2rfc: for converting RFC XML (v2 or v3) into TXT
    • 909
  • idnits: for submission preflight
    • 910
911
912 Referencing external content 913
    914
  • This is a published RFC
    • 915
  • This is an Internet-Draft
    • 917
  • This is an external reference
    • 918
919
920
921 Code snippets 922 Code snippets should be wrapped with <CODE BEGINS> 923 and 924 <CODE ENDS> blocks, as required by the IETF Trust Legal 925 Provisions (TLP) specified in . 927
928
Security 929 ConsiderationsAny security considerations should be placed 930 here. 931 As described in (here’s how you refer a 932 local anchor), 933 local tools have to be installed before the document template 934 can be built. 935 Running of these local tools MAY produce unintended 936 side 937 effects that impact security.
938
IANA 939 ConsiderationsThis document does not require any action by 940 IANA. 941 But if it does, such as proposing changes to IANA registries, 942 please include them here.
943 944 945 Normative References 946 949 952 955 956 957 Informative References 958 960 961 IETF Trust Legal Provisions (TLP) 962 963 IETF 964 965 966 967 968 969 970 RNP: A C library approach to OpenPGP 971 972 Ribose Inc. 973
974 975 Suite 1111, 1 Pedder Street 976 Central 977 Hong Kong 978 Hong Kong 979 980 open.source@ribose.com 981 https://www.ribose.com 982
983 984 985 986 987 990 993 996 997
998 Examples 999
Example 1000 1Here’s an example of a properly wrapped code snippet in 1001 accordance with rules specified in . 1002
1003 1005 { 1006 "code": { 1007 "encoding": "ascii", 1008 "type": "rfc", 1009 "authors": [ "Josiah Carberry", "Truman Grayson" ] 1010 } 1011 } 1012 1013 ]]> 1014
1015
1016
1017 Acknowledgements 1018 The authors would like to thank their families. 1019
1020 1021 1022 1024 Figure 2: Sample Internet-Draft In AsciiRFC, Output In RFC XML v3 1025 Format 1027 Some default processing instructions have already been prefixed to 1028 the XML. 1030 Our AsciiRFC converter can also generate RFC XML v2 from the same 1031 source AsciiRFC, as shown in Figure 3. Output in RFC XML v2 is not 1032 extensively described in this document. 1034 1035 1036 1037 1040 1042 1044 1046 1048 1050 ]> 1051 1052 1053 1054 1055 1056 1057 1058 1060 1061 A Minimal Internet-Draft In 1062 AsciiRFC 1063 1065 Brown University 1066
1067 1068 Box K, 69 Brown Street 1069 Providence 1070 02912 1071 United States of America 1072 1073 +1 401 863 1000 1074 josiah.carberry@ribose.com 1075 https://www.brown.edu 1076
1077 1078 1079 Brown University 1080
1081 1082 Box G, 69 Brown Street 1083 Providence 1084 02912 1085 United States of America 1086 1087 +1 401 863 1000 1088 truman.grayson@ribose.com 1089 https://www.brown.edu 1090
1091 1092 1093 Internet 1095 This document provides a template on how to author (or 1096 migrate!) 1097 a new Internet-Draft / RFC in the AsciiRFC format. 1098 This template requires usage of the asciidoctor-rfc Ruby gem. 1100 1101
AsciiRFC is an extremely simple way to 1103 author Internet-Drafts and RFCs without needing to manually 1104 craft RFC XML conforming to . 1105 This is a template specifically made for authors to easily 1106 start with creating an Internet-Draft conforming to 1108 and submittable to the IETF datatracker.
1109
The key 1110 words "MUST", "MUST 1111 NOT", "REQUIRED", "SHALL", 1113 "SHALL NOT", "SHOULD", "SHOULD 1115 NOT", "RECOMMENDED", 1116 "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 1119 document are to be interpreted as described in BCP 14 1120 when, and only when, 1121 they appear in 1122 all capitals, as shown here. 1123 This document also refers to the following terms and 1124 definitions: 1125 1126 1127 an AsciiDoc-derived 1128 syntax used for authoring RFCs and 1129 Internet-Drafts, as defined in . 1131 1132
1133
1134 1135 1136 abbreviated form of 1137 AsciiRFC 1138 1139 1140
1141
This is where you place 1142 the main content, and the following 1143 serves as a placeholder for your text. 1144 Subsections are used here for demonstration purposes. 1145
The 1146 AsciiRFC and RFC toolchains MUST be 1147 available locally to 1148 build this document template. 1149
You will need to have: 1151 1152 1153 Ruby: for running the AsciiRFC toolchain 1154 asciidoctor-rfc gem: for converting 1155 AsciiRFC into XML RFC 1156 (v2 or v3) 1157 1158
1159
You 1160 will need to have: 1161 1162 1163 Python: for running xml2rfc 1164 xml2rfc: for converting RFC XML (v2 1165 or v3) into TXT 1166 idnits: for submission preflight 1167 1168
1169
1171 1172 1173 This is a published RFC 1174 This is an Internet-Draft 1176 This is an external reference 1177 1178 1179
1180
1181 Code snippets should be wrapped with <CODE 1182 BEGINS> and 1183 <CODE ENDS> blocks, as required by 1184 the IETF Trust Legal 1185 Provisions (TLP) specified in . 1187
1188
Any 1189 security considerations should be placed here. 1190 As described in (here’s how you refer a 1191 local anchor), 1192 local tools have to be installed before the document template 1193 can be built. 1194 Running of these local tools MAY 1195 produce unintended side 1196 effects that impact security.
1197
This document 1198 does not require any action by IANA. 1199 But if it does, such as proposing changes to IANA registries, 1200 please include them here.
1201 1202 1203 &RFC2119; 1204 &RFC7991; 1205 &RFC8174; 1206 1207 1208 1210 1211 IETF Trust Legal Provisions (TLP) 1212 1213 IETF 1214 1215 1216 1217 1218 1219 1220 RNP: A C library approach to OpenPGP 1221 1222 Ribose Inc. 1223
1224 1225 Suite 1111, 1 Pedder Street 1226 Central 1227 Hong Kong 1228 Hong Kong 1229 1230 open.source@ribose.com 1231 https://www.ribose.com 1232
1233 1234 1235 1236 1237 &I-D.ribose-asciirfc; 1238 &RFC5378; 1239 &RFC7253; 1240 1241
1242
Here’s an 1243 example of a properly wrapped code snippet in 1244 accordance with rules specified in . 1245
1246 1248 { 1249 "code": { 1250 "encoding": "ascii", 1251 "type": "rfc", 1252 "authors": [ "Josiah Carberry", "Truman Grayson" ] 1253 } 1254 } 1255 1256 ]]> 1257
1258
1259
1260 The authors would like to thank their families. 1261
1262 1263 1264 1266 Figure 3: Sample Internet-Draft In AsciiRFC, Output In RFC XML v2 1267 Format 1269 4. Header And Document Attributes 1271 The header gives the document title, followed by an optional author 1272 attribution, and a series of document attributes, with no empty 1273 lines. 1275 4.1. Title And Basic Attributes 1277 Document attributes are used to populate attributes of the root "rfc" 1278 element, "front" elements, and document-level processing 1279 instructions. 1281 o ":doctype:" determines whether the document will be considered 1282 "rfc" or "internet-draft", and interprets other attributes 1283 accordingly. 1285 o Certain attributes ("workgroup", "area", "keyword") are comma 1286 delimited, and result in repeated RFC XML elements. 1288 Figure 4 demonstrates how to set the document header in AsciiRFC, 1289 with its rendering in RFC XML v3 shown in Figure 5. 1291 1292 = The Holy Hand Grenade of Antioch 1293 Arthur son of Uther Pendragon 1294 :doctype: internet-draft 1295 :abbrev: Hand Grenade of Antioch 1296 :updates: 8140 1297 :submission-type: independent 1298 :name: draft-camelot-holy-grenade-00 1299 :status: informational 1300 :consensus: false 1301 :area: General, Operations and Management 1302 :keyword: rabbits, grenades, antioch, camelot 1303 :ipr: trust200902 1304 :toc-include: true 1305 :sort-refs: true 1306 :revdate: 2018-04-01 1307 1309 Figure 4: AsciiRFC Document Header 1311 1312 1316 1317 The Holy Hand Grenade of 1318 Antioch 1319 1321 1323 Camelot 1324
1325 1326 Palace 1327 Camel Lot 1 1328 Camelot 1329 antioch 1331 1333 1335 1337 Figure 5: AsciiRFC Document Header Rendered As RFC XML v3 1339 4.2. Detailed Author Information 1341 The document header can spell out further information about authors, 1342 including contact details. The AsciiRFC header is shown in Figure 6 1343 with its rendering in RFC XML v3 shown in Figure 7. 1345 1346 = The Holy Hand Grenade of Antioch 1347 Arthur son of Uther Pendragon 1348 :doctype: internet-draft 1349 :abbrev: Hand Grenade of Antioch 1350 :updates: 8140 1351 :submission-type: independent 1352 :name: draft-camelot-holy-grenade-00 1353 :status: informational 1354 :consensus: false 1355 :area: General, Operations and Management 1356 :keyword: rabbits, grenades, antioch, camelot 1357 :ipr: trust200902 1358 :toc-include: true 1359 :sort-refs: true 1360 :revdate: 2018-04-01 1361 :fullname: Arthur son of Uther Pendragon 1362 :forename_initials: A. 1363 :lastname: Pendragon 1364 :email: arthur.pendragon@ribose.com 1365 :organization: Camelot 1366 :uri: http://camelot.gov.example 1367 :street: Palace\ Camel Lot 1 1368 :city: Camelot 1369 :country: England 1370 :comments: yes 1371 1373 Figure 6: AsciiRFC Document Header With One Author 1375 1376 1380 1381 The Holy Hand Grenade of 1382 Antioch 1383 1385 1387 Camelot 1388
1389 1390 Palace 1391 Camel Lot 1 1392 Camelot 1393 England 1394 1395 arthur.pendragon@ribose.com 1396 http://camelot.gov.example 1397
1398 1399 1400 General 1401 Operations and Management 1402 rabbits 1403 grenades 1404 antioch 1405 camelot 1407 1409 1411 1413 Figure 7: AsciiRFC Document Header With One Author (RFC XML v3) 1415 Details of a second, third etc. author, including their organization 1416 and contact details, are provided by suffixing the relevant author 1417 attributes with "_2", "_3" etc., as shown in Figure 8 and its RFC XML 1418 v3 rendering Figure 9. 1420 1421 = An API For Calendar-Based Fortune Heuristics Services 1422 Gabriel Destiny; Charise Luck 1423 :doctype: internet-draft 1424 :abbrev: Calendar Fortune Heuristics API 1425 :name: draft-divination-cfapi-00 1426 :status: informational 1427 :ipr: trust200902 1428 :area: Internet 1429 :submission-type: independent 1430 :intended-series: informational 1431 :revdate: 2018-03-23T00:00:00Z 1432 :lastname: Destiny 1433 :fullname: Gabriel Destiny 1434 :forename_initials: G. 1435 :organization: Divination Inc. 1436 :email: gabriel.destiny@ribose.com 1437 :street: 9288 N Divine Street 1438 :city: Dunn 1439 :code: 28334 1440 :region: NC 1441 :country: United States of America 1442 :lastname_2: Luck 1443 :fullname_2: Charise Luck 1444 :forename_initials_2: C. 1445 :organization_2: Divination Inc. 1446 :email_2: charise.luck@ribose.com 1447 :street_2: 9288 N Divine Street 1448 :city_2: Dunn 1449 :code_2: 28334 1450 :region_2: NC 1451 :country_2: United States of America 1452 1454 Figure 8 1456 1457 1460 1461 An API For 1462 Calendar-Based Fortune Heuristics Services 1463 1465 1467 1468 Divination Inc. 1469
1470 1471 9288 N Divine Street 1472 Dunn 1473 NC 1474 28334 1475 United States of America 1476 1477 gabriel.destiny@ribose.com 1478
1479 1480 1481 Divination Inc. 1482
1483 1484 9288 N Divine Street 1485 Dunn 1486 NC 1487 28334 1488 United States of America 1489 1490 charise.luck@ribose.com 1491
1492 1493 1494 Internet 1496 1498 1500 1502 Figure 9: AsciiRFC Document Header With Multiple Authors (RFC XML v3) 1503 The initial author attribution in AsciiRFC, e.g. "Gabriel Destiny; 1504 Charlise Luck" in the example above, expects a strict format of First 1505 Name, zero or more Middle Names, Last name, and cannot process 1506 honorifics like "Dr." or suffixes like "Jr.". 1508 Name attributes with any degree of complexity should be overriden by 1509 using the ":fullname:" and ":lastname:" attributes. The AsciiRFC 1510 ":forename_initials:" attribute replaces the built-in Asciidoctor 1511 syntax ":initials:" attribute (which includes the surname initial), 1512 and is not automatically populated from the name attribution. 1514 4.3. XML Processing Information 1516 A document header may also contain attribute headers which are 1517 treated as XML processing instructions. An AsciiRFC example is shown 1518 in Figure 10 with its rendering in Figure 11. (Note that several 1519 processing instructions are included by default in the output of the 1520 AsciiRFC processor.) 1522 1523 = The Holy Hand Grenade of Antioch 1524 Arthur son of Uther Pendragon 1525 :doctype: internet-draft 1526 :abbrev: Hand Grenade of Antioch 1527 :updates: 8140 1528 :submission-type: independent 1529 :name: draft-camelot-holy-grenade-00 1530 :status: informational 1531 :consensus: false 1532 :ipr: trust200902 1533 :notedraftinprogress: yes 1534 :smart-quotes: false 1535 1537 Figure 10: AsciiRFC Document Header With XML Processing Information 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1556 1557 The Holy Hand Grenade of 1558 Antioch 1559 1561 1563 Camelot 1564
1565 1566 Palace 1567 Camel Lot 1 1568 Camelot 1569 antioch 1570 1572 Figure 11: AsciiRFC Document Header With XML Processing Information 1573 (RFC XML v3) 1575 In the foregoing, values for the processing instructions "strict", 1576 "compact", "toc" etc are included by default; but "comments" and 1577 "notedraftinprogress" are included as specified in the AsciiRFC 1578 document header. The default values provided for processing 1579 instructions can in fact be overriden through the AsciiRFC document 1580 header. 1582 4.4. AsciiRFC-specific Document Attributes 1584 A few document attributes are specific to the operation of the RFC 1585 XML document converter: 1587 :no-rfc-bold-bcp14: false 1588 overrides the wrapping by default of boldface uppercase BCP14 1589 [RFC2119] words (e.g. "*MUST NOT*") with the "bcp14" element. 1591 :smart-quotes: false 1592 overrides Asciidoctor's conversion of straight quotes and 1593 apostrophes to smart quotes and apostrophes. 1595 :inline-definition-lists: true 1596 overrides the RFC XML v2 "idnits" requirement that a blank line be 1597 inserted between a definition list term and its definition. 1599 1600 = The Holy Hand Grenade of Antioch 1601 Arthur son of Uther Pendragon 1602 :doctype: internet-draft 1603 :status: informational 1604 :name: draft-camelot-holy-grenade-00 1606 == Section 1 1607 The specification *MUST NOT* use the word _doesn't_. 1608 1610 Figure 12: AsciiRFC Document Header Without RFC-specific Attributes 1612 1613 1615 1616 The Holy Hand Grenade of Antioch 1617 1619 1622 1623 1624 1625 1626
1627 Section 1 1628 The specification MUST NOT 1629 use the word doesn’t. 1630
1631 1632 1633 1635 Figure 13: AsciiRFC Document Header Without RFC-specific Attributes 1636 (RFC XML v3) 1638 1639 = The Holy Hand Grenade of Antioch 1640 Arthur son of Uther Pendragon 1641 :doctype: internet-draft 1642 :status: informational 1643 :name: draft-camelot-holy-grenade-00 1644 :no-rfc-bold-bcp14: false 1645 :smart-quotes: false 1647 == Section 1 1648 The specification *MUST NOT* use the word _doesn't_. 1649 1651 Figure 14: AsciiRFC Document Header With Overridden RFC-specific 1652 Attributes 1654 1655 1657 1658 The Holy Hand Grenade of Antioch 1659 1661 1664 1665 1666 1667 1668
1669 Section 1 1670 The specification MUST NOT 1671 use the word doesn't. 1672
1673 1674 1675 1677 Figure 15: AsciiRFC Document Header With Overridden RFC-specific 1678 Attributes (RFC XML v3) 1680 5. Preamble 1682 The preamble in AsciiRFC is the text between the end of the document 1683 header (which terminates with a blank line) and the first section of 1684 text. 1686 Any paragraphs of text in the preamble are treated as an abstract, 1687 and may optionally be tagged with the "abstract" style attribute. 1689 Any notes in the preamble are treated as a "note" element. 1691 An example of setting the preamble is given in Figure 16 with its 1692 rendering in Figure 17. 1694 1696 [abstract] 1697 The menagerie of beasts and artefacts depicted in RFC8140 1698 may be usefully supplemented by other renowned figures of 1699 Internet and more general lore. This document extends the 1700 menagerie to the seminal fable of the 1701 "Holy Hand Grenade of Antioch", as depicted in the 1702 Monty Python film "Monty Python and the Holy Grail", 1703 as well as "Spamalot", the musical inspired by the movie. 1705 [NOTE,remove-in-rfc=false] 1706 .Spamalot 1707 The relevance of the musical "Spamalot" to Internet lore should be 1708 obvious to the reader; but in case of doubt, see also 1709 Section 1 ("What is Spam*?") of RFC2635. 1711 1713 Figure 16: AsciiRFC With Preamble 1715 1716 1718 The menagerie of beasts and artefacts depicted in RFC8140 1719 may be usefully supplemented by other renowned figures of 1720 Internet and more general lore. This document extends the 1721 menagerie to the seminal fable of the 1722 "Holy Hand Grenade of Antioch", as depicted in the 1723 Monty Python film "Monty Python and the Holy Grail", 1724 as well as "Spamalot", the musical inspired by the 1725 movie. 1726 Spamalot 1727 The relevance of the musical "Spamalot" to Internet lore should be 1728 obvious to the reader; but in case of doubt, see also 1729 Section 1 ("What is Spam*?") of RFC2635. 1730 1732 1733 1735 Figure 17: AsciiRFC With Preamble (RFC XML v3) 1737 6. Sections and Paragraphs 1739 Section headers are given with a sequence of "=", where the number of 1740 instances of "=" gives the header level. The document itself opens 1741 with a single "=", and sections within it must be started with a 1742 minimum of "==". 1744 Section numbering is toggled with the in-document attribute 1745 ":sectnums:" (on), ":sectnums!:" (off). The boolean "toc" attribute 1746 can also be set on sections, indicating whether the section can be 1747 included in the document's table of contents. 1749 Figure 18 shows how sections and paragraphs are used in AsciiRFC, and 1750 its rendered form is shown in Figure 19. 1752 1754 [toc=exclude] 1755 :sectnums!: 1756 == Terminology 1758 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 1759 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 1760 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 1761 are to be interpreted as described in BCP 14 <> <> 1762 when, and only when, they appear in all capitals, as shown here. 1764 :sectnums: 1765 == Introduction 1767 <> refers to the intended move of RFC formatting to 1768 XML2RFC v3 <>, in the following terms: 1770 1772 Figure 18: AsciiRFC With Sections 1774 1776 1777
1778 Terminology 1779 The key words "MUST", "MUST NOT", 1780 "REQUIRED", "SHALL", 1781 "SHALL NOT", "SHOULD", "SHOULD 1782 NOT", "RECOMMENDED", 1783 "NOT RECOMMENDED", "MAY", and 1784 "OPTIONAL" in this document 1785 are to be interpreted as described in BCP 14 1786 1787 when, and only when, they appear in all capitals, as shown here. 1788
1789
Introduction refers to 1791 the intended move of RFC formatting to 1792 XML2RFC v3 , in the following terms: 1794 1796 Figure 19: AsciiRFC With Sections (RFC XML v3) 1798 Note that skipped sections, such as defining a section using "====" 1799 within a section defined using "==", is not allowed in AsciiRFC 1800 syntax. Doing so will trigger an error with the following message: 1802 asciidoctor: WARNING: _filename_: line _X_: 1803 section title out of sequence: expected level 2, got level 3 1805 7. Figures 1807 AsciiRFC examples (corresponding to RFC XML Figures), source code 1808 Listings, and Literals (preformatted text) are all delimited blocks. 1809 Listings and Literals can occur nested within Examples. 1811 An AsciiRFC example with a figure is given in Figure 20, and its 1812 rendering in Figure 21. 1814 1816 [[killer-bunny]] 1817 .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 1818 ==== 1819 [alt=The Killer Bunny, in ASCII] 1820 .... 1821 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1822 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1823 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 1824 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 1825 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 1826 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 1827 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 1828 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 1829 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 1830 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 1831 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 1832 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 1833 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 1834 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 1835 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 1836 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 1837 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 1838 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 1839 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 1840 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 1841 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 1842 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 1843 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 1844 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 1845 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 1846 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 1847 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 1848 MW \\/\||v v|| -\\-------___ . ., \ | 1849 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 1850 ) /--------^-^ ,. \|// 1851 # \(/ .\\|x// " ' ' 1852 . , \\||// \||\\\// \\ 1853 .... 1854 ==== 1856 [[killer-source]] 1857 .C Code To Lure Killer Rabbit Back To Cave 1858 ==== 1859 [source,c] 1860 ---- 1861 1862 /* Locate the Killer Rabbit */ 1863 int type; 1864 unsigned char *killerRabbit = 1865 LocateCreature(&caerbannog, "killer rabbit"); 1866 if( killerRabbit == 0 ){ 1867 puts("The Killer Rabbit of Caerbannog is out of town."); 1868 return LOST_CREATURE; 1869 } 1870 /* Load Cave */ 1871 unsigned char *cave = LoadPlace(&caerbannog, 1872 "The Cave Of Caerbannog"); 1873 if( cave == 0 ){ 1874 puts("The Cave of Caerbannog must have moved."); 1875 return LOST_PLACE; 1876 } 1878 /* Lure the Killer Rabbit back into the Cave */ 1879 unsigned char *carrot = allocateObjectInPlace( 1880 carrot("fresh"), cave); 1881 if( carrot == 0 ){ 1882 puts("No carrot, no rabbit."); 1883 return LOST_LURE; 1884 } 1886 /* Finally, notify the Killer Rabbit to act */ 1887 return notifyCreature(killerRabbit, &carrot); 1888 1889 ---- 1890 ==== 1892 1894 Figure 20: AsciiRFC With A Figure 1896 1898
1899 A Photo Of The Killer Rabbit of Caerbannog Taken In 1900 Secret 1901 >>\\\\\\\\\\\\ 1906 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 1907 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 1908 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 1909 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 1910 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 1911 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 1912 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 1913 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 1914 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 1915 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 1916 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 1917 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 1918 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 1919 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 1920 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 1921 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 1922 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 1923 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 1924 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 1925 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 1926 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 1927 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 1928 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 1929 MW \\/\||v v|| -\\-------___ . ., \ | 1930 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 1931 ) /--------^-^ ,. \|// 1932 # \(/ .\\|x// " ' ' 1933 . , \\||// \||\\\// \\ 1934 ]]> 1935
1936
1937 C Code To Lure Killer Rabbit Back To Cave 1938 1940 /* Locate the Killer Rabbit */ 1941 int type; 1942 unsigned char *killerRabbit = 1943 LocateCreature(&caerbannog, "killer rabbit"); 1944 if( killerRabbit == 0 ){ 1945 puts("The Killer Rabbit of Caerbannog is out of town."); 1946 return LOST_CREATURE; 1947 } 1949 /* Load Cave */ 1950 unsigned char *cave = LoadPlace(&caerbannog, 1951 "The Cave Of Caerbannog"); 1952 if( cave == 0 ){ 1953 puts("The Cave of Caerbannog must have moved."); 1954 return LOST_PLACE; 1955 } 1957 /* Lure the Killer Rabbit back into the Cave */ 1958 unsigned char *carrot = allocateObjectInPlace( 1959 carrot("fresh"), cave); 1960 if( carrot == 0 ){ 1961 puts("No carrot, no rabbit."); 1962 return LOST_LURE; 1963 } 1964 /* Finally, notify the Killer Rabbit to act */ 1965 return notifyCreature(killerRabbit, &carrot); 1966 1967 ]]> 1968
1970 1972 Figure 21: AsciiRFC With A Figure (RFC XML v3) 1974 If an AsciiRFC Listing or Literal occurs outside of an Example 1975 (Figure 22), the RFC XML converter will supply the surrounding 1976 Figure element (Figure 23). 1978 1980 [[hand-grenade-figure]] 1981 .The Holy Hand Grenade of Antioch (don't pull the pin) 1983 Figure 22: AsciiRFC With ASCII Art Without Figure Wrapping 1985 ______ 1986 \\/ \/ 1987 __\\ /__ 1988 || //\ | 1989 ||__\\/ __| 1990 || | ,---, 1991 || |====`\ | 1992 || | '---' 1993 ,--'*`--, 1994 _||#|***|#| 1995 _,/.-'#|* *|#`-._ 1996 ,,-'#####| |#####`-. 1997 ,,'########| |########`, 1998 //##########| o |##########\ 1999 ||###########| |###########| 2000 ||############| o |############| 2001 ||------------' '------------| 2002 ||o o o o o o o o o o| 2003 |-----------------------------| 2004 ||###########################| 2005 \\#########################/ 2006 `..#####################,' 2007 ``..###############_,' 2008 ``--.._____..--' 2009 `''-----''` 2010 2012 2014
2015 The Holy Hand Grenade of Antioch (don't pull the pin) 2016 2044
2046 2048 Figure 23: AsciiRFC With ASCII Art Without Figure Wrapping (RFC XML 2049 v3) 2051 8. Lists 2052 8.1. Basic Lists 2054 AsciiRFC supports ordered, unordered, and definition lists. 2055 Indentation of ordered and unordered lists is indicated by repeating 2056 the list item prefix ("*" and "." respectively); for definition 2057 lists, it is indicated by incrementing the number of definition term 2058 delimiters ("::"). 2060 List attributes can be used to specify the type of symbol used for 2061 ordered lists. 2063 An example of an unordered list is shown in Figure 24 (with its 2064 rendered version in Figure 25). An example of an ordered list with 2065 ordered and unordered sublists is shown in Figure 26 (with its 2066 rendered version in Figure 27). An example of a definition list is 2067 shown in Figure 28 (with its rendered version in Figure 29). 2069 2071 * Killed 2072 ** Sir Bors 2073 ** Sir Gawain 2074 ** Sir Ector 2075 * Soiled Himself 2076 ** Sir Robin 2077 * Panicked 2078 ** King Arthur 2079 * Employed Ordnance 2080 ** The Lector 2081 ** Brother Maynard 2082 * Scoffed 2083 ** Tim the Enchanter 2085 2087 Figure 24: AsciiRFC With Unordered lists 2089 2091
    2092
  • 2093 Killed 2094
      2095
    • Sir Bors
      • 2096
    • Sir Gawain
      • 2097
    • Sir Ector
      • 2098
    2099
    • 2100
  • 2101 Soiled Himself 2102
      2103
    • Sir Robin
      • 2104
    2105
    • 2106
  • 2107 Panicked 2108
      2109
    • King Arthur
      • 2110
    2111
    • 2112
  • 2113 Employed Ordnance 2114
      2115
    • The Lector
      • 2116
    • Brother Maynard
      • 2117
    2118
    • 2119
  • 2120 Scoffed 2121
      2122
    • Tim the Enchanter
      • 2123
    2124
    • 2125
2127 2129 Figure 25: AsciiRFC With Unordered Lists (RFC XML v3) 2131 2133 . Preamble: St Attila Benediction 2134 . Feast of the People on Sundry Foods 2135 ** Lambs 2136 ** Sloths 2137 ** Carp 2138 ** Anchovies 2139 ** Orangutangs 2140 ** Breakfast Cereals 2141 ** Fruit Bats 2142 ** _et hoc genus omne_ 2143 . Take out the Holy Pin 2144 . The Count 2145 [upperalpha] 2146 .. Count is to Three: no more, no less 2147 .. Not Four 2148 .. Nor Two, except if the count then proceeds to Three 2149 .. Five is Right Out 2150 . Lob the Holy Hand Grenade of Antioch towards the Foe 2151 . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it 2153 2155 Figure 26: AsciiRFC With Ordered lists 2157 2159
    2160
  1. Preamble: St Attila Benediction
    2. 2161
  2. 2162 Feast of the People on Sundry Foods 2163
      2164
    • Lambs
      • 2165
    • Sloths
      • 2166
    • Carp
      • 2167
    • Anchovies
      • 2168
    • Orangutangs
      • 2169
    • Breakfast Cereals
      • 2170
    • Fruit Bats
      • 2171
    • 2172 et hoc genus omne 2173
      • 2174
    2175
    3. 2176
  3. Take out the Holy Pin
    4. 2177
  4. 2178 The Count 2179
      2180
    1. Count is to Three: no more, no less
      2. 2181
    2. Not Four
      3. 2182
    3. Nor Two, except if the count then proceeds to Three
      4. 2183
    4. Five is Right Out
      5. 2184
    2185
    5. 2186
  5. Lob the Holy Hand Grenade of Antioch towards the Foe
    6. 2187
  6. The Foe, being naughty in the LORD's sight, 2188 SHALL snuff it
    7. 2189
2191 2193 Figure 27: AsciiRFC With Ordered Lists (RFC XML v3) 2195 2197 Holy Hand Grenade of Antioch:: 2198 Ordnance deployed by Brother Maynard under the incantation of a 2199 lector, in order to dispense with the Foes of the Virtuous. 2200 See <>. 2202 Holy Spear of Antioch:: 2203 A supposed relic of the crucifixion of Jesus Christ, this is one 2204 of at least four claimed instances of the lance that pierced 2205 Christ's side. Its historical significance lies in inspiring 2206 crusaders to continue their siege of Antioch in 1098. 2208 Sovereign's Orb of the United Kingdom:: 2209 Part of the Crown Jewels of the United Kingdom, the Sovereign's 2210 Orb is a hollow gold sphere set with jewels and topped with a 2211 cross. It was made for Charles II in 1661. See <>. 2213 2215 Figure 28: AsciiRFC With Definition lists 2217 2219
2220
Holy Hand Grenade of Antioch
2221
Ordnance deployed by Brother Maynard under the incantation of a 2222 lector, in order to dispense with the Foes of the Virtuous. 2223 See .
2224
Holy Spear of Antioch
2225
A supposed relic of the crucifixion of Jesus Christ, this is one 2226 of at least four claimed instances of the lance that pierced 2227 Christ's side. Its historical significance lies in inspiring 2228 crusaders to continue their siege of Antioch in 1098.
2229
Sovereign's Orb of the United Kingdom
2230
Part of the Crown Jewels of the United Kingdom, the Sovereign's 2231 Orb is a hollow gold sphere set with jewels and topped with a 2232 cross. It was made for Charles II in 1661. See .
2234
2236 2238 Figure 29: AsciiRFC With Definition Lists (RFC XML v3) 2240 8.2. List Continuation 2242 A list item by default spans a single paragraph. A following 2243 paragraph or other block element can be appended to the current list 2244 item by prefixing it with "+" in a separate line. 2246 See the "List Continuation" section in [Asciidoctor-Manual] for more 2247 information. 2249 An example of list continuation with text is shown in Figure 30 with 2250 its rendered version in Figure 31. 2252 2254 Trojan Rabbit:: 2255 In their siege of the French-occupied castle which may already 2256 contain an instance of the Grail, Sir Bedevere the Wise proposes to 2257 use a Trojan Rabbit to infiltrate the castle, with a raiding party 2258 to take the French "not only by surprise, but totally unarmed." 2259 + 2260 The proposal, unsurprisingly, proved abortive. The more so as the 2261 raiding party forgot to hide within the Trojan Rabbit, before the 2262 French soldiers took the Trojan Rabbit inside the castle. 2264 Killer Rabbit of Caerbannog:: 2265 Guarding the entrance to the Cave of Caerbannog; see <>. 2267 2269 Figure 30: AsciiRFC List With Text Continuation 2271 2273
2274
Trojan Rabbit
2275
2276 In their siege of the French-occupied castle which may already 2277 contain an instance of the Grail, Sir Bedevere the Wise proposes to 2278 use a Trojan Rabbit to infiltrate the castle, with a raiding party 2279 to take the French "not only by surprise, but totally unarmed." 2280 The proposal, unsurprisingly, proved abortive. The more so as the 2281 raiding party forgot to hide within the Trojan Rabbit, before the 2282 French soldiers took the Trojan Rabbit inside the castle. 2283
2284
Killer Rabbit of Caerbannog
2285
Guarding the entrance to the Cave of Caerbannog; see .
2287
2289 2291 Figure 31: AsciiRFC List With Text Continuation (RFC XML v3) 2293 (Multiple paragraphs are not permitted within a list item in RFC XML 2294 v2. The RFC XML converter deals with this by converting paragraph 2295 breaks into line breaks within a list item.) 2297 List continuations can also be embedded to populate a list item with 2298 a sequence of blocks as a unit (in an Asciidoctor syntax open block). 2300 An example of list continuation with a delimited block is shown in 2301 Figure 32 with its rendered version in Figure 33. 2303 2305 . Take out the Holy Pin 2306 . The Count 2307 + 2308 ---- 2309 integer count; 2310 for count := 1 step 1 until 3 do 2311 say(count) 2312 comment Five is Right Out 2313 ---- 2314 . Lob the Holy Hand Grenade of Antioch towards the Foe 2315 . Foe snuffs it 2317 2319 Figure 32: AsciiRFC List With Block Continuation 2321 2323
    2324
  1. Take out the Holy Pin
    2. 2325
  2. 2326 The Count 2327
    2328 2334
    2335
    3. 2336
  3. Lob the Holy Hand Grenade of Antioch towards the Foe
    4. 2337
  4. Foe snuffs it
    5. 2338
2340 2342 Figure 33: AsciiRFC List With Block Continuation (RFC XML v3) 2344 AsciiDoc, and thus AsciiRFC, considers paragraphs to be the basic 2345 level of blocks, and does not permit lists to be nested within them: 2346 any text after a list is considered to be a new paragraph. 2348 Therefore, markup as shown in Figure 34 cannot be generated via 2349 AsciiRFC. 2351 2352 2353 This is the start of a paragraph. 2354
    2355
  • List Entry 1
    • 2356
  • 2357 List Entry 2 2358 Note 2. 2359
    • 2360
2361 And this is the continuation of the paragraph. 2362 2363 2365 Figure 34: This RFC XML v3 Output Cannot Be Generated Using AsciiRFC 2367 9. Blockquotes 2369 Asciidoctor syntax supports blockquotes and quotations of verse; its 2370 block quotations permit arbitrary levels of quote nesting. RFC XML 2371 v3, and thus AsciiRFC, only supports one level of blockquotes. 2373 Unlike RFC XML v2, RFC XML v3 does not support line breaks outside of 2374 tables, so verse quotations are converted to prose in the v3 2375 converter. 2377 An example of using AsciiRFC Blockquotes is given in Figure 35 with 2378 its rendered version in Figure 36. 2380 2382 [quote,attribution="A. Farrel"] 2383 ____ 2384 Although the RFC Editor has recently dragged the IETF kicking and 2385 screaming into the twentieth century [RFC7990] [RFC7996], there is a 2386 yearning among all right-thinking Internet architects to "keep it 2387 simple" and to return to the olden days when pigs could be given 2388 thrust without anyone taking undue offence. 2389 ____ 2391 2393 Figure 35: AsciiRFC Blockquote Usage 2395 2397
2398 Although the RFC Editor has recently dragged the IETF kicking and 2399 screaming into the twentieth century [RFC7990] [RFC7996], there is a 2400 yearning among all right-thinking Internet architects to "keep it 2401 simple" and to return to the olden days when pigs could be given 2402 thrust without anyone taking undue offence. 2403
2405 2407 Figure 36: AsciiRFC Blockquote Usage (RFC XML v3) 2409 10. Notes And Asides 2411 Asciidoctor syntax supports a range of "admonitions", including 2412 notes, warnings, and tips. They are indicated by a paragraph prefix 2413 (e.g. "WARNING:"), or as a block with an admonition style attribute. 2415 All admonitions are conflated in AsciiRFC, being converted to "note" 2416 elements in the document preamble, and "cref" elements in the main 2417 document. 2419 This means that no admonitions will therefore appear in the textual 2420 output, unless forced to through the "comments" processing 2421 instruction. A sample admonition is shown in Figure 37, with its 2422 rendered output in Figure 38. 2424 2426 [NOTE,display=true,source=Author] 2427 ==== 2428 Image courtesy of 2429 https://camelot.gov.example/creatures-in-ascii/ 2430 ==== 2432 2434 Figure 37: An AsciiRFC Adminition Block 2436 2438 Image courtesy of 2439 2442 2444 Figure 38: An AsciiRFC Adminition Block (RFC XML v3) 2446 With RFC XML v2, note that no inline formatting is permitted for 2447 "cref" elements, and any such formatting is therefore stripped for v2 2448 by the converter. 2450 Because paragraphs in AsciiRFC cannot contain any other blocks, a 2451 comment at the end of a paragraph is treated as a new block. In the 2452 document converter, any such comments are moved inside the preceding 2453 RFC XML paragraph; if the comment is at the start of a section, as in 2454 the example above, it is wrapped inside a paragraph. 2456 The RFC XML v3 converter also supports "asides" (Asciidoctor syntax 2457 Sidebars). A sample is shown in Figure 39, with its rendered output 2458 in Figure 40. 2460 2462 **** 2463 While the exchange at the French-occupied castle is one of 2464 the more memorable scenes of _Monty Python and the Holy Grail_, 2465 the Trojan Rabbit has not reached the same level of cultural 2466 resonance as its more murderous counterpart. Reasons for this 2467 may include: 2469 * Less overall screen-time dedicated to the Trojan Rabbit. 2471 * The Trojan Rabbit as projectile has already been anticipated 2472 by the Cow as projectile. 2473 **** 2475 2477 Figure 39: An AsciiRFC Sidebar Block 2479 2481 2492 2494 Figure 40: An AsciiRFC Sidebar Block Rendered As An Aside (RFC XML 2495 v3) 2497 Comments given in AsciiDoc syntax (notated with initial "//") are not 2498 intended to be shown in the rendered output, and will not appear in 2499 the output as XML comments. XML comments can be generated by using 2500 the "[comment]#...#" inline formatting macro, or the "[.comment]" 2501 role attribute on blocks. A sample is shown in Figure 39 with its 2502 rendered output in Figure 40. 2504 2506 The exchange of projectile animals was the beginning of a 2507 long-running fruitful relationship between the British and the 2508 French peoples, 2509 [comment]#TODO: Will need to verify that claim.# which 2510 arguably predates the traditional English enmity with the 2511 French. [comment]#Strictly speaking, the Knights are Welsh.# 2513 [.comment] 2514 -- 2515 This document, as it turns out, has a profusion of XML comments. 2517 As expected, they are ignored in any rendering of the document. 2518 -- 2520 2522 Figure 41: AsciiRFC delimited text intended as an XML Comment 2524 2526 The exchange of projectile animals was the beginning of a 2527 long-running fruitful relationship between the British and the 2528 French peoples, 2530 2532 which 2533 arguably predates the traditional English enmity with the 2534 French. 2536 2538 2540 2545 2547 Figure 42: AsciiRFC delimited text Rendered As An XML Comment (RFC 2548 XML v3) 2550 11. Tables 2552 AsciiRFC tables, like RFC XML v3, support distinct table heads, 2553 bodies and feet; cells spanning multiple rows and columns; and 2554 horizontal alignment. The larger range of table formatting options 2555 available in RFC XML v2 is also supported. 2557 A sample of an AsciiRFC table is shown in Figure 43, with its 2558 rendered output in Figure 44. 2560 Neither version of RFC XML is as expressive in its table structure as 2561 Asciidoctor syntax. RFC XML, for example, does not permit blocks 2562 within table cells. 2564 2566 [grid=all,options="footer"] 2567 |=== 2568 |French Castle | Cave of Caerbannog 2570 2+|King Arthur 2571 2+|Patsy 2572 2+|Sir Bedevere the Wise 2573 2+|Sir Galahad the Pure 2574 2+|Sir Lancelot the Brave 2575 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot 2576 |French Guard with Outrageous Accent| Tim the Enchanter 2577 |Other French Guards | Brother Maynard 2578 | | The Lector 2579 .3+^|not yet recruited 2580 >|Sir Bors 2581 >|Sir Gawain 2582 >|Sir Ector 2584 |Retinue of sundry knights 2585 |Retinue of sundry more knights than at the French Castle 2586 |=== 2588 2590 Figure 43: An AsciiRFC Table 2592 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2649 2650 2651
French CastleCave of Caerbannog
King Arthur
Patsy
Sir Bedevere the Wise
Sir Galahad the Pure
Sir Lancelot the Brave
Sir Robin the 2619 Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous AccentTim the Enchanter
Other French GuardsBrother Maynard
2631 The Lector
not yet recruitedSir Bors
Sir Gawain
Sir Ector
Retinue of sundry knightsRetinue of sundry more knights than at the 2648 French Castle
2653 2655 Figure 44: An AsciiRFC Table (RFC XML v3) 2657 12. Inline Formatting 2659 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts 2661 AsciiRFC supports italics, boldface, monospace, subscripts and 2662 superscripts, just like RFC XML v3. 2664 The inline formatting syntax given in Figure 45 produces the RFC XML 2665 v3 output given in Figure 46. 2667 2669 The participants of that renowned exercise in cross-cultural 2670 communication, to wit the exchange between the 2671 _Knights of the Round Table_ 2672 and the taunting French soldiers serving under *Guy de Lombard* are, 2673 properly speaking, outside the scope of this `menagerie`, being more 2674 or less human. Notwithstanding, several^ish^ beasts both animate~d~ 2675 and wooden played a significant part in this encounter; most 2676 notably: 2678 * The Projectile Cow, see <> 2679 * The Trojan Rabbit, see <> 2681 2683 Figure 45: Inline Formatting In AsciiRFC 2685 2687 The participants of that renowned exercise in cross-cultural 2688 communication, to wit the exchange between the 2689 Knights of the Round Table 2690 and the taunting French soldiers serving under Guy de 2691 Lombard are, 2692 properly speaking, outside the scope of this menagerie, being 2693 more 2694 or less human. Notwithstanding, severalish beasts both 2695 animated 2696 and wooden played a significant part in this encounter; most 2697 notably: 2698
    2699
  • The Projectile Cow, see
    • 2700
  • The Trojan Rabbit, see
    • 2701
2703 2705 Figure 46: Inline Formatting In AsciiRFC (RFC XML v3) 2707 12.2. Formatting BCP 14 Keywords 2709 RFC XML v3 also supports tagging of BCP14 keywords [RFC2119] 2710 [RFC8174]; this is done in AsciiRFC either by tagging them with a 2711 custom formatting span (e.g. "MUST NOT"), or by converting any 2712 boldface all-caps words recognised as BCP14 words (unless the ":no- 2713 rfc-bold-bcp14: false" document attribute is set). 2715 Any spans of BCP14 text delimited by inline formatting delimiters 2716 need to be contained within a single line of text; in Asciidoctor 2717 syntax, formatting spans are broken up across line breaks. 2719 This usage is demonstrated in Figure 47 with the rendered output in 2720 Figure 48. 2722 2724 The instructions in the _Book of Armaments_ on the proper deployment 2725 of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as 2726 follows, although this summary *SHALL NOT* be used as a substitute 2727 for a reading from the Book of Armaments: 2729 2731 Figure 47: BCP14 Keywords In AsciiRFC 2733 2735 The instructions in the Book of Armaments on the proper 2736 deployment 2737 of the Holy Hand Grenade of Antioch MAY be summarized as 2738 follows, although this summary SHALL NOT be used as a 2739 substitute 2740 for a reading from the Book of Armaments: 2742 2744 Figure 48: BCP14 Keywords In AsciiRFC (RFC XML v3) 2746 12.3. Escaping AsciiRFC Syntax 2748 Formatting delimiters like "*" can be escaped with backslash ("\*"); 2749 double formatting delimiters, like "**" and "__", need to be escaped 2750 with double backslash ("\\**"). 2752 Escaping delimiters is not always reliable, and for double delimiters 2753 it is preferable to use HTML entities ("**"), or attribute 2754 references (references to the value of attributes set in the document 2755 header) as shown in Figure 49. 2757 2758 :dblast: ** 2760 `{dblast}` 2761 2763 Figure 49: Escaping AsciiRFC Syntax Using Attributes 2765 In extreme circumstances (such as quoting AsciiDoc syntax), you may 2766 need to resort to altering the substitutions behaviour within a given 2767 block of of AsciiDoc; see the "Applying Substitutions" section of 2768 [Asciidoctor-Manual]. 2770 13. Links 2772 Common URL formats are recognised automatically as hyperlinks in 2773 AsciiRFC, which inherits this excellent feature from AsciiDoc, and 2774 are rendered as such. 2776 Any hyperlinked text is appended after the hyperlink in square 2777 brackets. 2779 An example is given in Figure 50 with its rendered version in 2780 Figure 51. 2782 2784 <> of the fearsome beast 2785 has been sourced from 2786 http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], 2787 <> 2788 by C code that was used in this accurate depiction of the 2789 Killer Rabbit: 2791 2793 Figure 50: An AsciiRFC Link 2795 2797 The following depiction of the 2798 fearsome beast 2799 has been sourced from 2800 Rabbit-SCII, 2802 accompanied 2803 by C code that was used in this accurate depiction of the 2804 Killer Rabbit: 2806 2808 Figure 51: An AsciiRFC Link (RFC XML v3) 2810 To prevent hyperlinking of a URL, prefix it with a backslash, as 2811 shown in Figure 52 with its rendered version in Figure 53. 2813 2815 The screaming move into the twenty-*first* century is accompanied by 2816 a move back to the late twentieth century, with ASCII stylings more 2817 wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be 2818 accessible in 1996.) 2820 2822 Figure 52: A Literal AsciiRFC Link 2824 2826 The screaming move into the twenty-first century is 2827 accompanied by 2828 a move back to the late twentieth century, with ASCII stylings more 2829 wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be 2830 accessible in 1996.) 2832 2834 Figure 53: A Literal AsciiRFC Link (RFC XML v3) 2836 14. Cross-References 2838 14.1. Basic Referencing 2840 Anchors for cross-references are notated as "[[...]]" or "[#...]", 2841 and can be inserted on their own line in front of most blocks. 2843 Asciidoctor syntax supports anchors in a much wider range of contexts 2844 than is supported than RFC XML v3 (let alone v2); anchors that are 2845 not supported for that version of RFC XML are simply ignored by the 2846 converter. 2848 Note that anchors in RFC XML are constrained to the format "[A-Za- 2849 z_:][[A-Za-z0-9_:.-]*" (i.e. "xsd:ID"). 2851 Cross-references to anchors are notated as "<<...>>"; cross- 2852 references with custom text as "<>". 2854 An example of using cross-references in AsciiRFC is given in 2855 Figure 54 with its rendered output in Figure 55. 2857 2859 The _Cave of Caerbannog_ has been well-established in the mythology 2860 of Camelot (as recounted by Monty Python) as the lair of the 2861 Legendary Black Beast of Arrrghhh, more commonly known today as the 2862 *Killer Rabbit of Caerbannog* <>. 2863 It is the encounter between the Killer Rabbit of Caerbannog and the 2864 Knights of the Round Table, armed with the Holy Hand Grenade of 2865 Antioch (see the <>), that we 2866 recount here through monospace font and multiple spaces. 2868 [[killer_rabbit_caerbannog]] 2869 === The Killer Rabbit of Caerbannog 2871 2873 Figure 54: Setting And Referring To Cross-References In AsciiRFC 2875 2877 The Cave of Caerbannog has been well-established in the 2878 mythology 2879 of Camelot (as recounted by Monty Python) as the lair of the 2880 Legendary Black Beast of Arrrghhh, more commonly known today as the 2881 Killer Rabbit of Caerbannog . 2883 It is the encounter between the Killer Rabbit of Caerbannog and the 2884 Knights of the Round Table, armed with the Holy Hand Grenade of 2885 Antioch (see the following 2886 section), that we 2887 recount here through monospace font and multiple spaces. 2888
The 2889 Killer Rabbit of Caerbannog 2890 2892 Figure 55: Setting And Referring To Cross-References In AsciiRFC (RFC 2893 XML v3) 2895 14.2. Referencing With Attributes 2897 While Asciidoctor syntax natively does not support attributes on 2898 cross-references, AsciiRFC works around that by embedding formatting 2899 information as templated text within cross-references: 2901 o "format= x: text" populates the "xref@format" attribute 2902 o a section number followed by one of the words "of", "parens", 2903 "bare", "text" is treated as a "relref" reference to an external 2904 document. 2906 An example of referencing with attributes is given in Figure 56 with 2907 its output in Figure 57. 2909 2911 The *Killer Rabbit of Caerbannog*, that most formidable foe of 2912 the Knights and of all that is holy or carrot-like, has been 2913 depicted diversely in lay and in song. We venture to say, 2914 _contra_ the claim made in <>, 2915 that the Killer Rabbit of Caerbannog truly is the most afeared 2916 of all the creatures. Short of sanctified ordnance such as 2917 <>, there are few remedies 2918 known against its awful lapine powers. 2920 2922 Figure 56: Cross-References With Attributes In AsciiRFC 2924 2926 The Killer Rabbit of Caerbannog, that most 2927 formidable foe of 2928 the Knights and of all that is holy or carrot-like, has been 2929 depicted diversely in lay and in song. We venture to say, 2930 contra the claim made in Ze Vompyre, 2932 that the Killer Rabbit of Caerbannog truly is the most afeared 2933 of all the creatures. Short of sanctified ordnance such as 2934 , there are few 2935 remedies 2936 known against its awful lapine powers. 2938 2940 Figure 57: Cross-References With Attributes In AsciiRFC (RFC XML v3) 2942 14.3. Indexing 2944 Inline index entries are notated as "((...))". Index entries which 2945 do not appear in the text are notated as "(((...)))"; such entries 2946 may include a separate sub-entry, separated from the main entry by 2947 comma. 2949 2951 The solution to the impasse at the ((Cave of Caerbannog)) was 2952 provided by the successful deployment of the 2953 *Holy Hand Grenade of Antioch* (see <>) 2954 (((Holy Hand Grenade of Antioch))). 2955 Any similarity between the Holy Hand Grenade of Antioch and the 2956 mythical _Holy Spear of Antioch_ is purely intentional; 2957 (((relics, Christian))) any similarity between the Holy Hand Grenade 2958 of Antioch and the _Sovereign's Orb of the United Kingdom_ 2959 (see <>) is putatively fortuitous. 2960 (((relics, monarchic))) 2962 2964 Figure 58: AsciiRFC Index Entries 2966 2968 The solution to the impasse at the Cave of Caerbannog was 2970 provided by the successful deployment of the 2971 Holy Hand Grenade of Antioch (see ) 2973 . 2974 Any similarity between the Holy Hand Grenade of Antioch and the 2975 mythical Holy Spear of Antioch is purely intentional; 2976 any similarity between the 2977 Holy Hand Grenade 2978 of Antioch and the Sovereign's Orb of the United Kingdom 2979 (see ) is putatively fortuitous. 2980 2982 2984 Figure 59: AsciiRFC Index Entries (RFC XML v3) 2986 15. Inclusions 2988 AsciiRFC inherits the Asciidoctor syntax "include" directive 2989 [Asciidoctor-Manual] to include external files in a master AsciiRFC 2990 document. 2992 This directive is capable of sophisticated document merging, 2993 including adjusting the heading levels of the included text, 2994 selecting text within specified tags or line numbers to be included, 2995 and adjusting the indentation of code snippets in merged text. 2997 Its basic syntax is given in Figure 60. 2999 3000 include::path[ 3001 leveloffset=_offset_, 3002 lines=_ranges_, 3003 tag(s)=_name(s)_, 3004 indent=_depth_ 3005 ] 3006 3008 Figure 60: Inclusions In AsciiRFC 3010 If a file is included in an AsciiRFC document, ensure it ends with a 3011 blank line. An inclusion that results in its final block not being 3012 delimited with a blank line from what follows can lead to 3013 unpredictable results. 3015 16. Encoding and Entities 3017 XML accepts the full range of characters in the world's languages 3018 through UTF-8 character encoding, and one of the motivations for the 3019 move by the IETF from plain text to RFC XML has been to allow non- 3020 ASCII characters to be included in RFCs. 3022 However, current RFC XML v2 tools still do not support UTF-8, and 3023 alternative tooling support for UTF-8 also remains patchy. Out of an 3024 abundance of caution, the RFC XML converter uses US-ASCII for its 3025 character encoding, and renders any non-ASCII characters as HTML 3026 entities. 3028 AsciiRFC accepts HTML entities as input, even though they are not 3029 part of the W3C XML specification. HTML entities such as " " 3030 feature in examples of RFC XML provided by the IETF. In order to 3031 prevent dependence of the XML output from extraneous entity 3032 definitions, any such entities are rendered in the XML as decimal 3033 character entities. 3035 An example of how AsciiRFC renders non-ASCII UTF-8 characters are 3036 given in Figure 61 with the output in Figure 62. 3038 3040 ____ 3041 .כאן אולי 3042 ימצאו 3043 המילים 3044 האחרונות של 3045 יוסף 3046 .מארמתיה 3047 .מי אשר יהיה 3048 אמיץ ובעל 3049 נפש טהורה 3050 יוכל למצוא 3051 את הגביע 3052 הקדוש בטירת 3053 .אאאאאאאה 3055 "Here may be found the last words of Joseph of Arimathea. 3056 He who is valiant and pure of spirit may find the Holy Grail 3057 in the castle of — Aaaargh." 3058 ____ 3060 3062 Figure 61: UTF-8 Characters In AsciiRFC 3064 3066
כאן אולי 3067 ימצאו 3068 המילים 3069 האחרונות של 3070 יוסף 3071 .מארמתיה 3072 מי אשר יהיה 3073 אמיץ ובעל 3074 נפש טהורה 3075 יוכל למצוא 3076 את הגביע 3077 הקדוש בטירת 3078 .אאאאאאאה 3079 "Here may be found the last words of Joseph of Arimathea. 3080 He who is valiant and pure of spirit may find the Holy Grail 3081 in the castle of — Aaaargh."
3083 3085 Figure 62: UTF-8 Characters In AsciiRFC Rendered As RFC XML v3 3087 Note that because initial period is a formatting character in 3088 Asciidoctor, we have had to use "." to escape the period at the 3089 end of Hebrew sentences (which appears at the start of the line, 3090 Hebrew being written Right-to-Left). Asciidoctor is not natively 3091 equipped to deal with Right-to-Left languages in its formatting 3092 parsing. 3094 17. Bibliography 3096 The simple encoding of bibliography syntax provided by AsciiDoc (and 3097 Asciidoctor syntax) is inadequate for the complexity of bibliographic 3098 markup required by RFC XML. 3100 RFC documents overwhelmingly cite other RFC documents, and canonical 3101 RFC XML bibliographic entries are available at [IETF-BibXML]; so it 3102 would be inefficient to encode those entries natively in AsciiRFC, 3103 only to have them converted back to RFC XML. 3105 The converter provides two means of incorporating bibliographies into 3106 RFC documents authored in AsciiRFC: 3108 o using raw RFC XML; and 3110 o assembling bibliographies in preprocessing. 3112 In either case, the RFC XML needs to be well-formed; missing closing 3113 tags can lead to erratic behaviour in the converter. 3115 17.1. Using Raw RFC XML 3117 In the first method, bibliographic citations are handled like all 3118 other AsciiRFC cross-references. The bibliographic entries for 3119 normative and informative references are given in the AsciiRFC as 3120 passthrough blocks, which contain the raw RFC XML for all references; 3121 document conversion leaves the raw RFC XML in place. 3123 This approach requires authors to maintain the normative and 3124 informative bibliographies within the document, to update them as 3125 citations are added and removed, and to sort them manually. However, 3126 if the citation is stored on the IETF's RFC XML citation libraries 3127 (see ), AsciiRFC will automatically 3128 replace it with an external reference to that citation. So the body 3129 of the citation XML can be left out. 3131 For example, the AsciiRFC in Figure 63 will generate the 3132 corresponding RFC XML v3 output in Figure 64. 3134 3136 [bibliography] 3137 == Normative References 3138 ++++ 3139 3141 3142 Key words for use in RFCs to Indicate 3143 Requirement Levels 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 ++++ 3155 [bibliography] 3156 == Informative References 3157 ++++ 3159 3160 3161 Monty Python and the Holy Grail 3162 3163 3164 3165 3166 3167 3168 3169 3170 3172 3174 3175 DON'T SPEW A Set of Guidelines for Mass Unsolicited 3176 Mailings and Postings (spam*) 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3190 3192 3193 RFC Format Framework 3194 3195 3196 3197 3198 3199 3200 3201 3203 3205 3206 3207 The Arte of ASCII: Or, An True and Accurate Representation of 3208 an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of 3209 Character 3210 3211 3212 3213 3214 3215 3216 3217 3218 3220 3222 3223 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 3224 Words 3225 3226 3227 3228 3229 RFC 2119 specifies common key words that may be used 3230 in protocol specifications. This document aims to reduce 3231 the ambiguity by clarifying that only UPPERCASE usage of the 3232 key words have the defined special meanings. 3233 3234 3235 3236 3237 3239 ++++ 3241 3243 Figure 63: AsciiRFC Inline Bibliography 3245 3246
3247 3248 3249 Normative References 3250 3253 3254 3255 Informative References 3256 3257 3258 Monty Python and the Holy Grail 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3271 3274 3277 3280 3281 3282 3283 3285 Figure 64: AsciiRFC Inline Bibliography Rendered As RFC XML v3 3287 17.2. Preprocessing Using "asciidoctor-bibliography" 3289 The alternative method is to use a preprocessing tool, 3290 [asciidoctor-bibliography], to import citations into the AsciiRFC 3291 document from an external file of references. 3293 The references file consists of RFC XML reference entries, and still 3294 needs to be managed manually; however the bibliographies are 3295 assembled from that file, sorted, and inserted into the normative and 3296 informative references in preprocessing. Citations in the document 3297 itself are given as macros to be interpreted by the preprocessor; 3298 this allows them to be split into normative and informative 3299 references. (The MMark tool likewise splits reference citations into 3300 normative and informative.) 3302 Integration with the "asciidoc-bibliography" gem proceeds as follows: 3304 1. Create an RFC XML references file, consisting of a "" 3305 element with individual "" elements inserted, as would 3306 be done for the informative and normative references normally. 3307 The references file will contain all possible references to be 3308 used in the file; the bibliography gem will select which 3309 references have actually been cited in the document. 3311 A. Rather than hand crafting RFC XML references for RFC 3312 documents, you should download them from an authoritative 3313 source; e.g., "http://xml.resource.org/public/rfc/ 3314 bibxml//reference.RFC.2119.xml". Note that RFC XML 3315 references from this link contains the XML document 3316 declaration, which needs to be removed before being used in 3317 the XML bibliography. 3319 B. Unlike the case for RFC XML documents created manually, the 3320 references file does not recognise XML entities and will not 3321 attempt to download them during processing. Any references 3322 to "http://xml.resource.org/public/rfc/bibxml//" will need to 3323 be downloaded and inserted into the references file. 3325 C. The RFC XML in the references file will need to be 3326 appropriate to the version of RFC XML used in the main 3327 document, as usual. Note that RFC XML v2 references are 3328 forward compatible with v3; v3 contains a couple of 3329 additional elements. 3331 2. Add to the main document header attributes referencing the 3332 references file (":bibliography-database:"), and the bibliography 3333 style (":bibliography-style: rfc-v3"). 3335 3. References to a normative reference are inserted with the macro 3336 "cite:norm[id]" instead of "<>", where "id" is the anchor of 3337 the reference. 3339 4. References to an informative reference are inserted with the 3340 macro "cite:info[id]" instead of "<>", where "id" is the 3341 anchor of the reference. 3343 5. Formatted crossreferences and "relref" crossreferences are 3344 entered by inserting the expected raw XML in the "text" 3345 attribute. Do not use the "{cite}" interpolation of the 3346 citation. For example: 3348 * "<>" = "cite:norm[id, text="words"]" 3351 * "<>" (processed as a formatted 3352 cross-reference) = "cite:norm[id, text="words"]" 3355 * "<>" (processed as relref) = 3356 "cite:norm[id, text=""]" 3359 * "<>" (processed as relref with 3360 a cross-document internal reference) = "cite:norm[id, 3361 text=""]" 3364 6. Normative and Informative References are inserted in the document 3365 through a macro, which occurs where the RFC XML references would 3366 be inserted, as shown in Figure 65. 3368 3369 [bibliography] 3370 == Normative References 3372 ++++ 3373 bibliography::norm[] 3374 ++++ 3376 [bibliography] 3377 == Informative References 3379 ++++ 3380 bibliography::info[] 3381 ++++ 3382 3384 Figure 65: Using asciidoctor-bibliography For Bibliography 3385 Preprocessing 3387 18. RFC XML features not supported in Asciidoctor 3389 The following features of RFC XML v3 [RFC7991] and v2 [RFC7749] are 3390 not supported by the AsciiRFC converter, and would need to be 3391 adjusted manually after RFC XML is generated: 3393 +------------------------+--------------------+---------------------+ 3394 | RFC XML element | RFC XML v3 | RFC XML v2 | 3395 +------------------------+--------------------+---------------------+ 3396 | "front/boilerplate" | Not added by the | Not added by the | 3397 | | converter | converter | 3398 | "iref@primary" | N | N | 3399 | "reference" (and all | As Raw XML | As Raw XML | 3400 | children) | | | 3401 | "table/preamble" | Deprecated | N | 3402 | "table/postamble" | Deprecated | N | 3403 | "artwork@width" | Only on images | Only on images | 3404 | "artwork@height" | Only on images | Only on images | 3405 +------------------------+--------------------+---------------------+ 3407 19. Authoring 3409 To author an AsciiRFC document, you should first familiarise yourself 3410 with the [Asciidoctor-Manual]. 3412 The [asciidoctor-rfc] Ruby gem source code distribution also has 3413 samples of individual RFC XML features in v2 and v3, and examples of 3414 self-standing AsciiRFC documents, along with their RFC XML 3415 renderings. (This includes round-tripped RFC XML documents.) 3417 19.1. Using the "rfc-asciirfc-minimal" template 3419 In addition, you can clone the sample "rfc-asciirfc-minimal" 3420 repository as a template, and populate it for your AsciiRFC document 3421 using the steps shown in Figure 66. 3423 $ git clone https://github.com/riboseinc/rfc-asciirfc-minimal 3425 Figure 66: Cloning The AsciiRFC Document Template 3427 19.2. Installing AsciiRFC Backend Processors 3429 Converting your AsciiRFC to RFC XML is a simple as installing the 3430 Asciidoctor Ruby gem "asciidoctor" (see "Installation" at 3431 [Asciidoctor]) and the "asciidoctor-rfc" gem in Ruby (through 3432 RubyGems), then running the "asciidoctor" executable on the document, 3433 specifying the "asciidoctor-rfc" gem as a library. 3435 The necessary steps are shown in Figure 67. 3437 $ gem install asciidoctor-rfc 3438 $ asciidoctor -b rfc3 -r 'asciidoctor-rfc' foo.adoc # RFC XML v3 output 3439 $ asciidoctor -b rfc2 -r 'asciidoctor-rfc' foo.adoc # RFC XML v2 output 3441 Figure 67: Installing The AsciiRFC Backend Processors 3443 19.3. Iterating AsciiRFC Content 3445 As you author AsciiRFC content, you should iterate by running the 3446 AsciiRFC conversion frequently, to ensure that you are still 3447 generating valid XML through your markup. The converter makes an 3448 effort to ensure that its XML output is valid, and it issues warnings 3449 about likely issues; it also validates its own XML output against the 3450 RFC XML schema (of the corresponding version), and reports errors in 3451 the XML output in the format shown in Figure 68. 3453 V3 RELAXNG Validation: 12:0: ERROR: Invalid attribute 3454 sortRefs for element rfc 3456 Figure 68: Sample Validation Error Message From AsciiRFC 3458 Note that validation against the Relax NG RFC XML schema includes 3459 confirming the referential integrity of all cross-references in the 3460 document. 3462 It may be necessary to intervene in the XML output generated by the 3463 converter, either because the block model of AsciiRFC does not 3464 conform with the intended RFC XML (e.g. lists embedded in 3465 paragraphs), or because RFC XML features are required that are not 3466 supported within AsciiRFC. 3468 20. Security Considerations 3470 o Ensure your AsciiRFC generator comes from a geniune and 3471 trustworthy source. This protects your own machine and also 3472 prevents injection of malicious content in your resulting 3473 document. 3475 o An AsciiRFC generator may cause errors in textual rendering or 3476 link generation that may lead to security issues. 3478 o Creating cross-references (and also bibliographic references) to 3479 external documents may pose risks since the specified external 3480 location may become controlled by a malicious party. 3482 o URIs that start with the "http:" or "https:" prefix are 3483 automatically converted into links in AsciiRFC except when escaped 3484 with a backslash before the prefix. A URI that is intended to be 3485 text but unintentionally rendered as a link may cause users to 3486 visit a malicious website with security consequences. 3488 o AsciiRFC contains syntax that can directly incorporate remote URI 3489 content, such as "include::" which allows remotely-located 3490 AsciiRFC content files. If a remote URI contains malicious 3491 content, this content will be included in the resulting AsciiRFC 3492 document compiled as RFC XML. Remotely-linked URIs should always 3493 be checked for malicious content prior to compiling AsciiRFC into 3494 RFC XML. 3496 21. IANA Considerations 3498 This document does not require any action by IANA. 3500 22. References 3502 22.1. Normative References 3504 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 3505 RFC 7991, DOI 10.17487/RFC7991, December 2016, 3506 . 3508 22.2. Informative References 3510 [AsciiDoc] 3511 Rackham, S., "AsciiDoc: Text based document generation", 3512 November 2013, . 3514 [Asciidoctor] 3515 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast 3516 text processor & publishing toolchain for converting 3517 AsciiDoc to HTML5, DocBook & more.", November 2017, 3518 . 3520 [asciidoctor-bibliography] 3521 Ribose Inc., "Citations and Bibliography the 'asciidoctor- 3522 way'", November 2017, 3523 . 3525 [Asciidoctor-Manual] 3526 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast 3527 text processor & publishing toolchain for converting 3528 AsciiDoc to HTML5, DocBook & more.", November 2017, 3529 . 3531 [asciidoctor-rfc] 3532 Ribose Inc., "asciidoctor-rfc lets you write Internet- 3533 Drafts and RFCs in AsciiDoc, the "asciidoctor-way".", 3534 November 2017, 3535 . 3537 [AsciiMathML] 3538 "AsciiMath is an easy-to-write markup language for 3539 mathematics.", November 2017, . 3541 [datatracker-asciirfc-minimal] 3542 Carberry, J. and T. Grayson, "IETF Datatracker: A Minimal 3543 Internet-Draft In AsciiRFC", March 2018, 3544 . 3547 [datatracker-camelot-holy-grenade] 3548 Pendragon, A., "IETF Datatracker: The Holy Hand Grenade of 3549 Antioch", March 2018, . 3552 [datatracker-divination-cfapi] 3553 Destiny, G. and C. Luck, "IETF Datatracker: An API For 3554 Calendar-Based Fortune Heuristics Services", March 2018, 3555 . 3558 [draftr] Barnes, R., "draftr: an HTML front-end to pandoc2rfc", Nov 3559 2017, . 3561 [git-asciirfc-minimal] 3562 Carberry, J. and T. Grayson, "Git repository: A Minimal 3563 Internet-Draft In AsciiRFC", March 2018, 3564 . 3566 [git-camelot-holy-grenade] 3567 Pendragon, A., "Git repository: The Holy Hand Grenade of 3568 Antioch", March 2018, 3569 . 3571 [git-divination-cfapi] 3572 Destiny, G. and C. Luck, "Git repository: An API For 3573 Calendar-Based Fortune Heuristics Services", March 2018, 3574 . 3576 [I-D.asciirfc-minimal] 3577 Carberry, J. and T. Grayson, "A Minimal Internet-Draft In 3578 AsciiRFC", draft-asciirfc-minimal-02 (work in progress), 3579 April 2018. 3581 [I-D.camelot-holy-grenade] 3582 Pendragon, A., "The Holy Hand Grenade of Antioch", draft- 3583 camelot-holy-grenade-00 (work in progress), March 2018. 3585 [I-D.divination-cfapi] 3586 Destiny, G. and C. Luck, "An API For Calendar-Based 3587 Fortune Heuristics Services", draft-divination-cfapi-00 3588 (work in progress), March 2018. 3590 [IETF-BibXML] 3591 "IETF BibXML Library", November 2017, 3592 . 3594 [kramdown-rfc2629] 3595 Bormann, C., "kramdown-rfc2629: An RFC2629 (XML2RFC) 3596 backend for Thomas Leitner's kramdown markdown parser", 3597 Nov 2017, . 3599 [lyx2rfc] Williams, N., "LyX to I-D/RFC export by way of Lyx export 3600 to XHTML and XSLT conversion to xml2rfc schema", 2014, 3601 . 3603 [MathJax] "MathJax: A JavaScript display engine for mathematics that 3604 works in all browsers.", November 2017, 3605 . 3607 [mmark] Gieben, R., "Using mmark to create I-Ds and RFCs", June 3608 2015, . 3610 [NroffEdit] 3611 Santesson, S., "WYSIWYG Internet-Draft Nroff Editor", May 3612 2011, . 3614 [pandoc2rfc] 3615 Gieben, R., "pandoc2rfc: Use pandoc to create XML suitable 3616 for xml2rfc", 2012, . 3618 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3619 Requirement Levels", BCP 14, RFC 2119, 3620 DOI 10.17487/RFC2119, March 1997, 3621 . 3623 [RFC5385] Touch, J., "Version 2.0 Microsoft Word Template for 3624 Creating Internet Drafts and RFCs", RFC 5385, 3625 DOI 10.17487/RFC5385, February 2010, 3626 . 3628 [RFC7328] Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit 3629 of XML", RFC 7328, DOI 10.17487/RFC7328, August 2014, 3630 . 3632 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 3633 RFC 7749, DOI 10.17487/RFC7749, February 2016, 3634 . 3636 [RFC7763] Leonard, S., "The text/markdown Media Type", RFC 7763, 3637 DOI 10.17487/RFC7763, March 2016, 3638 . 3640 [RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies, 3641 Stability Strategies, and Select Registrations", RFC 7764, 3642 DOI 10.17487/RFC7764, March 2016, 3643 . 3645 [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990, 3646 DOI 10.17487/RFC7990, December 2016, 3647 . 3649 [RFC7996] Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", 3650 RFC 7996, DOI 10.17487/RFC7996, December 2016, 3651 . 3653 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3654 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3655 May 2017, . 3657 [TeX-LaTeX] 3658 "LaTeX is document preparation software that runs on top 3659 of Donald E. Knuth's TeX typesetting system.", November 3660 2017, . 3662 Appendix A. Examples 3664 A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" 3666 This example is available in the following formats: 3668 o AsciiRFC [git-asciirfc-minimal] 3670 o Internet-Draft [I-D.asciirfc-minimal] 3671 o Text, RFC XML, PDF and HTML on the IETF Datatracker 3672 [datatracker-asciirfc-minimal] 3674 A.1.1. In AsciiRFC 3676 3677 = A Minimal Internet-Draft In AsciiRFC 3678 :doctype: internet-draft 3679 :name: draft-asciirfc-minimal-02 3680 :abbrev: AsciiRFC Example 3681 :status: informational 3682 :ipr: trust200902 3683 :submissionType: individual 3684 :area: Internet 3685 :intended-series: full-standard 3686 :revdate: 2018-04-12T00:00:00Z 3687 :fullname: Josiah Stinkney Carberry 3688 :lastname: Carberry 3689 :forename_initials: J. S. 3690 :organization: Brown University 3691 :phone: +1 401 863 1000 3692 :street: Box K, 69 Brown Street 3693 :city: Providence 3694 :code: 02912 3695 :country: United States of America 3696 :uri: https://www.brown.edu 3697 :email: josiah.carberry@ribose.com 3698 :fullname_2: Truman Grayson 3699 :lastname_2: Grayson 3700 :forename_initials_2: T. 3701 :organization_2: Brown University 3702 :phone_2: +1 401 863 1000 3703 :street_2: Box G, 69 Brown Street 3704 :city_2: Providence 3705 :code_2: 02912 3706 :country_2: United States of America 3707 :uri_2: https://www.brown.edu 3708 :email_2: truman.grayson@ribose.com 3710 [abstract] 3712 This document provides a template on how to author (or migrate!) 3713 a new Internet-Draft / RFC in the AsciiRFC format. 3715 This template requires usage of the `asciidoctor-rfc` Ruby gem. 3717 [#introduction] 3718 == Introduction 3719 AsciiRFC <> is an extremely simple way to 3720 author Internet-Drafts and RFCs without needing to manually 3721 craft RFC XML conforming to <>. 3723 This is a template specifically made for authors to easily 3724 start with creating an Internet-Draft conforming to <> 3725 and submittable to the IETF datatracker. 3727 [#conventions] 3728 == Terms and Definitions 3730 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 3731 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 3732 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this 3733 document are to be interpreted as described in BCP 14 3734 <> <> when, and only when, they appear in 3735 all capitals, as shown here. 3737 This document also refers to the following terms and 3738 definitions: 3740 AsciiRFC:: 3741 an AsciiDoc-derived syntax used for authoring RFCs and 3742 Internet-Drafts, as defined in <>. 3744 [#symbols] 3745 == Symbols And Abbreviations 3747 ADRFC:: 3748 abbreviated form of AsciiRFC 3750 [#main] 3751 == Main content 3753 This is where you place the main content, and the following 3754 serves as a placeholder for your text. 3756 Subsections are used here for demonstration purposes. 3758 === Getting started 3760 The AsciiRFC and RFC toolchains *MUST* be available locally to 3761 build this document template. 3763 ==== AsciiRFC toolchain 3765 You will need to have: 3767 * Ruby: for running the AsciiRFC toolchain 3768 * `asciidoctor-rfc` gem: for converting AsciiRFC into XML RFC 3769 (v2 or v3) 3771 ==== XML RFC toolchain 3773 You will need to have: 3775 * Python: for running `xml2rfc` 3776 * `xml2rfc`: for converting RFC XML (v2 or v3) into TXT 3777 * `idnits`: for submission preflight 3779 === Referencing external content 3781 * This is a published RFC <> 3783 * This is an Internet-Draft <> 3785 * This is an external reference <> 3787 [#code-snippets] 3788 === Code snippets 3790 Code snippets should be wrapped with `` and 3791 `` blocks, as required by the IETF Trust Legal 3792 Provisions (TLP) <> specified in <>. 3794 [#security] 3795 == Security Considerations 3797 Any security considerations should be placed here. 3799 As described in <
> (here's how you refer a local anchor), 3800 local tools have to be installed before the document template 3801 can be built. 3803 Running of these local tools *MAY* produce unintended side 3804 effects that impact security. 3806 [#iana] 3807 == IANA Considerations 3809 This document does not require any action by IANA. 3811 But if it does, such as proposing changes to IANA registries, 3812 please include them here. 3814 // References must be given before appendixes 3816 [bibliography] 3817 == Normative References 3819 //bibliography::norm[] 3820 ++++ 3822 3824 3825 Key words for use in RFCs to Indicate Requirement 3826 Levels 3827 3828 3829 3830 3831 3832 In many standards track documents several words are 3833 used to signify the requirements in the specification. 3834 These words are often capitalized. This document defines 3835 these words as they should be interpreted in IETF 3836 documents. This document specifies an Internet Best 3837 Current Practices for the Internet Community, and 3838 requests discussion and suggestions for improvements. 3839 3840 3841 3842 3843 3844 3845 3847 3849 3850 The "xml2rfc" Version 3 Vocabulary 3851 3852 3853 3854 3855 3856 This document defines the "xml2rfc" 3857 version 3 vocabulary: an XML-based language used for 3858 writing RFCs and Internet-Drafts. It is heavily derived 3859 from the version 2 vocabulary that is also under 3860 discussion. This document obsoletes the v2 grammar 3861 described in RFC 7749. 3862 3863 3864 3865 3866 3868 3870 3871 Ambiguity of Uppercase vs Lowercase in RFC 2119 3872 Key Words 3873 3874 3875 3876 3877 3878 RFC 2119 specifies common key words that may be 3879 used in protocol specifications. This document aims to 3880 reduce the ambiguity by clarifying that only UPPERCASE 3881 usage of the key words have the defined special 3882 meanings. 3883 3884 3885 3886 3887 3888 3889 ++++ 3891 [bibliography] 3892 == Informative References 3894 //bibliography::info[] 3895 ++++ 3897 3899 3900 IETF Trust Legal Provisions (TLP) 3901 3902 IETF 3903 3904 3905 3906 3908 3909 3910 RNP: A C library approach to OpenPGP 3911 3912 Ribose Inc. 3913
3914 3915 Suite 1111, 1 Pedder Street 3916 Central 3917 Hong Kong 3918 Hong Kong 3919 3920 open.source@ribose.com 3921 https://www.ribose.com 3922
3923 3924 3925 3926 3928 3929 3930 3931 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 This document describes an AsciiDoc syntax 3948 extension called AsciiRFC, designed for authoring IETF 3949 Internet-Drafts and RFCs. AsciiDoc is a human readable document 3950 markup language which affords more granular control over markup 3951 than comparable schemes such as Markdown. The AsciiRFC syntax 3952 is designed to allow the author to entirely focus on text, 3953 providing the full power of the resulting RFC XML through the 3954 AsciiDoc language, while abstracting away the need to manually 3955 edit XML, including references. This document itself was 3956 written and generated into RFC XML v2 (RFC7749) and RFC XML v3 3957 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC 3958 generator. 3959 3960 3961 3962 3964 3966 3968 3969 Rights Contributors Provide to the IETF Trust 3970 3972 3973 3974 3976 3977 3978 3979 The IETF policies about rights in Contributions 3980 to the IETF are designed to ensure that such Contributions 3981 can be made available to the IETF and Internet communities 3982 while permitting the authors to retain as many rights as 3983 possible. This memo details the IETF policies on rights in 3984 Contributions to the IETF. It also describes the 3985 objectives that the policies are designed to meet. This 3986 memo obsoletes RFCs 3978 and 4748 and, with BCP 79 and 3987 RFC 5377, replaces Section 10 of RFC 2026. This document 3988 specifies an Internet Best Current Practices for the 3989 Internet Community, and requests discussion and 3990 suggestions for improvements. 3991 3992 3993 3994 3995 3997 3999 4000 The OCB Authenticated-Encryption Algorithm 4001 4002 4003 4004 4005 4006 4007 4008 This document specifies OCB, a shared-key 4009 blockcipher-based encryption scheme that provides 4010 confidentiality and authenticity for plaintexts and 4011 authenticity for associated data. This document is a product 4012 of the Crypto Forum Research Group (CFRG). 4013 4014 4015 4016 4017 ++++ 4019 [appendix] 4020 [#appendix-a] 4021 == Examples 4023 === Example 1 4025 Here's an example of a properly wrapped code snippet in 4026 accordance with rules specified in <>. 4028 [source,json] 4029 ---- 4030 4031 { 4032 "code": { 4033 "encoding": "ascii", 4034 "type": "rfc", 4035 "authors": [ "Josiah Carberry", "Truman Grayson" ] 4036 } 4037 } 4038 4039 ---- 4041 [#acknowledgements] 4042 == Acknowledgements 4044 The authors would like to thank their families. 4046 4048 A.1.2. Rendered as RFC XML v3 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4063 4064 A Minimal Internet-Draft In 4065 AsciiRFC 4066 4068 4070 4072 Brown University 4073
4074 4075 Box K, 69 Brown Street 4076 Providence 4077 02912 4078 United States of America 4079 4080 +1 401 863 1000 4081 josiah.carberry@ribose.com 4082 https://www.brown.edu 4083
4084 4085 4086 Brown University 4087
4088 4089 Box G, 69 Brown Street 4090 Providence 4091 02912 4092 United States of America 4093 4094 +1 401 863 1000 4095 truman.grayson@ribose.com 4096 https://www.brown.edu 4097
4098 4099 4100 Internet 4101 This document provides a template on how to author (or 4102 migrate!) 4103 a new Internet-Draft / RFC in the AsciiRFC format. 4104 This template requires usage of the asciidoctor-rfc Ruby 4105 gem. 4106 4107
IntroductionAsciiRFC is an extremely simple way to 4110 author Internet-Drafts and RFCs without needing to manually 4111 craft RFC XML conforming to . 4112 This is a template specifically made for authors to easily 4113 start with creating an Internet-Draft conforming to 4115 and submittable to the IETF datatracker.
4116
Terms and 4117 DefinitionsThe key words "MUST", "MUST 4118 NOT", "REQUIRED", "SHALL", 4119 "SHALL NOT", "SHOULD", "SHOULD 4120 NOT", "RECOMMENDED", 4121 "NOT RECOMMENDED", "MAY", and 4122 "OPTIONAL" in this 4123 document are to be interpreted as described in BCP 14 4124 when, and only when, 4125 they appear in 4126 all capitals, as shown here. 4127 This document also refers to the following terms and 4128 definitions: 4129
4130
AsciiRFC
4131
an AsciiDoc-derived syntax used for authoring RFCs and 4132 Internet-Drafts, as defined in .
4134
4135
4136 Symbols And Abbreviations 4137
4138
ADRFC
4139
abbreviated form of AsciiRFC
4140
4141
4142
Main 4143 contentThis is where you place the main content, and the 4144 following 4145 serves as a placeholder for your text. 4146 Subsections are used here for demonstration purposes. 4147
Getting 4148 startedThe AsciiRFC and RFC toolchains MUST be 4149 available locally to 4150 build this document template. 4151
AsciiRFC 4152 toolchainYou will need to have: 4153
    4154
  • Ruby: for running the AsciiRFC toolchain
    • 4155
  • asciidoctor-rfc gem: for converting AsciiRFC into XML RFC 4156 (v2 or v3)
    • 4157
4158
XML RFC 4159 toolchainYou will need to have: 4160
    4161
  • Python: for running xml2rfc
    • 4162
  • xml2rfc: for converting RFC XML (v2 or v3) into TXT
    • 4163
  • idnits: for submission preflight
    • 4164
4165
4166 Referencing external content 4167
    4168
  • This is a published RFC
    • 4169
  • This is an Internet-Draft
    • 4171
  • This is an external reference
    • 4172
4173
4174
4175 Code snippets 4176 Code snippets should be wrapped with <CODE BEGINS> 4177 and 4178 <CODE ENDS> blocks, as required by the IETF Trust Legal 4179 Provisions (TLP) specified in . 4181
4182
Security 4183 ConsiderationsAny security considerations should be placed 4184 here. 4185 As described in (here’s how you refer a 4186 local anchor), 4187 local tools have to be installed before the document template 4188 can be built. 4189 Running of these local tools MAY produce unintended 4190 side 4191 effects that impact security.
4192
IANA 4193 ConsiderationsThis document does not require any action by 4194 IANA. 4195 But if it does, such as proposing changes to IANA registries, 4196 please include them here.
4197 4198 4199 Normative References 4200 4203 4206 4209 4210 4211 Informative References 4212 4214 4215 IETF Trust Legal Provisions (TLP) 4216 4217 IETF 4218 4219 4220 4221 4222 4223 4224 RNP: A C library approach to OpenPGP 4225 4226 Ribose Inc. 4227
4228 4229 Suite 1111, 1 Pedder Street 4230 Central 4231 Hong Kong 4232 Hong Kong 4233 4234 open.source@ribose.com 4235 https://www.ribose.com 4236
4237 4238 4239 4240 4241 4244 4247 4250 4251
4252 Examples 4253
Example 4254 1Here’s an example of a properly wrapped code snippet in 4255 accordance with rules specified in . 4256
4257 4259 { 4260 "code": { 4261 "encoding": "ascii", 4262 "type": "rfc", 4263 "authors": [ "Josiah Carberry", "Truman Grayson" ] 4264 } 4265 } 4266 4267 ]]> 4268
4269
4270
4271 Acknowledgements 4272 The authors would like to thank their families. 4273
4274 4275 4276 4278 A.2. Example 2: "The Holy Hand Grenade of Antioch" 4280 This example is available in the following formats: 4282 o AsciiRFC [git-camelot-holy-grenade] 4284 o Internet-Draft [I-D.camelot-holy-grenade] 4286 o Text, RFC XML, PDF and HTML on the IETF Datatracker 4287 [datatracker-camelot-holy-grenade] 4289 A.2.1. In AsciiRFC 4291 4292 = The Holy Hand Grenade of Antioch 4293 Arthur son of Uther Pendragon 4294 :doctype: internet-draft 4295 :abbrev: Hand Grenade of Antioch 4296 :updates: 8140 4297 :submission-type: independent 4298 :name: draft-camelot-holy-grenade-00 4299 :status: informational 4300 :consensus: false 4301 :area: General, Operations and Management 4302 :keyword: rabbits, grenades, antioch, camelot 4303 :ipr: trust200902 4304 :toc-include: true 4305 :sort-refs: true 4306 :revdate: 2018-04-01 4307 :fullname: Arthur son of Uther Pendragon 4308 :forename_initials: A. 4309 :lastname: Pendragon 4310 :email: arthur.pendragon@ribose.com 4311 :organization: Camelot 4312 :uri: http://camelot.gov.example 4313 :street: Palace\ Camel Lot 1 4314 :city: Camelot 4315 :country: England 4316 :comments: yes 4317 :notedraftinprogress: yes 4318 :smart-quotes: false 4320 [.comment] 4321 tag::preamble1[] 4322 // tag::preamble[] 4324 [abstract] 4325 The menagerie of beasts and artefacts depicted in RFC8140 4326 may be usefully supplemented by other renowned figures of 4327 Internet and more general lore. This document extends the 4328 menagerie to the seminal fable of the 4329 "Holy Hand Grenade of Antioch", as depicted in the 4330 Monty Python film "Monty Python and the Holy Grail", 4331 as well as "Spamalot", the musical inspired by the movie. 4333 [NOTE,remove-in-rfc=false] 4334 .Spamalot 4335 The relevance of the musical "Spamalot" to Internet lore should be 4336 obvious to the reader; but in case of doubt, see also 4337 Section 1 ("What is Spam*?") of RFC2635. 4339 // end::preamble[] 4340 [.comment] 4341 end::preamble1[] 4343 [.comment] 4344 tag::sectnums1[] 4345 // tag::sectnums[] 4347 [toc=exclude] 4348 :sectnums!: 4349 == Terminology 4351 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 4352 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 4353 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 4354 are to be interpreted as described in BCP 14 <> <> 4355 when, and only when, they appear in all capitals, as shown here. 4357 :sectnums: 4358 == Introduction 4360 <> refers to the intended move of RFC formatting to 4361 XML2RFC v3 <>, in the following terms: 4363 // end::sectnums[] 4364 [.comment] 4365 end::sectnums1[] 4367 [.comment] 4368 tag::quote1[] 4369 // tag::quote[] 4371 [quote,attribution="A. Farrel"] 4372 ____ 4373 Although the RFC Editor has recently dragged the IETF kicking and 4374 screaming into the twentieth century [RFC7990] [RFC7996], there is a 4375 yearning among all right-thinking Internet architects to "keep it 4376 simple" and to return to the olden days when pigs could be given 4377 thrust without anyone taking undue offence. 4378 ____ 4380 // end::quote[] 4381 [.comment] 4382 end::quote1[] 4384 While no pigs, flying or otherwise, are involved in the transition 4385 to RFC XML v3, it is opportune to enhance the <> 4386 legendarium in the service of RFC XML v3, by illustrating its 4387 functionality through references to the mythology of Camelot, and 4388 particularly the incidents at the Cave of Caerbannog. 4390 [.comment] 4391 tag::escaped_hyperlink1[] 4392 // tag::escaped_hyperlink[] 4394 The screaming move into the twenty-*first* century is accompanied by 4395 a move back to the late twentieth century, with ASCII stylings more 4396 wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be 4397 accessible in 1996.) 4399 // end::escaped_hyperlink[] 4400 [.comment] 4401 end::escaped_hyperlink1[] 4403 There are two references to rabbits in 4404 _Monty Python and the Holy Grail_ which are expounded on herewith: 4406 [.comment] 4407 tag::listcontinuation1[] 4408 // tag::listcontinuation[] 4410 Trojan Rabbit:: 4411 In their siege of the French-occupied castle which may already 4412 contain an instance of the Grail, Sir Bedevere the Wise proposes to 4413 use a Trojan Rabbit to infiltrate the castle, with a raiding party 4414 to take the French "not only by surprise, but totally unarmed." 4415 + 4416 The proposal, unsurprisingly, proved abortive. The more so as the 4417 raiding party forgot to hide within the Trojan Rabbit, before the 4418 French soldiers took the Trojan Rabbit inside the castle. 4420 Killer Rabbit of Caerbannog:: 4421 Guarding the entrance to the Cave of Caerbannog; see <>. 4423 // end::listcontinuation[] 4424 [.comment] 4425 end::listcontinuation1[] 4427 == The French-occupied castle 4429 [.comment] 4430 tag::inline_formatting1[] 4431 // tag::inline_formatting[] 4432 The participants of that renowned exercise in cross-cultural 4433 communication, to wit the exchange between the 4434 _Knights of the Round Table_ 4435 and the taunting French soldiers serving under *Guy de Lombard* are, 4436 properly speaking, outside the scope of this `menagerie`, being more 4437 or less human. Notwithstanding, several^ish^ beasts both animate~d~ 4438 and wooden played a significant part in this encounter; most 4439 notably: 4441 * The Projectile Cow, see <> 4442 * The Trojan Rabbit, see <> 4444 // end::inline_formatting[] 4445 [.comment] 4446 end::inline_formatting1[] 4448 [[projectile-cow]] 4449 .The Projectile Cow with an accompanying cannon 4450 ==== 4451 [alt=The Projectile Cow with an accompanying cannon in ASCII] 4452 .... 4453 .-.-.-.-.-.-.-.-.-.-.-.--.-.-.-.-.-.-.--.-.-.-.-.-.-.-.--.-. 4454 _-_---__--__--___-___-__-____---___-________---____-____-__- 4455 ._.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-…-.-.--..-.-.-.-.-.-..--.- 4456 ,..,.,.,.,.,..,.,,..,.,.,.,.,.,, ^^ .,,.,., ^^ .,.,.,.= 4457 _>-.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-. 4458 .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., 4459 .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # .,.,.,. 4460 .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. 4461 .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ‘ ‘! .,.,..,.,.- 4462 .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_] . ., . . , 4463 .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / -.-<>.,.,..-.-, 4464 .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. 4465 .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- 4466 .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. 4467 .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- 4468 .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- 4469 -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- 4470 ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, 4471 ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- 4472 ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. 4473 .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., 4474 .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,. 4475 ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,. 4476 ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. 4477 .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. 4478 -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> 4479 _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,., 4480 .._...{WITHHONEY}-.-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_> 4481 GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASSPC 4482 SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS 4483 CLAY_ROCKS_REBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY>< 4484 CLAY_CLAY_SKLETONS_MORESOIL_CLAY_CLAY_CLAY_CLAY_CLAY_VR 4485 .... 4486 ==== 4488 [[trojan-rabbit]] 4489 .The Trojan Rabbit with an automatic sliding door 4490 ==== 4491 [alt=The Trojan Rabbit with an automatic sliding door, in ASCII] 4492 .... 4493 ___ ____ 4494 //_ \//\__\ 4495 || || | 4496 -__||_||__| 4497 // \--_ 4498 // ____ --___ 4499 // // \ \-_ 4500 // \\ @/ o || 4501 // ---- _____|| 4502 // // 4503 //\_//__ // 4504 //-- --- \____ // 4505 // --- \______ // 4506 // , . ----- \_//_ 4507 // ,. --- \____ 4508 // .,v --- \___ 4509 // __ -- \_ 4510 || , _______________ //|| |-_ 4511 || | |''''''''''| // || | | 4512 || ' | | | || | | 4513 || | | | || | | 4514 || " | | 0 | ___||___ | | 4515 || | | | -------- | | 4516 ||___ | | | ______ | |- 4517 // \ | | | // \| _| \ 4518 // \ ____|---|__________|______// \/ | 4519 || X | / || X | / 4520 \\ /\\____/ \\ /___/ 4521 \\_____/ ----- \\_____/--- 4522 ----- ----- 4523 .... 4524 ==== 4526 [.comment] 4527 tag::aside1[] 4528 // tag::aside[] 4530 **** 4531 While the exchange at the French-occupied castle is one of 4532 the more memorable scenes of _Monty Python and the Holy Grail_, 4533 the Trojan Rabbit has not reached the same level of cultural 4534 resonance as its more murderous counterpart. Reasons for this 4535 may include: 4537 * Less overall screen-time dedicated to the Trojan Rabbit. 4539 * The Trojan Rabbit as projectile has already been anticipated 4540 by the Cow as projectile. 4541 **** 4543 // end::aside[] 4545 [.comment] 4546 end::aside1[] 4548 [.comment] 4549 tag::note1[] 4550 // tag::note[] 4552 [NOTE,display=true,source=Author] 4553 ==== 4554 Image courtesy of 4555 https://camelot.gov.example/creatures-in-ascii/ 4556 ==== 4558 // end::note[] 4559 [.comment] 4560 end::note1[] 4562 [.comment] 4563 tag::comment1[] 4564 // tag::comment[] 4566 The exchange of projectile animals was the beginning of a 4567 long-running fruitful relationship between the British and the 4568 French peoples, 4569 [comment]#TODO: Will need to verify that claim.# which 4570 arguably predates the traditional English enmity with the 4571 French. [comment]#Strictly speaking, the Knights are Welsh.# 4573 [.comment] 4574 -- 4575 This document, as it turns out, has a profusion of XML comments. 4577 As expected, they are ignored in any rendering of the document. 4578 -- 4580 // end::comment[] 4581 [.comment] 4582 end::comment1[] 4584 [[caerbannog]] 4585 == The Mythos of Caerbannog 4587 [.comment] 4588 tag::xref1[] 4589 // tag::xref[] 4591 The _Cave of Caerbannog_ has been well-established in the mythology 4592 of Camelot (as recounted by Monty Python) as the lair of the 4593 Legendary Black Beast of Arrrghhh, more commonly known today as the 4594 *Killer Rabbit of Caerbannog* <>. 4595 It is the encounter between the Killer Rabbit of Caerbannog and the 4596 Knights of the Round Table, armed with the Holy Hand Grenade of 4597 Antioch (see the <>), that we 4598 recount here through monospace font and multiple spaces. 4600 [[killer_rabbit_caerbannog]] 4601 === The Killer Rabbit of Caerbannog 4603 // end::xref[] 4604 [.comment] 4605 end::xref1[] 4607 [.comment] 4608 tag::relref1[] 4609 // tag::relref[] 4611 The *Killer Rabbit of Caerbannog*, that most formidable foe of 4612 the Knights and of all that is holy or carrot-like, has been 4613 depicted diversely in lay and in song. We venture to say, 4614 _contra_ the claim made in <>, 4615 that the Killer Rabbit of Caerbannog truly is the most afeared 4616 of all the creatures. Short of sanctified ordnance such as 4617 <>, there are few remedies 4618 known against its awful lapine powers. 4620 // end::relref[] 4621 [.comment] 4622 end::relref1[] 4624 [.comment] 4625 tag::hyperlink1[] 4626 // tag::hyperlink[] 4628 <> of the fearsome beast 4629 has been sourced from 4630 http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], 4631 <> 4632 by C code that was used in this accurate depiction of the 4633 Killer Rabbit: 4635 // end::hyperlink[] 4636 [.comment] 4637 end::hyperlink1[] 4639 [.comment] 4640 tag::figure1[] 4641 // tag::figure1a[] 4643 [[killer-bunny]] 4644 .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 4645 ==== 4646 [alt=The Killer Bunny, in ASCII] 4647 .... 4648 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4649 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4650 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 4651 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 4652 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 4653 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 4654 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 4655 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 4656 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 4657 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 4658 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 4659 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 4660 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 4661 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 4662 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 4663 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 4664 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 4665 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 4666 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 4667 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 4668 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 4669 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 4670 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 4671 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 4672 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 4673 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 4674 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 4675 MW \\/\||v v|| -\\-------___ . ., \ | 4676 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 4677 ) /--------^-^ ,. \|// 4678 # \(/ .\\|x// " ' ' 4679 . , \\||// \||\\\// \\ 4680 .... 4681 ==== 4683 [[killer-source]] 4684 .C Code To Lure Killer Rabbit Back To Cave 4685 ==== 4686 [source,c] 4687 ---- 4688 4689 /* Locate the Killer Rabbit */ 4690 int type; 4691 unsigned char *killerRabbit = 4692 LocateCreature(&caerbannog, "killer rabbit"); 4693 if( killerRabbit == 0 ){ 4694 puts("The Killer Rabbit of Caerbannog is out of town."); 4695 return LOST_CREATURE; 4696 } 4698 /* Load Cave */ 4699 unsigned char *cave = LoadPlace(&caerbannog, 4700 "The Cave Of Caerbannog"); 4701 if( cave == 0 ){ 4702 puts("The Cave of Caerbannog must have moved."); 4703 return LOST_PLACE; 4704 } 4706 /* Lure the Killer Rabbit back into the Cave */ 4707 unsigned char *carrot = allocateObjectInPlace( 4708 carrot("fresh"), cave); 4709 if( carrot == 0 ){ 4710 puts("No carrot, no rabbit."); 4711 return LOST_LURE; 4712 } 4714 /* Finally, notify the Killer Rabbit to act */ 4715 return notifyCreature(killerRabbit, &carrot); 4716 4717 ---- 4718 ==== 4720 // end::figure1a[] 4721 [.comment] 4722 end::figure1[] 4724 On the beast's encounter with the Knights of the Round Table, 4725 the following personnel engaged with it in combat: 4727 [.comment] 4728 tag::ul1[] 4729 // tag::ul[] 4731 * Killed 4732 ** Sir Bors 4733 ** Sir Gawain 4734 ** Sir Ector 4735 * Soiled Himself 4736 ** Sir Robin 4737 * Panicked 4738 ** King Arthur 4739 * Employed Ordnance 4740 ** The Lector 4741 ** Brother Maynard 4742 * Scoffed 4743 ** Tim the Enchanter 4745 // end::ul[] 4746 [.comment] 4747 end::ul1[] 4749 [[holy_hand_grenade]] 4750 === Holy Hand Grenade of Antioch 4752 [.comment] 4753 tag::figure2[] 4755 // tag::figure2a[] 4757 [[hand-grenade-figure]] 4758 .The Holy Hand Grenade of Antioch (don't pull the pin) 4759 ==== 4760 [alt=Holy Hand Grenade of Antioch, in ASCII] 4761 .... 4762 ______ 4763 \\/ \/ 4764 __\\ /__ 4765 || //\ | 4766 ||__\\/ __| 4767 || | ,---, 4768 || |====`\ | 4769 || | '---' 4770 ,--'*`--, 4771 _||#|***|#| 4772 _,/.-'#|* *|#`-._ 4773 ,,-'#####| |#####`-. 4774 ,,'########| |########`, 4775 //##########| o |##########\ 4776 ||###########| |###########| 4777 ||############| o |############| 4778 ||------------' '------------| 4779 ||o o o o o o o o o o| 4780 |-----------------------------| 4781 ||###########################| 4782 \\#########################/ 4783 `..#####################,' 4784 ``..###############_,' 4785 ``--.._____..--' 4786 `''-----''` 4787 .... 4788 ==== 4790 // end::figure2a[] 4792 [.comment] 4793 end::figure2[] 4795 [[sovereign-orb]] 4796 .The Sovereign's Orb made invisible 4797 ==== 4798 .Outlines of the Sovereign's Orb 4799 [link=https://camelot.gov.example/sovereigns_orb.jpg,align=right] 4800 image::https://camelot.gov.example/sovereigns_orb.jpg[Orb,124,135] 4801 ==== 4803 [.comment] 4804 tag::index1[] 4805 // tag::index[] 4807 The solution to the impasse at the ((Cave of Caerbannog)) was 4808 provided by the successful deployment of the 4809 *Holy Hand Grenade of Antioch* (see <>) 4810 (((Holy Hand Grenade of Antioch))). 4811 Any similarity between the Holy Hand Grenade of Antioch and the 4812 mythical _Holy Spear of Antioch_ is purely intentional; 4813 (((relics, Christian))) any similarity between the Holy Hand Grenade 4814 of Antioch and the _Sovereign's Orb of the United Kingdom_ 4815 (see <>) is putatively fortuitous. 4816 (((relics, monarchic))) 4818 // end::index[] 4819 [.comment] 4820 end::index1[] 4822 [.comment] 4823 tag::dl1[] 4824 // tag::dl[] 4826 Holy Hand Grenade of Antioch:: 4827 Ordnance deployed by Brother Maynard under the incantation of a 4828 lector, in order to dispense with the Foes of the Virtuous. 4829 See <>. 4831 Holy Spear of Antioch:: 4832 A supposed relic of the crucifixion of Jesus Christ, this is one 4833 of at least four claimed instances of the lance that pierced 4834 Christ's side. Its historical significance lies in inspiring 4835 crusaders to continue their siege of Antioch in 1098. 4837 Sovereign's Orb of the United Kingdom:: 4838 Part of the Crown Jewels of the United Kingdom, the Sovereign's 4839 Orb is a hollow gold sphere set with jewels and topped with a 4840 cross. It was made for Charles II in 1661. See <>. 4842 // end::dl[] 4843 [.comment] 4844 end::dl1[] 4846 [.comment] 4847 tag::bcp14_1[] 4848 // tag::bcp14[] 4850 The instructions in the _Book of Armaments_ on the proper deployment 4851 of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as 4852 follows, although this summary *SHALL NOT* be used as a substitute 4853 for a reading from the Book of Armaments: 4855 // end::bcp14[] 4856 [.comment] 4857 end::bcp14_1[] 4859 [.comment] 4860 tag::ol1[] 4861 // tag::ol[] 4863 . Preamble: St Attila Benediction 4864 . Feast of the People on Sundry Foods 4865 ** Lambs 4866 ** Sloths 4867 ** Carp 4868 ** Anchovies 4869 ** Orangutangs 4870 ** Breakfast Cereals 4871 ** Fruit Bats 4872 ** _et hoc genus omne_ 4873 . Take out the Holy Pin 4874 . The Count 4875 [upperalpha] 4876 .. Count is to Three: no more, no less 4877 .. Not Four 4878 .. Nor Two, except if the count then proceeds to Three 4879 .. Five is Right Out 4880 . Lob the Holy Hand Grenade of Antioch towards the Foe 4881 . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it 4883 // end::ol[] 4884 [.comment] 4885 end::ol1[] 4887 This could also be represented in pseudocode as follows: 4889 [.comment] 4890 tag::listcontinuationblock1[] 4891 // tag::listcontinuationblock[] 4893 . Take out the Holy Pin 4894 . The Count 4895 + 4896 ---- 4897 integer count; 4898 for count := 1 step 1 until 3 do 4899 say(count) 4900 comment Five is Right Out 4901 ---- 4902 . Lob the Holy Hand Grenade of Antioch towards the Foe 4903 . Foe snuffs it 4905 // end::listcontinuationblock[] 4906 [.comment] 4907 end::listcontinuationblock1[] 4909 == Dramatis Personae 4911 The following human (more-or-less) protagonists were involved 4912 in the two incidents recounted as lore of the Knights of the 4913 Round Table: 4915 [.comment] 4916 tag::table1[] 4917 // tag::table[] 4919 [grid=all,options="footer"] 4920 |=== 4921 |French Castle | Cave of Caerbannog 4923 2+|King Arthur 4924 2+|Patsy 4925 2+|Sir Bedevere the Wise 4926 2+|Sir Galahad the Pure 4927 2+|Sir Lancelot the Brave 4928 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot 4929 |French Guard with Outrageous Accent| Tim the Enchanter 4930 |Other French Guards | Brother Maynard 4931 | | The Lector 4932 .3+^|not yet recruited 4933 >|Sir Bors 4934 >|Sir Gawain 4935 >|Sir Ector 4937 |Retinue of sundry knights 4938 |Retinue of sundry more knights than at the French Castle 4939 |=== 4941 // end::table[] 4942 [.comment] 4943 end::table1[] 4945 === Past the Killer Rabbit 4947 Once the Killer Rabbit of Caerbannog (<>) had been 4948 dispatched, the Knights of the Round Table uncovered the last 4949 words of Joseph of Arimathea, inscribed on the Cave of Caerbannog 4950 in Aramaic. While the precise Aramaic wording has not survived, 4951 we trust the following Hebrew subtitles will serve as an 4952 acceptable substitute: 4954 [.comment] 4955 tag::hebrew1[] 4956 // tag::hebrew[] 4958 ____ 4959 .כאן אולי 4960 ימצאו 4961 המילים 4962 האחרונות של 4963 יוסף 4964 .מארמתיה 4965 .מי אשר יהיה 4966 אמיץ ובעל 4967 נפש טהורה 4968 יוכל למצוא 4969 את הגביע 4970 הקדוש בטירת 4971 .אאאאאאאה 4973 "Here may be found the last words of Joseph of Arimathea. 4974 He who is valiant and pure of spirit may find the Holy Grail 4975 in the castle of — Aaaargh." 4976 ____ 4978 // end::hebrew[] 4979 [.comment] 4980 end::hebrew1[] 4982 == IANA Considerations 4984 IANA might consider a registry to track the mythical, especially 4985 ravaging beasts, such as the Killer Rabbit, who haunt the Internet. 4987 == Security Considerations 4989 Do not let the Killer Rabbit out under any circumstance. 4991 I repeat. Do not let the Killer Rabbit (<>) out. 4993 [.comment] 4994 tag::bibliography1[] 4995 // tag::bibliography[] 4996 [bibliography] 4997 == Normative References 4998 ++++ 4999 5001 5002 Key words for use in RFCs to Indicate 5003 Requirement Levels 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 ++++ 5015 [bibliography] 5016 == Informative References 5017 ++++ 5019 5020 5021 Monty Python and the Holy Grail 5022 5023 5024 5025 5026 5027 5028 5029 5030 5032 5034 5035 DON'T SPEW A Set of Guidelines for Mass Unsolicited 5036 Mailings and Postings (spam*) 5037 5038 5039 5040 5041 5042 5043 5044 5045 5046 5047 5048 5050 5052 5053 RFC Format Framework 5054 5055 5056 5057 5058 5059 5060 5061 5063 5065 5066 5067 The Arte of ASCII: Or, An True and Accurate Representation of 5068 an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of 5069 Character 5070 5071 5072 5073 5074 5075 5076 5077 5078 5080 5082 5083 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 5084 Words 5085 5086 5087 5088 5089 RFC 2119 specifies common key words that may be used 5090 in protocol specifications. This document aims to reduce 5091 the ambiguity by clarifying that only UPPERCASE usage of the 5092 key words have the defined special meanings. 5093 5094 5095 5096 5097 5099 ++++ 5101 // end::bibliography[] 5102 [.comment] 5103 end::bibliography1[] 5104 5106 A.2.2. Rendered as RFC XML v3 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5125 5126 The Holy Hand Grenade of 5127 Antioch 5128 5130 5132 Camelot 5133
5134 5135 Palace 5136 Camel Lot 1 5137 Camelot 5138 England 5139 5140 arthur.pendragon@ribose.com 5141 http://camelot.gov.example 5142
5143 5144 5145 General 5146 Operations and Management 5147 rabbits 5148 grenades 5149 antioch 5150 camelot 5152 5154 5156 The menagerie of beasts and artefacts depicted in RFC8140 5157 may be usefully supplemented by other renowned figures of 5158 Internet and more general lore. This document extends the 5159 menagerie to the seminal fable of the 5160 "Holy Hand Grenade of Antioch", as depicted in the 5161 Monty Python film "Monty Python and the Holy Grail", 5162 as well as "Spamalot", the musical inspired by the 5163 movie. 5164 Spamalot 5165 The relevance of the musical "Spamalot" to Internet lore should be 5166 obvious to the reader; but in case of doubt, see also 5167 Section 1 ("What is Spam*?") of RFC2635. 5168 5170 5172 5174 5175
5176 Terminology 5177 The key words "MUST", "MUST NOT", 5178 "REQUIRED", "SHALL", 5179 "SHALL NOT", "SHOULD", "SHOULD 5180 NOT", "RECOMMENDED", 5181 "NOT RECOMMENDED", "MAY", and 5182 "OPTIONAL" in this document 5183 are to be interpreted as described in BCP 14 5184 5185 when, and only when, they appear in all capitals, as shown here. 5186
5187
Introduction refers to 5189 the intended move of RFC formatting to 5190 XML2RFC v3 , in the following terms: 5192 5194 5196
5197 Although the RFC Editor has recently dragged the IETF kicking and 5198 screaming into the twentieth century [RFC7990] [RFC7996], there is a 5199 yearning among all right-thinking Internet architects to "keep it 5200 simple" and to return to the olden days when pigs could be given 5201 thrust without anyone taking undue offence. 5202
5204 5206 While no pigs, flying or otherwise, are involved in the transition 5207 to RFC XML v3, it is opportune to enhance the 5208 legendarium in the service of RFC XML v3, by illustrating its 5209 functionality through references to the mythology of Camelot, and 5210 particularly the incidents at the Cave of Caerbannog. 5212 5214 The screaming move into the twenty-first century is 5215 accompanied by 5216 a move back to the late twentieth century, with ASCII stylings more 5217 wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be 5218 accessible in 1996.) 5219 5221 There are two references to rabbits in 5222 Monty Python and the Holy Grail which are expounded on 5223 herewith: 5225 5227
5228
Trojan Rabbit
5229
5230 In their siege of the French-occupied castle which may already 5231 contain an instance of the Grail, Sir Bedevere the Wise proposes to 5232 use a Trojan Rabbit to infiltrate the castle, with a raiding party 5233 to take the French "not only by surprise, but totally unarmed." 5234 The proposal, unsurprisingly, proved abortive. The more so as the 5235 raiding party forgot to hide within the Trojan Rabbit, before the 5236 French soldiers took the Trojan Rabbit inside the castle. 5237
5238
Killer Rabbit of Caerbannog
5239
Guarding the entrance to the Cave of Caerbannog; see .
5241
5243 5245
5246
The French-occupied castle 5249 5251 The participants of that renowned exercise in cross-cultural 5252 communication, to wit the exchange between the 5253 Knights of the Round Table 5254 and the taunting French soldiers serving under Guy de 5255 Lombard are, 5256 properly speaking, outside the scope of this menagerie, being 5257 more 5258 or less human. Notwithstanding, severalish beasts both 5259 animated 5260 and wooden played a significant part in this encounter; most 5261 notably: 5262
    5263
  • The Projectile Cow, see
    • 5264
  • The Trojan Rabbit, see
    • 5265
5267 5269
5270 The Projectile Cow with an accompanying cannon 5271 -.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-. 5278 .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., 5279 .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # .,.,.,. 5280 .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. 5281 .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ‘ ‘! .,.,..,.,.- 5282 .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_] . ., . . , 5283 .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / -.-<>.,.,..-.-, 5284 .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. 5285 .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- 5286 .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. 5287 .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- 5288 .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- 5289 -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- 5290 ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, 5291 ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- 5292 ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. 5293 .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., 5294 .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,. 5295 ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,. 5296 ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. 5297 .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. 5298 -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> 5299 _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,., 5300 .._...{WITHHONEY}-.-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_> 5301 GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASSPC 5302 SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS 5303 CLAY_ROCKS_REBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY>< 5304 CLAY_CLAY_SKLETONS_MORESOIL_CLAY_CLAY_CLAY_CLAY_CLAY_VR 5305 ]]> 5306
5307
5308 The Trojan Rabbit with an automatic sliding door 5309 5342
5344 5346 5357 5359 5361 Image courtesy of 5362 5365 5367 5369 The exchange of projectile animals was the beginning of a 5370 long-running fruitful relationship between the British and the 5371 French peoples, 5373 5375 which 5376 arguably predates the traditional English enmity with the 5377 French. 5379 5381 5383 5387 5389
5390
The Mythos of 5391 Caerbannog 5393 5395 The Cave of Caerbannog has been well-established in the 5396 mythology 5397 of Camelot (as recounted by Monty Python) as the lair of the 5398 Legendary Black Beast of Arrrghhh, more commonly known today as the 5399 Killer Rabbit of Caerbannog . 5401 It is the encounter between the Killer Rabbit of Caerbannog and the 5402 Knights of the Round Table, armed with the Holy Hand Grenade of 5403 Antioch (see the following 5404 section), that we 5405 recount here through monospace font and multiple spaces. 5406
The 5407 Killer Rabbit of Caerbannog 5409 5411 5413 The Killer Rabbit of Caerbannog, that most 5414 formidable foe of 5415 the Knights and of all that is holy or carrot-like, has been 5416 depicted diversely in lay and in song. We venture to say, 5417 contra the claim made in Ze Vompyre, 5419 that the Killer Rabbit of Caerbannog truly is the most afeared 5420 of all the creatures. Short of sanctified ordnance such as 5421 , there are few 5422 remedies 5423 known against its awful lapine powers. 5425 5426 5428 The following depiction of the 5429 fearsome beast 5430 has been sourced from 5431 Rabbit-SCII, 5433 accompanied 5434 by C code that was used in this accurate depiction of the 5435 Killer Rabbit: 5437 5439 5441
5442 A Photo Of The Killer Rabbit of Caerbannog Taken In 5443 Secret 5444 >>\\\\\\\\\\\\ 5449 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 5450 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 5451 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 5452 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 5453 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 5454 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 5455 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 5456 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 5457 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 5458 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 5459 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 5460 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 5461 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 5462 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 5463 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 5464 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 5465 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 5466 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 5467 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 5468 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 5469 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 5470 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 5471 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 5472 MW \\/\||v v|| -\\-------___ . ., \ | 5473 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 5474 ) /--------^-^ ,. \|// 5475 # \(/ .\\|x// " ' ' 5476 . , \\||// \||\\\// \\ 5477 ]]> 5478
5479
5480 C Code To Lure Killer Rabbit Back To Cave 5481 5483 /* Locate the Killer Rabbit */ 5484 int type; 5485 unsigned char *killerRabbit = 5486 LocateCreature(&caerbannog, "killer rabbit"); 5487 if( killerRabbit == 0 ){ 5488 puts("The Killer Rabbit of Caerbannog is out of town."); 5489 return LOST_CREATURE; 5490 } 5492 /* Load Cave */ 5493 unsigned char *cave = LoadPlace(&caerbannog, 5494 "The Cave Of Caerbannog"); 5495 if( cave == 0 ){ 5496 puts("The Cave of Caerbannog must have moved."); 5497 return LOST_PLACE; 5498 } 5500 /* Lure the Killer Rabbit back into the Cave */ 5501 unsigned char *carrot = allocateObjectInPlace( 5502 carrot("fresh"), cave); 5503 if( carrot == 0 ){ 5504 puts("No carrot, no rabbit."); 5505 return LOST_LURE; 5506 } 5508 /* Finally, notify the Killer Rabbit to act */ 5509 return notifyCreature(killerRabbit, &carrot); 5510 5511 ]]> 5512
5514 5515 On the beast's encounter with the Knights of the Round Table, 5516 the following personnel engaged with it in combat: 5518 5520
    5521
  • 5522 Killed 5523
      5524
    • Sir Bors
      • 5525
    • Sir Gawain
      • 5526
    • Sir Ector
      • 5527
    5528
    • 5529
  • 5530 Soiled Himself 5531
      5532
    • Sir Robin
      • 5533
    5534
    • 5535
  • 5536 Panicked 5537
      5538
    • King Arthur
      • 5539
    5540
    • 5541
  • 5542 Employed Ordnance 5543
      5544
    • The Lector
      • 5545
    • Brother Maynard
      • 5546
    5547
    • 5548
  • 5549 Scoffed 5550
      5551
    • Tim the Enchanter
      • 5552
    5553
    • 5554
5556 5558
5559
Holy Hand 5560 Grenade of Antioch 5562 5564
5565 The Holy Hand Grenade of Antioch (don't pull the pin) 5566 5594
5596 5598
5599 The Sovereign's Orb made invisible 5600 5603
5604 5606 The solution to the impasse at the Cave of Caerbannog was 5608 provided by the successful deployment of the 5609 Holy Hand Grenade of Antioch (see ) 5611 . 5612 Any similarity between the Holy Hand Grenade of Antioch and the 5613 mythical Holy Spear of Antioch is purely intentional; 5614 any similarity between the 5615 Holy Hand Grenade 5616 of Antioch and the Sovereign's Orb of the United Kingdom 5617 (see ) is putatively fortuitous. 5618 5620 5622 5624
5625
Holy Hand Grenade of Antioch
5626
Ordnance deployed by Brother Maynard under the incantation of a 5627 lector, in order to dispense with the Foes of the Virtuous. 5628 See .
5629
Holy Spear of Antioch
5630
A supposed relic of the crucifixion of Jesus Christ, this is one 5631 of at least four claimed instances of the lance that pierced 5632 Christ's side. Its historical significance lies in inspiring 5633 crusaders to continue their siege of Antioch in 1098.
5634
Sovereign's Orb of the United Kingdom
5635
Part of the Crown Jewels of the United Kingdom, the Sovereign's 5636 Orb is a hollow gold sphere set with jewels and topped with a 5637 cross. It was made for Charles II in 1661. See .
5639
5641 5642 5644 The instructions in the Book of Armaments on the proper 5645 deployment 5646 of the Holy Hand Grenade of Antioch MAY be summarized as 5647 follows, although this summary SHALL NOT be used as a 5648 substitute 5649 for a reading from the Book of Armaments: 5651 5653 5655
    5656
  1. Preamble: St Attila Benediction
    2. 5657
  2. 5658 Feast of the People on Sundry Foods 5659
      5660
    • Lambs
      • 5661
    • Sloths
      • 5662
    • Carp
      • 5663
    • Anchovies
      • 5664
    • Orangutangs
      • 5665
    • Breakfast Cereals
      • 5666
    • Fruit Bats
      • 5667
    • 5668 et hoc genus omne 5669
      • 5670
    5671
    3. 5672
  3. Take out the Holy Pin
    4. 5673
  4. 5674 The Count 5675
      5676
    1. Count is to Three: no more, no less
      2. 5677
    2. Not Four
      3. 5678
    3. Nor Two, except if the count then proceeds to Three
      4. 5679
    4. Five is Right Out
      5. 5680
    5681
    5. 5682
  5. Lob the Holy Hand Grenade of Antioch towards the Foe
    6. 5683
  6. The Foe, being naughty in the LORD's sight, 5684 SHALL snuff it
    7. 5685
5687 5689 This could also be represented in pseudocode as follows: 5691 5693
    5694
  1. Take out the Holy Pin
    2. 5695
  2. 5696 The Count 5697
    5698 5704
    5705
    3. 5706
  3. Lob the Holy Hand Grenade of Antioch towards the Foe
    4. 5707
  4. Foe snuffs it
    5. 5708
5710 5712
5713
Dramatis 5714 PersonaeThe following human (more-or-less) protagonists were 5715 involved 5716 in the two incidents recounted as lore of the Knights of the 5717 Round Table: 5719 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5747 5748 5749 5750 5751 5752 5753 5754 5755 5756 5757 5759 5760 5761 5762 5763 5764 5765 5766 5767 5768 5769 5770 5771 5772 5773 5774 5776 5777 5778
French CastleCave of Caerbannog
King Arthur
Patsy
Sir Bedevere the Wise
Sir Galahad the Pure
Sir Lancelot the Brave
Sir Robin the 5746 Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous AccentTim the Enchanter
Other French GuardsBrother Maynard
5758 The Lector
not yet recruitedSir Bors
Sir Gawain
Sir Ector
Retinue of sundry knightsRetinue of sundry more knights than at the 5775 French Castle
5780 5782
Past 5783 the Killer RabbitOnce the Killer Rabbit of Caerbannog () had been 5785 dispatched, the Knights of the Round Table uncovered the last 5786 words of Joseph of Arimathea, inscribed on the Cave of Caerbannog 5787 in Aramaic. While the precise Aramaic wording has not survived, 5788 we trust the following Hebrew subtitles will serve as an 5789 acceptable substitute: 5791 5793
כאן אולי 5794 ימצאו 5795 המילים 5796 האחרונות של 5797 יוסף 5798 .מארמתיה 5799 מי אשר יהיה 5800 אמיץ ובעל 5801 נפש טהורה 5802 יוכל למצוא 5803 את הגביע 5804 הקדוש בטירת 5805 .אאאאאאאה 5806 "Here may be found the last words of Joseph of Arimathea. 5807 He who is valiant and pure of spirit may find the Holy Grail 5808 in the castle of — Aaaargh."
5810 5812
5813
5814 IANA Considerations 5815 IANA might consider a registry to track the mythical, especially 5816 ravaging beasts, such as the Killer Rabbit, who haunt the Internet. 5817
5818
Security ConsiderationsDo not let the Killer 5820 Rabbit out under any circumstance. 5821 I repeat. Do not let the Killer Rabbit () out. 5824 5826
5827 5828 5829 Normative References 5830 5833 5834 5835 Informative References 5836 5837 5838 Monty Python and the Holy Grail 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5851 5854 5857 5860 5861 5862 5863 5865 A.3. Example 3: "An API For Calendar-Based Fortune Heuristics Services" 5866 in AsciiRFC 5868 This example is available in the following formats: 5870 o AsciiRFC [git-divination-cfapi] 5872 o Internet-Draft [I-D.divination-cfapi] 5874 o Text, RFC XML, PDF and HTML on the IETF Datatracker 5875 [datatracker-divination-cfapi] 5877 A.3.1. In AsciiRFC 5879 5880 = An API For Calendar-Based Fortune Heuristics Services 5881 Gabriel Destiny; Charise Luck 5882 :doctype: internet-draft 5883 :abbrev: Calendar Fortune Heuristics API 5884 :name: draft-divination-cfapi-00 5885 :status: informational 5886 :ipr: trust200902 5887 :area: Internet 5888 :submission-type: independent 5889 :intended-series: informational 5890 :revdate: 2018-03-23T00:00:00Z 5891 :lastname: Destiny 5892 :fullname: Gabriel Destiny 5893 :forename_initials: G. 5894 :organization: Divination Inc. 5895 :email: gabriel.destiny@ribose.com 5896 :street: 9288 N Divine Street 5897 :city: Dunn 5898 :code: 28334 5899 :region: NC 5900 :country: United States of America 5901 :lastname_2: Luck 5902 :fullname_2: Charise Luck 5903 :forename_initials_2: C. 5904 :organization_2: Divination Inc. 5905 :email_2: charise.luck@ribose.com 5906 :street_2: 9288 N Divine Street 5907 :city_2: Dunn 5908 :code_2: 28334 5909 :region_2: NC 5910 :country_2: United States of America 5912 [.comment] 5913 tag::sample[] 5914 // tag::sample[] 5916 [abstract] 5918 This document describes a JSON HTTP API for online services that 5919 provide calendar-based fortune heuristics. 5921 == Introduction 5923 Fortune-telling, the practice of predicting information about a 5924 person's life, is an activity practiced throughout history. 5926 While there are myriad forms of fortune telling methodologies, this 5927 document applies to a particular form of service that provides fortune 5928 heuristics, commonly known as "luck", for a particular subject based 5929 on a calendar-based input. 5931 Since HTTP <> status codes are insufficient to convey 5932 information about fortune heuristics, this specification defines a 5933 simple JSON <> document format for this purpose. The 5934 response can be used by HTTP APIs to deliver results to non-human 5935 clients or to an end-user. 5937 == Conventions Used in This Document 5939 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 5940 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 5941 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 5942 are to be interpreted as described in BCP 14 <> <> 5943 when, and only when, they appear in all capitals, as shown here. 5945 The following definitions apply in this document: 5947 Well-known URI:: This specification makes use of the "well-known URI" 5948 feature of HTTP servers <> to provide a bootstrapping URI for 5949 the client usage of fortune heuristics services. 5951 Root of Fortune:: The service discovery endpoint that provides a URI 5952 list of available fortune heuristic endpoints available, in accordance 5953 with <>. 5955 == Fortune Heuristics Service Well-Known URI 5957 A well-known URI called "fortune" is registered by this specification 5958 for fortune heuristics services (see <>). 5960 Services complying with this document *SHOULD* have its well-known 5961 URI pointing (directly or through redirection) to the Root of Fortune. 5963 The Root of Fortune can be used by the client for service discovery, 5964 namely, the available calendar-based fortune heuristics services 5965 available on the server, as specified in <>. 5967 === Well-Known URI Redirection 5969 Servers *MUST* redirect HTTP requests for that resource to the 5970 actual "context path" using one of the available mechanisms provided 5971 by HTTP <> (e.g., using a 301, 303, or 307 response). 5973 Clients *MUST* handle HTTP redirects on the well-known URI. 5975 === Well-Known URI Cache Behavior 5977 Servers *SHOULD* set an appropriate Cache-Control header value (as 5978 according to <>) in the redirect response to set 5979 caching behavior as required by the type of response generated. 5981 == New HTTP Methods: SEEK and DIVINE 5983 This specification defines two new HTTP methods: "SEEK" and "DIVINE" 5984 methods for HTTP <>. 5986 While HTTP GET requests are treated equivalently as the "SEEK" and 5987 "DIVINE" requests, its usage is discouraged and therefore *SHOULD NOT* 5988 be used. 5990 Usage of these methods are defined in the sections below. 5992 == Defined Data Types: Date-Time Formats 5994 This specification defines a number of date-time formats as according 5995 to the conventions of <> for the unambiguous communication 5996 between client and server. 5998 The types defined are as follows. 6000 `DATETIME`:: 6001 As described in <>, with the addition that reduced 6002 accuracy representations described in <> are 6003 supported. Reduced accuracy date and times are accepted where a 6004 date or time component (2-digits long) is replaced by "--". 6006 + 6007 For example, the date time "2018-04---T01:02:00Z" represents the UTC 6008 time of 1:02am, on an unknown day within April of the year 2018. 6010 `DATE`:: 6011 As described in "DATETIME", but the "time" component will not be 6012 taken into account in the algorithm. 6014 [#service-discovery] 6015 == Fortune Heuristics Service Discovery 6017 [#root-of-fortune] 6018 === Root of Fortune Path URI ("/") 6020 The Root of Fortune URI, defined as "/" in this document, is used for 6021 service discovery on types of calendar-based fortune heuristics 6022 available. 6024 An empty SEEK request with the "application/json" request type 6025 *MUST* be sent to this endpoint to retrieve the available endpoints. 6026 All other HTTP methods *MUST NOT* be supported at this URI. 6028 An example of such a response is as follows: 6030 [source,json] 6031 ---- 6032 HTTP/1.1 200 Success 6033 Content-Type: application/json 6034 Content-Language: en 6036 { 6037 "diviners" : [ 6038 "/astrology", 6039 "/bazi", 6040 ] 6041 } 6042 ---- 6044 A service discovery object *MUST* have the following members: 6046 `diviners`:: 6047 (JSON array) 6048 An array that contains endpoints that conform to this specification. 6049 All endpoints listed here are relative to the Root of Fortune path. 6050 For example, the path "/astrology" listed in the example has an 6051 endpoint path of "[root-of-fortune]/astrology", where 6052 "[root-of-fortune]" indicates the real path of the Root of Fortune. 6054 // end::sample[] 6055 [.comment] 6056 end::sample[] 6058 [#service-endpoint] 6059 == Fortune Heuristics Service Endpoint 6061 An endpoint offering fortune heuristics services *MUST* adhere to 6062 specifications in this section. 6064 A service *MAY* implement multiple divination services based on 6065 different divination methods, such as the digital oracle shown 6066 in <>. 6068 [[digital-oracle]] 6069 .Dimensional Eye, a digital oracle that communicates through one button 6070 ==== 6071 [alt=An incarnation of the Dimensional Eye, in ASCII] 6072 .... 6073 __ 6074 __===^-\ 6075 __=== -\ 6076 __===- -\ 6077 __===- -\ 6078 ___===- -\ 6079 ===- ---__ -\ 6080 \\\ |||^^\ \__ -\ 6081 \\\ ||| \__ -\ 6082 \\\ ||| ______\_ -\ 6083 \\\ ||| _/-******\\__ -\ 6084 \\\ || /-****_****-\ \_ -\ 6085 \\\ || |-***/ \***-\ \_ -\ 6086 \\\ || |-***\___/***-| \ -\ 6087 \\\ || \-*********-/ __--/ -\ 6088 \\\ || \-******/__-- -\ 6089 \\\ || __-- -\ 6090 \\\ || __-- -\ 6091 \\\ ||__-- -\ 6092 \\\ -\ 6093 \\\ -\ 6094 \\\ -\ 6095 \\\ -\ 6096 \\\ __ -\ 6097 \\\ //##\\ -\ 6098 \\\ \\##// -\ 6099 \\\ ^^ __--==^ 6100 \\\ __--=== 6101 \\\ __--=== 6102 \\\ __--=== 6103 \\\ __--== 6104 \\= 6106 .... 6107 ==== 6109 [#endpoint-specification-request] 6110 === Service Specification Request 6112 To retrieve capabilities and parameters of an endpoint complying with 6113 this specification, a service specification JSON object is returned. 6115 An empty SEEK request with the "application/json" request type 6116 *MUST* be sent to this endpoint to retrieve the service 6117 specification that describes parameters accepted by this endpoint. 6119 Two examples of such a response are given below. 6121 [source,json] 6122 ---- 6123 HTTP/1.1 200 Success 6124 Content-Type: application/json 6125 Content-Language: en 6127 { 6128 "description": "Gaze into your upcoming luck!", 6129 "details": "https://divine.example.com/manual/astrology-api", 6130 "parameters": { 6131 "birthday": { 6132 "type": "DATE", 6133 "description": "Your birth date in UTC" 6134 }, 6135 "targetDateBegin": { 6136 "type": "DATE", 6137 "description": "Start of the target date range to report on" 6138 }, 6139 "targetDateEnd": { 6140 "type": "DATE", 6141 "description": "End of the target date range to report on" 6142 }, 6143 "interval": { 6144 "values": { 6145 "D": "Daily", 6146 "M": "Monthly", 6147 "Y": "Yearly" 6148 }, 6149 "description": "Available intervals to report on." 6150 } 6151 } 6152 } 6153 ---- 6155 [source,json] 6156 ---- 6157 HTTP/1.1 200 Success 6158 Content-Type: application/json 6159 Content-Language: en 6161 { 6162 "description": "Matches and mis-matches according to the " 6163 "Yin Yang and Five Elements techniques", 6164 "details": "https://divine.example.com/manual/bazi-api", 6165 "parameters": { 6166 "birthday": { 6167 "type": "DATETIME", 6168 "description": "Your birth date and time in UTC" 6169 }, 6170 "targetDateBegin": { 6171 "type": "DATETIME", 6172 "description": "Start of the target date/time range to report on" 6173 }, 6174 "targetDateEnd": { 6175 "type": "DATETIME", 6176 "description": "End of the target date/time range to report on" 6177 }, 6178 "interval": { 6179 "values": { 6180 "H": "Hourly", 6181 "D": "Daily", 6182 "M": "Monthly", 6183 "Y": "Yearly" 6184 }, 6185 "description": "Available intervals to report on." 6186 } 6187 } 6188 } 6189 ---- 6191 [#service-endpoint-specification] 6192 === Service Specification Object 6194 A service specification object *MUST* contain the following members. 6196 `description`:: 6197 (string) A short, human-readable summary of the fortune heuristic 6198 service at this endpoint. This *SHOULD* be a stable reference. 6200 `details`:: 6201 (URI, optional) A URI reference that provides further details for 6202 human consumption, such as API documentation that includes details of 6203 parameters accepted or response states. 6205 `parameters`:: 6206 (object, mandatory) An object that specifies what parameters 6207 are accepted by this endpoint. Each parameter key within this object 6208 specifies an accepted parameter name, and its value is a parameter 6209 specification object, which is described below. 6211 A parameter specification object *SHOULD* contain the following 6212 members: 6214 `type`:: 6215 (string, optional) The value type accepted by this parameter. Value 6216 types are described in this document. This member is mutually 6217 exclusive with `values`. 6219 `description`:: 6220 (string, mandatory) The purpose of this parameter. 6222 `values`:: 6223 (object, optional) The accepted values of this parameter, unlisted 6224 values *SHOULD* not be accepted by the parameter. Each key within 6225 this object specifies an accepted value, and its value provides a 6226 description of the purpose of the value. 6228 [#endpoint-report] 6229 == Fortune Heuristics Report Request and Response 6231 [#endpoint-report-request] 6232 === Fortune Heuristics Report Request 6234 A request using the HTTP "DIVINE" method and the "application/json" 6235 type *MUST* be sent to the fortune heuristic endpoint to retrieve 6236 results for a fortune heuristic query. 6238 The request made *MUST* conform to the specifications of the 6239 endpoint, as retrieved via the "SEEK" method described in 6240 <>. 6242 An example of a request is provided below. 6244 [source] 6245 ---- 6246 URI: /divination/astrology 6247 Method: DIVINE 6248 Content-Type: application/json 6249 Content-Language: en 6251 { 6252 "birthday": "1976-02-11T00:00:00Z", 6253 "targetDateBegin": "2018-01-01T00:00:00Z", 6254 "targetDateEnd": "2019-01-01T00:00:00Z", 6255 "interval": "M" 6256 } 6257 ---- 6259 [#endpoint-report-response] 6260 === Fortune Heuristics Report Response 6262 A fortune heuristic query using the "DIVINE" method triggers a 6263 response that contains a fortune heuristics report. 6265 A successful response returns a JSON object that *MUST* conform 6266 to the object structure described in this section. 6268 A report object *SHOULD* contain the following members: 6270 `type`:: 6271 (URI, mandatory) A URI that defines the type of the report located 6272 at the `report` key of this object. 6274 `report`:: 6275 (object, mandatory) An object that contains two keys, `intervals` 6276 and `events`. The `intervals` object contains an array of interval 6277 objects that matches the demanded intervals in the request within 6278 the target date range. 6279 The `events` object contains an array of significant event objects 6280 within the target date range. 6282 An example of a response is provided below. 6284 [source] 6285 ---- 6286 URI: /divination/astrology 6287 Method: DIVINE 6288 HTTP/1.1 200 Success 6289 Content-Type: application/json 6290 Content-Language: en 6291 { 6292 "type": "https://association-of.astrology/reports/monthly", 6293 "report": { 6294 "intervals": [ 6295 { 6296 "dateStart": "2018-01-01T00:00:00Z", 6297 "dateEnd": "2018-02-01T00:00:00Z", 6298 "categories": [ 6299 { 6300 "category": 6301 "https://divine.example.com/astrology/categories/health" 6302 "value": 80, 6303 "description": "Charge ahead with excellent health." 6304 }, 6305 { 6306 "category": 6307 "https://divine.example.com/astrology/categories/love" 6308 "value": 70, 6309 "description": 6310 "Give a certain person or situation another try!" 6311 }, 6312 { 6313 "category": 6314 "https://divine.example.com/astrology/categories/finance" 6315 "value": 5, 6316 "description": "You've just realized that you don't have 6317 any cash on hand." 6318 } 6319 ] 6320 }, 6321 { 6322 "dateStart": "2018-02-01T00:00:00Z", 6323 "dateEnd": "2018-03-01T00:00:00Z", 6324 "..." 6325 }, 6326 "..." 6327 ], 6328 "events": [ 6329 { 6330 "dateStart": "2018-01-15T03:20:00", 6331 "dateEnd": "2018-01-16T20:22:15", 6332 "description": "The planet of growth and good luck, Jupiter 6333 will make a harmonious connection with power planet Pluto, 6334 helping you connect with influential people", 6335 "recommendation": "Engage in networking during this time." 6336 }, 6337 { 6338 "dateStart": "2018-03-22T00:12:40", 6339 "dateEnd": "2018-03-28T02:45:03", 6340 "description": "Communication planet Mercury enters your sign, 6341 which will find you in a busier and chattier mood.", 6342 "recommendation": 6343 "Take charge of work with your newfound energy." 6344 } 6345 "..." 6346 ] 6347 } 6348 } 6349 ---- 6351 Fortune heuristic reports are created by a divination output that 6352 *MAY* requires quantitative interpretation. A sample representation of 6353 interpreting a graphical divination output is provided in 6354 <>. 6356 [[divination-message]] 6357 .Forty-nine yarrow sticks reveals a mystical message on fortune 6358 ==== 6359 [alt=A mystical pattern in ASCII] 6360 .... 6361 0000000000000000000000000 6362 0000000000000000000000001 G 1000000000000000000000000 6363 0000000000000000000000011 R 1100000000000000000000000 6364 0000000000000000000000111 A 1110000000000000000000000 6365 0000000000000000000001111 C 1111000000000000000000000 6366 0000000000000000000011111 E 1111100000000000000000000 6367 0000000000000000000111111 , 1111110000000000000000000 6368 0000000000000000001111111 1111111000000000000000000 6369 0000000011111111111111111 M 1111111111111111100000000 6370 0000000111111111111111111 E 1111111111111111110000000 6371 0000001111111111111111111 R 1111111111111111111000000 6372 0000011111111111111111111 C 1111111111111111111100000 6373 0000111111111111111111111 Y 1111111111111111111110000 6374 0001111111111111111111111 , 1111111111111111111111000 6375 0011111111111111111111111 1111111111111111111111100 6376 0111111111111111111111111 A 1111111111111111111111110 6377 0000000000000000011111111 N 1111111100000000000000000 6378 0000000000000000111111111 D 1111111110000000000000000 6379 0000000000000001111111111 1111111111000000000000000 6380 0000000000000011111111111 P 1111111111100000000000000 6381 0000000000000111111111111 E 1111111111110000000000000 6382 0000000000001111111111111 A 1111111111111000000000000 6383 0000000000011111111111111 C 1111111111111100000000000 6384 0000000000111111111111111 E 1111111111111110000000000 6385 0000000001111111111111111 . 1111111111111111000000000 6386 .... 6387 ==== 6389 [#endpoint-report-interval-obj] 6390 === Report Interval Object 6392 The `intervals` value of a report object contains a number of report 6393 intervals -- each representing a non-overlapping period of the 6394 selected interval length. When all of these intervals are put 6395 together, the combined period *MUST* fully cover the requested 6396 report target period. 6398 An example interval object is shown below. 6400 [source,json] 6401 ---- 6402 { 6403 "dateStart": "2018-01-01T00:00:00Z", 6404 "dateEnd": "2018-02-01T00:00:00Z", 6405 "categories": [ 6406 { 6407 "category": 6408 "https://divine.example.com/astrology/categories/health" 6409 "value": 80, 6410 "description": "Charge ahead with your excellent health." 6411 }, 6412 { 6413 "category": 6414 "https://divine.example.com/astrology/categories/love" 6415 "value": 70, 6416 "description": "Give a certain person or situation another try!" 6417 }, 6418 { 6419 "category": 6420 "https://divine.example.com/astrology/categories/finance" 6421 "value": 5, 6422 "description": "You've just realized that you don't have 6423 any cash on hand." 6424 } 6425 ] 6426 } 6427 ---- 6429 An interval object *MUST* contain the following members: 6431 `dateStart`:: 6433 (datetime, mandatory) This value specifies the start of the period 6434 which this interval object applies to. 6436 `dateEnd`:: 6437 (datetime, mandatory) This value specifies the end of the period 6438 which this interval object applies to. 6440 In the given example, the `categories` key is an implementation 6441 specific object that details heuristic results returned by the 6442 selected algorithm. This *MAY* differ in different algorithms. 6444 [#endpoint-report-event-obj] 6445 === Report Events Object 6447 The `events` value of a report object contains a number of event 6448 objects. Each event object represents an event relevant to the 6449 calculation of fortune heuristics during a target report period. These 6450 events *MAY* be of variable time lengths, and *MAY* be overlapping 6451 amongst each other. 6453 The following example demonstrates two event objects the service 6454 determines relevant to a user's query. 6456 [source,json] 6457 ---- 6458 { 6459 "dateStart": "2018-01-15T03:20:00", 6460 "dateEnd": "2018-01-16T20:22:15", 6461 "description": "The planet of growth and good luck, Jupiter will 6462 make a harmonious connection with power planet Pluto, helping you 6463 connect with influential people", 6464 "recommendation": "Engage in networking during this time." 6465 }, 6466 { 6467 "dateStart": "2018-03-22T00:12:40", 6468 "dateEnd": "2018-03-28T02:45:03", 6469 "description": "Communication planet Mercury enters your sign, 6470 which will find you in a busier and chattier mood.", 6471 "recommendation": "Take charge of work with your newfound energy." 6472 } 6473 ---- 6475 Similar to an interval object, an event object *MUST* contain the 6476 following members: 6478 `dateStart`:: 6479 (datetime, mandatory) This value specifies the start of the period 6480 described by the event. 6482 `dateEnd`:: 6483 (datetime, mandatory) This value specifies the end of the period 6484 described by the event. 6486 In the given example, the keys `description` and `recommendation` 6487 are implementation-specific details. This *MAY* differ in different 6488 algorithms. 6490 [#endpoint-report-errors] 6491 === Report Generation Errors 6493 This specification makes use of normal HTTP error codes with the 6494 following extensions. 6496 Errors *MUST* be returned using the Problem JSON Structure as 6497 accordance with <>. 6499 422 Unprocessable Entity:: 6500 For example, a malformed date-time parameter, or an illogical input, 6501 such as when the subject's birthday occurs after the report target 6502 date period. 6504 473 Beyond Existing Capability:: 6505 The service determines that the outcome is too difficult to predict. 6506 For example, in the case where the calculation is too complex to 6507 complete in a certain time period. The service *SHOULD* issue this 6508 response code to indicate that the client should not try the same 6509 request again. 6511 474 Outcome Impossible:: 6512 The service determines that the outcome is impossible. For example, 6513 when the algorithm determines that the subject will have deceased 6514 before the start of the requested target period. 6516 [#security] 6517 == Security Considerations 6519 * TLS <> and authenticated HTTP requests should be used to 6520 protect the DIVINE request and responses due to the personal nature 6521 of information transmitted. 6523 * A client *SHOULD* verify the identity of the server on every 6524 request to prevent impersonation or man-in-the-middle attacks, as data 6525 transmitted to and from the server is sensitive information, and at 6526 times critical information to the user. 6528 * Synchronization of client and server time *MUST* be 6529 well-considered in the implementation of this specification. A 6530 mismatch of client and server time *MAY* lead to algorithm 6531 miscalculations that can cause mistaken choices of a user that depends 6532 on the reliability of this system. 6534 [#iana] 6535 == IANA Considerations 6537 === Well-Known URI Registrations 6539 This document defines a well-known URI using the registration 6540 procedure and template from <>. 6542 ==== "fortune" Well-Known URI Registration 6544 URI suffix:: fortune 6546 Change controller:: IETF 6548 Specification document(s):: This document 6550 Related information:: N/A. 6552 [.comment] 6553 tag::sample[] 6554 // begin::sample[] 6556 [bibliography] 6557 == Normative References 6559 ++++ 6561 6563 6564 Key words for use in RFCs to Indicate Requirement 6565 Levels 6566 6567 6568 6569 6570 In many standards track documents several words are 6571 used to signify the requirements in the specification. These 6572 words are often capitalized. This document defines these words 6573 as they should be interpreted in IETF documents. This 6574 document specifies an Internet Best Current Practices for the 6575 Internet Community, and requests discussion and suggestions 6576 for improvements. 6577 6578 6579 6580 6581 6583 6585 6586 Defining Well-Known Uniform Resource Identifiers 6587 (URIs) 6588 6590 6591 6592 6594 6595 6596 6597 This memo defines a path prefix for "well-known 6598 locations", "/.well-known/", in selected Uniform 6599 Resource Identifier (URI) schemes. 6600 [STANDARDS-TRACK] 6601 6602 6603 6604 6606 6608 6609 Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and 6610 Routing 6611 6613 6614 6615 6617 6618 6619 6620 The Hypertext Transfer Protocol (HTTP) is a stateless 6621 application-level protocol for distributed, collaborative, 6622 hypertext information systems. This document provides an 6623 overview of HTTP architecture and its associated terminology, 6624 defines the "http" and "https" Uniform 6625 Resource Identifier (URI) schemes, defines the HTTP/1.1 6626 message syntax and parsing requirements, and describes related 6627 security concerns for implementations. 6628 6629 6630 6631 6633 6635 6636 Hypertext Transfer Protocol (HTTP/1.1): Caching 6637 6639 6640 6641 6644 6645 6646 6648 6649 6650 6651 The Hypertext Transfer Protocol (HTTP) is a stateless 6652 \%application- level protocol for distributed, collaborative, 6653 hypertext information systems. This document defines HTTP 6654 caches and the associated header fields that control cache 6655 behavior or indicate cacheable response 6656 messages. 6657 6658 6659 6660 6662 6664 6665 Problem Details for HTTP APIs 6666 6668 6669 6670 6671 6672 6673 6674 This document defines a "problem detail" 6675 as a way to carry machine- readable details of errors in a 6676 HTTP response to avoid the need to define new error response 6677 formats for HTTP APIs. 6678 6679 6680 6681 6683 6685 6686 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 6687 Words 6688 6689 6690 6691 6692 RFC 2119 specifies common key words that may be used 6693 in protocol specifications. This document aims to reduce 6694 the ambiguity by clarifying that only UPPERCASE usage of the 6695 key words have the defined special meanings. 6696 6697 6698 6699 6700 6702 6704 6705 The JavaScript Object Notation (JSON) Data Interchange 6706 Format 6707 6709 6710 6711 6712 JavaScript Object Notation (JSON) is a lightweight, 6713 text-based, language-independent data interchange format. 6715 It was derived from the ECMAScript Programming Language 6716 Standard. JSON defines a small set of formatting rules for 6717 the portable representation of structured data. 6718 This document removes inconsistencies with other 6719 specifications of JSON, repairs specification errors, and 6720 offers experience-based interoperability 6721 guidance. 6722 6723 6724 6725 6726 6727 6728 ++++ 6730 [bibliography] 6731 == Informative References 6733 ++++ 6735 6737 6738 ISO/DIS 8601-1:2018, Data elements and interchange 6739 formats -- Information interchange -- Representation of dates 6740 and times -- Part 1: Basic rules 6741 6742 ISO/IEC 6743
6744 http://www.iso.org 6745
6746 6747 6748 6749 6750 6752 6754 6755 Date and Time on the Internet: Timestamps 6756 6757 6758 6759 6760 6761 6762 6763 6764 6765 6766 6768 6770 6771 The Transport Layer Security (TLS) Protocol 6772 Version 1.2 6773 6774 6775 6776 6777 6778 6779 6780 This document specifies Version 1.2 of the Transport 6781 Layer Security (TLS) protocol. The TLS protocol provides 6782 communications security over the Internet. The protocol 6783 allows client/server applications to communicate in a way 6784 that is designed to prevent eavesdropping, tampering, or 6785 message forgery. [STANDARDS-TRACK] 6786 6787 6788 6789 6790 ++++ 6792 [appendix] 6793 == Acknowledgements 6795 The authors thank the following individuals for their valuable 6796 feedback on this specification, and commend them for making fortune 6797 heuristics more accessible for the benefit of mankind. 6799 // end::sample[] 6800 [.comment] 6801 end::sample[] 6802 6804 A.4. Rendered as RFC XML v3 6806 6807 6808 6809 6810 6811 6812 6813 6814 6815 6816 6817 6820 6821 An API For 6822 Calendar-Based Fortune Heuristics Services 6823 6825 6827 6828 Divination Inc. 6829
6830 6831 9288 N Divine Street 6832 Dunn 6833 NC 6834 28334 6835 United States of America 6836 6837 gabriel.destiny@ribose.com 6838
6839 6840 6841 Divination Inc. 6842
6843 6844 9288 N Divine Street 6845 Dunn 6846 NC 6847 28334 6848 United States of America 6849 6850 charise.luck@ribose.com 6851
6852 6853 6854 Internet 6856 6858 6860 This document describes a JSON HTTP API for online services that 6861 provide calendar-based fortune heuristics. 6862 6863
IntroductionFortune-telling, the practice of 6865 predicting information about a 6866 person’s life, is an activity practiced throughout history. 6867 While there are myriad forms of fortune telling methodologies, this 6868 document applies to a particular form of service that provides fortune 6869 heuristics, commonly known as "luck", for a particular subject based 6870 on a calendar-based input. 6871 Since HTTP status codes are insufficient to 6872 convey 6873 information about fortune heuristics, this specification defines a 6874 simple JSON document format for this purpose. 6875 The 6876 response can be used by HTTP APIs to deliver results to non-human 6877 clients or to an end-user.
6878
Conventions Used in This DocumentThe key words 6880 "MUST", "MUST NOT", 6881 "REQUIRED", "SHALL", 6882 "SHALL NOT", "SHOULD", "SHOULD 6883 NOT", "RECOMMENDED", 6884 "NOT RECOMMENDED", "MAY", and 6885 "OPTIONAL" in this document 6886 are to be interpreted as described in BCP 14 6887 6888 when, and only when, they appear in all capitals, as shown here. 6889 The following definitions apply in this document: 6890
6891
Well-known URI
6892
This specification makes use of the "well-known URI" 6893 feature of HTTP servers to provide a 6894 bootstrapping URI for 6895 the client usage of fortune heuristics services.
6896
Root of Fortune
6897
The service discovery endpoint that provides a URI 6898 list of available fortune heuristic endpoints available, in accordance 6899 with .
6900
6901
Fortune Heuristics Service Well-Known URIA 6903 well-known URI called "fortune" is registered by this specification 6904 for fortune heuristics services (see ). 6905 Services complying with this document SHOULD have its 6906 well-known 6907 URI pointing (directly or through redirection) to the Root of 6908 Fortune. 6909 The Root of Fortune can be used by the client for service discovery, 6910 namely, the available calendar-based fortune heuristics services 6911 available on the server, as specified in . 6913
Well-Known URI RedirectionServers 6915 MUST redirect HTTP requests for that resource to the 6916 actual "context path" using one of the available mechanisms provided 6917 by HTTP (e.g., using a 301, 303, or 307 6918 response). 6919 Clients MUST handle HTTP redirects on the well-known 6920 URI.
6921
6922 Well-Known URI Cache Behavior 6923 Servers SHOULD set an appropriate Cache-Control 6924 header value (as 6925 according to ) in the redirect response to set 6927 caching behavior as required by the type of response generated. 6928
6929
New HTTP Methods: SEEK and DIVINEThis 6931 specification defines two new HTTP methods: "SEEK" and "DIVINE" 6932 methods for HTTP . 6933 While HTTP GET requests are treated equivalently as the "SEEK" and 6934 "DIVINE" requests, its usage is discouraged and therefore SHOULD 6935 NOT 6936 be used. 6937 Usage of these methods are defined in the sections 6938 below.
6939
Defined Data Types: Date-Time FormatsThis 6941 specification defines a number of date-time formats as according 6942 to the conventions of for the unambiguous 6943 communication 6944 between client and server. 6945 The types defined are as follows. 6946
6947
6948 DATETIME 6949
6950
6951 As described in , with the addition that reduced 6953 accuracy representations described in 6954 are 6955 supported. Reduced accuracy date and times are accepted where a 6956 date or time component (2-digits long) is replaced by "--". 6957 For example, the date time "2018-04---T01:02:00Z" represents the 6958 UTC 6959 time of 1:02am, on an unknown day within April of the year 2018. 6960
6961
6962 DATE 6963
6964
As described in "DATETIME", but the "time" component will not be 6965 taken into account in the algorithm.
6966
6967
6968 Fortune Heuristics Service Discovery 6969
Root of 6970 Fortune Path URI ("/")The Root of Fortune URI, defined as "/" 6971 in this document, is used for 6972 service discovery on types of calendar-based fortune heuristics 6973 available. 6974 An empty SEEK request with the "application/json" request type 6975 MUST be sent to this endpoint to retrieve the available 6976 endpoints. 6977 All other HTTP methods MUST NOT be supported at this 6978 URI. 6979 An example of such a response is as follows: 6980
6981 6993
6994 A service discovery object MUST have the following 6995 members: 6996
6997
6998 diviners 6999
7000
(JSON array) 7001 An array that contains endpoints that conform to this specification. 7002 All endpoints listed here are relative to the Root of Fortune path. 7003 For example, the path "/astrology" listed in the example has an 7004 endpoint path of "[root-of-fortune]/astrology", where 7005 "[root-of-fortune]" indicates the real path of the Root of Fortune.
7006
7008 7010
7011
7012
Fortune 7013 Heuristics Service EndpointAn endpoint offering fortune 7014 heuristics services MUST adhere to 7015 specifications in this section. 7016 A service MAY implement multiple divination services 7017 based on 7018 different divination methods, such as the digital oracle shown 7019 in . 7020
7021 Dimensional Eye, a digital oracle that communicates through one 7022 button 7023 7059
7060
Service Specification RequestTo retrieve 7062 capabilities and parameters of an endpoint complying with 7063 this specification, a service specification JSON object is returned. 7064 An empty SEEK request with the "application/json" request type 7065 MUST be sent to this endpoint to retrieve the service 7066 specification that describes parameters accepted by this endpoint. 7067 Two examples of such a response are given below. 7068
7069 7101
7102
7103 7137
7138
Service Specification ObjectA service 7140 specification object MUST contain the following 7141 members. 7142
7143
7144 description 7145
7146
(string) A short, human-readable summary of the fortune heuristic 7147 service at this endpoint. This SHOULD be a stable 7148 reference.
7149
7150 details 7151
7152
(URI, optional) A URI reference that provides further details for 7153 human consumption, such as API documentation that includes details of 7154 parameters accepted or response states.
7155
7156 parameters 7157
7158
(object, mandatory) An object that specifies what parameters 7159 are accepted by this endpoint. Each parameter key within this object 7160 specifies an accepted parameter name, and its value is a parameter 7161 specification object, which is described below.
7162
7163 A parameter specification object SHOULD contain the 7164 following 7165 members: 7166
7167
7168 type 7169
7170
(string, optional) The value type accepted by this parameter. 7171 Value 7172 types are described in this document. This member is mutually 7173 exclusive with values.
7174
7175 description 7176
7177
(string, mandatory) The purpose of this parameter.
7178
7179 values 7180
7181
(object, optional) The accepted values of this parameter, unlisted 7182 values SHOULD not be accepted by the parameter. Each key 7183 within 7184 this object specifies an accepted value, and its value provides a 7185 description of the purpose of the value.
7186
7187
Fortune 7188 Heuristics Report Request and Response
Fortune Heuristics 7190 Report RequestA request using the HTTP "DIVINE" method and the 7191 "application/json" 7192 type MUST be sent to the fortune heuristic endpoint to 7193 retrieve 7194 results for a fortune heuristic query. 7195 The request made MUST conform to the specifications of 7196 the 7197 endpoint, as retrieved via the "SEEK" method described in 7198 . 7199 An example of a request is provided below. 7200
7201 7214
7215
Fortune Heuristics Report ResponseA fortune 7217 heuristic query using the "DIVINE" method triggers a 7218 response that contains a fortune heuristics report. 7219 A successful response returns a JSON object that MUST 7220 conform 7221 to the object structure described in this section. 7222 A report object SHOULD contain the following 7223 members: 7224
7225
7226 type 7227
7228
(URI, mandatory) A URI that defines the type of the report located 7229 at the report key of this object.
7230
7231 report 7232
7233
(object, mandatory) An object that contains two keys, 7234 intervals 7235 and events. The intervals object contains an array of 7236 interval 7237 objects that matches the demanded intervals in the request within 7238 the target date range. 7239 The events object contains an array of significant event 7240 objects 7241 within the target date range.
7242
7243 An example of a response is provided below. 7244
7245 7311
7312 Fortune heuristic reports are created by a divination output that 7313 MAY requires quantitative interpretation. A sample 7314 representation of 7315 interpreting a graphical divination output is provided in 7316 . 7317
7318 Forty-nine yarrow sticks reveals a mystical message on 7319 fortune 7320 7348
7349
Report Interval ObjectThe intervals 7351 value of a report object contains a number of report 7352 intervals — each representing a non-overlapping period 7353 of the 7354 selected interval length. When all of these intervals are put 7355 together, the combined period MUST fully cover the 7356 requested 7357 report target period. 7358 An example interval object is shown below. 7359
7360 7387
7388 An interval object MUST contain the following 7389 members: 7390
7391
7392 dateStart 7393
7394
(datetime, mandatory) This value specifies the start of the period 7395 which this interval object applies to.
7396
7397 dateEnd 7398
7399
(datetime, mandatory) This value specifies the end of the period 7400 which this interval object applies to.
7401
7402 In the given example, the categories key is an 7403 implementation 7404 specific object that details heuristic results returned by the 7405 selected algorithm. This MAY differ in different 7406 algorithms.
7407
Report Events ObjectThe events value of 7409 a report object contains a number of event 7410 objects. Each event object represents an event relevant to the 7411 calculation of fortune heuristics during a target report period. These 7412 events MAY be of variable time lengths, and 7413 MAY be overlapping 7414 amongst each other. 7415 The following example demonstrates two event objects the service 7416 determines relevant to a user’s query. 7417
7418 7435
7436 Similar to an interval object, an event object MUST 7437 contain the 7438 following members: 7439
7440
7441 dateStart 7442
7443
(datetime, mandatory) This value specifies the start of the period 7444 described by the event.
7445
7446 dateEnd 7447
7448
(datetime, mandatory) This value specifies the end of the period 7449 described by the event.
7450
7451 In the given example, the keys description and 7452 recommendation 7453 are implementation-specific details. This MAY differ in 7454 different 7455 algorithms.
7456
Report 7457 Generation ErrorsThis specification makes use of normal HTTP 7458 error codes with the 7459 following extensions. 7460 Errors MUST be returned using the Problem JSON 7461 Structure as 7462 accordance with . 7463
7464
422 Unprocessable Entity
7465
For example, a malformed date-time parameter, or an illogical 7466 input, 7467 such as when the subject’s birthday occurs after the report target 7468 date period.
7469
473 Beyond Existing Capability
7470
The service determines that the outcome is too difficult to 7471 predict. 7472 For example, in the case where the calculation is too complex to 7473 complete in a certain time period. The service SHOULD 7474 issue this 7475 response code to indicate that the client should not try the same 7476 request again.
7477
474 Outcome Impossible
7478
The service determines that the outcome is impossible. For 7479 example, 7480 when the algorithm determines that the subject will have deceased 7481 before the start of the requested target period.
7482
7483
7484 Security Considerations 7485
    7486
  • TLS and authenticated HTTP requests 7487 should be used to 7488 protect the DIVINE request and responses due to the personal nature 7489 of information transmitted.
    • 7490
  • A client SHOULD verify the identity of the server 7491 on every 7492 request to prevent impersonation or man-in-the-middle attacks, as data 7493 transmitted to and from the server is sensitive information, and at 7494 times critical information to the user.
    • 7495
  • Synchronization of client and server time MUST be 7496 well-considered in the implementation of this specification. A 7497 mismatch of client and server time MAY lead to algorithm 7498 miscalculations that can cause mistaken choices of a user that depends 7499 on the reliability of this system.
    • 7500
7501
7502
7503 IANA Considerations 7504
Well-Known URI RegistrationsThis document 7506 defines a well-known URI using the registration 7507 procedure and template from . 7509
"fortune" Well-Known URI Registration
7511
URI suffix
7512
fortune
7513
Change controller
7514
IETF
7515
Specification document(s)
7516
This document
7517
Related information
7518
N/A.
7519
7520 7522
7523
7524 7525 7526 Normative References 7527 7530 7533 7536 7539 7542 7545 7548 7549 7550 Informative References 7551 7553 7554 ISO/DIS 8601-1:2018, Data elements and interchange 7555 formats -- Information interchange -- Representation of dates 7556 and times -- Part 1: Basic rules 7557 7558 ISO/IEC 7559
7560 http://www.iso.org 7561
7562 7563 7564 7565 7566 7567 7570 7573 7574
AcknowledgementsThe authors thank the following 7576 individuals for their valuable 7577 feedback on this specification, and commend them for making fortune 7578 heuristics more accessible for the benefit of mankind. 7580 7582
7583 7584 7585 7587 Appendix B. Acknowledgements 7589 The authors would like to thank the following persons for their 7590 valuable advice and input. 7592 o Adrian Farrel for his comprehensive review of the document and 7593 numerous beneficial suggestions. 7595 Authors' Addresses 7597 Ronald Henry Tse 7598 Ribose 7599 Suite 1111, 1 Pedder Street 7600 Central, Hong Kong 7601 Hong Kong 7603 Email: ronald.tse@ribose.com 7604 URI: https://www.ribose.com 7606 Nick Nicholas 7607 Ribose 7608 Australia 7610 Email: nick.nicholas@ribose.com 7611 URI: https://www.ribose.com 7612 Jeffrey Lau 7613 Ribose 7614 Suite 1111, 1 Pedder Street 7615 Central, Hong Kong 7616 Hong Kong 7618 Email: jeffrey.lau@ribose.com 7619 URI: https://www.ribose.com 7621 Paolo Brasolin 7622 Ribose 7623 Italy 7625 Email: paolo.brasolin@ribose.com 7626 URI: https://www.ribose.com