idnits 2.17.1 draft-ribose-asciirfc-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 18, 2018) is 2198 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Orb' is mentioned on line 4866, but not defined -- Looks like a reference, but probably isn't: '124' on line 4866 -- Looks like a reference, but probably isn't: '135' on line 4866 == Unused Reference: 'I-D.camelot-holy-grenade' is defined on line 3630, 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 (-05) exists of draft-wu-netmod-yang-xml-doc-conventions-00 -- Obsolete informational reference (is this intentional?): RFC 7749 (Obsoleted by RFC 7991) Summary: 0 errors (**), 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 20, 2018 P. Brasolin 6 Ribose 7 April 18, 2018 9 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc 10 draft-ribose-asciirfc-08 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 20, 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 2.1. Terms and Definitions . . . . . . . . . . . . . . . . . . 6 67 2.2. Wrapping Lines in Documentation Examples . . . . . . . . 6 68 3. Document Structure and Syntax . . . . . . . . . . . . . . . . 7 69 3.1. Unsupported features compared with Asciidoctor syntax . . 8 70 3.2. Mapping To RFC XML syntax . . . . . . . . . . . . . . . . 8 71 3.3. Example Illustrations . . . . . . . . . . . . . . . . . . 9 72 3.4. Simple Illustration . . . . . . . . . . . . . . . . . . . 10 73 4. Header And Document Attributes . . . . . . . . . . . . . . . 28 74 4.1. Title And Basic Attributes . . . . . . . . . . . . . . . 28 75 4.2. Detailed Author Information . . . . . . . . . . . . . . . 30 76 4.3. XML Processing Information . . . . . . . . . . . . . . . 34 77 4.4. AsciiRFC-specific Document Attributes . . . . . . . . . . 35 78 5. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 38 79 6. Sections and Paragraphs . . . . . . . . . . . . . . . . . . . 39 80 7. Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 81 8. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 82 8.1. Basic Lists . . . . . . . . . . . . . . . . . . . . . . . 47 83 8.2. List Continuation . . . . . . . . . . . . . . . . . . . . 52 84 9. Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . . 55 85 10. Notes And Asides . . . . . . . . . . . . . . . . . . . . . . 56 86 11. Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 87 12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . . 62 88 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts . 62 89 12.2. Formatting BCP 14 Keywords . . . . . . . . . . . . . . . 63 90 12.3. Escaping AsciiRFC Syntax . . . . . . . . . . . . . . . . 64 91 13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 92 14. Cross-References . . . . . . . . . . . . . . . . . . . . . . 66 93 14.1. Basic Referencing . . . . . . . . . . . . . . . . . . . 66 94 14.2. Referencing With Attributes . . . . . . . . . . . . . . 67 95 14.3. Indexing . . . . . . . . . . . . . . . . . . . . . . . . 68 96 15. Inclusions . . . . . . . . . . . . . . . . . . . . . . . . . 69 97 16. Encoding and Entities . . . . . . . . . . . . . . . . . . . . 70 98 17. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 72 99 17.1. Using Raw RFC XML . . . . . . . . . . . . . . . . . . . 72 100 17.2. Preprocessing Using "asciidoctor-bibliography" . . . . . 77 101 18. RFC XML features not supported in Asciidoctor . . . . . . . . 79 102 19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 79 103 19.1. Using the "rfc-asciirfc-minimal" template . . . . . . . 80 104 19.2. Installing AsciiRFC Backend Processors . . . . . . . . . 80 105 19.3. Iterating AsciiRFC Content . . . . . . . . . . . . . . . 80 106 20. Security Considerations . . . . . . . . . . . . . . . . . . . 81 107 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 81 108 22. References . . . . . . . . . . . . . . . . . . . . . . . . . 81 109 22.1. Normative References . . . . . . . . . . . . . . . . . . 81 110 22.2. Informative References . . . . . . . . . . . . . . . . . 81 111 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 85 112 A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" . . . . 85 113 A.1.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 85 114 A.1.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 93 115 A.2. Example 2: "The Holy Hand Grenade of Antioch" . . . . . . 98 116 A.2.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 98 117 A.2.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 115 118 A.3. Example 3: "An API For Calendar-Based Fortune Heuristics 119 Services" in AsciiRFC . . . . . . . . . . . . . . . . . . 133 120 A.3.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 134 121 A.4. Rendered as RFC XML v3 . . . . . . . . . . . . . . . . . 153 122 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 170 123 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 170 125 1. Introduction 127 This document describes a markup language called "AsciiRFC", 128 developed specifically for the purpose of generating RFC XML 129 document, based on Asciidoctor syntax. AsciiRFC can be used to 130 generate compliant RFC XML v2 and v3 documents through the usage of 131 an open source, MIT-licensed Ruby gem called "asciidoctor-rfc" 132 written by the authors [asciidoctor-rfc]. 134 1.1. Designed for authoring RFCs and Internet-Drafts 136 Internet-Drafts and RFCs intended for publication submission to the 137 IETF can be written in a multitude of formats today, including: 139 o XML: RFC XML v2 [RFC7749] and v3 [RFC7991] 141 o nroff: through [NroffEdit] 142 o Microsoft Word: through usage of [RFC5385] 144 o Lyx: through [lyx2rfc] 146 o Pandoc: [RFC7328], through [pandoc2rfc] or [draftr] 148 o Kramdown: through [kramdown-rfc2629] 150 o mmark: through [mmark] 152 Interestingly, the last three are Markdown [RFC7763] variants. 154 As specified in [RFC7990], the IETF intends for the canonical format 155 of RFCs to transition from plain-text ASCII to RFC XML v3 [RFC7991]. 156 While plain-text will continue to be accepted from authors by the 157 IETF, at least in the short- to medium-term, XML will be preferred 158 for submission, and any plain-text submissions will need to be 159 converted to RFC XML v3. 161 While this need is already met for RFC XML v2 [RFC7749] by the tools 162 specified above, the transition to RFC XML v3 [RFC7991] places added 163 onus on authors to generate compliant XML. 165 1.2. Relationship between AsciiRFC, AsciiDoc and Asciidoctor 167 [AsciiDoc] is a lightweight markup language and an alternative to 168 Markdown, with features that make it attractive as a markup language 169 for RFC with XML output. 171 [Asciidoctor] is an open source, MIT-licensed Ruby implementation of 172 [AsciiDoc] that provides an enhancement of the original AsciiDoc 173 markup language. 175 The variant of AsciiDoc syntax accepted by [Asciidoctor] is hereafter 176 called "Asciidoctor syntax". 178 AsciiRFC, as described in this document, is an AsciiDoc variant 179 developed on Asciidoctor syntax, created for the purpose of 180 generating RFC XML documents. 182 1.3. Comparison with RFC XML tools based on Markdown variants 184 Section 1.2 of [RFC7764] famously states that "there is no such thing 185 as 'invalid' Markdown, there is no standard demanding adherence to 186 the Markdown syntax, and there is no governing body that guides or 187 impedes its development." While there are contexts where that 188 flexibility is useful, the authoring of RFCs does have a standard and 189 a governing body, and there is such a thing as invalid RFC XML. A 190 more rigorous and extensible counterpart to Markdown, which still 191 preserves its basic approach to formatting, can generate RFC XML that 192 encompasses a fuller subset of the specification, and preempts 193 malformed RFC XML output. The proposed markup language and 194 associated Ruby gem has several advantages that we believe make it 195 worth considering as an approach to generating RFC XML. 197 o AsciiDoc was designed from the beginning as a publishing language: 198 it was initially intended as a plain-text alternative to the 199 DocBook XML schema. For that reason, Asciidoctor natively 200 supports the full range of formatting required by RFC XML 201 (including notes, tables, bibliographies, source-code blocks, and 202 definition lists), without resorting to embedded HTML or Markdown 203 "flavours". 205 o AsciiRFC covers the full range of elements in RFC XML v2 and RFC 206 XML v3. 208 o AsciiDoc in its Ruby-based Asciidoctor implementation is 209 extensible, with a well-defined API. (Extensions have been 210 harnessed to deal with bibliographic preprocessing for AsciiRFC.) 212 o AsciiRFC allows granular control of rendering, including user- 213 specified attributes of text blocks. 215 o The Asciidoctor implementation allows document inclusion, for 216 managing large-scale documentation projects. 218 o AsciiRFC allows granular control of permutations of block nesting, 219 such as source code within lists or definition lists within 220 unordered lists. 222 o As a more formal counterpart to Markdown, AsciiDoc is well-suited 223 to generating XML that needs to conform to a specified schema. 224 The asciidoctor-rfc Ruby gem developed around AsciiDoc validates 225 its RFC XML output against the RelaxNG schema defined for RFC XML, 226 and reports any issues to the end user. 228 o The asciidoctor-rfc Ruby gem incorporates validation not only of 229 the XML structure of the standard, but also of the IETF workgroups 230 it mentions against the latest listing online, and the 231 bibliographic entries for RFC and other standards registered on 232 . The gem also dynamically 233 fetches bibliographic entries from the xml2rfc site, and uses them 234 to populate the RFC XML document. 236 As with Markdown, there is a wide range of tools that can render 237 AsciiDoc; so AsciiRFC drafts of RFC documents can be previewed and 238 accessed without depending on the RFC tools ecosystem. Our 239 realisation of RFC XML in AsciiRFC has aimed to ensure that, as much 240 as possible, the markup language can be can be processed by generic 241 Asciidoctor tools. 243 The only exception to this as an add-on is the optional bibliography 244 module, which allows bibliographies to be assembled on the fly based 245 on citations in a document: see Section 17.2. 247 2. Conventions Used in This Document 249 2.1. Terms and Definitions 251 The following terms and definitions apply to this document: 253 AsciiDoc 254 The AsciiDoc markup language generically, as described in 255 [AsciiDoc]. 257 Asciidoctor syntax 258 The enhanced AsciiDoc syntax implemented by the [Asciidoctor] Ruby 259 gem. 261 AsciiRFC 262 The AsciiDoc syntax developed for the purpose of generating RFC 263 XML document based on Asciidoctor syntax, as described in this 264 document. 266 2.2. Wrapping Lines in Documentation Examples 268 This document contains a number of examples as fragments of XML. In 269 some cases, the examples contain URLs that are over 72 characters 270 long and so need to be wrapped for presentation in this document even 271 though they would not need to be wrapped in the actual source XML. 273 This document adopts a policy similar to that described in 274 [I-D.wu-netmod-yang-xml-doc-conventions] to denote line wraps. When 275 an XML example contains a URL, that URL is always included in double- 276 quotes. If the URL would extend beyond 72 characters, the line is 277 wrapped and the wrap is indicated with a backslash ("\"). The 278 backslash appears without any additional space before the backslash 279 and with no further characters after the backslash. 281 For example, the following XML... 283 286 ...may be presented as 288 292 3. Document Structure and Syntax 294 AsciiRFC consists of a subset of Asciidoctor syntax with the addition 295 of bibliographic macros (Section 17.2). Asciidoctor syntax is 296 presented in the Asciidoctor user manual [Asciidoctor-Manual]. 298 AsciiRFC syntax consists of: 300 o A document header, containing a title, a list of authors, and 301 document attributes in lines prefixed with ":". 303 o An optional document preamble, separated from the document header 304 by a blank line, and not containing any section titles. 306 o A number of sections, set off by a section title (a line prefixed 307 with two or more "=".) 309 A section may contain: 311 o Other sections, whose level of nesting is indicated by the number 312 of "=" in their header. 314 o Blocks of text. Blocks can have metadata (including a title, an 315 anchor for cross-references, and attributes.) 317 Blocks can be: 319 o Paragraphs, which are terminated by blank lines. 321 o Lists. List items are by default paragraphs, but can span over 322 multiple paragraphs. 324 o Delimited blocks (with a line delimiter on either side of them); 325 these include tables, notes, sidebars, source code, block quotes, 326 examples, and unprocessed content (e.g. raw XML). Delimited 327 blocks contain by default one or more paragraphs. 329 o List items can contain other blocks, including both nested lists 330 and delimited blocks. 332 o Some delimited blocks can contain other delimited blocks; for 333 example, examples can contain source code as well as discussion in 334 paragraphs. 336 o Blocks of text consist of inline text, which itself can contain 337 markup. 339 Inline markup includes: 341 o Text formatting: Bold, italic, superscript, subscript, monospace. 343 o Markup macros: the "bcp14" and "comment" macros. (Asciidoctor 344 syntax supports custom markup macros.) 346 o URLs, including display text to render. 348 o Inline anchors. 350 o Cross-references to anchors (IDs of blocks or spans of text), 351 including display text to render. 353 o Images: SVG only, as specified in [RFC7996]. 355 o Index terms. 357 3.1. Unsupported features compared with Asciidoctor syntax 359 Several features from Asciidoctor are not supported within AsciiRFC 360 due to the lack of support within RFC XML, including: 362 o Audio and video files are not supported in AsciiRFC as today's RFC 363 XML structure does not support audio or video. 365 o Equations are not supported as there is no current RFC XML 366 equivalent. Asciidoctor provides native support for [AsciiMathML] 367 and [TeX-LaTeX], via the [MathJax] tool. 369 o Footnotes are not supported in AsciiRFC as there is no equivalent 370 semantic representation in RFC XML. 372 These carved out features can be easily supported by AsciiRFC once 373 RFC XML allows these elements. 375 3.2. Mapping To RFC XML syntax 377 The Asciidoctor syntax document structure aligns with both the RFC 378 XML v2 and the RFC XML v3 structure. In the following, RFC XML v3 379 equivalences are given to the basic Asciidoctor structure. 381 Header 382 "" attributes, most "front" elements. 384 Preamble 385 "front/abstract" and "front/note". 387 Sections 388 "middle/section" elements. 390 Sections with bibliography style attribute 391 "back/references" elements. 393 Sections with appendix style attribute 394 "back/section" elements. 396 Paragraphs 397 "t" elements. 399 Lists 400 "ul", "ol", "dl" elements. 402 Delimited blocks 403 "artwork", "aside", "blockquote", "figure", "note", "sourcecode", 404 "table". 406 Inline markup 407 "bcp14", "br", "cref", "em", "eref", "iref", "relref", "strong", 408 "sub", "sup", "tt", "xref". 410 Full details of the mapping of AsciiRFC elements to RFC XML v2 and v3 411 elements, and of how to convert AsciiRFC documents to RFC XML, are 412 given in the documentation of [asciidoctor-rfc]. 414 3.3. Example Illustrations 416 This document utilizes example documents provided in Appendix A for 417 demonstration of AsciiRFC syntax and usage. The source files and 418 published versions (at the IETF Datatracker) of these example 419 documents are available in Appendix A. 421 o "A Minimal Internet-Draft In AsciiRFC" Appendix A.1.1 423 o "The Holy Hand Grenade of Antioch" Appendix A.2.1 425 o "An API For Calendar-Based Fortune Heuristics Services" 426 Appendix A.3.1 428 3.4. Simple Illustration 430 This section gives an overview of how to create an RFC XML document 431 in AsciiRFC, with some pitfalls to be aware of. 433 Illustrations are in RFC XML v3 and RFC XML v2. 435 A sample AsciiRFC document is provided in Figure 1, together with its 436 corresponding rendering in: 438 o RFC XML v3 (Figure 2) 440 o RFC XML v2 (Figure 3) 442 443 = A Minimal Internet-Draft In AsciiRFC 444 :doctype: internet-draft 445 :name: draft-asciirfc-minimal-02 446 :abbrev: AsciiRFC Example 447 :status: informational 448 :ipr: trust200902 449 :submissionType: individual 450 :area: Internet 451 :intended-series: full-standard 452 :revdate: 2018-04-12T00:00:00Z 453 :fullname: Josiah Stinkney Carberry 454 :lastname: Carberry 455 :forename_initials: J. S. 456 :organization: Brown University 457 :phone: +1 401 863 1000 458 :street: Box K, 69 Brown Street 459 :city: Providence 460 :code: 02912 461 :country: United States of America 462 :uri: https://www.brown.edu 463 :email: josiah.carberry@ribose.com 464 :fullname_2: Truman Grayson 465 :lastname_2: Grayson 466 :forename_initials_2: T. 467 :organization_2: Brown University 468 :phone_2: +1 401 863 1000 469 :street_2: Box G, 69 Brown Street 470 :city_2: Providence 471 :code_2: 02912 472 :country_2: United States of America 473 :uri_2: https://www.brown.edu 474 :email_2: truman.grayson@ribose.com 476 [abstract] 478 This document provides a template on how to author (or migrate!) 479 a new Internet-Draft / RFC in the AsciiRFC format. 481 This template requires usage of the `asciidoctor-rfc` Ruby gem. 483 [#introduction] 484 == Introduction 486 AsciiRFC <> is an extremely simple way to 487 author Internet-Drafts and RFCs without needing to manually 488 craft RFC XML conforming to <>. 490 This is a template specifically made for authors to easily 491 start with creating an Internet-Draft conforming to <> 492 and submittable to the IETF datatracker. 494 [#conventions] 495 == Terms and Definitions 497 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 498 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 499 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this 500 document are to be interpreted as described in BCP 14 501 <> <> when, and only when, they appear in 502 all capitals, as shown here. 504 This document also refers to the following terms and 505 definitions: 507 AsciiRFC:: 508 an AsciiDoc-derived syntax used for authoring RFCs and 509 Internet-Drafts, as defined in <>. 511 [#symbols] 512 == Symbols And Abbreviations 514 ADRFC:: 515 abbreviated form of AsciiRFC 517 [#security] 518 == Security Considerations 520 Any security considerations should be placed here. 522 As described in <
> (here's how you refer a local anchor), 523 local tools have to be installed before the document template 524 can be built. 526 Running of these local tools *MAY* produce unintended side 527 effects that impact security. 529 [#iana] 530 == IANA Considerations 532 This document does not require any action by IANA. 534 But if it does, such as proposing changes to IANA registries, 535 please include them here. 537 [bibliography] 538 == Normative References 540 //bibliography::norm[] 541 ++++ 543 545 546 Key words for use in RFCs to Indicate Requirement 547 Levels 548 549 550 551 552 553 In many standards track documents several words are 554 used to signify the requirements in the specification. 555 These words are often capitalized. This document defines 556 these words as they should be interpreted in IETF 557 documents. This document specifies an Internet Best 558 Current Practices for the Internet Community, and 559 requests discussion and suggestions for improvements. 560 561 562 563 564 565 566 568 570 571 The "xml2rfc" Version 3 Vocabulary 572 573 574 575 576 577 This document defines the "xml2rfc" 578 version 3 vocabulary: an XML-based language used for 579 writing RFCs and Internet-Drafts. It is heavily derived 580 from the version 2 vocabulary that is also under 581 discussion. This document obsoletes the v2 grammar 582 described in RFC 7749. 583 584 585 586 587 589 591 592 Ambiguity of Uppercase vs Lowercase in RFC 2119 593 Key Words 594 595 596 597 598 599 RFC 2119 specifies common key words that may be 600 used in protocol specifications. This document aims to 601 reduce the ambiguity by clarifying that only UPPERCASE 602 usage of the key words have the defined special 603 meanings. 604 605 606 607 608 609 610 ++++ 612 [bibliography] 613 == Informative References 615 //bibliography::info[] 616 ++++ 618 620 621 IETF Trust Legal Provisions (TLP) 622 623 IETF 624 625 626 627 629 630 631 RNP: A C library approach to OpenPGP 632 633 Ribose Inc. 634
635 636 Suite 1111, 1 Pedder Street 637 Central 638 Hong Kong 639 Hong Kong 640 641 open.source@ribose.com 642 https://www.ribose.com 643
644 645 646 647 649 650 651 652 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 This document describes an AsciiDoc syntax 669 extension called AsciiRFC, designed for authoring IETF 670 Internet-Drafts and RFCs. AsciiDoc is a human readable document 671 markup language which affords more granular control over markup 672 than comparable schemes such as Markdown. The AsciiRFC syntax 673 is designed to allow the author to entirely focus on text, 674 providing the full power of the resulting RFC XML through the 675 AsciiDoc language, while abstracting away the need to manually 676 edit XML, including references. This document itself was 677 written and generated into RFC XML v2 (RFC7749) and RFC XML v3 678 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC 679 generator. 680 681 682 683 685 687 689 690 Rights Contributors Provide to the IETF Trust 691 693 694 695 697 698 699 700 The IETF policies about rights in Contributions 701 to the IETF are designed to ensure that such Contributions 702 can be made available to the IETF and Internet communities 703 while permitting the authors to retain as many rights as 704 possible. This memo details the IETF policies on rights in 705 Contributions to the IETF. It also describes the 706 objectives that the policies are designed to meet. This 707 memo obsoletes RFCs 3978 and 4748 and, with BCP 79 and 708 RFC 5377, replaces Section 10 of RFC 2026. This document 709 specifies an Internet Best Current Practices for the 710 Internet Community, and requests discussion and 711 suggestions for improvements. 712 713 714 715 716 718 720 721 The OCB Authenticated-Encryption Algorithm 722 723 724 725 726 727 728 729 This document specifies OCB, a shared-key 730 blockcipher-based encryption scheme that provides 731 confidentiality and authenticity for plaintexts and 732 authenticity for associated data. This document is a product 733 of the Crypto Forum Research Group (CFRG). 734 735 736 737 738 ++++ 740 [appendix] 741 [#appendix-a] 742 == Examples 744 === Example 1 746 Here's an example of a properly wrapped code snippet in 747 accordance with rules specified in <>. 749 [source,json] 750 ---- 751 752 { 753 "code": { 754 "encoding": "ascii", 755 "type": "rfc", 756 "authors": [ "Josiah Carberry", "Truman Grayson" ] 757 } 758 } 759 760 ---- 762 [#acknowledgements] 763 == Acknowledgements 765 The authors would like to thank their families. 766 768 Figure 1: Sample Internet-Draft in AsciiRFC 770 The first block of text, from "= Template For Writing An Internet- 771 Draft In AsciiRFC" through to ":email_2: thomas.kandell@brown.edu", 772 is the document header. It contains a title in the first line, an 773 author attribution ("Josiah Carberry; Thomas Kandell"), and then a 774 set of document attributes, conveying information about the document 775 as well as information about its authors. This information ends up 776 in RFC XML either as attributes of the root "rfc" tag, elements of 777 the "front" tag, or processing instructions. 779 The following blocks of text, up until the first section header ("== 780 Introduction"), are the document preamble. They are treated by the 781 document converter as containing the document abstract ("abstract"), 782 followed by any notes if present. 784 Section headers delimit the sections of the main body of the 785 document, starting with "== Introduction". The document converter 786 treats the first section of the document as the start of the "middle" 787 section in RFC XML. The first section header is followed by a 788 paragraph, and other sections and paragraphs. The number of "=" 789 signs can be one higher than that of the preceding section header, 790 which indicates that they are subsections of that section; so "=== 791 Operators" is a subsection of the preceding "== Symbols And 792 Abbreviations". 794 The paragraphs contain some inline formatting (e.g. boldface: 795 "*MUST*", monospace: "`type`"), and sections can also contain blocks 796 other than normal paragraphs; the section "== Operators", for 797 example, contains a definition list (whose terms are delimited by 798 "::"), and the subsection "=== Example 1" contains a code snippet 799 (delimited by "----", and tagged with the style attribute 800 "[source,json]", indicating that this is a JSON sourcecode listing). 801 The document can also include comments ("//" for inline, "////" for 802 blocks), which are not rendered when the document is processed. 804 The introductory section in this example contains a citation of a 805 reference, which in this version of AsciiRFC is treated identically 806 to a cross-reference ("<>") -- the crossreference being to 807 the references section of the document. Sections and blocks of texts 808 within the document can also be the target of crossreferences; for 809 example, the section header "=== Operators" is preceded by the anchor 810 "[#operators]", and that anchor is already referenced in the section 811 "== Security Considerations". 813 The third last and second last section are tagged with the style 814 attribute "[bibliography]", which identifies them as references 815 containers; the document converter accordingly inserts them into the 816 "back" element under RFC XML. The contents of the references 817 sections are in this instance raw XML, delimited as a passthrough 818 block (with "++++"), which the converter does not alter. 820 The final section is tagged with the style attribute "[appendix]", 821 and is treated as such. 823 The RFC XML v3 document generated from this AsciiRFC document is: 825 826 827 828 829 830 831 832 833 834 835 836 838 839 A Minimal Internet-Draft In 840 AsciiRFC 841 843 845 847 Brown University 848
849 850 Box K, 69 Brown Street 851 Providence 852 02912 853 United States of America 854 855 +1 401 863 1000 856 josiah.carberry@ribose.com 857 https://www.brown.edu 858
859 860 861 Brown University 862
863 864 Box G, 69 Brown Street 865 Providence 866 02912 867 United States of America 868 869 +1 401 863 1000 870 truman.grayson@ribose.com 871 https://www.brown.edu 872
873 874 875 Internet 877 This document provides a template on how to author (or 878 migrate!) 879 a new Internet-Draft / RFC in the AsciiRFC format. 880 This template requires usage of the asciidoctor-rfc Ruby 881 gem. 882 883
IntroductionAsciiRFC is an extremely simple way to 886 author Internet-Drafts and RFCs without needing to manually 887 craft RFC XML conforming to . 888 This is a template specifically made for authors to easily 889 start with creating an Internet-Draft conforming to 891 and submittable to the IETF datatracker.
892
Terms and 893 DefinitionsThe key words "MUST", "MUST 894 NOT", "REQUIRED", "SHALL", 895 "SHALL NOT", "SHOULD", "SHOULD 896 NOT", "RECOMMENDED", 897 "NOT RECOMMENDED", "MAY", and 898 "OPTIONAL" in this 899 document are to be interpreted as described in BCP 14 900 when, and only when, 901 they appear in 902 all capitals, as shown here. 903 This document also refers to the following terms and 904 definitions: 905
906
AsciiRFC
907
an AsciiDoc-derived syntax used for authoring RFCs and 908 Internet-Drafts, as defined in .
910
911
912 Symbols And Abbreviations 913
914
ADRFC
915
abbreviated form of AsciiRFC
916
917
918
Main 919 contentThis is where you place the main content, and the 920 following 921 serves as a placeholder for your text. 922 Subsections are used here for demonstration purposes. 923
Getting 924 startedThe AsciiRFC and RFC toolchains MUST be 925 available locally to 926 build this document template. 927
AsciiRFC 928 toolchainYou will need to have: 929
    930
  • Ruby: for running the AsciiRFC toolchain
    • 931
  • asciidoctor-rfc gem: for converting AsciiRFC into XML RFC 932 (v2 or v3)
    • 933
934
XML RFC 935 toolchainYou will need to have: 936
    937
  • Python: for running xml2rfc
    • 938
  • xml2rfc: for converting RFC XML (v2 or v3) into TXT
    • 939
  • idnits: for submission preflight
    • 940
941
942 Referencing external content 943
    944
  • This is a published RFC
    • 945
  • This is an Internet-Draft
    • 947
  • This is an external reference
    • 948
949
950
951 Code snippets 952 Code snippets should be wrapped with <CODE BEGINS> 953 and 954 <CODE ENDS> blocks, as required by the IETF Trust Legal 955 Provisions (TLP) specified in . 957
958
Security 959 ConsiderationsAny security considerations should be placed 960 here. 961 As described in (here’s how you refer a 962 local anchor), 963 local tools have to be installed before the document template 964 can be built. 965 Running of these local tools MAY produce unintended 966 side 967 effects that impact security.
968
IANA 969 ConsiderationsThis document does not require any action by 970 IANA. 971 But if it does, such as proposing changes to IANA registries, 972 please include them here.
973 974 975 Normative References 976 980 984 988 989 990 Informative References 991 993 994 IETF Trust Legal Provisions (TLP) 995 996 IETF 997 998 999 1000 1001 1002 1003 RNP: A C library approach to OpenPGP 1004 1005 Ribose Inc. 1006
1007 1008 Suite 1111, 1 Pedder Street 1009 Central 1010 Hong Kong 1011 Hong Kong 1012 1013 open.source@ribose.com 1014 https://www.ribose.com 1015
1016 1017 1018 1019 1020 1024 1028 1032 1033
1034 Examples 1035
Example 1036 1Here’s an example of a properly wrapped code snippet in 1037 accordance with rules specified in . 1038
1039 1041 { 1042 "code": { 1043 "encoding": "ascii", 1044 "type": "rfc", 1045 "authors": [ "Josiah Carberry", "Truman Grayson" ] 1046 } 1047 } 1048 1049 ]]> 1050
1051
1052
1053 Acknowledgements 1054 The authors would like to thank their families. 1055
1056 1057 1058 1060 Figure 2: Sample Internet-Draft In AsciiRFC, Output In RFC XML v3 1061 Format 1063 Some default processing instructions have already been prefixed to 1064 the XML. 1066 Our AsciiRFC converter can also generate RFC XML v2 from the same 1067 source AsciiRFC, as shown in Figure 3. Output in RFC XML v2 is not 1068 extensively described in this document. 1070 1071 1072 1073 1077 1080 1083 1086 1089 1092 ]> 1093 1094 1095 1096 1097 1098 1099 1100 1102 1103 A Minimal Internet-Draft In 1104 AsciiRFC 1105 1107 Brown University 1108
1109 1110 Box K, 69 Brown Street 1111 Providence 1112 02912 1113 United States of America 1114 1115 +1 401 863 1000 1116 josiah.carberry@ribose.com 1117 https://www.brown.edu 1118
1119 1120 1121 Brown University 1122
1123 1124 Box G, 69 Brown Street 1125 Providence 1126 02912 1127 United States of America 1128 1129 +1 401 863 1000 1130 truman.grayson@ribose.com 1131 https://www.brown.edu 1132
1133 1134 1135 Internet 1137 This document provides a template on how to author (or 1138 migrate!) 1139 a new Internet-Draft / RFC in the AsciiRFC format. 1140 This template requires usage of the asciidoctor-rfc Ruby gem. 1142 1143
AsciiRFC is an extremely simple way to 1145 author Internet-Drafts and RFCs without needing to manually 1146 craft RFC XML conforming to . 1147 This is a template specifically made for authors to easily 1148 start with creating an Internet-Draft conforming to 1150 and submittable to the IETF datatracker.
1151
The key 1152 words "MUST", "MUST 1153 NOT", "REQUIRED", "SHALL", 1155 "SHALL NOT", "SHOULD", "SHOULD 1157 NOT", "RECOMMENDED", 1158 "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 1161 document are to be interpreted as described in BCP 14 1162 when, and only when, 1163 they appear in 1164 all capitals, as shown here. 1165 This document also refers to the following terms and 1166 definitions: 1167 1168 1169 an AsciiDoc-derived 1170 syntax used for authoring RFCs and 1171 Internet-Drafts, as defined in . 1173 1174
1175
1176 1177 1178 abbreviated form of 1179 AsciiRFC 1180 1181 1182
1183
This is where you place 1184 the main content, and the following 1185 serves as a placeholder for your text. 1186 Subsections are used here for demonstration purposes. 1187
The 1188 AsciiRFC and RFC toolchains MUST be 1189 available locally to 1190 build this document template. 1191
You will need to have: 1193 1194 1195 Ruby: for running the AsciiRFC toolchain 1196 asciidoctor-rfc gem: for converting 1197 AsciiRFC into XML RFC 1198 (v2 or v3) 1199 1200
1201
You 1202 will need to have: 1203 1204 1205 Python: for running xml2rfc 1206 xml2rfc: for converting RFC XML (v2 1207 or v3) into TXT 1208 idnits: for submission preflight 1209 1210
1211
1213 1214 1215 This is a published RFC 1216 This is an Internet-Draft 1218 This is an external reference 1219 1220 1221
1222
1223 Code snippets should be wrapped with <CODE 1224 BEGINS> and 1225 <CODE ENDS> blocks, as required by 1226 the IETF Trust Legal 1227 Provisions (TLP) specified in . 1229
1230
Any 1231 security considerations should be placed here. 1232 As described in (here’s how you refer a 1233 local anchor), 1234 local tools have to be installed before the document template 1235 can be built. 1236 Running of these local tools MAY 1237 produce unintended side 1238 effects that impact security.
1239
This document 1240 does not require any action by IANA. 1241 But if it does, such as proposing changes to IANA registries, 1242 please include them here.
1243 1244 1245 &RFC2119; 1246 &RFC7991; 1247 &RFC8174; 1248 1249 1250 1252 1253 IETF Trust Legal Provisions (TLP) 1254 1255 IETF 1256 1257 1258 1259 1260 1261 1262 RNP: A C library approach to OpenPGP 1263 1264 Ribose Inc. 1265
1266 1267 Suite 1111, 1 Pedder Street 1268 Central 1269 Hong Kong 1270 Hong Kong 1271 1272 open.source@ribose.com 1273 https://www.ribose.com 1274
1275 1276 1277 1278 1279 &I-D.ribose-asciirfc; 1280 &RFC5378; 1281 &RFC7253; 1282 1283
1284
Here’s an 1285 example of a properly wrapped code snippet in 1286 accordance with rules specified in . 1287
1288 1290 { 1291 "code": { 1292 "encoding": "ascii", 1293 "type": "rfc", 1294 "authors": [ "Josiah Carberry", "Truman Grayson" ] 1295 } 1296 } 1297 1298 ]]> 1299
1300
1301
1302 The authors would like to thank their families. 1303
1304 1305 1306 1308 Figure 3: Sample Internet-Draft In AsciiRFC, Output In RFC XML v2 1309 Format 1311 4. Header And Document Attributes 1313 The header gives the document title, followed by an optional author 1314 attribution, and a series of document attributes, with no empty 1315 lines. 1317 4.1. Title And Basic Attributes 1319 Document attributes are used to populate attributes of the root "rfc" 1320 element, "front" elements, and document-level processing 1321 instructions. 1323 o ":doctype:" determines whether the document will be considered 1324 "rfc" or "internet-draft", and interprets other attributes 1325 accordingly. 1327 o Certain attributes ("workgroup", "area", "keyword") are comma 1328 delimited, and result in repeated RFC XML elements. 1330 Figure 4 demonstrates how to set the document header in AsciiRFC, 1331 with its rendering in RFC XML v3 shown in Figure 5. 1333 1334 = The Holy Hand Grenade of Antioch 1335 Arthur son of Uther Pendragon 1336 :doctype: internet-draft 1337 :abbrev: Hand Grenade of Antioch 1338 :updates: 8140 1339 :submission-type: independent 1340 :name: draft-camelot-holy-grenade-01 1341 :status: informational 1342 :consensus: false 1343 :area: General, Operations and Management 1344 :keyword: rabbits, grenades, antioch, camelot 1345 :ipr: trust200902 1346 :toc-include: true 1347 :sort-refs: true 1348 :revdate: 2018-04-15T00:00:00Z 1349 1351 Figure 4: AsciiRFC Document Header 1353 1354 1358 1359 The Holy Hand Grenade of 1360 Antioch 1361 1363 1365 Camelot 1366
1367 1368 Palace 1369 Camel Lot 1 1370 Camelot 1371 grenades 1372 camelot 1374 1376 1378 1380 Figure 5: AsciiRFC Document Header Rendered As RFC XML v3 1382 4.2. Detailed Author Information 1384 The document header can spell out further information about authors, 1385 including contact details. The AsciiRFC header is shown in Figure 6 1386 with its rendering in RFC XML v3 shown in Figure 7. 1388 1389 = The Holy Hand Grenade of Antioch 1390 Arthur son of Uther Pendragon 1391 :doctype: internet-draft 1392 :abbrev: Hand Grenade of Antioch 1393 :updates: 8140 1394 :submission-type: independent 1395 :name: draft-camelot-holy-grenade-01 1396 :status: informational 1397 :consensus: false 1398 :area: General, Operations and Management 1399 :keyword: rabbits, grenades, antioch, camelot 1400 :ipr: trust200902 1401 :toc-include: true 1402 :sort-refs: true 1403 :revdate: 2018-04-15T00:00:00Z 1404 :fullname: Arthur son of Uther Pendragon 1405 :forename_initials: A. 1406 :lastname: Pendragon 1407 :email: arthur.pendragon@ribose.com 1408 :organization: Camelot 1409 :uri: http://camelot.gov.example 1410 :street: Palace\ Camel Lot 1 1411 :city: Camelot 1412 :region: England 1413 :country: United Kingdom 1414 1416 Figure 6: AsciiRFC Document Header With One Author 1418 1419 1423 1424 The Holy Hand Grenade of 1425 Antioch 1426 1428 1430 Camelot 1431
1432 1433 Palace 1434 Camel Lot 1 1435 Camelot 1436 England 1437 United Kingdom 1438 1439 arthur.pendragon@ribose.com 1440 http://camelot.gov.example 1441
1442 1443 1444 General 1445 Operations and Management 1446 rabbits 1447 grenades 1448 antioch 1449 camelot 1451 1453 1455 1457 Figure 7: AsciiRFC Document Header With One Author (RFC XML v3) 1459 Details of a second, third etc. author, including their organization 1460 and contact details, are provided by suffixing the relevant author 1461 attributes with "_2", "_3" etc., as shown in Figure 8 and its RFC XML 1462 v3 rendering Figure 9. 1464 1465 = An API For Calendar-Based Fortune Heuristics Services 1466 Gabriel Destiny; Charise Luck 1467 :doctype: internet-draft 1468 :abbrev: Calendar Fortune Heuristics API 1469 :name: draft-divination-cfapi-00 1470 :status: informational 1471 :ipr: trust200902 1472 :area: Internet 1473 :submission-type: independent 1474 :intended-series: informational 1475 :revdate: 2018-03-23T00:00:00Z 1476 :lastname: Destiny 1477 :fullname: Gabriel Destiny 1478 :forename_initials: G. 1479 :organization: Divination Inc. 1480 :email: gabriel.destiny@ribose.com 1481 :street: 9288 N Divine Street 1482 :city: Dunn 1483 :code: 28334 1484 :region: NC 1485 :country: United States of America 1486 :lastname_2: Luck 1487 :fullname_2: Charise Luck 1488 :forename_initials_2: C. 1489 :organization_2: Divination Inc. 1490 :email_2: charise.luck@ribose.com 1491 :street_2: 9288 N Divine Street 1492 :city_2: Dunn 1493 :code_2: 28334 1494 :region_2: NC 1495 :country_2: United States of America 1496 1498 Figure 8 1500 1501 1504 1505 An API For 1506 Calendar-Based Fortune Heuristics Services 1507 1509 1511 1512 Divination Inc. 1513
1514 1515 9288 N Divine Street 1516 Dunn 1517 NC 1518 28334 1519 United States of America 1520 1521 gabriel.destiny@ribose.com 1522
1523 1524 1525 Divination Inc. 1526
1527 1528 9288 N Divine Street 1529 Dunn 1530 NC 1531 28334 1532 United States of America 1533 1534 charise.luck@ribose.com 1535
1536 1537 1538 Internet 1540 1542 1544 1546 Figure 9: AsciiRFC Document Header With Multiple Authors (RFC XML v3) 1547 The initial author attribution in AsciiRFC, e.g. "Gabriel Destiny; 1548 Charlise Luck" in the example above, expects a strict format of First 1549 Name, zero or more Middle Names, Last name, and cannot process 1550 honorifics like "Dr." or suffixes like "Jr.". 1552 Name attributes with any degree of complexity should be overriden by 1553 using the ":fullname:" and ":lastname:" attributes. The AsciiRFC 1554 ":forename_initials:" attribute replaces the built-in Asciidoctor 1555 syntax ":initials:" attribute (which includes the surname initial), 1556 and is not automatically populated from the name attribution. 1558 4.3. XML Processing Information 1560 A document header may also contain attribute headers which are 1561 treated as XML processing instructions. An AsciiRFC example is shown 1562 in Figure 10 with its rendering in Figure 11. (Note that several 1563 processing instructions are included by default in the output of the 1564 AsciiRFC processor.) 1566 1567 = The Holy Hand Grenade of Antioch 1568 Arthur son of Uther Pendragon 1569 :doctype: internet-draft 1570 :abbrev: Hand Grenade of Antioch 1571 :updates: 8140 1572 :submission-type: independent 1573 :name: draft-camelot-holy-grenade-01 1574 :status: informational 1575 :consensus: false 1576 :ipr: trust200902 1577 :comments: yes 1578 :notedraftinprogress: yes 1579 1581 Figure 10: AsciiRFC Document Header With XML Processing Information 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1600 1601 The Holy Hand Grenade of 1602 Antioch 1603 1605 1607 Camelot 1608
1609 1610 Palace 1611 Camel Lot 1 1612 Camelot 1613 grenades 1614 1616 Figure 11: AsciiRFC Document Header With XML Processing Information 1617 (RFC XML v3) 1619 In the foregoing, values for the processing instructions "strict", 1620 "compact", "toc" etc are included by default; but "comments" and 1621 "notedraftinprogress" are included as specified in the AsciiRFC 1622 document header. The default values provided for processing 1623 instructions can in fact be overriden through the AsciiRFC document 1624 header. 1626 4.4. AsciiRFC-specific Document Attributes 1628 A few document attributes are specific to the operation of the RFC 1629 XML document converter: 1631 :no-rfc-bold-bcp14: false 1632 overrides the wrapping by default of boldface uppercase BCP14 1633 [RFC2119] words (e.g. "*MUST NOT*") with the "bcp14" element. 1635 :smart-quotes: false 1636 overrides Asciidoctor's conversion of straight quotes and 1637 apostrophes to smart quotes and apostrophes. 1639 :inline-definition-lists: true 1640 overrides the RFC XML v2 "idnits" requirement that a blank line be 1641 inserted between a definition list term and its definition. 1643 1644 = The Holy Hand Grenade of Antioch 1645 Arthur son of Uther Pendragon 1646 :doctype: internet-draft 1647 :status: informational 1648 :name: draft-camelot-holy-grenade-00 1650 == Section 1 1651 The specification *MUST NOT* use the word _doesn't_. 1652 1654 Figure 12: AsciiRFC Document Header Without RFC-specific Attributes 1656 1657 1659 1660 The Holy Hand Grenade of Antioch 1661 1663 1666 1667 1668 1669 1670
1671 Section 1 1672 The specification MUST NOT 1673 use the word doesn’t. 1674
1675 1676 1677 1679 Figure 13: AsciiRFC Document Header Without RFC-specific Attributes 1680 (RFC XML v3) 1682 1683 = The Holy Hand Grenade of Antioch 1684 Arthur son of Uther Pendragon 1685 :doctype: internet-draft 1686 :status: informational 1687 :name: draft-camelot-holy-grenade-00 1688 :no-rfc-bold-bcp14: false 1689 :smart-quotes: false 1691 == Section 1 1692 The specification *MUST NOT* use the word _doesn't_. 1693 1695 Figure 14: AsciiRFC Document Header With Overridden RFC-specific 1696 Attributes 1698 1699 1701 1702 The Holy Hand Grenade of Antioch 1703 1705 1708 1709 1710 1711 1712
1713 Section 1 1714 The specification MUST NOT 1715 use the word doesn't. 1716
1717 1718 1719 1721 Figure 15: AsciiRFC Document Header With Overridden RFC-specific 1722 Attributes (RFC XML v3) 1724 5. Preamble 1726 The preamble in AsciiRFC is the text between the end of the document 1727 header (which terminates with a blank line) and the first section of 1728 text. 1730 Any paragraphs of text in the preamble are treated as an abstract, 1731 and may optionally be tagged with the "abstract" style attribute. 1733 Any notes in the preamble are treated as a "note" element. 1735 An example of setting the preamble is given in Figure 16 with its 1736 rendering in Figure 17. 1738 1740 [abstract] 1741 The menagerie of beasts and artefacts depicted in RFC8140 1742 may be usefully supplemented by other renowned figures of 1743 Internet and more general lore. This document extends the 1744 menagerie to the seminal fable of the 1745 "Holy Hand Grenade of Antioch", as depicted in the 1746 Monty Python film "Monty Python and the Holy Grail", 1747 as well as "Spamalot", the musical inspired by the movie. 1749 [NOTE,remove-in-rfc=false] 1750 .Spamalot 1751 The relevance of the musical "Spamalot" to Internet lore should be 1752 obvious to the reader; but in case of doubt, see also 1753 Section 1 ("What is Spam*?") of RFC2635. 1755 1757 Figure 16: AsciiRFC With Preamble 1759 1760 1762 The menagerie of beasts and artefacts depicted in RFC8140 1763 may be usefully supplemented by other renowned figures of 1764 Internet and more general lore. This document extends the 1765 menagerie to the seminal fable of the 1766 "Holy Hand Grenade of Antioch", as depicted in the 1767 Monty Python film "Monty Python and the Holy Grail", 1768 as well as "Spamalot", the musical inspired by the 1769 movie. 1770 Spamalot 1771 The relevance of the musical "Spamalot" to Internet lore should be 1772 obvious to the reader; but in case of doubt, see also 1773 Section 1 ("What is Spam*?") of RFC2635. 1774 1776 1777 1779 Figure 17: AsciiRFC With Preamble (RFC XML v3) 1781 6. Sections and Paragraphs 1783 Section headers are given with a sequence of "=", where the number of 1784 instances of "=" gives the header level. The document itself opens 1785 with a single "=", and sections within it must be started with a 1786 minimum of "==". 1788 Section numbering is toggled with the in-document attribute 1789 ":sectnums:" (on), ":sectnums!:" (off). The boolean "toc" attribute 1790 can also be set on sections, indicating whether the section can be 1791 included in the document's table of contents. 1793 Figure 18 shows how sections and paragraphs are used in AsciiRFC, and 1794 its rendered form is shown in Figure 19. 1796 1798 [toc=exclude] 1799 :sectnums!: 1800 == Terminology 1802 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 1803 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 1804 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 1805 are to be interpreted as described in BCP 14 <> <> 1806 when, and only when, they appear in all capitals, as shown here. 1808 :sectnums: 1809 == Introduction 1811 <> refers to the intended move of RFC formatting to 1812 XML2RFC v3 <>, in the following terms: 1814 1816 Figure 18: AsciiRFC With Sections 1818 1820 1821
1822 Terminology 1823 The key words "MUST", "MUST NOT", 1824 "REQUIRED", "SHALL", 1825 "SHALL NOT", "SHOULD", "SHOULD 1826 NOT", "RECOMMENDED", 1827 "NOT RECOMMENDED", "MAY", and 1828 "OPTIONAL" in this document 1829 are to be interpreted as described in BCP 14 1830 1831 when, and only when, they appear in all capitals, as shown here. 1832
1833
Introduction refers to 1835 the intended move of RFC formatting to 1836 XML2RFC v3 , in the following terms: 1838 1840 Figure 19: AsciiRFC With Sections (RFC XML v3) 1842 Note that skipped sections, such as defining a section using "====" 1843 within a section defined using "==", is not allowed in AsciiRFC 1844 syntax. Doing so will trigger an error with the following message: 1846 asciidoctor: WARNING: _filename_: line _X_: 1847 section title out of sequence: expected level 2, got level 3 1849 7. Figures 1851 AsciiRFC examples (corresponding to RFC XML Figures), source code 1852 Listings, and Literals (preformatted text) are all delimited blocks. 1853 Listings and Literals can occur nested within Examples. 1855 An AsciiRFC example with a figure is given in Figure 20, and its 1856 rendering in Figure 21. 1858 1860 [[killer-bunny]] 1861 .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 1862 ==== 1863 [alt=The Killer Bunny, in ASCII] 1864 .... 1865 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1866 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1867 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 1868 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 1869 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 1870 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 1871 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 1872 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 1873 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 1874 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 1875 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 1876 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 1877 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 1878 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 1879 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 1880 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 1881 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 1882 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 1883 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 1884 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 1885 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 1886 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 1887 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 1888 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 1889 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 1890 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 1891 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 1892 MW \\/\||v v|| -\\-------___ . ., \ | 1893 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 1894 ) /--------^-^ ,. \|// 1895 # \(/ .\\|x// " ' ' 1896 . , \\||// \||\\\// \\ 1897 .... 1898 ==== 1900 [[killer-source]] 1901 .C Code To Lure Killer Rabbit Back To Cave 1902 ==== 1903 [source,c] 1904 ---- 1905 1906 /* Locate the Killer Rabbit */ 1907 int type; 1908 unsigned char *killerRabbit = 1909 LocateCreature(&caerbannog, "killer rabbit"); 1910 if( killerRabbit == 0 ){ 1911 puts("The Killer Rabbit of Caerbannog is out of town."); 1912 return LOST_CREATURE; 1913 } 1914 /* Load Cave */ 1915 unsigned char *cave = LoadPlace(&caerbannog, 1916 "The Cave Of Caerbannog"); 1917 if( cave == 0 ){ 1918 puts("The Cave of Caerbannog must have moved."); 1919 return LOST_PLACE; 1920 } 1922 /* Lure the Killer Rabbit back into the Cave */ 1923 unsigned char *carrot = allocateObjectInPlace( 1924 carrot("fresh"), cave); 1925 if( carrot == 0 ){ 1926 puts("No carrot, no rabbit."); 1927 return LOST_LURE; 1928 } 1930 /* Finally, notify the Killer Rabbit to act */ 1931 return notifyCreature(killerRabbit, &carrot); 1932 1933 ---- 1934 ==== 1936 1938 Figure 20: AsciiRFC With A Figure 1940 1942
1943 A Photo Of The Killer Rabbit of Caerbannog Taken In 1944 Secret 1945 >>\\\\\\\\\\\\ 1950 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 1951 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 1952 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 1953 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 1954 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 1955 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 1956 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 1957 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 1958 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 1959 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 1960 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 1961 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 1962 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 1963 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 1964 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 1965 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 1966 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 1967 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 1968 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 1969 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 1970 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 1971 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 1972 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 1973 MW \\/\||v v|| -\\-------___ . ., \ | 1974 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 1975 ) /--------^-^ ,. \|// 1976 # \(/ .\\|x// " ' ' 1977 . , \\||// \||\\\// \\ 1978 ]]> 1979
1980
1981 C Code To Lure Killer Rabbit Back To Cave 1982 1984 /* Locate the Killer Rabbit */ 1985 int type; 1986 unsigned char *killerRabbit = 1987 LocateCreature(&caerbannog, "killer rabbit"); 1988 if( killerRabbit == 0 ){ 1989 puts("The Killer Rabbit of Caerbannog is out of town."); 1990 return LOST_CREATURE; 1991 } 1993 /* Load Cave */ 1994 unsigned char *cave = LoadPlace(&caerbannog, 1995 "The Cave Of Caerbannog"); 1996 if( cave == 0 ){ 1997 puts("The Cave of Caerbannog must have moved."); 1998 return LOST_PLACE; 1999 } 2001 /* Lure the Killer Rabbit back into the Cave */ 2002 unsigned char *carrot = allocateObjectInPlace( 2003 carrot("fresh"), cave); 2004 if( carrot == 0 ){ 2005 puts("No carrot, no rabbit."); 2006 return LOST_LURE; 2007 } 2008 /* Finally, notify the Killer Rabbit to act */ 2009 return notifyCreature(killerRabbit, &carrot); 2010 2011 ]]> 2012
2014 2016 Figure 21: AsciiRFC With A Figure (RFC XML v3) 2018 If an AsciiRFC Listing or Literal occurs outside of an Example 2019 (Figure 22), the RFC XML converter will supply the surrounding 2020 Figure element (Figure 23). 2022 2024 [[hand-grenade-figure]] 2025 .The Holy Hand Grenade of Antioch (don't pull the pin) 2027 Figure 22: AsciiRFC With ASCII Art Without Figure Wrapping 2029 ______ 2030 \\/ \/ 2031 __\\ /__ 2032 || //\ | 2033 ||__\\/ __| 2034 || | ,---, 2035 || |====`\ | 2036 || | '---' 2037 ,--'*`--, 2038 _||#|***|#| 2039 _,/.-'#|* *|#`-._ 2040 ,,-'#####| |#####`-. 2041 ,,'########| |########`, 2042 //##########| o |##########\ 2043 ||###########| |###########| 2044 ||############| o |############| 2045 ||------------' '------------| 2046 ||o o o o o o o o o o| 2047 |-----------------------------| 2048 ||###########################| 2049 \\#########################/ 2050 `..#####################,' 2051 ``..###############_,' 2052 ``--.._____..--' 2053 `''-----''` 2055 2057 2059
2060 The Holy Hand Grenade of Antioch (don't pull the pin) 2061 2089
2091 2093 Figure 23: AsciiRFC With ASCII Art Without Figure Wrapping (RFC XML 2094 v3) 2096 8. Lists 2097 8.1. Basic Lists 2099 AsciiRFC supports ordered, unordered, and definition lists. 2100 Indentation of ordered and unordered lists is indicated by repeating 2101 the list item prefix ("*" and "." respectively); for definition 2102 lists, it is indicated by incrementing the number of definition term 2103 delimiters ("::"). 2105 List attributes can be used to specify the type of symbol used for 2106 ordered lists. 2108 An example of an unordered list is shown in Figure 24 (with its 2109 rendered version in Figure 25). An example of an ordered list with 2110 ordered and unordered sublists is shown in Figure 26 (with its 2111 rendered version in Figure 27). An example of a definition list is 2112 shown in Figure 28 (with its rendered version in Figure 29). 2114 2116 * Killed 2117 ** Sir Bors 2118 ** Sir Gawain 2119 ** Sir Ector 2120 * Soiled Himself 2121 ** Sir Robin 2122 * Panicked 2123 ** King Arthur 2124 * Employed Ordnance 2125 ** The Lector 2126 ** Brother Maynard 2127 * Scoffed 2128 ** Tim the Enchanter 2130 2132 Figure 24: AsciiRFC With Unordered lists 2134 2136
    2137
  • 2138 Killed 2139
      2140
    • Sir Bors
      • 2141
    • Sir Gawain
      • 2142
    • Sir Ector
      • 2143
    2144
    • 2145
  • 2146 Soiled Himself 2147
      2148
    • Sir Robin
      • 2149
    2150
    • 2151
  • 2152 Panicked 2153
      2154
    • King Arthur
      • 2155
    2156
    • 2157
  • 2158 Employed Ordnance 2159
      2160
    • The Lector
      • 2161
    • Brother Maynard
      • 2162
    2163
    • 2164
  • 2165 Scoffed 2166
      2167
    • Tim the Enchanter
      • 2168
    2169
    • 2170
2172 2174 Figure 25: AsciiRFC With Unordered Lists (RFC XML v3) 2176 2178 . Preamble: St Attila Benediction 2179 . Feast of the People on Sundry Foods 2180 ** Lambs 2181 ** Sloths 2182 ** Carp 2183 ** Anchovies 2184 ** Orangutangs 2185 ** Breakfast Cereals 2186 ** Fruit Bats 2187 ** _et hoc genus omne_ 2188 . Take out the Holy Pin 2189 . The Count 2190 [upperalpha] 2191 .. Count is to Three: no more, no less 2192 .. Not Four 2193 .. Nor Two, except if the count then proceeds to Three 2194 .. Five is Right Out 2195 . Lob the Holy Hand Grenade of Antioch towards the Foe 2196 . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it 2198 2200 Figure 26: AsciiRFC With Ordered lists 2202 2204
    2205
  1. Preamble: St Attila Benediction
    2. 2206
  2. 2207 Feast of the People on Sundry Foods 2208
      2209
    • Lambs
      • 2210
    • Sloths
      • 2211
    • Carp
      • 2212
    • Anchovies
      • 2213
    • Orangutangs
      • 2214
    • Breakfast Cereals
      • 2215
    • Fruit Bats
      • 2216
    • 2217 et hoc genus omne 2218
      • 2219
    2220
    3. 2221
  3. Take out the Holy Pin
    4. 2222
  4. 2223 The Count 2224
      2225
    1. Count is to Three: no more, no less
      2. 2226
    2. Not Four
      3. 2227
    3. Nor Two, except if the count then proceeds to Three
      4. 2228
    4. Five is Right Out
      5. 2229
    2230
    5. 2231
  5. Lob the Holy Hand Grenade of Antioch towards the Foe
    6. 2232
  6. The Foe, being naughty in the LORD's sight, 2233 SHALL snuff it
    7. 2234
2236 2238 Figure 27: AsciiRFC With Ordered Lists (RFC XML v3) 2240 2242 Holy Hand Grenade of Antioch:: 2243 Ordnance deployed by Brother Maynard under the incantation of a 2244 lector, in order to dispense with the Foes of the Virtuous. 2245 See <>. 2247 Holy Spear of Antioch:: 2248 A supposed relic of the crucifixion of Jesus Christ, this is one 2249 of at least four claimed instances of the lance that pierced 2250 Christ's side. Its historical significance lies in inspiring 2251 crusaders to continue their siege of Antioch in 1098. 2253 Sovereign's Orb of the United Kingdom:: 2254 Part of the Crown Jewels of the United Kingdom, the Sovereign's 2255 Orb is a hollow gold sphere set with jewels and topped with a 2256 cross. It was made for Charles II in 1661. See <>. 2258 2260 Figure 28: AsciiRFC With Definition lists 2262 2264
2265
Holy Hand Grenade of Antioch
2266
Ordnance deployed by Brother Maynard under the incantation of a 2267 lector, in order to dispense with the Foes of the Virtuous. 2268 See .
2269
Holy Spear of Antioch
2270
A supposed relic of the crucifixion of Jesus Christ, this is one 2271 of at least four claimed instances of the lance that pierced 2272 Christ's side. Its historical significance lies in inspiring 2273 crusaders to continue their siege of Antioch in 1098.
2274
Sovereign's Orb of the United Kingdom
2275
Part of the Crown Jewels of the United Kingdom, the Sovereign's 2276 Orb is a hollow gold sphere set with jewels and topped with a 2277 cross. It was made for Charles II in 1661. See .
2279
2281 2283 Figure 29: AsciiRFC With Definition Lists (RFC XML v3) 2285 8.2. List Continuation 2287 A list item by default spans a single paragraph. A following 2288 paragraph or other block element can be appended to the current list 2289 item by prefixing it with "+" in a separate line. 2291 See the "List Continuation" section in [Asciidoctor-Manual] for more 2292 information. 2294 An example of list continuation with text is shown in Figure 30 with 2295 its rendered version in Figure 31. 2297 2299 Trojan Rabbit:: 2300 In their siege of the French-occupied castle which may already 2301 contain an instance of the Grail, Sir Bedevere the Wise proposes to 2302 use a Trojan Rabbit to infiltrate the castle, with a raiding party 2303 to take the French "not only by surprise, but totally unarmed." 2304 + 2305 The proposal, unsurprisingly, proved abortive. The more so as the 2306 raiding party forgot to hide within the Trojan Rabbit, before the 2307 French soldiers took the Trojan Rabbit inside the castle. 2309 Killer Rabbit of Caerbannog:: 2310 Guarding the entrance to the Cave of Caerbannog; see <>. 2312 2314 Figure 30: AsciiRFC List With Text Continuation 2316 2318
2319
Trojan Rabbit
2320
2321 In their siege of the French-occupied castle which may already 2322 contain an instance of the Grail, Sir Bedevere the Wise proposes to 2323 use a Trojan Rabbit to infiltrate the castle, with a raiding party 2324 to take the French "not only by surprise, but totally unarmed." 2325 The proposal, unsurprisingly, proved abortive. The more so as the 2326 raiding party forgot to hide within the Trojan Rabbit, before the 2327 French soldiers took the Trojan Rabbit inside the castle. 2328
2329
Killer Rabbit of Caerbannog
2330
Guarding the entrance to the Cave of Caerbannog; see .
2332
2334 2336 Figure 31: AsciiRFC List With Text Continuation (RFC XML v3) 2338 (Multiple paragraphs are not permitted within a list item in RFC XML 2339 v2. The RFC XML converter deals with this by converting paragraph 2340 breaks into line breaks within a list item.) 2342 List continuations can also be embedded to populate a list item with 2343 a sequence of blocks as a unit (in an Asciidoctor syntax open block). 2345 An example of list continuation with a delimited block is shown in 2346 Figure 32 with its rendered version in Figure 33. 2348 2350 . Take out the Holy Pin 2351 . The Count 2352 + 2353 ---- 2354 integer count; 2355 for count := 1 step 1 until 3 do 2356 say(count) 2357 comment Five is Right Out 2358 ---- 2359 . Lob the Holy Hand Grenade of Antioch towards the Foe 2360 . Foe snuffs it 2362 2364 Figure 32: AsciiRFC List With Block Continuation 2366 2368
    2369
  1. Take out the Holy Pin
    2. 2370
  2. 2371 The Count 2372
    2373 2379
    2380
    3. 2381
  3. Lob the Holy Hand Grenade of Antioch towards the Foe
    4. 2382
  4. Foe snuffs it
    5. 2383
2385 2387 Figure 33: AsciiRFC List With Block Continuation (RFC XML v3) 2389 AsciiDoc, and thus AsciiRFC, considers paragraphs to be the basic 2390 level of blocks, and does not permit lists to be nested within them: 2391 any text after a list is considered to be a new paragraph. 2393 Therefore, markup as shown in Figure 34 cannot be generated via 2394 AsciiRFC. 2396 2397 2398 This is the start of a paragraph. 2399
    2400
  • List Entry 1
    • 2401
  • 2402 List Entry 2 2403 Note 2. 2404
    • 2405
2406 And this is the continuation of the paragraph. 2407 2408 2410 Figure 34: This RFC XML v3 Output Cannot Be Generated Using AsciiRFC 2412 9. Blockquotes 2414 Asciidoctor syntax supports blockquotes and quotations of verse; its 2415 block quotations permit arbitrary levels of quote nesting. RFC XML 2416 v3, and thus AsciiRFC, only supports one level of blockquotes. 2418 Unlike RFC XML v2, RFC XML v3 does not support line breaks outside of 2419 tables, so verse quotations are converted to prose in the v3 2420 converter. 2422 An example of using AsciiRFC Blockquotes is given in Figure 35 with 2423 its rendered version in Figure 36. 2425 2427 [quote,attribution="A. Farrel"] 2428 ____ 2429 Although the RFC Editor has recently dragged the IETF kicking and 2430 screaming into the twentieth century [RFC7990] [RFC7996], there is a 2431 yearning among all right-thinking Internet architects to "keep it 2432 simple" and to return to the olden days when pigs could be given 2433 thrust without anyone taking undue offence. 2434 ____ 2436 2438 Figure 35: AsciiRFC Blockquote Usage 2440 2442
2443 Although the RFC Editor has recently dragged the IETF kicking and 2444 screaming into the twentieth century [RFC7990] [RFC7996], there is a 2445 yearning among all right-thinking Internet architects to "keep it 2446 simple" and to return to the olden days when pigs could be given 2447 thrust without anyone taking undue offence. 2448
2450 2452 Figure 36: AsciiRFC Blockquote Usage (RFC XML v3) 2454 10. Notes And Asides 2456 Asciidoctor syntax supports a range of "admonitions", including 2457 notes, warnings, and tips. They are indicated by a paragraph prefix 2458 (e.g. "WARNING:"), or as a block with an admonition style attribute. 2460 All admonitions are conflated in AsciiRFC, being converted to "note" 2461 elements in the document preamble, and "cref" elements in the main 2462 document. 2464 This means that no admonitions will therefore appear in the textual 2465 output, unless forced to through the "comments" processing 2466 instruction. A sample admonition is shown in Figure 37, with its 2467 rendered output in Figure 38. 2469 2471 [NOTE,display=true,source=Author] 2472 ==== 2473 Image courtesy of 2474 https://camelot.gov.example/creatures-in-ascii/ 2475 ==== 2477 2479 Figure 37: An AsciiRFC Adminition Block 2481 2483 Image courtesy of 2484 2487 2489 Figure 38: An AsciiRFC Adminition Block (RFC XML v3) 2491 With RFC XML v2, note that no inline formatting is permitted for 2492 "cref" elements, and any such formatting is therefore stripped for v2 2493 by the converter. 2495 Because paragraphs in AsciiRFC cannot contain any other blocks, a 2496 comment at the end of a paragraph is treated as a new block. In the 2497 document converter, any such comments are moved inside the preceding 2498 RFC XML paragraph; if the comment is at the start of a section, as in 2499 the example above, it is wrapped inside a paragraph. 2501 The RFC XML v3 converter also supports "asides" (Asciidoctor syntax 2502 Sidebars). A sample is shown in Figure 39, with its rendered output 2503 in Figure 40. 2505 2507 **** 2508 While the exchange at the French-occupied castle is one of 2509 the more memorable scenes of _Monty Python and the Holy Grail_, 2510 the Trojan Rabbit has not reached the same level of cultural 2511 resonance as its more murderous counterpart. Reasons for this 2512 may include: 2514 * Less overall screen-time dedicated to the Trojan Rabbit. 2516 * The Trojan Rabbit as projectile has already been anticipated 2517 by the Cow as projectile. 2518 **** 2520 2522 Figure 39: An AsciiRFC Sidebar Block 2524 2526 2537 2539 Figure 40: An AsciiRFC Sidebar Block Rendered As An Aside (RFC XML 2540 v3) 2542 Comments given in AsciiDoc syntax (notated with initial "//") are not 2543 intended to be shown in the rendered output, and will not appear in 2544 the output as XML comments. XML comments can be generated by using 2545 the "[comment]#...#" inline formatting macro, or the "[.comment]" 2546 role attribute on blocks. A sample is shown in Figure 39 with its 2547 rendered output in Figure 40. 2549 2551 The exchange of projectile animals was the beginning of a 2552 long-running fruitful relationship between the British and the 2553 French peoples, 2554 [comment]#TODO: Will need to verify that claim.# which 2555 arguably predates the traditional English enmity with the 2556 French. [comment]#Strictly speaking, the Knights are Welsh.# 2558 [.comment] 2559 -- 2560 This document, as it turns out, has a profusion of XML comments. 2562 As expected, they are ignored in any rendering of the document. 2563 -- 2565 2567 Figure 41: AsciiRFC delimited text intended as an XML Comment 2569 2571 The exchange of projectile animals was the beginning of a 2572 long-running fruitful relationship between the British and the 2573 French peoples, 2575 2577 which 2578 arguably predates the traditional English enmity with the 2579 French. 2581 2583 2585 2590 2592 Figure 42: AsciiRFC delimited text Rendered As An XML Comment (RFC 2593 XML v3) 2595 11. Tables 2597 AsciiRFC tables, like RFC XML v3, support distinct table heads, 2598 bodies and feet; cells spanning multiple rows and columns; and 2599 horizontal alignment. The larger range of table formatting options 2600 available in RFC XML v2 is also supported. 2602 A sample of an AsciiRFC table is shown in Figure 43, with its 2603 rendered output in Figure 44. 2605 Neither version of RFC XML is as expressive in its table structure as 2606 Asciidoctor syntax. RFC XML, for example, does not permit blocks 2607 within table cells. 2609 2611 [grid=all,options="footer"] 2612 |=== 2613 |French Castle | Cave of Caerbannog 2615 2+|King Arthur 2616 2+|Patsy 2617 2+|Sir Bedevere the Wise 2618 2+|Sir Galahad the Pure 2619 2+|Sir Lancelot the Brave 2620 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot 2621 |French Guard with Outrageous Accent| Tim the Enchanter 2622 |Other French Guards | Brother Maynard 2623 | | The Lector 2624 .3+^|not yet recruited 2625 >|Sir Bors 2626 >|Sir Gawain 2627 >|Sir Ector 2629 |Retinue of sundry knights 2630 |Retinue of sundry more knights than at the French Castle 2631 |=== 2633 2635 Figure 43: An AsciiRFC Table 2637 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2694 2695 2696
French CastleCave of Caerbannog
King Arthur
Patsy
Sir Bedevere the Wise
Sir Galahad the Pure
Sir Lancelot the Brave
Sir Robin the 2664 Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous AccentTim the Enchanter
Other French GuardsBrother Maynard
2676 The Lector
not yet recruitedSir Bors
Sir Gawain
Sir Ector
Retinue of sundry knightsRetinue of sundry more knights than at the 2693 French Castle
2698 2700 Figure 44: An AsciiRFC Table (RFC XML v3) 2702 12. Inline Formatting 2704 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts 2706 AsciiRFC supports italics, boldface, monospace, subscripts and 2707 superscripts, just like RFC XML v3. 2709 The inline formatting syntax given in Figure 45 produces the RFC XML 2710 v3 output given in Figure 46. 2712 2714 The participants of that renowned exercise in cross-cultural 2715 communication, to wit the exchange between the 2716 _Knights of the Round Table_ 2717 and the taunting French soldiers serving under *Guy de Lombard* are, 2718 properly speaking, outside the scope of this `menagerie`, being more 2719 or less human. Notwithstanding, several^ish^ beasts both animate~d~ 2720 and wooden played a significant part in this encounter; most 2721 notably: 2723 * The Projectile Cow, see <> 2724 * The Trojan Rabbit, see <> 2726 2728 Figure 45: Inline Formatting In AsciiRFC 2730 2732 The participants of that renowned exercise in cross-cultural 2733 communication, to wit the exchange between the 2734 Knights of the Round Table 2735 and the taunting French soldiers serving under Guy de 2736 Lombard are, 2737 properly speaking, outside the scope of this menagerie, being 2738 more 2739 or less human. Notwithstanding, severalish beasts both 2740 animated 2741 and wooden played a significant part in this encounter; most 2742 notably: 2743
    2744
  • The Projectile Cow, see
    • 2745
  • The Trojan Rabbit, see
    • 2746
2748 2750 Figure 46: Inline Formatting In AsciiRFC (RFC XML v3) 2752 12.2. Formatting BCP 14 Keywords 2754 RFC XML v3 also supports tagging of BCP14 keywords [RFC2119] 2755 [RFC8174]; this is done in AsciiRFC either by tagging them with a 2756 custom formatting span (e.g. "MUST NOT"), or by converting any 2757 boldface all-caps words recognised as BCP14 words (unless the ":no- 2758 rfc-bold-bcp14: false" document attribute is set). 2760 Any spans of BCP14 text delimited by inline formatting delimiters 2761 need to be contained within a single line of text; in Asciidoctor 2762 syntax, formatting spans are broken up across line breaks. 2764 This usage is demonstrated in Figure 47 with the rendered output in 2765 Figure 48. 2767 2769 The instructions in the _Book of Armaments_ on the proper deployment 2770 of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as 2771 follows, although this summary *SHALL NOT* be used as a substitute 2772 for a reading from the Book of Armaments: 2774 2776 Figure 47: BCP14 Keywords In AsciiRFC 2778 2780 The instructions in the Book of Armaments on the proper 2781 deployment 2782 of the Holy Hand Grenade of Antioch MAY be summarized as 2783 follows, although this summary SHALL NOT be used as a 2784 substitute 2785 for a reading from the Book of Armaments: 2787 2789 Figure 48: BCP14 Keywords In AsciiRFC (RFC XML v3) 2791 12.3. Escaping AsciiRFC Syntax 2793 Formatting delimiters like "*" can be escaped with backslash ("\*"); 2794 double formatting delimiters, like "**" and "__", need to be escaped 2795 with double backslash ("\\**"). 2797 Escaping delimiters is not always reliable, and for double delimiters 2798 it is preferable to use HTML entities ("**"), or attribute 2799 references (references to the value of attributes set in the document 2800 header) as shown in Figure 49. 2802 2803 :dblast: ** 2805 `{dblast}` 2806 2808 Figure 49: Escaping AsciiRFC Syntax Using Attributes 2810 In extreme circumstances (such as quoting AsciiDoc syntax), you may 2811 need to resort to altering the substitutions behaviour within a given 2812 block of of AsciiDoc; see the "Applying Substitutions" section of 2813 [Asciidoctor-Manual]. 2815 13. Links 2817 Common URL formats are recognised automatically as hyperlinks in 2818 AsciiRFC, which inherits this excellent feature from AsciiDoc, and 2819 are rendered as such. 2821 Any hyperlinked text is appended after the hyperlink in square 2822 brackets. 2824 An example is given in Figure 50 with its rendered version in 2825 Figure 51. 2827 2829 <> of the fearsome beast 2830 has been sourced from 2831 http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], 2832 <> 2833 by C code that was used in this accurate depiction of the 2834 Killer Rabbit: 2836 2838 Figure 50: An AsciiRFC Link 2840 2842 The following depiction of the 2843 fearsome beast 2844 has been sourced from 2845 Rabbit-SCII, 2847 accompanied 2848 by C code that was used in this accurate depiction of the 2849 Killer Rabbit: 2851 2853 Figure 51: An AsciiRFC Link (RFC XML v3) 2855 To prevent hyperlinking of a URL, prefix it with a backslash, as 2856 shown in Figure 52 with its rendered version in Figure 53. 2858 2860 The screaming move into the twenty-*first* century is accompanied by 2861 a move back to the late twentieth century, with ASCII stylings more 2862 wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be 2863 accessible in 1996.) 2865 2867 Figure 52: A Literal AsciiRFC Link 2869 2871 The screaming move into the twenty-first century is 2872 accompanied by 2873 a move back to the late twentieth century, with ASCII stylings more 2874 wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be 2875 accessible in 1996.) 2877 2879 Figure 53: A Literal AsciiRFC Link (RFC XML v3) 2881 14. Cross-References 2883 14.1. Basic Referencing 2885 Anchors for cross-references are notated as "[[...]]" or "[#...]", 2886 and can be inserted on their own line in front of most blocks. 2888 Asciidoctor syntax supports anchors in a much wider range of contexts 2889 than is supported than RFC XML v3 (let alone v2); anchors that are 2890 not supported for that version of RFC XML are simply ignored by the 2891 converter. 2893 Note that anchors in RFC XML are constrained to the format "[A-Za- 2894 z_:][[A-Za-z0-9_:.-]*" (i.e. "xsd:ID"). 2896 Cross-references to anchors are notated as "<<...>>"; cross- 2897 references with custom text as "<>". 2899 An example of using cross-references in AsciiRFC is given in 2900 Figure 54 with its rendered output in Figure 55. 2902 2904 The _Cave of Caerbannog_ has been well-established in the mythology 2905 of Camelot (as recounted by Monty Python) as the lair of the 2906 Legendary Black Beast of Arrrghhh, more commonly known today as the 2907 *Killer Rabbit of Caerbannog* <>. 2908 It is the encounter between the Killer Rabbit of Caerbannog and the 2909 Knights of the Round Table, armed with the Holy Hand Grenade of 2910 Antioch (see the <>), that we 2911 recount here through monospace font and multiple spaces. 2913 [[killer_rabbit_caerbannog]] 2914 === The Killer Rabbit of Caerbannog 2916 2918 Figure 54: Setting And Referring To Cross-References In AsciiRFC 2920 2922 The Cave of Caerbannog has been well-established in the 2923 mythology 2924 of Camelot (as recounted by Monty Python) as the lair of the 2925 Legendary Black Beast of Arrrghhh, more commonly known today as the 2926 Killer Rabbit of Caerbannog . 2928 It is the encounter between the Killer Rabbit of Caerbannog and the 2929 Knights of the Round Table, armed with the Holy Hand Grenade of 2930 Antioch (see the following 2931 section), that we 2932 recount here through monospace font and multiple spaces. 2933
The 2934 Killer Rabbit of Caerbannog 2935 2937 Figure 55: Setting And Referring To Cross-References In AsciiRFC (RFC 2938 XML v3) 2940 14.2. Referencing With Attributes 2942 While Asciidoctor syntax natively does not support attributes on 2943 cross-references, AsciiRFC works around that by embedding formatting 2944 information as templated text within cross-references: 2946 o "format= x: text" populates the "xref@format" attribute 2947 o a section number followed by one of the words "of", "parens", 2948 "bare", "text" is treated as a "relref" reference to an external 2949 document. 2951 An example of referencing with attributes is given in Figure 56 with 2952 its output in Figure 57. 2954 2956 The *Killer Rabbit of Caerbannog*, that most formidable foe of 2957 the Knights and of all that is holy or carrot-like, has been 2958 depicted diversely in lay and in song. We venture to say, 2959 _contra_ the claim made in <>, 2960 that the Killer Rabbit of Caerbannog truly is the most afeared 2961 of all the creatures. Short of sanctified ordnance such as 2962 <>, there are few remedies 2963 known against its awful lapine powers. 2965 2967 Figure 56: Cross-References With Attributes In AsciiRFC 2969 2971 The Killer Rabbit of Caerbannog, that most 2972 formidable foe of 2973 the Knights and of all that is holy or carrot-like, has been 2974 depicted diversely in lay and in song. We venture to say, 2975 contra the claim made in Ze Vompyre, 2977 that the Killer Rabbit of Caerbannog truly is the most afeared 2978 of all the creatures. Short of sanctified ordnance such as 2979 , there are few 2980 remedies 2981 known against its awful lapine powers. 2983 2985 Figure 57: Cross-References With Attributes In AsciiRFC (RFC XML v3) 2987 14.3. Indexing 2989 Inline index entries are notated as "((...))". Index entries which 2990 do not appear in the text are notated as "(((...)))"; such entries 2991 may include a separate sub-entry, separated from the main entry by 2992 comma. 2994 2996 The solution to the impasse at the ((Cave of Caerbannog)) was 2997 provided by the successful deployment of the 2998 *Holy Hand Grenade of Antioch* (see <>) 2999 (((Holy Hand Grenade of Antioch))). 3000 Any similarity between the Holy Hand Grenade of Antioch and the 3001 mythical _Holy Spear of Antioch_ is purely intentional; 3002 (((relics, Christian))) any similarity between the Holy Hand Grenade 3003 of Antioch and the _Sovereign's Orb of the United Kingdom_ 3004 (see <>) is putatively fortuitous. 3005 (((relics, monarchic))) 3007 3009 Figure 58: AsciiRFC Index Entries 3011 3013 The solution to the impasse at the Cave of Caerbannog was 3015 provided by the successful deployment of the 3016 Holy Hand Grenade of Antioch (see ) 3018 . 3019 Any similarity between the Holy Hand Grenade of Antioch and the 3020 mythical Holy Spear of Antioch is purely intentional; 3021 any similarity between the 3022 Holy Hand Grenade 3023 of Antioch and the Sovereign's Orb of the United Kingdom 3024 (see ) is putatively fortuitous. 3025 3027 3029 Figure 59: AsciiRFC Index Entries (RFC XML v3) 3031 15. Inclusions 3033 AsciiRFC inherits the Asciidoctor syntax "include" directive 3034 [Asciidoctor-Manual] to include external files in a master AsciiRFC 3035 document. 3037 This directive is capable of sophisticated document merging, 3038 including adjusting the heading levels of the included text, 3039 selecting text within specified tags or line numbers to be included, 3040 and adjusting the indentation of code snippets in merged text. 3042 Its basic syntax is given in Figure 60. 3044 3045 include::path[ 3046 leveloffset=_offset_, 3047 lines=_ranges_, 3048 tag(s)=_name(s)_, 3049 indent=_depth_ 3050 ] 3051 3053 Figure 60: Inclusions In AsciiRFC 3055 If a file is included in an AsciiRFC document, ensure it ends with a 3056 blank line. An inclusion that results in its final block not being 3057 delimited with a blank line from what follows can lead to 3058 unpredictable results. 3060 16. Encoding and Entities 3062 XML accepts the full range of characters in the world's languages 3063 through UTF-8 character encoding, and one of the motivations for the 3064 move by the IETF from plain text to RFC XML has been to allow non- 3065 ASCII characters to be included in RFCs. 3067 However, current RFC XML v2 tools still do not support UTF-8, and 3068 alternative tooling support for UTF-8 also remains patchy. Out of an 3069 abundance of caution, the RFC XML converter uses US-ASCII for its 3070 character encoding, and renders any non-ASCII characters as HTML 3071 entities. 3073 AsciiRFC accepts HTML entities as input, even though they are not 3074 part of the W3C XML specification. HTML entities such as " " 3075 feature in examples of RFC XML provided by the IETF. In order to 3076 prevent dependence of the XML output from extraneous entity 3077 definitions, any such entities are rendered in the XML as decimal 3078 character entities. 3080 An example of how AsciiRFC renders non-ASCII UTF-8 characters are 3081 given in Figure 61 with the output in Figure 62. 3083 3085 ____ 3086 .כאן אולי 3087 ימצאו 3088 המילים 3089 האחרונות של 3090 יוסף 3091 .מארמתיה 3092 .מי אשר יהיה 3093 אמיץ ובעל 3094 נפש טהורה 3095 יוכל למצוא 3096 את הגביע 3097 הקדוש בטירת 3098 .אאאאאאאה 3100 "Here may be found the last words of Joseph of Arimathea. 3101 He who is valiant and pure of spirit may find the Holy Grail 3102 in the castle of — Aaaargh." 3103 ____ 3105 3107 Figure 61: UTF-8 Characters In AsciiRFC 3109 3111
כאן אולי 3112 ימצאו 3113 המילים 3114 האחרונות של 3115 יוסף 3116 .מארמתיה 3117 מי אשר יהיה 3118 אמיץ ובעל 3119 נפש טהורה 3120 יוכל למצוא 3121 את הגביע 3122 הקדוש בטירת 3123 .אאאאאאאה 3124 "Here may be found the last words of Joseph of Arimathea. 3125 He who is valiant and pure of spirit may find the Holy Grail 3126 in the castle of — Aaaargh."
3128 3130 Figure 62: UTF-8 Characters In AsciiRFC Rendered As RFC XML v3 3132 Note that because initial period is a formatting character in 3133 Asciidoctor, we have had to use "." to escape the period at the 3134 end of Hebrew sentences (which appears at the start of the line, 3135 Hebrew being written Right-to-Left). Asciidoctor is not natively 3136 equipped to deal with Right-to-Left languages in its formatting 3137 parsing. 3139 17. Bibliography 3141 The simple encoding of bibliography syntax provided by AsciiDoc (and 3142 Asciidoctor syntax) is inadequate for the complexity of bibliographic 3143 markup required by RFC XML. 3145 RFC documents overwhelmingly cite other RFC documents, and canonical 3146 RFC XML bibliographic entries are available at [IETF-BibXML]; so it 3147 would be inefficient to encode those entries natively in AsciiRFC, 3148 only to have them converted back to RFC XML. 3150 The converter provides two means of incorporating bibliographies into 3151 RFC documents authored in AsciiRFC: 3153 o using raw RFC XML; and 3155 o assembling bibliographies in preprocessing. 3157 In either case, the RFC XML needs to be well-formed; missing closing 3158 tags can lead to erratic behaviour in the converter. 3160 17.1. Using Raw RFC XML 3162 In the first method, bibliographic citations are handled like all 3163 other AsciiRFC cross-references. The bibliographic entries for 3164 normative and informative references are given in the AsciiRFC as 3165 passthrough blocks, which contain the raw RFC XML for all references; 3166 document conversion leaves the raw RFC XML in place. 3168 This approach requires authors to maintain the normative and 3169 informative bibliographies within the document, to update them as 3170 citations are added and removed, and to sort them manually. However, 3171 if the citation is stored on the IETF's RFC XML citation libraries 3172 (see ), AsciiRFC will automatically 3173 replace it with an external reference to that citation. So the body 3174 of the citation XML can be left out. 3176 For example, the AsciiRFC in Figure 63 will generate the 3177 corresponding RFC XML v3 output in Figure 64. 3179 3181 [bibliography] 3182 == Normative References 3183 ++++ 3184 3186 3187 Key words for use in RFCs to Indicate 3188 Requirement Levels 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 ++++ 3200 [bibliography] 3201 == Informative References 3202 ++++ 3204 3205 3206 Monty Python and the Holy Grail 3207 3208 3209 3210 3211 3212 3213 3214 3215 3217 3219 3220 DON'T SPEW A Set of Guidelines for Mass Unsolicited 3221 Mailings and Postings (spam*) 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3235 3237 3238 RFC Format Framework 3239 3240 3241 3242 3243 3244 3245 3246 3248 3250 3251 3252 The Arte of ASCII: Or, An True and Accurate Representation of 3253 an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of 3254 Character 3255 3256 3257 3258 3259 3260 3261 3262 3263 3265 3267 3268 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 3269 Words 3270 3271 3272 3273 3274 RFC 2119 specifies common key words that may be used 3275 in protocol specifications. This document aims to reduce 3276 the ambiguity by clarifying that only UPPERCASE usage of the 3277 key words have the defined special meanings. 3278 3279 3280 3281 3282 3284 ++++ 3286 3288 Figure 63: AsciiRFC Inline Bibliography 3290 3291
3292 3293 3294 Normative References 3295 3299 3300 3301 Informative References 3302 3303 3304 Monty Python and the Holy Grail 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3318 3322 3326 3330 3331 3332 3333 3335 Figure 64: AsciiRFC Inline Bibliography Rendered As RFC XML v3 3337 17.2. Preprocessing Using "asciidoctor-bibliography" 3339 The alternative method is to use a preprocessing tool, 3340 [asciidoctor-bibliography], to import citations into the AsciiRFC 3341 document from an external file of references. 3343 The references file consists of RFC XML reference entries, and still 3344 needs to be managed manually; however the bibliographies are 3345 assembled from that file, sorted, and inserted into the normative and 3346 informative references in preprocessing. Citations in the document 3347 itself are given as macros to be interpreted by the preprocessor; 3348 this allows them to be split into normative and informative 3349 references. (The MMark tool likewise splits reference citations into 3350 normative and informative.) 3352 Integration with the "asciidoc-bibliography" gem proceeds as follows: 3354 1. Create an RFC XML references file, consisting of a "" 3355 element with individual "" elements inserted, as would 3356 be done for the informative and normative references normally. 3357 The references file will contain all possible references to be 3358 used in the file; the bibliography gem will select which 3359 references have actually been cited in the document. 3361 A. Rather than hand crafting RFC XML references for RFC 3362 documents, you should download them from an authoritative 3363 source; e.g., "http://xml.resource.org/public/rfc/bibxml/\ 3364 reference.RFC.2119.xml". Note that RFC XML references from 3365 this link contains the XML document declaration, which needs 3366 to be removed before being used in the XML bibliography. 3368 B. Unlike the case for RFC XML documents created manually, the 3369 references file does not recognise XML entities and will not 3370 attempt to download them during processing. Any references 3371 to "http://xml.resource.org/public/rfc/bibxml/\ " will need 3372 to be downloaded and inserted into the references file. 3374 C. The RFC XML in the references file will need to be 3375 appropriate to the version of RFC XML used in the main 3376 document, as usual. Note that RFC XML v2 references are 3377 forward compatible with v3; v3 contains a couple of 3378 additional elements. 3380 2. Add to the main document header attributes referencing the 3381 references file (":bibliography-database:"), and the bibliography 3382 style (":bibliography-style: rfc-v3"). 3384 3. References to a normative reference are inserted with the macro 3385 "cite:norm[id]" instead of "<>", where "id" is the anchor of 3386 the reference. 3388 4. References to an informative reference are inserted with the 3389 macro "cite:info[id]" instead of "<>", where "id" is the 3390 anchor of the reference. 3392 5. Formatted crossreferences and "relref" crossreferences are 3393 entered by inserting the expected raw XML in the "text" 3394 attribute. Do not use the "{cite}" interpolation of the 3395 citation. For example: 3397 * "<>" = "cite:norm[id, text="words"]" 3400 * "<>" (processed as a formatted 3401 cross-reference) = "cite:norm[id, text="words"]" 3404 * "<>" (processed as relref) = 3405 "cite:norm[id, text=""]" 3408 * "<>" (processed as relref with 3409 a cross-document internal reference) = "cite:norm[id, 3410 text=""]" 3413 6. Normative and Informative References are inserted in the document 3414 through a macro, which occurs where the RFC XML references would 3415 be inserted, as shown in Figure 65. 3417 3418 [bibliography] 3419 == Normative References 3421 ++++ 3422 bibliography::norm[] 3423 ++++ 3425 [bibliography] 3426 == Informative References 3428 ++++ 3429 bibliography::info[] 3430 ++++ 3431 3433 Figure 65: Using asciidoctor-bibliography For Bibliography 3434 Preprocessing 3436 18. RFC XML features not supported in Asciidoctor 3438 The following features of RFC XML v3 [RFC7991] and v2 [RFC7749] are 3439 not supported by the AsciiRFC converter, and would need to be 3440 adjusted manually after RFC XML is generated: 3442 +------------------------+--------------------+---------------------+ 3443 | RFC XML element | RFC XML v3 | RFC XML v2 | 3444 +------------------------+--------------------+---------------------+ 3445 | "front/boilerplate" | Not added by the | Not added by the | 3446 | | converter | converter | 3447 | "iref@primary" | N | N | 3448 | "reference" (and all | As Raw XML | As Raw XML | 3449 | children) | | | 3450 | "table/preamble" | Deprecated | N | 3451 | "table/postamble" | Deprecated | N | 3452 | "artwork@width" | Only on images | Only on images | 3453 | "artwork@height" | Only on images | Only on images | 3454 +------------------------+--------------------+---------------------+ 3456 19. Authoring 3458 To author an AsciiRFC document, you should first familiarise yourself 3459 with the [Asciidoctor-Manual]. 3461 The [asciidoctor-rfc] Ruby gem source code distribution also has 3462 samples of individual RFC XML features in v2 and v3, and examples of 3463 self-standing AsciiRFC documents, along with their RFC XML 3464 renderings. (This includes round-tripped RFC XML documents.) 3466 19.1. Using the "rfc-asciirfc-minimal" template 3468 In addition, you can clone the sample "rfc-asciirfc-minimal" 3469 repository as a template, and populate it for your AsciiRFC document 3470 using the steps shown in Figure 66. 3472 $ git clone https://github.com/riboseinc/rfc-asciirfc-minimal 3474 Figure 66: Cloning The AsciiRFC Document Template 3476 19.2. Installing AsciiRFC Backend Processors 3478 Converting your AsciiRFC to RFC XML is a simple as installing the 3479 Asciidoctor Ruby gem "asciidoctor" (see "Installation" at 3480 [Asciidoctor]) and the "asciidoctor-rfc" gem in Ruby (through 3481 RubyGems), then running the "asciidoctor" executable on the document, 3482 specifying the "asciidoctor-rfc" gem as a library. 3484 The necessary steps are shown in Figure 67. 3486 $ gem install asciidoctor-rfc 3487 $ asciidoctor -b rfc3 -r 'asciidoctor-rfc' foo.adoc # RFC XML v3 output 3488 $ asciidoctor -b rfc2 -r 'asciidoctor-rfc' foo.adoc # RFC XML v2 output 3490 Figure 67: Installing The AsciiRFC Backend Processors 3492 19.3. Iterating AsciiRFC Content 3494 As you author AsciiRFC content, you should iterate by running the 3495 AsciiRFC conversion frequently, to ensure that you are still 3496 generating valid XML through your markup. The converter makes an 3497 effort to ensure that its XML output is valid, and it issues warnings 3498 about likely issues; it also validates its own XML output against the 3499 RFC XML schema (of the corresponding version), and reports errors in 3500 the XML output in the format shown in Figure 68. 3502 V3 RELAXNG Validation: 12:0: ERROR: Invalid attribute 3503 sortRefs for element rfc 3505 Figure 68: Sample Validation Error Message From AsciiRFC 3507 Note that validation against the Relax NG RFC XML schema includes 3508 confirming the referential integrity of all cross-references in the 3509 document. 3511 It may be necessary to intervene in the XML output generated by the 3512 converter, either because the block model of AsciiRFC does not 3513 conform with the intended RFC XML (e.g. lists embedded in 3514 paragraphs), or because RFC XML features are required that are not 3515 supported within AsciiRFC. 3517 20. Security Considerations 3519 o Ensure your AsciiRFC generator comes from a geniune and 3520 trustworthy source. This protects your own machine and also 3521 prevents injection of malicious content in your resulting 3522 document. 3524 o An AsciiRFC generator may cause errors in textual rendering or 3525 link generation that may lead to security issues. 3527 o Creating cross-references (and also bibliographic references) to 3528 external documents may pose risks since the specified external 3529 location may become controlled by a malicious party. 3531 o URIs that start with the "http:" or "https:" prefix are 3532 automatically converted into links in AsciiRFC except when escaped 3533 with a backslash before the prefix. A URI that is intended to be 3534 text but unintentionally rendered as a link may cause users to 3535 visit a malicious website with security consequences. 3537 o AsciiRFC contains syntax that can directly incorporate remote URI 3538 content, such as "include::" which allows remotely-located 3539 AsciiRFC content files. If a remote URI contains malicious 3540 content, this content will be included in the resulting AsciiRFC 3541 document compiled as RFC XML. Remotely-linked URIs should always 3542 be checked for malicious content prior to compiling AsciiRFC into 3543 RFC XML. 3545 21. IANA Considerations 3547 This document does not require any action by IANA. 3549 22. References 3551 22.1. Normative References 3553 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 3554 RFC 7991, DOI 10.17487/RFC7991, December 2016, 3555 . 3557 22.2. Informative References 3559 [AsciiDoc] 3560 Rackham, S., "AsciiDoc: Text based document generation", 3561 November 2013, . 3563 [Asciidoctor] 3564 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast 3565 text processor & publishing toolchain for converting 3566 AsciiDoc to HTML5, DocBook & more.", November 2017, 3567 . 3569 [asciidoctor-bibliography] 3570 Ribose Inc., "Citations and Bibliography the 'asciidoctor- 3571 way'", November 2017, 3572 . 3574 [Asciidoctor-Manual] 3575 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast 3576 text processor & publishing toolchain for converting 3577 AsciiDoc to HTML5, DocBook & more.", November 2017, 3578 . 3580 [asciidoctor-rfc] 3581 Ribose Inc., "asciidoctor-rfc lets you write Internet- 3582 Drafts and RFCs in AsciiDoc, the "asciidoctor-way".", 3583 November 2017, 3584 . 3586 [AsciiMathML] 3587 "AsciiMath is an easy-to-write markup language for 3588 mathematics.", November 2017, . 3590 [datatracker-asciirfc-minimal] 3591 Carberry, J. and T. Grayson, "IETF Datatracker: A Minimal 3592 Internet-Draft In AsciiRFC", April 2018, 3593 . 3596 [datatracker-camelot-holy-grenade] 3597 Pendragon, A., "IETF Datatracker: The Holy Hand Grenade of 3598 Antioch", Aprilt 2018, . 3601 [datatracker-divination-cfapi] 3602 Destiny, G. and C. Luck, "IETF Datatracker: An API For 3603 Calendar-Based Fortune Heuristics Services", March 2018, 3604 . 3607 [draftr] Barnes, R., "draftr: an HTML front-end to pandoc2rfc", Nov 3608 2017, . 3610 [git-asciirfc-minimal] 3611 Carberry, J. and T. Grayson, "Git repository: A Minimal 3612 Internet-Draft In AsciiRFC", March 2018, 3613 . 3615 [git-camelot-holy-grenade] 3616 Pendragon, A., "Git repository: The Holy Hand Grenade of 3617 Antioch", March 2018, 3618 . 3620 [git-divination-cfapi] 3621 Destiny, G. and C. Luck, "Git repository: An API For 3622 Calendar-Based Fortune Heuristics Services", March 2018, 3623 . 3625 [I-D.asciirfc-minimal] 3626 Carberry, J. and T. Grayson, "A Minimal Internet-Draft In 3627 AsciiRFC", draft-asciirfc-minimal-02 (work in progress), 3628 April 2018. 3630 [I-D.camelot-holy-grenade] 3631 Pendragon, A., "The Holy Hand Grenade of Antioch", draft- 3632 camelot-holy-grenade-01 (work in progress), April 2018. 3634 [I-D.divination-cfapi] 3635 Destiny, G. and C. Luck, "An API For Calendar-Based 3636 Fortune Heuristics Services", draft-divination-cfapi-00 3637 (work in progress), March 2018. 3639 [I-D.wu-netmod-yang-xml-doc-conventions] 3640 Wu, Q., Farrel, A., and B. Claise, "Documentation 3641 Conventions for Expressing YANG in XML", draft-wu-netmod- 3642 yang-xml-doc-conventions-00 (work in progress), January 3643 2018. 3645 [IETF-BibXML] 3646 "IETF BibXML Library", November 2017, 3647 . 3649 [kramdown-rfc2629] 3650 Bormann, C., "kramdown-rfc2629: An RFC2629 (XML2RFC) 3651 backend for Thomas Leitner's kramdown markdown parser", 3652 Nov 2017, . 3654 [lyx2rfc] Williams, N., "LyX to I-D/RFC export by way of Lyx export 3655 to XHTML and XSLT conversion to xml2rfc schema", 2014, 3656 . 3658 [MathJax] "MathJax: A JavaScript display engine for mathematics that 3659 works in all browsers.", November 2017, 3660 . 3662 [mmark] Gieben, R., "Using mmark to create I-Ds and RFCs", June 3663 2015, . 3665 [NroffEdit] 3666 Santesson, S., "WYSIWYG Internet-Draft Nroff Editor", May 3667 2011, . 3669 [pandoc2rfc] 3670 Gieben, R., "pandoc2rfc: Use pandoc to create XML suitable 3671 for xml2rfc", 2012, . 3673 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3674 Requirement Levels", BCP 14, RFC 2119, 3675 DOI 10.17487/RFC2119, March 1997, 3676 . 3678 [RFC5385] Touch, J., "Version 2.0 Microsoft Word Template for 3679 Creating Internet Drafts and RFCs", RFC 5385, 3680 DOI 10.17487/RFC5385, February 2010, 3681 . 3683 [RFC7328] Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit 3684 of XML", RFC 7328, DOI 10.17487/RFC7328, August 2014, 3685 . 3687 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 3688 RFC 7749, DOI 10.17487/RFC7749, February 2016, 3689 . 3691 [RFC7763] Leonard, S., "The text/markdown Media Type", RFC 7763, 3692 DOI 10.17487/RFC7763, March 2016, 3693 . 3695 [RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies, 3696 Stability Strategies, and Select Registrations", RFC 7764, 3697 DOI 10.17487/RFC7764, March 2016, 3698 . 3700 [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990, 3701 DOI 10.17487/RFC7990, December 2016, 3702 . 3704 [RFC7996] Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", 3705 RFC 7996, DOI 10.17487/RFC7996, December 2016, 3706 . 3708 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3709 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3710 May 2017, . 3712 [TeX-LaTeX] 3713 "LaTeX is document preparation software that runs on top 3714 of Donald E. Knuth's TeX typesetting system.", November 3715 2017, . 3717 Appendix A. Examples 3719 A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" 3721 This example is available in the following formats: 3723 o AsciiRFC [git-asciirfc-minimal] 3725 o Internet-Draft [I-D.asciirfc-minimal] 3727 o Text, RFC XML, PDF and HTML on the IETF Datatracker 3728 [datatracker-asciirfc-minimal] 3730 A.1.1. In AsciiRFC 3732 3733 = A Minimal Internet-Draft In AsciiRFC 3734 :doctype: internet-draft 3735 :name: draft-asciirfc-minimal-02 3736 :abbrev: AsciiRFC Example 3737 :status: informational 3738 :ipr: trust200902 3739 :submissionType: individual 3740 :area: Internet 3741 :intended-series: full-standard 3742 :revdate: 2018-04-12T00:00:00Z 3743 :fullname: Josiah Stinkney Carberry 3744 :lastname: Carberry 3745 :forename_initials: J. S. 3746 :organization: Brown University 3747 :phone: +1 401 863 1000 3748 :street: Box K, 69 Brown Street 3749 :city: Providence 3750 :code: 02912 3751 :country: United States of America 3752 :uri: https://www.brown.edu 3753 :email: josiah.carberry@ribose.com 3754 :fullname_2: Truman Grayson 3755 :lastname_2: Grayson 3756 :forename_initials_2: T. 3757 :organization_2: Brown University 3758 :phone_2: +1 401 863 1000 3759 :street_2: Box G, 69 Brown Street 3760 :city_2: Providence 3761 :code_2: 02912 3762 :country_2: United States of America 3763 :uri_2: https://www.brown.edu 3764 :email_2: truman.grayson@ribose.com 3766 [abstract] 3768 This document provides a template on how to author (or migrate!) 3769 a new Internet-Draft / RFC in the AsciiRFC format. 3771 This template requires usage of the `asciidoctor-rfc` Ruby gem. 3773 [#introduction] 3774 == Introduction 3776 AsciiRFC <> is an extremely simple way to 3777 author Internet-Drafts and RFCs without needing to manually 3778 craft RFC XML conforming to <>. 3780 This is a template specifically made for authors to easily 3781 start with creating an Internet-Draft conforming to <> 3782 and submittable to the IETF datatracker. 3784 [#conventions] 3785 == Terms and Definitions 3787 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 3788 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 3789 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this 3790 document are to be interpreted as described in BCP 14 3791 <> <> when, and only when, they appear in 3792 all capitals, as shown here. 3794 This document also refers to the following terms and 3795 definitions: 3797 AsciiRFC:: 3798 an AsciiDoc-derived syntax used for authoring RFCs and 3799 Internet-Drafts, as defined in <>. 3801 [#symbols] 3802 == Symbols And Abbreviations 3804 ADRFC:: 3805 abbreviated form of AsciiRFC 3807 [#main] 3808 == Main content 3810 This is where you place the main content, and the following 3811 serves as a placeholder for your text. 3813 Subsections are used here for demonstration purposes. 3815 === Getting started 3817 The AsciiRFC and RFC toolchains *MUST* be available locally to 3818 build this document template. 3820 ==== AsciiRFC toolchain 3822 You will need to have: 3824 * Ruby: for running the AsciiRFC toolchain 3825 * `asciidoctor-rfc` gem: for converting AsciiRFC into XML RFC 3826 (v2 or v3) 3828 ==== XML RFC toolchain 3830 You will need to have: 3832 * Python: for running `xml2rfc` 3833 * `xml2rfc`: for converting RFC XML (v2 or v3) into TXT 3834 * `idnits`: for submission preflight 3836 === Referencing external content 3838 * This is a published RFC <> 3840 * This is an Internet-Draft <> 3842 * This is an external reference <> 3844 [#code-snippets] 3845 === Code snippets 3846 Code snippets should be wrapped with `` and 3847 `` blocks, as required by the IETF Trust Legal 3848 Provisions (TLP) <> specified in <>. 3850 [#security] 3851 == Security Considerations 3853 Any security considerations should be placed here. 3855 As described in <
> (here's how you refer a local anchor), 3856 local tools have to be installed before the document template 3857 can be built. 3859 Running of these local tools *MAY* produce unintended side 3860 effects that impact security. 3862 [#iana] 3863 == IANA Considerations 3865 This document does not require any action by IANA. 3867 But if it does, such as proposing changes to IANA registries, 3868 please include them here. 3870 // References must be given before appendixes 3872 [bibliography] 3873 == Normative References 3875 //bibliography::norm[] 3876 ++++ 3878 3880 3881 Key words for use in RFCs to Indicate Requirement 3882 Levels 3883 3884 3885 3886 3887 3888 In many standards track documents several words are 3889 used to signify the requirements in the specification. 3890 These words are often capitalized. This document defines 3891 these words as they should be interpreted in IETF 3892 documents. This document specifies an Internet Best 3893 Current Practices for the Internet Community, and 3894 requests discussion and suggestions for improvements. 3895 3896 3897 3898 3899 3900 3901 3903 3905 3906 The "xml2rfc" Version 3 Vocabulary 3907 3908 3909 3910 3911 3912 This document defines the "xml2rfc" 3913 version 3 vocabulary: an XML-based language used for 3914 writing RFCs and Internet-Drafts. It is heavily derived 3915 from the version 2 vocabulary that is also under 3916 discussion. This document obsoletes the v2 grammar 3917 described in RFC 7749. 3918 3919 3920 3921 3922 3924 3926 3927 Ambiguity of Uppercase vs Lowercase in RFC 2119 3928 Key Words 3929 3930 3931 3932 3933 3934 RFC 2119 specifies common key words that may be 3935 used in protocol specifications. This document aims to 3936 reduce the ambiguity by clarifying that only UPPERCASE 3937 usage of the key words have the defined special 3938 meanings. 3939 3940 3941 3942 3943 3944 3945 ++++ 3947 [bibliography] 3948 == Informative References 3950 //bibliography::info[] 3951 ++++ 3953 3955 3956 IETF Trust Legal Provisions (TLP) 3957 3958 IETF 3959 3960 3961 3962 3964 3965 3966 RNP: A C library approach to OpenPGP 3967 3968 Ribose Inc. 3969
3970 3971 Suite 1111, 1 Pedder Street 3972 Central 3973 Hong Kong 3974 Hong Kong 3975 3976 open.source@ribose.com 3977 https://www.ribose.com 3978
3979 3980 3981 3982 3984 3985 3986 3987 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 This document describes an AsciiDoc syntax 4004 extension called AsciiRFC, designed for authoring IETF 4005 Internet-Drafts and RFCs. AsciiDoc is a human readable document 4006 markup language which affords more granular control over markup 4007 than comparable schemes such as Markdown. The AsciiRFC syntax 4008 is designed to allow the author to entirely focus on text, 4009 providing the full power of the resulting RFC XML through the 4010 AsciiDoc language, while abstracting away the need to manually 4011 edit XML, including references. This document itself was 4012 written and generated into RFC XML v2 (RFC7749) and RFC XML v3 4013 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC 4014 generator. 4015 4016 4017 4018 4020 4022 4024 4025 Rights Contributors Provide to the IETF Trust 4026 4028 4029 4030 4032 4033 4034 4035 The IETF policies about rights in Contributions 4036 to the IETF are designed to ensure that such Contributions 4037 can be made available to the IETF and Internet communities 4038 while permitting the authors to retain as many rights as 4039 possible. This memo details the IETF policies on rights in 4040 Contributions to the IETF. It also describes the 4041 objectives that the policies are designed to meet. This 4042 memo obsoletes RFCs 3978 and 4748 and, with BCP 79 and 4043 RFC 5377, replaces Section 10 of RFC 2026. This document 4044 specifies an Internet Best Current Practices for the 4045 Internet Community, and requests discussion and 4046 suggestions for improvements. 4047 4048 4049 4050 4051 4053 4055 4056 The OCB Authenticated-Encryption Algorithm 4057 4058 4059 4060 4061 4062 4063 4064 This document specifies OCB, a shared-key 4065 blockcipher-based encryption scheme that provides 4066 confidentiality and authenticity for plaintexts and 4067 authenticity for associated data. This document is a product 4068 of the Crypto Forum Research Group (CFRG). 4069 4070 4071 4072 4073 ++++ 4075 [appendix] 4076 [#appendix-a] 4077 == Examples 4079 === Example 1 4081 Here's an example of a properly wrapped code snippet in 4082 accordance with rules specified in <>. 4084 [source,json] 4085 ---- 4086 4087 { 4088 "code": { 4089 "encoding": "ascii", 4090 "type": "rfc", 4091 "authors": [ "Josiah Carberry", "Truman Grayson" ] 4092 } 4093 } 4094 4095 ---- 4097 [#acknowledgements] 4098 == Acknowledgements 4100 The authors would like to thank their families. 4102 4104 A.1.2. Rendered as RFC XML v3 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4119 4120 A Minimal Internet-Draft In 4121 AsciiRFC 4122 4124 4126 4128 Brown University 4129
4130 4131 Box K, 69 Brown Street 4132 Providence 4133 02912 4134 United States of America 4135 4136 +1 401 863 1000 4137 josiah.carberry@ribose.com 4138 https://www.brown.edu 4139
4140 4141 4142 Brown University 4143
4144 4145 Box G, 69 Brown Street 4146 Providence 4147 02912 4148 United States of America 4149 4150 +1 401 863 1000 4151 truman.grayson@ribose.com 4152 https://www.brown.edu 4153
4154 4155 4156 Internet 4158 This document provides a template on how to author (or 4159 migrate!) 4160 a new Internet-Draft / RFC in the AsciiRFC format. 4161 This template requires usage of the asciidoctor-rfc Ruby 4162 gem. 4163 4164
IntroductionAsciiRFC is an extremely simple way to 4167 author Internet-Drafts and RFCs without needing to manually 4168 craft RFC XML conforming to . 4169 This is a template specifically made for authors to easily 4170 start with creating an Internet-Draft conforming to 4172 and submittable to the IETF datatracker.
4173
Terms and 4174 DefinitionsThe key words "MUST", "MUST 4175 NOT", "REQUIRED", "SHALL", 4176 "SHALL NOT", "SHOULD", "SHOULD 4177 NOT", "RECOMMENDED", 4178 "NOT RECOMMENDED", "MAY", and 4179 "OPTIONAL" in this 4180 document are to be interpreted as described in BCP 14 4181 when, and only when, 4182 they appear in 4183 all capitals, as shown here. 4184 This document also refers to the following terms and 4185 definitions: 4186
4187
AsciiRFC
4188
an AsciiDoc-derived syntax used for authoring RFCs and 4189 Internet-Drafts, as defined in .
4191
4192
4193 Symbols And Abbreviations 4194
4195
ADRFC
4196
abbreviated form of AsciiRFC
4197
4198
4199
Main 4200 contentThis is where you place the main content, and the 4201 following 4202 serves as a placeholder for your text. 4203 Subsections are used here for demonstration purposes. 4204
Getting 4205 startedThe AsciiRFC and RFC toolchains MUST be 4206 available locally to 4207 build this document template. 4208
AsciiRFC 4209 toolchainYou will need to have: 4210
    4211
  • Ruby: for running the AsciiRFC toolchain
    • 4212
  • asciidoctor-rfc gem: for converting AsciiRFC into XML RFC 4213 (v2 or v3)
    • 4214
4215
XML RFC 4216 toolchainYou will need to have: 4217
    4218
  • Python: for running xml2rfc
    • 4219
  • xml2rfc: for converting RFC XML (v2 or v3) into TXT
    • 4220
  • idnits: for submission preflight
    • 4221
4222
4223 Referencing external content 4224
    4225
  • This is a published RFC
    • 4226
  • This is an Internet-Draft
    • 4228
  • This is an external reference
    • 4229
4230
4231
4232 Code snippets 4233 Code snippets should be wrapped with <CODE BEGINS> 4234 and 4235 <CODE ENDS> blocks, as required by the IETF Trust Legal 4236 Provisions (TLP) specified in . 4238
4239
Security 4240 ConsiderationsAny security considerations should be placed 4241 here. 4242 As described in (here’s how you refer a 4243 local anchor), 4244 local tools have to be installed before the document template 4245 can be built. 4246 Running of these local tools MAY produce unintended 4247 side 4248 effects that impact security.
4249
IANA 4250 ConsiderationsThis document does not require any action by 4251 IANA. 4252 But if it does, such as proposing changes to IANA registries, 4253 please include them here.
4254 4255 4256 Normative References 4257 4261 4265 4269 4270 4271 Informative References 4272 4274 4275 IETF Trust Legal Provisions (TLP) 4276 4277 IETF 4278 4279 4280 4281 4282 4283 4284 RNP: A C library approach to OpenPGP 4285 4286 Ribose Inc. 4287
4288 4289 Suite 1111, 1 Pedder Street 4290 Central 4291 Hong Kong 4292 Hong Kong 4293 4294 open.source@ribose.com 4295 https://www.ribose.com 4296
4297 4298 4299 4300 4301 4305 4309 4313 4314
4315 Examples 4316
Example 4317 1Here’s an example of a properly wrapped code snippet in 4318 accordance with rules specified in . 4319
4320 4322 { 4323 "code": { 4324 "encoding": "ascii", 4325 "type": "rfc", 4326 "authors": [ "Josiah Carberry", "Truman Grayson" ] 4327 } 4328 } 4329 4330 ]]> 4331
4332
4333
4334 Acknowledgements 4335 The authors would like to thank their families. 4336
4337 4338 4339 4341 A.2. Example 2: "The Holy Hand Grenade of Antioch" 4343 This example is available in the following formats: 4345 o AsciiRFC [git-camelot-holy-grenade] 4347 o Internet-Draft [I-D.camelot-holy-grenade] 4349 o Text, RFC XML, PDF and HTML on the IETF Datatracker 4350 [datatracker-camelot-holy-grenade] 4352 A.2.1. In AsciiRFC 4354 4355 = The Holy Hand Grenade of Antioch 4356 Arthur son of Uther Pendragon 4357 :doctype: internet-draft 4358 :abbrev: Hand Grenade of Antioch 4359 :updates: 8140 4360 :submission-type: independent 4361 :name: draft-camelot-holy-grenade-01 4362 :status: informational 4363 :consensus: false 4364 :area: General, Operations and Management 4365 :keyword: rabbits, grenades, antioch, camelot 4366 :ipr: trust200902 4367 :toc-include: true 4368 :sort-refs: true 4369 :revdate: 2018-04-15T00:00:00Z 4370 :fullname: Arthur son of Uther Pendragon 4371 :forename_initials: A. 4372 :lastname: Pendragon 4373 :email: arthur.pendragon@ribose.com 4374 :organization: Camelot 4375 :uri: http://camelot.gov.example 4376 :street: Palace\ Camel Lot 1 4377 :city: Camelot 4378 :region: England 4379 :country: United Kingdom 4380 :comments: yes 4381 :notedraftinprogress: yes 4382 :smart-quotes: false 4384 [.comment] 4385 tag::preamble1[] 4386 // tag::preamble[] 4388 [abstract] 4389 The menagerie of beasts and artefacts depicted in RFC8140 4390 may be usefully supplemented by other renowned figures of 4391 Internet and more general lore. This document extends the 4392 menagerie to the seminal fable of the 4393 "Holy Hand Grenade of Antioch", as depicted in the 4394 Monty Python film "Monty Python and the Holy Grail", 4395 as well as "Spamalot", the musical inspired by the movie. 4397 [NOTE,remove-in-rfc=false] 4398 .Spamalot 4399 The relevance of the musical "Spamalot" to Internet lore should be 4400 obvious to the reader; but in case of doubt, see also 4401 Section 1 ("What is Spam*?") of RFC2635. 4403 // end::preamble[] 4404 [.comment] 4405 end::preamble1[] 4407 [.comment] 4408 tag::sectnums1[] 4409 // tag::sectnums[] 4411 [toc=exclude] 4412 :sectnums!: 4413 == Terminology 4415 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 4416 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 4417 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 4418 are to be interpreted as described in BCP 14 <> <> 4419 when, and only when, they appear in all capitals, as shown here. 4421 :sectnums: 4422 == Introduction 4424 <> refers to the intended move of RFC formatting to 4425 XML2RFC v3 <>, in the following terms: 4427 // end::sectnums[] 4428 [.comment] 4429 end::sectnums1[] 4431 [.comment] 4432 tag::quote1[] 4433 // tag::quote[] 4435 [quote,attribution="A. Farrel"] 4436 ____ 4437 Although the RFC Editor has recently dragged the IETF kicking and 4438 screaming into the twentieth century [RFC7990] [RFC7996], there is a 4439 yearning among all right-thinking Internet architects to "keep it 4440 simple" and to return to the olden days when pigs could be given 4441 thrust without anyone taking undue offence. 4442 ____ 4444 // end::quote[] 4445 [.comment] 4446 end::quote1[] 4448 While no pigs, flying or otherwise, are involved in the transition 4449 to RFC XML v3, it is opportune to enhance the <> 4450 legendarium in the service of RFC XML v3, by illustrating its 4451 functionality through references to the mythology of Camelot, and 4452 particularly the incidents at the Cave of Caerbannog. 4454 [.comment] 4455 tag::escaped_hyperlink1[] 4456 // tag::escaped_hyperlink[] 4458 The screaming move into the twenty-*first* century is accompanied by 4459 a move back to the late twentieth century, with ASCII stylings more 4460 wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be 4461 accessible in 1996.) 4463 // end::escaped_hyperlink[] 4464 [.comment] 4465 end::escaped_hyperlink1[] 4467 There are two references to rabbits in 4468 _Monty Python and the Holy Grail_ which are expounded on herewith: 4470 [.comment] 4471 tag::listcontinuation1[] 4472 // tag::listcontinuation[] 4474 Trojan Rabbit:: 4475 In their siege of the French-occupied castle which may already 4476 contain an instance of the Grail, Sir Bedevere the Wise proposes to 4477 use a Trojan Rabbit to infiltrate the castle, with a raiding party 4478 to take the French "not only by surprise, but totally unarmed." 4479 + 4480 The proposal, unsurprisingly, proved abortive. The more so as the 4481 raiding party forgot to hide within the Trojan Rabbit, before the 4482 French soldiers took the Trojan Rabbit inside the castle. 4484 Killer Rabbit of Caerbannog:: 4485 Guarding the entrance to the Cave of Caerbannog; see <>. 4487 // end::listcontinuation[] 4488 [.comment] 4489 end::listcontinuation1[] 4491 == The French-occupied castle 4493 [.comment] 4494 tag::inline_formatting1[] 4495 // tag::inline_formatting[] 4497 The participants of that renowned exercise in cross-cultural 4498 communication, to wit the exchange between the 4499 _Knights of the Round Table_ 4500 and the taunting French soldiers serving under *Guy de Lombard* are, 4501 properly speaking, outside the scope of this `menagerie`, being more 4502 or less human. Notwithstanding, several^ish^ beasts both animate~d~ 4503 and wooden played a significant part in this encounter; most 4504 notably: 4506 * The Projectile Cow, see <> 4507 * The Trojan Rabbit, see <> 4509 // end::inline_formatting[] 4510 [.comment] 4511 end::inline_formatting1[] 4513 [[projectile-cow]] 4514 .The Projectile Cow with an accompanying cannon 4515 ==== 4516 [alt=The Projectile Cow with an accompanying cannon in ASCII] 4517 .... 4518 .-.-.-.-.-.-.-.-.-.-.-.--.-.-.-.-.-.-.--.-.-.-.-.-.-.-.--.-. 4519 _-_---__--__--___-___-__-____---___-________---____-____-__- 4520 ._.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.--..-.-.-.-.-.-..--.- 4521 ,..,.,.,.,.,..,.,,..,.,.,.,.,.,, ^^ .,,.,., ^^ .,.,.,.= 4522 _>-.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-. 4523 .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., 4524 .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # .,.,.,. 4525 .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. 4526 .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ` `] .,.,..,.,.- 4527 .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_} . ., . . , 4528 .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / -.-<>.,.,..-.-, 4529 .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. 4530 .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- 4531 .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. 4532 .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- 4533 .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- 4534 -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- 4535 ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, 4536 ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- 4537 ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. 4538 .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., 4539 .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,., 4540 ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,., 4541 ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. 4542 .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. 4543 -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> 4544 _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,.. 4545 .._...{WITH_HONEY}-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_.. 4546 GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASSPC 4547 SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS_SOIL 4548 CLAY_ROCKS_PEBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY><_WORM 4549 ROOTS_CLAY_SKELETON_MORESOIL_CLAY_CLAY_CLAY_CLAY_ 4550 .... 4551 ==== 4553 [[trojan-rabbit]] 4554 .The Trojan Rabbit with an automatic sliding door 4555 ==== 4556 [alt=The Trojan Rabbit with an automatic sliding door, in ASCII] 4557 .... 4558 ___ ____ 4559 //_ \//\__\ 4560 || || | 4561 -__||_||__| 4562 // \--_ 4563 // ____ --___ 4564 // // \ \-_ 4566 // \\ @/ o || 4567 // ---- _____|| 4568 // // 4569 //\_//__ // 4570 //-- --- \____ // 4571 // --- \______ // 4572 // , . ----- \_//_ 4573 // ,. --- \____ 4574 // .,v --- \___ 4575 // __ -- \_ 4576 || , _______________ //|| |-_ 4577 || | |''''''''''| // || | | 4578 || ' | | | || | | 4579 || | | | || | | 4580 || " | | 0 | ___||___ | | 4581 || | | | -------- | | 4582 ||___ | | | ______ | |- 4583 // \ | | | // \| _| \ 4584 // \ ____|---|__________|______// \/ | 4585 || X | / || X | / 4586 \\ /\\____/ \\ /___/ 4587 \\_____/ ----- \\_____/--- 4588 ----- ----- 4589 .... 4590 ==== 4592 [.comment] 4593 tag::aside1[] 4594 // tag::aside[] 4596 **** 4597 While the exchange at the French-occupied castle is one of 4598 the more memorable scenes of _Monty Python and the Holy Grail_, 4599 the Trojan Rabbit has not reached the same level of cultural 4600 resonance as its more murderous counterpart. Reasons for this 4601 may include: 4603 * Less overall screen-time dedicated to the Trojan Rabbit. 4605 * The Trojan Rabbit as projectile has already been anticipated 4606 by the Cow as projectile. 4607 **** 4609 // end::aside[] 4611 [.comment] 4612 end::aside1[] 4614 [.comment] 4615 tag::note1[] 4616 // tag::note[] 4618 [NOTE,display=true,source=Author] 4619 ==== 4620 Image courtesy of 4621 https://camelot.gov.example/creatures-in-ascii/ 4622 ==== 4624 // end::note[] 4625 [.comment] 4626 end::note1[] 4628 [.comment] 4629 tag::comment1[] 4630 // tag::comment[] 4632 The exchange of projectile animals was the beginning of a 4633 long-running fruitful relationship between the British and the 4634 French peoples, 4635 [comment]#TODO: Will need to verify that claim.# which 4636 arguably predates the traditional English enmity with the 4637 French. [comment]#Strictly speaking, the Knights are Welsh.# 4639 [.comment] 4640 -- 4641 This document, as it turns out, has a profusion of XML comments. 4643 As expected, they are ignored in any rendering of the document. 4644 -- 4646 // end::comment[] 4647 [.comment] 4648 end::comment1[] 4650 [[caerbannog]] 4651 == The Mythos of Caerbannog 4653 [.comment] 4654 tag::xref1[] 4655 // tag::xref[] 4657 The _Cave of Caerbannog_ has been well-established in the mythology 4658 of Camelot (as recounted by Monty Python) as the lair of the 4659 Legendary Black Beast of Arrrghhh, more commonly known today as the 4660 *Killer Rabbit of Caerbannog* <>. 4661 It is the encounter between the Killer Rabbit of Caerbannog and the 4662 Knights of the Round Table, armed with the Holy Hand Grenade of 4663 Antioch (see the <>), that we 4664 recount here through monospace font and multiple spaces. 4666 [[killer_rabbit_caerbannog]] 4667 === The Killer Rabbit of Caerbannog 4669 // end::xref[] 4670 [.comment] 4671 end::xref1[] 4673 [.comment] 4674 tag::relref1[] 4675 // tag::relref[] 4677 The *Killer Rabbit of Caerbannog*, that most formidable foe of 4678 the Knights and of all that is holy or carrot-like, has been 4679 depicted diversely in lay and in song. We venture to say, 4680 _contra_ the claim made in <>, 4681 that the Killer Rabbit of Caerbannog truly is the most afeared 4682 of all the creatures. Short of sanctified ordnance such as 4683 <>, there are few remedies 4684 known against its awful lapine powers. 4686 // end::relref[] 4687 [.comment] 4688 end::relref1[] 4690 [.comment] 4691 tag::hyperlink1[] 4692 // tag::hyperlink[] 4694 <> of the fearsome beast 4695 has been sourced from 4696 http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], 4697 <> 4698 by C code that was used in this accurate depiction of the 4699 Killer Rabbit: 4701 // end::hyperlink[] 4702 [.comment] 4703 end::hyperlink1[] 4705 [.comment] 4706 tag::figure1[] 4707 // tag::figure1a[] 4709 [[killer-bunny]] 4710 .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 4711 ==== 4712 [alt=The Killer Bunny, in ASCII] 4713 .... 4714 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4715 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4716 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 4717 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 4718 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 4719 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 4720 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 4721 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 4722 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 4723 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 4724 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 4725 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 4726 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 4727 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 4728 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 4729 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 4730 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 4731 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 4732 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 4733 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 4734 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 4735 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 4736 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 4737 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 4738 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 4739 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 4740 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 4741 MW \\/\||v v|| -\\-------___ . ., \ | 4742 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 4743 ) /--------^-^ ,. \|// 4744 # \(/ .\\|x// " ' ' 4745 . , \\||// \||\\\// \\ 4746 .... 4747 ==== 4749 [[killer-source]] 4750 .C Code To Lure Killer Rabbit Back To Cave 4751 ==== 4752 [source,c] 4753 ---- 4754 4755 /* Locate the Killer Rabbit */ 4756 int type; 4757 unsigned char *killerRabbit = 4758 LocateCreature(&caerbannog, "killer rabbit"); 4759 if( killerRabbit == 0 ){ 4760 puts("The Killer Rabbit of Caerbannog is out of town."); 4761 return LOST_CREATURE; 4762 } 4764 /* Load Cave */ 4765 unsigned char *cave = LoadPlace(&caerbannog, 4766 "The Cave Of Caerbannog"); 4767 if( cave == 0 ){ 4768 puts("The Cave of Caerbannog must have moved."); 4769 return LOST_PLACE; 4770 } 4772 /* Lure the Killer Rabbit back into the Cave */ 4773 unsigned char *carrot = allocateObjectInPlace( 4774 carrot("fresh"), cave); 4775 if( carrot == 0 ){ 4776 puts("No carrot, no rabbit."); 4777 return LOST_LURE; 4778 } 4780 /* Finally, notify the Killer Rabbit to act */ 4781 return notifyCreature(killerRabbit, &carrot); 4782 4783 ---- 4784 ==== 4786 // end::figure1a[] 4787 [.comment] 4788 end::figure1[] 4790 On the beast's encounter with the Knights of the Round Table, 4791 the following personnel engaged with it in combat: 4793 [.comment] 4794 tag::ul1[] 4795 // tag::ul[] 4797 * Killed 4798 ** Sir Bors 4799 ** Sir Gawain 4800 ** Sir Ector 4801 * Soiled Himself 4802 ** Sir Robin 4803 * Panicked 4804 ** King Arthur 4805 * Employed Ordnance 4806 ** The Lector 4807 ** Brother Maynard 4808 * Scoffed 4809 ** Tim the Enchanter 4811 // end::ul[] 4812 [.comment] 4813 end::ul1[] 4815 [[holy_hand_grenade]] 4816 === Holy Hand Grenade of Antioch 4818 [.comment] 4819 tag::figure2[] 4821 // tag::figure2a[] 4823 [[hand-grenade-figure]] 4824 .The Holy Hand Grenade of Antioch (don't pull the pin) 4825 ==== 4826 [alt=Holy Hand Grenade of Antioch, in ASCII] 4827 .... 4828 ______ 4829 \\/ \/ 4830 __\\ /__ 4831 || //\ | 4832 ||__\\/ __| 4833 || | ,---, 4834 || |====`\ | 4835 || | '---' 4836 ,--'*`--, 4837 _||#|***|#| 4838 _,/.-'#|* *|#`-._ 4839 ,,-'#####| |#####`-. 4840 ,,'########| |########`, 4841 //##########| o |##########\ 4842 ||###########| |###########| 4843 ||############| o |############| 4844 ||------------' '------------| 4845 ||o o o o o o o o o o| 4846 |-----------------------------| 4847 ||###########################| 4848 \\#########################/ 4849 `..#####################,' 4850 ``..###############_,' 4851 ``--.._____..--' 4852 `''-----''` 4853 .... 4854 ==== 4856 // end::figure2a[] 4858 [.comment] 4859 end::figure2[] 4861 [[sovereign-orb]] 4862 .The Sovereign's Orb made invisible 4863 ==== 4864 .Outlines of the Sovereign's Orb 4865 [link=https://camelot.gov.example/sovereigns_orb.jpg,align=right] 4866 image::https://camelot.gov.example/sovereigns_orb.jpg[Orb,124,135] 4867 ==== 4869 [.comment] 4870 tag::index1[] 4871 // tag::index[] 4873 The solution to the impasse at the ((Cave of Caerbannog)) was 4874 provided by the successful deployment of the 4875 *Holy Hand Grenade of Antioch* (see <>) 4876 (((Holy Hand Grenade of Antioch))). 4877 Any similarity between the Holy Hand Grenade of Antioch and the 4878 mythical _Holy Spear of Antioch_ is purely intentional; 4879 (((relics, Christian))) any similarity between the Holy Hand Grenade 4880 of Antioch and the _Sovereign's Orb of the United Kingdom_ 4881 (see <>) is putatively fortuitous. 4882 (((relics, monarchic))) 4884 // end::index[] 4885 [.comment] 4886 end::index1[] 4888 [.comment] 4889 tag::dl1[] 4890 // tag::dl[] 4892 Holy Hand Grenade of Antioch:: 4893 Ordnance deployed by Brother Maynard under the incantation of a 4894 lector, in order to dispense with the Foes of the Virtuous. 4895 See <>. 4897 Holy Spear of Antioch:: 4898 A supposed relic of the crucifixion of Jesus Christ, this is one 4899 of at least four claimed instances of the lance that pierced 4900 Christ's side. Its historical significance lies in inspiring 4901 crusaders to continue their siege of Antioch in 1098. 4903 Sovereign's Orb of the United Kingdom:: 4904 Part of the Crown Jewels of the United Kingdom, the Sovereign's 4905 Orb is a hollow gold sphere set with jewels and topped with a 4906 cross. It was made for Charles II in 1661. See <>. 4908 // end::dl[] 4909 [.comment] 4910 end::dl1[] 4912 [.comment] 4913 tag::bcp14_1[] 4914 // tag::bcp14[] 4916 The instructions in the _Book of Armaments_ on the proper deployment 4917 of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as 4918 follows, although this summary *SHALL NOT* be used as a substitute 4919 for a reading from the Book of Armaments: 4921 // end::bcp14[] 4922 [.comment] 4923 end::bcp14_1[] 4925 [.comment] 4926 tag::ol1[] 4927 // tag::ol[] 4929 . Preamble: St Attila Benediction 4930 . Feast of the People on Sundry Foods 4931 ** Lambs 4932 ** Sloths 4933 ** Carp 4934 ** Anchovies 4935 ** Orangutangs 4936 ** Breakfast Cereals 4937 ** Fruit Bats 4938 ** _et hoc genus omne_ 4939 . Take out the Holy Pin 4940 . The Count 4941 [upperalpha] 4942 .. Count is to Three: no more, no less 4943 .. Not Four 4944 .. Nor Two, except if the count then proceeds to Three 4945 .. Five is Right Out 4946 . Lob the Holy Hand Grenade of Antioch towards the Foe 4947 . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it 4949 // end::ol[] 4950 [.comment] 4951 end::ol1[] 4953 This could also be represented in pseudocode as follows: 4955 [.comment] 4956 tag::listcontinuationblock1[] 4957 // tag::listcontinuationblock[] 4959 . Take out the Holy Pin 4960 . The Count 4961 + 4962 ---- 4963 integer count; 4964 for count := 1 step 1 until 3 do 4965 say(count) 4966 comment Five is Right Out 4967 ---- 4968 . Lob the Holy Hand Grenade of Antioch towards the Foe 4969 . Foe snuffs it 4971 // end::listcontinuationblock[] 4972 [.comment] 4973 end::listcontinuationblock1[] 4975 == Dramatis Personae 4977 The following human (more-or-less) protagonists were involved 4978 in the two incidents recounted as lore of the Knights of the 4979 Round Table: 4981 [.comment] 4982 tag::table1[] 4983 // tag::table[] 4985 [grid=all,options="footer"] 4986 |=== 4987 |French Castle | Cave of Caerbannog 4989 2+|King Arthur 4990 2+|Patsy 4991 2+|Sir Bedevere the Wise 4992 2+|Sir Galahad the Pure 4993 2+|Sir Lancelot the Brave 4994 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot 4995 |French Guard with Outrageous Accent| Tim the Enchanter 4996 |Other French Guards | Brother Maynard 4997 | | The Lector 4998 .3+^|not yet recruited 4999 >|Sir Bors 5000 >|Sir Gawain 5001 >|Sir Ector 5003 |Retinue of sundry knights 5004 |Retinue of sundry more knights than at the French Castle 5005 |=== 5007 // end::table[] 5008 [.comment] 5009 end::table1[] 5011 === Past the Killer Rabbit 5013 Once the Killer Rabbit of Caerbannog (<>) had been 5014 dispatched, the Knights of the Round Table uncovered the last 5015 words of Joseph of Arimathea, inscribed on the Cave of Caerbannog 5016 in Aramaic. While the precise Aramaic wording has not survived, 5017 we trust the following Hebrew subtitles will serve as an 5018 acceptable substitute: 5020 [.comment] 5021 tag::hebrew1[] 5022 // tag::hebrew[] 5024 ____ 5025 .כאן אולי 5026 ימצאו 5027 המילים 5028 האחרונות של 5029 יוסף 5030 .מארמתיה 5031 .מי אשר יהיה 5032 אמיץ ובעל 5033 נפש טהורה 5034 יוכל למצוא 5035 את הגביע 5036 הקדוש בטירת 5037 .אאאאאאאה 5039 "Here may be found the last words of Joseph of Arimathea. 5041 He who is valiant and pure of spirit may find the Holy Grail 5042 in the castle of — Aaaargh." 5043 ____ 5045 // end::hebrew[] 5046 [.comment] 5047 end::hebrew1[] 5049 == IANA Considerations 5051 IANA might consider a registry to track the mythical, especially 5052 ravaging beasts, such as the Killer Rabbit, who haunt the Internet. 5054 == Security Considerations 5056 Do not let the Killer Rabbit out under any circumstance. 5058 I repeat. Do not let the Killer Rabbit (<>) out. 5060 [.comment] 5061 tag::bibliography1[] 5062 // tag::bibliography[] 5064 [bibliography] 5065 == Normative References 5066 ++++ 5067 5069 5070 Key words for use in RFCs to Indicate 5071 Requirement Levels 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 ++++ 5083 [bibliography] 5084 == Informative References 5085 ++++ 5087 5088 5089 Monty Python and the Holy Grail 5090 5091 5092 5093 5094 5095 5096 5097 5098 5100 5102 5103 DON'T SPEW A Set of Guidelines for Mass Unsolicited 5104 Mailings and Postings (spam*) 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5118 5120 5121 RFC Format Framework 5122 5123 5124 5125 5126 5127 5128 5129 5131 5133 5134 5135 The Arte of ASCII: Or, An True and Accurate Representation of 5136 an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of 5137 Character 5138 5139 5140 5141 5142 5143 5144 5145 5146 5148 5150 5151 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 5152 Words 5153 5154 5155 5156 5157 RFC 2119 specifies common key words that may be used 5158 in protocol specifications. This document aims to reduce 5159 the ambiguity by clarifying that only UPPERCASE usage of the 5160 key words have the defined special meanings. 5161 5162 5163 5164 5165 5167 ++++ 5169 // end::bibliography[] 5170 [.comment] 5171 end::bibliography1[] 5172 5174 A.2.2. Rendered as RFC XML v3 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5193 5194 The Holy Hand Grenade of 5195 Antioch 5196 5198 5200 Camelot 5201
5202 5203 Palace 5204 Camel Lot 1 5205 Camelot 5206 England 5207 United Kingdom 5208 5209 arthur.pendragon@ribose.com 5210 http://camelot.gov.example 5211
5212 5213 5214 General 5215 Operations and Management 5216 rabbits 5217 grenades 5218 antioch 5219 camelot 5221 5223 5225 The menagerie of beasts and artefacts depicted in RFC8140 5226 may be usefully supplemented by other renowned figures of 5227 Internet and more general lore. This document extends the 5228 menagerie to the seminal fable of the 5229 "Holy Hand Grenade of Antioch", as depicted in the 5230 Monty Python film "Monty Python and the Holy Grail", 5231 as well as "Spamalot", the musical inspired by the 5232 movie. 5233 Spamalot 5234 The relevance of the musical "Spamalot" to Internet lore should be 5235 obvious to the reader; but in case of doubt, see also 5236 Section 1 ("What is Spam*?") of RFC2635. 5237 5239 5241 5243 5244
5245 Terminology 5246 The key words "MUST", "MUST NOT", 5247 "REQUIRED", "SHALL", 5248 "SHALL NOT", "SHOULD", "SHOULD 5249 NOT", "RECOMMENDED", 5250 "NOT RECOMMENDED", "MAY", and 5251 "OPTIONAL" in this document 5252 are to be interpreted as described in BCP 14 5253 5254 when, and only when, they appear in all capitals, as shown here. 5255
5256
Introduction refers to 5258 the intended move of RFC formatting to 5259 XML2RFC v3 , in the following terms: 5261 5263 5265
5266 Although the RFC Editor has recently dragged the IETF kicking and 5267 screaming into the twentieth century [RFC7990] [RFC7996], there is a 5268 yearning among all right-thinking Internet architects to "keep it 5269 simple" and to return to the olden days when pigs could be given 5270 thrust without anyone taking undue offence. 5271
5273 5275 While no pigs, flying or otherwise, are involved in the transition 5276 to RFC XML v3, it is opportune to enhance the 5277 legendarium in the service of RFC XML v3, by illustrating its 5278 functionality through references to the mythology of Camelot, and 5279 particularly the incidents at the Cave of Caerbannog. 5281 5283 The screaming move into the twenty-first century is 5284 accompanied by 5285 a move back to the late twentieth century, with ASCII stylings more 5286 wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be 5287 accessible in 1996.) 5289 5291 There are two references to rabbits in 5292 Monty Python and the Holy Grail which are expounded on 5293 herewith: 5295 5297
5298
Trojan Rabbit
5299
5300 In their siege of the French-occupied castle which may already 5301 contain an instance of the Grail, Sir Bedevere the Wise proposes to 5302 use a Trojan Rabbit to infiltrate the castle, with a raiding party 5303 to take the French "not only by surprise, but totally unarmed." 5304 The proposal, unsurprisingly, proved abortive. The more so as the 5305 raiding party forgot to hide within the Trojan Rabbit, before the 5306 French soldiers took the Trojan Rabbit inside the castle. 5307
5308
Killer Rabbit of Caerbannog
5309
Guarding the entrance to the Cave of Caerbannog; see .
5311
5313 5315
5316
The French-occupied castle 5319 5321 The participants of that renowned exercise in cross-cultural 5322 communication, to wit the exchange between the 5323 Knights of the Round Table 5324 and the taunting French soldiers serving under Guy de 5325 Lombard are, 5326 properly speaking, outside the scope of this menagerie, being 5327 more 5328 or less human. Notwithstanding, severalish beasts both 5329 animated 5330 and wooden played a significant part in this encounter; most 5331 notably: 5332
    5333
  • The Projectile Cow, see
    • 5334
  • The Trojan Rabbit, see
    • 5335
