idnits 2.17.1 draft-ribose-asciirfc-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 271 instances of too long lines in the document, the longest one being 360 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (March 23, 2018) is 2227 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Orb' is mentioned on line 4378, but not defined -- Looks like a reference, but probably isn't: '124' on line 4378 -- Looks like a reference, but probably isn't: '135' on line 4378 == Unused Reference: 'I-D.camelot-holy-grenade' is defined on line 3297, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-asciirfc-minimal-00 == Outdated reference: A later version (-01) exists of draft-camelot-holy-grenade-00 -- Obsolete informational reference (is this intentional?): RFC 7749 (Obsoleted by RFC 7991) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Tse 3 Internet-Draft N. Nicholas 4 Intended status: Informational J. Lau 5 Expires: September 24, 2018 P. Brasolin 6 Ribose 7 March 23, 2018 9 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc 10 draft-ribose-asciirfc-05 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 September 24, 2018. 47 Copyright Notice 49 Copyright (c) 2018 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (https://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. Designed for authoring RFCs and Internet-Drafts . . . . . 3 63 1.2. Relationship between AsciiRFC, AsciiDoc and Asciidoctor . 4 64 1.3. Comparison with RFC XML tools based on Markdown variants 4 65 2. Conventions Used in This Document . . . . . . . . . . . . . . 6 66 3. Document Structure and Syntax . . . . . . . . . . . . . . . . 6 67 3.1. Unsupported features compared with Asciidoctor syntax . . 7 68 3.2. Mapping To RFC XML syntax . . . . . . . . . . . . . . . . 8 69 3.3. Example Illustrations . . . . . . . . . . . . . . . . . . 9 70 3.4. Simple Illustration . . . . . . . . . . . . . . . . . . . 9 71 4. Header And Document Attributes . . . . . . . . . . . . . . . 23 72 4.1. Title And Basic Attributes . . . . . . . . . . . . . . . 23 73 4.2. Detailed Author Information . . . . . . . . . . . . . . . 25 74 4.3. XML Processing Information . . . . . . . . . . . . . . . 29 75 4.4. AsciiRFC-specific Document Attributes . . . . . . . . . . 30 76 5. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 32 77 6. Sections and Paragraphs . . . . . . . . . . . . . . . . . . . 34 78 7. Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 79 8. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 80 8.1. Basic Lists . . . . . . . . . . . . . . . . . . . . . . . 40 81 8.2. List Continuation . . . . . . . . . . . . . . . . . . . . 46 82 9. Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . . 49 83 10. Notes And Asides . . . . . . . . . . . . . . . . . . . . . . 49 84 11. Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 85 12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . . 55 86 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts . 55 87 12.2. Formatting BCP 14 Keywords . . . . . . . . . . . . . . . 56 88 12.3. Escaping AsciiRFC Syntax . . . . . . . . . . . . . . . . 57 89 13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 90 14. Cross-References . . . . . . . . . . . . . . . . . . . . . . 59 91 14.1. Basic Referencing . . . . . . . . . . . . . . . . . . . 59 92 14.2. Referencing With Attributes . . . . . . . . . . . . . . 60 93 14.3. Indexing . . . . . . . . . . . . . . . . . . . . . . . . 61 94 15. Inclusions . . . . . . . . . . . . . . . . . . . . . . . . . 62 95 16. Encoding and Entities . . . . . . . . . . . . . . . . . . . . 63 96 17. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 64 97 17.1. Using Raw RFC XML . . . . . . . . . . . . . . . . . . . 65 98 17.2. Preprocessing Using "asciidoctor-bibliography" . . . . . 68 99 18. RFC XML features not supported in Asciidoctor . . . . . . . . 70 100 19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 71 101 19.1. Using the "rfc-asciirfc-minimal" template . . . . . . . 71 102 19.2. Installing AsciiRFC Backend Processors . . . . . . . . . 71 103 19.3. Iterating AsciiRFC Content . . . . . . . . . . . . . . . 72 104 20. Security Considerations . . . . . . . . . . . . . . . . . . . 72 105 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 73 106 22. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 107 22.1. Normative References . . . . . . . . . . . . . . . . . . 73 108 22.2. Informative References . . . . . . . . . . . . . . . . . 73 109 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 76 110 A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" . . . . 76 111 A.1.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 77 112 A.1.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 83 113 A.2. Example 2: "The Holy Hand Grenade of Antioch" . . . . . . 86 114 A.2.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 87 115 A.2.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 104 116 A.3. Example 3: "An API For Calendar-Based Fortune Heuristics 117 Services" in AsciiRFC . . . . . . . . . . . . . . . . . . 118 118 A.3.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 118 119 A.4. Rendered as RFC XML v3 . . . . . . . . . . . . . . . . . 138 120 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 151 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 152 123 1. Introduction 125 This document describes a markup language called "AsciiRFC", 126 developed specifically for the purpose of generating RFC XML 127 document, based on Asciidoctor syntax. AsciiRFC can be used to 128 generate compliant RFC XML v2 and v3 documents through the usage of 129 an open source, MIT-licensed Ruby gem called "asciidoctor-rfc" 130 written by the authors [asciidoctor-rfc]. 132 1.1. Designed for authoring RFCs and Internet-Drafts 134 Internet-Drafts and RFCs intended for publication submission to the 135 IETF can be written in a multitude of formats today, including: 137 o XML: RFC XML v2 [RFC7749] and v3 [RFC7991] 139 o nroff: through [NroffEdit] 141 o Microsoft Word: through usage of [RFC5385] 142 o Lyx: through [lyx2rfc] 144 o Pandoc: [RFC7328], through [pandoc2rfc] or [draftr] 146 o Kramdown: through [kramdown-rfc2629] 148 o mmark: through [mmark] 150 Interestingly, the last three are Markdown [RFC7763] variants. 152 As specified in [RFC7990], the IETF intends for the canonical format 153 of RFCs to transition from plain-text ASCII to RFC XML v3 [RFC7991]. 154 While plain-text will continue to be accepted from authors by the 155 IETF, at least in the short- to medium-term, XML will be preferred 156 for submission, and any plain-text submissions will need to be 157 converted to RFC XML v3. 159 While this need is already met for RFC XML v2 [RFC7749] by the tools 160 specified above, the transition to RFC XML v3 [RFC7991] places added 161 onus on authors to generate compliant XML. 163 1.2. Relationship between AsciiRFC, AsciiDoc and Asciidoctor 165 [AsciiDoc] is a lightweight markup language and an alternative to 166 Markdown, with features that make it attractive as a markup language 167 for RFC with XML output. 169 [Asciidoctor] is an open source, MIT-licensed Ruby implementation of 170 [AsciiDoc] that provides an enhancement of the original AsciiDoc 171 markup language. 173 The variant of AsciiDoc syntax accepted by [Asciidoctor] is hereafter 174 called "Asciidoctor syntax". 176 AsciiRFC, as described in this document, is an AsciiDoc variant 177 developed on Asciidoctor syntax, created for the purpose of 178 generating RFC XML documents. 180 1.3. Comparison with RFC XML tools based on Markdown variants 182 Section 1.2 of [RFC7764] famously states that "there is no such thing 183 as 'invalid' Markdown, there is no standard demanding adherence to 184 the Markdown syntax, and there is no governing body that guides or 185 impedes its development." While there are contexts where that 186 flexibility is useful, the authoring of RFCs does have a standard and 187 a governing body, and there is such a thing as invalid RFC XML. A 188 more rigorous and extensible counterpart to Markdown, which still 189 preserves its basic approach to formatting, can generate RFC XML that 190 encompasses a fuller subset of the specification, and preempts 191 malformed RFC XML output. The proposed markup language and 192 associated Ruby gem has several advantages that we believe make it 193 worth considering as an approach to generating RFC XML. 195 o AsciiDoc was designed from the beginning as a publishing language: 196 it was initially intended as a plain-text alternative to the 197 DocBook XML schema. For that reason, Asciidoctor natively 198 supports the full range of formatting required by RFC XML 199 (including notes, tables, bibliographies, source-code blocks, and 200 definition lists), without resorting to embedded HTML or Markdown 201 "flavours". 203 o AsciiRFC covers the full range of elements in RFC XML v2 and RFC 204 XML v3. 206 o AsciiDoc in its Ruby-based Asciidoctor implementation is 207 extensible, with a well-defined API. (Extensions have been 208 harnessed to deal with bibliographic preprocessing for AsciiRFC.) 210 o AsciiRFC allows granular control of rendering, including user- 211 specified attributes of text blocks. 213 o The Asciidoctor implementation allows document inclusion, for 214 managing large-scale documentation projects. 216 o AsciiRFC allows granular control of permutations of block nesting, 217 such as source code within lists or definition lists within 218 unordered lists. 220 o As a more formal counterpart to Markdown, AsciiDoc is well-suited 221 to generating XML that needs to conform to a specified schema. 222 The asciidoctor-rfc Ruby gem developed around AsciiDoc validates 223 its RFC XML output against the RelaxNG schema defined for RFC XML, 224 and reports any issues to the end user. 226 o The asciidoctor-rfc Ruby gem incorporates validation not only of 227 the XML structure of the standard, but also of the IETF workgroups 228 it mentions against the latest listing online, and the 229 bibliographic entries for RFC and other standards registered on 230 . The gem also dynamically 231 fetches bibliographic entries from the xml2rfc site, and uses them 232 to populate the RFC XML document. 234 As with Markdown, there is a wide range of tools that can render 235 AsciiDoc; so AsciiRFC drafts of RFC documents can be previewed and 236 accessed without depending on the RFC tools ecosystem. Our 237 realisation of RFC XML in AsciiRFC has aimed to ensure that, as much 238 as possible, the markup language can be can be processed by generic 239 Asciidoctor tools. 241 The only exception to this as an add-on is the optional bibliography 242 module, which allows bibliographies to be assembled on the fly based 243 on citations in a document: see Section 17.2. 245 2. Conventions Used in This Document 247 The following terms and definitions apply to this document: 249 AsciiDoc 250 The AsciiDoc markup language generically, as described in 251 [AsciiDoc]. 253 Asciidoctor syntax 254 The enhanced AsciiDoc syntax implemented by the [Asciidoctor] Ruby 255 gem. 257 AsciiRFC 258 The AsciiDoc syntax developed for the purpose of generating RFC 259 XML document based on Asciidoctor syntax, as described in this 260 document. 262 3. Document Structure and Syntax 264 AsciiRFC consists of a subset of Asciidoctor syntax with the addition 265 of bibliographic macros (Section 17.2). Asciidoctor syntax is 266 presented in the Asciidoctor user manual [Asciidoctor-Manual]. 268 AsciiRFC syntax consists of: 270 o A document header, containing a title, a list of authors, and 271 document attributes in lines prefixed with ":". 273 o An optional document preamble, separated from the document header 274 by a blank line, and not containing any section titles. 276 o A number of sections, set off by a section title (a line prefixed 277 with two or more "=".) 279 A section may contain: 281 o Other sections, whose level of nesting is indicated by the number 282 of "=" in their header. 284 o Blocks of text. Blocks can have metadata (including a title, an 285 anchor for cross-references, and attributes.) 287 Blocks can be: 289 o Paragraphs, which are terminated by blank lines. 291 o Lists. List items are by default paragraphs, but can span over 292 multiple paragraphs. 294 o Delimited blocks (with a line delimiter on either side of them); 295 these include tables, notes, sidebars, source code, block quotes, 296 examples, and unprocessed content (e.g. raw XML). Delimited 297 blocks contain by default one or more paragraphs. 299 o List items can contain other blocks, including both nested lists 300 and delimited blocks. 302 o Some delimited blocks can contain other delimited blocks; for 303 example, examples can contain source code as well as discussion in 304 paragraphs. 306 o Blocks of text consist of inline text, which itself can contain 307 markup. 309 Inline markup includes: 311 o Text formatting: Bold, italic, superscript, subscript, monospace. 313 o Markup macros: the "bcp14" and "comment" macros. (Asciidoctor 314 syntax supports custom markup macros.) 316 o URLs, including display text to render. 318 o Inline anchors. 320 o Cross-references to anchors (IDs of blocks or spans of text), 321 including display text to render. 323 o Images: SVG only, as specified in [RFC7996]. 325 o Index terms. 327 3.1. Unsupported features compared with Asciidoctor syntax 329 Several features from Asciidoctor are not supported within AsciiRFC 330 due to the lack of support within RFC XML, including: 332 o Audio and video files are not supported in AsciiRFC as today's RFC 333 XML structure does not support audio or video. 335 o Equations are not supported as there is no current RFC XML 336 equivalent. Asciidoctor provides native support for [AsciiMathML] 337 and [TeX-LaTeX], via the [MathJax] tool. 339 o Footnotes are not supported in AsciiRFC as there is no equivalent 340 semantic representation in RFC XML. 342 These carved out features can be easily supported by AsciiRFC once 343 RFC XML allows these elements. 345 3.2. Mapping To RFC XML syntax 347 The Asciidoctor syntax document structure aligns with both the RFC 348 XML v2 and the RFC XML v3 structure. In the following, RFC XML v3 349 equivalences are given to the basic Asciidoctor structure. 351 Header 352 "" attributes, most "front" elements. 354 Preamble 355 "front/abstract" and "front/note". 357 Sections 358 "middle/section" elements. 360 Sections with bibliography style attribute 361 "back/references" elements. 363 Sections with appendix style attribute 364 "back/section" elements. 366 Paragraphs 367 "t" elements. 369 Lists 370 "ul", "ol", "dl" elements. 372 Delimited blocks 373 "artwork", "aside", "blockquote", "figure", "note", "sourcecode", 374 "table". 376 Inline markup 377 "bcp14", "br", "cref", "em", "eref", "iref", "relref", "strong", 378 "sub", "sup", "tt", "xref". 380 Full details of the mapping of AsciiRFC elements to RFC XML v2 and v3 381 elements, and of how to convert AsciiRFC documents to RFC XML, are 382 given in the documentation of [asciidoctor-rfc]. 384 3.3. Example Illustrations 386 This document utilizes example documents provided in Appendix A for 387 demonstration of AsciiRFC syntax and usage. The source files and 388 published versions (at the IETF Datatracker) of these example 389 documents are available in Appendix A. 391 o "A Minimal Internet-Draft In AsciiRFC" Appendix A.1.1 393 o "The Holy Hand Grenade of Antioch" Appendix A.2.1 395 o "An API For Calendar-Based Fortune Heuristics Services" 396 Appendix A.3.1 398 3.4. Simple Illustration 400 This section gives an overview of how to create an RFC XML document 401 in AsciiRFC, with some pitfalls to be aware of. 403 Illustrations are in RFC XML v3 and RFC XML v2. 405 A sample AsciiRFC document is provided in Figure 1, together with its 406 corresponding rendering in: 408 o RFC XML v3 (Figure 2) 410 o RFC XML v2 (Figure 3) 412 413 = A Minimal Internet-Draft In AsciiRFC 414 :doctype: internet-draft 415 :name: draft-asciirfc-minimal-00 416 :abbrev: AsciiRFC Example 417 :status: informational 418 :ipr: trust200902 419 :submissionType: individual 420 :area: Internet 421 :intended-series: full-standard 422 :revdate: 2018-03-23T00:00:00Z 423 :fullname: Josiah Stinkney Carberry 424 :lastname: Carberry 425 :forename_initials: J. S. 426 :organization: Brown University 427 :phone: +1 401 863 1000 428 :street: Box K, 69 Brown Street 429 :city: Providence 430 :code: 02912 431 :country: United States of America 432 :uri: https://www.brown.edu 433 :email: josiah.carberry@ribose.com 434 :fullname_2: Truman Grayson 435 :lastname_2: Grayson 436 :forename_initials_2: T. 437 :organization_2: Brown University 438 :phone_2: +1 401 863 1000 439 :street_2: Box G, 69 Brown Street 440 :city_2: Providence 441 :code_2: 02912 442 :country_2: United States of America 443 :uri_2: https://www.brown.edu 444 :email_2: truman.grayson@ribose.com 446 [abstract] 448 This document provides a template on how to author (or migrate!) 449 a new Internet-Draft / RFC in AsciiRFC format. This template 450 requires usage of the `asciidoctor-rfc` Ruby gem. 452 [#introduction] 453 == Introduction 455 AsciiRFC <> is an extremely simple way to 456 author Internet-Drafts and RFCs without needing to manually craft 457 RFC XML <>. 459 This is a template for authors to easily start with 460 <>. 462 [#conventions] 463 == Terms and Definitions 465 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 466 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 467 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this 468 document are to be interpreted as described in BCP 14 469 <> <> when, and only when, they appear in 470 all capitals, as shown here. 472 //// 473 Note: do not break formatted strings over carriage return. Bad 474 things happen. (In this instance, the carriage return is 475 suppressed, and no space takes its place.) This is an 476 Asciidoctor issue, not an asciidoctor-rfc issue. 477 //// 478 [#symbols] 479 == Symbols And Abbreviations 481 [#operators] 482 === Operators 484 AsciiRFC:: 485 As defined in <>. 487 [#security] 488 == Security Considerations 490 * Please beware of implementation issues caused by <>. 492 * Here's how you include references <>, 493 <>, <>. 495 [#iana] 496 == IANA Considerations 498 This document does not require any action by IANA. 500 [bibliography] 501 == Normative References 503 //bibliography::norm[] 504 ++++ 506 508 509 Key words for use in RFCs to Indicate Requirement 510 Levels 511 512 513 514 515 516 In many standards track documents several words are 517 used to signify the requirements in the specification. 518 These words are often capitalized. This document defines 519 these words as they should be interpreted in IETF 520 documents. This document specifies an Internet Best 521 Current Practices for the Internet Community, and 522 requests discussion and suggestions for improvements. 523 525 526 527 528 529 530 532 534 535 The "xml2rfc" Version 3 536 Vocabulary 537 538 539 540 541 542 This document defines the "xml2rfc" 543 version 3 vocabulary: an XML-based language used for 544 writing RFCs and Internet-Drafts. It is heavily derived 545 from the version 2 vocabulary that is also under 546 discussion. This document obsoletes the v2 grammar 547 described in RFC 7749. 548 549 550 551 552 554 556 557 Ambiguity of Uppercase vs Lowercase in RFC 2119 558 Key Words 559 560 561 562 563 564 RFC 2119 specifies common key words that may be 565 used in protocol specifications. This document aims to 566 reduce the ambiguity by clarifying that only UPPERCASE 567 usage of the key words have the defined special 568 meanings. 569 570 571 572 573 574 575 ++++ 577 [bibliography] 578 == Informative References 580 //bibliography::info[] 581 ++++ 583 584 585 Botan: Crypto and TLS for C++11 586 587 Ribose Inc. 588
589 590 Suite 1111, 1 Pedder Street 591 Central 592 Hong Kong 593 Hong Kong 594 595 open.source@ribose.com 596 https://www.ribose.com 597
598 599 600 601 603 604 605 AsciiRFC: Authoring Internet-Drafts And RFCs Using 606 AsciiDoc 608 609 610 612 614 615 617 619 620 622 624 This document describes the AsciiDoc syntax 625 extension 626 called AsciiRFC designed for authoring IETF Internet-Drafts 627 and RFCs. AsciiDoc is a human readable document markup 628 language which affords more granular control over markup than 629 comparable schemes such as Markdown. The AsciiRFC syntax is 630 designed to allow the author to entirely focus on text, 631 providing the full power of the resulting RFC XML through the 632 AsciiDoc language, while abstracting away the need to manually 633 edit XML, including references. This document itself was 634 written and generated into RFC XML v2 (RFC7749) and RFC XML v3 635 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC 636 generator. 638 640 642 646 648 649 650 The SM4 Blockcipher Algorithm And Its Modes Of 651 Operations 653 654 655 657 658 659 661 663 This document describes the SM4 symmetric 664 blockcipher 665 algorithm published as GB/T 32907-2016 by the State 666 Cryptography Administration of China (SCA). This document is 667 a product of the Crypto Forum Research Group 668 (CFRG). 670 672 674 678 680 682 683 The OCB Authenticated-Encryption 684 Algorithm 685 686 687 688 689 690 691 692 This document specifies OCB, a shared-key 693 blockcipher-based encryption scheme that provides 694 confidentiality and authenticity for plaintexts and 695 authenticity for associated data. This document is a product 696 of the Crypto Forum Research Group 697 (CFRG). 698 699 700 701 702 ++++ 704 [appendix] 705 [#appendix-a] 706 == Examples 708 === Example 1 710 Here's an example. 712 [source,json] 713 ---- 714 { 715 "code": { 716 "encoding": "ascii", 717 "type": "rfc", 718 "authors": [ "Josiah Carberry", "Truman Grayson" ] 719 } 720 } 721 ---- 723 [#acknowledgements] 724 == Acknowledgements 726 The authors would like to thank their families. 727 729 Figure 1: Sample Internet-Draft in AsciiRFC 731 The first block of text, from "= Template For Writing An Internet- 732 Draft In AsciiRFC" through to ":email_2: thomas.kandell@brown.edu", 733 is the document header. It contains a title in the first line, an 734 author attribution ("Josiah Carberry; Thomas Kandell"), and then a 735 set of document attributes, conveying information about the document 736 as well as information about its authors. This information ends up 737 in RFC XML either as attributes of the root "rfc" tag, elements of 738 the "front" tag, or processing instructions. 740 The following blocks of text, up until the first section header ("== 741 Introduction"), are the document preamble. They are treated by the 742 document converter as containing the document abstract ("abstract"), 743 followed by any notes if present. 745 Section headers delimit the sections of the main body of the 746 document, starting with "== Introduction". The document converter 747 treats the first section of the document as the start of the "middle" 748 section in RFC XML. The first section header is followed by a 749 paragraph, and other sections and paragraphs. The number of "=" 750 signs can be one higher than that of the preceding section header, 751 which indicates that they are subsections of that section; so "=== 752 Operators" is a subsection of the preceding "== Symbols And 753 Abbreviations". 755 The paragraphs contain some inline formatting (e.g. boldface: 756 "*MUST*", monospace: "`type`"), and sections can also contain blocks 757 other than normal paragraphs; the section "== Operators", for 758 example, contains a definition list (whose terms are delimited by 759 "::"), and the subsection "=== Example 1" contains a code snippet 760 (delimited by "----", and tagged with the style attribute 761 "[source,json]", indicating that this is a JSON sourcecode listing). 763 The document can also include comments ("//" for inline, "////" for 764 blocks), which are not rendered when the document is processed. 766 The introductory section in this example contains a citation of a 767 reference, which in this version of AsciiRFC is treated identically 768 to a cross-reference ("<>") -- the crossreference being to 769 the references section of the document. Sections and blocks of texts 770 within the document can also be the target of crossreferences; for 771 example, the section header "=== Operators" is preceded by the anchor 772 "[#operators]", and that anchor is already referenced in the section 773 "== Security Considerations". 775 The third last and second last section are tagged with the style 776 attribute "[bibliography]", which identifies them as references 777 containers; the document converter accordingly inserts them into the 778 "back" element under RFC XML. The contents of the references 779 sections are in this instance raw XML, delimited as a passthrough 780 block (with "++++"), which the converter does not alter. 782 The final section is tagged with the style attribute "[appendix]", 783 and is treated as such. 785 The RFC XML v3 document generated from this AsciiRFC document is: 787 788 789 790 791 792 793 794 795 796 797 798 799 800 A Minimal Internet-Draft In AsciiRFC 801 802 803 804 Brown University 805
806 807 Box K, 69 Brown Street 808 Providence 809 02912 810 United States of America 812 813 +1 401 863 1000 814 josiah.carberry@ribose.com 815 https://www.brown.edu 816
817 818 819 Brown University 820
821 822 Box G, 69 Brown Street 823 Providence 824 02912 825 United States of America 826 827 +1 401 863 1000 828 truman.grayson@ribose.com 829 https://www.brown.edu 830
831 832 833 Internet 835 836 This document provides a template on how to author (or migrate!) 837 a new Internet-Draft / RFC in AsciiRFC format. This template 838 requires usage of the asciidoctor-rfc Ruby gem. 839 840 841
IntroductionAsciiRFC is an extremely simple way to 842 author Internet-Drafts and RFCs without needing to manually craft 843 RFC XML . 844 This is a template for authors to easily start with 845 .
846
847 Terms and Definitions 848 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", 849 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", 850 "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 851 document are to be interpreted as described in BCP 14 852 when, and only when, they appear in 853 all capitals, as shown here. 854
855
856 Symbols And Abbreviations 857
858 Operators 859
860
AsciiRFC
861
As defined in .
862
863
864
865
866 Security Considerations 867
    868
  • Please beware of implementation issues caused by .
    • 869
  • Here’s how you include references , 870 , .
    • 871
872
873
874 IANA Considerations 875 This document does not require any action by IANA. 876
877 878 879 Normative References 880 881 882 883 884 885 Informative References 886 887 888 Botan: Crypto and TLS for C++11 889 890 Ribose Inc. 891
892 893 Suite 1111, 1 Pedder Street 894 Central 895 Hong Kong 896 Hong Kong 897 898 open.source@ribose.com 899 https://www.ribose.com 900
901 902 903 904 905 906 907 909 910
911 Examples 912
Example 1Here’s an example. 913
914 { 915 "code": { 916 "encoding": "ascii", 917 "type": "rfc", 918 "authors": [ "Josiah Carberry", "Truman Grayson" ] 919 } 920 } 921
922
923
924 Acknowledgements 925 The authors would like to thank their families. 926
927 928 929 931 Figure 2: Sample Internet-Draft In AsciiRFC, Output In RFC XML v3 932 Format 934 Some default processing instructions have already been prefixed to 935 the XML. 937 Our AsciiRFC converter can also generate RFC XML v2 from the same 938 source AsciiRFC, as shown in Figure 3. Output in RFC XML v2 is not 939 extensively described in this document. 941 942 943 944 946 947 948 949 950 951 ]> 952 953 954 955 956 957 958 959 960 961 A Minimal Internet-Draft In AsciiRFC 962 963 Brown University 964
965 966 Box K, 69 Brown Street 967 Providence 968 02912 969 United States of America 970 971 +1 401 863 1000 972 josiah.carberry@ribose.com 973 https://www.brown.edu 974
975 976 977 Brown University 978
979 980 Box G, 69 Brown Street 981 Providence 982 02912 983 United States of America 984 985 +1 401 863 1000 986 truman.grayson@ribose.com 987 https://www.brown.edu 988
989 990 991 Internet 993 994 This document provides a template on how to author (or migrate!) 995 a new Internet-Draft / RFC in AsciiRFC format. This template 996 requires usage of the asciidoctor-rfc Ruby gem. 997 998 999
AsciiRFC is an extremely simple way to 1000 author Internet-Drafts and RFCs without needing to manually craft 1001 RFC XML . 1002 This is a template for authors to easily start with 1003 .
1004
1005 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", 1006 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", 1007 "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 1008 document are to be interpreted as described in BCP 14 1009 when, and only when, they appear in 1010 all capitals, as shown here. 1011
1012
1013
1014 1015 1016 As defined in . 1017 1018 1019
1020
1021
1022 1023 1024 Please beware of implementation issues caused by . 1025 Here’s how you include references , 1026 , . 1027 1028 1029
1030
1031 This document does not require any action by IANA. 1032
1033 1034 1035 &RFC2119; 1036 &RFC7991; 1037 &RFC8174; 1038 1039 1040 1041 1042 Botan: Crypto and TLS for C++11 1043 1044 Ribose Inc. 1045
1046 1047 Suite 1111, 1 Pedder Street 1048 Central 1049 Hong Kong 1050 Hong Kong 1051 1052 open.source@ribose.com 1053 https://www.ribose.com 1054
1055 1056 1057 1058 1059 &I-D.ribose-asciirfc; 1060 &I-D.ribose-cfrg-sm4; 1061 &RFC7253; 1062 1063
1064
Here’s an example. 1065
1066 { 1067 "code": { 1068 "encoding": "ascii", 1069 "type": "rfc", 1070 "authors": [ "Josiah Carberry", "Truman Grayson" ] 1071 } 1072 } 1073
1074
1075
1076 The authors would like to thank their families. 1077
1078 1079 1080 1082 Figure 3: Sample Internet-Draft In AsciiRFC, Output In RFC XML v2 1083 Format 1085 4. Header And Document Attributes 1087 The header gives the document title, followed by an optional author 1088 attribution, and a series of document attributes, with no empty 1089 lines. 1091 4.1. Title And Basic Attributes 1093 Document attributes are used to populate attributes of the root "rfc" 1094 element, "front" elements, and document-level processing 1095 instructions. 1097 o ":doctype:" determines whether the document will be considered 1098 "rfc" or "internet-draft", and interprets other attributes 1099 accordingly. 1101 o Certain attributes ("workgroup", "area", "keyword") are comma 1102 delimited, and result in repeated RFC XML elements. 1104 Figure 4 demonstrates how to set the document header in AsciiRFC, 1105 with its rendering in RFC XML v3 shown in Figure 5. 1107 1108 = The Holy Hand Grenade of Antioch 1109 Arthur son of Uther Pendragon 1110 :doctype: internet-draft 1111 :abbrev: Hand Grenade of Antioch 1112 :updates: 8140 1113 :submission-type: independent 1114 :name: draft-camelot-holy-grenade-00 1115 :status: informational 1116 :consensus: false 1117 :area: General, Operations and Management 1118 :keyword: rabbits, grenades, antioch, camelot 1119 :ipr: trust200902 1120 :toc-include: true 1121 :sort-refs: true 1122 :revdate: 2018-04-01 1123 1125 Figure 4: AsciiRFC Document Header 1127 1128 1129 1130 The Holy Hand Grenade of Antioch 1131 1132 1133 Camelot 1134
1135 1136 Palace 1137 Camel Lot 1 1138 Camelot 1139 antioch 1141 1142 1144 1146 Figure 5: AsciiRFC Document Header Rendered As RFC XML v3 1148 4.2. Detailed Author Information 1150 The document header can spell out further information about authors, 1151 including contact details. The AsciiRFC header is shown in Figure 6 1152 with its rendering in RFC XML v3 shown in Figure 7. 1154 1155 = The Holy Hand Grenade of Antioch 1156 Arthur son of Uther Pendragon 1157 :doctype: internet-draft 1158 :abbrev: Hand Grenade of Antioch 1159 :updates: 8140 1160 :submission-type: independent 1161 :name: draft-camelot-holy-grenade-00 1162 :status: informational 1163 :consensus: false 1164 :area: General, Operations and Management 1165 :keyword: rabbits, grenades, antioch, camelot 1166 :ipr: trust200902 1167 :toc-include: true 1168 :sort-refs: true 1169 :revdate: 2018-04-01 1170 :fullname: Arthur son of Uther Pendragon 1171 :forename_initials: A. 1172 :lastname: Pendragon 1173 :email: arthur.pendragon@ribose.com 1174 :organization: Camelot 1175 :uri: http://camelot.gov.example 1176 :street: Palace\ Camel Lot 1 1177 :city: Camelot 1178 :country: England 1179 :comments: yes 1180 1182 Figure 6: AsciiRFC Document Header With One Author 1184 1185 1186 1187 The Holy Hand Grenade of Antioch 1188 1189 1190 Camelot 1191
1192 1193 Palace 1194 Camel Lot 1 1195 Camelot 1196 England 1197 1198 arthur.pendragon@ribose.com 1199 http://camelot.gov.example 1200
1201 1202 1203 General 1204 Operations and Management 1205 rabbits 1206 grenades 1207 antioch 1208 camelot 1210 1211 1213 1215 Figure 7: AsciiRFC Document Header With One Author (RFC XML v3) 1217 Details of a second, third etc. author, including their organization 1218 and contact details, are provided by suffixing the relevant author 1219 attributes with "_2", "_3" etc., as shown in Figure 8 and its RFC XML 1220 v3 rendering Figure 9. 1222 1223 = An API For Calendar-Based Fortune Heuristics Services 1224 Gabriel Destiny; Charise Luck 1225 :doctype: internet-draft 1226 :abbrev: Calendar Fortune Heuristics API 1227 :name: draft-divination-cfapi-00 1228 :status: informational 1229 :ipr: trust200902 1230 :area: Internet 1231 :submission-type: independent 1232 :intended-series: informational 1233 :revdate: 2018-03-23T00:00:00Z 1234 :lastname: Destiny 1235 :fullname: Gabriel Destiny 1236 :forename_initials: G. 1237 :organization: Divination Inc. 1238 :email: gabriel.destiny@ribose.com 1239 :street: 9288 N Divine Street 1240 :city: Dunn 1241 :code: 28334 1242 :region: NC 1243 :country: United States of America 1244 :lastname_2: Luck 1245 :fullname_2: Charise Luck 1246 :forename_initials_2: C. 1247 :organization_2: Divination Inc. 1248 :email_2: charise.luck@ribose.com 1249 :street_2: 9288 N Divine Street 1250 :city_2: Dunn 1251 :code_2: 28334 1252 :region_2: NC 1253 :country_2: United States of America 1254 1256 Figure 8 1258 1259 1260 1261 An API For Calendar-Based Fortune Heuristics Services 1262 1263 1264 1265 Divination Inc. 1266
1267 1268 9288 N Divine Street 1269 Dunn 1270 NC 1271 28334 1272 United States of America 1273 1274 gabriel.destiny@ribose.com 1275
1276 1277 1278 Divination Inc. 1279
1280 1281 9288 N Divine Street 1282 Dunn 1283 NC 1284 28334 1285 United States of America 1286 1287 charise.luck@ribose.com 1288
1289 1290 1291 Internet 1293 1294 1296 1298 Figure 9: AsciiRFC Document Header With Multiple Authors (RFC XML v3) 1300 The initial author attribution in AsciiRFC, e.g. "Gabriel Destiny; 1301 Charlise Luck" in the example above, expects a strict format of First 1302 Name, zero or more Middle Names, Last name, and cannot process 1303 honorifics like "Dr." or suffixes like "Jr.". 1305 Name attributes with any degree of complexity should be overriden by 1306 using the ":fullname:" and ":lastname:" attributes. The AsciiRFC 1307 ":forename_initials:" attribute replaces the built-in Asciidoctor 1308 syntax ":initials:" attribute (which includes the surname initial), 1309 and is not automatically populated from the name attribution. 1311 4.3. XML Processing Information 1313 A document header may also contain attribute headers which are 1314 treated as XML processing instructions. An AsciiRFC example is shown 1315 in Figure 10 with its rendering in Figure 11. (Note that several 1316 processing instructions are included by default in the output of the 1317 AsciiRFC processor.) 1319 1320 = The Holy Hand Grenade of Antioch 1321 Arthur son of Uther Pendragon 1322 :doctype: internet-draft 1323 :abbrev: Hand Grenade of Antioch 1324 :updates: 8140 1325 :submission-type: independent 1326 :name: draft-camelot-holy-grenade-00 1327 :status: informational 1328 :consensus: false 1329 :ipr: trust200902 1330 :notedraftinprogress: yes 1331 :smart-quotes: false 1332 1334 Figure 10: AsciiRFC Document Header With XML Processing Information 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 The Holy Hand Grenade of Antioch 1352 1353 1354 Camelot 1355
1356 1357 Palace 1358 Camel Lot 1 1359 Camelot 1360 antioch 1361 1363 Figure 11: AsciiRFC Document Header With XML Processing Information 1364 (RFC XML v3) 1366 In the foregoing, values for the processing instructions "strict", 1367 "compact", "toc" etc are included by default; but "comments" and 1368 "notedraftinprogress" are included as specified in the AsciiRFC 1369 document header. The default values provided for processing 1370 instructions can in fact be overriden through the AsciiRFC document 1371 header. 1373 4.4. AsciiRFC-specific Document Attributes 1375 A few document attributes are specific to the operation of the RFC 1376 XML document converter: 1378 :no-rfc-bold-bcp14: false 1379 overrides the wrapping by default of boldface uppercase BCP14 1380 [RFC2119] words (e.g. "*MUST NOT*") with the "bcp14" element. 1382 :smart-quotes: false 1383 overrides Asciidoctor's conversion of straight quotes and 1384 apostrophes to smart quotes and apostrophes. 1386 :inline-definition-lists: true 1387 overrides the RFC XML v2 "idnits" requirement that a blank line be 1388 inserted between a definition list term and its definition. 1390 1391 = The Holy Hand Grenade of Antioch 1392 Arthur son of Uther Pendragon 1393 :doctype: internet-draft 1394 :status: informational 1395 :name: draft-camelot-holy-grenade-00 1397 == Section 1 1398 The specification *MUST NOT* use the word _doesn't_. 1399 1401 Figure 12: AsciiRFC Document Header Without RFC-specific Attributes 1403 1404 1405 1406 The Holy Hand Grenade of Antioch 1407 1409 1411 1412 1413 1414 1415
1416 Section 1 1417 The specification MUST NOT 1418 use the word doesn’t. 1419
1420 1421 1422 1424 Figure 13: AsciiRFC Document Header Without RFC-specific Attributes 1425 (RFC XML v3) 1427 1428 = The Holy Hand Grenade of Antioch 1429 Arthur son of Uther Pendragon 1430 :doctype: internet-draft 1431 :status: informational 1432 :name: draft-camelot-holy-grenade-00 1433 :no-rfc-bold-bcp14: false 1434 :smart-quotes: false 1436 == Section 1 1437 The specification *MUST NOT* use the word _doesn't_. 1438 1440 Figure 14: AsciiRFC Document Header With Overridden RFC-specific 1441 Attributes 1443 1444 1445 1446 The Holy Hand Grenade of Antioch 1447 1449 1451 1452 1453 1454 1455
1456 Section 1 1457 The specification MUST NOT 1458 use the word doesn't. 1459
1460 1461 1462 1464 Figure 15: AsciiRFC Document Header With Overridden RFC-specific 1465 Attributes (RFC XML v3) 1467 5. Preamble 1469 The preamble in AsciiRFC is the text between the end of the document 1470 header (which terminates with a blank line) and the first section of 1471 text. 1473 Any paragraphs of text in the preamble are treated as an abstract, 1474 and may optionally be tagged with the "abstract" style attribute. 1476 Any notes in the preamble are treated as a "note" element. 1478 An example of setting the preamble is given in Figure 16 with its 1479 rendering in Figure 17. 1481 1483 [abstract] 1484 The menagerie of beasts and artefacts depicted in RFC8140 1485 may be usefully supplemented by other renowned figures of 1486 Internet and more general lore. This document extends the 1487 menagerie to the seminal fable of the 1488 "Holy Hand Grenade of Antioch", as depicted in the 1489 Monty Python film "Monty Python and the Holy Grail", 1490 as well as "Spamalot", the musical inspired by the movie. 1492 [NOTE,remove-in-rfc=false] 1493 .Spamalot 1494 The relevance of the musical "Spamalot" to Internet lore should be 1495 obvious to the reader; but in case of doubt, see also 1496 Section 1 ("What is Spam*?") of RFC2635. 1498 1500 Figure 16: AsciiRFC With Preamble 1502 1503 1505 The menagerie of beasts and artefacts depicted in RFC8140 1506 may be usefully supplemented by other renowned figures of 1507 Internet and more general lore. This document extends the 1508 menagerie to the seminal fable of the 1509 "Holy Hand Grenade of Antioch", as depicted in the 1510 Monty Python film "Monty Python and the Holy Grail", 1511 as well as "Spamalot", the musical inspired by the movie. 1512 Spamalot 1513 The relevance of the musical "Spamalot" to Internet lore should be 1514 obvious to the reader; but in case of doubt, see also 1515 Section 1 ("What is Spam*?") of RFC2635. 1516 1518 1519 1521 Figure 17: AsciiRFC With Preamble (RFC XML v3) 1523 6. Sections and Paragraphs 1525 Section headers are given with a sequence of "=", where the number of 1526 instances of "=" gives the header level. The document itself opens 1527 with a single "=", and sections within it must be started with a 1528 minimum of "==". 1530 Section numbering is toggled with the in-document attribute 1531 ":sectnums:" (on), ":sectnums!:" (off). The boolean "toc" attribute 1532 can also be set on sections, indicating whether the section can be 1533 included in the document's table of contents. 1535 Figure 18 shows how sections and paragraphs are used in AsciiRFC, and 1536 its rendered form is shown in Figure 19. 1538 1540 [toc=exclude] 1541 :sectnums!: 1542 == Terminology 1544 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 1545 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 1546 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 1547 are to be interpreted as described in BCP 14 <> <> 1548 when, and only when, they appear in all capitals, as shown here. 1550 :sectnums: 1551 == Introduction 1553 <> refers to the intended move of RFC formatting to 1554 XML2RFC v3 <>, in the following terms: 1556 1558 Figure 18: AsciiRFC With Sections 1560 1562 1563
1564 Terminology 1565 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", 1566 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", 1567 "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document 1568 are to be interpreted as described in BCP 14 1569 when, and only when, they appear in all capitals, as shown here. 1570
1571
Introduction refers to the intended move of RFC formatting to 1572 XML2RFC v3 , in the following terms: 1574 1576 Figure 19: AsciiRFC With Sections (RFC XML v3) 1578 Note that skipped sections, such as defining a section using "====" 1579 within a section defined using "==", is not allowed in AsciiRFC 1580 syntax. Doing so will trigger an error with the following message: 1582 asciidoctor: WARNING: _filename_: line _X_: 1583 section title out of sequence: expected level 2, got level 3 1585 7. Figures 1587 AsciiRFC examples (corresponding to RFC XML Figures), source code 1588 Listings, and Literals (preformatted text) are all delimited blocks. 1589 Listings and Literals can occur nested within Examples. 1591 An AsciiRFC example with a figure is given in Figure 20, and its 1592 rendering in Figure 21. 1594 1596 [[killer-bunny]] 1597 .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 1598 ==== 1599 [alt=The Killer Bunny, in ASCII] 1600 .... 1601 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1602 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1603 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 1604 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 1605 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 1606 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 1607 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 1608 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 1609 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 1610 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 1611 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 1612 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 1613 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 1614 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 1615 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 1616 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 1617 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 1618 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 1619 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 1620 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 1621 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 1622 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 1623 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 1624 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 1625 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 1626 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 1627 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 1628 MW \\/\||v v|| -\\-------___ . ., \ | 1629 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 1630 ) /--------^-^ ,. \|// 1631 # \(/ .\\|x// " ' ' 1632 . , \\||// \||\\\// \\ 1633 .... 1634 ==== 1636 [[killer-source]] 1637 .C Code To Lure Killer Rabbit Back To Cave 1638 ==== 1639 [source,c] 1640 ---- 1641 1642 /* Locate the Killer Rabbit */ 1643 int type; 1644 unsigned char *killerRabbit = 1645 LocateCreature(&caerbannog, "killer rabbit"); 1646 if( killerRabbit == 0 ){ 1647 puts("The Killer Rabbit of Caerbannog is out of town."); 1648 return LOST_CREATURE; 1649 } 1651 /* Load Cave */ 1652 unsigned char *cave = LoadPlace(&caerbannog, 1653 "The Cave Of Caerbannog"); 1654 if( cave == 0 ){ 1655 puts("The Cave of Caerbannog must have moved."); 1656 return LOST_PLACE; 1657 } 1659 /* Lure the Killer Rabbit back into the Cave */ 1660 unsigned char *carrot = allocateObjectInPlace( 1661 carrot("fresh"), cave); 1662 if( carrot == 0 ){ 1663 puts("No carrot, no rabbit."); 1664 return LOST_LURE; 1665 } 1667 /* Finally, notify the Killer Rabbit to act */ 1668 return notifyCreature(killerRabbit, &carrot); 1669 1670 ---- 1671 ==== 1673 1675 Figure 20: AsciiRFC With A Figure 1677 1679
1680 A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 1681 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1682 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1683 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 1684 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 1685 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 1686 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 1687 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 1688 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 1689 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 1690 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 1691 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 1692 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 1693 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 1694 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 1695 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 1696 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 1697 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 1698 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 1699 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 1700 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 1701 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 1702 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 1703 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 1704 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 1705 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 1706 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 1707 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 1708 MW \\/\||v v|| -\\-------___ . ., \ | 1709 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 1710 ) /--------^-^ ,. \|// 1711 # \(/ .\\|x// " ' ' 1712 . , \\||// \||\\\// \\ 1713
1714
1715 C Code To Lure Killer Rabbit Back To Cave 1716 <CODE BEGINS> 1717 /* Locate the Killer Rabbit */ 1718 int type; 1719 unsigned char *killerRabbit = 1720 LocateCreature(&caerbannog, "killer rabbit"); 1721 if( killerRabbit == 0 ){ 1722 puts("The Killer Rabbit of Caerbannog is out of town."); 1723 return LOST_CREATURE; 1724 } 1726 /* Load Cave */ 1727 unsigned char *cave = LoadPlace(&caerbannog, 1728 "The Cave Of Caerbannog"); 1729 if( cave == 0 ){ 1730 puts("The Cave of Caerbannog must have moved."); 1731 return LOST_PLACE; 1732 } 1734 /* Lure the Killer Rabbit back into the Cave */ 1735 unsigned char *carrot = allocateObjectInPlace( 1736 carrot("fresh"), cave); 1737 if( carrot == 0 ){ 1738 puts("No carrot, no rabbit."); 1739 return LOST_LURE; 1740 } 1742 /* Finally, notify the Killer Rabbit to act */ 1743 return notifyCreature(killerRabbit, &carrot); 1744 <CODE ENDS> 1745
1747 1749 Figure 21: AsciiRFC With A Figure (RFC XML v3) 1751 If an AsciiRFC Listing or Literal occurs outside of an Example 1752 (Figure 22), the RFC XML converter will supply the surrounding 1753 Figure element (Figure 23). 1755 1757 [[hand-grenade-figure]] 1758 .The Holy Hand Grenade of Antioch (don't pull the pin) 1760 Figure 22: AsciiRFC With ASCII Art Without Figure Wrapping 1762 ______ 1763 \\/ \/ 1764 __\\ /__ 1765 || //\ | 1766 ||__\\/ __| 1767 || | ,---, 1768 || |====`\ | 1769 || | '---' 1770 ,--'*`--, 1771 _||#|***|#| 1772 _,/.-'#|* *|#`-._ 1773 ,,-'#####| |#####`-. 1774 ,,'########| |########`, 1775 //##########| o |##########\ 1776 ||###########| |###########| 1777 ||############| o |############| 1778 ||------------' '------------| 1779 ||o o o o o o o o o o| 1780 |-----------------------------| 1781 ||###########################| 1782 \\#########################/ 1783 `..#####################,' 1784 ``..###############_,' 1785 ``--.._____..--' 1786 `''-----''` 1788 1790 1792
1793 The Holy Hand Grenade of Antioch (don't pull the pin) 1794 ______ 1795 \\/ \/ 1796 __\\ /__ 1797 || //\ | 1798 ||__\\/ __| 1799 || | ,---, 1800 || |====`\ | 1801 || | '---' 1802 ,--'*`--, 1803 _||#|***|#| 1804 _,/.-'#|* *|#`-._ 1805 ,,-'#####| |#####`-. 1806 ,,'########| |########`, 1807 //##########| o |##########\ 1808 ||###########| |###########| 1809 ||############| o |############| 1810 ||------------' '------------| 1811 ||o o o o o o o o o o| 1812 |-----------------------------| 1813 ||###########################| 1814 \\#########################/ 1815 `..#####################,' 1816 ``..###############_,' 1817 ``--.._____..--' 1818 `''-----''` 1819
1821 1823 Figure 23: AsciiRFC With ASCII Art Without Figure Wrapping (RFC XML 1824 v3) 1826 8. Lists 1828 8.1. Basic Lists 1830 AsciiRFC supports ordered, unordered, and definition lists. 1831 Indentation of ordered and unordered lists is indicated by repeating 1832 the list item prefix ("*" and "." respectively); for definition 1833 lists, it is indicated by incrementing the number of definition term 1834 delimiters ("::"). 1836 List attributes can be used to specify the type of symbol used for 1837 ordered lists. 1839 An example of an unordered list is shown in Figure 24 (with its 1840 rendered version in Figure 25). An example of an ordered list with 1841 ordered and unordered sublists is shown in Figure 26 (with its 1842 rendered version in Figure 27). An example of a definition list is 1843 shown in Figure 28 (with its rendered version in Figure 29). 1845 1847 * Killed 1848 ** Sir Bors 1849 ** Sir Gawain 1850 ** Sir Ector 1851 * Soiled Himself 1852 ** Sir Robin 1853 * Panicked 1854 ** King Arthur 1855 * Employed Ordnance 1856 ** The Lector 1857 ** Brother Maynard 1858 * Scoffed 1859 ** Tim the Enchanter 1861 1863 Figure 24: AsciiRFC With Unordered lists 1865 1867
    1868
  • 1869 Killed 1870
      1871
    • Sir Bors
      • 1872
    • Sir Gawain
      • 1873
    • Sir Ector
      • 1874
    1875
    • 1876
  • 1877 Soiled Himself 1878
      1879
    • Sir Robin
      • 1880
    1881
    • 1882
  • 1883 Panicked 1884
      1885
    • King Arthur
      • 1886
    1887
    • 1888
  • 1889 Employed Ordnance 1890
      1891
    • The Lector
      • 1892
    • Brother Maynard
      • 1893
    1894
    • 1895
  • 1896 Scoffed 1897
      1898
    • Tim the Enchanter
      • 1899
    1900
    • 1901
1903 1905 Figure 25: AsciiRFC With Unordered Lists (RFC XML v3) 1907 1909 . Preamble: St Attila Benediction 1910 . Feast of the People on Sundry Foods 1911 ** Lambs 1912 ** Sloths 1913 ** Carp 1914 ** Anchovies 1915 ** Orangutangs 1916 ** Breakfast Cereals 1917 ** Fruit Bats 1918 ** _et hoc genus omne_ 1919 . Take out the Holy Pin 1920 . The Count 1921 [upperalpha] 1922 .. Count is to Three: no more, no less 1923 .. Not Four 1924 .. Nor Two, except if the count then proceeds to Three 1925 .. Five is Right Out 1926 . Lob the Holy Hand Grenade of Antioch towards the Foe 1927 . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it 1929 1931 Figure 26: AsciiRFC With Ordered lists 1933 1935
    1936
  1. Preamble: St Attila Benediction
    2. 1937
  2. 1938 Feast of the People on Sundry Foods 1939
      1940
    • Lambs
      • 1941
    • Sloths
      • 1942
    • Carp
      • 1943
    • Anchovies
      • 1944
    • Orangutangs
      • 1945
    • Breakfast Cereals
      • 1946
    • Fruit Bats
      • 1947
    • 1948 et hoc genus omne 1949
      • 1950
    1951
    3. 1952
  3. Take out the Holy Pin
    4. 1953
  4. 1954 The Count 1955
      1956
    1. Count is to Three: no more, no less
      2. 1957
    2. Not Four
      3. 1958
    3. Nor Two, except if the count then proceeds to Three
      4. 1959
    4. Five is Right Out
      5. 1960
    1961
    5. 1962
  5. Lob the Holy Hand Grenade of Antioch towards the Foe
    6. 1963
  6. The Foe, being naughty in the LORD's sight, SHALL snuff it
    7. 1964
1966 1968 Figure 27: AsciiRFC With Ordered Lists (RFC XML v3) 1970 1972 Holy Hand Grenade of Antioch:: 1973 Ordnance deployed by Brother Maynard under the incantation of a 1974 lector, in order to dispense with the Foes of the Virtuous. 1975 See <>. 1977 Holy Spear of Antioch:: 1978 A supposed relic of the crucifixion of Jesus Christ, this is one 1979 of at least four claimed instances of the lance that pierced 1980 Christ's side. Its historical significance lies in inspiring 1981 crusaders to continue their siege of Antioch in 1098. 1983 Sovereign's Orb of the United Kingdom:: 1984 Part of the Crown Jewels of the United Kingdom, the Sovereign's 1985 Orb is a hollow gold sphere set with jewels and topped with a 1986 cross. It was made for Charles II in 1661. See <>. 1988 1990 Figure 28: AsciiRFC With Definition lists 1992 1994
1995
Holy Hand Grenade of Antioch
1996
Ordnance deployed by Brother Maynard under the incantation of a 1997 lector, in order to dispense with the Foes of the Virtuous. 1998 See .
1999
Holy Spear of Antioch
2000
A supposed relic of the crucifixion of Jesus Christ, this is one 2001 of at least four claimed instances of the lance that pierced 2002 Christ's side. Its historical significance lies in inspiring 2003 crusaders to continue their siege of Antioch in 1098.
2004
Sovereign's Orb of the United Kingdom
2005
Part of the Crown Jewels of the United Kingdom, the Sovereign's 2006 Orb is a hollow gold sphere set with jewels and topped with a 2007 cross. It was made for Charles II in 1661. See .
2008
2010 2012 Figure 29: AsciiRFC With Definition Lists (RFC XML v3) 2014 8.2. List Continuation 2016 A list item by default spans a single paragraph. A following 2017 paragraph or other block element can be appended to the current list 2018 item by prefixing it with "+" in a separate line. 2020 See the "List Continuation" section in [Asciidoctor-Manual] for more 2021 information. 2023 An example of list continuation with text is shown in Figure 30 with 2024 its rendered version in Figure 31. 2026 2028 Trojan Rabbit:: 2029 In their siege of the French-occupied castle which may already 2030 contain an instance of the Grail, Sir Bedevere the Wise proposes to 2031 use a Trojan Rabbit to infiltrate the castle, with a raiding party 2032 to take the French "not only by surprise, but totally unarmed." 2033 + 2034 The proposal, unsurprisingly, proved abortive. The more so as the 2035 raiding party forgot to hide within the Trojan Rabbit, before the 2036 French soldiers took the Trojan Rabbit inside the castle. 2038 Killer Rabbit of Caerbannog:: 2039 Guarding the entrance to the Cave of Caerbannog; see <>. 2041 2043 Figure 30: AsciiRFC List With Text Continuation 2045 2047
2048
Trojan Rabbit
2049
2050 In their siege of the French-occupied castle which may already 2051 contain an instance of the Grail, Sir Bedevere the Wise proposes to 2052 use a Trojan Rabbit to infiltrate the castle, with a raiding party 2053 to take the French "not only by surprise, but totally unarmed." 2054 The proposal, unsurprisingly, proved abortive. The more so as the 2055 raiding party forgot to hide within the Trojan Rabbit, before the 2056 French soldiers took the Trojan Rabbit inside the castle. 2057
2058
Killer Rabbit of Caerbannog
2059
Guarding the entrance to the Cave of Caerbannog; see .
2060
2062 2064 Figure 31: AsciiRFC List With Text Continuation (RFC XML v3) 2066 (Multiple paragraphs are not permitted within a list item in RFC XML 2067 v2. The RFC XML converter deals with this by converting paragraph 2068 breaks into line breaks within a list item.) 2070 List continuations can also be embedded to populate a list item with 2071 a sequence of blocks as a unit (in an Asciidoctor syntax open block). 2073 An example of list continuation with a delimited block is shown in 2074 Figure 32 with its rendered version in Figure 33. 2076 2078 . Take out the Holy Pin 2079 . The Count 2080 + 2081 ---- 2082 integer count; 2083 for count := 1 step 1 until 3 do 2084 say(count) 2085 comment Five is Right Out 2086 ---- 2087 . Lob the Holy Hand Grenade of Antioch towards the Foe 2088 . Foe snuffs it 2090 2092 Figure 32: AsciiRFC List With Block Continuation 2094 2096
    2097
  1. Take out the Holy Pin
    2. 2098
  2. 2099 The Count 2100
    2101 integer count; 2102 for count := 1 step 1 until 3 do 2103 say(count) 2104 comment Five is Right Out 2105
    2106
    3. 2107
  3. Lob the Holy Hand Grenade of Antioch towards the Foe
    4. 2108
  4. Foe snuffs it
    5. 2109
2111 2113 Figure 33: AsciiRFC List With Block Continuation (RFC XML v3) 2115 AsciiDoc, and thus AsciiRFC, considers paragraphs to be the basic 2116 level of blocks, and does not permit lists to be nested within them: 2117 any text after a list is considered to be a new paragraph. 2119 Therefore, markup as shown in Figure 34 cannot be generated via 2120 AsciiRFC. 2122 2123 2124 This is the start of a paragraph. 2125
    2126
  • List Entry 1
    • 2127
  • 2128 List Entry 2 2129 Note 2. 2130
    • 2131
2132 And this is the continuation of the paragraph. 2133 2134 2136 Figure 34: This RFC XML v3 Output Cannot Be Generated Using AsciiRFC 2138 9. Blockquotes 2140 Asciidoctor syntax supports blockquotes and quotations of verse; its 2141 block quotations permit arbitrary levels of quote nesting. RFC XML 2142 v3, and thus AsciiRFC, only supports one level of blockquotes. 2144 Unlike RFC XML v2, RFC XML v3 does not support line breaks outside of 2145 tables, so verse quotations are converted to prose in the v3 2146 converter. 2148 An example of using AsciiRFC Blockquotes is given in Figure 35 with 2149 its rendered version in Figure 36. 2151 2153 [quote,attribution="A. Farrel"] 2154 ____ 2155 Although the RFC Editor has recently dragged the IETF kicking and 2156 screaming into the twentieth century [RFC7990] [RFC7996], there is a 2157 yearning among all right-thinking Internet architects to "keep it 2158 simple" and to return to the olden days when pigs could be given 2159 thrust without anyone taking undue offence. 2160 ____ 2162 2164 Figure 35: AsciiRFC Blockquote Usage 2166 2168
2169 Although the RFC Editor has recently dragged the IETF kicking and 2170 screaming into the twentieth century [RFC7990] [RFC7996], there is a 2171 yearning among all right-thinking Internet architects to "keep it 2172 simple" and to return to the olden days when pigs could be given 2173 thrust without anyone taking undue offence. 2174
2176 2178 Figure 36: AsciiRFC Blockquote Usage (RFC XML v3) 2180 10. Notes And Asides 2182 Asciidoctor syntax supports a range of "admonitions", including 2183 notes, warnings, and tips. They are indicated by a paragraph prefix 2184 (e.g. "WARNING:"), or as a block with an admonition style attribute. 2186 All admonitions are conflated in AsciiRFC, being converted to "note" 2187 elements in the document preamble, and "cref" elements in the main 2188 document. 2190 This means that no admonitions will therefore appear in the textual 2191 output, unless forced to through the "comments" processing 2192 instruction. A sample admonition is shown in Figure 37, with its 2193 rendered output in Figure 38. 2195 2197 [NOTE,display=true,source=Author] 2198 ==== 2199 Image courtesy of 2200 https://camelot.gov.example/creatures-in-ascii/ 2201 ==== 2203 2205 Figure 37: An AsciiRFC Adminition Block 2207 2209 Image courtesy of 2210 2212 2214 Figure 38: An AsciiRFC Adminition Block (RFC XML v3) 2216 With RFC XML v2, note that no inline formatting is permitted for 2217 "cref" elements, and any such formatting is therefore stripped for v2 2218 by the converter. 2220 Because paragraphs in AsciiRFC cannot contain any other blocks, a 2221 comment at the end of a paragraph is treated as a new block. In the 2222 document converter, any such comments are moved inside the preceding 2223 RFC XML paragraph; if the comment is at the start of a section, as in 2224 the example above, it is wrapped inside a paragraph. 2226 The RFC XML v3 converter also supports "asides" (Asciidoctor syntax 2227 Sidebars). A sample is shown in Figure 39, with its rendered output 2228 in Figure 40. 2230 2232 **** 2233 While the exchange at the French-occupied castle is one of 2234 the more memorable scenes of _Monty Python and the Holy Grail_, 2235 the Trojan Rabbit has not reached the same level of cultural 2236 resonance as its more murderous counterpart. Reasons for this 2237 may include: 2239 * Less overall screen-time dedicated to the Trojan Rabbit. 2241 * The Trojan Rabbit as projectile has already been anticipated 2242 by the Cow as projectile. 2243 **** 2245 2247 Figure 39: An AsciiRFC Sidebar Block 2249 2251 2262 2264 Figure 40: An AsciiRFC Sidebar Block Rendered As An Aside (RFC XML 2265 v3) 2267 Comments given in AsciiDoc syntax (notated with initial "//") are not 2268 intended to be shown in the rendered output, and will not appear in 2269 the output as XML comments. XML comments can be generated by using 2270 the "[comment]#...#" inline formatting macro, or the "[.comment]" 2271 role attribute on blocks. A sample is shown in Figure 39 with its 2272 rendered output in Figure 40. 2274 2276 The exchange of projectile animals was the beginning of a 2277 long-running fruitful relationship between the British and the 2278 French peoples, 2279 [comment]#TODO: Will need to verify that claim.# which 2280 arguably predates the traditional English enmity with the 2281 French. [comment]#Strictly speaking, the Knights are Welsh.# 2283 [.comment] 2284 -- 2285 This document, as it turns out, has a profusion of XML comments. 2287 As expected, they are ignored in any rendering of the document. 2288 -- 2290 2292 Figure 41: AsciiRFC delimited text intended as an XML Comment 2294 2296 The exchange of projectile animals was the beginning of a 2297 long-running fruitful relationship between the British and the 2298 French peoples, 2300 2301 which 2302 arguably predates the traditional English enmity with the 2303 French. 2304 2305 2307 2312 2314 Figure 42: AsciiRFC delimited text Rendered As An XML Comment (RFC 2315 XML v3) 2317 11. Tables 2319 AsciiRFC tables, like RFC XML v3, support distinct table heads, 2320 bodies and feet; cells spanning multiple rows and columns; and 2321 horizontal alignment. The larger range of table formatting options 2322 available in RFC XML v2 is also supported. 2324 A sample of an AsciiRFC table is shown in Figure 43, with its 2325 rendered output in Figure 44. 2327 Neither version of RFC XML is as expressive in its table structure as 2328 Asciidoctor syntax. RFC XML, for example, does not permit blocks 2329 within table cells. 2331 2333 [grid=all,options="footer"] 2334 |=== 2335 |French Castle | Cave of Caerbannog 2337 2+|King Arthur 2338 2+|Patsy 2339 2+|Sir Bedevere the Wise 2340 2+|Sir Galahad the Pure 2341 2+|Sir Lancelot the Brave 2342 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot 2343 |French Guard with Outrageous Accent| Tim the Enchanter 2344 |Other French Guards | Brother Maynard 2345 | | The Lector 2346 .3+^|not yet recruited 2347 >|Sir Bors 2348 >|Sir Gawain 2349 >|Sir Ector 2351 |Retinue of sundry knights 2352 |Retinue of sundry more knights than at the French Castle 2353 |=== 2355 2357 Figure 43: An AsciiRFC Table 2359 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416
French CastleCave of Caerbannog
King Arthur
Patsy
Sir Bedevere the Wise
Sir Galahad the Pure
Sir Lancelot the Brave
Sir Robin the Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous AccentTim the Enchanter
Other French GuardsBrother Maynard
2397 The Lector
not yet recruitedSir Bors
Sir Gawain
Sir Ector
Retinue of sundry knightsRetinue of sundry more knights than at the French Castle
2418 2420 Figure 44: An AsciiRFC Table (RFC XML v3) 2422 12. Inline Formatting 2424 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts 2426 AsciiRFC supports italics, boldface, monospace, subscripts and 2427 superscripts, just like RFC XML v3. 2429 The inline formatting syntax given in Figure 45 produces the RFC XML 2430 v3 output given in Figure 46. 2432 2434 The participants of that renowned exercise in cross-cultural 2435 communication, to wit the exchange between the 2436 _Knights of the Round Table_ 2437 and the taunting French soldiers serving under *Guy de Lombard* are, 2438 properly speaking, outside the scope of this `menagerie`, being more 2439 or less human. Notwithstanding, several^ish^ beasts both animate~d~ 2440 and wooden played a significant part in this encounter; most 2441 notably: 2443 * The Projectile Cow, see <> 2444 * The Trojan Rabbit, see <> 2446 2448 Figure 45: Inline Formatting In AsciiRFC 2450 2452 The participants of that renowned exercise in cross-cultural 2453 communication, to wit the exchange between the 2454 Knights of the Round Table 2455 and the taunting French soldiers serving under Guy de Lombard are, 2456 properly speaking, outside the scope of this menagerie, being more 2457 or less human. Notwithstanding, severalish beasts both animated 2458 and wooden played a significant part in this encounter; most 2459 notably: 2460
    2461
  • The Projectile Cow, see
    • 2462
  • The Trojan Rabbit, see
    • 2463
2465 2467 Figure 46: Inline Formatting In AsciiRFC (RFC XML v3) 2469 12.2. Formatting BCP 14 Keywords 2471 RFC XML v3 also supports tagging of BCP14 keywords [RFC2119] 2472 [RFC8174]; this is done in AsciiRFC either by tagging them with a 2473 custom formatting span (e.g. "MUST NOT"), or by converting any 2474 boldface all-caps words recognised as BCP14 words (unless the ":no- 2475 rfc-bold-bcp14: false" document attribute is set). 2477 Any spans of BCP14 text delimited by inline formatting delimiters 2478 need to be contained within a single line of text; in Asciidoctor 2479 syntax, formatting spans are broken up across line breaks. 2481 This usage is demonstrated in Figure 47 with the rendered output in 2482 Figure 48. 2484 2486 The instructions in the _Book of Armaments_ on the proper deployment 2487 of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as 2488 follows, although this summary *SHALL NOT* be used as a substitute 2489 for a reading from the Book of Armaments: 2491 2493 Figure 47: BCP14 Keywords In AsciiRFC 2495 2497 The instructions in the Book of Armaments on the proper deployment 2498 of the Holy Hand Grenade of Antioch MAY be summarized as 2499 follows, although this summary SHALL NOT be used as a substitute 2500 for a reading from the Book of Armaments: 2502 2504 Figure 48: BCP14 Keywords In AsciiRFC (RFC XML v3) 2506 12.3. Escaping AsciiRFC Syntax 2508 Formatting delimiters like "*" can be escaped with backslash ("\*"); 2509 double formatting delimiters, like "**" and "__", need to be escaped 2510 with double backslash ("\\**"). 2512 Escaping delimiters is not always reliable, and for double delimiters 2513 it is preferable to use HTML entities ("**"), or attribute 2514 references (references to the value of attributes set in the document 2515 header) as shown in Figure 49. 2517 2518 :dblast: ** 2520 `{dblast}` 2521 2523 Figure 49: Escaping AsciiRFC Syntax Using Attributes 2525 In extreme circumstances (such as quoting AsciiDoc syntax), you may 2526 need to resort to altering the substitutions behaviour within a given 2527 block of of AsciiDoc; see the "Applying Substitutions" section of 2528 [Asciidoctor-Manual]. 2530 13. Links 2532 Common URL formats are recognised automatically as hyperlinks in 2533 AsciiRFC, which inherits this excellent feature from AsciiDoc, and 2534 are rendered as such. 2536 Any hyperlinked text is appended after the hyperlink in square 2537 brackets. 2539 An example is given in Figure 50 with its rendered version in 2540 Figure 51. 2542 2544 <> of the fearsome beast 2545 has been sourced from 2546 http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], 2547 <> 2548 by C code that was used in this accurate depiction of the 2549 Killer Rabbit: 2551 2553 Figure 50: An AsciiRFC Link 2555 2557 The following depiction of the fearsome beast 2558 has been sourced from 2559 Rabbit-SCII, 2560 accompanied 2561 by C code that was used in this accurate depiction of the 2562 Killer Rabbit: 2564 2566 Figure 51: An AsciiRFC Link (RFC XML v3) 2568 To prevent hyperlinking of a URL, prefix it with a backslash, as 2569 shown in Figure 52 with its rendered version in Figure 53. 2571 2573 The screaming move into the twenty-*first* century is accompanied by 2574 a move back to the late twentieth century, with ASCII stylings more 2575 wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be 2576 accessible in 1996.) 2578 2580 Figure 52: A Literal AsciiRFC Link 2582 2584 The screaming move into the twenty-first century is accompanied by 2585 a move back to the late twentieth century, with ASCII stylings more 2586 wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be 2587 accessible in 1996.) 2589 2591 Figure 53: A Literal AsciiRFC Link (RFC XML v3) 2593 14. Cross-References 2595 14.1. Basic Referencing 2597 Anchors for cross-references are notated as "[[...]]" or "[#...]", 2598 and can be inserted on their own line in front of most blocks. 2600 Asciidoctor syntax supports anchors in a much wider range of contexts 2601 than is supported than RFC XML v3 (let alone v2); anchors that are 2602 not supported for that version of RFC XML are simply ignored by the 2603 converter. 2605 Note that anchors in RFC XML are constrained to the format "[A-Za- 2606 z_:][[A-Za-z0-9_:.-]*" (i.e. "xsd:ID"). 2608 Cross-references to anchors are notated as "<<...>>"; cross- 2609 references with custom text as "<>". 2611 An example of using cross-references in AsciiRFC is given in 2612 Figure 54 with its rendered output in Figure 55. 2614 2616 The _Cave of Caerbannog_ has been well-established in the mythology 2617 of Camelot (as recounted by Monty Python) as the lair of the 2618 Legendary Black Beast of Arrrghhh, more commonly known today as the 2619 *Killer Rabbit of Caerbannog* <>. 2620 It is the encounter between the Killer Rabbit of Caerbannog and the 2621 Knights of the Round Table, armed with the Holy Hand Grenade of 2622 Antioch (see the <>), that we 2623 recount here through monospace font and multiple spaces. 2625 [[killer_rabbit_caerbannog]] 2626 === The Killer Rabbit of Caerbannog 2628 2630 Figure 54: Setting And Referring To Cross-References In AsciiRFC 2632 2634 The Cave of Caerbannog has been well-established in the mythology 2635 of Camelot (as recounted by Monty Python) as the lair of the 2636 Legendary Black Beast of Arrrghhh, more commonly known today as the 2637 Killer Rabbit of Caerbannog . 2638 It is the encounter between the Killer Rabbit of Caerbannog and the 2639 Knights of the Round Table, armed with the Holy Hand Grenade of 2640 Antioch (see the following section), that we 2641 recount here through monospace font and multiple spaces. 2642
The Killer Rabbit of Caerbannog 2643 2645 Figure 55: Setting And Referring To Cross-References In AsciiRFC (RFC 2646 XML v3) 2648 14.2. Referencing With Attributes 2650 While Asciidoctor syntax natively does not support attributes on 2651 cross-references, AsciiRFC works around that by embedding formatting 2652 information as templated text within cross-references: 2654 o "format=x: text" populates the "xref@format" attribute 2656 o a section number followed by one of the words "of", "parens", 2657 "bare", "text" is treated as a "relref" reference to an external 2658 document. 2660 An example of referencing with attributes is given in Figure 56 with 2661 its output in Figure 57. 2663 2665 The *Killer Rabbit of Caerbannog*, that most formidable foe of 2666 the Knights and of all that is holy or carrot-like, has been 2667 depicted diversely in lay and in song. We venture to say, 2668 _contra_ the claim made in <>, 2669 that the Killer Rabbit of Caerbannog truly is the most afeared 2670 of all the creatures. Short of sanctified ordnance such as 2671 <>, there are few remedies 2672 known against its awful lapine powers. 2674 2676 Figure 56: Cross-References With Attributes In AsciiRFC 2678 2680 The Killer Rabbit of Caerbannog, that most formidable foe of 2681 the Knights and of all that is holy or carrot-like, has been 2682 depicted diversely in lay and in song. We venture to say, 2683 contra the claim made in Ze Vompyre, 2684 that the Killer Rabbit of Caerbannog truly is the most afeared 2685 of all the creatures. Short of sanctified ordnance such as 2686 , there are few remedies 2687 known against its awful lapine powers. 2689 2691 Figure 57: Cross-References With Attributes In AsciiRFC (RFC XML v3) 2693 14.3. Indexing 2695 Inline index entries are notated as "((...))". Index entries which 2696 do not appear in the text are notated as "(((...)))"; such entries 2697 may include a separate sub-entry, separated from the main entry by 2698 comma. 2700 2702 The solution to the impasse at the ((Cave of Caerbannog)) was 2703 provided by the successful deployment of the 2704 *Holy Hand Grenade of Antioch* (see <>) 2705 (((Holy Hand Grenade of Antioch))). 2706 Any similarity between the Holy Hand Grenade of Antioch and the 2707 mythical _Holy Spear of Antioch_ is purely intentional; 2708 (((relics, Christian))) any similarity between the Holy Hand Grenade 2709 of Antioch and the _Sovereign's Orb of the United Kingdom_ 2710 (see <>) is putatively fortuitous. 2711 (((relics, monarchic))) 2713 2715 Figure 58: AsciiRFC Index Entries 2717 2719 The solution to the impasse at the Cave of Caerbannog was 2720 provided by the successful deployment of the 2721 Holy Hand Grenade of Antioch (see ) 2722 . 2723 Any similarity between the Holy Hand Grenade of Antioch and the 2724 mythical Holy Spear of Antioch is purely intentional; 2725 any similarity between the Holy Hand Grenade 2726 of Antioch and the Sovereign's Orb of the United Kingdom 2727 (see ) is putatively fortuitous. 2728 2730 2732 Figure 59: AsciiRFC Index Entries (RFC XML v3) 2734 15. Inclusions 2736 AsciiRFC inherits the Asciidoctor syntax "include" directive 2737 [Asciidoctor-Manual] to include external files in a master AsciiRFC 2738 document. 2740 This directive is capable of sophisticated document merging, 2741 including adjusting the heading levels of the included text, 2742 selecting text within specified tags or line numbers to be included, 2743 and adjusting the indentation of code snippets in merged text. 2745 Its basic syntax is given in Figure 60. 2747 2748 include::path[ 2749 leveloffset=_offset_, 2750 lines=_ranges_, 2751 tag(s)=_name(s)_, 2752 indent=_depth_ 2753 ] 2754 2756 Figure 60: Inclusions In AsciiRFC 2758 If a file is included in an AsciiRFC document, ensure it ends with a 2759 blank line. An inclusion that results in its final block not being 2760 delimited with a blank line from what follows can lead to 2761 unpredictable results. 2763 16. Encoding and Entities 2765 XML accepts the full range of characters in the world's languages 2766 through UTF-8 character encoding, and one of the motivations for the 2767 move by the IETF from plain text to RFC XML has been to allow non- 2768 ASCII characters to be included in RFCs. 2770 However, current RFC XML v2 tools still do not support UTF-8, and 2771 alternative tooling support for UTF-8 also remains patchy. Out of an 2772 abundance of caution, the RFC XML converter uses US-ASCII for its 2773 character encoding, and renders any non-ASCII characters as HTML 2774 entities. 2776 AsciiRFC accepts HTML entities as input, even though they are not 2777 part of the W3C XML specification. HTML entities such as " " 2778 feature in examples of RFC XML provided by the IETF. In order to 2779 prevent dependence of the XML output from extraneous entity 2780 definitions, any such entities are rendered in the XML as decimal 2781 character entities. 2783 An example of how AsciiRFC renders non-ASCII UTF-8 characters are 2784 given in Figure 61 with the output in Figure 62. 2786 2788 ____ 2789 .כאן אולי ימצאו המילים האחרונות של יוסף מארמתיה 2790 .מי אשר יהיה אמיץ ובעל נפש טהורה יוכל למצוא את הגביע הקדוש בטירת אאאאאאאה 2792 "Here may be found the last words of Joseph of Arimathea. 2793 He who is valiant and pure of spirit may find the Holy Grail 2794 in the castle of — Aaaargh." 2795 ____ 2797 2799 Figure 61: UTF-8 Characters In AsciiRFC 2801 2803
.כאן אולי ימצאו המילים האחרונות של יוסף מארמתיה 2804 .מי אשר יהיה אמיץ ובעל נפש טהורה יוכל למצוא את הגביע הקדוש בטירת אאאאאאאה 2805 "Here may be found the last words of Joseph of Arimathea. 2806 He who is valiant and pure of spirit may find the Holy Grail 2807 in the castle of — Aaaargh."
2809 2811 Figure 62: UTF-8 Characters In AsciiRFC Rendered As RFC XML v3 2813 Note that because initial period is a formatting character in 2814 Asciidoctor, we have had to use "." to escape the period at the 2815 end of Hebrew sentences (which appears at the start of the line, 2816 Hebrew being written Right-to-Left). Asciidoctor is not natively 2817 equipped to deal with Right-to-Left languages in its formatting 2818 parsing. 2820 17. Bibliography 2822 The simple encoding of bibliography syntax provided by AsciiDoc (and 2823 Asciidoctor syntax) is inadequate for the complexity of bibliographic 2824 markup required by RFC XML. 2826 RFC documents overwhelmingly cite other RFC documents, and canonical 2827 RFC XML bibliographic entries are available at [IETF-BibXML]; so it 2828 would be inefficient to encode those entries natively in AsciiRFC, 2829 only to have them converted back to RFC XML. 2831 The converter provides two means of incorporating bibliographies into 2832 RFC documents authored in AsciiRFC: 2834 o using raw RFC XML; and 2836 o assembling bibliographies in preprocessing. 2838 In either case, the RFC XML needs to be well-formed; missing closing 2839 tags can lead to erratic behaviour in the converter. 2841 17.1. Using Raw RFC XML 2843 In the first method, bibliographic citations are handled like all 2844 other AsciiRFC cross-references. The bibliographic entries for 2845 normative and informative references are given in the AsciiRFC as 2846 passthrough blocks, which contain the raw RFC XML for all references; 2847 document conversion leaves the raw RFC XML in place. 2849 This approach requires authors to maintain the normative and 2850 informative bibliographies within the document, to update them as 2851 citations are added and removed, and to sort them manually. However, 2852 if the citation is stored on the IETF's RFC XML citation libraries 2853 (see ), AsciiRFC will automatically 2854 replace it with an external reference to that citation. So the body 2855 of the citation XML can be left out. 2857 For example, the AsciiRFC in Figure 63 will generate the 2858 corresponding RFC XML v3 output in Figure 64. 2860 2862 [bibliography] 2863 == Normative References 2864 ++++ 2865 2867 2868 Key words for use in RFCs to Indicate 2869 Requirement Levels 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 ++++ 2881 [bibliography] 2882 == Informative References 2883 ++++ 2885 2886 2887 Monty Python and the Holy Grail 2888 2889 2890 2891 2892 2893 2894 2895 2896 2898 2900 2901 DON'T SPEW A Set of Guidelines for Mass Unsolicited 2902 Mailings and Postings (spam*) 2903 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2917 2919 2920 RFC Format Framework 2921 2922 2923 2924 2925 2926 2927 2928 2929 2931 2932 2933 The Arte of ASCII: Or, An True and Accurate Representation of 2934 an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of 2935 Character 2936 2937 2938 2939 2940 2941 2942 2943 2944 2946 2948 2949 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 2950 Words 2951 2952 2953 2954 2955 RFC 2119 specifies common key words that may be 2956 used 2957 in protocol specifications. This document aims to reduce 2958 the ambiguity by clarifying that only UPPERCASE usage of the 2959 key words have the defined special meanings. 2960 2961 2962 2963 2964 2966 ++++ 2968 2970 Figure 63: AsciiRFC Inline Bibliography 2972 2973
2974 2975 2976 Normative References 2977 2978 2979 2980 Informative References 2981 2982 2983 Monty Python and the Holy Grail 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3002 Figure 64: AsciiRFC Inline Bibliography Rendered As RFC XML v3 3004 17.2. Preprocessing Using "asciidoctor-bibliography" 3006 The alternative method is to use a preprocessing tool, 3007 [asciidoctor-bibliography], to import citations into the AsciiRFC 3008 document from an external file of references. 3010 The references file consists of RFC XML reference entries, and still 3011 needs to be managed manually; however the bibliographies are 3012 assembled from that file, sorted, and inserted into the normative and 3013 informative references in preprocessing. Citations in the document 3014 itself are given as macros to be interpreted by the preprocessor; 3015 this allows them to be split into normative and informative 3016 references. (The MMark tool likewise splits reference citations into 3017 normative and informative.) 3019 Integration with the "asciidoc-bibliography" gem proceeds as follows: 3021 1. Create an RFC XML references file, consisting of a "" 3022 element with individual "" elements inserted, as would 3023 be done for the informative and normative references normally. 3024 The references file will contain all possible references to be 3025 used in the file; the bibliography gem will select which 3026 references have actually been cited in the document. 3028 A. Rather than hand crafting RFC XML references for RFC 3029 documents, you should download them from an authoritative 3030 source; e.g., "http://xml.resource.org/public/rfc/bibxml/ 3031 reference.RFC.2119.xml". Note that RFC XML references from 3032 this link contains the XML document declaration, which needs 3033 to be removed before being used in the XML bibliography. 3035 B. Unlike the case for RFC XML documents created manually, the 3036 references file does not recognise XML entities and will not 3037 attempt to download them during processing. Any references 3038 to "http://xml.resource.org/public/rfc/bibxml/" will need to 3039 be downloaded and inserted into the references file. 3041 C. The RFC XML in the references file will need to be 3042 appropriate to the version of RFC XML used in the main 3043 document, as usual. Note that RFC XML v2 references are 3044 forward compatible with v3; v3 contains a couple of 3045 additional elements. 3047 2. Add to the main document header attributes referencing the 3048 references file (":bibliography-database:"), and the bibliography 3049 style (":bibliography-style: rfc-v3"). 3051 3. References to a normative reference are inserted with the macro 3052 "cite:norm[id]" instead of "<>", where "id" is the anchor of 3053 the reference. 3055 4. References to an informative reference are inserted with the 3056 macro "cite:info[id]" instead of "<>", where "id" is the 3057 anchor of the reference. 3059 5. Formatted crossreferences and "relref" crossreferences are 3060 entered by inserting the expected raw XML in the "text" 3061 attribute. Do not use the "{cite}" interpolation of the 3062 citation. For example: 3064 * "<>" = "cite:norm[id, text="words"]" 3067 * "<>" (processed as a formatted 3068 cross-reference) = "cite:norm[id, text="words"]" 3071 * "<>" (processed as relref) = 3072 "cite:norm[id, text=""]" 3075 * "<>" (processed as relref with 3076 a cross-document internal reference) = "cite:norm[id, 3077 text=""]" 3080 6. Normative and Informative References are inserted in the document 3081 through a macro, which occurs where the RFC XML references would 3082 be inserted, as shown in Figure 65. 3084 3085 [bibliography] 3086 == Normative References 3088 ++++ 3089 bibliography::norm[] 3090 ++++ 3092 [bibliography] 3093 == Informative References 3095 ++++ 3096 bibliography::info[] 3097 ++++ 3098 3100 Figure 65: Using asciidoctor-bibliography For Bibliography 3101 Preprocessing 3103 18. RFC XML features not supported in Asciidoctor 3105 The following features of RFC XML v3 [RFC7991] and v2 [RFC7749] are 3106 not supported by the AsciiRFC converter, and would need to be 3107 adjusted manually after RFC XML is generated: 3109 +------------------------+--------------------+---------------------+ 3110 | RFC XML element | RFC XML v3 | RFC XML v2 | 3111 +------------------------+--------------------+---------------------+ 3112 | "front/boilerplate" | Not added by the | Not added by the | 3113 | | converter | converter | 3114 | "iref@primary" | N | N | 3115 | "reference" (and all | As Raw XML | As Raw XML | 3116 | children) | | | 3117 | "table/preamble" | Deprecated | N | 3118 | "table/postamble" | Deprecated | N | 3119 | "artwork@width" | Only on images | Only on images | 3120 | "artwork@height" | Only on images | Only on images | 3121 +------------------------+--------------------+---------------------+ 3123 19. Authoring 3125 To author an AsciiRFC document, you should first familiarise yourself 3126 with the [Asciidoctor-Manual]. 3128 The [asciidoctor-rfc] Ruby gem source code distribution also has 3129 samples of individual RFC XML features in v2 and v3, and examples of 3130 self-standing AsciiRFC documents, along with their RFC XML 3131 renderings. (This includes round-tripped RFC XML documents.) 3133 19.1. Using the "rfc-asciirfc-minimal" template 3135 In addition, you can clone the sample "rfc-asciirfc-minimal" 3136 repository as a template, and populate it for your AsciiRFC document 3137 using the steps shown in Figure 66. 3139 $ git clone https://github.com/riboseinc/rfc-asciirfc-minimal 3141 Figure 66: Cloning The AsciiRFC Document Template 3143 19.2. Installing AsciiRFC Backend Processors 3145 Converting your AsciiRFC to RFC XML is a simple as installing the 3146 Asciidoctor Ruby gem "asciidoctor" (see "Installation" at 3147 [Asciidoctor]) and the "asciidoctor-rfc" gem in Ruby (through 3148 RubyGems), then running the "asciidoctor" executable on the document, 3149 specifying the "asciidoctor-rfc" gem as a library. 3151 The necessary steps are shown in Figure 67. 3153 $ gem install asciidoctor-rfc 3154 $ asciidoctor -b rfc3 -r 'asciidoctor-rfc' foo.adoc # RFC XML v3 output 3155 $ asciidoctor -b rfc2 -r 'asciidoctor-rfc' foo.adoc # RFC XML v2 output 3157 Figure 67: Installing The AsciiRFC Backend Processors 3159 19.3. Iterating AsciiRFC Content 3161 As you author AsciiRFC content, you should iterate by running the 3162 AsciiRFC conversion frequently, to ensure that you are still 3163 generating valid XML through your markup. The converter makes an 3164 effort to ensure that its XML output is valid, and it issues warnings 3165 about likely issues; it also validates its own XML output against the 3166 RFC XML schema (of the corresponding version), and reports errors in 3167 the XML output in the format shown in Figure 68. 3169 V3 RELAXNG Validation: 12:0: ERROR: Invalid attribute 3170 sortRefs for element rfc 3172 Figure 68: Sample Validation Error Message From AsciiRFC 3174 Note that validation against the Relax NG RFC XML schema includes 3175 confirming the referential integrity of all cross-references in the 3176 document. 3178 It may be necessary to intervene in the XML output generated by the 3179 converter, either because the block model of AsciiRFC does not 3180 conform with the intended RFC XML (e.g. lists embedded in 3181 paragraphs), or because RFC XML features are required that are not 3182 supported within AsciiRFC. 3184 20. Security Considerations 3186 o Ensure your AsciiRFC generator comes from a geniune and 3187 trustworthy source. This protects your own machine and also 3188 prevents injection of malicious content in your resulting 3189 document. 3191 o An AsciiRFC generator may cause errors in textual rendering or 3192 link generation that may lead to security issues. 3194 o Creating cross-references (and also bibliographic references) to 3195 external documents may pose risks since the specified external 3196 location may become controlled by a malicious party. 3198 o URIs that start with the "http:" or "https:" prefix are 3199 automatically converted into links in AsciiRFC except when escaped 3200 with a backslash before the prefix. A URI that is intended to be 3201 text but unintentionally rendered as a link may cause users to 3202 visit a malicious website with security consequences. 3204 o AsciiRFC contains syntax that can directly incorporate remote URI 3205 content, such as "include::" which allows remotely-located 3206 AsciiRFC content files. If a remote URI contains malicious 3207 content, this content will be included in the resulting AsciiRFC 3208 document compiled as RFC XML. Remotely-linked URIs should always 3209 be checked for malicious content prior to compiling AsciiRFC into 3210 RFC XML. 3212 21. IANA Considerations 3214 This document does not require any action by IANA. 3216 22. References 3218 22.1. Normative References 3220 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 3221 RFC 7991, DOI 10.17487/RFC7991, December 2016, 3222 . 3224 22.2. Informative References 3226 [AsciiDoc] 3227 Rackham, S., "AsciiDoc: Text based document generation", 3228 November 2013, . 3230 [Asciidoctor] 3231 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast 3232 text processor & publishing toolchain for converting 3233 AsciiDoc to HTML5, DocBook & more.", November 2017, 3234 . 3236 [asciidoctor-bibliography] 3237 Ribose Inc., "Citations and Bibliography the 'asciidoctor- 3238 way'", November 2017, 3239 . 3241 [Asciidoctor-Manual] 3242 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast 3243 text processor & publishing toolchain for converting 3244 AsciiDoc to HTML5, DocBook & more.", November 2017, 3245 . 3247 [asciidoctor-rfc] 3248 Ribose Inc., "asciidoctor-rfc lets you write Internet- 3249 Drafts and RFCs in AsciiDoc, the "asciidoctor-way".", 3250 November 2017, 3251 . 3253 [AsciiMathML] 3254 "AsciiMath is an easy-to-write markup language for 3255 mathematics.", November 2017, . 3257 [datatracker-asciirfc-minimal] 3258 Carberry, J. and T. Grayson, "IETF Datatracker: A Minimal 3259 Internet-Draft In AsciiRFC", March 2018, 3260 . 3263 [datatracker-camelot-holy-grenade] 3264 Pendragon, A., "IETF Datatracker: The Holy Hand Grenade of 3265 Antioch", March 2018, . 3268 [datatracker-divination-cfapi] 3269 Destiny, G. and C. Luck, "IETF Datatracker: An API For 3270 Calendar-Based Fortune Heuristics Services", March 2018, 3271 . 3274 [draftr] Barnes, R., "draftr: an HTML front-end to pandoc2rfc", Nov 3275 2017, . 3277 [git-asciirfc-minimal] 3278 Carberry, J. and T. Grayson, "Git repository: A Minimal 3279 Internet-Draft In AsciiRFC", March 2018, 3280 . 3282 [git-camelot-holy-grenade] 3283 Pendragon, A., "Git repository: The Holy Hand Grenade of 3284 Antioch", March 2018, 3285 . 3287 [git-divination-cfapi] 3288 Destiny, G. and C. Luck, "Git repository: An API For 3289 Calendar-Based Fortune Heuristics Services", March 2018, 3290 . 3292 [I-D.asciirfc-minimal] 3293 Carberry, J. and T. Grayson, "A Minimal Internet-Draft In 3294 AsciiRFC", draft-asciirfc-minimal-00 (work in progress), 3295 March 2018. 3297 [I-D.camelot-holy-grenade] 3298 Pendragon, A., "The Holy Hand Grenade of Antioch", draft- 3299 camelot-holy-grenade-00 (work in progress), March 2018. 3301 [I-D.divination-cfapi] 3302 Destiny, G. and C. Luck, "An API For Calendar-Based 3303 Fortune Heuristics Services", draft-divination-cfapi-00 3304 (work in progress), March 2018. 3306 [IETF-BibXML] 3307 "IETF BibXML Library", November 2017, 3308 . 3310 [kramdown-rfc2629] 3311 Bormann, C., "kramdown-rfc2629: An RFC2629 (XML2RFC) 3312 backend for Thomas Leitner's kramdown markdown parser", 3313 Nov 2017, . 3315 [lyx2rfc] Williams, N., "LyX to I-D/RFC export by way of Lyx export 3316 to XHTML and XSLT conversion to xml2rfc schema", 2014, 3317 . 3319 [MathJax] "MathJax: A JavaScript display engine for mathematics that 3320 works in all browsers.", November 2017, 3321 . 3323 [mmark] Gieben, R., "Using mmark to create I-Ds and RFCs", June 3324 2015, . 3326 [NroffEdit] 3327 Santesson, S., "WYSIWYG Internet-Draft Nroff Editor", May 3328 2011, . 3330 [pandoc2rfc] 3331 Gieben, R., "pandoc2rfc: Use pandoc to create XML suitable 3332 for xml2rfc", 2012, . 3334 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3335 Requirement Levels", BCP 14, RFC 2119, 3336 DOI 10.17487/RFC2119, March 1997, 3337 . 3339 [RFC5385] Touch, J., "Version 2.0 Microsoft Word Template for 3340 Creating Internet Drafts and RFCs", RFC 5385, 3341 DOI 10.17487/RFC5385, February 2010, 3342 . 3344 [RFC7328] Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit 3345 of XML", RFC 7328, DOI 10.17487/RFC7328, August 2014, 3346 . 3348 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 3349 RFC 7749, DOI 10.17487/RFC7749, February 2016, 3350 . 3352 [RFC7763] Leonard, S., "The text/markdown Media Type", RFC 7763, 3353 DOI 10.17487/RFC7763, March 2016, 3354 . 3356 [RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies, 3357 Stability Strategies, and Select Registrations", RFC 7764, 3358 DOI 10.17487/RFC7764, March 2016, 3359 . 3361 [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990, 3362 DOI 10.17487/RFC7990, December 2016, 3363 . 3365 [RFC7996] Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", 3366 RFC 7996, DOI 10.17487/RFC7996, December 2016, 3367 . 3369 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3370 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3371 May 2017, . 3373 [TeX-LaTeX] 3374 "LaTeX is document preparation software that runs on top 3375 of Donald E. Knuth's TeX typesetting system.", November 3376 2017, . 3378 Appendix A. Examples 3380 A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" 3382 This example is available in the following formats: 3384 o AsciiRFC [git-asciirfc-minimal] 3386 o Internet-Draft [I-D.asciirfc-minimal] 3387 o Text, RFC XML, PDF and HTML on the IETF Datatracker 3388 [datatracker-asciirfc-minimal] 3390 A.1.1. In AsciiRFC 3392 3393 = A Minimal Internet-Draft In AsciiRFC 3394 :doctype: internet-draft 3395 :name: draft-asciirfc-minimal-00 3396 :abbrev: AsciiRFC Example 3397 :status: informational 3398 :ipr: trust200902 3399 :submissionType: individual 3400 :area: Internet 3401 :intended-series: full-standard 3402 :revdate: 2018-03-23T00:00:00Z 3403 :fullname: Josiah Stinkney Carberry 3404 :lastname: Carberry 3405 :forename_initials: J. S. 3406 :organization: Brown University 3407 :phone: +1 401 863 1000 3408 :street: Box K, 69 Brown Street 3409 :city: Providence 3410 :code: 02912 3411 :country: United States of America 3412 :uri: https://www.brown.edu 3413 :email: josiah.carberry@ribose.com 3414 :fullname_2: Truman Grayson 3415 :lastname_2: Grayson 3416 :forename_initials_2: T. 3417 :organization_2: Brown University 3418 :phone_2: +1 401 863 1000 3419 :street_2: Box G, 69 Brown Street 3420 :city_2: Providence 3421 :code_2: 02912 3422 :country_2: United States of America 3423 :uri_2: https://www.brown.edu 3424 :email_2: truman.grayson@ribose.com 3426 [abstract] 3428 This document provides a template on how to author (or migrate!) 3429 a new Internet-Draft / RFC in AsciiRFC format. This template 3430 requires usage of the `asciidoctor-rfc` Ruby gem. 3432 [#introduction] 3433 == Introduction 3434 AsciiRFC <> is an extremely simple way to 3435 author Internet-Drafts and RFCs without needing to manually craft 3436 RFC XML <>. 3438 This is a template for authors to easily start with 3439 <>. 3441 [#conventions] 3442 == Terms and Definitions 3444 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 3445 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 3446 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this 3447 document are to be interpreted as described in BCP 14 3448 <> <> when, and only when, they appear in 3449 all capitals, as shown here. 3451 //// 3452 Note: do not break formatted strings over carriage return. Bad 3453 things happen. (In this instance, the carriage return is 3454 suppressed, and no space takes its place.) This is an 3455 Asciidoctor issue, not an asciidoctor-rfc issue. 3456 //// 3458 [#symbols] 3459 == Symbols And Abbreviations 3461 [#operators] 3462 === Operators 3464 AsciiRFC:: 3465 As defined in <>. 3467 [#security] 3468 == Security Considerations 3470 * Please beware of implementation issues caused by <>. 3472 * Here's how you include references <>, 3473 <>, <>. 3475 [#iana] 3476 == IANA Considerations 3478 This document does not require any action by IANA. 3480 // References must be given before appendixes 3482 [bibliography] 3483 == Normative References 3485 //bibliography::norm[] 3486 ++++ 3488 3490 3491 Key words for use in RFCs to Indicate Requirement 3492 Levels 3493 3494 3495 3496 3497 3498 In many standards track documents several words are 3499 used to signify the requirements in the specification. 3500 These words are often capitalized. This document defines 3501 these words as they should be interpreted in IETF 3502 documents. This document specifies an Internet Best 3503 Current Practices for the Internet Community, and 3504 requests discussion and suggestions for improvements. 3505 3506 3507 3508 3509 3510 3511 3513 3515 3516 The "xml2rfc" Version 3 3517 Vocabulary 3518 3519 3520 3521 3522 3523 This document defines the "xml2rfc" 3524 version 3 vocabulary: an XML-based language used for 3525 writing RFCs and Internet-Drafts. It is heavily derived 3526 from the version 2 vocabulary that is also under 3527 discussion. This document obsoletes the v2 grammar 3528 described in RFC 7749. 3529 3530 3531 3532 3533 3535 3537 3538 Ambiguity of Uppercase vs Lowercase in RFC 2119 3539 Key Words 3540 3541 3542 3543 3544 3545 RFC 2119 specifies common key words that may be 3546 used in protocol specifications. This document aims to 3547 reduce the ambiguity by clarifying that only UPPERCASE 3548 usage of the key words have the defined special 3549 meanings. 3550 3551 3552 3553 3554 3555 3556 ++++ 3558 [bibliography] 3559 == Informative References 3561 //bibliography::info[] 3562 ++++ 3564 3565 3566 Botan: Crypto and TLS for C++11 3567 3568 Ribose Inc. 3569
3570 3571 Suite 1111, 1 Pedder Street 3572 Central 3573 Hong Kong 3574 Hong Kong 3575 3576 open.source@ribose.com 3577 https://www.ribose.com 3578
3579 3580 3581 3582 3584 3585 3586 AsciiRFC: Authoring Internet-Drafts And RFCs Using 3587 AsciiDoc 3589 3590 3591 3593 3595 3596 3598 3600 3601 3603 3605 This document describes the AsciiDoc syntax 3606 extension 3607 called AsciiRFC designed for authoring IETF Internet-Drafts 3608 and RFCs. AsciiDoc is a human readable document markup 3609 language which affords more granular control over markup than 3610 comparable schemes such as Markdown. The AsciiRFC syntax is 3611 designed to allow the author to entirely focus on text, 3612 providing the full power of the resulting RFC XML through the 3613 AsciiDoc language, while abstracting away the need to manually 3614 edit XML, including references. This document itself was 3615 written and generated into RFC XML v2 (RFC7749) and RFC XML v3 3616 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC 3617 generator. 3619 3621 3624 3628 3630 3631 3632 The SM4 Blockcipher Algorithm And Its Modes Of 3633 Operations 3635 3636 3637 3639 3640 3641 3643 3645 This document describes the SM4 symmetric 3646 blockcipher 3647 algorithm published as GB/T 32907-2016 by the State 3648 Cryptography Administration of China (SCA). This document is 3649 a product of the Crypto Forum Research Group 3650 (CFRG). 3652 3654 3656 3660 3662 3664 3665 The OCB Authenticated-Encryption 3666 Algorithm 3667 3668 3669 3670 3671 3672 3673 3674 This document specifies OCB, a shared-key 3675 blockcipher-based encryption scheme that provides 3676 confidentiality and authenticity for plaintexts and 3677 authenticity for associated data. This document is a product 3678 of the Crypto Forum Research Group 3679 (CFRG). 3680 3681 3682 3683 3684 ++++ 3686 [appendix] 3687 [#appendix-a] 3688 == Examples 3690 === Example 1 3692 Here's an example. 3694 [source,json] 3695 ---- 3696 { 3697 "code": { 3698 "encoding": "ascii", 3699 "type": "rfc", 3700 "authors": [ "Josiah Carberry", "Truman Grayson" ] 3701 } 3702 } 3703 ---- 3705 [#acknowledgements] 3706 == Acknowledgements 3708 The authors would like to thank their families. 3710 3712 A.1.2. Rendered as RFC XML v3 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 A Minimal Internet-Draft In AsciiRFC 3728 3729 3730 3731 Brown University 3732
3733 3734 Box K, 69 Brown Street 3735 Providence 3736 02912 3737 United States of America 3738 3739 +1 401 863 1000 3740 josiah.carberry@ribose.com 3741 https://www.brown.edu 3742
3743 3744 3745 Brown University 3746
3747 3748 Box G, 69 Brown Street 3749 Providence 3750 02912 3751 United States of America 3752 3753 +1 401 863 1000 3754 truman.grayson@ribose.com 3755 https://www.brown.edu 3756
3757 3758 3759 Internet 3761 3762 This document provides a template on how to author (or migrate!) 3763 a new Internet-Draft / RFC in AsciiRFC format. This template 3764 requires usage of the asciidoctor-rfc Ruby gem. 3765 3766 3767
IntroductionAsciiRFC is an extremely simple way to 3768 author Internet-Drafts and RFCs without needing to manually craft 3769 RFC XML . 3770 This is a template for authors to easily start with 3771 .
3772
3773 Terms and Definitions 3774 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", 3775 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", 3776 "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 3777 document are to be interpreted as described in BCP 14 3778 when, and only when, they appear in 3779 all capitals, as shown here. 3780
3781
3782 Symbols And Abbreviations 3783
3784 Operators 3785
3786
AsciiRFC
3787
As defined in .
3788
3789
3790
3791
3792 Security Considerations 3793
    3794
  • Please beware of implementation issues caused by .
    • 3795
  • Here’s how you include references , 3796 , .
    • 3797
3798
3799
3800 IANA Considerations 3801 This document does not require any action by IANA. 3802
3803 3804 3805 Normative References 3806 3807 3808 3809 3810 3811 Informative References 3812 3813 3814 Botan: Crypto and TLS for C++11 3815 3816 Ribose Inc. 3817
3818 3819 Suite 1111, 1 Pedder Street 3820 Central 3821 Hong Kong 3822 Hong Kong 3823 3824 open.source@ribose.com 3825 https://www.ribose.com 3826
3827 3828 3829 3830 3831 3832 3833 3834 3835
3836 Examples 3837
Example 1Here’s an example. 3838
3839 { 3840 "code": { 3841 "encoding": "ascii", 3842 "type": "rfc", 3843 "authors": [ "Josiah Carberry", "Truman Grayson" ] 3844 } 3845 } 3846
3847
3848
3849 Acknowledgements 3850 The authors would like to thank their families. 3851
3852 3853 3854 3856 A.2. Example 2: "The Holy Hand Grenade of Antioch" 3858 This example is available in the following formats: 3860 o AsciiRFC [git-camelot-holy-grenade] 3861 o Internet-Draft [I-D.camelot-holy-grenade] 3863 o Text, RFC XML, PDF and HTML on the IETF Datatracker 3864 [datatracker-camelot-holy-grenade] 3866 A.2.1. In AsciiRFC 3868 3869 = The Holy Hand Grenade of Antioch 3870 Arthur son of Uther Pendragon 3871 :doctype: internet-draft 3872 :abbrev: Hand Grenade of Antioch 3873 :updates: 8140 3874 :submission-type: independent 3875 :name: draft-camelot-holy-grenade-00 3876 :status: informational 3877 :consensus: false 3878 :area: General, Operations and Management 3879 :keyword: rabbits, grenades, antioch, camelot 3880 :ipr: trust200902 3881 :toc-include: true 3882 :sort-refs: true 3883 :revdate: 2018-04-01 3884 :fullname: Arthur son of Uther Pendragon 3885 :forename_initials: A. 3886 :lastname: Pendragon 3887 :email: arthur.pendragon@ribose.com 3888 :organization: Camelot 3889 :uri: http://camelot.gov.example 3890 :street: Palace\ Camel Lot 1 3891 :city: Camelot 3892 :country: England 3893 :comments: yes 3894 :notedraftinprogress: yes 3895 :smart-quotes: false 3897 [.comment] 3898 tag::preamble1[] 3899 // tag::preamble[] 3901 [abstract] 3902 The menagerie of beasts and artefacts depicted in RFC8140 3903 may be usefully supplemented by other renowned figures of 3904 Internet and more general lore. This document extends the 3905 menagerie to the seminal fable of the 3906 "Holy Hand Grenade of Antioch", as depicted in the 3907 Monty Python film "Monty Python and the Holy Grail", 3908 as well as "Spamalot", the musical inspired by the movie. 3910 [NOTE,remove-in-rfc=false] 3911 .Spamalot 3912 The relevance of the musical "Spamalot" to Internet lore should be 3913 obvious to the reader; but in case of doubt, see also 3914 Section 1 ("What is Spam*?") of RFC2635. 3916 // end::preamble[] 3917 [.comment] 3918 end::preamble1[] 3920 [.comment] 3921 tag::sectnums1[] 3922 // tag::sectnums[] 3924 [toc=exclude] 3925 :sectnums!: 3926 == Terminology 3928 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 3929 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 3930 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 3931 are to be interpreted as described in BCP 14 <> <> 3932 when, and only when, they appear in all capitals, as shown here. 3934 :sectnums: 3935 == Introduction 3937 <> refers to the intended move of RFC formatting to 3938 XML2RFC v3 <>, in the following terms: 3940 // end::sectnums[] 3941 [.comment] 3942 end::sectnums1[] 3944 [.comment] 3945 tag::quote1[] 3946 // tag::quote[] 3948 [quote,attribution="A. Farrel"] 3949 ____ 3950 Although the RFC Editor has recently dragged the IETF kicking and 3951 screaming into the twentieth century [RFC7990] [RFC7996], there is a 3952 yearning among all right-thinking Internet architects to "keep it 3953 simple" and to return to the olden days when pigs could be given 3954 thrust without anyone taking undue offence. 3955 ____ 3957 // end::quote[] 3958 [.comment] 3959 end::quote1[] 3961 While no pigs, flying or otherwise, are involved in the transition 3962 to RFC XML v3, it is opportune to enhance the <> 3963 legendarium in the service of RFC XML v3, by illustrating its 3964 functionality through references to the mythology of Camelot, and 3965 particularly the incidents at the Cave of Caerbannog. 3967 [.comment] 3968 tag::escaped_hyperlink1[] 3969 // tag::escaped_hyperlink[] 3971 The screaming move into the twenty-*first* century is accompanied by 3972 a move back to the late twentieth century, with ASCII stylings more 3973 wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be 3974 accessible in 1996.) 3976 // end::escaped_hyperlink[] 3977 [.comment] 3978 end::escaped_hyperlink1[] 3980 There are two references to rabbits in 3981 _Monty Python and the Holy Grail_ which are expounded on herewith: 3983 [.comment] 3984 tag::listcontinuation1[] 3985 // tag::listcontinuation[] 3987 Trojan Rabbit:: 3988 In their siege of the French-occupied castle which may already 3989 contain an instance of the Grail, Sir Bedevere the Wise proposes to 3990 use a Trojan Rabbit to infiltrate the castle, with a raiding party 3991 to take the French "not only by surprise, but totally unarmed." 3992 + 3993 The proposal, unsurprisingly, proved abortive. The more so as the 3994 raiding party forgot to hide within the Trojan Rabbit, before the 3995 French soldiers took the Trojan Rabbit inside the castle. 3997 Killer Rabbit of Caerbannog:: 3998 Guarding the entrance to the Cave of Caerbannog; see <>. 4000 // end::listcontinuation[] 4001 [.comment] 4002 end::listcontinuation1[] 4004 == The French-occupied castle 4005 [.comment] 4006 tag::inline_formatting1[] 4007 // tag::inline_formatting[] 4009 The participants of that renowned exercise in cross-cultural 4010 communication, to wit the exchange between the 4011 _Knights of the Round Table_ 4012 and the taunting French soldiers serving under *Guy de Lombard* are, 4013 properly speaking, outside the scope of this `menagerie`, being more 4014 or less human. Notwithstanding, several^ish^ beasts both animate~d~ 4015 and wooden played a significant part in this encounter; most 4016 notably: 4018 * The Projectile Cow, see <> 4019 * The Trojan Rabbit, see <> 4021 // end::inline_formatting[] 4022 [.comment] 4023 end::inline_formatting1[] 4025 [[projectile-cow]] 4026 .The Projectile Cow with an accompanying cannon 4027 ==== 4028 [alt=The Projectile Cow with an accompanying cannon in ASCII] 4029 .... 4030 .-.-.-.-.-.-.-.-.-.-.-.--.-.-.-.-.-.-.--.-.-.-.-.-.-.-.--.-. 4031 _-_---__--__--___-___-__-____---___-________---____-____-__- 4032 ._.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-...-.-.--..-.-.-.-.-.-..--.- 4033 ,..,.,.,.,.,..,.,,..,.,.,.,.,.,, ^^ .,,.,., ^^ .,.,.,.= 4034 _>-.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-. 4035 .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., 4036 .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # .,.,.,. 4037 .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. 4038 .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ' '! .,.,..,.,.- 4039 .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_] . ., . . , 4040 .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / -.-<>.,.,..-.-, 4041 .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. 4042 .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- 4043 .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. 4044 .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- 4045 .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- 4046 -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- 4047 ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, 4048 ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- 4049 ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. 4050 .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., 4051 .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,. 4053 ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,. 4054 ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. 4055 .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. 4056 -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> 4057 _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,., 4058 .._...{WITHHONEY}-.-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_> 4059 GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASSPC 4060 SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS 4061 CLAY_ROCKS_REBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY>< 4062 CLAY_CLAY_SKLETONS_MORESOIL_CLAY_CLAY_CLAY_CLAY_CLAY_VR 4063 .... 4064 ==== 4066 [[trojan-rabbit]] 4067 .The Trojan Rabbit with an automatic sliding door 4068 ==== 4069 [alt=The Trojan Rabbit with an automatic sliding door, in ASCII] 4070 .... 4071 ___ ____ 4072 //_ \//\__\ 4073 || || | 4074 -__||_||__| 4075 // \--_ 4076 // ____ --___ 4077 // // \ \-_ 4078 // \\ @/ o || 4079 // ---- _____|| 4080 // // 4081 //\_//__ // 4082 //-- --- \____ // 4083 // --- \______ // 4084 // , . ----- \_//_ 4085 // ,. --- \____ 4086 // .,v --- \___ 4087 // __ -- \_ 4088 || , _______________ //|| |-_ 4089 || | |''''''''''| // || | | 4090 || ' | | | || | | 4091 || | | | || | | 4092 || " | | 0 | ___||___ | | 4093 || | | | -------- | | 4094 ||___ | | | ______ | |- 4095 // \ | | | // \| _| \ 4096 // \ ____|---|__________|______// \/ | 4097 || X | / || X | / 4098 \\ /\\____/ \\ /___/ 4099 \\_____/ ----- \\_____/--- 4100 ----- ----- 4102 .... 4103 ==== 4105 [.comment] 4106 tag::aside1[] 4107 // tag::aside[] 4109 **** 4110 While the exchange at the French-occupied castle is one of 4111 the more memorable scenes of _Monty Python and the Holy Grail_, 4112 the Trojan Rabbit has not reached the same level of cultural 4113 resonance as its more murderous counterpart. Reasons for this 4114 may include: 4116 * Less overall screen-time dedicated to the Trojan Rabbit. 4118 * The Trojan Rabbit as projectile has already been anticipated 4119 by the Cow as projectile. 4120 **** 4122 // end::aside[] 4124 [.comment] 4125 end::aside1[] 4127 [.comment] 4128 tag::note1[] 4129 // tag::note[] 4131 [NOTE,display=true,source=Author] 4132 ==== 4133 Image courtesy of 4134 https://camelot.gov.example/creatures-in-ascii/ 4135 ==== 4137 // end::note[] 4138 [.comment] 4139 end::note1[] 4141 [.comment] 4142 tag::comment1[] 4143 // tag::comment[] 4145 The exchange of projectile animals was the beginning of a 4146 long-running fruitful relationship between the British and the 4147 French peoples, 4148 [comment]#TODO: Will need to verify that claim.# which 4149 arguably predates the traditional English enmity with the 4150 French. [comment]#Strictly speaking, the Knights are Welsh.# 4152 [.comment] 4153 -- 4154 This document, as it turns out, has a profusion of XML comments. 4156 As expected, they are ignored in any rendering of the document. 4157 -- 4159 // end::comment[] 4160 [.comment] 4161 end::comment1[] 4163 [[caerbannog]] 4164 == The Mythos of Caerbannog 4166 [.comment] 4167 tag::xref1[] 4168 // tag::xref[] 4170 The _Cave of Caerbannog_ has been well-established in the mythology 4171 of Camelot (as recounted by Monty Python) as the lair of the 4172 Legendary Black Beast of Arrrghhh, more commonly known today as the 4173 *Killer Rabbit of Caerbannog* <>. 4174 It is the encounter between the Killer Rabbit of Caerbannog and the 4175 Knights of the Round Table, armed with the Holy Hand Grenade of 4176 Antioch (see the <>), that we 4177 recount here through monospace font and multiple spaces. 4179 [[killer_rabbit_caerbannog]] 4180 === The Killer Rabbit of Caerbannog 4182 // end::xref[] 4183 [.comment] 4184 end::xref1[] 4186 [.comment] 4187 tag::relref1[] 4188 // tag::relref[] 4190 The *Killer Rabbit of Caerbannog*, that most formidable foe of 4191 the Knights and of all that is holy or carrot-like, has been 4192 depicted diversely in lay and in song. We venture to say, 4193 _contra_ the claim made in <>, 4194 that the Killer Rabbit of Caerbannog truly is the most afeared 4195 of all the creatures. Short of sanctified ordnance such as 4196 <>, there are few remedies 4197 known against its awful lapine powers. 4199 // end::relref[] 4200 [.comment] 4201 end::relref1[] 4203 [.comment] 4204 tag::hyperlink1[] 4205 // tag::hyperlink[] 4207 <> of the fearsome beast 4208 has been sourced from 4209 http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], 4210 <> 4211 by C code that was used in this accurate depiction of the 4212 Killer Rabbit: 4214 // end::hyperlink[] 4215 [.comment] 4216 end::hyperlink1[] 4218 [.comment] 4219 tag::figure1[] 4220 // tag::figure1a[] 4222 [[killer-bunny]] 4223 .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 4224 ==== 4225 [alt=The Killer Bunny, in ASCII] 4226 .... 4227 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4228 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4229 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 4230 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 4231 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 4232 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 4233 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 4234 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 4235 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 4236 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 4237 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 4238 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 4239 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 4240 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 4241 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 4242 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 4243 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 4244 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 4245 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 4246 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 4247 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 4248 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 4249 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 4250 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 4251 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 4252 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 4253 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 4254 MW \\/\||v v|| -\\-------___ . ., \ | 4255 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 4256 ) /--------^-^ ,. \|// 4257 # \(/ .\\|x// " ' ' 4258 . , \\||// \||\\\// \\ 4259 .... 4260 ==== 4262 [[killer-source]] 4263 .C Code To Lure Killer Rabbit Back To Cave 4264 ==== 4265 [source,c] 4266 ---- 4267 4268 /* Locate the Killer Rabbit */ 4269 int type; 4270 unsigned char *killerRabbit = 4271 LocateCreature(&caerbannog, "killer rabbit"); 4272 if( killerRabbit == 0 ){ 4273 puts("The Killer Rabbit of Caerbannog is out of town."); 4274 return LOST_CREATURE; 4275 } 4277 /* Load Cave */ 4278 unsigned char *cave = LoadPlace(&caerbannog, 4279 "The Cave Of Caerbannog"); 4280 if( cave == 0 ){ 4281 puts("The Cave of Caerbannog must have moved."); 4282 return LOST_PLACE; 4283 } 4285 /* Lure the Killer Rabbit back into the Cave */ 4286 unsigned char *carrot = allocateObjectInPlace( 4287 carrot("fresh"), cave); 4288 if( carrot == 0 ){ 4289 puts("No carrot, no rabbit."); 4290 return LOST_LURE; 4291 } 4292 /* Finally, notify the Killer Rabbit to act */ 4293 return notifyCreature(killerRabbit, &carrot); 4294 4295 ---- 4296 ==== 4298 // end::figure1a[] 4299 [.comment] 4300 end::figure1[] 4302 On the beast's encounter with the Knights of the Round Table, 4303 the following personnel engaged with it in combat: 4305 [.comment] 4306 tag::ul1[] 4307 // tag::ul[] 4309 * Killed 4310 ** Sir Bors 4311 ** Sir Gawain 4312 ** Sir Ector 4313 * Soiled Himself 4314 ** Sir Robin 4315 * Panicked 4316 ** King Arthur 4317 * Employed Ordnance 4318 ** The Lector 4319 ** Brother Maynard 4320 * Scoffed 4321 ** Tim the Enchanter 4323 // end::ul[] 4324 [.comment] 4325 end::ul1[] 4327 [[holy_hand_grenade]] 4328 === Holy Hand Grenade of Antioch 4330 [.comment] 4331 tag::figure2[] 4333 // tag::figure2a[] 4335 [[hand-grenade-figure]] 4336 .The Holy Hand Grenade of Antioch (don't pull the pin) 4337 ==== 4338 [alt=Holy Hand Grenade of Antioch, in ASCII] 4339 .... 4340 ______ 4341 \\/ \/ 4342 __\\ /__ 4343 || //\ | 4344 ||__\\/ __| 4345 || | ,---, 4346 || |====`\ | 4347 || | '---' 4348 ,--'*`--, 4349 _||#|***|#| 4350 _,/.-'#|* *|#`-._ 4351 ,,-'#####| |#####`-. 4352 ,,'########| |########`, 4353 //##########| o |##########\ 4354 ||###########| |###########| 4355 ||############| o |############| 4356 ||------------' '------------| 4357 ||o o o o o o o o o o| 4358 |-----------------------------| 4359 ||###########################| 4360 \\#########################/ 4361 `..#####################,' 4362 ``..###############_,' 4363 ``--.._____..--' 4364 `''-----''` 4365 .... 4366 ==== 4368 // end::figure2a[] 4370 [.comment] 4371 end::figure2[] 4373 [[sovereign-orb]] 4374 .The Sovereign's Orb made invisible 4375 ==== 4376 .Outlines of the Sovereign's Orb 4377 [link=https://camelot.gov.example/sovereigns_orb.jpg,align=right] 4378 image::https://camelot.gov.example/sovereigns_orb.jpg[Orb,124,135] 4379 ==== 4381 [.comment] 4382 tag::index1[] 4383 // tag::index[] 4385 The solution to the impasse at the ((Cave of Caerbannog)) was 4386 provided by the successful deployment of the 4387 *Holy Hand Grenade of Antioch* (see <>) 4388 (((Holy Hand Grenade of Antioch))). 4389 Any similarity between the Holy Hand Grenade of Antioch and the 4390 mythical _Holy Spear of Antioch_ is purely intentional; 4391 (((relics, Christian))) any similarity between the Holy Hand Grenade 4392 of Antioch and the _Sovereign's Orb of the United Kingdom_ 4393 (see <>) is putatively fortuitous. 4394 (((relics, monarchic))) 4396 // end::index[] 4397 [.comment] 4398 end::index1[] 4400 [.comment] 4401 tag::dl1[] 4402 // tag::dl[] 4404 Holy Hand Grenade of Antioch:: 4405 Ordnance deployed by Brother Maynard under the incantation of a 4406 lector, in order to dispense with the Foes of the Virtuous. 4407 See <>. 4409 Holy Spear of Antioch:: 4410 A supposed relic of the crucifixion of Jesus Christ, this is one 4411 of at least four claimed instances of the lance that pierced 4412 Christ's side. Its historical significance lies in inspiring 4413 crusaders to continue their siege of Antioch in 1098. 4415 Sovereign's Orb of the United Kingdom:: 4416 Part of the Crown Jewels of the United Kingdom, the Sovereign's 4417 Orb is a hollow gold sphere set with jewels and topped with a 4418 cross. It was made for Charles II in 1661. See <>. 4420 // end::dl[] 4421 [.comment] 4422 end::dl1[] 4424 [.comment] 4425 tag::bcp14_1[] 4426 // tag::bcp14[] 4428 The instructions in the _Book of Armaments_ on the proper deployment 4429 of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as 4430 follows, although this summary *SHALL NOT* be used as a substitute 4431 for a reading from the Book of Armaments: 4433 // end::bcp14[] 4434 [.comment] 4435 end::bcp14_1[] 4437 [.comment] 4438 tag::ol1[] 4439 // tag::ol[] 4441 . Preamble: St Attila Benediction 4442 . Feast of the People on Sundry Foods 4443 ** Lambs 4444 ** Sloths 4445 ** Carp 4446 ** Anchovies 4447 ** Orangutangs 4448 ** Breakfast Cereals 4449 ** Fruit Bats 4450 ** _et hoc genus omne_ 4451 . Take out the Holy Pin 4452 . The Count 4453 [upperalpha] 4454 .. Count is to Three: no more, no less 4455 .. Not Four 4456 .. Nor Two, except if the count then proceeds to Three 4457 .. Five is Right Out 4458 . Lob the Holy Hand Grenade of Antioch towards the Foe 4459 . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it 4461 // end::ol[] 4462 [.comment] 4463 end::ol1[] 4465 This could also be represented in pseudocode as follows: 4467 [.comment] 4468 tag::listcontinuationblock1[] 4469 // tag::listcontinuationblock[] 4471 . Take out the Holy Pin 4472 . The Count 4473 + 4474 ---- 4475 integer count; 4476 for count := 1 step 1 until 3 do 4477 say(count) 4479 comment Five is Right Out 4480 ---- 4481 . Lob the Holy Hand Grenade of Antioch towards the Foe 4482 . Foe snuffs it 4484 // end::listcontinuationblock[] 4485 [.comment] 4486 end::listcontinuationblock1[] 4488 == Dramatis Personae 4490 The following human (more-or-less) protagonists were involved 4491 in the two incidents recounted as lore of the Knights of the 4492 Round Table: 4494 [.comment] 4495 tag::table1[] 4496 // tag::table[] 4498 [grid=all,options="footer"] 4499 |=== 4500 |French Castle | Cave of Caerbannog 4502 2+|King Arthur 4503 2+|Patsy 4504 2+|Sir Bedevere the Wise 4505 2+|Sir Galahad the Pure 4506 2+|Sir Lancelot the Brave 4507 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot 4508 |French Guard with Outrageous Accent| Tim the Enchanter 4509 |Other French Guards | Brother Maynard 4510 | | The Lector 4511 .3+^|not yet recruited 4512 >|Sir Bors 4513 >|Sir Gawain 4514 >|Sir Ector 4516 |Retinue of sundry knights 4517 |Retinue of sundry more knights than at the French Castle 4518 |=== 4520 // end::table[] 4521 [.comment] 4522 end::table1[] 4524 === Past the Killer Rabbit 4526 Once the Killer Rabbit of Caerbannog (<>) had been 4527 dispatched, the Knights of the Round Table uncovered the last 4528 words of Joseph of Arimathea, inscribed on the Cave of Caerbannog 4529 in Aramaic. While the precise Aramaic wording has not survived, 4530 we trust the following Hebrew subtitles will serve as an 4531 acceptable substitute: 4533 [.comment] 4534 tag::hebrew1[] 4535 // tag::hebrew[] 4537 ____ 4538 .כאן אולי ימצאו המילים האחרונות של יוסף מארמתיה 4539 .מי אשר יהיה אמיץ ובעל נפש טהורה יוכל למצוא את הגביע הקדוש בטירת אאאאאאאה 4541 "Here may be found the last words of Joseph of Arimathea. 4542 He who is valiant and pure of spirit may find the Holy Grail 4543 in the castle of — Aaaargh." 4544 ____ 4546 // end::hebrew[] 4547 [.comment] 4548 end::hebrew1[] 4550 == IANA Considerations 4552 IANA might consider a registry to track the mythical, especially 4553 ravaging beasts, such as the Killer Rabbit, who haunt the Internet. 4555 == Security Considerations 4557 Do not let the Killer Rabbit out under any circumstance. 4559 I repeat. Do not let the Killer Rabbit (<>) out. 4561 [.comment] 4562 tag::bibliography1[] 4563 // tag::bibliography[] 4565 [bibliography] 4566 == Normative References 4567 ++++ 4568 4570 4571 Key words for use in RFCs to Indicate 4572 Requirement Levels 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 ++++ 4584 [bibliography] 4585 == Informative References 4586 ++++ 4588 4589 4590 Monty Python and the Holy Grail 4591 4592 4593 4594 4595 4596 4597 4598 4599 4601 4603 4604 DON'T SPEW A Set of Guidelines for Mass Unsolicited 4605 Mailings and Postings (spam*) 4606 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4621 4622 RFC Format Framework 4623 4624 4625 4626 4627 4628 4629 4630 4632 4634 4635 4636 The Arte of ASCII: Or, An True and Accurate Representation of 4637 an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of 4638 Character 4639 4640 4641 4642 4643 4644 4645 4646 4647 4649 4651 4652 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 4653 Words 4654 4655 4656 4657 4658 RFC 2119 specifies common key words that may be 4659 used 4660 in protocol specifications. This document aims to reduce 4661 the ambiguity by clarifying that only UPPERCASE usage of the 4662 key words have the defined special meanings. 4663 4664 4665 4666 4667 4669 ++++ 4671 // end::bibliography[] 4672 [.comment] 4673 end::bibliography1[] 4674 4676 A.2.2. Rendered as RFC XML v3 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 The Holy Hand Grenade of Antioch 4694 4695 4696 Camelot 4697
4698 4699 Palace 4700 Camel Lot 1 4701 Camelot 4702 England 4703 4704 arthur.pendragon@ribose.com 4705 http://camelot.gov.example 4706
4707 4708 4709 General 4710 Operations and Management 4711 rabbits 4712 grenades 4713 antioch 4714 camelot 4716 4717 4719 The menagerie of beasts and artefacts depicted in RFC8140 4720 may be usefully supplemented by other renowned figures of 4721 Internet and more general lore. This document extends the 4722 menagerie to the seminal fable of the 4723 "Holy Hand Grenade of Antioch", as depicted in the 4724 Monty Python film "Monty Python and the Holy Grail", 4725 as well as "Spamalot", the musical inspired by the movie. 4726 Spamalot 4727 The relevance of the musical "Spamalot" to Internet lore should be 4728 obvious to the reader; but in case of doubt, see also 4729 Section 1 ("What is Spam*?") of RFC2635. 4730 4732 4734 4736 4737
4738 Terminology 4739 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", 4740 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", 4741 "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document 4742 are to be interpreted as described in BCP 14 4743 when, and only when, they appear in all capitals, as shown here. 4744
4745
Introduction refers to the intended move of RFC formatting to 4746 XML2RFC v3 , in the following terms: 4748 4750 4752
4753 Although the RFC Editor has recently dragged the IETF kicking and 4754 screaming into the twentieth century [RFC7990] [RFC7996], there is a 4755 yearning among all right-thinking Internet architects to "keep it 4756 simple" and to return to the olden days when pigs could be given 4757 thrust without anyone taking undue offence. 4758
4760 4761 While no pigs, flying or otherwise, are involved in the transition 4762 to RFC XML v3, it is opportune to enhance the 4763 legendarium in the service of RFC XML v3, by illustrating its 4764 functionality through references to the mythology of Camelot, and 4765 particularly the incidents at the Cave of Caerbannog. 4767 4769 The screaming move into the twenty-first century is accompanied by 4770 a move back to the late twentieth century, with ASCII stylings more 4771 wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be 4772 accessible in 1996.) 4774 4776 There are two references to rabbits in 4777 Monty Python and the Holy Grail which are expounded on herewith: 4779 4781
4782
Trojan Rabbit
4783
4784 In their siege of the French-occupied castle which may already 4785 contain an instance of the Grail, Sir Bedevere the Wise proposes to 4786 use a Trojan Rabbit to infiltrate the castle, with a raiding party 4787 to take the French "not only by surprise, but totally unarmed." 4788 The proposal, unsurprisingly, proved abortive. The more so as the 4789 raiding party forgot to hide within the Trojan Rabbit, before the 4790 French soldiers took the Trojan Rabbit inside the castle. 4791
4792
Killer Rabbit of Caerbannog
4793
Guarding the entrance to the Cave of Caerbannog; see .
4794
4796 4797
4798
The French-occupied castle 4799 4801 The participants of that renowned exercise in cross-cultural 4802 communication, to wit the exchange between the 4803 Knights of the Round Table 4804 and the taunting French soldiers serving under Guy de Lombard are, 4805 properly speaking, outside the scope of this menagerie, being more 4806 or less human. Notwithstanding, severalish beasts both animated 4807 and wooden played a significant part in this encounter; most 4808 notably: 4809
    4810
  • The Projectile Cow, see
    • 4811
  • The Trojan Rabbit, see
    • 4812
4814 4816
4817 The Projectile Cow with an accompanying cannon 4818 .-.-.-.-.-.-.-.-.-.-.-.--.-.-.-.-.-.-.--.-.-.-.-.-.-.-.--.-. 4819 _-_---__--__--___-___-__-____---___-________---____-____-__- 4820 ._.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-…-.-.--..-.-.-.-.-.-..--.- 4821 ,..,.,.,.,.,..,.,,..,.,.,.,.,.,, ^^ .,,.,., ^^ .,.,.,.= 4822 _>-.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-. 4823 .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., 4824 .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # .,.,.,. 4825 .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. 4826 .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ‘ ‘! .,.,..,.,.- 4827 .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_] . ., . . , 4828 .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / -.-<>.,.,..-.-, 4829 .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. 4830 .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- 4831 .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. 4832 .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- 4833 .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- 4834 -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- 4835 ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, 4836 ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- 4837 ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. 4838 .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., 4839 .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,. 4840 ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,. 4841 ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. 4842 .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. 4843 -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> 4844 _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,., 4845 .._...{WITHHONEY}-.-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_> 4846 GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASS<GRASS>PC 4847 SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS 4848 CLAY_ROCKS_REBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY>< 4849 CLAY_CLAY_SKLETONS_MORESOIL_CLAY_CLAY_CLAY_CLAY_CLAY_VR 4850
4851
4852 The Trojan Rabbit with an automatic sliding door 4853 ___ ____ 4854 //_ \//\__\ 4855 || || | 4856 -__||_||__| 4858 // \--_ 4859 // ____ --___ 4860 // // \ \-_ 4861 // \\ @/ o || 4862 // ---- _____|| 4863 // // 4864 //\_//__ // 4865 //-- --- \____ // 4866 // --- \______ // 4867 // , . ----- \_//_ 4868 // ,. --- \____ 4869 // .,v --- \___ 4870 // __ -- \_ 4871 || , _______________ //|| |-_ 4872 || | |''''''''''| // || | | 4873 || ' | | | || | | 4874 || | | | || | | 4875 || " | | 0 | ___||___ | | 4876 || | | | -------- | | 4877 ||___ | | | ______ | |- 4878 // \ | | | // \| _| \ 4879 // \ ____|---|__________|______// \/ | 4880 || X | / || X | / 4881 \\ /\\____/ \\ /___/ 4882 \\_____/ ----- \\_____/--- 4883 ----- ----- 4884
4886 4888 4899 4901 4903 Image courtesy of 4904 4905 4907 4909 The exchange of projectile animals was the beginning of a 4910 long-running fruitful relationship between the British and the 4911 French peoples, 4913 4914 which 4915 arguably predates the traditional English enmity with the 4916 French. 4917 4918 4920 4925 4926
4927
The Mythos of Caerbannog 4928 4930 The Cave of Caerbannog has been well-established in the mythology 4931 of Camelot (as recounted by Monty Python) as the lair of the 4932 Legendary Black Beast of Arrrghhh, more commonly known today as the 4933 Killer Rabbit of Caerbannog . 4934 It is the encounter between the Killer Rabbit of Caerbannog and the 4935 Knights of the Round Table, armed with the Holy Hand Grenade of 4936 Antioch (see the following section), that we 4937 recount here through monospace font and multiple spaces. 4938
The Killer Rabbit of Caerbannog 4939 4941 4943 The Killer Rabbit of Caerbannog, that most formidable foe of 4944 the Knights and of all that is holy or carrot-like, has been 4945 depicted diversely in lay and in song. We venture to say, 4946 contra the claim made in Ze Vompyre, 4947 that the Killer Rabbit of Caerbannog truly is the most afeared 4948 of all the creatures. Short of sanctified ordnance such as 4949 , there are few remedies 4950 known against its awful lapine powers. 4952 4954 4956 The following depiction of the fearsome beast 4957 has been sourced from 4958 Rabbit-SCII, 4959 accompanied 4960 by C code that was used in this accurate depiction of the 4961 Killer Rabbit: 4963 4965 4967
4968 A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 4969 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4970 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4971 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 4972 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 4973 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 4974 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 4975 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 4976 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 4977 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 4978 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 4979 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 4980 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 4981 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 4982 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 4983 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 4984 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 4985 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 4986 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 4987 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 4988 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 4989 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 4990 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 4991 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 4992 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 4993 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 4994 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 4995 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 4996 MW \\/\||v v|| -\\-------___ . ., \ | 4997 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 4998 ) /--------^-^ ,. \|// 4999 # \(/ .\\|x// " ' ' 5000 . , \\||// \||\\\// \\ 5001
5002
5003 C Code To Lure Killer Rabbit Back To Cave 5004 <CODE BEGINS> 5005 /* Locate the Killer Rabbit */ 5006 int type; 5007 unsigned char *killerRabbit = 5008 LocateCreature(&caerbannog, "killer rabbit"); 5009 if( killerRabbit == 0 ){ 5010 puts("The Killer Rabbit of Caerbannog is out of town."); 5011 return LOST_CREATURE; 5012 } 5014 /* Load Cave */ 5015 unsigned char *cave = LoadPlace(&caerbannog, 5016 "The Cave Of Caerbannog"); 5017 if( cave == 0 ){ 5018 puts("The Cave of Caerbannog must have moved."); 5019 return LOST_PLACE; 5020 } 5022 /* Lure the Killer Rabbit back into the Cave */ 5023 unsigned char *carrot = allocateObjectInPlace( 5024 carrot("fresh"), cave); 5025 if( carrot == 0 ){ 5026 puts("No carrot, no rabbit."); 5027 return LOST_LURE; 5028 } 5030 /* Finally, notify the Killer Rabbit to act */ 5031 return notifyCreature(killerRabbit, &carrot); 5032 <CODE ENDS> 5033
5035 5037 On the beast's encounter with the Knights of the Round Table, 5038 the following personnel engaged with it in combat: 5040 5042
    5043
  • 5044 Killed 5045
      5046
    • Sir Bors
      • 5047
    • Sir Gawain
      • 5048
    • Sir Ector
      • 5049
    5050
    • 5051
  • 5052 Soiled Himself 5053
      5054
    • Sir Robin
      • 5055
    5056
    • 5057
  • 5058 Panicked 5059
      5060
    • King Arthur
      • 5061
    5062
    • 5063
  • 5064 Employed Ordnance 5065
      5066
    • The Lector
      • 5067
    • Brother Maynard
      • 5068
    5069
    • 5070
  • 5071 Scoffed 5072
      5073
    • Tim the Enchanter
      • 5074
    5075
    • 5076