5337 5339
5340 The Projectile Cow with an accompanying cannon 5341 -.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-. 5348 .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., 5349 .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # .,.,.,. 5351 .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. 5352 .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ` `] .,.,..,.,.- 5353 .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_} . ., . . , 5354 .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / -.-<>.,.,..-.-, 5355 .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. 5356 .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- 5357 .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. 5358 .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- 5359 .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- 5360 -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- 5361 ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, 5362 ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- 5363 ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. 5364 .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., 5365 .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,., 5366 ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,., 5367 ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. 5368 .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. 5369 -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> 5370 _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,.. 5371 .._...{WITH_HONEY}-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_.. 5372 GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASSPC 5373 SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS_SOIL 5374 CLAY_ROCKS_PEBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY><_WORM 5375 ROOTS_CLAY_SKELETON_MORESOIL_CLAY_CLAY_CLAY_CLAY_ 5376 ]]> 5377
5378
5379 The Trojan Rabbit with an automatic sliding door 5380 5414
5416 5418 5429 5431 5433 Image courtesy of 5434 5437 5438 5440 The exchange of projectile animals was the beginning of a 5441 long-running fruitful relationship between the British and the 5442 French peoples, 5444 5446 which 5447 arguably predates the traditional English enmity with the 5448 French. 5450 5452 5454 5459 5461
5462
The Mythos of 5463 Caerbannog 5465 5467 The Cave of Caerbannog has been well-established in the 5468 mythology 5469 of Camelot (as recounted by Monty Python) as the lair of the 5470 Legendary Black Beast of Arrrghhh, more commonly known today as the 5471 Killer Rabbit of Caerbannog . 5473 It is the encounter between the Killer Rabbit of Caerbannog and the 5474 Knights of the Round Table, armed with the Holy Hand Grenade of 5475 Antioch (see the following 5476 section), that we 5477 recount here through monospace font and multiple spaces. 5478
The 5479 Killer Rabbit of Caerbannog 5481 5483 5485 The Killer Rabbit of Caerbannog, that most 5486 formidable foe of 5487 the Knights and of all that is holy or carrot-like, has been 5488 depicted diversely in lay and in song. We venture to say, 5489 contra the claim made in Ze Vompyre, 5491 that the Killer Rabbit of Caerbannog truly is the most afeared 5492 of all the creatures. Short of sanctified ordnance such as 5493 , there are few 5494 remedies 5495 known against its awful lapine powers. 5497 5499 5501 The following depiction of the 5502 fearsome beast 5503 has been sourced from 5504 Rabbit-SCII, 5506 accompanied 5507 by C code that was used in this accurate depiction of the 5508 Killer Rabbit: 5510 5512 5513
5514 A Photo Of The Killer Rabbit of Caerbannog Taken In 5515 Secret 5516 >>\\\\\\\\\\\\ 5521 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 5522 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 5523 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 5524 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 5525 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 5526 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 5527 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 5528 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 5529 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 5530 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 5531 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 5532 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 5533 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 5534 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 5535 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 5536 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 5537 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 5538 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 5539 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 5540 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 5541 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 5542 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 5543 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 5544 MW \\/\||v v|| -\\-------___ . ., \ | 5545 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 5546 ) /--------^-^ ,. \|// 5547 # \(/ .\\|x// " ' ' 5548 . , \\||// \||\\\// \\ 5549 ]]> 5550
5551
5552 C Code To Lure Killer Rabbit Back To Cave 5553 5555 /* Locate the Killer Rabbit */ 5556 int type; 5557 unsigned char *killerRabbit = 5558 LocateCreature(&caerbannog, "killer rabbit"); 5559 if( killerRabbit == 0 ){ 5560 puts("The Killer Rabbit of Caerbannog is out of town."); 5561 return LOST_CREATURE; 5562 } 5564 /* Load Cave */ 5565 unsigned char *cave = LoadPlace(&caerbannog, 5566 "The Cave Of Caerbannog"); 5567 if( cave == 0 ){ 5568 puts("The Cave of Caerbannog must have moved."); 5569 return LOST_PLACE; 5570 } 5572 /* Lure the Killer Rabbit back into the Cave */ 5573 unsigned char *carrot = allocateObjectInPlace( 5574 carrot("fresh"), cave); 5575 if( carrot == 0 ){ 5576 puts("No carrot, no rabbit."); 5577 return LOST_LURE; 5578 } 5580 /* Finally, notify the Killer Rabbit to act */ 5581 return notifyCreature(killerRabbit, &carrot); 5582 5583 ]]> 5584
5586 5588 On the beast's encounter with the Knights of the Round Table, 5589 the following personnel engaged with it in combat: 5591 5593
    5594
  • 5595 Killed 5596
      5597
    • Sir Bors
      • 5598
    • Sir Gawain
      • 5599
    • Sir Ector
      • 5600
    5601
    • 5602
  • 5603 Soiled Himself 5604
      5605
    • Sir Robin
      • 5606
    5607
    • 5608
  • 5609 Panicked 5610
      5611
    • King Arthur
      • 5612
    5613
    • 5614
  • 5615 Employed Ordnance 5616
      5617
    • The Lector
      • 5618
    • Brother Maynard
      • 5619
    5620
    • 5621
  • 5622 Scoffed 5623
      5624
    • Tim the Enchanter
      • 5625
    5626
    • 5627
5629 5631
5632
Holy Hand 5633 Grenade of Antioch 5635 5637
5638 The Holy Hand Grenade of Antioch (don't pull the pin) 5639 5668
5670 5672
5673 The Sovereign's Orb made invisible 5674 5677
5679 5681 The solution to the impasse at the Cave of Caerbannog was 5683 provided by the successful deployment of the 5684 Holy Hand Grenade of Antioch (see ) 5686 . 5687 Any similarity between the Holy Hand Grenade of Antioch and the 5688 mythical Holy Spear of Antioch is purely intentional; 5689 any similarity between the 5690 Holy Hand Grenade 5691 of Antioch and the Sovereign's Orb of the United Kingdom 5692 (see ) is putatively fortuitous. 5693 5694 5696 5698
5699
Holy Hand Grenade of Antioch
5700
Ordnance deployed by Brother Maynard under the incantation of a 5701 lector, in order to dispense with the Foes of the Virtuous. 5702 See .
5703
Holy Spear of Antioch
5704
A supposed relic of the crucifixion of Jesus Christ, this is one 5705 of at least four claimed instances of the lance that pierced 5706 Christ's side. Its historical significance lies in inspiring 5707 crusaders to continue their siege of Antioch in 1098.
5708
Sovereign's Orb of the United Kingdom
5709
Part of the Crown Jewels of the United Kingdom, the Sovereign's 5710 Orb is a hollow gold sphere set with jewels and topped with a 5711 cross. It was made for Charles II in 1661. See .
5713
5715 5717 5719 The instructions in the Book of Armaments on the proper 5720 deployment 5721 of the Holy Hand Grenade of Antioch MAY be summarized as 5722 follows, although this summary SHALL NOT be used as a 5723 substitute 5724 for a reading from the Book of Armaments: 5726 5728 5729
    5730
  1. Preamble: St Attila Benediction
    2. 5731
  2. 5732 Feast of the People on Sundry Foods 5733
      5734
    • Lambs
      • 5735
    • Sloths
      • 5736
    • Carp
      • 5737
    • Anchovies
      • 5738
    • Orangutangs
      • 5739
    • Breakfast Cereals
      • 5740
    • Fruit Bats
      • 5741
    • 5742 et hoc genus omne 5743
      • 5744
    5745
    3. 5746
  3. Take out the Holy Pin
    4. 5747
  4. 5748 The Count 5749
      5750
    1. Count is to Three: no more, no less
      2. 5751
    2. Not Four
      3. 5752
    3. Nor Two, except if the count then proceeds to Three
      4. 5753
    4. Five is Right Out
      5. 5754
    5755
    5. 5756
  5. Lob the Holy Hand Grenade of Antioch towards the Foe
    6. 5757
  6. The Foe, being naughty in the LORD's sight, 5758 SHALL snuff it
    7. 5759
5761 5763 This could also be represented in pseudocode as follows: 5765 5767
    5768
  1. Take out the Holy Pin
    2. 5769
  2. 5770 The Count 5771
    5772 5778
    5779
    3. 5780
  3. Lob the Holy Hand Grenade of Antioch towards the Foe
    4. 5781
  4. Foe snuffs it
    5. 5782
5784 5786
5787
Dramatis 5788 PersonaeThe following human (more-or-less) protagonists were 5789 involved 5790 in the two incidents recounted as lore of the Knights of the 5791 Round Table: 5793 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 5812 5813 5814 5815 5816 5817 5818 5819 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5850 5851 5852
French CastleCave of Caerbannog
King Arthur
Patsy
Sir Bedevere the Wise
Sir Galahad the Pure
Sir Lancelot the Brave
Sir Robin the 5820 Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous AccentTim the Enchanter
Other French GuardsBrother Maynard
5832 The Lector
not yet recruitedSir Bors
Sir Gawain
Sir Ector
Retinue of sundry knightsRetinue of sundry more knights than at the 5849 French Castle
5854 5856
Past 5857 the Killer RabbitOnce the Killer Rabbit of Caerbannog () had been 5859 dispatched, the Knights of the Round Table uncovered the last 5860 words of Joseph of Arimathea, inscribed on the Cave of Caerbannog 5861 in Aramaic. While the precise Aramaic wording has not survived, 5862 we trust the following Hebrew subtitles will serve as an 5863 acceptable substitute: 5864 5866
כאן אולי 5867 ימצאו 5868 המילים 5869 האחרונות של 5870 יוסף 5871 .מארמתיה 5872 מי אשר יהיה 5873 אמיץ ובעל 5874 נפש טהורה 5875 יוכל למצוא 5876 את הגביע 5877 הקדוש בטירת 5878 .אאאאאאאה 5879 "Here may be found the last words of Joseph of Arimathea. 5880 He who is valiant and pure of spirit may find the Holy Grail 5881 in the castle of — Aaaargh."
5883 5885
5886
5887 IANA Considerations 5888 IANA might consider a registry to track the mythical, especially 5889 ravaging beasts, such as the Killer Rabbit, who haunt the Internet. 5890
5891
Security ConsiderationsDo not let the Killer 5893 Rabbit out under any circumstance. 5894 I repeat. Do not let the Killer Rabbit () out. 5897 5899
5900 5901 5902 Normative References 5903 5907 5908 5909 Informative References 5910 5911 5912 Monty Python and the Holy Grail 5913 5914 5915 5916 5917 5918 5919 5920 5921 5922 5926 5930 5934 5938 5939 5940 5941 5943 A.3. Example 3: "An API For Calendar-Based Fortune Heuristics Services" 5944 in AsciiRFC 5946 This example is available in the following formats: 5948 o AsciiRFC [git-divination-cfapi] 5950 o Internet-Draft [I-D.divination-cfapi] 5952 o Text, RFC XML, PDF and HTML on the IETF Datatracker 5953 [datatracker-divination-cfapi] 5955 A.3.1. In AsciiRFC 5957 5958 = An API For Calendar-Based Fortune Heuristics Services 5959 Gabriel Destiny; Charise Luck 5960 :doctype: internet-draft 5961 :abbrev: Calendar Fortune Heuristics API 5962 :name: draft-divination-cfapi-00 5963 :status: informational 5964 :ipr: trust200902 5965 :area: Internet 5966 :submission-type: independent 5967 :intended-series: informational 5968 :revdate: 2018-03-23T00:00:00Z 5969 :lastname: Destiny 5970 :fullname: Gabriel Destiny 5971 :forename_initials: G. 5972 :organization: Divination Inc. 5973 :email: gabriel.destiny@ribose.com 5974 :street: 9288 N Divine Street 5975 :city: Dunn 5976 :code: 28334 5977 :region: NC 5978 :country: United States of America 5979 :lastname_2: Luck 5980 :fullname_2: Charise Luck 5981 :forename_initials_2: C. 5982 :organization_2: Divination Inc. 5983 :email_2: charise.luck@ribose.com 5984 :street_2: 9288 N Divine Street 5985 :city_2: Dunn 5986 :code_2: 28334 5987 :region_2: NC 5988 :country_2: United States of America 5990 [.comment] 5991 tag::sample[] 5992 // tag::sample[] 5994 [abstract] 5996 This document describes a JSON HTTP API for online services that 5997 provide calendar-based fortune heuristics. 5999 == Introduction 6001 Fortune-telling, the practice of predicting information about a 6002 person's life, is an activity practiced throughout history. 6004 While there are myriad forms of fortune telling methodologies, this 6005 document applies to a particular form of service that provides fortune 6006 heuristics, commonly known as "luck", for a particular subject based 6007 on a calendar-based input. 6009 Since HTTP <> status codes are insufficient to convey 6010 information about fortune heuristics, this specification defines a 6011 simple JSON <> document format for this purpose. The 6012 response can be used by HTTP APIs to deliver results to non-human 6013 clients or to an end-user. 6015 == Conventions Used in This Document 6017 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 6018 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 6019 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 6020 are to be interpreted as described in BCP 14 <> <> 6021 when, and only when, they appear in all capitals, as shown here. 6023 The following definitions apply in this document: 6025 Well-known URI:: This specification makes use of the "well-known URI" 6026 feature of HTTP servers <> to provide a bootstrapping URI for 6027 the client usage of fortune heuristics services. 6029 Root of Fortune:: The service discovery endpoint that provides a URI 6030 list of available fortune heuristic endpoints available, in accordance 6031 with <>. 6033 == Fortune Heuristics Service Well-Known URI 6035 A well-known URI called "fortune" is registered by this specification 6036 for fortune heuristics services (see <>). 6038 Services complying with this document *SHOULD* have its well-known 6039 URI pointing (directly or through redirection) to the Root of Fortune. 6041 The Root of Fortune can be used by the client for service discovery, 6042 namely, the available calendar-based fortune heuristics services 6043 available on the server, as specified in <>. 6045 === Well-Known URI Redirection 6047 Servers *MUST* redirect HTTP requests for that resource to the 6048 actual "context path" using one of the available mechanisms provided 6049 by HTTP <> (e.g., using a 301, 303, or 307 response). 6051 Clients *MUST* handle HTTP redirects on the well-known URI. 6053 === Well-Known URI Cache Behavior 6055 Servers *SHOULD* set an appropriate Cache-Control header value (as 6056 according to <>) in the redirect response to set 6057 caching behavior as required by the type of response generated. 6059 == New HTTP Methods: SEEK and DIVINE 6061 This specification defines two new HTTP methods: "SEEK" and "DIVINE" 6062 methods for HTTP <>. 6064 While HTTP GET requests are treated equivalently as the "SEEK" and 6065 "DIVINE" requests, its usage is discouraged and therefore *SHOULD NOT* 6066 be used. 6068 Usage of these methods are defined in the sections below. 6070 == Defined Data Types: Date-Time Formats 6072 This specification defines a number of date-time formats as according 6073 to the conventions of <> for the unambiguous communication 6074 between client and server. 6076 The types defined are as follows. 6078 `DATETIME`:: 6079 As described in <>, with the addition that reduced 6080 accuracy representations described in <> are 6081 supported. Reduced accuracy date and times are accepted where a 6082 date or time component (2-digits long) is replaced by "--". 6083 + 6084 For example, the date time "2018-04---T01:02:00Z" represents the UTC 6085 time of 1:02am, on an unknown day within April of the year 2018. 6087 `DATE`:: 6088 As described in "DATETIME", but the "time" component will not be 6089 taken into account in the algorithm. 6091 [#service-discovery] 6092 == Fortune Heuristics Service Discovery 6094 [#root-of-fortune] 6095 === Root of Fortune Path URI ("/") 6097 The Root of Fortune URI, defined as "/" in this document, is used for 6098 service discovery on types of calendar-based fortune heuristics 6099 available. 6101 An empty SEEK request with the "application/json" request type 6102 *MUST* be sent to this endpoint to retrieve the available endpoints. 6103 All other HTTP methods *MUST NOT* be supported at this URI. 6105 An example of such a response is as follows: 6107 [source,json] 6108 ---- 6109 HTTP/1.1 200 Success 6110 Content-Type: application/json 6111 Content-Language: en 6113 { 6114 "diviners" : [ 6115 "/astrology", 6116 "/bazi", 6117 ] 6118 } 6119 ---- 6121 A service discovery object *MUST* have the following members: 6123 `diviners`:: 6124 (JSON array) 6125 An array that contains endpoints that conform to this specification. 6126 All endpoints listed here are relative to the Root of Fortune path. 6127 For example, the path "/astrology" listed in the example has an 6128 endpoint path of "[root-of-fortune]/astrology", where 6129 "[root-of-fortune]" indicates the real path of the Root of Fortune. 6131 // end::sample[] 6132 [.comment] 6133 end::sample[] 6135 [#service-endpoint] 6136 == Fortune Heuristics Service Endpoint 6138 An endpoint offering fortune heuristics services *MUST* adhere to 6139 specifications in this section. 6141 A service *MAY* implement multiple divination services based on 6142 different divination methods, such as the digital oracle shown 6143 in <>. 6145 [[digital-oracle]] 6146 .Dimensional Eye, a digital oracle that communicates through one button 6147 ==== 6148 [alt=An incarnation of the Dimensional Eye, in ASCII] 6149 .... 6150 __ 6151 __===^-\ 6152 __=== -\ 6153 __===- -\ 6154 __===- -\ 6155 ___===- -\ 6156 ===- ---__ -\ 6157 \\\ |||^^\ \__ -\ 6158 \\\ ||| \__ -\ 6159 \\\ ||| ______\_ -\ 6160 \\\ ||| _/-******\\__ -\ 6161 \\\ || /-****_****-\ \_ -\ 6162 \\\ || |-***/ \***-\ \_ -\ 6163 \\\ || |-***\___/***-| \ -\ 6164 \\\ || \-*********-/ __--/ -\ 6165 \\\ || \-******/__-- -\ 6166 \\\ || __-- -\ 6167 \\\ || __-- -\ 6168 \\\ ||__-- -\ 6169 \\\ -\ 6170 \\\ -\ 6171 \\\ -\ 6172 \\\ -\ 6173 \\\ __ -\ 6174 \\\ //##\\ -\ 6175 \\\ \\##// -\ 6176 \\\ ^^ __--==^ 6177 \\\ __--=== 6178 \\\ __--=== 6179 \\\ __--=== 6180 \\\ __--== 6181 \\= 6183 .... 6184 ==== 6186 [#endpoint-specification-request] 6187 === Service Specification Request 6188 To retrieve capabilities and parameters of an endpoint complying with 6189 this specification, a service specification JSON object is returned. 6191 An empty SEEK request with the "application/json" request type 6192 *MUST* be sent to this endpoint to retrieve the service 6193 specification that describes parameters accepted by this endpoint. 6195 Two examples of such a response are given below. 6197 [source,json] 6198 ---- 6199 HTTP/1.1 200 Success 6200 Content-Type: application/json 6201 Content-Language: en 6203 { 6204 "description": "Gaze into your upcoming luck!", 6205 "details": "https://divine.example.com/manual/astrology-api", 6206 "parameters": { 6207 "birthday": { 6208 "type": "DATE", 6209 "description": "Your birth date in UTC" 6210 }, 6211 "targetDateBegin": { 6212 "type": "DATE", 6213 "description": "Start of the target date range to report on" 6214 }, 6215 "targetDateEnd": { 6216 "type": "DATE", 6217 "description": "End of the target date range to report on" 6218 }, 6219 "interval": { 6220 "values": { 6221 "D": "Daily", 6222 "M": "Monthly", 6223 "Y": "Yearly" 6224 }, 6225 "description": "Available intervals to report on." 6226 } 6227 } 6228 } 6229 ---- 6231 [source,json] 6232 ---- 6233 HTTP/1.1 200 Success 6234 Content-Type: application/json 6235 Content-Language: en 6236 { 6237 "description": "Matches and mis-matches according to the " 6238 "Yin Yang and Five Elements techniques", 6239 "details": "https://divine.example.com/manual/bazi-api", 6240 "parameters": { 6241 "birthday": { 6242 "type": "DATETIME", 6243 "description": "Your birth date and time in UTC" 6244 }, 6245 "targetDateBegin": { 6246 "type": "DATETIME", 6247 "description": "Start of the target date/time range to report on" 6248 }, 6249 "targetDateEnd": { 6250 "type": "DATETIME", 6251 "description": "End of the target date/time range to report on" 6252 }, 6253 "interval": { 6254 "values": { 6255 "H": "Hourly", 6256 "D": "Daily", 6257 "M": "Monthly", 6258 "Y": "Yearly" 6259 }, 6260 "description": "Available intervals to report on." 6261 } 6262 } 6263 } 6264 ---- 6266 [#service-endpoint-specification] 6267 === Service Specification Object 6269 A service specification object *MUST* contain the following members. 6271 `description`:: 6272 (string) A short, human-readable summary of the fortune heuristic 6273 service at this endpoint. This *SHOULD* be a stable reference. 6275 `details`:: 6276 (URI, optional) A URI reference that provides further details for 6277 human consumption, such as API documentation that includes details of 6278 parameters accepted or response states. 6280 `parameters`:: 6281 (object, mandatory) An object that specifies what parameters 6282 are accepted by this endpoint. Each parameter key within this object 6283 specifies an accepted parameter name, and its value is a parameter 6284 specification object, which is described below. 6286 A parameter specification object *SHOULD* contain the following 6287 members: 6289 `type`:: 6290 (string, optional) The value type accepted by this parameter. Value 6291 types are described in this document. This member is mutually 6292 exclusive with `values`. 6294 `description`:: 6295 (string, mandatory) The purpose of this parameter. 6297 `values`:: 6298 (object, optional) The accepted values of this parameter, unlisted 6299 values *SHOULD* not be accepted by the parameter. Each key within 6300 this object specifies an accepted value, and its value provides a 6301 description of the purpose of the value. 6303 [#endpoint-report] 6304 == Fortune Heuristics Report Request and Response 6306 [#endpoint-report-request] 6307 === Fortune Heuristics Report Request 6309 A request using the HTTP "DIVINE" method and the "application/json" 6310 type *MUST* be sent to the fortune heuristic endpoint to retrieve 6311 results for a fortune heuristic query. 6313 The request made *MUST* conform to the specifications of the 6314 endpoint, as retrieved via the "SEEK" method described in 6315 <>. 6317 An example of a request is provided below. 6319 [source] 6320 ---- 6321 URI: /divination/astrology 6322 Method: DIVINE 6323 Content-Type: application/json 6324 Content-Language: en 6326 { 6327 "birthday": "1976-02-11T00:00:00Z", 6328 "targetDateBegin": "2018-01-01T00:00:00Z", 6329 "targetDateEnd": "2019-01-01T00:00:00Z", 6330 "interval": "M" 6331 } 6332 ---- 6334 [#endpoint-report-response] 6335 === Fortune Heuristics Report Response 6337 A fortune heuristic query using the "DIVINE" method triggers a 6338 response that contains a fortune heuristics report. 6340 A successful response returns a JSON object that *MUST* conform 6341 to the object structure described in this section. 6343 A report object *SHOULD* contain the following members: 6345 `type`:: 6346 (URI, mandatory) A URI that defines the type of the report located 6347 at the `report` key of this object. 6349 `report`:: 6350 (object, mandatory) An object that contains two keys, `intervals` 6351 and `events`. The `intervals` object contains an array of interval 6352 objects that matches the demanded intervals in the request within 6353 the target date range. 6354 The `events` object contains an array of significant event objects 6355 within the target date range. 6357 An example of a response is provided below. 6359 [source] 6360 ---- 6361 URI: /divination/astrology 6362 Method: DIVINE 6363 HTTP/1.1 200 Success 6364 Content-Type: application/json 6365 Content-Language: en 6367 { 6368 "type": "https://association-of.astrology/reports/monthly", 6369 "report": { 6370 "intervals": [ 6371 { 6372 "dateStart": "2018-01-01T00:00:00Z", 6373 "dateEnd": "2018-02-01T00:00:00Z", 6374 "categories": [ 6375 { 6376 "category": 6377 "https://divine.example.com/astrology/categories/health" 6378 "value": 80, 6379 "description": "Charge ahead with excellent health." 6380 }, 6381 { 6382 "category": 6383 "https://divine.example.com/astrology/categories/love" 6384 "value": 70, 6385 "description": 6386 "Give a certain person or situation another try!" 6387 }, 6388 { 6389 "category": 6390 "https://divine.example.com/astrology/categories/finance" 6391 "value": 5, 6392 "description": "You've just realized that you don't have 6393 any cash on hand." 6394 } 6395 ] 6396 }, 6397 { 6398 "dateStart": "2018-02-01T00:00:00Z", 6399 "dateEnd": "2018-03-01T00:00:00Z", 6400 "..." 6401 }, 6402 "..." 6403 ], 6404 "events": [ 6405 { 6406 "dateStart": "2018-01-15T03:20:00", 6407 "dateEnd": "2018-01-16T20:22:15", 6408 "description": "The planet of growth and good luck, Jupiter 6409 will make a harmonious connection with power planet Pluto, 6410 helping you connect with influential people", 6411 "recommendation": "Engage in networking during this time." 6412 }, 6413 { 6414 "dateStart": "2018-03-22T00:12:40", 6415 "dateEnd": "2018-03-28T02:45:03", 6416 "description": "Communication planet Mercury enters your sign, 6417 which will find you in a busier and chattier mood.", 6418 "recommendation": 6419 "Take charge of work with your newfound energy." 6420 } 6421 "..." 6422 ] 6423 } 6424 } 6425 ---- 6426 Fortune heuristic reports are created by a divination output that 6427 *MAY* requires quantitative interpretation. A sample representation of 6428 interpreting a graphical divination output is provided in 6429 <>. 6431 [[divination-message]] 6432 .Forty-nine yarrow sticks reveals a mystical message on fortune 6433 ==== 6434 [alt=A mystical pattern in ASCII] 6435 .... 6436 0000000000000000000000000 6437 0000000000000000000000001 G 1000000000000000000000000 6438 0000000000000000000000011 R 1100000000000000000000000 6439 0000000000000000000000111 A 1110000000000000000000000 6440 0000000000000000000001111 C 1111000000000000000000000 6441 0000000000000000000011111 E 1111100000000000000000000 6442 0000000000000000000111111 , 1111110000000000000000000 6443 0000000000000000001111111 1111111000000000000000000 6444 0000000011111111111111111 M 1111111111111111100000000 6445 0000000111111111111111111 E 1111111111111111110000000 6446 0000001111111111111111111 R 1111111111111111111000000 6447 0000011111111111111111111 C 1111111111111111111100000 6448 0000111111111111111111111 Y 1111111111111111111110000 6449 0001111111111111111111111 , 1111111111111111111111000 6450 0011111111111111111111111 1111111111111111111111100 6451 0111111111111111111111111 A 1111111111111111111111110 6452 0000000000000000011111111 N 1111111100000000000000000 6453 0000000000000000111111111 D 1111111110000000000000000 6454 0000000000000001111111111 1111111111000000000000000 6455 0000000000000011111111111 P 1111111111100000000000000 6456 0000000000000111111111111 E 1111111111110000000000000 6457 0000000000001111111111111 A 1111111111111000000000000 6458 0000000000011111111111111 C 1111111111111100000000000 6459 0000000000111111111111111 E 1111111111111110000000000 6460 0000000001111111111111111 . 1111111111111111000000000 6461 .... 6462 ==== 6464 [#endpoint-report-interval-obj] 6465 === Report Interval Object 6467 The `intervals` value of a report object contains a number of report 6468 intervals -- each representing a non-overlapping period of the 6469 selected interval length. When all of these intervals are put 6470 together, the combined period *MUST* fully cover the requested 6471 report target period. 6473 An example interval object is shown below. 6475 [source,json] 6476 ---- 6477 { 6478 "dateStart": "2018-01-01T00:00:00Z", 6479 "dateEnd": "2018-02-01T00:00:00Z", 6480 "categories": [ 6481 { 6482 "category": 6483 "https://divine.example.com/astrology/categories/health" 6484 "value": 80, 6485 "description": "Charge ahead with your excellent health." 6486 }, 6487 { 6488 "category": 6489 "https://divine.example.com/astrology/categories/love" 6490 "value": 70, 6491 "description": "Give a certain person or situation another try!" 6492 }, 6493 { 6494 "category": 6495 "https://divine.example.com/astrology/categories/finance" 6496 "value": 5, 6497 "description": "You've just realized that you don't have 6498 any cash on hand." 6499 } 6500 ] 6501 } 6502 ---- 6504 An interval object *MUST* contain the following members: 6506 `dateStart`:: 6507 (datetime, mandatory) This value specifies the start of the period 6508 which this interval object applies to. 6510 `dateEnd`:: 6511 (datetime, mandatory) This value specifies the end of the period 6512 which this interval object applies to. 6514 In the given example, the `categories` key is an implementation 6515 specific object that details heuristic results returned by the 6516 selected algorithm. This *MAY* differ in different algorithms. 6518 [#endpoint-report-event-obj] 6519 === Report Events Object 6520 The `events` value of a report object contains a number of event 6521 objects. Each event object represents an event relevant to the 6522 calculation of fortune heuristics during a target report period. These 6523 events *MAY* be of variable time lengths, and *MAY* be overlapping 6524 amongst each other. 6526 The following example demonstrates two event objects the service 6527 determines relevant to a user's query. 6529 [source,json] 6530 ---- 6531 { 6532 "dateStart": "2018-01-15T03:20:00", 6533 "dateEnd": "2018-01-16T20:22:15", 6534 "description": "The planet of growth and good luck, Jupiter will 6535 make a harmonious connection with power planet Pluto, helping you 6536 connect with influential people", 6537 "recommendation": "Engage in networking during this time." 6538 }, 6539 { 6540 "dateStart": "2018-03-22T00:12:40", 6541 "dateEnd": "2018-03-28T02:45:03", 6542 "description": "Communication planet Mercury enters your sign, 6543 which will find you in a busier and chattier mood.", 6544 "recommendation": "Take charge of work with your newfound energy." 6545 } 6546 ---- 6548 Similar to an interval object, an event object *MUST* contain the 6549 following members: 6551 `dateStart`:: 6552 (datetime, mandatory) This value specifies the start of the period 6553 described by the event. 6555 `dateEnd`:: 6556 (datetime, mandatory) This value specifies the end of the period 6557 described by the event. 6559 In the given example, the keys `description` and `recommendation` 6560 are implementation-specific details. This *MAY* differ in different 6561 algorithms. 6563 [#endpoint-report-errors] 6564 === Report Generation Errors 6566 This specification makes use of normal HTTP error codes with the 6567 following extensions. 6569 Errors *MUST* be returned using the Problem JSON Structure as 6570 accordance with <>. 6572 422 Unprocessable Entity:: 6573 For example, a malformed date-time parameter, or an illogical input, 6574 such as when the subject's birthday occurs after the report target 6575 date period. 6577 473 Beyond Existing Capability:: 6578 The service determines that the outcome is too difficult to predict. 6579 For example, in the case where the calculation is too complex to 6580 complete in a certain time period. The service *SHOULD* issue this 6581 response code to indicate that the client should not try the same 6582 request again. 6584 474 Outcome Impossible:: 6585 The service determines that the outcome is impossible. For example, 6586 when the algorithm determines that the subject will have deceased 6587 before the start of the requested target period. 6589 [#security] 6590 == Security Considerations 6592 * TLS <> and authenticated HTTP requests should be used to 6593 protect the DIVINE request and responses due to the personal nature 6594 of information transmitted. 6596 * A client *SHOULD* verify the identity of the server on every 6597 request to prevent impersonation or man-in-the-middle attacks, as data 6598 transmitted to and from the server is sensitive information, and at 6599 times critical information to the user. 6601 * Synchronization of client and server time *MUST* be 6602 well-considered in the implementation of this specification. A 6603 mismatch of client and server time *MAY* lead to algorithm 6604 miscalculations that can cause mistaken choices of a user that depends 6605 on the reliability of this system. 6607 [#iana] 6608 == IANA Considerations 6610 === Well-Known URI Registrations 6611 This document defines a well-known URI using the registration 6612 procedure and template from <>. 6614 ==== "fortune" Well-Known URI Registration 6616 URI suffix:: fortune 6618 Change controller:: IETF 6620 Specification document(s):: This document 6622 Related information:: N/A. 6624 [.comment] 6625 tag::sample[] 6626 // begin::sample[] 6628 [bibliography] 6629 == Normative References 6631 ++++ 6633 6635 6636 Key words for use in RFCs to Indicate Requirement 6637 Levels 6638 6639 6640 6641 6642 In many standards track documents several words are 6643 used to signify the requirements in the specification. These 6644 words are often capitalized. This document defines these words 6645 as they should be interpreted in IETF documents. This 6646 document specifies an Internet Best Current Practices for the 6647 Internet Community, and requests discussion and suggestions 6648 for improvements. 6649 6650 6651 6652 6653 6655 6657 6658 Defining Well-Known Uniform Resource Identifiers 6659 (URIs) 6660 6662 6663 6664 6666 6667 6668 6669 This memo defines a path prefix for "well-known 6670 locations", "/.well-known/", in selected Uniform 6671 Resource Identifier (URI) schemes. 6672 [STANDARDS-TRACK] 6673 6674 6675 6676 6678 6680 6681 Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and 6682 Routing 6683 6685 6686 6687 6689 6690 6691 6692 The Hypertext Transfer Protocol (HTTP) is a stateless 6693 application-level protocol for distributed, collaborative, 6694 hypertext information systems. This document provides an 6695 overview of HTTP architecture and its associated terminology, 6696 defines the "http" and "https" Uniform 6697 Resource Identifier (URI) schemes, defines the HTTP/1.1 6698 message syntax and parsing requirements, and describes related 6699 security concerns for implementations. 6700 6701 6702 6703 6705 6707 6708 Hypertext Transfer Protocol (HTTP/1.1): Caching 6709 6711 6712 6713 6716 6717 6718 6720 6721 6722 6723 The Hypertext Transfer Protocol (HTTP) is a stateless 6724 \%application- level protocol for distributed, collaborative, 6725 hypertext information systems. This document defines HTTP 6726 caches and the associated header fields that control cache 6727 behavior or indicate cacheable response 6728 messages. 6729 6730 6731 6732 6734 6736 6737 Problem Details for HTTP APIs 6738 6740 6741 6742 6743 6744 6745 6746 This document defines a "problem detail" 6747 as a way to carry machine- readable details of errors in a 6748 HTTP response to avoid the need to define new error response 6749 formats for HTTP APIs. 6750 6751 6752 6753 6754 6756 6757 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 6758 Words 6759 6760 6761 6762 6763 RFC 2119 specifies common key words that may be used 6764 in protocol specifications. This document aims to reduce 6765 the ambiguity by clarifying that only UPPERCASE usage of the 6766 key words have the defined special meanings. 6767 6768 6769 6770 6771 6773 6775 6776 The JavaScript Object Notation (JSON) Data Interchange 6777 Format 6778 6780 6781 6782 6783 JavaScript Object Notation (JSON) is a lightweight, 6784 text-based, language-independent data interchange format. 6785 It was derived from the ECMAScript Programming Language 6786 Standard. JSON defines a small set of formatting rules for 6787 the portable representation of structured data. 6788 This document removes inconsistencies with other 6789 specifications of JSON, repairs specification errors, and 6790 offers experience-based interoperability 6791 guidance. 6792 6793 6794 6795 6796 6797 6798 ++++ 6800 [bibliography] 6801 == Informative References 6802 ++++ 6804 6806 6807 ISO/DIS 8601-1:2018, Data elements and interchange 6808 formats -- Information interchange -- Representation of dates 6809 and times -- Part 1: Basic rules 6810 6811 ISO/IEC 6812
6813 http://www.iso.org 6814
6815 6816 6817 6818 6819 6821 6823 6824 Date and Time on the Internet: Timestamps 6825 6826 6827 6828 6829 6830 6831 6832 6833 6834 6835 6837 6839 6840 The Transport Layer Security (TLS) Protocol 6841 Version 1.2 6842 6843 6844 6845 6846 6847 6848 6849 This document specifies Version 1.2 of the Transport 6850 Layer Security (TLS) protocol. The TLS protocol provides 6851 communications security over the Internet. The protocol 6852 allows client/server applications to communicate in a way 6853 that is designed to prevent eavesdropping, tampering, or 6854 message forgery. [STANDARDS-TRACK] 6855 6856 6857 6858 6859 ++++ 6861 [appendix] 6862 == Acknowledgements 6864 The authors thank the following individuals for their valuable 6865 feedback on this specification, and commend them for making fortune 6866 heuristics more accessible for the benefit of mankind. 6868 // end::sample[] 6869 [.comment] 6870 end::sample[] 6871 6873 A.4. Rendered as RFC XML v3 6875 6876 6877 6878 6879 6880 6881 6882 6883 6884 6885 6886 6889 6890 An API For 6891 Calendar-Based Fortune Heuristics Services 6892 6894 6896 6897 Divination Inc. 6898
6899 6900 9288 N Divine Street 6901 Dunn 6902 NC 6903 28334 6904 United States of America 6905 6906 gabriel.destiny@ribose.com 6907
6908 6909 6910 Divination Inc. 6911
6912 6913 9288 N Divine Street 6914 Dunn 6915 NC 6916 28334 6917 United States of America 6918 6919 charise.luck@ribose.com 6920
6921 6922 6923 Internet 6925 6927 6929 This document describes a JSON HTTP API for online services that 6930 provide calendar-based fortune heuristics. 6931 6932
IntroductionFortune-telling, the practice of 6934 predicting information about a 6935 person’s life, is an activity practiced throughout history. 6936 While there are myriad forms of fortune telling methodologies, this 6937 document applies to a particular form of service that provides fortune 6938 heuristics, commonly known as "luck", for a particular subject based 6939 on a calendar-based input. 6940 Since HTTP status codes are insufficient to 6941 convey 6942 information about fortune heuristics, this specification defines a 6943 simple JSON document format for this purpose. 6944 The 6945 response can be used by HTTP APIs to deliver results to non-human 6946 clients or to an end-user.
6947
Conventions Used in This DocumentThe key words 6949 "MUST", "MUST NOT", 6950 "REQUIRED", "SHALL", 6951 "SHALL NOT", "SHOULD", "SHOULD 6952 NOT", "RECOMMENDED", 6953 "NOT RECOMMENDED", "MAY", and 6954 "OPTIONAL" in this document 6955 are to be interpreted as described in BCP 14 6956 6957 when, and only when, they appear in all capitals, as shown here. 6958 The following definitions apply in this document: 6959
6960
Well-known URI
6961
This specification makes use of the "well-known URI" 6962 feature of HTTP servers to provide a 6963 bootstrapping URI for 6964 the client usage of fortune heuristics services.
6965
Root of Fortune
6966
The service discovery endpoint that provides a URI 6967 list of available fortune heuristic endpoints available, in accordance 6968 with .
6969
6970
Fortune Heuristics Service Well-Known URIA 6972 well-known URI called "fortune" is registered by this specification 6973 for fortune heuristics services (see ). 6974 Services complying with this document SHOULD have its 6975 well-known 6976 URI pointing (directly or through redirection) to the Root of 6977 Fortune. 6978 The Root of Fortune can be used by the client for service discovery, 6979 namely, the available calendar-based fortune heuristics services 6980 available on the server, as specified in . 6982
Well-Known URI RedirectionServers 6984 MUST redirect HTTP requests for that resource to the 6985 actual "context path" using one of the available mechanisms provided 6986 by HTTP (e.g., using a 301, 303, or 307 6987 response). 6988 Clients MUST handle HTTP redirects on the well-known 6989 URI.
6990
6991 Well-Known URI Cache Behavior 6992 Servers SHOULD set an appropriate Cache-Control 6993 header value (as 6994 according to ) in the redirect response to set 6996 caching behavior as required by the type of response generated. 6997
6998
New HTTP Methods: SEEK and DIVINEThis 7000 specification defines two new HTTP methods: "SEEK" and "DIVINE" 7001 methods for HTTP . 7002 While HTTP GET requests are treated equivalently as the "SEEK" and 7003 "DIVINE" requests, its usage is discouraged and therefore SHOULD 7004 NOT 7005 be used. 7006 Usage of these methods are defined in the sections 7007 below.
7008
Defined Data Types: Date-Time FormatsThis 7010 specification defines a number of date-time formats as according 7011 to the conventions of for the unambiguous 7012 communication 7013 between client and server. 7014 The types defined are as follows. 7015
7016
7017 DATETIME 7018
7019
7020 As described in , with the addition that reduced 7022 accuracy representations described in 7023 are 7024 supported. Reduced accuracy date and times are accepted where a 7025 date or time component (2-digits long) is replaced by "--". 7026 For example, the date time "2018-04---T01:02:00Z" represents the 7027 UTC 7028 time of 1:02am, on an unknown day within April of the year 2018. 7029
7030
7031 DATE 7032
7033
As described in "DATETIME", but the "time" component will not be 7034 taken into account in the algorithm.
7035
7036
7037 Fortune Heuristics Service Discovery 7038
Root of 7039 Fortune Path URI ("/")The Root of Fortune URI, defined as "/" 7040 in this document, is used for 7041 service discovery on types of calendar-based fortune heuristics 7042 available. 7043 An empty SEEK request with the "application/json" request type 7044 MUST be sent to this endpoint to retrieve the available 7045 endpoints. 7046 All other HTTP methods MUST NOT be supported at this 7047 URI. 7048 An example of such a response is as follows: 7049
7050 7062
7063 A service discovery object MUST have the following 7064 members: 7065
7066
7067 diviners 7068
7069
(JSON array) 7070 An array that contains endpoints that conform to this specification. 7071 All endpoints listed here are relative to the Root of Fortune path. 7072 For example, the path "/astrology" listed in the example has an 7073 endpoint path of "[root-of-fortune]/astrology", where 7074 "[root-of-fortune]" indicates the real path of the Root of Fortune.
7075
7077 7079
7080
7081
Fortune 7082 Heuristics Service EndpointAn endpoint offering fortune 7083 heuristics services MUST adhere to 7084 specifications in this section. 7085 A service MAY implement multiple divination services 7086 based on 7087 different divination methods, such as the digital oracle shown 7088 in . 7089
7090 Dimensional Eye, a digital oracle that communicates through one 7091 button 7092 7128
7129
Service Specification RequestTo retrieve 7131 capabilities and parameters of an endpoint complying with 7132 this specification, a service specification JSON object is returned. 7133 An empty SEEK request with the "application/json" request type 7134 MUST be sent to this endpoint to retrieve the service 7135 specification that describes parameters accepted by this endpoint. 7136 Two examples of such a response are given below. 7137
7138 7170
7171
7172 7206
7207
Service Specification ObjectA service 7209 specification object MUST contain the following 7210 members. 7211
7212
7213 description 7214
7215
(string) A short, human-readable summary of the fortune heuristic 7216 service at this endpoint. This SHOULD be a stable 7217 reference.
7218
7219 details 7220
7221
(URI, optional) A URI reference that provides further details for 7222 human consumption, such as API documentation that includes details of 7223 parameters accepted or response states.
7224
7225 parameters 7226
7227
(object, mandatory) An object that specifies what parameters 7228 are accepted by this endpoint. Each parameter key within this object 7229 specifies an accepted parameter name, and its value is a parameter 7230 specification object, which is described below.
7231
7232 A parameter specification object SHOULD contain the 7233 following 7234 members: 7235
7236
7237 type 7238
7239
(string, optional) The value type accepted by this parameter. 7240 Value 7241 types are described in this document. This member is mutually 7242 exclusive with values.
7243
7244 description 7245
7246
(string, mandatory) The purpose of this parameter.
7247
7248 values 7249
7250
(object, optional) The accepted values of this parameter, unlisted 7251 values SHOULD not be accepted by the parameter. Each key 7252 within 7253 this object specifies an accepted value, and its value provides a 7254 description of the purpose of the value.
7255
7256
Fortune 7257 Heuristics Report Request and Response
Fortune Heuristics 7259 Report RequestA request using the HTTP "DIVINE" method and the 7260 "application/json" 7261 type MUST be sent to the fortune heuristic endpoint to 7262 retrieve 7263 results for a fortune heuristic query. 7264 The request made MUST conform to the specifications of 7265 the 7266 endpoint, as retrieved via the "SEEK" method described in 7267 . 7268 An example of a request is provided below. 7269
7270 7283
7284
Fortune Heuristics Report ResponseA fortune 7286 heuristic query using the "DIVINE" method triggers a 7287 response that contains a fortune heuristics report. 7288 A successful response returns a JSON object that MUST 7289 conform 7290 to the object structure described in this section. 7291 A report object SHOULD contain the following 7292 members: 7293
7294
7295 type 7296
7297
(URI, mandatory) A URI that defines the type of the report located 7298 at the report key of this object.
7299
7300 report 7301
7302
(object, mandatory) An object that contains two keys, 7303 intervals 7304 and events. The intervals object contains an array of 7305 interval 7306 objects that matches the demanded intervals in the request within 7307 the target date range. 7308 The events object contains an array of significant event 7309 objects 7310 within the target date range.
7311
7312 An example of a response is provided below. 7313
7314 7381
7382 Fortune heuristic reports are created by a divination output that 7383 MAY requires quantitative interpretation. A sample 7384 representation of 7385 interpreting a graphical divination output is provided in 7386 . 7387
7388 Forty-nine yarrow sticks reveals a mystical message on 7389 fortune 7390 7418
7419
Report Interval ObjectThe intervals 7421 value of a report object contains a number of report 7422 intervals — each representing a non-overlapping period 7423 of the 7424 selected interval length. When all of these intervals are put 7425 together, the combined period MUST fully cover the 7426 requested 7427 report target period. 7428 An example interval object is shown below. 7429
7430 7457
7458 An interval object MUST contain the following 7459 members: 7460
7461
7462 dateStart 7463
7464
(datetime, mandatory) This value specifies the start of the period 7465 which this interval object applies to.
7466
7467 dateEnd 7468
7469
(datetime, mandatory) This value specifies the end of the period 7470 which this interval object applies to.
7471
7472 In the given example, the categories key is an 7473 implementation 7474 specific object that details heuristic results returned by the 7475 selected algorithm. This MAY differ in different 7476 algorithms.
7477
Report Events ObjectThe events value of 7479 a report object contains a number of event 7480 objects. Each event object represents an event relevant to the 7481 calculation of fortune heuristics during a target report period. These 7482 events MAY be of variable time lengths, and 7483 MAY be overlapping 7484 amongst each other. 7485 The following example demonstrates two event objects the service 7486 determines relevant to a user’s query. 7487
7488 7505
7506 Similar to an interval object, an event object MUST 7507 contain the 7508 following members: 7509
7510
7511 dateStart 7512
7513
(datetime, mandatory) This value specifies the start of the period 7514 described by the event.
7515
7516 dateEnd 7517
7518
(datetime, mandatory) This value specifies the end of the period 7519 described by the event.
7520
7521 In the given example, the keys description and 7522 recommendation 7523 are implementation-specific details. This MAY differ in 7524 different 7525 algorithms.
7526
Report 7527 Generation ErrorsThis specification makes use of normal HTTP 7528 error codes with the 7529 following extensions. 7530 Errors MUST be returned using the Problem JSON 7531 Structure as 7532 accordance with . 7533
7534
422 Unprocessable Entity
7535
For example, a malformed date-time parameter, or an illogical 7536 input, 7537 such as when the subject’s birthday occurs after the report target 7538 date period.
7539
473 Beyond Existing Capability
7540
The service determines that the outcome is too difficult to 7541 predict. 7542 For example, in the case where the calculation is too complex to 7543 complete in a certain time period. The service SHOULD 7544 issue this 7545 response code to indicate that the client should not try the same 7546 request again.
7547
474 Outcome Impossible
7548
The service determines that the outcome is impossible. For 7549 example, 7550 when the algorithm determines that the subject will have deceased 7551 before the start of the requested target period.
7552
7553
7554 Security Considerations 7555
    7556
  • TLS and authenticated HTTP requests 7557 should be used to 7558 protect the DIVINE request and responses due to the personal nature 7559 of information transmitted.
    • 7560
  • A client SHOULD verify the identity of the server 7561 on every 7562 request to prevent impersonation or man-in-the-middle attacks, as data 7563 transmitted to and from the server is sensitive information, and at 7564 times critical information to the user.
    • 7565
  • Synchronization of client and server time MUST be 7566 well-considered in the implementation of this specification. A 7567 mismatch of client and server time MAY lead to algorithm 7568 miscalculations that can cause mistaken choices of a user that depends 7569 on the reliability of this system.
    • 7570
7571
7572
7573 IANA Considerations 7574
Well-Known URI RegistrationsThis document 7576 defines a well-known URI using the registration 7577 procedure and template from . 7579
"fortune" Well-Known URI Registration
7581
URI suffix
7582
fortune
7583
Change controller
7584
IETF
7585
Specification document(s)
7586
This document
7587
Related information
7588
N/A.
7589
7591 7593
7594
7595 7596 7597 Normative References 7598 7602 7606 7610 7614 7618 7622 7626 7627 7628 Informative References 7629 7631 7632 ISO/DIS 8601-1:2018, Data elements and interchange 7633 formats -- Information interchange -- Representation of dates 7634 and times -- Part 1: Basic rules 7635 7636 ISO/IEC 7637
7638 http://www.iso.org 7639
7640 7641 7642 7643 7644 7645 7649 7653 7654
AcknowledgementsThe authors thank the following 7656 individuals for their valuable 7657 feedback on this specification, and commend them for making fortune 7658 heuristics more accessible for the benefit of mankind. 7659 7661
7662 7663 7664 7666 Appendix B. Acknowledgements 7668 The authors would like to thank the following persons for their 7669 valuable advice and input. 7671 o Adrian Farrel for his comprehensive review of the document and 7672 numerous beneficial suggestions. 7674 Authors' Addresses 7676 Ronald Henry Tse 7677 Ribose 7678 Suite 1111, 1 Pedder Street 7679 Central, Hong Kong 7680 Hong Kong 7682 Email: ronald.tse@ribose.com 7683 URI: https://www.ribose.com 7685 Nick Nicholas 7686 Ribose 7687 Australia 7689 Email: nick.nicholas@ribose.com 7690 URI: https://www.ribose.com 7692 Jeffrey Lau 7693 Ribose 7694 Suite 1111, 1 Pedder Street 7695 Central, Hong Kong 7696 Hong Kong 7698 Email: jeffrey.lau@ribose.com 7699 URI: https://www.ribose.com 7700 Paolo Brasolin 7701 Ribose 7702 Italy 7704 Email: paolo.brasolin@ribose.com 7705 URI: https://www.ribose.com