5078 5079
5080
Holy Hand Grenade of Antioch 5081 5083
5084 The Holy Hand Grenade of Antioch (don't pull the pin) 5085 ______ 5086 \\/ \/ 5087 __\\ /__ 5088 || //\ | 5089 ||__\\/ __| 5090 || | ,---, 5091 || |====`\ | 5092 || | '---' 5093 ,--'*`--, 5094 _||#|***|#| 5095 _,/.-'#|* *|#`-._ 5096 ,,-'#####| |#####`-. 5097 ,,'########| |########`, 5098 //##########| o |##########\ 5099 ||###########| |###########| 5100 ||############| o |############| 5101 ||------------' '------------| 5102 ||o o o o o o o o o o| 5103 |-----------------------------| 5104 ||###########################| 5105 \\#########################/ 5106 `..#####################,' 5107 ``..###############_,' 5108 ``--.._____..--' 5109 `''-----''` 5110
5112 5114
5115 The Sovereign's Orb made invisible 5116 5117
5119 5121 The solution to the impasse at the Cave of Caerbannog was 5122 provided by the successful deployment of the 5123 Holy Hand Grenade of Antioch (see ) 5124 . 5125 Any similarity between the Holy Hand Grenade of Antioch and the 5126 mythical Holy Spear of Antioch is purely intentional; 5127 any similarity between the Holy Hand Grenade 5128 of Antioch and the Sovereign's Orb of the United Kingdom 5129 (see ) is putatively fortuitous. 5130 5132 5134 5136
5137
Holy Hand Grenade of Antioch
5138
Ordnance deployed by Brother Maynard under the incantation of a 5140 lector, in order to dispense with the Foes of the Virtuous. 5141 See .
5142
Holy Spear of Antioch
5143
A supposed relic of the crucifixion of Jesus Christ, this is one 5144 of at least four claimed instances of the lance that pierced 5145 Christ's side. Its historical significance lies in inspiring 5146 crusaders to continue their siege of Antioch in 1098.
5147
Sovereign's Orb of the United Kingdom
5148
Part of the Crown Jewels of the United Kingdom, the Sovereign's 5149 Orb is a hollow gold sphere set with jewels and topped with a 5150 cross. It was made for Charles II in 1661. See .
5151
5153 5155 5157 The instructions in the Book of Armaments on the proper deployment 5158 of the Holy Hand Grenade of Antioch MAY be summarized as 5159 follows, although this summary SHALL NOT be used as a substitute 5160 for a reading from the Book of Armaments: 5162 5164 5166
    5167
  1. Preamble: St Attila Benediction
    2. 5168
  2. 5169 Feast of the People on Sundry Foods 5170
      5171
    • Lambs
      • 5172
    • Sloths
      • 5173
    • Carp
      • 5174
    • Anchovies
      • 5175
    • Orangutangs
      • 5176
    • Breakfast Cereals
      • 5177
    • Fruit Bats
      • 5178
    • 5179 et hoc genus omne 5180
      • 5181
    5182
    3. 5183
  3. Take out the Holy Pin
    4. 5184
  4. 5185 The Count 5186
      5187
    1. Count is to Three: no more, no less
      2. 5188
    2. Not Four
      3. 5189
    3. Nor Two, except if the count then proceeds to Three
      4. 5190
    4. Five is Right Out
      5. 5191
    5192
    5. 5193
  5. Lob the Holy Hand Grenade of Antioch towards the Foe
    6. 5194
  6. The Foe, being naughty in the LORD's sight, SHALL snuff it
    7. 5195
5197 5199 This could also be represented in pseudocode as follows: 5201 5203
    5204
  1. Take out the Holy Pin
    2. 5205
  2. 5206 The Count 5207
    5208 integer count; 5209 for count := 1 step 1 until 3 do 5210 say(count) 5211 comment Five is Right Out 5212
    5213
    3. 5214
  3. Lob the Holy Hand Grenade of Antioch towards the Foe
    4. 5215
  4. Foe snuffs it
    5. 5216
5218 5219
5220
Dramatis PersonaeThe following human (more-or-less) protagonists were involved 5221 in the two incidents recounted as lore of the Knights of the 5222 Round Table: 5224 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281
French CastleCave of Caerbannog
King Arthur
Patsy
Sir Bedevere the Wise
Sir Galahad the Pure
Sir Lancelot the Brave
Sir Robin the Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous AccentTim the Enchanter
Other French GuardsBrother Maynard
5262 The Lector
not yet recruitedSir Bors
Sir Gawain
Sir Ector
Retinue of sundry knightsRetinue of sundry more knights than at the French Castle
5282 5284
Past the Killer RabbitOnce the Killer Rabbit of Caerbannog () had been 5285 dispatched, the Knights of the Round Table uncovered the last 5286 words of Joseph of Arimathea, inscribed on the Cave of Caerbannog 5287 in Aramaic. While the precise Aramaic wording has not survived, 5288 we trust the following Hebrew subtitles will serve as an 5289 acceptable substitute: 5291 5293
.כאן אולי ימצאו המילים האחרונות של יוסף מארמתיה 5294 .מי אשר יהיה אמיץ ובעל נפש טהורה יוכל למצוא את הגביע הקדוש בטירת אאאאאאאה 5295 "Here may be found the last words of Joseph of Arimathea. 5296 He who is valiant and pure of spirit may find the Holy Grail 5297 in the castle of — Aaaargh."
5299 5300
5301
5302 IANA Considerations 5303 IANA might consider a registry to track the mythical, especially 5304 ravaging beasts, such as the Killer Rabbit, who haunt the Internet. 5305
5306
Security ConsiderationsDo not let the Killer Rabbit out under any circumstance. 5307 I repeat. Do not let the Killer Rabbit () out. 5309 5310
5311 5312 5313 Normative References 5314 5315 5316 5317 Informative References 5318 5319 5320 Monty Python and the Holy Grail 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5339 A.3. Example 3: "An API For Calendar-Based Fortune Heuristics Services" 5340 in AsciiRFC 5342 This example is available in the following formats: 5344 o AsciiRFC [git-divination-cfapi] 5346 o Internet-Draft [I-D.divination-cfapi] 5348 o Text, RFC XML, PDF and HTML on the IETF Datatracker 5349 [datatracker-divination-cfapi] 5351 A.3.1. In AsciiRFC 5353 5354 = An API For Calendar-Based Fortune Heuristics Services 5355 Gabriel Destiny; Charise Luck 5356 :doctype: internet-draft 5357 :abbrev: Calendar Fortune Heuristics API 5358 :name: draft-divination-cfapi-00 5359 :status: informational 5360 :ipr: trust200902 5361 :area: Internet 5362 :submission-type: independent 5363 :intended-series: informational 5364 :revdate: 2018-03-23T00:00:00Z 5365 :lastname: Destiny 5366 :fullname: Gabriel Destiny 5367 :forename_initials: G. 5368 :organization: Divination Inc. 5369 :email: gabriel.destiny@ribose.com 5370 :street: 9288 N Divine Street 5371 :city: Dunn 5372 :code: 28334 5373 :region: NC 5374 :country: United States of America 5375 :lastname_2: Luck 5376 :fullname_2: Charise Luck 5377 :forename_initials_2: C. 5379 :organization_2: Divination Inc. 5380 :email_2: charise.luck@ribose.com 5381 :street_2: 9288 N Divine Street 5382 :city_2: Dunn 5383 :code_2: 28334 5384 :region_2: NC 5385 :country_2: United States of America 5387 [.comment] 5388 tag::sample[] 5389 // tag::sample[] 5391 [abstract] 5393 This document describes a JSON HTTP API for online services that 5394 provide calendar-based fortune heuristics. 5396 == Introduction 5398 Fortune-telling, the practice of predicting information about a 5399 person's life, is an activity practiced throughout history. 5401 While there are myriad forms of fortune telling methodologies, this 5402 document applies to a particular form of service that provides fortune 5403 heuristics, commonly known as "luck", for a particular subject based 5404 on a calendar-based input. 5406 Since HTTP <> status codes are insufficient to convey 5407 information about fortune heuristics, this specification defines a 5408 simple JSON <> document format for this purpose. The 5409 response can be used by HTTP APIs to deliver results to non-human 5410 clients or to an end-user. 5412 == Conventions Used in This Document 5414 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 5415 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 5416 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 5417 are to be interpreted as described in BCP 14 <> <> 5418 when, and only when, they appear in all capitals, as shown here. 5420 The following definitions apply in this document: 5422 Well-known URI:: This specification makes use of the "well-known URI" 5423 feature of HTTP servers <> to provide a bootstrapping URI for 5424 the client usage of fortune heuristics services. 5426 Root of Fortune:: The service discovery endpoint that provides a URI 5427 list of available fortune heuristic endpoints available, in accordance 5428 with <>. 5430 == Fortune Heuristics Service Well-Known URI 5432 A well-known URI called "fortune" is registered by this specification 5433 for fortune heuristics services (see <>). 5435 Services complying with this document *SHOULD* have its well-known 5436 URI pointing (directly or through redirection) to the Root of Fortune. 5438 The Root of Fortune can be used by the client for service discovery, 5439 namely, the available calendar-based fortune heuristics services 5440 available on the server, as specified in <>. 5442 === Well-Known URI Redirection 5444 Servers *MUST* redirect HTTP requests for that resource to the 5445 actual "context path" using one of the available mechanisms provided 5446 by HTTP <> (e.g., using a 301, 303, or 307 response). 5448 Clients *MUST* handle HTTP redirects on the well-known URI. 5450 === Well-Known URI Cache Behavior 5452 Servers *SHOULD* set an appropriate Cache-Control header value (as 5453 according to <>) in the redirect response to set 5454 caching behavior as required by the type of response generated. 5456 == New HTTP Methods: SEEK and DIVINE 5458 This specification defines two new HTTP methods: "SEEK" and "DIVINE" 5459 methods for HTTP <>. 5461 While HTTP GET requests are treated equivalently as the "SEEK" and 5462 "DIVINE" requests, its usage is discouraged and therefore *SHOULD NOT* 5463 be used. 5465 Usage of these methods are defined in the sections below. 5467 == Defined Data Types: Date-Time Formats 5469 This specification defines a number of date-time formats as according 5470 to the conventions of <> for the unambiguous communication 5471 between client and server. 5473 The types defined are as follows. 5475 `DATETIME`:: 5476 As described in <>, with the addition that reduced 5477 accuracy representations described in <> are 5478 supported. Reduced accuracy date and times are accepted where a 5479 date or time component (2-digits long) is replaced by "--". 5480 + 5481 For example, the date time "2018-04---T01:02:00Z" represents the UTC 5482 time of 1:02am, on an unknown day within April of the year 2018. 5484 `DATE`:: 5485 As described in "DATETIME", but the "time" component will not be 5486 taken into account in the algorithm. 5488 [#service-discovery] 5489 == Fortune Heuristics Service Discovery 5491 [#root-of-fortune] 5492 === Root of Fortune Path URI ("/") 5494 The Root of Fortune URI, defined as "/" in this document, is used for 5495 service discovery on types of calendar-based fortune heuristics 5496 available. 5498 An empty SEEK request with the "application/json" request type 5499 *MUST* be sent to this endpoint to retrieve the available endpoints. 5500 All other HTTP methods *MUST NOT* be supported at this URI. 5502 An example of such a response is as follows: 5504 [source,json] 5505 ---- 5506 HTTP/1.1 200 Success 5507 Content-Type: application/json 5508 Content-Language: en 5510 { 5511 "diviners" : [ 5512 "/astrology", 5513 "/bazi", 5514 ] 5515 } 5516 ---- 5517 A service discovery object *MUST* have the following members: 5519 `diviners`:: 5520 (JSON array) 5521 An array that contains endpoints that conform to this specification. 5522 All endpoints listed here are relative to the Root of Fortune path. 5523 For example, the path "/astrology" listed in the example has an 5524 endpoint path of "[root-of-fortune]/astrology", where 5525 "[root-of-fortune]" indicates the real path of the Root of Fortune. 5527 // end::sample[] 5528 [.comment] 5529 end::sample[] 5531 [#service-endpoint] 5532 == Fortune Heuristics Service Endpoint 5534 An endpoint offering fortune heuristics services *MUST* adhere to 5535 specifications in this section. 5537 A service *MAY* implement multiple divination services based on 5538 different divination methods, such as the digital oracle shown 5539 in <>. 5541 [[digital-oracle]] 5542 .Dimensional Eye, a digital oracle that communicates through one button 5543 ==== 5544 [alt=An incarnation of the Dimensional Eye, in ASCII] 5545 .... 5546 __ 5547 __===^-\ 5548 __=== -\ 5549 __===- -\ 5550 __===- -\ 5551 ___===- -\ 5552 ===- ---__ -\ 5553 \\\ |||^^\ \__ -\ 5554 \\\ ||| \__ -\ 5555 \\\ ||| ______\_ -\ 5556 \\\ ||| _/-******\\__ -\ 5557 \\\ || /-****_****-\ \_ -\ 5558 \\\ || |-***/ \***-\ \_ -\ 5559 \\\ || |-***\___/***-| \ -\ 5560 \\\ || \-*********-/ __--/ -\ 5561 \\\ || \-******/__-- -\ 5562 \\\ || __-- -\ 5563 \\\ || __-- -\ 5564 \\\ ||__-- -\ 5565 \\\ -\ 5566 \\\ -\ 5567 \\\ -\ 5568 \\\ -\ 5569 \\\ __ -\ 5570 \\\ //##\\ -\ 5571 \\\ \\##// -\ 5572 \\\ ^^ __--==^ 5573 \\\ __--=== 5574 \\\ __--=== 5575 \\\ __--=== 5576 \\\ __--== 5577 \\= 5579 .... 5580 ==== 5582 [#endpoint-specification-request] 5583 === Service Specification Request 5585 To retrieve capabilities and parameters of an endpoint complying with 5586 this specification, a service specification JSON object is returned. 5588 An empty SEEK request with the "application/json" request type 5589 *MUST* be sent to this endpoint to retrieve the service 5590 specification that describes parameters accepted by this endpoint. 5592 Two examples of such a response are given below. 5594 [source,json] 5595 ---- 5596 HTTP/1.1 200 Success 5597 Content-Type: application/json 5598 Content-Language: en 5600 { 5601 "description": "Gaze into your upcoming luck!", 5602 "details": "https://divine.example.com/manual/astrology-api", 5603 "parameters": { 5604 "birthday": { 5605 "type": "DATE", 5606 "description": "Your birth date in UTC" 5607 }, 5608 "targetDateBegin": { 5609 "type": "DATE", 5610 "description": "Start of the target date range to report on" 5611 }, 5612 "targetDateEnd": { 5613 "type": "DATE", 5614 "description": "End of the target date range to report on" 5615 }, 5616 "interval": { 5617 "values": { 5618 "D": "Daily", 5619 "M": "Monthly", 5620 "Y": "Yearly" 5621 }, 5622 "description": "Available intervals to report on." 5623 } 5624 } 5625 } 5626 ---- 5628 [source,json] 5629 ---- 5630 HTTP/1.1 200 Success 5631 Content-Type: application/json 5632 Content-Language: en 5634 { 5635 "description": "Matches and mis-matches according to the " 5636 "Yin Yang and Five Elements techniques", 5637 "details": "https://divine.example.com/manual/bazi-api", 5638 "parameters": { 5639 "birthday": { 5640 "type": "DATETIME", 5641 "description": "Your birth date and time in UTC" 5642 }, 5643 "targetDateBegin": { 5644 "type": "DATETIME", 5645 "description": "Start of the target date/time range to report on" 5646 }, 5647 "targetDateEnd": { 5648 "type": "DATETIME", 5649 "description": "End of the target date/time range to report on" 5650 }, 5651 "interval": { 5652 "values": { 5653 "H": "Hourly", 5654 "D": "Daily", 5655 "M": "Monthly", 5656 "Y": "Yearly" 5657 }, 5658 "description": "Available intervals to report on." 5659 } 5660 } 5661 } 5662 ---- 5664 [#service-endpoint-specification] 5665 === Service Specification Object 5667 A service specification object *MUST* contain the following members. 5669 `description`:: 5670 (string) A short, human-readable summary of the fortune heuristic 5671 service at this endpoint. This *SHOULD* be a stable reference. 5673 `details`:: 5674 (URI, optional) A URI reference that provides further details for 5675 human consumption, such as API documentation that includes details of 5676 parameters accepted or response states. 5678 `parameters`:: 5679 (object, mandatory) An object that specifies what parameters 5680 are accepted by this endpoint. Each parameter key within this object 5681 specifies an accepted parameter name, and its value is a parameter 5682 specification object, which is described below. 5684 A parameter specification object *SHOULD* contain the following 5685 members: 5687 `type`:: 5688 (string, optional) The value type accepted by this parameter. Value 5689 types are described in this document. This member is mutually 5690 exclusive with `values`. 5692 `description`:: 5693 (string, mandatory) The purpose of this parameter. 5695 `values`:: 5696 (object, optional) The accepted values of this parameter, unlisted 5697 values *SHOULD* not be accepted by the parameter. Each key within 5698 this object specifies an accepted value, and its value provides a 5699 description of the purpose of the value. 5701 [#endpoint-report] 5702 == Fortune Heuristics Report Request and Response 5704 [#endpoint-report-request] 5705 === Fortune Heuristics Report Request 5707 A request using the HTTP "DIVINE" method and the "application/json" 5708 type *MUST* be sent to the fortune heuristic endpoint to retrieve 5709 results for a fortune heuristic query. 5711 The request made *MUST* conform to the specifications of the 5712 endpoint, as retrieved via the "SEEK" method described in 5713 <>. 5715 An example of a request is provided below. 5717 [source] 5718 ---- 5719 URI: /divination/astrology 5720 Method: DIVINE 5721 Content-Type: application/json 5722 Content-Language: en 5724 { 5725 "birthday": "1976-02-11T00:00:00Z", 5726 "targetDateBegin": "2018-01-01T00:00:00Z", 5727 "targetDateEnd": "2019-01-01T00:00:00Z", 5728 "interval": "M" 5729 } 5730 ---- 5732 [#endpoint-report-response] 5733 === Fortune Heuristics Report Response 5735 A fortune heuristic query using the "DIVINE" method triggers a 5736 response that contains a fortune heuristics report. 5738 A successful response returns a JSON object that *MUST* conform 5739 to the object structure described in this section. 5741 A report object *SHOULD* contain the following members: 5743 `type`:: 5744 (URI, mandatory) A URI that defines the type of the report located 5745 at the `report` key of this object. 5747 `report`:: 5748 (object, mandatory) An object that contains two keys, `intervals` 5749 and `events`. The `intervals` object contains an array of interval 5750 objects that matches the demanded intervals in the request within 5751 the target date range. 5753 The `events` object contains an array of significant event objects 5754 within the target date range. 5756 An example of a response is provided below. 5758 [source] 5759 ---- 5760 URI: /divination/astrology 5761 Method: DIVINE 5762 HTTP/1.1 200 Success 5763 Content-Type: application/json 5764 Content-Language: en 5766 { 5767 "type": "https://association-of.astrology/reports/monthly", 5768 "report": { 5769 "intervals": [ 5770 { 5771 "dateStart": "2018-01-01T00:00:00Z", 5772 "dateEnd": "2018-02-01T00:00:00Z", 5773 "categories": [ 5774 { 5775 "category": 5776 "https://divine.example.com/astrology/categories/health" 5777 "value": 80, 5778 "description": "Charge ahead with excellent health." 5779 }, 5780 { 5781 "category": 5782 "https://divine.example.com/astrology/categories/love" 5783 "value": 70, 5784 "description": 5785 "Give a certain person or situation another try!" 5786 }, 5787 { 5788 "category": 5789 "https://divine.example.com/astrology/categories/finance" 5790 "value": 5, 5791 "description": "You've just realized that you don't have 5792 any cash on hand." 5793 } 5794 ] 5795 }, 5796 { 5797 "dateStart": "2018-02-01T00:00:00Z", 5798 "dateEnd": "2018-03-01T00:00:00Z", 5799 "..." 5800 }, 5801 "..." 5802 ], 5803 "events": [ 5804 { 5805 "dateStart": "2018-01-15T03:20:00", 5806 "dateEnd": "2018-01-16T20:22:15", 5807 "description": "The planet of growth and good luck, Jupiter 5808 will make a harmonious connection with power planet Pluto, 5809 helping you connect with influential people", 5810 "recommendation": "Engage in networking during this time." 5811 }, 5812 { 5813 "dateStart": "2018-03-22T00:12:40", 5814 "dateEnd": "2018-03-28T02:45:03", 5815 "description": "Communication planet Mercury enters your sign, 5816 which will find you in a busier and chattier mood.", 5817 "recommendation": 5818 "Take charge of work with your newfound energy." 5819 } 5820 "..." 5821 ] 5822 } 5823 } 5824 ---- 5826 Fortune heuristic reports are created by a divination output that 5827 *MAY* requires quantitative interpretation. A sample representation of 5828 interpreting a graphical divination output is provided in 5829 <>. 5831 [[divination-message]] 5832 .Forty-nine yarrow sticks reveals a mystical message on fortune 5833 ==== 5834 [alt=A mystical pattern in ASCII] 5835 .... 5836 0000000000000000000000000 5837 0000000000000000000000001 G 1000000000000000000000000 5838 0000000000000000000000011 R 1100000000000000000000000 5839 0000000000000000000000111 A 1110000000000000000000000 5840 0000000000000000000001111 C 1111000000000000000000000 5841 0000000000000000000011111 E 1111100000000000000000000 5842 0000000000000000000111111 , 1111110000000000000000000 5843 0000000000000000001111111 1111111000000000000000000 5844 0000000011111111111111111 M 1111111111111111100000000 5845 0000000111111111111111111 E 1111111111111111110000000 5846 0000001111111111111111111 R 1111111111111111111000000 5847 0000011111111111111111111 C 1111111111111111111100000 5848 0000111111111111111111111 Y 1111111111111111111110000 5849 0001111111111111111111111 , 1111111111111111111111000 5850 0011111111111111111111111 1111111111111111111111100 5851 0111111111111111111111111 A 1111111111111111111111110 5852 0000000000000000011111111 N 1111111100000000000000000 5853 0000000000000000111111111 D 1111111110000000000000000 5854 0000000000000001111111111 1111111111000000000000000 5855 0000000000000011111111111 P 1111111111100000000000000 5856 0000000000000111111111111 E 1111111111110000000000000 5857 0000000000001111111111111 A 1111111111111000000000000 5858 0000000000011111111111111 C 1111111111111100000000000 5859 0000000000111111111111111 E 1111111111111110000000000 5860 0000000001111111111111111 . 1111111111111111000000000 5861 .... 5862 ==== 5864 [#endpoint-report-interval-obj] 5865 === Report Interval Object 5867 The `intervals` value of a report object contains a number of report 5868 intervals -- each representing a non-overlapping period of the 5869 selected interval length. When all of these intervals are put 5870 together, the combined period *MUST* fully cover the requested 5871 report target period. 5873 An example interval object is shown below. 5875 [source,json] 5876 ---- 5877 { 5878 "dateStart": "2018-01-01T00:00:00Z", 5879 "dateEnd": "2018-02-01T00:00:00Z", 5880 "categories": [ 5881 { 5882 "category": 5883 "https://divine.example.com/astrology/categories/health" 5884 "value": 80, 5885 "description": "Charge ahead with your excellent health." 5886 }, 5887 { 5888 "category": 5889 "https://divine.example.com/astrology/categories/love" 5890 "value": 70, 5891 "description": "Give a certain person or situation another try!" 5892 }, 5893 { 5894 "category": 5895 "https://divine.example.com/astrology/categories/finance" 5896 "value": 5, 5897 "description": "You've just realized that you don't have 5898 any cash on hand." 5899 } 5900 ] 5901 } 5902 ---- 5904 An interval object *MUST* contain the following members: 5906 `dateStart`:: 5907 (datetime, mandatory) This value specifies the start of the period 5908 which this interval object applies to. 5910 `dateEnd`:: 5911 (datetime, mandatory) This value specifies the end of the period 5912 which this interval object applies to. 5914 In the given example, the `categories` key is an implementation 5915 specific object that details heuristic results returned by the 5916 selected algorithm. This *MAY* differ in different algorithms. 5918 [#endpoint-report-event-obj] 5919 === Report Events Object 5921 The `events` value of a report object contains a number of event 5922 objects. Each event object represents an event relevant to the 5923 calculation of fortune heuristics during a target report period. These 5924 events *MAY* be of variable time lengths, and *MAY* be overlapping 5925 amongst each other. 5927 The following example demonstrates two event objects the service 5928 determines relevant to a user's query. 5930 [source,json] 5931 ---- 5932 { 5933 "dateStart": "2018-01-15T03:20:00", 5934 "dateEnd": "2018-01-16T20:22:15", 5935 "description": "The planet of growth and good luck, Jupiter will 5936 make a harmonious connection with power planet Pluto, helping you 5937 connect with influential people", 5938 "recommendation": "Engage in networking during this time." 5939 }, 5940 { 5941 "dateStart": "2018-03-22T00:12:40", 5942 "dateEnd": "2018-03-28T02:45:03", 5943 "description": "Communication planet Mercury enters your sign, 5944 which will find you in a busier and chattier mood.", 5945 "recommendation": "Take charge of work with your newfound energy." 5946 } 5947 ---- 5949 Similar to an interval object, an event object *MUST* contain the 5950 following members: 5952 `dateStart`:: 5953 (datetime, mandatory) This value specifies the start of the period 5954 described by the event. 5956 `dateEnd`:: 5957 (datetime, mandatory) This value specifies the end of the period 5958 described by the event. 5960 In the given example, the keys `description` and `recommendation` 5961 are implementation-specific details. This *MAY* differ in different 5962 algorithms. 5964 [#endpoint-report-errors] 5965 === Report Generation Errors 5967 This specification makes use of normal HTTP error codes with the 5968 following extensions. 5970 Errors *MUST* be returned using the Problem JSON Structure as 5971 accordance with <>. 5973 422 Unprocessable Entity:: 5974 For example, a malformed date-time parameter, or an illogical input, 5975 such as when the subject's birthday occurs after the report target 5976 date period. 5978 473 Beyond Existing Capability:: 5979 The service determines that the outcome is too difficult to predict. 5980 For example, in the case where the calculation is too complex to 5981 complete in a certain time period. The service *SHOULD* issue this 5982 response code to indicate that the client should not try the same 5983 request again. 5985 474 Outcome Impossible:: 5986 The service determines that the outcome is impossible. For example, 5987 when the algorithm determines that the subject will have deceased 5988 before the start of the requested target period. 5990 [#security] 5991 == Security Considerations 5993 * TLS <> and authenticated HTTP requests should be used to 5994 protect the DIVINE request and responses due to the personal nature 5995 of information transmitted. 5997 * A client *SHOULD* verify the identity of the server on every 5998 request to prevent impersonation or man-in-the-middle attacks, as data 5999 transmitted to and from the server is sensitive information, and at 6000 times critical information to the user. 6002 * Synchronization of client and server time *MUST* be 6003 well-considered in the implementation of this specification. A 6004 mismatch of client and server time *MAY* lead to algorithm 6005 miscalculations that can cause mistaken choices of a user that depends 6006 on the reliability of this system. 6008 [#iana] 6009 == IANA Considerations 6011 === Well-Known URI Registrations 6013 This document defines a well-known URI using the registration 6014 procedure and template from <>. 6016 ==== "fortune" Well-Known URI Registration 6018 URI suffix:: fortune 6020 Change controller:: IETF 6022 Specification document(s):: This document 6024 Related information:: N/A. 6026 [.comment] 6027 tag::sample[] 6028 // begin::sample[] 6030 [bibliography] 6031 == Normative References 6033 ++++ 6035 6037 6038 Key words for use in RFCs to Indicate Requirement 6039 Levels 6040 6041 6042 6043 6044 In many standards track documents several 6045 words are 6046 used to signify the requirements in the specification. These 6047 words are often capitalized. This document defines these words 6048 as they should be interpreted in IETF documents. This 6049 document specifies an Internet Best Current Practices for the 6050 Internet Community, and requests discussion and suggestions 6051 for improvements. 6052 6053 6054 6055 6056 6058 6060 6061 Defining Well-Known Uniform Resource Identifiers 6062 (URIs) 6063 6065 6066 6067 6069 6070 6071 6072 This memo defines a path prefix for 6073 "well-known 6074 locations", "/.well-known/", in 6075 selected Uniform 6076 Resource Identifier (URI) schemes. 6077 [STANDARDS-TRACK] 6078 6079 6080 6081 6083 6085 6086 Hypertext Transfer Protocol (HTTP/1.1): Message Syntax 6087 and 6088 Routing 6089 6091 6092 6093 6095 6096 6097 6098 The Hypertext Transfer Protocol (HTTP) is a 6099 stateless 6100 application-level protocol for distributed, collaborative, 6101 hypertext information systems. This document provides an 6102 overview of HTTP architecture and its associated terminology, 6103 defines the "http" and 6104 "https" Uniform 6105 Resource Identifier (URI) schemes, defines the HTTP/1.1 6106 message syntax and parsing requirements, and describes related 6107 security concerns for 6108 implementations. 6109 6110 6111 6112 6114 6116 6117 Hypertext Transfer Protocol (HTTP/1.1): 6118 Caching 6119 6121 6122 6123 6126 6128 6129 6131 6132 6133 6134 The Hypertext Transfer Protocol (HTTP) is a 6135 stateless 6136 \%application- level protocol for distributed, collaborative, 6137 hypertext information systems. This document defines HTTP 6138 caches and the associated header fields that control cache 6139 behavior or indicate cacheable response 6140 messages. 6141 6142 6143 6144 6146 6148 6149 Problem Details for HTTP APIs 6150 6152 6153 6154 6155 6156 6157 6158 This document defines a "problem 6159 detail" 6160 as a way to carry machine- readable details of errors in a 6161 HTTP response to avoid the need to define new error response 6162 formats for HTTP APIs. 6163 6164 6165 6166 6168 6170 6171 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 6172 Words 6173 6174 6175 6176 6177 RFC 2119 specifies common key words that 6178 may be used 6179 in protocol specifications. This document aims to reduce 6180 the ambiguity by clarifying that only UPPERCASE usage of the 6181 key words have the defined special 6182 meanings. 6183 6184 6185 6186 6187 6189 6191 6192 The JavaScript Object Notation (JSON) Data Interchange 6193 Format 6194 6196 6197 6198 6199 JavaScript Object Notation (JSON) is a 6200 lightweight, 6201 text-based, language-independent data interchange format. 6202 It was derived from the ECMAScript Programming Language 6203 Standard. JSON defines a small set of formatting rules for 6204 the portable representation of structured data. 6205 This document removes inconsistencies with other 6206 specifications of JSON, repairs specification errors, and 6207 offers experience-based interoperability 6208 guidance. 6209 6210 6211 6212 6213 6214 6215 ++++ 6217 [bibliography] 6218 == Informative References 6220 ++++ 6222 6224 6225 ISO/DIS 8601-1:2018, Data elements and interchange 6226 formats -- Information interchange -- Representation of dates 6227 and times -- Part 1: Basic rules 6228 6229 ISO/IEC 6230
6231 http://www.iso.org 6232
6233 6234 6235 6236 6237 6239 6241 6242 Date and Time on the Internet: Timestamps 6243 6244 6245 6246 6247 6248 6249 6250 6251 6252 6253 6255 6257 6258 The Transport Layer Security (TLS) Protocol 6259 Version 1.2 6260 6261 6262 6263 6265 6266 6267 6268 This document specifies Version 1.2 of the 6269 Transport 6270 Layer Security (TLS) protocol. The TLS protocol provides 6271 communications security over the Internet. The protocol 6272 allows client/server applications to communicate in a way 6273 that is designed to prevent eavesdropping, tampering, or 6274 message forgery. [STANDARDS-TRACK] 6275 6276 6277 6278 6279 ++++ 6281 [appendix] 6282 == Acknowledgements 6284 The authors thank the following individuals for their valuable 6285 feedback on this specification, and commend them for making fortune 6286 heuristics more accessible for the benefit of mankind. 6288 // end::sample[] 6289 [.comment] 6290 end::sample[] 6291 6293 A.4. Rendered as RFC XML v3 6295 6296 6297 6298 6299 6300 6301 6302 6303 6304 6305 6306 6307 6308 An API For Calendar-Based Fortune Heuristics Services 6309 6310 6311 6312 Divination Inc. 6313
6314 6315 9288 N Divine Street 6316 Dunn 6317 NC 6318 28334 6319 United States of America 6320 6321 gabriel.destiny@ribose.com 6322
6323 6324 6325 Divination Inc. 6326
6327 6328 9288 N Divine Street 6329 Dunn 6330 NC 6331 28334 6332 United States of America 6333 6334 charise.luck@ribose.com 6335
6336 6337 6338 Internet 6340 6341 6343 This document describes a JSON HTTP API for online services that 6344 provide calendar-based fortune heuristics. 6345 6346
IntroductionFortune-telling, the practice of predicting information about a 6347 person’s life, is an activity practiced throughout history. 6348 While there are myriad forms of fortune telling methodologies, this 6349 document applies to a particular form of service that provides fortune 6350 heuristics, commonly known as "luck", for a particular subject based 6351 on a calendar-based input. 6352 Since HTTP status codes are insufficient to convey 6353 information about fortune heuristics, this specification defines a 6354 simple JSON document format for this purpose. The 6355 response can be used by HTTP APIs to deliver results to non-human 6356 clients or to an end-user.
6357
Conventions Used in This DocumentThe key words "MUST", "MUST NOT", "REQUIRED", "SHALL", 6358 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", 6359 "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document 6360 are to be interpreted as described in BCP 14 6361 when, and only when, they appear in all capitals, as shown here. 6362 The following definitions apply in this document: 6363
6364
Well-known URI
6365
This specification makes use of the "well-known URI" 6366 feature of HTTP servers to provide a bootstrapping URI for 6367 the client usage of fortune heuristics services.
6368
Root of Fortune
6369
The service discovery endpoint that provides a URI 6370 list of available fortune heuristic endpoints available, in accordance 6371 with .
6372
6373
Fortune Heuristics Service Well-Known URIA well-known URI called "fortune" is registered by this specification 6374 for fortune heuristics services (see ). 6375 Services complying with this document SHOULD have its well-known 6376 URI pointing (directly or through redirection) to the Root of Fortune. 6377 The Root of Fortune can be used by the client for service discovery, 6378 namely, the available calendar-based fortune heuristics services 6379 available on the server, as specified in . 6380
Well-Known URI RedirectionServers MUST redirect HTTP requests for that resource to the 6381 actual "context path" using one of the available mechanisms provided 6382 by HTTP (e.g., using a 301, 303, or 307 response). 6383 Clients MUST handle HTTP redirects on the well-known URI.
6384
6385 Well-Known URI Cache Behavior 6386 Servers SHOULD set an appropriate Cache-Control header value (as 6387 according to ) in the redirect response to set 6388 caching behavior as required by the type of response generated. 6389
6390
New HTTP Methods: SEEK and DIVINEThis specification defines two new HTTP methods: "SEEK" and "DIVINE" 6391 methods for HTTP . 6392 While HTTP GET requests are treated equivalently as the "SEEK" and 6393 "DIVINE" requests, its usage is discouraged and therefore SHOULD NOT 6394 be used. 6395 Usage of these methods are defined in the sections below.
6396
Defined Data Types: Date-Time FormatsThis specification defines a number of date-time formats as according 6397 to the conventions of for the unambiguous communication 6398 between client and server. 6399 The types defined are as follows. 6400
6401
6402 DATETIME 6403
6404
6405 As described in , with the addition that reduced 6406 accuracy representations described in are 6407 supported. Reduced accuracy date and times are accepted where a 6408 date or time component (2-digits long) is replaced by "--". 6409 For example, the date time "2018-04---T01:02:00Z" represents the UTC 6410 time of 1:02am, on an unknown day within April of the year 2018. 6411
6412
6413 DATE 6414
6415
As described in "DATETIME", but the "time" component will not be 6416 taken into account in the algorithm.
6417
6418
6419 Fortune Heuristics Service Discovery 6420
Root of Fortune Path URI ("/")The Root of Fortune URI, defined as "/" in this document, is used for 6421 service discovery on types of calendar-based fortune heuristics 6422 available. 6423 An empty SEEK request with the "application/json" request type 6424 MUST be sent to this endpoint to retrieve the available endpoints. 6425 All other HTTP methods MUST NOT be supported at this URI. 6426 An example of such a response is as follows: 6427
6428 HTTP/1.1 200 Success 6429 Content-Type: application/json 6430 Content-Language: en 6432 { 6433 "diviners" : [ 6434 "/astrology", 6435 "/bazi", 6436 ] 6437 } 6438
6439 A service discovery object MUST have the following members: 6440
6441
6442 diviners 6443
6444
(JSON array) 6445 An array that contains endpoints that conform to this specification. 6446 All endpoints listed here are relative to the Root of Fortune path. 6447 For example, the path "/astrology" listed in the example has an 6448 endpoint path of "[root-of-fortune]/astrology", where 6449 "[root-of-fortune]" indicates the real path of the Root of Fortune.
6450
6452 6453
6454
6455
Fortune Heuristics Service EndpointAn endpoint offering fortune heuristics services MUST adhere to 6456 specifications in this section. 6457 A service MAY implement multiple divination services based on 6458 different divination methods, such as the digital oracle shown 6459 in . 6460
6461 Dimensional Eye, a digital oracle that communicates through one button 6462 __ 6463 __===^-\ 6464 __=== -\ 6465 __===- -\ 6466 __===- -\ 6467 ___===- -\ 6468 ===- ---__ -\ 6469 \\\ |||^^\ \__ -\ 6470 \\\ ||| \__ -\ 6471 \\\ ||| ______\_ -\ 6472 \\\ ||| _/-******\\__ -\ 6473 \\\ || /-****_****-\ \_ -\ 6474 \\\ || |-***/ \***-\ \_ -\ 6475 \\\ || |-***\___/***-| \ -\ 6476 \\\ || \-*********-/ __--/ -\ 6477 \\\ || \-******/__-- -\ 6478 \\\ || __-- -\ 6479 \\\ || __-- -\ 6480 \\\ ||__-- -\ 6481 \\\ -\ 6482 \\\ -\ 6483 \\\ -\ 6484 \\\ -\ 6485 \\\ __ -\ 6486 \\\ //##\\ -\ 6487 \\\ \\##// -\ 6488 \\\ ^^ __--==^ 6489 \\\ __--=== 6490 \\\ __--=== 6491 \\\ __--=== 6492 \\\ __--== 6493 \\= 6494 6495
6496
Service Specification RequestTo retrieve capabilities and parameters of an endpoint complying with 6497 this specification, a service specification JSON object is returned. 6498 An empty SEEK request with the "application/json" request type 6499 MUST be sent to this endpoint to retrieve the service 6500 specification that describes parameters accepted by this endpoint. 6501 Two examples of such a response are given below. 6502
6503 HTTP/1.1 200 Success 6504 Content-Type: application/json 6505 Content-Language: en 6507 { 6508 "description": "Gaze into your upcoming luck!", 6509 "details": "https://divine.example.com/manual/astrology-api", 6510 "parameters": { 6511 "birthday": { 6512 "type": "DATE", 6513 "description": "Your birth date in UTC" 6514 }, 6515 "targetDateBegin": { 6516 "type": "DATE", 6517 "description": "Start of the target date range to report on" 6518 }, 6519 "targetDateEnd": { 6520 "type": "DATE", 6521 "description": "End of the target date range to report on" 6522 }, 6523 "interval": { 6524 "values": { 6525 "D": "Daily", 6526 "M": "Monthly", 6527 "Y": "Yearly" 6528 }, 6529 "description": "Available intervals to report on." 6530 } 6531 } 6532 } 6533
6534
6535 HTTP/1.1 200 Success 6536 Content-Type: application/json 6537 Content-Language: en 6539 { 6540 "description": "Matches and mis-matches according to the " 6541 "Yin Yang and Five Elements techniques", 6542 "details": "https://divine.example.com/manual/bazi-api", 6543 "parameters": { 6544 "birthday": { 6545 "type": "DATETIME", 6546 "description": "Your birth date and time in UTC" 6547 }, 6548 "targetDateBegin": { 6549 "type": "DATETIME", 6550 "description": "Start of the target date/time range to report on" 6551 }, 6552 "targetDateEnd": { 6553 "type": "DATETIME", 6554 "description": "End of the target date/time range to report on" 6555 }, 6556 "interval": { 6557 "values": { 6558 "H": "Hourly", 6559 "D": "Daily", 6560 "M": "Monthly", 6561 "Y": "Yearly" 6562 }, 6563 "description": "Available intervals to report on." 6564 } 6565 } 6566 } 6567
6568
Service Specification ObjectA service specification object MUST contain the following members. 6569
6570
6571 description 6572
6573
(string) A short, human-readable summary of the fortune heuristic 6574 service at this endpoint. This SHOULD be a stable reference.
6575
6576 details 6577
6578
(URI, optional) A URI reference that provides further details for 6579 human consumption, such as API documentation that includes details of 6580 parameters accepted or response states.
6581
6582 parameters 6583
6584
(object, mandatory) An object that specifies what parameters 6585 are accepted by this endpoint. Each parameter key within this object 6586 specifies an accepted parameter name, and its value is a parameter 6587 specification object, which is described below.
6588
6589 A parameter specification object SHOULD contain the following 6590 members: 6591
6592
6593 type 6594
6595
(string, optional) The value type accepted by this parameter. Value 6596 types are described in this document. This member is mutually 6597 exclusive with values.
6598
6599 description 6600
6601
(string, mandatory) The purpose of this parameter.
6602
6603 values 6604
6605
(object, optional) The accepted values of this parameter, unlisted 6606 values SHOULD not be accepted by the parameter. Each key within 6607 this object specifies an accepted value, and its value provides a 6608 description of the purpose of the value.
6609
6610
Fortune Heuristics Report Request and Response
Fortune Heuristics Report RequestA request using the HTTP "DIVINE" method and the "application/json" 6611 type MUST be sent to the fortune heuristic endpoint to retrieve 6612 results for a fortune heuristic query. 6613 The request made MUST conform to the specifications of the 6614 endpoint, as retrieved via the "SEEK" method described in 6615 . 6616 An example of a request is provided below. 6617
6618 URI: /divination/astrology 6619 Method: DIVINE 6620 Content-Type: application/json 6621 Content-Language: en 6623 { 6624 "birthday": "1976-02-11T00:00:00Z", 6625 "targetDateBegin": "2018-01-01T00:00:00Z", 6626 "targetDateEnd": "2019-01-01T00:00:00Z", 6627 "interval": "M" 6628 } 6629
6630
Fortune Heuristics Report ResponseA fortune heuristic query using the "DIVINE" method triggers a 6631 response that contains a fortune heuristics report. 6632 A successful response returns a JSON object that MUST conform 6633 to the object structure described in this section. 6634 A report object SHOULD contain the following members: 6635
6636
6637 type 6638
6639
(URI, mandatory) A URI that defines the type of the report located 6640 at the report key of this object.
6641
6642 report 6643
6644
(object, mandatory) An object that contains two keys, intervals 6645 and events. The intervals object contains an array of interval 6646 objects that matches the demanded intervals in the request within 6647 the target date range. 6648 The events object contains an array of significant event objects 6649 within the target date range.
6650
6651 An example of a response is provided below. 6652
6653 URI: /divination/astrology 6654 Method: DIVINE 6655 HTTP/1.1 200 Success 6656 Content-Type: application/json 6657 Content-Language: en 6659 { 6660 "type": "https://association-of.astrology/reports/monthly", 6661 "report": { 6662 "intervals": [ 6663 { 6664 "dateStart": "2018-01-01T00:00:00Z", 6665 "dateEnd": "2018-02-01T00:00:00Z", 6666 "categories": [ 6667 { 6668 "category": 6669 "https://divine.example.com/astrology/categories/health" 6670 "value": 80, 6671 "description": "Charge ahead with excellent health." 6672 }, 6673 { 6674 "category": 6675 "https://divine.example.com/astrology/categories/love" 6676 "value": 70, 6677 "description": 6678 "Give a certain person or situation another try!" 6679 }, 6680 { 6681 "category": 6682 "https://divine.example.com/astrology/categories/finance" 6683 "value": 5, 6684 "description": "You've just realized that you don't have 6685 any cash on hand." 6686 } 6687 ] 6688 }, 6689 { 6690 "dateStart": "2018-02-01T00:00:00Z", 6691 "dateEnd": "2018-03-01T00:00:00Z", 6692 "..." 6693 }, 6694 "..." 6695 ], 6696 "events": [ 6697 { 6698 "dateStart": "2018-01-15T03:20:00", 6699 "dateEnd": "2018-01-16T20:22:15", 6700 "description": "The planet of growth and good luck, Jupiter 6701 will make a harmonious connection with power planet Pluto, 6702 helping you connect with influential people", 6703 "recommendation": "Engage in networking during this time." 6704 }, 6705 { 6706 "dateStart": "2018-03-22T00:12:40", 6707 "dateEnd": "2018-03-28T02:45:03", 6708 "description": "Communication planet Mercury enters your sign, 6709 which will find you in a busier and chattier mood.", 6710 "recommendation": 6711 "Take charge of work with your newfound energy." 6712 } 6713 "..." 6714 ] 6715 } 6716 } 6717
6718 Fortune heuristic reports are created by a divination output that 6719 MAY requires quantitative interpretation. A sample representation of 6720 interpreting a graphical divination output is provided in 6721 . 6722
6723 Forty-nine yarrow sticks reveals a mystical message on fortune 6724 0000000000000000000000000 6725 0000000000000000000000001 G 1000000000000000000000000 6726 0000000000000000000000011 R 1100000000000000000000000 6727 0000000000000000000000111 A 1110000000000000000000000 6728 0000000000000000000001111 C 1111000000000000000000000 6729 0000000000000000000011111 E 1111100000000000000000000 6730 0000000000000000000111111 , 1111110000000000000000000 6731 0000000000000000001111111 1111111000000000000000000 6732 0000000011111111111111111 M 1111111111111111100000000 6733 0000000111111111111111111 E 1111111111111111110000000 6734 0000001111111111111111111 R 1111111111111111111000000 6735 0000011111111111111111111 C 1111111111111111111100000 6736 0000111111111111111111111 Y 1111111111111111111110000 6737 0001111111111111111111111 , 1111111111111111111111000 6738 0011111111111111111111111 1111111111111111111111100 6739 0111111111111111111111111 A 1111111111111111111111110 6740 0000000000000000011111111 N 1111111100000000000000000 6741 0000000000000000111111111 D 1111111110000000000000000 6742 0000000000000001111111111 1111111111000000000000000 6743 0000000000000011111111111 P 1111111111100000000000000 6744 0000000000000111111111111 E 1111111111110000000000000 6745 0000000000001111111111111 A 1111111111111000000000000 6746 0000000000011111111111111 C 1111111111111100000000000 6747 0000000000111111111111111 E 1111111111111110000000000 6748 0000000001111111111111111 . 1111111111111111000000000 6750
6751
Report Interval ObjectThe intervals value of a report object contains a number of report 6752 intervals — each representing a non-overlapping period of the 6753 selected interval length. When all of these intervals are put 6754 together, the combined period MUST fully cover the requested 6755 report target period. 6756 An example interval object is shown below. 6757
6758 { 6759 "dateStart": "2018-01-01T00:00:00Z", 6760 "dateEnd": "2018-02-01T00:00:00Z", 6761 "categories": [ 6762 { 6763 "category": 6764 "https://divine.example.com/astrology/categories/health" 6765 "value": 80, 6766 "description": "Charge ahead with your excellent health." 6767 }, 6768 { 6769 "category": 6770 "https://divine.example.com/astrology/categories/love" 6771 "value": 70, 6772 "description": "Give a certain person or situation another try!" 6773 }, 6774 { 6775 "category": 6776 "https://divine.example.com/astrology/categories/finance" 6777 "value": 5, 6778 "description": "You've just realized that you don't have 6779 any cash on hand." 6780 } 6781 ] 6782 } 6783
6784 An interval object MUST contain the following members: 6785
6786
6787 dateStart 6788
6789
(datetime, mandatory) This value specifies the start of the period 6790 which this interval object applies to.
6791
6792 dateEnd 6793
6794
(datetime, mandatory) This value specifies the end of the period 6795 which this interval object applies to.
6796
6797 In the given example, the categories key is an implementation 6798 specific object that details heuristic results returned by the 6799 selected algorithm. This MAY differ in different algorithms.
6800
Report Events ObjectThe events value of a report object contains a number of event 6801 objects. Each event object represents an event relevant to the 6802 calculation of fortune heuristics during a target report period. These 6803 events MAY be of variable time lengths, and MAY be overlapping 6804 amongst each other. 6805 The following example demonstrates two event objects the service 6806 determines relevant to a user’s query. 6807
6808 { 6809 "dateStart": "2018-01-15T03:20:00", 6810 "dateEnd": "2018-01-16T20:22:15", 6811 "description": "The planet of growth and good luck, Jupiter will 6812 make a harmonious connection with power planet Pluto, helping you 6813 connect with influential people", 6814 "recommendation": "Engage in networking during this time." 6815 }, 6816 { 6817 "dateStart": "2018-03-22T00:12:40", 6818 "dateEnd": "2018-03-28T02:45:03", 6819 "description": "Communication planet Mercury enters your sign, 6820 which will find you in a busier and chattier mood.", 6821 "recommendation": "Take charge of work with your newfound energy." 6822 } 6823
6824 Similar to an interval object, an event object MUST contain the 6825 following members: 6826
6827
6828 dateStart 6829
6830
(datetime, mandatory) This value specifies the start of the period 6831 described by the event.
6832
6833 dateEnd 6834
6835
(datetime, mandatory) This value specifies the end of the period 6836 described by the event.
6837
6838 In the given example, the keys description and recommendation 6839 are implementation-specific details. This MAY differ in different 6840 algorithms.
6841
Report Generation ErrorsThis specification makes use of normal HTTP error codes with the 6842 following extensions. 6843 Errors MUST be returned using the Problem JSON Structure as 6844 accordance with . 6845
6846
422 Unprocessable Entity
6847
For example, a malformed date-time parameter, or an illogical input, 6848 such as when the subject’s birthday occurs after the report target 6849 date period.
6850
473 Beyond Existing Capability
6851
The service determines that the outcome is too difficult to predict. 6852 For example, in the case where the calculation is too complex to 6853 complete in a certain time period. The service SHOULD issue this 6854 response code to indicate that the client should not try the same 6855 request again.
6856
474 Outcome Impossible
6857
The service determines that the outcome is impossible. For example, 6858 when the algorithm determines that the subject will have deceased 6859 before the start of the requested target period.
6860
6861
6862 Security Considerations 6863
    6864
  • TLS and authenticated HTTP requests should be used to 6865 protect the DIVINE request and responses due to the personal nature 6866 of information transmitted.
    • 6867
  • A client SHOULD verify the identity of the server on every 6868 request to prevent impersonation or man-in-the-middle attacks, as data 6869 transmitted to and from the server is sensitive information, and at 6870 times critical information to the user.
    • 6871
  • Synchronization of client and server time MUST be 6872 well-considered in the implementation of this specification. A 6873 mismatch of client and server time MAY lead to algorithm 6874 miscalculations that can cause mistaken choices of a user that depends 6875 on the reliability of this system.
    • 6876
6877
6878
6879 IANA Considerations 6880
Well-Known URI RegistrationsThis document defines a well-known URI using the registration 6881 procedure and template from . 6882
"fortune" Well-Known URI Registration
6883
URI suffix
6884
fortune
6885
Change controller
6886
IETF
6887
Specification document(s)
6888
This document
6889
Related information
6890
N/A.
6891
6893 6894
6895
6896 6897 6898 Normative References 6899 6900 6901 6902 6903 6904 6905 6906 6907 6908 Informative References 6909 6910 6911 ISO/DIS 8601-1:2018, Data elements and interchange 6912 formats -- Information interchange -- Representation of dates 6913 and times -- Part 1: Basic rules 6914 6915 ISO/IEC 6916
6917 http://www.iso.org 6918
6919 6920 6921 6922 6923 6924 6925 6926 6927
AcknowledgementsThe authors thank the following individuals for their valuable 6928 feedback on this specification, and commend them for making fortune 6929 heuristics more accessible for the benefit of mankind. 6931 6932
6933 6934 6935 6937 Appendix B. Acknowledgements 6939 The authors would like to thank the following persons for their 6940 valuable advice and input. 6942 o Adrian Farrel for his comprehensive review of the document and 6943 numerous beneficial suggestions. 6945 Authors' Addresses 6947 Ronald Henry Tse 6948 Ribose 6949 Suite 1111, 1 Pedder Street 6950 Central, Hong Kong 6951 Hong Kong 6953 Email: ronald.tse@ribose.com 6954 URI: https://www.ribose.com 6956 Nick Nicholas 6957 Ribose 6958 Australia 6960 Email: nick.nicholas@ribose.com 6961 URI: https://www.ribose.com 6963 Jeffrey Lau 6964 Ribose 6965 Suite 1111, 1 Pedder Street 6966 Central, Hong Kong 6967 Hong Kong 6969 Email: jeffrey.lau@ribose.com 6970 URI: https://www.ribose.com 6972 Paolo Brasolin 6973 Ribose 6974 Italy 6976 Email: paolo.brasolin@ribose.com 6977 URI: https://www.ribose.com