idnits 2.17.1 draft-ribose-asciirfc-06.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 52 instances of too long lines in the document, the longest one being 28 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 2219 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Orb' is mentioned on line 4595, but not defined -- Looks like a reference, but probably isn't: '124' on line 4595 -- Looks like a reference, but probably isn't: '135' on line 4595 == Unused Reference: 'I-D.camelot-holy-grenade' is defined on line 3485, but no explicit reference was found in the text == Outdated reference: A later version (-03) exists of draft-asciirfc-minimal-01 == 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 (==), 5 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-06 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 . . . . . . . . . . . . . . . 24 72 4.1. Title And Basic Attributes . . . . . . . . . . . . . . . 24 73 4.2. Detailed Author Information . . . . . . . . . . . . . . . 26 74 4.3. XML Processing Information . . . . . . . . . . . . . . . 31 75 4.4. AsciiRFC-specific Document Attributes . . . . . . . . . . 32 76 5. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 35 77 6. Sections and Paragraphs . . . . . . . . . . . . . . . . . . . 37 78 7. Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 79 8. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 80 8.1. Basic Lists . . . . . . . . . . . . . . . . . . . . . . . 44 81 8.2. List Continuation . . . . . . . . . . . . . . . . . . . . 50 82 9. Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . . 53 83 10. Notes And Asides . . . . . . . . . . . . . . . . . . . . . . 54 84 11. Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 85 12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . . 60 86 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts . 60 87 12.2. Formatting BCP 14 Keywords . . . . . . . . . . . . . . . 61 88 12.3. Escaping AsciiRFC Syntax . . . . . . . . . . . . . . . . 62 89 13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 90 14. Cross-References . . . . . . . . . . . . . . . . . . . . . . 64 91 14.1. Basic Referencing . . . . . . . . . . . . . . . . . . . 64 92 14.2. Referencing With Attributes . . . . . . . . . . . . . . 65 93 14.3. Indexing . . . . . . . . . . . . . . . . . . . . . . . . 66 94 15. Inclusions . . . . . . . . . . . . . . . . . . . . . . . . . 67 95 16. Encoding and Entities . . . . . . . . . . . . . . . . . . . . 68 96 17. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 70 97 17.1. Using Raw RFC XML . . . . . . . . . . . . . . . . . . . 71 98 17.2. Preprocessing Using "asciidoctor-bibliography" . . . . . 74 99 18. RFC XML features not supported in Asciidoctor . . . . . . . . 77 100 19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 77 101 19.1. Using the "rfc-asciirfc-minimal" template . . . . . . . 77 102 19.2. Installing AsciiRFC Backend Processors . . . . . . . . . 77 103 19.3. Iterating AsciiRFC Content . . . . . . . . . . . . . . . 78 104 20. Security Considerations . . . . . . . . . . . . . . . . . . . 78 105 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 106 22. References . . . . . . . . . . . . . . . . . . . . . . . . . 79 107 22.1. Normative References . . . . . . . . . . . . . . . . . . 79 108 22.2. Informative References . . . . . . . . . . . . . . . . . 79 109 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 82 110 A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" . . . . 82 111 A.1.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 83 112 A.1.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 89 113 A.2. Example 2: "The Holy Hand Grenade of Antioch" . . . . . . 93 114 A.2.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 93 115 A.2.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 111 116 A.3. Example 3: "An API For Calendar-Based Fortune Heuristics 117 Services" in AsciiRFC . . . . . . . . . . . . . . . . . . 127 118 A.3.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 128 119 A.4. Rendered as RFC XML v3 . . . . . . . . . . . . . . . . . 148 120 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 165 121 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 165 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-01 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 456 to 457 author Internet-Drafts and RFCs without needing to manually craft 458 RFC XML <>. 460 This is a template for authors to easily start with 461 <>. 463 [#conventions] 464 == Terms and Definitions 466 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 467 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 468 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this 469 document are to be interpreted as described in BCP 14 470 <> <> when, and only when, 471 they appear in 472 all capitals, as shown here. 474 //// 475 Note: do not break formatted strings over carriage return. Bad 476 things happen. (In this instance, the carriage return is 477 suppressed, and no space takes its place.) This is an 478 Asciidoctor issue, not an asciidoctor-rfc issue. 480 //// 482 [#symbols] 483 == Symbols And Abbreviations 485 [#operators] 486 === Operators 488 AsciiRFC:: 489 As defined in <>. 491 [#security] 492 == Security Considerations 494 * Please beware of implementation issues caused by 495 <>. 497 * Here's how you include references <>, 498 <>, <>. 500 [#iana] 501 == IANA Considerations 503 This document does not require any action by IANA. 505 [bibliography] 506 == Normative References 508 //bibliography::norm[] 509 ++++ 511 513 514 Key words for use in RFCs to Indicate Requirement 515 Levels 516 517 518 519 520 521 In many standards track documents several words are 522 used to signify the requirements in the specification. 523 These words are often capitalized. This document defines 524 these words as they should be interpreted in IETF 525 documents. This document specifies an Internet Best 526 Current Practices for the Internet Community, and 527 requests discussion and suggestions for improvements. 528 529 530 531 532 533 534 536 538 539 The "xml2rfc" Version 3 540 Vocabulary 541 542 543 544 545 546 This document defines the "xml2rfc" 547 version 3 vocabulary: an XML-based language used for 548 writing RFCs and Internet-Drafts. It is heavily derived 549 from the version 2 vocabulary that is also under 550 discussion. This document obsoletes the v2 grammar 551 described in RFC 7749. 552 553 554 555 556 558 560 561 Ambiguity of Uppercase vs Lowercase in RFC 2119 562 Key Words 563 564 565 566 567 568 RFC 2119 specifies common key words that may be 569 used in protocol specifications. This document aims to 570 reduce the ambiguity by clarifying that only UPPERCASE 571 usage of the key words have the defined special 572 meanings. 573 574 575 576 577 578 579 ++++ 581 [bibliography] 582 == Informative References 584 //bibliography::info[] 585 ++++ 587 589 590 RNP: A C library approach to OpenPGP 591 592 Ribose Inc. 593
594 595 Suite 1111, 1 Pedder Street 596 Central 597 Hong Kong 598 Hong Kong 599 600 open.source@ribose.com 601 https://www.ribose.com 602
603 604 605 606 608 609 610 611 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc 612 613 614 615 616 618 619 620 622 623 624 625 626 This document describes an AsciiDoc syntax 627 extension called AsciiRFC, designed for authoring IETF 628 Internet-Drafts and RFCs. AsciiDoc is a human readable document 629 markup language which affords more granular control over markup 630 than comparable schemes such as Markdown. The AsciiRFC syntax 631 is designed to allow the author to entirely focus on text, 632 providing the full power of the resulting RFC XML through the 633 AsciiDoc language, while abstracting away the need to manually 634 edit XML, including references. This document itself was 635 written and generated into RFC XML v2 (RFC7749) and RFC XML v3 636 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC 637 generator. 638 639 640 642 644 646 647 648 649 The SM4 Blockcipher Algorithm And Its Modes Of Operations 650 651 652 653 654 655 656 657 658 This document describes the SM4 symmetric 659 blockcipher 660 algorithm published as GB/T 32907-2016 by the State Cryptography 661 Administration of China (SCA). This document is a product of 662 the Crypto Forum Research Group (CFRG). 663 664 666 669 671 673 674 The OCB Authenticated-Encryption 675 Algorithm 676 677 678 679 680 681 682 683 This document specifies OCB, a shared-key 684 blockcipher-based encryption scheme that provides 685 confidentiality and authenticity for plaintexts and 686 authenticity for associated data. This document is a product 687 of the Crypto Forum Research Group 688 (CFRG). 689 690 691 692 693 ++++ 695 [appendix] 696 [#appendix-a] 697 == Examples 699 === Example 1 701 Here's an example. 703 [source,json] 704 ---- 705 { 706 "code": { 707 "encoding": "ascii", 708 "type": "rfc", 709 "authors": [ "Josiah Carberry", "Truman Grayson" ] 710 } 711 } 712 ---- 714 [#acknowledgements] 715 == Acknowledgements 716 The authors would like to thank their families. 717 719 Figure 1: Sample Internet-Draft in AsciiRFC 721 The first block of text, from "= Template For Writing An Internet- 722 Draft In AsciiRFC" through to ":email_2: thomas.kandell@brown.edu", 723 is the document header. It contains a title in the first line, an 724 author attribution ("Josiah Carberry; Thomas Kandell"), and then a 725 set of document attributes, conveying information about the document 726 as well as information about its authors. This information ends up 727 in RFC XML either as attributes of the root "rfc" tag, elements of 728 the "front" tag, or processing instructions. 730 The following blocks of text, up until the first section header ("== 731 Introduction"), are the document preamble. They are treated by the 732 document converter as containing the document abstract ("abstract"), 733 followed by any notes if present. 735 Section headers delimit the sections of the main body of the 736 document, starting with "== Introduction". The document converter 737 treats the first section of the document as the start of the "middle" 738 section in RFC XML. The first section header is followed by a 739 paragraph, and other sections and paragraphs. The number of "=" 740 signs can be one higher than that of the preceding section header, 741 which indicates that they are subsections of that section; so "=== 742 Operators" is a subsection of the preceding "== Symbols And 743 Abbreviations". 745 The paragraphs contain some inline formatting (e.g. boldface: 746 "*MUST*", monospace: "`type`"), and sections can also contain blocks 747 other than normal paragraphs; the section "== Operators", for 748 example, contains a definition list (whose terms are delimited by 749 "::"), and the subsection "=== Example 1" contains a code snippet 750 (delimited by "----", and tagged with the style attribute 751 "[source,json]", indicating that this is a JSON sourcecode listing). 752 The document can also include comments ("//" for inline, "////" for 753 blocks), which are not rendered when the document is processed. 755 The introductory section in this example contains a citation of a 756 reference, which in this version of AsciiRFC is treated identically 757 to a cross-reference ("<>") -- the crossreference being to 758 the references section of the document. Sections and blocks of texts 759 within the document can also be the target of crossreferences; for 760 example, the section header "=== Operators" is preceded by the anchor 761 "[#operators]", and that anchor is already referenced in the section 762 "== Security Considerations". 764 The third last and second last section are tagged with the style 765 attribute "[bibliography]", which identifies them as references 766 containers; the document converter accordingly inserts them into the 767 "back" element under RFC XML. The contents of the references 768 sections are in this instance raw XML, delimited as a passthrough 769 block (with "++++"), which the converter does not alter. 771 The final section is tagged with the style attribute "[appendix]", 772 and is treated as such. 774 The RFC XML v3 document generated from this AsciiRFC document is: 776 777 778 779 780 781 782 783 784 785 786 787 789 790 A Minimal Internet-Draft In 791 AsciiRFC 792 794 796 798 Brown University 799
800 801 Box K, 69 Brown Street 802 Providence 803 02912 804 United States of America 805 806 +1 401 863 1000 807 josiah.carberry@ribose.com 808 https://www.brown.edu 809
810 811 813 Brown University 814
815 816 Box G, 69 Brown Street 817 Providence 818 02912 819 United States of America 820 821 +1 401 863 1000 822 truman.grayson@ribose.com 823 https://www.brown.edu 824
825 826 827 Internet 829 830 This document provides a template on how to author (or 831 migrate!) 832 a new Internet-Draft / RFC in AsciiRFC format. This template 833 requires usage of the asciidoctor-rfc Ruby 834 gem. 835 836 837
IntroductionAsciiRFC 839 is an extremely simple way to 840 author Internet-Drafts and RFCs without needing to manually craft 841 RFC XML . 842 This is a template for authors to easily start with 843 .
844
845 Terms and Definitions 846 The key words "MUST", 847 "MUST NOT", 848 "REQUIRED", 849 "SHALL", 850 "SHALL NOT", 851 "SHOULD", "SHOULD 852 NOT", "RECOMMENDED", 853 "NOT RECOMMENDED", 854 "MAY", and 855 "OPTIONAL" in this 856 document are to be interpreted as described in BCP 14 857 when, and 858 only when, they appear in 859 all capitals, as shown here. 860
861
862 Symbols And Abbreviations 863
864 Operators 865
866
AsciiRFC
867
As defined in .
869
870
871
872
873 Security Considerations 874
    875
  • Please beware of implementation issues caused by .
    • 877
  • Here’s how you include references , 879 , .
    • 880
881
882
883 IANA Considerations 884 This document does not require any action by IANA. 885
886 887 888 Normative References 889 892 895 898 899 900 Informative References 901 903 904 RNP: A C library approach to OpenPGP 905 906 Ribose Inc. 907
908 909 Suite 1111, 1 Pedder Street 910 Central 911 Hong Kong 912 Hong Kong 913 914 open.source@ribose.com 915 https://www.ribose.com 916
917 918 919 920 921 924 927 930 931
932 Examples 933
Example 935 1Here’s an example. 936
937 { 938 "code": { 939 "encoding": "ascii", 940 "type": "rfc", 941 "authors": [ "Josiah Carberry", "Truman Grayson" ] 942 } 943 } 944
945
946
947 Acknowledgements 948 The authors would like to thank their families. 949
950 951 952 954 Figure 2: Sample Internet-Draft In AsciiRFC, Output In RFC XML v3 955 Format 957 Some default processing instructions have already been prefixed to 958 the XML. 960 Our AsciiRFC converter can also generate RFC XML v2 from the same 961 source AsciiRFC, as shown in Figure 3. Output in RFC XML v2 is not 962 extensively described in this document. 964 965 966 967 970 972 974 976 978 980 ]> 981 982 983 984 985 986 987 988 990 991 A Minimal Internet-Draft In 992 AsciiRFC 993 995 Brown University 996
997 998 Box K, 69 Brown Street 999 Providence 1000 02912 1001 United States of America 1002 1003 +1 401 863 1000 1004 josiah.carberry@ribose.com 1005 https://www.brown.edu 1006
1007 1008 1010 Brown University 1011
1012 1013 Box G, 69 Brown Street 1014 Providence 1015 02912 1016 United States of America 1017 1018 +1 401 863 1000 1019 truman.grayson@ribose.com 1020 https://www.brown.edu 1021
1022 1023 1024 Internet 1026 1027 This document provides a template on how to author (or 1028 migrate!) 1029 a new Internet-Draft / RFC in AsciiRFC format. This template 1030 requires usage of the asciidoctor-rfc Ruby gem. 1032 1033 1034
AsciiRFC is an extremely simple way to 1037 author Internet-Drafts and RFCs without needing to manually craft 1038 RFC XML . 1039 This is a template for authors to easily start with 1040 .
1041
1042 The key words "MUST", "MUST 1044 NOT", "REQUIRED", "SHALL", 1047 "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", 1051 "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this 1054 document are to be interpreted as described in BCP 14 1055 when, and 1056 only when, they appear in 1057 all capitals, as shown here. 1058
1059
1060
1061 1062 1063 As 1064 defined in . 1065 1066 1067
1068
1069
1070 1071 1072 Please beware of implementation issues caused by . 1074 Here’s how you include references , 1076 , . 1077 1078 1079
1080
1081 This document does not require any action by IANA. 1082
1083 1084 1085 &RFC2119; 1086 &RFC7991; 1087 &RFC8174; 1088 1089 1090 1092 1093 RNP: A C library approach to OpenPGP 1094 1095 Ribose Inc. 1096
1097 1098 Suite 1111, 1 Pedder Street 1099 Central 1100 Hong Kong 1101 Hong Kong 1102 1103 open.source@ribose.com 1104 https://www.ribose.com 1105
1106 1107 1108 1109 1110 &I-D.ribose-asciirfc; 1111 &I-D.ribose-cfrg-sm4; 1112 &RFC7253; 1113 1114
1115
Here’s an example. 1117
1118 { 1119 "code": { 1120 "encoding": "ascii", 1121 "type": "rfc", 1122 "authors": [ "Josiah Carberry", "Truman Grayson" ] 1123 } 1124 } 1125
1126
1127
1128 The authors would like to thank their families. 1129
1130 1131 1132 1134 Figure 3: Sample Internet-Draft In AsciiRFC, Output In RFC XML v2 1135 Format 1137 4. Header And Document Attributes 1139 The header gives the document title, followed by an optional author 1140 attribution, and a series of document attributes, with no empty 1141 lines. 1143 4.1. Title And Basic Attributes 1145 Document attributes are used to populate attributes of the root "rfc" 1146 element, "front" elements, and document-level processing 1147 instructions. 1149 o ":doctype:" determines whether the document will be considered 1150 "rfc" or "internet-draft", and interprets other attributes 1151 accordingly. 1153 o Certain attributes ("workgroup", "area", "keyword") are comma 1154 delimited, and result in repeated RFC XML elements. 1156 Figure 4 demonstrates how to set the document header in AsciiRFC, 1157 with its rendering in RFC XML v3 shown in Figure 5. 1159 1160 = The Holy Hand Grenade of Antioch 1161 Arthur son of Uther Pendragon 1162 :doctype: internet-draft 1163 :abbrev: Hand Grenade of Antioch 1164 :updates: 8140 1165 :submission-type: independent 1166 :name: draft-camelot-holy-grenade-00 1167 :status: informational 1168 :consensus: false 1169 :area: General, Operations and Management 1170 :keyword: rabbits, grenades, antioch, camelot 1171 :ipr: trust200902 1172 :toc-include: true 1173 :sort-refs: true 1174 :revdate: 2018-04-01 1175 1177 Figure 4: AsciiRFC Document Header 1179 1180 1184 1185 The Holy Hand Grenade of 1186 Antioch 1187 1189 1191 Camelot 1192
1193 1194 Palace 1195 Camel Lot 1 1196 Camelot 1197 antioch 1199 1200 1202 1204 Figure 5: AsciiRFC Document Header Rendered As RFC XML v3 1206 4.2. Detailed Author Information 1208 The document header can spell out further information about authors, 1209 including contact details. The AsciiRFC header is shown in Figure 6 1210 with its rendering in RFC XML v3 shown in Figure 7. 1212 1213 = The Holy Hand Grenade of Antioch 1214 Arthur son of Uther Pendragon 1215 :doctype: internet-draft 1216 :abbrev: Hand Grenade of Antioch 1217 :updates: 8140 1218 :submission-type: independent 1219 :name: draft-camelot-holy-grenade-00 1220 :status: informational 1221 :consensus: false 1222 :area: General, Operations and Management 1223 :keyword: rabbits, grenades, antioch, camelot 1224 :ipr: trust200902 1225 :toc-include: true 1226 :sort-refs: true 1227 :revdate: 2018-04-01 1228 :fullname: Arthur son of Uther Pendragon 1229 :forename_initials: A. 1230 :lastname: Pendragon 1231 :email: arthur.pendragon@ribose.com 1232 :organization: Camelot 1233 :uri: http://camelot.gov.example 1234 :street: Palace\ Camel Lot 1 1235 :city: Camelot 1236 :country: England 1237 :comments: yes 1238 1240 Figure 6: AsciiRFC Document Header With One Author 1242 1243 1247 1248 The Holy Hand Grenade of 1249 Antioch 1250 1252 1254 Camelot 1255
1256 1257 Palace 1258 Camel Lot 1 1259 Camelot 1260 England 1261 1262 arthur.pendragon@ribose.com 1263 http://camelot.gov.example 1264
1265 1266 1267 General 1268 Operations and Management 1269 rabbits 1270 grenades 1271 antioch 1272 camelot 1274 1275 1277 1279 Figure 7: AsciiRFC Document Header With One Author (RFC XML v3) 1281 Details of a second, third etc. author, including their organization 1282 and contact details, are provided by suffixing the relevant author 1283 attributes with "_2", "_3" etc., as shown in Figure 8 and its RFC XML 1284 v3 rendering Figure 9. 1286 1287 = An API For Calendar-Based Fortune Heuristics Services 1288 Gabriel Destiny; Charise Luck 1289 :doctype: internet-draft 1290 :abbrev: Calendar Fortune Heuristics API 1291 :name: draft-divination-cfapi-00 1292 :status: informational 1293 :ipr: trust200902 1294 :area: Internet 1295 :submission-type: independent 1296 :intended-series: informational 1297 :revdate: 2018-03-23T00:00:00Z 1298 :lastname: Destiny 1299 :fullname: Gabriel Destiny 1300 :forename_initials: G. 1301 :organization: Divination Inc. 1302 :email: gabriel.destiny@ribose.com 1303 :street: 9288 N Divine Street 1304 :city: Dunn 1305 :code: 28334 1306 :region: NC 1307 :country: United States of America 1308 :lastname_2: Luck 1309 :fullname_2: Charise Luck 1310 :forename_initials_2: C. 1311 :organization_2: Divination Inc. 1312 :email_2: charise.luck@ribose.com 1313 :street_2: 9288 N Divine Street 1314 :city_2: Dunn 1315 :code_2: 28334 1316 :region_2: NC 1317 :country_2: United States of America 1318 1320 Figure 8 1322 1323 1326 1327 An API For 1328 Calendar-Based Fortune Heuristics Services 1329 1331 1333 1335 Divination Inc. 1336
1337 1338 9288 N Divine Street 1339 Dunn 1340 NC 1341 28334 1342 United States of America 1343 1344 gabriel.destiny@ribose.com 1345
1346 1347 1348 Divination Inc. 1349
1350 1351 9288 N Divine Street 1352 Dunn 1353 NC 1354 28334 1355 United States of America 1356 1357 charise.luck@ribose.com 1358
1359 1360 1361 Internet 1363 1364 1366 1368 Figure 9: AsciiRFC Document Header With Multiple Authors (RFC XML v3) 1369 The initial author attribution in AsciiRFC, e.g. "Gabriel Destiny; 1370 Charlise Luck" in the example above, expects a strict format of First 1371 Name, zero or more Middle Names, Last name, and cannot process 1372 honorifics like "Dr." or suffixes like "Jr.". 1374 Name attributes with any degree of complexity should be overriden by 1375 using the ":fullname:" and ":lastname:" attributes. The AsciiRFC 1376 ":forename_initials:" attribute replaces the built-in Asciidoctor 1377 syntax ":initials:" attribute (which includes the surname initial), 1378 and is not automatically populated from the name attribution. 1380 4.3. XML Processing Information 1382 A document header may also contain attribute headers which are 1383 treated as XML processing instructions. An AsciiRFC example is shown 1384 in Figure 10 with its rendering in Figure 11. (Note that several 1385 processing instructions are included by default in the output of the 1386 AsciiRFC processor.) 1388 1389 = The Holy Hand Grenade of Antioch 1390 Arthur son of Uther Pendragon 1391 :doctype: internet-draft 1392 :abbrev: Hand Grenade of Antioch 1393 :updates: 8140 1394 :submission-type: independent 1395 :name: draft-camelot-holy-grenade-00 1396 :status: informational 1397 :consensus: false 1398 :ipr: trust200902 1399 :notedraftinprogress: yes 1400 :smart-quotes: false 1401 1403 Figure 10: AsciiRFC Document Header With XML Processing Information 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1422 1423 The Holy Hand Grenade of 1424 Antioch 1425 1427 1429 Camelot 1430
1431 1432 Palace 1433 Camel Lot 1 1434 Camelot 1435 antioch 1436 1438 Figure 11: AsciiRFC Document Header With XML Processing Information 1439 (RFC XML v3) 1441 In the foregoing, values for the processing instructions "strict", 1442 "compact", "toc" etc are included by default; but "comments" and 1443 "notedraftinprogress" are included as specified in the AsciiRFC 1444 document header. The default values provided for processing 1445 instructions can in fact be overriden through the AsciiRFC document 1446 header. 1448 4.4. AsciiRFC-specific Document Attributes 1450 A few document attributes are specific to the operation of the RFC 1451 XML document converter: 1453 :no-rfc-bold-bcp14: false 1454 overrides the wrapping by default of boldface uppercase BCP14 1455 [RFC2119] words (e.g. "*MUST NOT*") with the "bcp14" element. 1457 :smart-quotes: false 1458 overrides Asciidoctor's conversion of straight quotes and 1459 apostrophes to smart quotes and apostrophes. 1461 :inline-definition-lists: true 1462 overrides the RFC XML v2 "idnits" requirement that a blank line be 1463 inserted between a definition list term and its definition. 1465 1466 = The Holy Hand Grenade of Antioch 1467 Arthur son of Uther Pendragon 1468 :doctype: internet-draft 1469 :status: informational 1470 :name: draft-camelot-holy-grenade-00 1472 == Section 1 1473 The specification *MUST NOT* use the word _doesn't_. 1474 1476 Figure 12: AsciiRFC Document Header Without RFC-specific Attributes 1478 1479 1481 1482 The Holy Hand Grenade of Antioch 1483 1485 1488 1489 1490 1491 1492
1493 Section 1 1494 The specification MUST NOT 1495 use the word doesn’t. 1496
1497 1498 1499 1501 Figure 13: AsciiRFC Document Header Without RFC-specific Attributes 1502 (RFC XML v3) 1504 1505 = The Holy Hand Grenade of Antioch 1506 Arthur son of Uther Pendragon 1507 :doctype: internet-draft 1508 :status: informational 1509 :name: draft-camelot-holy-grenade-00 1510 :no-rfc-bold-bcp14: false 1511 :smart-quotes: false 1513 == Section 1 1514 The specification *MUST NOT* use the word _doesn't_. 1515 1517 Figure 14: AsciiRFC Document Header With Overridden RFC-specific 1518 Attributes 1520 1521 1523 1524 The Holy Hand Grenade of Antioch 1525 1527 1530 1531 1532 1533 1534
1535 Section 1 1536 The specification MUST NOT 1537 use the word doesn't. 1538
1539 1540 1541 1543 Figure 15: AsciiRFC Document Header With Overridden RFC-specific 1544 Attributes (RFC XML v3) 1546 5. Preamble 1548 The preamble in AsciiRFC is the text between the end of the document 1549 header (which terminates with a blank line) and the first section of 1550 text. 1552 Any paragraphs of text in the preamble are treated as an abstract, 1553 and may optionally be tagged with the "abstract" style attribute. 1555 Any notes in the preamble are treated as a "note" element. 1557 An example of setting the preamble is given in Figure 16 with its 1558 rendering in Figure 17. 1560 1562 [abstract] 1563 The menagerie of beasts and artefacts depicted in RFC8140 1564 may be usefully supplemented by other renowned figures of 1565 Internet and more general lore. This document extends the 1566 menagerie to the seminal fable of the 1567 "Holy Hand Grenade of Antioch", as depicted in the 1568 Monty Python film "Monty Python and the Holy Grail", 1569 as well as "Spamalot", the musical inspired by the movie. 1571 [NOTE,remove-in-rfc=false] 1572 .Spamalot 1573 The relevance of the musical "Spamalot" to Internet lore should be 1574 obvious to the reader; but in case of doubt, see also 1575 Section 1 ("What is Spam*?") of RFC2635. 1577 1579 Figure 16: AsciiRFC With Preamble 1581 1582 1584 The menagerie of beasts and artefacts depicted in RFC8140 1585 may be usefully supplemented by other renowned figures of 1586 Internet and more general lore. This document extends the 1587 menagerie to the seminal fable of the 1588 "Holy Hand Grenade of Antioch", as depicted in the 1589 Monty Python film "Monty Python and the Holy Grail", 1590 as well as "Spamalot", the musical inspired by the 1591 movie. 1592 Spamalot 1593 The relevance of the musical "Spamalot" to Internet lore 1594 should be 1595 obvious to the reader; but in case of doubt, see also 1596 Section 1 ("What is Spam*?") of RFC2635. 1597 1599 1600 1602 Figure 17: AsciiRFC With Preamble (RFC XML v3) 1604 6. Sections and Paragraphs 1606 Section headers are given with a sequence of "=", where the number of 1607 instances of "=" gives the header level. The document itself opens 1608 with a single "=", and sections within it must be started with a 1609 minimum of "==". 1611 Section numbering is toggled with the in-document attribute 1612 ":sectnums:" (on), ":sectnums!:" (off). The boolean "toc" attribute 1613 can also be set on sections, indicating whether the section can be 1614 included in the document's table of contents. 1616 Figure 18 shows how sections and paragraphs are used in AsciiRFC, and 1617 its rendered form is shown in Figure 19. 1619 1621 [toc=exclude] 1622 :sectnums!: 1623 == Terminology 1625 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 1626 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 1627 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 1628 are to be interpreted as described in BCP 14 <> 1629 <> 1630 when, and only when, they appear in all capitals, as shown here. 1632 :sectnums: 1633 == Introduction 1635 <> refers to the intended move of RFC formatting to 1636 XML2RFC v3 <>, in the following terms: 1638 1640 Figure 18: AsciiRFC With Sections 1642 1644 1645
1646 Terminology 1647 The key words "MUST", 1648 "MUST NOT", 1649 "REQUIRED", 1650 "SHALL", 1651 "SHALL NOT", 1652 "SHOULD", "SHOULD 1653 NOT", "RECOMMENDED", 1654 "NOT RECOMMENDED", 1655 "MAY", and 1656 "OPTIONAL" in this document 1657 are to be interpreted as described in BCP 14 1659 when, and only when, they appear in all capitals, as shown 1660 here. 1661
1662
Introduction refers to the intended move of RFC formatting to 1665 XML2RFC v3 , in the following 1666 terms: 1668 1670 Figure 19: AsciiRFC With Sections (RFC XML v3) 1672 Note that skipped sections, such as defining a section using "====" 1673 within a section defined using "==", is not allowed in AsciiRFC 1674 syntax. Doing so will trigger an error with the following message: 1676 asciidoctor: WARNING: _filename_: line _X_: 1677 section title out of sequence: expected level 2, got level 3 1679 7. Figures 1681 AsciiRFC examples (corresponding to RFC XML Figures), source code 1682 Listings, and Literals (preformatted text) are all delimited blocks. 1683 Listings and Literals can occur nested within Examples. 1685 An AsciiRFC example with a figure is given in Figure 20, and its 1686 rendering in Figure 21. 1688 1690 [[killer-bunny]] 1691 .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 1692 ==== 1693 [alt=The Killer Bunny, in ASCII] 1694 .... 1695 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1696 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1697 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 1698 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 1699 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 1700 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 1701 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 1702 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 1703 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 1704 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 1705 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 1706 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 1707 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 1708 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 1709 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 1710 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 1711 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 1712 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 1713 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 1714 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 1715 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 1716 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 1717 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 1718 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 1719 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 1720 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 1721 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 1722 MW \\/\||v v|| -\\-------___ . ., \ | 1723 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 1724 ) /--------^-^ ,. \|// 1725 # \(/ .\\|x// " ' ' 1726 . , \\||// \||\\\// \\ 1727 .... 1728 ==== 1730 [[killer-source]] 1731 .C Code To Lure Killer Rabbit Back To Cave 1732 ==== 1733 [source,c] 1734 ---- 1735 1736 /* Locate the Killer Rabbit */ 1737 int type; 1738 unsigned char *killerRabbit = 1739 LocateCreature(&caerbannog, "killer rabbit"); 1740 if( killerRabbit == 0 ){ 1741 puts("The Killer Rabbit of Caerbannog is out of town."); 1742 return LOST_CREATURE; 1743 } 1745 /* Load Cave */ 1746 unsigned char *cave = LoadPlace(&caerbannog, 1747 "The Cave Of Caerbannog"); 1748 if( cave == 0 ){ 1749 puts("The Cave of Caerbannog must have moved."); 1750 return LOST_PLACE; 1751 } 1753 /* Lure the Killer Rabbit back into the Cave */ 1754 unsigned char *carrot = allocateObjectInPlace( 1755 carrot("fresh"), cave); 1756 if( carrot == 0 ){ 1757 puts("No carrot, no rabbit."); 1758 return LOST_LURE; 1759 } 1761 /* Finally, notify the Killer Rabbit to act */ 1762 return notifyCreature(killerRabbit, &carrot); 1763 1764 ---- 1765 ==== 1767 1769 Figure 20: AsciiRFC With A Figure 1771 1773
1774 A Photo Of The Killer Rabbit of Caerbannog Taken In 1775 Secret 1776 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1778 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 1779 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 1780 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 1781 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 1782 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 1783 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ 1784 \MWMWMWMW##\\\\\\\ 1785 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 1786 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 1787 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 1788 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 1789 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 1790 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 1791 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 1792 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 1793 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 1794 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 1795 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 1796 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 1797 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 1798 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 1799 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 1800 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 1801 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 1802 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 1803 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 1804 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 1805 MW \\/\||v v|| -\\-------___ . ., \ | 1806 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 1807 ) /--------^-^ ,. \|// 1808 # \(/ .\\|x// " ' ' 1809 . , \\||// \||\\\// \\ 1810
1811
1812 C Code To Lure Killer Rabbit Back To Cave 1813 <CODE BEGINS> 1814 /* Locate the Killer Rabbit */ 1815 int type; 1816 unsigned char *killerRabbit = 1817 LocateCreature(&caerbannog, "killer rabbit"); 1818 if( killerRabbit == 0 ){ 1819 puts("The Killer Rabbit of Caerbannog is out of town."); 1820 return LOST_CREATURE; 1821 } 1823 /* Load Cave */ 1824 unsigned char *cave = LoadPlace(&caerbannog, 1825 "The Cave Of Caerbannog"); 1826 if( cave == 0 ){ 1827 puts("The Cave of Caerbannog must have moved."); 1828 return LOST_PLACE; 1829 } 1831 /* Lure the Killer Rabbit back into the Cave */ 1832 unsigned char *carrot = allocateObjectInPlace( 1833 carrot("fresh"), cave); 1834 if( carrot == 0 ){ 1835 puts("No carrot, no rabbit."); 1836 return LOST_LURE; 1837 } 1839 /* Finally, notify the Killer Rabbit to act */ 1840 return notifyCreature(killerRabbit, &carrot); 1841 <CODE ENDS> 1842
1844 1846 Figure 21: AsciiRFC With A Figure (RFC XML v3) 1848 If an AsciiRFC Listing or Literal occurs outside of an Example 1849 (Figure 22), the RFC XML converter will supply the surrounding 1850 Figure element (Figure 23). 1852 1854 [[hand-grenade-figure]] 1855 .The Holy Hand Grenade of Antioch (don't pull the pin) 1857 Figure 22: AsciiRFC With ASCII Art Without Figure Wrapping 1859 ______ 1860 \\/ \/ 1861 __\\ /__ 1862 || //\ | 1863 ||__\\/ __| 1864 || | ,---, 1865 || |====`\ | 1866 || | '---' 1867 ,--'*`--, 1868 _||#|***|#| 1869 _,/.-'#|* *|#`-._ 1870 ,,-'#####| |#####`-. 1871 ,,'########| |########`, 1872 //##########| o |##########\ 1873 ||###########| |###########| 1874 ||############| o |############| 1875 ||------------' '------------| 1876 ||o o o o o o o o o o| 1877 |-----------------------------| 1878 ||###########################| 1879 \\#########################/ 1880 `..#####################,' 1881 ``..###############_,' 1882 ``--.._____..--' 1883 `''-----''` 1885 1886 1888
1889 The Holy Hand Grenade of Antioch (don't pull the 1890 pin) 1891 1892 ______ 1893 \\/ \/ 1894 __\\ /__ 1895 || //\ | 1896 ||__\\/ __| 1897 || | ,---, 1898 || |====`\ | 1899 || | '---' 1900 ,--'*`--, 1901 _||#|***|#| 1902 _,/.-'#|* *|#`-._ 1903 ,,-'#####| |#####`-. 1904 ,,'########| |########`, 1905 //##########| o |##########\ 1906 ||###########| |###########| 1907 ||############| o |############| 1908 ||------------' '------------| 1909 ||o o o o o o o o o o| 1910 |-----------------------------| 1911 ||###########################| 1912 \\#########################/ 1913 `..#####################,' 1914 ``..###############_,' 1915 ``--.._____..--' 1916 `''-----''` 1917
1919 1921 Figure 23: AsciiRFC With ASCII Art Without Figure Wrapping (RFC XML 1922 v3) 1924 8. Lists 1926 8.1. Basic Lists 1928 AsciiRFC supports ordered, unordered, and definition lists. 1929 Indentation of ordered and unordered lists is indicated by repeating 1930 the list item prefix ("*" and "." respectively); for definition 1931 lists, it is indicated by incrementing the number of definition term 1932 delimiters ("::"). 1934 List attributes can be used to specify the type of symbol used for 1935 ordered lists. 1937 An example of an unordered list is shown in Figure 24 (with its 1938 rendered version in Figure 25). An example of an ordered list with 1939 ordered and unordered sublists is shown in Figure 26 (with its 1940 rendered version in Figure 27). An example of a definition list is 1941 shown in Figure 28 (with its rendered version in Figure 29). 1943 1945 * Killed 1946 ** Sir Bors 1947 ** Sir Gawain 1948 ** Sir Ector 1949 * Soiled Himself 1950 ** Sir Robin 1951 * Panicked 1952 ** King Arthur 1953 * Employed Ordnance 1954 ** The Lector 1955 ** Brother Maynard 1956 * Scoffed 1957 ** Tim the Enchanter 1959 1961 Figure 24: AsciiRFC With Unordered lists 1963 1965
    1966
  • 1967 Killed 1968
      1969
    • Sir Bors
      • 1970
    • Sir Gawain
      • 1971
    • Sir Ector
      • 1972
    1973
    • 1974
  • 1975 Soiled Himself 1976
      1977
    • Sir Robin
      • 1978
    1979
    • 1980
  • 1981 Panicked 1982
      1983
    • King Arthur
      • 1984
    1985
    • 1986
  • 1987 Employed Ordnance 1988
      1989
    • The Lector
      • 1990
    • Brother Maynard
      • 1991
    1992
    • 1993
  • 1994 Scoffed 1995
      1996
    • Tim the Enchanter
      • 1997
    1998
    • 1999
2001 2003 Figure 25: AsciiRFC With Unordered Lists (RFC XML v3) 2005 2007 . Preamble: St Attila Benediction 2008 . Feast of the People on Sundry Foods 2009 ** Lambs 2010 ** Sloths 2011 ** Carp 2012 ** Anchovies 2013 ** Orangutangs 2014 ** Breakfast Cereals 2015 ** Fruit Bats 2016 ** _et hoc genus omne_ 2017 . Take out the Holy Pin 2018 . The Count 2019 [upperalpha] 2020 .. Count is to Three: no more, no less 2021 .. Not Four 2022 .. Nor Two, except if the count then proceeds to Three 2023 .. Five is Right Out 2024 . Lob the Holy Hand Grenade of Antioch towards the Foe 2025 . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it 2027 2029 Figure 26: AsciiRFC With Ordered lists 2031 2033
    2034
  1. Preamble: St Attila Benediction
    2. 2035
  2. 2036 Feast of the People on Sundry Foods 2037
      2038
    • Lambs
      • 2039
    • Sloths
      • 2040
    • Carp
      • 2041
    • Anchovies
      • 2042
    • Orangutangs
      • 2043
    • Breakfast Cereals
      • 2044
    • Fruit Bats
      • 2045
    • 2046 et hoc genus omne 2047
      • 2048
    2049
    3. 2050
  3. Take out the Holy Pin
    4. 2051
  4. 2052 The Count 2053
      2054
    1. Count is to Three: no more, no less
      2. 2055
    2. Not Four
      3. 2056
    3. Nor Two, except if the count then proceeds to 2057 Three
      4. 2058
    4. Five is Right Out
      5. 2059
    2060
    5. 2061
  5. Lob the Holy Hand Grenade of Antioch towards the 2062 Foe
    6. 2063
  6. The Foe, being naughty in the 2064 LORD's sight, 2065 SHALL snuff it
    7. 2066
2068 2070 Figure 27: AsciiRFC With Ordered Lists (RFC XML v3) 2072 2074 Holy Hand Grenade of Antioch:: 2075 Ordnance deployed by Brother Maynard under the incantation of a 2076 lector, in order to dispense with the Foes of the Virtuous. 2077 See <>. 2079 Holy Spear of Antioch:: 2080 A supposed relic of the crucifixion of Jesus Christ, this is one 2081 of at least four claimed instances of the lance that pierced 2082 Christ's side. Its historical significance lies in inspiring 2083 crusaders to continue their siege of Antioch in 1098. 2085 Sovereign's Orb of the United Kingdom:: 2086 Part of the Crown Jewels of the United Kingdom, the Sovereign's 2087 Orb is a hollow gold sphere set with jewels and topped with a 2088 cross. It was made for Charles II in 1661. See 2089 <>. 2091 2093 Figure 28: AsciiRFC With Definition lists 2095 2097
2098
Holy Hand Grenade of Antioch
2099
Ordnance deployed by Brother Maynard under the incantation 2100 of a 2101 lector, in order to dispense with the Foes of the Virtuous. 2102 See .
2103
Holy Spear of Antioch
2104
A supposed relic of the crucifixion of Jesus Christ, this is 2105 one 2106 of at least four claimed instances of the lance that pierced 2107 Christ's side. Its historical significance lies in inspiring 2108 crusaders to continue their siege of Antioch in 1098.
2109
Sovereign's Orb of the United Kingdom
2110
Part of the Crown Jewels of the United Kingdom, the 2111 Sovereign's 2112 Orb is a hollow gold sphere set with jewels and topped with a 2113 cross. It was made for Charles II in 1661. See .
2115
2117 2119 Figure 29: AsciiRFC With Definition Lists (RFC XML v3) 2121 8.2. List Continuation 2123 A list item by default spans a single paragraph. A following 2124 paragraph or other block element can be appended to the current list 2125 item by prefixing it with "+" in a separate line. 2127 See the "List Continuation" section in [Asciidoctor-Manual] for more 2128 information. 2130 An example of list continuation with text is shown in Figure 30 with 2131 its rendered version in Figure 31. 2133 2135 Trojan Rabbit:: 2136 In their siege of the French-occupied castle which may already 2137 contain an instance of the Grail, Sir Bedevere the Wise proposes to 2138 use a Trojan Rabbit to infiltrate the castle, with a raiding party 2139 to take the French "not only by surprise, but totally unarmed." 2140 + 2141 The proposal, unsurprisingly, proved abortive. The more so as the 2142 raiding party forgot to hide within the Trojan Rabbit, before the 2143 French soldiers took the Trojan Rabbit inside the castle. 2145 Killer Rabbit of Caerbannog:: 2146 Guarding the entrance to the Cave of Caerbannog; see 2147 <>. 2149 2151 Figure 30: AsciiRFC List With Text Continuation 2153 2155
2156
Trojan Rabbit
2157
2158 In their siege of the French-occupied castle which may 2159 already 2160 contain an instance of the Grail, Sir Bedevere the Wise proposes to 2161 use a Trojan Rabbit to infiltrate the castle, with a raiding party 2162 to take the French "not only by surprise, but totally 2163 unarmed." 2164 The proposal, unsurprisingly, proved abortive. The more so 2165 as the 2166 raiding party forgot to hide within the Trojan Rabbit, before the 2167 French soldiers took the Trojan Rabbit inside the castle. 2168
2169
Killer Rabbit of Caerbannog
2170
Guarding the entrance to the Cave of Caerbannog; see 2171 .
2172
2174 2176 Figure 31: AsciiRFC List With Text Continuation (RFC XML v3) 2178 (Multiple paragraphs are not permitted within a list item in RFC XML 2179 v2. The RFC XML converter deals with this by converting paragraph 2180 breaks into line breaks within a list item.) 2182 List continuations can also be embedded to populate a list item with 2183 a sequence of blocks as a unit (in an Asciidoctor syntax open block). 2185 An example of list continuation with a delimited block is shown in 2186 Figure 32 with its rendered version in Figure 33. 2188 2190 . Take out the Holy Pin 2191 . The Count 2192 + 2193 ---- 2194 integer count; 2195 for count := 1 step 1 until 3 do 2196 say(count) 2197 comment Five is Right Out 2198 ---- 2199 . Lob the Holy Hand Grenade of Antioch towards the Foe 2200 . Foe snuffs it 2202 2204 Figure 32: AsciiRFC List With Block Continuation 2206 2208
    2209
  1. Take out the Holy Pin
    2. 2210
  2. 2211 The Count 2212
    2213 integer count; 2214 for count := 1 step 1 until 3 do 2215 say(count) 2216 comment Five is Right Out 2217
    2218
    3. 2219
  3. Lob the Holy Hand Grenade of Antioch towards the 2220 Foe
    4. 2221
  4. Foe snuffs it
    5. 2222
2224 2226 Figure 33: AsciiRFC List With Block Continuation (RFC XML v3) 2228 AsciiDoc, and thus AsciiRFC, considers paragraphs to be the basic 2229 level of blocks, and does not permit lists to be nested within them: 2230 any text after a list is considered to be a new paragraph. 2232 Therefore, markup as shown in Figure 34 cannot be generated via 2233 AsciiRFC. 2235 2236 2237 This is the start of a paragraph. 2238
    2239
  • List Entry 1
    • 2240
  • 2241 List Entry 2 2242 Note 2. 2243
    • 2244
2245 And this is the continuation of the paragraph. 2246 2247 2249 Figure 34: This RFC XML v3 Output Cannot Be Generated Using AsciiRFC 2251 9. Blockquotes 2253 Asciidoctor syntax supports blockquotes and quotations of verse; its 2254 block quotations permit arbitrary levels of quote nesting. RFC XML 2255 v3, and thus AsciiRFC, only supports one level of blockquotes. 2257 Unlike RFC XML v2, RFC XML v3 does not support line breaks outside of 2258 tables, so verse quotations are converted to prose in the v3 2259 converter. 2261 An example of using AsciiRFC Blockquotes is given in Figure 35 with 2262 its rendered version in Figure 36. 2264 2266 [quote,attribution="A. Farrel"] 2267 ____ 2268 Although the RFC Editor has recently dragged the IETF kicking and 2269 screaming into the twentieth century [RFC7990] [RFC7996], there is a 2270 yearning among all right-thinking Internet architects to "keep it 2271 simple" and to return to the olden days when pigs could be given 2272 thrust without anyone taking undue offence. 2273 ____ 2275 2277 Figure 35: AsciiRFC Blockquote Usage 2279 2281
2282 Although the RFC Editor has recently dragged the IETF kicking 2283 and 2284 screaming into the twentieth century [RFC7990] [RFC7996], there is a 2285 yearning among all right-thinking Internet architects to "keep it 2286 simple" and to return to the olden days when pigs could be given 2287 thrust without anyone taking undue offence. 2288
2290 2292 Figure 36: AsciiRFC Blockquote Usage (RFC XML v3) 2294 10. Notes And Asides 2296 Asciidoctor syntax supports a range of "admonitions", including 2297 notes, warnings, and tips. They are indicated by a paragraph prefix 2298 (e.g. "WARNING:"), or as a block with an admonition style attribute. 2300 All admonitions are conflated in AsciiRFC, being converted to "note" 2301 elements in the document preamble, and "cref" elements in the main 2302 document. 2304 This means that no admonitions will therefore appear in the textual 2305 output, unless forced to through the "comments" processing 2306 instruction. A sample admonition is shown in Figure 37, with its 2307 rendered output in Figure 38. 2309 2311 [NOTE,display=true,source=Author] 2312 ==== 2313 Image courtesy of 2314 https://camelot.gov.example/creatures-in-ascii/ 2315 ==== 2317 2319 Figure 37: An AsciiRFC Adminition Block 2321 2323 Image courtesy of 2324 2326 2328 Figure 38: An AsciiRFC Adminition Block (RFC XML v3) 2330 With RFC XML v2, note that no inline formatting is permitted for 2331 "cref" elements, and any such formatting is therefore stripped for v2 2332 by the converter. 2334 Because paragraphs in AsciiRFC cannot contain any other blocks, a 2335 comment at the end of a paragraph is treated as a new block. In the 2336 document converter, any such comments are moved inside the preceding 2337 RFC XML paragraph; if the comment is at the start of a section, as in 2338 the example above, it is wrapped inside a paragraph. 2340 The RFC XML v3 converter also supports "asides" (Asciidoctor syntax 2341 Sidebars). A sample is shown in Figure 39, with its rendered output 2342 in Figure 40. 2344 2346 **** 2347 While the exchange at the French-occupied castle is one of 2348 the more memorable scenes of _Monty Python and the Holy Grail_, 2349 the Trojan Rabbit has not reached the same level of cultural 2350 resonance as its more murderous counterpart. Reasons for this 2351 may include: 2353 * Less overall screen-time dedicated to the Trojan Rabbit. 2355 * The Trojan Rabbit as projectile has already been anticipated 2356 by the Cow as projectile. 2357 **** 2359 2361 Figure 39: An AsciiRFC Sidebar Block 2363 2365 2379 2381 Figure 40: An AsciiRFC Sidebar Block Rendered As An Aside (RFC XML 2382 v3) 2384 Comments given in AsciiDoc syntax (notated with initial "//") are not 2385 intended to be shown in the rendered output, and will not appear in 2386 the output as XML comments. XML comments can be generated by using 2387 the "[comment]#...#" inline formatting macro, or the "[.comment]" 2388 role attribute on blocks. A sample is shown in Figure 39 with its 2389 rendered output in Figure 40. 2391 2393 The exchange of projectile animals was the beginning of a 2394 long-running fruitful relationship between the British and the 2395 French peoples, 2396 [comment]#TODO: Will need to verify that claim.# which 2397 arguably predates the traditional English enmity with the 2398 French. [comment]#Strictly speaking, the Knights are Welsh.# 2400 [.comment] 2401 -- 2402 This document, as it turns out, has a profusion of XML comments. 2404 As expected, they are ignored in any rendering of the document. 2405 -- 2407 2409 Figure 41: AsciiRFC delimited text intended as an XML Comment 2411 2413 The exchange of projectile animals was the beginning of a 2414 long-running fruitful relationship between the British and the 2415 French peoples, 2417 2418 which 2419 arguably predates the traditional English enmity with the 2420 French. 2421 2422 2424 2429 2431 Figure 42: AsciiRFC delimited text Rendered As An XML Comment (RFC 2432 XML v3) 2434 11. Tables 2436 AsciiRFC tables, like RFC XML v3, support distinct table heads, 2437 bodies and feet; cells spanning multiple rows and columns; and 2438 horizontal alignment. The larger range of table formatting options 2439 available in RFC XML v2 is also supported. 2441 A sample of an AsciiRFC table is shown in Figure 43, with its 2442 rendered output in Figure 44. 2444 Neither version of RFC XML is as expressive in its table structure as 2445 Asciidoctor syntax. RFC XML, for example, does not permit blocks 2446 within table cells. 2448 2450 [grid=all,options="footer"] 2451 |=== 2452 |French Castle | Cave of Caerbannog 2454 2+|King Arthur 2455 2+|Patsy 2456 2+|Sir Bedevere the Wise 2457 2+|Sir Galahad the Pure 2458 2+|Sir Lancelot the Brave 2459 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot 2460 |French Guard with Outrageous Accent| Tim the Enchanter 2461 |Other French Guards | Brother Maynard 2462 | | The Lector 2463 .3+^|not yet recruited 2464 >|Sir Bors 2465 >|Sir Gawain 2466 >|Sir Ector 2468 |Retinue of sundry knights 2469 |Retinue of sundry more knights than at the French Castle 2470 |=== 2472 2474 Figure 43: An AsciiRFC Table 2476 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2495 2496 2497 2498 2499 2500 2502 2503 2504 2506 2507 2508 2510 2511 2512 2513 2514 2515 2516 2517 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2536 2537 2538
French CastleCave of Caerbannog
King Arthur
Patsy
Sir Bedevere the 2494 Wise
Sir Galahad the Pure
Sir Lancelot the 2501 Brave
Sir Robin the 2505 Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous 2509 AccentTim the Enchanter
Other French GuardsBrother Maynard
2518 The Lector
not yet recruitedSir Bors
Sir Gawain
Sir Ector
Retinue of sundry knightsRetinue of sundry more knights than at the 2535 French Castle
2540 2542 Figure 44: An AsciiRFC Table (RFC XML v3) 2544 12. Inline Formatting 2546 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts 2548 AsciiRFC supports italics, boldface, monospace, subscripts and 2549 superscripts, just like RFC XML v3. 2551 The inline formatting syntax given in Figure 45 produces the RFC XML 2552 v3 output given in Figure 46. 2554 2556 The participants of that renowned exercise in cross-cultural 2557 communication, to wit the exchange between the 2558 _Knights of the Round Table_ 2559 and the taunting French soldiers serving under *Guy de Lombard* are, 2560 properly speaking, outside the scope of this `menagerie`, being more 2561 or less human. Notwithstanding, several^ish^ beasts both animate~d~ 2562 and wooden played a significant part in this encounter; most 2563 notably: 2565 * The Projectile Cow, see <> 2566 * The Trojan Rabbit, see <> 2568 2570 Figure 45: Inline Formatting In AsciiRFC 2572 2574 The participants of that renowned exercise in cross-cultural 2575 communication, to wit the exchange between the 2576 Knights of the Round Table 2577 and the taunting French soldiers serving under Guy de 2578 Lombard are, 2579 properly speaking, outside the scope of this 2580 menagerie, being more 2581 or less human. Notwithstanding, severalish beasts 2582 both animated 2583 and wooden played a significant part in this encounter; most 2584 notably: 2585
    2586
  • The Projectile Cow, see
    • 2588
  • The Trojan Rabbit, see
    • 2590
2592 2594 Figure 46: Inline Formatting In AsciiRFC (RFC XML v3) 2596 12.2. Formatting BCP 14 Keywords 2598 RFC XML v3 also supports tagging of BCP14 keywords [RFC2119] 2599 [RFC8174]; this is done in AsciiRFC either by tagging them with a 2600 custom formatting span (e.g. "MUST NOT"), or by converting any 2601 boldface all-caps words recognised as BCP14 words (unless the ":no- 2602 rfc-bold-bcp14: false" document attribute is set). 2604 Any spans of BCP14 text delimited by inline formatting delimiters 2605 need to be contained within a single line of text; in Asciidoctor 2606 syntax, formatting spans are broken up across line breaks. 2608 This usage is demonstrated in Figure 47 with the rendered output in 2609 Figure 48. 2611 2613 The instructions in the _Book of Armaments_ on the proper deployment 2614 of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as 2615 follows, although this summary *SHALL NOT* be used as a substitute 2616 for a reading from the Book of Armaments: 2618 2620 Figure 47: BCP14 Keywords In AsciiRFC 2622 2624 The instructions in the Book of Armaments 2625 on the proper deployment 2626 of the Holy Hand Grenade of Antioch MAY be 2627 summarized as 2628 follows, although this summary SHALL NOT be 2629 used as a substitute 2630 for a reading from the Book of Armaments: 2632 2634 Figure 48: BCP14 Keywords In AsciiRFC (RFC XML v3) 2636 12.3. Escaping AsciiRFC Syntax 2638 Formatting delimiters like "*" can be escaped with backslash ("\*"); 2639 double formatting delimiters, like "**" and "__", need to be escaped 2640 with double backslash ("\\**"). 2642 Escaping delimiters is not always reliable, and for double delimiters 2643 it is preferable to use HTML entities ("**"), or attribute 2644 references (references to the value of attributes set in the document 2645 header) as shown in Figure 49. 2647 2648 :dblast: ** 2650 `{dblast}` 2651 2653 Figure 49: Escaping AsciiRFC Syntax Using Attributes 2655 In extreme circumstances (such as quoting AsciiDoc syntax), you may 2656 need to resort to altering the substitutions behaviour within a given 2657 block of of AsciiDoc; see the "Applying Substitutions" section of 2658 [Asciidoctor-Manual]. 2660 13. Links 2662 Common URL formats are recognised automatically as hyperlinks in 2663 AsciiRFC, which inherits this excellent feature from AsciiDoc, and 2664 are rendered as such. 2666 Any hyperlinked text is appended after the hyperlink in square 2667 brackets. 2669 An example is given in Figure 50 with its rendered version in 2670 Figure 51. 2672 2674 <> of the fearsome 2675 beast 2676 has been sourced from 2677 http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], 2678 <> 2679 by C code that was used in this accurate depiction of the 2680 Killer Rabbit: 2682 2684 Figure 50: An AsciiRFC Link 2686 2688 The following 2689 depiction of the fearsome beast 2690 has been sourced from 2691 Rabbit-SCII, 2692 accompanied 2693 by C code that was used in this accurate depiction of the 2694 Killer Rabbit: 2696 2698 Figure 51: An AsciiRFC Link (RFC XML v3) 2700 To prevent hyperlinking of a URL, prefix it with a backslash, as 2701 shown in Figure 52 with its rendered version in Figure 53. 2703 2705 The screaming move into the twenty-*first* century is accompanied by 2706 a move back to the late twentieth century, with ASCII stylings more 2707 wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be 2708 accessible in 1996.) 2710 2712 Figure 52: A Literal AsciiRFC Link 2714 2716 The screaming move into the 2717 twenty-first century is accompanied by 2718 a move back to the late twentieth century, with ASCII stylings more 2719 wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be 2720 accessible in 1996.) 2722 2724 Figure 53: A Literal AsciiRFC Link (RFC XML v3) 2726 14. Cross-References 2728 14.1. Basic Referencing 2730 Anchors for cross-references are notated as "[[...]]" or "[#...]", 2731 and can be inserted on their own line in front of most blocks. 2733 Asciidoctor syntax supports anchors in a much wider range of contexts 2734 than is supported than RFC XML v3 (let alone v2); anchors that are 2735 not supported for that version of RFC XML are simply ignored by the 2736 converter. 2738 Note that anchors in RFC XML are constrained to the format "[A-Za- 2739 z_:][[A-Za-z0-9_:.-]*" (i.e. "xsd:ID"). 2741 Cross-references to anchors are notated as "<<...>>"; cross- 2742 references with custom text as "<>". 2744 An example of using cross-references in AsciiRFC is given in 2745 Figure 54 with its rendered output in Figure 55. 2747 2749 The _Cave of Caerbannog_ has been well-established in the mythology 2750 of Camelot (as recounted by Monty Python) as the lair of the 2751 Legendary Black Beast of Arrrghhh, more commonly known today as the 2752 *Killer Rabbit of Caerbannog* <>. 2753 It is the encounter between the Killer Rabbit of Caerbannog and the 2754 Knights of the Round Table, armed with the Holy Hand Grenade of 2755 Antioch (see the <>), 2756 that we 2757 recount here through monospace font and multiple spaces. 2759 [[killer_rabbit_caerbannog]] 2760 === The Killer Rabbit of Caerbannog 2762 2764 Figure 54: Setting And Referring To Cross-References In AsciiRFC 2766 2768 The Cave of Caerbannog has been 2769 well-established in the mythology 2770 of Camelot (as recounted by Monty Python) as the lair of the 2771 Legendary Black Beast of Arrrghhh, more commonly known today as the 2772 Killer Rabbit of Caerbannog . 2774 It is the encounter between the Killer Rabbit of Caerbannog and the 2775 Knights of the Round Table, armed with the Holy Hand Grenade of 2776 Antioch (see the following 2777 section), that we 2778 recount here through monospace font and multiple spaces. 2779
The Killer Rabbit of 2781 Caerbannog 2782 2784 Figure 55: Setting And Referring To Cross-References In AsciiRFC (RFC 2785 XML v3) 2787 14.2. Referencing With Attributes 2789 While Asciidoctor syntax natively does not support attributes on 2790 cross-references, AsciiRFC works around that by embedding formatting 2791 information as templated text within cross-references: 2793 o "format=x: text" populates the "xref@format" attribute 2794 o a section number followed by one of the words "of", "parens", 2795 "bare", "text" is treated as a "relref" reference to an external 2796 document. 2798 An example of referencing with attributes is given in Figure 56 with 2799 its output in Figure 57. 2801 2803 The *Killer Rabbit of Caerbannog*, that most formidable foe of 2804 the Knights and of all that is holy or carrot-like, has been 2805 depicted diversely in lay and in song. We venture to say, 2806 _contra_ the claim made in <>, 2807 that the Killer Rabbit of Caerbannog truly is the most afeared 2808 of all the creatures. Short of sanctified ordnance such as 2809 <>, there are few remedies 2810 known against its awful lapine powers. 2812 2814 Figure 56: Cross-References With Attributes In AsciiRFC 2816 2818 The Killer Rabbit of Caerbannog, 2819 that most formidable foe of 2820 the Knights and of all that is holy or carrot-like, has been 2821 depicted diversely in lay and in song. We venture to say, 2822 contra the claim made in Ze Vompyre, 2824 that the Killer Rabbit of Caerbannog truly is the most afeared 2825 of all the creatures. Short of sanctified ordnance such as 2826 , there are few 2827 remedies 2828 known against its awful lapine powers. 2830 2832 Figure 57: Cross-References With Attributes In AsciiRFC (RFC XML v3) 2834 14.3. Indexing 2836 Inline index entries are notated as "((...))". Index entries which 2837 do not appear in the text are notated as "(((...)))"; such entries 2838 may include a separate sub-entry, separated from the main entry by 2839 comma. 2841 2843 The solution to the impasse at the ((Cave of Caerbannog)) was 2844 provided by the successful deployment of the 2845 *Holy Hand Grenade of Antioch* (see <>) 2846 (((Holy Hand Grenade of Antioch))). 2847 Any similarity between the Holy Hand Grenade of Antioch and the 2848 mythical _Holy Spear of Antioch_ is purely intentional; 2849 (((relics, Christian))) any similarity between the Holy Hand Grenade 2850 of Antioch and the _Sovereign's Orb of the United Kingdom_ 2851 (see <>) is putatively fortuitous. 2852 (((relics, monarchic))) 2854 2856 Figure 58: AsciiRFC Index Entries 2858 2860 The solution to the impasse at the Cave of Caerbannog was 2862 provided by the successful deployment of the 2863 Holy Hand Grenade of Antioch (see ) 2865 . 2866 Any similarity between the Holy Hand Grenade of Antioch and the 2867 mythical Holy Spear of Antioch is purely 2868 intentional; 2869 any similarity between 2870 the Holy Hand Grenade 2871 of Antioch and the Sovereign's Orb of the United 2872 Kingdom 2873 (see ) is putatively fortuitous. 2874 2876 2878 Figure 59: AsciiRFC Index Entries (RFC XML v3) 2880 15. Inclusions 2882 AsciiRFC inherits the Asciidoctor syntax "include" directive 2883 [Asciidoctor-Manual] to include external files in a master AsciiRFC 2884 document. 2886 This directive is capable of sophisticated document merging, 2887 including adjusting the heading levels of the included text, 2888 selecting text within specified tags or line numbers to be included, 2889 and adjusting the indentation of code snippets in merged text. 2891 Its basic syntax is given in Figure 60. 2893 2894 include::path[ 2895 leveloffset=_offset_, 2896 lines=_ranges_, 2897 tag(s)=_name(s)_, 2898 indent=_depth_ 2899 ] 2900 2902 Figure 60: Inclusions In AsciiRFC 2904 If a file is included in an AsciiRFC document, ensure it ends with a 2905 blank line. An inclusion that results in its final block not being 2906 delimited with a blank line from what follows can lead to 2907 unpredictable results. 2909 16. Encoding and Entities 2911 XML accepts the full range of characters in the world's languages 2912 through UTF-8 character encoding, and one of the motivations for the 2913 move by the IETF from plain text to RFC XML has been to allow non- 2914 ASCII characters to be included in RFCs. 2916 However, current RFC XML v2 tools still do not support UTF-8, and 2917 alternative tooling support for UTF-8 also remains patchy. Out of an 2918 abundance of caution, the RFC XML converter uses US-ASCII for its 2919 character encoding, and renders any non-ASCII characters as HTML 2920 entities. 2922 AsciiRFC accepts HTML entities as input, even though they are not 2923 part of the W3C XML specification. HTML entities such as " " 2924 feature in examples of RFC XML provided by the IETF. In order to 2925 prevent dependence of the XML output from extraneous entity 2926 definitions, any such entities are rendered in the XML as decimal 2927 character entities. 2929 An example of how AsciiRFC renders non-ASCII UTF-8 characters are 2930 given in Figure 61 with the output in Figure 62. 2932 2934 ____ 2935 .כאן אולי 2936 ימצאו 2937 המילים 2938 האחרונות של 2939 יוסף 2940 מארמתיה 2941 .מי אשר 2942 יהיה אמיץ 2943 ובעל נפש 2944 טהורה יוכל 2945 למצוא את 2946 הגביע הקדוש 2947 בטירת 2948 אאאאאאאה 2950 "Here may be found the last words of Joseph of Arimathea. 2951 He who is valiant and pure of spirit may find the Holy Grail 2952 in the castle of — Aaaargh." 2953 ____ 2955 2957 Figure 61: UTF-8 Characters In AsciiRFC 2959 2961
.כאן 2962 אולי 2963 ימצאו 2964 המילים 2965 האחרונות 2966 של יוסף 2967 מארמתיה 2968 .מי אשר 2969 יהיה 2970 אמיץ 2971 ובעל 2972 נפש 2973 טהורה 2974 יוכל 2975 למצוא 2976 את 2977 הגביע 2978 הקדוש 2979 בטירת 2980 אאאאאאאה 2981 "Here may be found the last words of Joseph of 2982 Arimathea. 2983 He who is valiant and pure of spirit may find the Holy Grail 2984 in the castle of — Aaaargh."
2986 2988 Figure 62: UTF-8 Characters In AsciiRFC Rendered As RFC XML v3 2990 Note that because initial period is a formatting character in 2991 Asciidoctor, we have had to use "." to escape the period at the 2992 end of Hebrew sentences (which appears at the start of the line, 2993 Hebrew being written Right-to-Left). Asciidoctor is not natively 2994 equipped to deal with Right-to-Left languages in its formatting 2995 parsing. 2997 17. Bibliography 2999 The simple encoding of bibliography syntax provided by AsciiDoc (and 3000 Asciidoctor syntax) is inadequate for the complexity of bibliographic 3001 markup required by RFC XML. 3003 RFC documents overwhelmingly cite other RFC documents, and canonical 3004 RFC XML bibliographic entries are available at [IETF-BibXML]; so it 3005 would be inefficient to encode those entries natively in AsciiRFC, 3006 only to have them converted back to RFC XML. 3008 The converter provides two means of incorporating bibliographies into 3009 RFC documents authored in AsciiRFC: 3011 o using raw RFC XML; and 3013 o assembling bibliographies in preprocessing. 3015 In either case, the RFC XML needs to be well-formed; missing closing 3016 tags can lead to erratic behaviour in the converter. 3018 17.1. Using Raw RFC XML 3020 In the first method, bibliographic citations are handled like all 3021 other AsciiRFC cross-references. The bibliographic entries for 3022 normative and informative references are given in the AsciiRFC as 3023 passthrough blocks, which contain the raw RFC XML for all references; 3024 document conversion leaves the raw RFC XML in place. 3026 This approach requires authors to maintain the normative and 3027 informative bibliographies within the document, to update them as 3028 citations are added and removed, and to sort them manually. However, 3029 if the citation is stored on the IETF's RFC XML citation libraries 3030 (see ), AsciiRFC will automatically 3031 replace it with an external reference to that citation. So the body 3032 of the citation XML can be left out. 3034 For example, the AsciiRFC in Figure 63 will generate the 3035 corresponding RFC XML v3 output in Figure 64. 3037 3039 [bibliography] 3040 == Normative References 3041 ++++ 3042 3044 3045 Key words for use in RFCs to Indicate 3046 Requirement Levels 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 ++++ 3058 [bibliography] 3059 == Informative References 3060 ++++ 3062 3063 3064 Monty Python and the Holy Grail 3065 3066 3067 3068 3069 3070 3071 3072 3073 3075 3077 3078 DON'T SPEW A Set of Guidelines for Mass Unsolicited 3079 Mailings and Postings (spam*) 3080 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3094 3096 3097 RFC Format Framework 3098 3099 3100 3101 3102 3103 3104 3105 3107 3109 3110 3111 The Arte of ASCII: Or, An True and Accurate Representation of 3112 an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of 3113 Character 3114 3115 3116 3117 3118 3119 3120 3121 3122 3124 3126 3127 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 3128 Words 3129 3130 3131 3132 3133 RFC 2119 specifies common key words that may be 3134 used 3135 in protocol specifications. This document aims to reduce 3136 the ambiguity by clarifying that only UPPERCASE usage of the 3137 key words have the defined special meanings. 3138 3139 3140 3141 3142 3144 ++++ 3146 3148 Figure 63: AsciiRFC Inline Bibliography 3150 3151
3152 3153 3154 Normative References 3155 3158 3159 3160 Informative References 3161 3162 3163 Monty Python and the Holy Grail 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3176 3179 3182 3185 3186 3187 3188 3190 Figure 64: AsciiRFC Inline Bibliography Rendered As RFC XML v3 3192 17.2. Preprocessing Using "asciidoctor-bibliography" 3194 The alternative method is to use a preprocessing tool, 3195 [asciidoctor-bibliography], to import citations into the AsciiRFC 3196 document from an external file of references. 3198 The references file consists of RFC XML reference entries, and still 3199 needs to be managed manually; however the bibliographies are 3200 assembled from that file, sorted, and inserted into the normative and 3201 informative references in preprocessing. Citations in the document 3202 itself are given as macros to be interpreted by the preprocessor; 3203 this allows them to be split into normative and informative 3204 references. (The MMark tool likewise splits reference citations into 3205 normative and informative.) 3207 Integration with the "asciidoc-bibliography" gem proceeds as follows: 3209 1. Create an RFC XML references file, consisting of a "" 3210 element with individual "" elements inserted, as would 3211 be done for the informative and normative references normally. 3212 The references file will contain all possible references to be 3213 used in the file; the bibliography gem will select which 3214 references have actually been cited in the document. 3216 A. Rather than hand crafting RFC XML references for RFC 3217 documents, you should download them from an authoritative 3218 source; e.g., "http://xml.resource.org/public/rfc/bibxml/ 3219 reference.RFC.2119.xml". Note that RFC XML references from 3220 this link contains the XML document declaration, which needs 3221 to be removed before being used in the XML bibliography. 3223 B. Unlike the case for RFC XML documents created manually, the 3224 references file does not recognise XML entities and will not 3225 attempt to download them during processing. Any references 3226 to "http://xml.resource.org/public/rfc/bibxml/" will need to 3227 be downloaded and inserted into the references file. 3229 C. The RFC XML in the references file will need to be 3230 appropriate to the version of RFC XML used in the main 3231 document, as usual. Note that RFC XML v2 references are 3232 forward compatible with v3; v3 contains a couple of 3233 additional elements. 3235 2. Add to the main document header attributes referencing the 3236 references file (":bibliography-database:"), and the bibliography 3237 style (":bibliography-style: rfc-v3"). 3239 3. References to a normative reference are inserted with the macro 3240 "cite:norm[id]" instead of "<>", where "id" is the anchor of 3241 the reference. 3243 4. References to an informative reference are inserted with the 3244 macro "cite:info[id]" instead of "<>", where "id" is the 3245 anchor of the reference. 3247 5. Formatted crossreferences and "relref" crossreferences are 3248 entered by inserting the expected raw XML in the "text" 3249 attribute. Do not use the "{cite}" interpolation of the 3250 citation. For example: 3252 * "<>" = "cite:norm[id, text="words"]" 3255 * "<>" (processed as a formatted 3256 cross-reference) = "cite:norm[id, text="words"]" 3259 * "<>" (processed as relref) = 3260 "cite:norm[id, text=""]" 3263 * "<>" (processed as relref with 3264 a cross-document internal reference) = "cite:norm[id, 3265 text=""]" 3268 6. Normative and Informative References are inserted in the document 3269 through a macro, which occurs where the RFC XML references would 3270 be inserted, as shown in Figure 65. 3272 3273 [bibliography] 3274 == Normative References 3276 ++++ 3277 bibliography::norm[] 3278 ++++ 3280 [bibliography] 3281 == Informative References 3283 ++++ 3284 bibliography::info[] 3285 ++++ 3286 3288 Figure 65: Using asciidoctor-bibliography For Bibliography 3289 Preprocessing 3291 18. RFC XML features not supported in Asciidoctor 3293 The following features of RFC XML v3 [RFC7991] and v2 [RFC7749] are 3294 not supported by the AsciiRFC converter, and would need to be 3295 adjusted manually after RFC XML is generated: 3297 +------------------------+--------------------+---------------------+ 3298 | RFC XML element | RFC XML v3 | RFC XML v2 | 3299 +------------------------+--------------------+---------------------+ 3300 | "front/boilerplate" | Not added by the | Not added by the | 3301 | | converter | converter | 3302 | "iref@primary" | N | N | 3303 | "reference" (and all | As Raw XML | As Raw XML | 3304 | children) | | | 3305 | "table/preamble" | Deprecated | N | 3306 | "table/postamble" | Deprecated | N | 3307 | "artwork@width" | Only on images | Only on images | 3308 | "artwork@height" | Only on images | Only on images | 3309 +------------------------+--------------------+---------------------+ 3311 19. Authoring 3313 To author an AsciiRFC document, you should first familiarise yourself 3314 with the [Asciidoctor-Manual]. 3316 The [asciidoctor-rfc] Ruby gem source code distribution also has 3317 samples of individual RFC XML features in v2 and v3, and examples of 3318 self-standing AsciiRFC documents, along with their RFC XML 3319 renderings. (This includes round-tripped RFC XML documents.) 3321 19.1. Using the "rfc-asciirfc-minimal" template 3323 In addition, you can clone the sample "rfc-asciirfc-minimal" 3324 repository as a template, and populate it for your AsciiRFC document 3325 using the steps shown in Figure 66. 3327 $ git clone https://github.com/riboseinc/rfc-asciirfc-minimal 3329 Figure 66: Cloning The AsciiRFC Document Template 3331 19.2. Installing AsciiRFC Backend Processors 3333 Converting your AsciiRFC to RFC XML is a simple as installing the 3334 Asciidoctor Ruby gem "asciidoctor" (see "Installation" at 3335 [Asciidoctor]) and the "asciidoctor-rfc" gem in Ruby (through 3336 RubyGems), then running the "asciidoctor" executable on the document, 3337 specifying the "asciidoctor-rfc" gem as a library. 3339 The necessary steps are shown in Figure 67. 3341 $ gem install asciidoctor-rfc 3342 $ asciidoctor -b rfc3 -r 'asciidoctor-rfc' foo.adoc # RFC XML v3 output 3343 $ asciidoctor -b rfc2 -r 'asciidoctor-rfc' foo.adoc # RFC XML v2 output 3345 Figure 67: Installing The AsciiRFC Backend Processors 3347 19.3. Iterating AsciiRFC Content 3349 As you author AsciiRFC content, you should iterate by running the 3350 AsciiRFC conversion frequently, to ensure that you are still 3351 generating valid XML through your markup. The converter makes an 3352 effort to ensure that its XML output is valid, and it issues warnings 3353 about likely issues; it also validates its own XML output against the 3354 RFC XML schema (of the corresponding version), and reports errors in 3355 the XML output in the format shown in Figure 68. 3357 V3 RELAXNG Validation: 12:0: ERROR: Invalid attribute 3358 sortRefs for element rfc 3360 Figure 68: Sample Validation Error Message From AsciiRFC 3362 Note that validation against the Relax NG RFC XML schema includes 3363 confirming the referential integrity of all cross-references in the 3364 document. 3366 It may be necessary to intervene in the XML output generated by the 3367 converter, either because the block model of AsciiRFC does not 3368 conform with the intended RFC XML (e.g. lists embedded in 3369 paragraphs), or because RFC XML features are required that are not 3370 supported within AsciiRFC. 3372 20. Security Considerations 3374 o Ensure your AsciiRFC generator comes from a geniune and 3375 trustworthy source. This protects your own machine and also 3376 prevents injection of malicious content in your resulting 3377 document. 3379 o An AsciiRFC generator may cause errors in textual rendering or 3380 link generation that may lead to security issues. 3382 o Creating cross-references (and also bibliographic references) to 3383 external documents may pose risks since the specified external 3384 location may become controlled by a malicious party. 3386 o URIs that start with the "http:" or "https:" prefix are 3387 automatically converted into links in AsciiRFC except when escaped 3388 with a backslash before the prefix. A URI that is intended to be 3389 text but unintentionally rendered as a link may cause users to 3390 visit a malicious website with security consequences. 3392 o AsciiRFC contains syntax that can directly incorporate remote URI 3393 content, such as "include::" which allows remotely-located 3394 AsciiRFC content files. If a remote URI contains malicious 3395 content, this content will be included in the resulting AsciiRFC 3396 document compiled as RFC XML. Remotely-linked URIs should always 3397 be checked for malicious content prior to compiling AsciiRFC into 3398 RFC XML. 3400 21. IANA Considerations 3402 This document does not require any action by IANA. 3404 22. References 3406 22.1. Normative References 3408 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 3409 RFC 7991, DOI 10.17487/RFC7991, December 2016, 3410 . 3412 22.2. Informative References 3414 [AsciiDoc] 3415 Rackham, S., "AsciiDoc: Text based document generation", 3416 November 2013, . 3418 [Asciidoctor] 3419 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast 3420 text processor & publishing toolchain for converting 3421 AsciiDoc to HTML5, DocBook & more.", November 2017, 3422 . 3424 [asciidoctor-bibliography] 3425 Ribose Inc., "Citations and Bibliography the 'asciidoctor- 3426 way'", November 2017, 3427 . 3429 [Asciidoctor-Manual] 3430 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast 3431 text processor & publishing toolchain for converting 3432 AsciiDoc to HTML5, DocBook & more.", November 2017, 3433 . 3435 [asciidoctor-rfc] 3436 Ribose Inc., "asciidoctor-rfc lets you write Internet- 3437 Drafts and RFCs in AsciiDoc, the "asciidoctor-way".", 3438 November 2017, 3439 . 3441 [AsciiMathML] 3442 "AsciiMath is an easy-to-write markup language for 3443 mathematics.", November 2017, . 3445 [datatracker-asciirfc-minimal] 3446 Carberry, J. and T. Grayson, "IETF Datatracker: A Minimal 3447 Internet-Draft In AsciiRFC", March 2018, 3448 . 3451 [datatracker-camelot-holy-grenade] 3452 Pendragon, A., "IETF Datatracker: The Holy Hand Grenade of 3453 Antioch", March 2018, . 3456 [datatracker-divination-cfapi] 3457 Destiny, G. and C. Luck, "IETF Datatracker: An API For 3458 Calendar-Based Fortune Heuristics Services", March 2018, 3459 . 3462 [draftr] Barnes, R., "draftr: an HTML front-end to pandoc2rfc", Nov 3463 2017, . 3465 [git-asciirfc-minimal] 3466 Carberry, J. and T. Grayson, "Git repository: A Minimal 3467 Internet-Draft In AsciiRFC", March 2018, 3468 . 3470 [git-camelot-holy-grenade] 3471 Pendragon, A., "Git repository: The Holy Hand Grenade of 3472 Antioch", March 2018, 3473 . 3475 [git-divination-cfapi] 3476 Destiny, G. and C. Luck, "Git repository: An API For 3477 Calendar-Based Fortune Heuristics Services", March 2018, 3478 . 3480 [I-D.asciirfc-minimal] 3481 Carberry, J. and T. Grayson, "A Minimal Internet-Draft In 3482 AsciiRFC", draft-asciirfc-minimal-01 (work in progress), 3483 March 2018. 3485 [I-D.camelot-holy-grenade] 3486 Pendragon, A., "The Holy Hand Grenade of Antioch", draft- 3487 camelot-holy-grenade-00 (work in progress), March 2018. 3489 [I-D.divination-cfapi] 3490 Destiny, G. and C. Luck, "An API For Calendar-Based 3491 Fortune Heuristics Services", draft-divination-cfapi-00 3492 (work in progress), March 2018. 3494 [IETF-BibXML] 3495 "IETF BibXML Library", November 2017, 3496 . 3498 [kramdown-rfc2629] 3499 Bormann, C., "kramdown-rfc2629: An RFC2629 (XML2RFC) 3500 backend for Thomas Leitner's kramdown markdown parser", 3501 Nov 2017, . 3503 [lyx2rfc] Williams, N., "LyX to I-D/RFC export by way of Lyx export 3504 to XHTML and XSLT conversion to xml2rfc schema", 2014, 3505 . 3507 [MathJax] "MathJax: A JavaScript display engine for mathematics that 3508 works in all browsers.", November 2017, 3509 . 3511 [mmark] Gieben, R., "Using mmark to create I-Ds and RFCs", June 3512 2015, . 3514 [NroffEdit] 3515 Santesson, S., "WYSIWYG Internet-Draft Nroff Editor", May 3516 2011, . 3518 [pandoc2rfc] 3519 Gieben, R., "pandoc2rfc: Use pandoc to create XML suitable 3520 for xml2rfc", 2012, . 3522 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3523 Requirement Levels", BCP 14, RFC 2119, 3524 DOI 10.17487/RFC2119, March 1997, 3525 . 3527 [RFC5385] Touch, J., "Version 2.0 Microsoft Word Template for 3528 Creating Internet Drafts and RFCs", RFC 5385, 3529 DOI 10.17487/RFC5385, February 2010, 3530 . 3532 [RFC7328] Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit 3533 of XML", RFC 7328, DOI 10.17487/RFC7328, August 2014, 3534 . 3536 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 3537 RFC 7749, DOI 10.17487/RFC7749, February 2016, 3538 . 3540 [RFC7763] Leonard, S., "The text/markdown Media Type", RFC 7763, 3541 DOI 10.17487/RFC7763, March 2016, 3542 . 3544 [RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies, 3545 Stability Strategies, and Select Registrations", RFC 7764, 3546 DOI 10.17487/RFC7764, March 2016, 3547 . 3549 [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990, 3550 DOI 10.17487/RFC7990, December 2016, 3551 . 3553 [RFC7996] Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", 3554 RFC 7996, DOI 10.17487/RFC7996, December 2016, 3555 . 3557 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 3558 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 3559 May 2017, . 3561 [TeX-LaTeX] 3562 "LaTeX is document preparation software that runs on top 3563 of Donald E. Knuth's TeX typesetting system.", November 3564 2017, . 3566 Appendix A. Examples 3568 A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" 3570 This example is available in the following formats: 3572 o AsciiRFC [git-asciirfc-minimal] 3574 o Internet-Draft [I-D.asciirfc-minimal] 3575 o Text, RFC XML, PDF and HTML on the IETF Datatracker 3576 [datatracker-asciirfc-minimal] 3578 A.1.1. In AsciiRFC 3580 3581 = A Minimal Internet-Draft In AsciiRFC 3582 :doctype: internet-draft 3583 :name: draft-asciirfc-minimal-01 3584 :abbrev: AsciiRFC Example 3585 :status: informational 3586 :ipr: trust200902 3587 :submissionType: individual 3588 :area: Internet 3589 :intended-series: full-standard 3590 :revdate: 2018-03-23T00:00:00Z 3591 :fullname: Josiah Stinkney Carberry 3592 :lastname: Carberry 3593 :forename_initials: J. S. 3594 :organization: Brown University 3595 :phone: +1 401 863 1000 3596 :street: Box K, 69 Brown Street 3597 :city: Providence 3598 :code: 02912 3599 :country: United States of America 3600 :uri: https://www.brown.edu 3601 :email: josiah.carberry@ribose.com 3602 :fullname_2: Truman Grayson 3603 :lastname_2: Grayson 3604 :forename_initials_2: T. 3605 :organization_2: Brown University 3606 :phone_2: +1 401 863 1000 3607 :street_2: Box G, 69 Brown Street 3608 :city_2: Providence 3609 :code_2: 02912 3610 :country_2: United States of America 3611 :uri_2: https://www.brown.edu 3612 :email_2: truman.grayson@ribose.com 3614 [abstract] 3616 This document provides a template on how to author (or migrate!) 3617 a new Internet-Draft / RFC in AsciiRFC format. This template 3618 requires usage of the `asciidoctor-rfc` Ruby gem. 3620 [#introduction] 3621 == Introduction 3622 AsciiRFC <> is an extremely simple way 3623 to 3624 author Internet-Drafts and RFCs without needing to manually craft 3625 RFC XML <>. 3627 This is a template for authors to easily start with 3628 <>. 3630 [#conventions] 3631 == Terms and Definitions 3633 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 3634 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 3635 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this 3636 document are to be interpreted as described in BCP 14 3637 <> <> when, and only when, 3638 they appear in 3639 all capitals, as shown here. 3641 //// 3642 Note: do not break formatted strings over carriage return. Bad 3643 things happen. (In this instance, the carriage return is 3644 suppressed, and no space takes its place.) This is an 3645 Asciidoctor issue, not an asciidoctor-rfc issue. 3646 //// 3648 [#symbols] 3649 == Symbols And Abbreviations 3651 [#operators] 3652 === Operators 3654 AsciiRFC:: 3655 As defined in <>. 3657 [#security] 3658 == Security Considerations 3660 * Please beware of implementation issues caused by 3661 <>. 3663 * Here's how you include references <>, 3664 <>, <>. 3666 [#iana] 3667 == IANA Considerations 3669 This document does not require any action by IANA. 3671 // References must be given before appendixes 3673 [bibliography] 3674 == Normative References 3676 //bibliography::norm[] 3677 ++++ 3679 3681 3682 Key words for use in RFCs to Indicate Requirement 3683 Levels 3684 3685 3686 3687 3688 3689 In many standards track documents several words are 3690 used to signify the requirements in the specification. 3691 These words are often capitalized. This document defines 3692 these words as they should be interpreted in IETF 3693 documents. This document specifies an Internet Best 3694 Current Practices for the Internet Community, and 3695 requests discussion and suggestions for improvements. 3696 3697 3698 3699 3700 3701 3702 3704 3706 3707 The "xml2rfc" Version 3 3708 Vocabulary 3709 3710 3711 3712 3713 3714 This document defines the "xml2rfc" 3715 version 3 vocabulary: an XML-based language used for 3716 writing RFCs and Internet-Drafts. It is heavily derived 3717 from the version 2 vocabulary that is also under 3718 discussion. This document obsoletes the v2 grammar 3719 described in RFC 7749. 3720 3721 3722 3723 3724 3726 3728 3729 Ambiguity of Uppercase vs Lowercase in RFC 2119 3730 Key Words 3731 3732 3733 3734 3735 3736 RFC 2119 specifies common key words that may be 3737 used in protocol specifications. This document aims to 3738 reduce the ambiguity by clarifying that only UPPERCASE 3739 usage of the key words have the defined special 3740 meanings. 3741 3742 3743 3744 3745 3746 3747 ++++ 3749 [bibliography] 3750 == Informative References 3752 //bibliography::info[] 3753 ++++ 3755 3757 3758 RNP: A C library approach to OpenPGP 3759 3760 Ribose Inc. 3761
3762 3763 Suite 1111, 1 Pedder Street 3764 Central 3765 Hong Kong 3766 Hong Kong 3767 3768 open.source@ribose.com 3769 https://www.ribose.com 3770
3771 3772 3773 3774 3776 3777 3778 3779 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc 3780 3781 3782 3783 3784 3786 3787 3788 3790 3791 3792 3793 3794 This document describes an AsciiDoc syntax 3795 extension called AsciiRFC, designed for authoring IETF 3796 Internet-Drafts and RFCs. AsciiDoc is a human readable document 3797 markup language which affords more granular control over markup 3798 than comparable schemes such as Markdown. The AsciiRFC syntax 3799 is designed to allow the author to entirely focus on text, 3800 providing the full power of the resulting RFC XML through the 3801 AsciiDoc language, while abstracting away the need to manually 3802 edit XML, including references. This document itself was 3803 written and generated into RFC XML v2 (RFC7749) and RFC XML v3 3804 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC 3805 generator. 3806 3807 3808 3810 3812 3814 3815 3816 3817 The SM4 Blockcipher Algorithm And Its Modes Of Operations 3818 3819 3820 3821 3822 3823 3824 3825 3826 This document describes the SM4 symmetric 3827 blockcipher 3828 algorithm published as GB/T 32907-2016 by the State Cryptography 3829 Administration of China (SCA). This document is a product of 3830 the Crypto Forum Research Group (CFRG). 3831 3832 3834 3837 3839 3841 3842 The OCB Authenticated-Encryption 3843 Algorithm 3844 3845 3846 3847 3848 3849 3850 3851 This document specifies OCB, a shared-key 3852 blockcipher-based encryption scheme that provides 3853 confidentiality and authenticity for plaintexts and 3854 authenticity for associated data. This document is a product 3855 of the Crypto Forum Research Group 3856 (CFRG). 3857 3858 3859 3860 3861 ++++ 3863 [appendix] 3864 [#appendix-a] 3865 == Examples 3867 === Example 1 3869 Here's an example. 3871 [source,json] 3872 ---- 3873 { 3874 "code": { 3875 "encoding": "ascii", 3876 "type": "rfc", 3877 "authors": [ "Josiah Carberry", "Truman Grayson" ] 3878 } 3879 } 3880 ---- 3882 [#acknowledgements] 3883 == Acknowledgements 3885 The authors would like to thank their families. 3887 3889 A.1.2. Rendered as RFC XML v3 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3904 3905 A Minimal Internet-Draft In 3906 AsciiRFC 3907 3909 3911 3913 Brown University 3914
3915 3916 Box K, 69 Brown Street 3917 Providence 3918 02912 3919 United States of America 3920 3921 +1 401 863 1000 3922 josiah.carberry@ribose.com 3923 https://www.brown.edu 3924
3925 3926 3928 Brown University 3929
3930 3931 Box G, 69 Brown Street 3932 Providence 3933 02912 3934 United States of America 3935 3936 +1 401 863 1000 3937 truman.grayson@ribose.com 3938 https://www.brown.edu 3939
3940 3941 3942 Internet 3944 3945 This document provides a template on how to author (or 3946 migrate!) 3947 a new Internet-Draft / RFC in AsciiRFC format. This template 3948 requires usage of the asciidoctor-rfc Ruby 3949 gem. 3950 3951 3952
IntroductionAsciiRFC 3954 is an extremely simple way to 3955 author Internet-Drafts and RFCs without needing to manually craft 3956 RFC XML . 3957 This is a template for authors to easily start with 3958 .
3959
3960 Terms and Definitions 3961 The key words "MUST", 3962 "MUST NOT", 3963 "REQUIRED", 3964 "SHALL", 3965 "SHALL NOT", 3966 "SHOULD", "SHOULD 3967 NOT", "RECOMMENDED", 3968 "NOT RECOMMENDED", 3969 "MAY", and 3970 "OPTIONAL" in this 3971 document are to be interpreted as described in BCP 14 3972 when, and 3973 only when, they appear in 3974 all capitals, as shown here. 3975
3976
3977 Symbols And Abbreviations 3978
3979 Operators 3980
3981
AsciiRFC
3982
As defined in .
3984
3985
3986
3987
3988 Security Considerations 3989
    3990
  • Please beware of implementation issues caused by .
    • 3992
  • Here’s how you include references , 3994 , .
    • 3995
3996
3997
3998 IANA Considerations 3999 This document does not require any action by IANA. 4000
4001 4002 4003 Normative References 4004 4007 4010 4013 4014 4015 Informative References 4016 4018 4019 RNP: A C library approach to OpenPGP 4020 4021 Ribose Inc. 4022
4023 4024 Suite 1111, 1 Pedder Street 4025 Central 4026 Hong Kong 4027 Hong Kong 4028 4029 open.source@ribose.com 4030 https://www.ribose.com 4031
4032 4033 4034 4035 4036 4039 4042 4045 4046
4047 Examples 4048
Example 4050 1Here’s an example. 4051
4052 { 4053 "code": { 4054 "encoding": "ascii", 4055 "type": "rfc", 4056 "authors": [ "Josiah Carberry", "Truman Grayson" ] 4057 } 4058 } 4059
4060
4061
4062 Acknowledgements 4063 The authors would like to thank their families. 4064
4065 4066 4067 4069 A.2. Example 2: "The Holy Hand Grenade of Antioch" 4071 This example is available in the following formats: 4073 o AsciiRFC [git-camelot-holy-grenade] 4075 o Internet-Draft [I-D.camelot-holy-grenade] 4077 o Text, RFC XML, PDF and HTML on the IETF Datatracker 4078 [datatracker-camelot-holy-grenade] 4080 A.2.1. In AsciiRFC 4082 4083 = The Holy Hand Grenade of Antioch 4084 Arthur son of Uther Pendragon 4085 :doctype: internet-draft 4086 :abbrev: Hand Grenade of Antioch 4087 :updates: 8140 4088 :submission-type: independent 4089 :name: draft-camelot-holy-grenade-00 4090 :status: informational 4091 :consensus: false 4092 :area: General, Operations and Management 4093 :keyword: rabbits, grenades, antioch, camelot 4094 :ipr: trust200902 4095 :toc-include: true 4096 :sort-refs: true 4097 :revdate: 2018-04-01 4098 :fullname: Arthur son of Uther Pendragon 4099 :forename_initials: A. 4100 :lastname: Pendragon 4101 :email: arthur.pendragon@ribose.com 4102 :organization: Camelot 4103 :uri: http://camelot.gov.example 4104 :street: Palace\ Camel Lot 1 4105 :city: Camelot 4106 :country: England 4107 :comments: yes 4108 :notedraftinprogress: yes 4109 :smart-quotes: false 4111 [.comment] 4112 tag::preamble1[] 4113 // tag::preamble[] 4115 [abstract] 4116 The menagerie of beasts and artefacts depicted in RFC8140 4117 may be usefully supplemented by other renowned figures of 4118 Internet and more general lore. This document extends the 4119 menagerie to the seminal fable of the 4120 "Holy Hand Grenade of Antioch", as depicted in the 4121 Monty Python film "Monty Python and the Holy Grail", 4122 as well as "Spamalot", the musical inspired by the movie. 4124 [NOTE,remove-in-rfc=false] 4125 .Spamalot 4126 The relevance of the musical "Spamalot" to Internet lore should be 4127 obvious to the reader; but in case of doubt, see also 4128 Section 1 ("What is Spam*?") of RFC2635. 4130 // end::preamble[] 4131 [.comment] 4132 end::preamble1[] 4134 [.comment] 4135 tag::sectnums1[] 4136 // tag::sectnums[] 4138 [toc=exclude] 4139 :sectnums!: 4140 == Terminology 4142 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 4143 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 4144 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 4145 are to be interpreted as described in BCP 14 <> 4146 <> 4147 when, and only when, they appear in all capitals, as shown here. 4149 :sectnums: 4150 == Introduction 4152 <> refers to the intended move of RFC formatting to 4153 XML2RFC v3 <>, in the following terms: 4155 // end::sectnums[] 4156 [.comment] 4157 end::sectnums1[] 4159 [.comment] 4160 tag::quote1[] 4161 // tag::quote[] 4163 [quote,attribution="A. Farrel"] 4164 ____ 4165 Although the RFC Editor has recently dragged the IETF kicking and 4166 screaming into the twentieth century [RFC7990] [RFC7996], there is a 4167 yearning among all right-thinking Internet architects to "keep it 4168 simple" and to return to the olden days when pigs could be given 4169 thrust without anyone taking undue offence. 4170 ____ 4172 // end::quote[] 4173 [.comment] 4174 end::quote1[] 4176 While no pigs, flying or otherwise, are involved in the transition 4177 to RFC XML v3, it is opportune to enhance the <> 4178 legendarium in the service of RFC XML v3, by illustrating its 4179 functionality through references to the mythology of Camelot, and 4180 particularly the incidents at the Cave of Caerbannog. 4182 [.comment] 4183 tag::escaped_hyperlink1[] 4184 // tag::escaped_hyperlink[] 4186 The screaming move into the twenty-*first* century is accompanied by 4187 a move back to the late twentieth century, with ASCII stylings more 4188 wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be 4189 accessible in 1996.) 4191 // end::escaped_hyperlink[] 4192 [.comment] 4193 end::escaped_hyperlink1[] 4195 There are two references to rabbits in 4196 _Monty Python and the Holy Grail_ which are expounded on herewith: 4198 [.comment] 4199 tag::listcontinuation1[] 4200 // tag::listcontinuation[] 4202 Trojan Rabbit:: 4203 In their siege of the French-occupied castle which may already 4204 contain an instance of the Grail, Sir Bedevere the Wise proposes to 4205 use a Trojan Rabbit to infiltrate the castle, with a raiding party 4206 to take the French "not only by surprise, but totally unarmed." 4207 + 4208 The proposal, unsurprisingly, proved abortive. The more so as the 4209 raiding party forgot to hide within the Trojan Rabbit, before the 4210 French soldiers took the Trojan Rabbit inside the castle. 4212 Killer Rabbit of Caerbannog:: 4213 Guarding the entrance to the Cave of Caerbannog; see 4214 <>. 4216 // end::listcontinuation[] 4217 [.comment] 4218 end::listcontinuation1[] 4220 == The French-occupied castle 4222 [.comment] 4223 tag::inline_formatting1[] 4224 // tag::inline_formatting[] 4226 The participants of that renowned exercise in cross-cultural 4227 communication, to wit the exchange between the 4228 _Knights of the Round Table_ 4229 and the taunting French soldiers serving under *Guy de Lombard* are, 4230 properly speaking, outside the scope of this `menagerie`, being more 4231 or less human. Notwithstanding, several^ish^ beasts both animate~d~ 4232 and wooden played a significant part in this encounter; most 4233 notably: 4235 * The Projectile Cow, see <> 4236 * The Trojan Rabbit, see <> 4238 // end::inline_formatting[] 4239 [.comment] 4240 end::inline_formatting1[] 4242 [[projectile-cow]] 4243 .The Projectile Cow with an accompanying cannon 4244 ==== 4245 [alt=The Projectile Cow with an accompanying cannon in ASCII] 4246 .... 4247 .-.-.-.-.-.-.-.-.-.-.-.--.-.-.-.-.-.-.--.-.-.-.-.-.-.-.--.-. 4248 _-_---__--__--___-___-__-____---___-________---____-____-__- 4249 ._.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-...-.-.--..-.-.-.-.-.-..--.- 4250 ,..,.,.,.,.,..,.,,..,.,.,.,.,.,, ^^ .,,.,., ^^ .,.,.,.= 4251 _>-.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-. 4252 .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., 4253 .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # .,.,.,. 4254 .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. 4255 .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ' '! .,.,..,.,.- 4256 .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_] . ., . . , 4257 .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / -.-<>.,.,..-.-, 4258 .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. 4259 .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- 4260 .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. 4261 .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- 4262 .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- 4263 -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- 4264 ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, 4265 ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- 4266 ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. 4267 .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., 4268 .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,. 4269 ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,. 4270 ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. 4271 .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. 4272 -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> 4273 _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,., 4274 .._...{WITHHONEY}-.-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_> 4275 GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASSPC 4276 SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS 4277 CLAY_ROCKS_REBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY>< 4278 CLAY_CLAY_SKLETONS_MORESOIL_CLAY_CLAY_CLAY_CLAY_CLAY_VR 4279 .... 4280 ==== 4282 [[trojan-rabbit]] 4283 .The Trojan Rabbit with an automatic sliding door 4284 ==== 4285 [alt=The Trojan Rabbit with an automatic sliding door, in ASCII] 4286 .... 4287 ___ ____ 4288 //_ \//\__\ 4289 || || | 4290 -__||_||__| 4291 // \--_ 4292 // ____ --___ 4293 // // \ \-_ 4294 // \\ @/ o || 4295 // ---- _____|| 4296 // // 4297 //\_//__ // 4298 //-- --- \____ // 4299 // --- \______ // 4300 // , . ----- \_//_ 4301 // ,. --- \____ 4302 // .,v --- \___ 4303 // __ -- \_ 4304 || , _______________ //|| |-_ 4305 || | |''''''''''| // || | | 4306 || ' | | | || | | 4307 || | | | || | | 4308 || " | | 0 | ___||___ | | 4309 || | | | -------- | | 4310 ||___ | | | ______ | |- 4311 // \ | | | // \| _| \ 4312 // \ ____|---|__________|______// \/ | 4313 || X | / || X | / 4314 \\ /\\____/ \\ /___/ 4315 \\_____/ ----- \\_____/--- 4316 ----- ----- 4317 .... 4318 ==== 4320 [.comment] 4321 tag::aside1[] 4322 // tag::aside[] 4324 **** 4325 While the exchange at the French-occupied castle is one of 4326 the more memorable scenes of _Monty Python and the Holy Grail_, 4327 the Trojan Rabbit has not reached the same level of cultural 4328 resonance as its more murderous counterpart. Reasons for this 4329 may include: 4331 * Less overall screen-time dedicated to the Trojan Rabbit. 4333 * The Trojan Rabbit as projectile has already been anticipated 4334 by the Cow as projectile. 4335 **** 4337 // end::aside[] 4339 [.comment] 4340 end::aside1[] 4342 [.comment] 4343 tag::note1[] 4344 // tag::note[] 4346 [NOTE,display=true,source=Author] 4347 ==== 4348 Image courtesy of 4349 https://camelot.gov.example/creatures-in-ascii/ 4350 ==== 4352 // end::note[] 4353 [.comment] 4354 end::note1[] 4356 [.comment] 4357 tag::comment1[] 4358 // tag::comment[] 4360 The exchange of projectile animals was the beginning of a 4361 long-running fruitful relationship between the British and the 4362 French peoples, 4363 [comment]#TODO: Will need to verify that claim.# which 4364 arguably predates the traditional English enmity with the 4365 French. [comment]#Strictly speaking, the Knights are Welsh.# 4367 [.comment] 4368 -- 4369 This document, as it turns out, has a profusion of XML comments. 4371 As expected, they are ignored in any rendering of the document. 4372 -- 4374 // end::comment[] 4375 [.comment] 4376 end::comment1[] 4378 [[caerbannog]] 4379 == The Mythos of Caerbannog 4381 [.comment] 4382 tag::xref1[] 4383 // tag::xref[] 4384 The _Cave of Caerbannog_ has been well-established in the mythology 4385 of Camelot (as recounted by Monty Python) as the lair of the 4386 Legendary Black Beast of Arrrghhh, more commonly known today as the 4387 *Killer Rabbit of Caerbannog* <>. 4388 It is the encounter between the Killer Rabbit of Caerbannog and the 4389 Knights of the Round Table, armed with the Holy Hand Grenade of 4390 Antioch (see the <>), 4391 that we 4392 recount here through monospace font and multiple spaces. 4394 [[killer_rabbit_caerbannog]] 4395 === The Killer Rabbit of Caerbannog 4397 // end::xref[] 4398 [.comment] 4399 end::xref1[] 4401 [.comment] 4402 tag::relref1[] 4403 // tag::relref[] 4405 The *Killer Rabbit of Caerbannog*, that most formidable foe of 4406 the Knights and of all that is holy or carrot-like, has been 4407 depicted diversely in lay and in song. We venture to say, 4408 _contra_ the claim made in <>, 4409 that the Killer Rabbit of Caerbannog truly is the most afeared 4410 of all the creatures. Short of sanctified ordnance such as 4411 <>, there are few remedies 4412 known against its awful lapine powers. 4414 // end::relref[] 4415 [.comment] 4416 end::relref1[] 4418 [.comment] 4419 tag::hyperlink1[] 4420 // tag::hyperlink[] 4422 <> of the fearsome 4423 beast 4424 has been sourced from 4425 http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], 4426 <> 4427 by C code that was used in this accurate depiction of the 4428 Killer Rabbit: 4430 // end::hyperlink[] 4431 [.comment] 4432 end::hyperlink1[] 4434 [.comment] 4435 tag::figure1[] 4436 // tag::figure1a[] 4438 [[killer-bunny]] 4439 .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret 4440 ==== 4441 [alt=The Killer Bunny, in ASCII] 4442 .... 4443 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4444 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 4445 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 4446 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 4447 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 4448 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 4449 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ 4450 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 4451 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 4452 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 4453 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 4454 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 4455 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 4456 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 4457 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 4458 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 4459 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 4460 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 4461 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 4462 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 4463 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 4464 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 4465 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 4466 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 4467 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 4468 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 4469 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 4470 MW \\/\||v v|| -\\-------___ . ., \ | 4471 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 4472 ) /--------^-^ ,. \|// 4473 # \(/ .\\|x// " ' ' 4474 . , \\||// \||\\\// \\ 4475 .... 4476 ==== 4478 [[killer-source]] 4479 .C Code To Lure Killer Rabbit Back To Cave 4480 ==== 4481 [source,c] 4482 ---- 4483 4484 /* Locate the Killer Rabbit */ 4485 int type; 4486 unsigned char *killerRabbit = 4487 LocateCreature(&caerbannog, "killer rabbit"); 4488 if( killerRabbit == 0 ){ 4489 puts("The Killer Rabbit of Caerbannog is out of town."); 4490 return LOST_CREATURE; 4491 } 4493 /* Load Cave */ 4494 unsigned char *cave = LoadPlace(&caerbannog, 4495 "The Cave Of Caerbannog"); 4496 if( cave == 0 ){ 4497 puts("The Cave of Caerbannog must have moved."); 4498 return LOST_PLACE; 4499 } 4501 /* Lure the Killer Rabbit back into the Cave */ 4502 unsigned char *carrot = allocateObjectInPlace( 4503 carrot("fresh"), cave); 4504 if( carrot == 0 ){ 4505 puts("No carrot, no rabbit."); 4506 return LOST_LURE; 4507 } 4509 /* Finally, notify the Killer Rabbit to act */ 4510 return notifyCreature(killerRabbit, &carrot); 4511 4512 ---- 4513 ==== 4515 // end::figure1a[] 4516 [.comment] 4517 end::figure1[] 4519 On the beast's encounter with the Knights of the Round Table, 4520 the following personnel engaged with it in combat: 4522 [.comment] 4523 tag::ul1[] 4524 // tag::ul[] 4526 * Killed 4527 ** Sir Bors 4528 ** Sir Gawain 4529 ** Sir Ector 4530 * Soiled Himself 4531 ** Sir Robin 4532 * Panicked 4533 ** King Arthur 4534 * Employed Ordnance 4535 ** The Lector 4536 ** Brother Maynard 4537 * Scoffed 4538 ** Tim the Enchanter 4540 // end::ul[] 4541 [.comment] 4542 end::ul1[] 4544 [[holy_hand_grenade]] 4545 === Holy Hand Grenade of Antioch 4547 [.comment] 4548 tag::figure2[] 4550 // tag::figure2a[] 4552 [[hand-grenade-figure]] 4553 .The Holy Hand Grenade of Antioch (don't pull the pin) 4554 ==== 4555 [alt=Holy Hand Grenade of Antioch, in ASCII] 4556 .... 4557 ______ 4558 \\/ \/ 4559 __\\ /__ 4560 || //\ | 4561 ||__\\/ __| 4562 || | ,---, 4563 || |====`\ | 4564 || | '---' 4565 ,--'*`--, 4566 _||#|***|#| 4567 _,/.-'#|* *|#`-._ 4568 ,,-'#####| |#####`-. 4569 ,,'########| |########`, 4570 //##########| o |##########\ 4571 ||###########| |###########| 4572 ||############| o |############| 4573 ||------------' '------------| 4574 ||o o o o o o o o o o| 4575 |-----------------------------| 4576 ||###########################| 4577 \\#########################/ 4578 `..#####################,' 4579 ``..###############_,' 4580 ``--.._____..--' 4581 `''-----''` 4582 .... 4583 ==== 4585 // end::figure2a[] 4587 [.comment] 4588 end::figure2[] 4590 [[sovereign-orb]] 4591 .The Sovereign's Orb made invisible 4592 ==== 4593 .Outlines of the Sovereign's Orb 4594 [link=https://camelot.gov.example/sovereigns_orb.jpg,align=right] 4595 image::https://camelot.gov.example/sovereigns_orb.jpg[Orb,124,135] 4596 ==== 4598 [.comment] 4599 tag::index1[] 4600 // tag::index[] 4602 The solution to the impasse at the ((Cave of Caerbannog)) was 4603 provided by the successful deployment of the 4604 *Holy Hand Grenade of Antioch* (see <>) 4605 (((Holy Hand Grenade of Antioch))). 4606 Any similarity between the Holy Hand Grenade of Antioch and the 4607 mythical _Holy Spear of Antioch_ is purely intentional; 4608 (((relics, Christian))) any similarity between the Holy Hand Grenade 4609 of Antioch and the _Sovereign's Orb of the United Kingdom_ 4610 (see <>) is putatively fortuitous. 4611 (((relics, monarchic))) 4613 // end::index[] 4614 [.comment] 4615 end::index1[] 4617 [.comment] 4618 tag::dl1[] 4619 // tag::dl[] 4621 Holy Hand Grenade of Antioch:: 4622 Ordnance deployed by Brother Maynard under the incantation of a 4623 lector, in order to dispense with the Foes of the Virtuous. 4624 See <>. 4626 Holy Spear of Antioch:: 4627 A supposed relic of the crucifixion of Jesus Christ, this is one 4628 of at least four claimed instances of the lance that pierced 4629 Christ's side. Its historical significance lies in inspiring 4630 crusaders to continue their siege of Antioch in 1098. 4632 Sovereign's Orb of the United Kingdom:: 4633 Part of the Crown Jewels of the United Kingdom, the Sovereign's 4634 Orb is a hollow gold sphere set with jewels and topped with a 4635 cross. It was made for Charles II in 1661. See 4636 <>. 4638 // end::dl[] 4639 [.comment] 4640 end::dl1[] 4642 [.comment] 4643 tag::bcp14_1[] 4644 // tag::bcp14[] 4646 The instructions in the _Book of Armaments_ on the proper deployment 4647 of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as 4648 follows, although this summary *SHALL NOT* be used as a substitute 4649 for a reading from the Book of Armaments: 4651 // end::bcp14[] 4652 [.comment] 4653 end::bcp14_1[] 4655 [.comment] 4656 tag::ol1[] 4657 // tag::ol[] 4659 . Preamble: St Attila Benediction 4660 . Feast of the People on Sundry Foods 4661 ** Lambs 4662 ** Sloths 4663 ** Carp 4664 ** Anchovies 4665 ** Orangutangs 4666 ** Breakfast Cereals 4667 ** Fruit Bats 4668 ** _et hoc genus omne_ 4669 . Take out the Holy Pin 4670 . The Count 4671 [upperalpha] 4672 .. Count is to Three: no more, no less 4673 .. Not Four 4674 .. Nor Two, except if the count then proceeds to Three 4675 .. Five is Right Out 4676 . Lob the Holy Hand Grenade of Antioch towards the Foe 4677 . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it 4679 // end::ol[] 4680 [.comment] 4681 end::ol1[] 4683 This could also be represented in pseudocode as follows: 4685 [.comment] 4686 tag::listcontinuationblock1[] 4687 // tag::listcontinuationblock[] 4689 . Take out the Holy Pin 4690 . The Count 4691 + 4692 ---- 4693 integer count; 4694 for count := 1 step 1 until 3 do 4695 say(count) 4696 comment Five is Right Out 4697 ---- 4698 . Lob the Holy Hand Grenade of Antioch towards the Foe 4699 . Foe snuffs it 4701 // end::listcontinuationblock[] 4702 [.comment] 4703 end::listcontinuationblock1[] 4705 == Dramatis Personae 4707 The following human (more-or-less) protagonists were involved 4708 in the two incidents recounted as lore of the Knights of the 4709 Round Table: 4711 [.comment] 4712 tag::table1[] 4713 // tag::table[] 4715 [grid=all,options="footer"] 4716 |=== 4717 |French Castle | Cave of Caerbannog 4719 2+|King Arthur 4720 2+|Patsy 4721 2+|Sir Bedevere the Wise 4722 2+|Sir Galahad the Pure 4723 2+|Sir Lancelot the Brave 4724 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot 4725 |French Guard with Outrageous Accent| Tim the Enchanter 4726 |Other French Guards | Brother Maynard 4727 | | The Lector 4728 .3+^|not yet recruited 4729 >|Sir Bors 4730 >|Sir Gawain 4731 >|Sir Ector 4733 |Retinue of sundry knights 4734 |Retinue of sundry more knights than at the French Castle 4735 |=== 4737 // end::table[] 4738 [.comment] 4739 end::table1[] 4741 === Past the Killer Rabbit 4743 Once the Killer Rabbit of Caerbannog (<>) had 4744 been 4745 dispatched, the Knights of the Round Table uncovered the last 4746 words of Joseph of Arimathea, inscribed on the Cave of Caerbannog 4747 in Aramaic. While the precise Aramaic wording has not survived, 4748 we trust the following Hebrew subtitles will serve as an 4749 acceptable substitute: 4751 [.comment] 4752 tag::hebrew1[] 4753 // tag::hebrew[] 4755 ____ 4756 .כאן אולי 4757 ימצאו 4758 המילים 4759 האחרונות של 4760 יוסף 4761 מארמתיה 4762 .מי אשר 4763 יהיה אמיץ 4764 ובעל נפש 4765 טהורה יוכל 4766 למצוא את 4767 הגביע הקדוש 4768 בטירת 4769 אאאאאאאה 4771 "Here may be found the last words of Joseph of Arimathea. 4772 He who is valiant and pure of spirit may find the Holy Grail 4773 in the castle of — Aaaargh." 4774 ____ 4776 // end::hebrew[] 4777 [.comment] 4778 end::hebrew1[] 4780 == IANA Considerations 4782 IANA might consider a registry to track the mythical, especially 4783 ravaging beasts, such as the Killer Rabbit, who haunt the Internet. 4785 == Security Considerations 4787 Do not let the Killer Rabbit out under any circumstance. 4789 I repeat. Do not let the Killer Rabbit (<>) 4790 out. 4792 [.comment] 4793 tag::bibliography1[] 4794 // tag::bibliography[] 4796 [bibliography] 4797 == Normative References 4798 ++++ 4799 4801 4802 Key words for use in RFCs to Indicate 4803 Requirement Levels 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 ++++ 4815 [bibliography] 4816 == Informative References 4817 ++++ 4819 4820 4821 Monty Python and the Holy Grail 4822 4823 4824 4825 4826 4827 4828 4829 4830 4832 4834 4835 DON'T SPEW A Set of Guidelines for Mass Unsolicited 4836 Mailings and Postings (spam*) 4837 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4851 4853 4854 RFC Format Framework 4855 4856 4857 4858 4859 4860 4861 4862 4864 4866 4867 4868 The Arte of ASCII: Or, An True and Accurate Representation of 4869 an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of 4870 Character 4871 4872 4873 4874 4875 4876 4877 4878 4879 4881 4883 4884 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 4885 Words 4886 4887 4888 4889 4890 RFC 2119 specifies common key words that may be 4891 used 4892 in protocol specifications. This document aims to reduce 4893 the ambiguity by clarifying that only UPPERCASE usage of the 4894 key words have the defined special meanings. 4895 4896 4897 4898 4899 4901 ++++ 4902 // end::bibliography[] 4903 [.comment] 4904 end::bibliography1[] 4905 4907 A.2.2. Rendered as RFC XML v3 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4926 4927 The Holy Hand Grenade of 4928 Antioch 4929 4931 4933 Camelot 4934
4935 4936 Palace 4937 Camel Lot 1 4938 Camelot 4939 England 4940 4941 arthur.pendragon@ribose.com 4942 http://camelot.gov.example 4943
4944 4945 4946 General 4947 Operations and Management 4948 rabbits 4949 grenades 4950 antioch 4951 camelot 4953 4954 4956 The menagerie of beasts and artefacts depicted in RFC8140 4957 may be usefully supplemented by other renowned figures of 4958 Internet and more general lore. This document extends the 4959 menagerie to the seminal fable of the 4960 "Holy Hand Grenade of Antioch", as depicted in the 4961 Monty Python film "Monty Python and the Holy Grail", 4962 as well as "Spamalot", the musical inspired by the 4963 movie. 4964 Spamalot 4965 The relevance of the musical "Spamalot" to Internet lore 4966 should be 4967 obvious to the reader; but in case of doubt, see also 4968 Section 1 ("What is Spam*?") of RFC2635. 4969 4971 4973 4975 4976
4977 Terminology 4978 The key words "MUST", 4979 "MUST NOT", 4980 "REQUIRED", 4981 "SHALL", 4982 "SHALL NOT", 4983 "SHOULD", "SHOULD 4984 NOT", "RECOMMENDED", 4985 "NOT RECOMMENDED", 4986 "MAY", and 4987 "OPTIONAL" in this document 4988 are to be interpreted as described in BCP 14 4990 when, and only when, they appear in all capitals, as shown 4991 here. 4992
4993
Introduction refers to the intended move of RFC formatting to 4996 XML2RFC v3 , in the following 4997 terms: 4999 5001 5003
5004 Although the RFC Editor has recently dragged the IETF kicking 5005 and 5006 screaming into the twentieth century [RFC7990] [RFC7996], there is a 5007 yearning among all right-thinking Internet architects to "keep it 5008 simple" and to return to the olden days when pigs could be given 5009 thrust without anyone taking undue offence. 5010
5012 5014 While no pigs, flying or otherwise, are involved in the 5015 transition 5016 to RFC XML v3, it is opportune to enhance the 5018 legendarium in the service of RFC XML v3, by illustrating its 5019 functionality through references to the mythology of Camelot, and 5020 particularly the incidents at the Cave of Caerbannog. 5022 5024 The screaming move into the 5025 twenty-first century is accompanied by 5026 a move back to the late twentieth century, with ASCII stylings more 5027 wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be 5028 accessible in 1996.) 5030 5032 There are two references to rabbits in 5033 Monty Python and the Holy Grail which are expounded 5034 on herewith: 5036 5038
5039
Trojan Rabbit
5040
5041 In their siege of the French-occupied castle which may 5042 already 5043 contain an instance of the Grail, Sir Bedevere the Wise proposes to 5044 use a Trojan Rabbit to infiltrate the castle, with a raiding party 5045 to take the French "not only by surprise, but totally 5046 unarmed." 5047 The proposal, unsurprisingly, proved abortive. The more so 5048 as the 5049 raiding party forgot to hide within the Trojan Rabbit, before the 5050 French soldiers took the Trojan Rabbit inside the castle. 5051
5052
Killer Rabbit of Caerbannog
5053
Guarding the entrance to the Cave of Caerbannog; see 5054 .
5055
5057 5058
5059
The French-occupied castle 5061 5063 The participants of that renowned exercise in cross-cultural 5064 communication, to wit the exchange between the 5065 Knights of the Round Table 5066 and the taunting French soldiers serving under Guy de 5067 Lombard are, 5068 properly speaking, outside the scope of this 5069 menagerie, being more 5070 or less human. Notwithstanding, severalish beasts 5071 both animated 5072 and wooden played a significant part in this encounter; most 5073 notably: 5074
    5075
  • The Projectile Cow, see
    • 5077
  • The Trojan Rabbit, see
    • 5079
5081 5083
5084 The Projectile Cow with an accompanying 5085 cannon 5086 .-.-.-.-.-.-.-.-.-.-.-.--.-.-.-.-.-.-.--.-.-.-.-.-.-.-.--.-. 5089 _-_---__--__--___-___-__-____---___-________---____-____-__- 5090 ._.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-…-.-.--..-.-.-.-.-.-..--.- 5091 ,..,.,.,.,.,..,.,,..,.,.,.,.,.,, ^^ .,,.,., ^^ .,.,.,.= 5092 _>-.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. 5093 /// .-.-.-.-. 5094 .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., 5095 .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # 5096 .,.,.,. 5097 .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. 5098 .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ‘ ‘! 5099 .,.,..,.,.- 5100 .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_] . ., . . , 5101 .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / 5102 -.-<>.,.,..-.-, 5103 .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. 5104 .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- 5105 .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. 5106 .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- 5107 .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- 5108 -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- 5109 ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, 5110 ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- 5111 ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. 5112 .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., 5113 .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,. 5114 ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,. 5115 ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. 5116 .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. 5117 -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> 5118 _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,., 5119 .._...{WITHHONEY}-.-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_> 5120 GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASS<GRASS>PC 5121 SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS 5122 CLAY_ROCKS_REBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY>< 5123 CLAY_CLAY_SKLETONS_MORESOIL_CLAY_CLAY_CLAY_CLAY_CLAY_VR 5124
5125
5126 The Trojan Rabbit with an automatic sliding 5127 door 5128 ___ ____ 5130 //_ \//\__\ 5131 || || | 5132 -__||_||__| 5133 // \--_ 5134 // ____ --___ 5135 // // \ \-_ 5136 // \\ @/ o || 5137 // ---- _____|| 5138 // // 5139 //\_//__ // 5140 //-- --- \____ // 5141 // --- \______ // 5142 // , . ----- \_//_ 5143 // ,. --- \____ 5144 // .,v --- \___ 5145 // __ -- \_ 5146 || , _______________ //|| |-_ 5147 || | |''''''''''| // || | | 5148 || ' | | | || | | 5149 || | | | || | | 5150 || " | | 0 | ___||___ | | 5151 || | | | -------- | | 5152 ||___ | | | ______ | |- 5153 // \ | | | // \| _| \ 5154 // \ ____|---|__________|______// \/ | 5155 || X | / || X | / 5156 \\ /\\____/ \\ /___/ 5157 \\_____/ ----- \\_____/--- 5158 ----- ----- 5159
5161 5163 5177 5179 5181 Image courtesy of 5182 5184 5185 5187 The exchange of projectile animals was the beginning of a 5188 long-running fruitful relationship between the British and the 5189 French peoples, 5191 5192 which 5193 arguably predates the traditional English enmity with the 5194 French. 5195 5196 5198 5203 5204
5205
The 5206 Mythos of Caerbannog 5207 5209 The Cave of Caerbannog has been 5210 well-established in the mythology 5211 of Camelot (as recounted by Monty Python) as the lair of the 5212 Legendary Black Beast of Arrrghhh, more commonly known today as the 5213 Killer Rabbit of Caerbannog . 5215 It is the encounter between the Killer Rabbit of Caerbannog and the 5216 Knights of the Round Table, armed with the Holy Hand Grenade of 5217 Antioch (see the following 5218 section), that we 5219 recount here through monospace font and multiple spaces. 5220
The Killer Rabbit of 5222 Caerbannog 5223 5225 5227 The Killer Rabbit of Caerbannog, 5228 that most formidable foe of 5229 the Knights and of all that is holy or carrot-like, has been 5230 depicted diversely in lay and in song. We venture to say, 5231 contra the claim made in Ze Vompyre, 5233 that the Killer Rabbit of Caerbannog truly is the most afeared 5234 of all the creatures. Short of sanctified ordnance such as 5235 , there are few 5236 remedies 5237 known against its awful lapine powers. 5239 5241 5243 The following 5244 depiction of the fearsome beast 5245 has been sourced from 5246 Rabbit-SCII, 5247 accompanied 5248 by C code that was used in this accurate depiction of the 5249 Killer Rabbit: 5251 5253 5255
5256 A Photo Of The Killer Rabbit of Caerbannog Taken In 5257 Secret 5258 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 5260 \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ 5261 \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ 5262 \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ 5263 \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ 5264 \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ 5265 \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ 5266 \MWMWMWMW##\\\\\\\ 5267 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ 5268 \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ 5269 \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## 5270 \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW 5271 \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW 5272 \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM 5273 \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW 5274 \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM 5275 MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW 5276 MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM 5277 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW 5278 MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW 5279 MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM 5280 MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW 5281 MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', 5282 MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` 5283 MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ 5284 MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' 5285 MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- 5286 MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ 5287 MW \\/\||v v|| -\\-------___ . ., \ | 5288 \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ 5289 ) /--------^-^ ,. \|// 5290 # \(/ .\\|x// " ' ' 5291 . , \\||// \||\\\// \\ 5292
5293
5294 C Code To Lure Killer Rabbit Back To Cave 5295 <CODE BEGINS> 5296 /* Locate the Killer Rabbit */ 5297 int type; 5298 unsigned char *killerRabbit = 5299 LocateCreature(&caerbannog, "killer rabbit"); 5300 if( killerRabbit == 0 ){ 5301 puts("The Killer Rabbit of Caerbannog is out of town."); 5302 return LOST_CREATURE; 5303 } 5305 /* Load Cave */ 5306 unsigned char *cave = LoadPlace(&caerbannog, 5307 "The Cave Of Caerbannog"); 5308 if( cave == 0 ){ 5309 puts("The Cave of Caerbannog must have moved."); 5310 return LOST_PLACE; 5311 } 5313 /* Lure the Killer Rabbit back into the Cave */ 5314 unsigned char *carrot = allocateObjectInPlace( 5315 carrot("fresh"), cave); 5316 if( carrot == 0 ){ 5317 puts("No carrot, no rabbit."); 5318 return LOST_LURE; 5319 } 5321 /* Finally, notify the Killer Rabbit to act */ 5322 return notifyCreature(killerRabbit, &carrot); 5323 <CODE ENDS> 5324
5325 5327 On the beast's encounter with the Knights of the Round Table, 5328 the following personnel engaged with it in combat: 5330 5332
    5333
  • 5334 Killed 5335
      5336
    • Sir Bors
      • 5337
    • Sir Gawain
      • 5338
    • Sir Ector
      • 5339
    5340
    • 5341
  • 5342 Soiled Himself 5343
      5344
    • Sir Robin
      • 5345
    5346
    • 5347
  • 5348 Panicked 5349
      5350
    • King Arthur
      • 5351
    5352
    • 5353
  • 5354 Employed Ordnance 5355
      5356
    • The Lector
      • 5357
    • Brother Maynard
      • 5358
    5359
    • 5360
  • 5361 Scoffed 5362
      5363
    • Tim the Enchanter
      • 5364
    5365
    • 5366
5368 5369
5370
Holy Hand Grenade of Antioch 5372 5373
5374 The Holy Hand Grenade of Antioch (don't pull the 5375 pin) 5376 5377 ______ 5378 \\/ \/ 5379 __\\ /__ 5380 || //\ | 5381 ||__\\/ __| 5382 || | ,---, 5383 || |====`\ | 5384 || | '---' 5385 ,--'*`--, 5386 _||#|***|#| 5387 _,/.-'#|* *|#`-._ 5388 ,,-'#####| |#####`-. 5389 ,,'########| |########`, 5390 //##########| o |##########\ 5391 ||###########| |###########| 5392 ||############| o |############| 5393 ||------------' '------------| 5394 ||o o o o o o o o o o| 5395 |-----------------------------| 5396 ||###########################| 5397 \\#########################/ 5398 `..#####################,' 5399 ``..###############_,' 5400 ``--.._____..--' 5401 `''-----''` 5402
5404 5406
5407 The Sovereign's Orb made invisible 5408 5411
5413 5415 The solution to the impasse at the Cave of Caerbannog was 5417 provided by the successful deployment of the 5418 Holy Hand Grenade of Antioch (see ) 5420 . 5422 Any similarity between the Holy Hand Grenade of Antioch and the 5423 mythical Holy Spear of Antioch is purely 5424 intentional; 5425 any similarity between 5426 the Holy Hand Grenade 5427 of Antioch and the Sovereign's Orb of the United 5428 Kingdom 5429 (see ) is putatively fortuitous. 5430 5432 5434 5436
5437
Holy Hand Grenade of Antioch
5438
Ordnance deployed by Brother Maynard under the incantation 5439 of a 5440 lector, in order to dispense with the Foes of the Virtuous. 5441 See .
5442
Holy Spear of Antioch
5443
A supposed relic of the crucifixion of Jesus Christ, this is 5444 one 5445 of at least four claimed instances of the lance that pierced 5446 Christ's side. Its historical significance lies in inspiring 5447 crusaders to continue their siege of Antioch in 1098.
5448
Sovereign's Orb of the United Kingdom
5449
Part of the Crown Jewels of the United Kingdom, the 5450 Sovereign's 5451 Orb is a hollow gold sphere set with jewels and topped with a 5452 cross. It was made for Charles II in 1661. See .
5454
5456 5458 5460 The instructions in the Book of Armaments 5461 on the proper deployment 5462 of the Holy Hand Grenade of Antioch MAY be 5463 summarized as 5464 follows, although this summary SHALL NOT be 5465 used as a substitute 5466 for a reading from the Book of Armaments: 5467 5469 5471
    5472
  1. Preamble: St Attila Benediction
    2. 5473
  2. 5474 Feast of the People on Sundry Foods 5475
      5476
    • Lambs
      • 5477
    • Sloths
      • 5478
    • Carp
      • 5479
    • Anchovies
      • 5480
    • Orangutangs
      • 5481
    • Breakfast Cereals
      • 5482
    • Fruit Bats
      • 5483
    • 5484 et hoc genus omne 5485
      • 5486
    5487
    3. 5488
  3. Take out the Holy Pin
    4. 5489
  4. 5490 The Count 5491
      5492
    1. Count is to Three: no more, no less
      2. 5493
    2. Not Four
      3. 5494
    3. Nor Two, except if the count then proceeds to 5495 Three
      4. 5496
    4. Five is Right Out
      5. 5497
    5498
    5. 5499
  5. Lob the Holy Hand Grenade of Antioch towards the 5500 Foe
    6. 5501
  6. The Foe, being naughty in the 5502 LORD's sight, 5503 SHALL snuff it
    7. 5504
5506 5508 This could also be represented in pseudocode as 5509 follows: 5511 5513
    5514
  1. Take out the Holy Pin
    2. 5515
  2. 5516 The Count 5517
    5518 integer count; 5519 for count := 1 step 1 until 3 do 5520 say(count) 5521 comment Five is Right Out 5522
    5523
    3. 5524
  3. Lob the Holy Hand Grenade of Antioch towards the 5525 Foe
    4. 5526
  4. Foe snuffs it
    5. 5527
5529 5530
5531
Dramatis 5533 PersonaeThe following human (more-or-less) 5534 protagonists were involved 5535 in the two incidents recounted as lore of the Knights of the 5536 Round Table: 5538 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5557 5558 5559 5560 5561 5562 5564 5565 5566 5568 5569 5570 5572 5573 5574 5575 5576 5577 5578 5579 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5598 5599 5600
French CastleCave of Caerbannog
King Arthur
Patsy
Sir Bedevere the 5556 Wise
Sir Galahad the Pure
Sir Lancelot the 5563 Brave
Sir Robin the 5567 Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous 5571 AccentTim the Enchanter
Other French GuardsBrother Maynard
5580 The Lector
not yet recruitedSir Bors
Sir Gawain
Sir Ector
Retinue of sundry knightsRetinue of sundry more knights than at the 5597 French Castle
5602 5604
Past the Killer 5606 RabbitOnce the Killer Rabbit of Caerbannog 5607 () had been 5608 dispatched, the Knights of the Round Table uncovered the last 5609 words of Joseph of Arimathea, inscribed on the Cave of Caerbannog 5610 in Aramaic. While the precise Aramaic wording has not survived, 5611 we trust the following Hebrew subtitles will serve as an 5612 acceptable substitute: 5614 5616
.כאן 5617 אולי 5618 ימצאו 5619 המילים 5620 האחרונות 5621 של יוסף 5622 מארמתיה 5623 .מי אשר 5624 יהיה 5625 אמיץ 5626 ובעל 5627 נפש 5628 טהורה 5629 יוכל 5630 למצוא 5631 את 5632 הגביע 5633 הקדוש 5634 בטירת 5635 אאאאאאאה 5636 "Here may be found the last words of Joseph of 5637 Arimathea. 5638 He who is valiant and pure of spirit may find the Holy Grail 5639 in the castle of — Aaaargh."
5641 5642
5643
5644 IANA Considerations 5645 IANA might consider a registry to track the mythical, 5646 especially 5647 ravaging beasts, such as the Killer Rabbit, who haunt the 5648 Internet. 5649
5650
Security 5652 ConsiderationsDo not let the Killer Rabbit out 5653 under any circumstance. 5654 I repeat. Do not let the Killer Rabbit () out. 5657 5658
5659 5660 5661 Normative References 5662 5665 5666 5667 Informative References 5668 5669 5670 Monty Python and the Holy Grail 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5683 5686 5689 5692 5693 5694 5695 5697 A.3. Example 3: "An API For Calendar-Based Fortune Heuristics Services" 5698 in AsciiRFC 5700 This example is available in the following formats: 5702 o AsciiRFC [git-divination-cfapi] 5704 o Internet-Draft [I-D.divination-cfapi] 5705 o Text, RFC XML, PDF and HTML on the IETF Datatracker 5706 [datatracker-divination-cfapi] 5708 A.3.1. In AsciiRFC 5710 5711 = An API For Calendar-Based Fortune Heuristics Services 5712 Gabriel Destiny; Charise Luck 5713 :doctype: internet-draft 5714 :abbrev: Calendar Fortune Heuristics API 5715 :name: draft-divination-cfapi-00 5716 :status: informational 5717 :ipr: trust200902 5718 :area: Internet 5719 :submission-type: independent 5720 :intended-series: informational 5721 :revdate: 2018-03-23T00:00:00Z 5722 :lastname: Destiny 5723 :fullname: Gabriel Destiny 5724 :forename_initials: G. 5725 :organization: Divination Inc. 5726 :email: gabriel.destiny@ribose.com 5727 :street: 9288 N Divine Street 5728 :city: Dunn 5729 :code: 28334 5730 :region: NC 5731 :country: United States of America 5732 :lastname_2: Luck 5733 :fullname_2: Charise Luck 5734 :forename_initials_2: C. 5735 :organization_2: Divination Inc. 5736 :email_2: charise.luck@ribose.com 5737 :street_2: 9288 N Divine Street 5738 :city_2: Dunn 5739 :code_2: 28334 5740 :region_2: NC 5741 :country_2: United States of America 5743 [.comment] 5744 tag::sample[] 5745 // tag::sample[] 5747 [abstract] 5749 This document describes a JSON HTTP API for online services that 5750 provide calendar-based fortune heuristics. 5752 == Introduction 5753 Fortune-telling, the practice of predicting information about a 5754 person's life, is an activity practiced throughout history. 5756 While there are myriad forms of fortune telling methodologies, this 5757 document applies to a particular form of service that provides fortune 5758 heuristics, commonly known as "luck", for a particular subject based 5759 on a calendar-based input. 5761 Since HTTP <> status codes are insufficient to 5762 convey 5763 information about fortune heuristics, this specification defines a 5764 simple JSON <> document format for this purpose. 5765 The 5766 response can be used by HTTP APIs to deliver results to non-human 5767 clients or to an end-user. 5769 == Conventions Used in This Document 5771 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 5772 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", 5773 "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document 5774 are to be interpreted as described in BCP 14 <> 5775 <> 5776 when, and only when, they appear in all capitals, as shown here. 5778 The following definitions apply in this document: 5780 Well-known URI:: This specification makes use of the "well-known URI" 5781 feature of HTTP servers <> to provide a 5782 bootstrapping URI for 5783 the client usage of fortune heuristics services. 5785 Root of Fortune:: The service discovery endpoint that provides a URI 5786 list of available fortune heuristic endpoints available, in accordance 5787 with <>. 5789 == Fortune Heuristics Service Well-Known URI 5791 A well-known URI called "fortune" is registered by this specification 5792 for fortune heuristics services (see <>). 5794 Services complying with this document *SHOULD* have its well-known 5795 URI pointing (directly or through redirection) to the Root of Fortune. 5797 The Root of Fortune can be used by the client for service discovery, 5798 namely, the available calendar-based fortune heuristics services 5799 available on the server, as specified in 5800 <>. 5802 === Well-Known URI Redirection 5804 Servers *MUST* redirect HTTP requests for that resource to the 5805 actual "context path" using one of the available mechanisms provided 5806 by HTTP <> (e.g., using a 301, 303, or 307 5807 response). 5809 Clients *MUST* handle HTTP redirects on the well-known URI. 5811 === Well-Known URI Cache Behavior 5813 Servers *SHOULD* set an appropriate Cache-Control header value (as 5814 according to <>) in the redirect response to 5815 set 5816 caching behavior as required by the type of response generated. 5818 == New HTTP Methods: SEEK and DIVINE 5820 This specification defines two new HTTP methods: "SEEK" and "DIVINE" 5821 methods for HTTP <>. 5823 While HTTP GET requests are treated equivalently as the "SEEK" and 5824 "DIVINE" requests, its usage is discouraged and therefore *SHOULD NOT* 5825 be used. 5827 Usage of these methods are defined in the sections below. 5829 == Defined Data Types: Date-Time Formats 5831 This specification defines a number of date-time formats as according 5832 to the conventions of <> for the unambiguous 5833 communication 5834 between client and server. 5836 The types defined are as follows. 5838 `DATETIME`:: 5839 As described in <>, with the addition that 5840 reduced 5841 accuracy representations described in <> 5842 are 5843 supported. Reduced accuracy date and times are accepted where a 5844 date or time component (2-digits long) is replaced by "--". 5846 + 5847 For example, the date time "2018-04---T01:02:00Z" represents the UTC 5848 time of 1:02am, on an unknown day within April of the year 2018. 5850 `DATE`:: 5851 As described in "DATETIME", but the "time" component will not be 5852 taken into account in the algorithm. 5854 [#service-discovery] 5855 == Fortune Heuristics Service Discovery 5857 [#root-of-fortune] 5858 === Root of Fortune Path URI ("/") 5860 The Root of Fortune URI, defined as "/" in this document, is used for 5861 service discovery on types of calendar-based fortune heuristics 5862 available. 5864 An empty SEEK request with the "application/json" request type 5865 *MUST* be sent to this endpoint to retrieve the available endpoints. 5866 All other HTTP methods *MUST NOT* be supported at this URI. 5868 An example of such a response is as follows: 5870 [source,json] 5871 ---- 5872 HTTP/1.1 200 Success 5873 Content-Type: application/json 5874 Content-Language: en 5876 { 5877 "diviners" : [ 5878 "/astrology", 5879 "/bazi", 5880 ] 5881 } 5882 ---- 5884 A service discovery object *MUST* have the following members: 5886 `diviners`:: 5887 (JSON array) 5888 An array that contains endpoints that conform to this specification. 5889 All endpoints listed here are relative to the Root of Fortune path. 5890 For example, the path "/astrology" listed in the example has an 5891 endpoint path of "[root-of-fortune]/astrology", where 5892 "[root-of-fortune]" indicates the real path of the Root of Fortune. 5894 // end::sample[] 5895 [.comment] 5896 end::sample[] 5898 [#service-endpoint] 5899 == Fortune Heuristics Service Endpoint 5901 An endpoint offering fortune heuristics services *MUST* adhere to 5902 specifications in this section. 5904 A service *MAY* implement multiple divination services based on 5905 different divination methods, such as the digital oracle shown 5906 in <>. 5908 [[digital-oracle]] 5909 .Dimensional Eye, a digital oracle that communicates through one button 5910 ==== 5911 [alt=An incarnation of the Dimensional Eye, in ASCII] 5912 .... 5913 __ 5914 __===^-\ 5915 __=== -\ 5916 __===- -\ 5917 __===- -\ 5918 ___===- -\ 5919 ===- ---__ -\ 5920 \\\ |||^^\ \__ -\ 5921 \\\ ||| \__ -\ 5922 \\\ ||| ______\_ -\ 5923 \\\ ||| _/-******\\__ -\ 5924 \\\ || /-****_****-\ \_ -\ 5925 \\\ || |-***/ \***-\ \_ -\ 5926 \\\ || |-***\___/***-| \ -\ 5927 \\\ || \-*********-/ __--/ -\ 5928 \\\ || \-******/__-- -\ 5929 \\\ || __-- -\ 5930 \\\ || __-- -\ 5931 \\\ ||__-- -\ 5932 \\\ -\ 5933 \\\ -\ 5934 \\\ -\ 5935 \\\ -\ 5936 \\\ __ -\ 5937 \\\ //##\\ -\ 5938 \\\ \\##// -\ 5939 \\\ ^^ __--==^ 5940 \\\ __--=== 5941 \\\ __--=== 5942 \\\ __--=== 5943 \\\ __--== 5944 \\= 5946 .... 5947 ==== 5949 [#endpoint-specification-request] 5950 === Service Specification Request 5952 To retrieve capabilities and parameters of an endpoint complying with 5953 this specification, a service specification JSON object is returned. 5955 An empty SEEK request with the "application/json" request type 5956 *MUST* be sent to this endpoint to retrieve the service 5957 specification that describes parameters accepted by this endpoint. 5959 Two examples of such a response are given below. 5961 [source,json] 5962 ---- 5963 HTTP/1.1 200 Success 5964 Content-Type: application/json 5965 Content-Language: en 5967 { 5968 "description": "Gaze into your upcoming luck!", 5969 "details": "https://divine.example.com/manual/astrology-api", 5970 "parameters": { 5971 "birthday": { 5972 "type": "DATE", 5973 "description": "Your birth date in UTC" 5974 }, 5975 "targetDateBegin": { 5976 "type": "DATE", 5977 "description": "Start of the target date range to report on" 5978 }, 5979 "targetDateEnd": { 5980 "type": "DATE", 5981 "description": "End of the target date range to report on" 5982 }, 5983 "interval": { 5984 "values": { 5985 "D": "Daily", 5986 "M": "Monthly", 5987 "Y": "Yearly" 5988 }, 5989 "description": "Available intervals to report on." 5990 } 5991 } 5992 } 5993 ---- 5995 [source,json] 5996 ---- 5997 HTTP/1.1 200 Success 5998 Content-Type: application/json 5999 Content-Language: en 6001 { 6002 "description": "Matches and mis-matches according to the " 6003 "Yin Yang and Five Elements techniques", 6004 "details": "https://divine.example.com/manual/bazi-api", 6005 "parameters": { 6006 "birthday": { 6007 "type": "DATETIME", 6008 "description": "Your birth date and time in UTC" 6009 }, 6010 "targetDateBegin": { 6011 "type": "DATETIME", 6012 "description": "Start of the target date/time range to report on" 6013 }, 6014 "targetDateEnd": { 6015 "type": "DATETIME", 6016 "description": "End of the target date/time range to report on" 6017 }, 6018 "interval": { 6019 "values": { 6020 "H": "Hourly", 6021 "D": "Daily", 6022 "M": "Monthly", 6023 "Y": "Yearly" 6024 }, 6025 "description": "Available intervals to report on." 6026 } 6027 } 6028 } 6029 ---- 6031 [#service-endpoint-specification] 6032 === Service Specification Object 6034 A service specification object *MUST* contain the following members. 6036 `description`:: 6037 (string) A short, human-readable summary of the fortune heuristic 6038 service at this endpoint. This *SHOULD* be a stable reference. 6040 `details`:: 6041 (URI, optional) A URI reference that provides further details for 6042 human consumption, such as API documentation that includes details of 6043 parameters accepted or response states. 6045 `parameters`:: 6046 (object, mandatory) An object that specifies what parameters 6047 are accepted by this endpoint. Each parameter key within this object 6048 specifies an accepted parameter name, and its value is a parameter 6049 specification object, which is described below. 6051 A parameter specification object *SHOULD* contain the following 6052 members: 6054 `type`:: 6055 (string, optional) The value type accepted by this parameter. Value 6056 types are described in this document. This member is mutually 6057 exclusive with `values`. 6059 `description`:: 6060 (string, mandatory) The purpose of this parameter. 6062 `values`:: 6063 (object, optional) The accepted values of this parameter, unlisted 6064 values *SHOULD* not be accepted by the parameter. Each key within 6065 this object specifies an accepted value, and its value provides a 6066 description of the purpose of the value. 6068 [#endpoint-report] 6069 == Fortune Heuristics Report Request and Response 6071 [#endpoint-report-request] 6072 === Fortune Heuristics Report Request 6074 A request using the HTTP "DIVINE" method and the "application/json" 6075 type *MUST* be sent to the fortune heuristic endpoint to retrieve 6076 results for a fortune heuristic query. 6078 The request made *MUST* conform to the specifications of the 6079 endpoint, as retrieved via the "SEEK" method described in 6080 <>. 6082 An example of a request is provided below. 6084 [source] 6085 ---- 6086 URI: /divination/astrology 6087 Method: DIVINE 6088 Content-Type: application/json 6089 Content-Language: en 6091 { 6092 "birthday": "1976-02-11T00:00:00Z", 6093 "targetDateBegin": "2018-01-01T00:00:00Z", 6094 "targetDateEnd": "2019-01-01T00:00:00Z", 6095 "interval": "M" 6096 } 6097 ---- 6099 [#endpoint-report-response] 6100 === Fortune Heuristics Report Response 6102 A fortune heuristic query using the "DIVINE" method triggers a 6103 response that contains a fortune heuristics report. 6105 A successful response returns a JSON object that *MUST* conform 6106 to the object structure described in this section. 6108 A report object *SHOULD* contain the following members: 6110 `type`:: 6111 (URI, mandatory) A URI that defines the type of the report located 6112 at the `report` key of this object. 6114 `report`:: 6115 (object, mandatory) An object that contains two keys, `intervals` 6116 and `events`. The `intervals` object contains an array of interval 6117 objects that matches the demanded intervals in the request within 6118 the target date range. 6119 The `events` object contains an array of significant event objects 6120 within the target date range. 6122 An example of a response is provided below. 6124 [source] 6125 ---- 6126 URI: /divination/astrology 6127 Method: DIVINE 6128 HTTP/1.1 200 Success 6129 Content-Type: application/json 6130 Content-Language: en 6131 { 6132 "type": "https://association-of.astrology/reports/monthly", 6133 "report": { 6134 "intervals": [ 6135 { 6136 "dateStart": "2018-01-01T00:00:00Z", 6137 "dateEnd": "2018-02-01T00:00:00Z", 6138 "categories": [ 6139 { 6140 "category": 6141 "https://divine.example.com/astrology/categories/health" 6142 "value": 80, 6143 "description": "Charge ahead with excellent health." 6144 }, 6145 { 6146 "category": 6147 "https://divine.example.com/astrology/categories/love" 6148 "value": 70, 6149 "description": 6150 "Give a certain person or situation another try!" 6151 }, 6152 { 6153 "category": 6154 "https://divine.example.com/astrology/categories/finance" 6155 "value": 5, 6156 "description": "You've just realized that you don't have 6157 any cash on hand." 6158 } 6159 ] 6160 }, 6161 { 6162 "dateStart": "2018-02-01T00:00:00Z", 6163 "dateEnd": "2018-03-01T00:00:00Z", 6164 "..." 6165 }, 6166 "..." 6167 ], 6168 "events": [ 6169 { 6170 "dateStart": "2018-01-15T03:20:00", 6171 "dateEnd": "2018-01-16T20:22:15", 6172 "description": "The planet of growth and good luck, Jupiter 6173 will make a harmonious connection with power planet Pluto, 6174 helping you connect with influential people", 6175 "recommendation": "Engage in networking during this time." 6176 }, 6177 { 6178 "dateStart": "2018-03-22T00:12:40", 6179 "dateEnd": "2018-03-28T02:45:03", 6180 "description": "Communication planet Mercury enters your sign, 6181 which will find you in a busier and chattier mood.", 6182 "recommendation": 6183 "Take charge of work with your newfound energy." 6184 } 6185 "..." 6186 ] 6187 } 6188 } 6189 ---- 6191 Fortune heuristic reports are created by a divination output that 6192 *MAY* requires quantitative interpretation. A sample representation of 6193 interpreting a graphical divination output is provided in 6194 <>. 6196 [[divination-message]] 6197 .Forty-nine yarrow sticks reveals a mystical message on fortune 6198 ==== 6199 [alt=A mystical pattern in ASCII] 6200 .... 6201 0000000000000000000000000 6202 0000000000000000000000001 G 1000000000000000000000000 6203 0000000000000000000000011 R 1100000000000000000000000 6204 0000000000000000000000111 A 1110000000000000000000000 6205 0000000000000000000001111 C 1111000000000000000000000 6206 0000000000000000000011111 E 1111100000000000000000000 6207 0000000000000000000111111 , 1111110000000000000000000 6208 0000000000000000001111111 1111111000000000000000000 6209 0000000011111111111111111 M 1111111111111111100000000 6210 0000000111111111111111111 E 1111111111111111110000000 6211 0000001111111111111111111 R 1111111111111111111000000 6212 0000011111111111111111111 C 1111111111111111111100000 6213 0000111111111111111111111 Y 1111111111111111111110000 6214 0001111111111111111111111 , 1111111111111111111111000 6215 0011111111111111111111111 1111111111111111111111100 6216 0111111111111111111111111 A 1111111111111111111111110 6217 0000000000000000011111111 N 1111111100000000000000000 6218 0000000000000000111111111 D 1111111110000000000000000 6219 0000000000000001111111111 1111111111000000000000000 6220 0000000000000011111111111 P 1111111111100000000000000 6221 0000000000000111111111111 E 1111111111110000000000000 6222 0000000000001111111111111 A 1111111111111000000000000 6223 0000000000011111111111111 C 1111111111111100000000000 6224 0000000000111111111111111 E 1111111111111110000000000 6225 0000000001111111111111111 . 1111111111111111000000000 6226 .... 6227 ==== 6229 [#endpoint-report-interval-obj] 6230 === Report Interval Object 6232 The `intervals` value of a report object contains a number of report 6233 intervals -- each representing a non-overlapping period of the 6234 selected interval length. When all of these intervals are put 6235 together, the combined period *MUST* fully cover the requested 6236 report target period. 6238 An example interval object is shown below. 6240 [source,json] 6241 ---- 6242 { 6243 "dateStart": "2018-01-01T00:00:00Z", 6244 "dateEnd": "2018-02-01T00:00:00Z", 6245 "categories": [ 6246 { 6247 "category": 6248 "https://divine.example.com/astrology/categories/health" 6249 "value": 80, 6250 "description": "Charge ahead with your excellent health." 6251 }, 6252 { 6253 "category": 6254 "https://divine.example.com/astrology/categories/love" 6255 "value": 70, 6256 "description": "Give a certain person or situation another try!" 6257 }, 6258 { 6259 "category": 6260 "https://divine.example.com/astrology/categories/finance" 6261 "value": 5, 6262 "description": "You've just realized that you don't have 6263 any cash on hand." 6264 } 6265 ] 6266 } 6267 ---- 6269 An interval object *MUST* contain the following members: 6271 `dateStart`:: 6273 (datetime, mandatory) This value specifies the start of the period 6274 which this interval object applies to. 6276 `dateEnd`:: 6277 (datetime, mandatory) This value specifies the end of the period 6278 which this interval object applies to. 6280 In the given example, the `categories` key is an implementation 6281 specific object that details heuristic results returned by the 6282 selected algorithm. This *MAY* differ in different algorithms. 6284 [#endpoint-report-event-obj] 6285 === Report Events Object 6287 The `events` value of a report object contains a number of event 6288 objects. Each event object represents an event relevant to the 6289 calculation of fortune heuristics during a target report period. These 6290 events *MAY* be of variable time lengths, and *MAY* be overlapping 6291 amongst each other. 6293 The following example demonstrates two event objects the service 6294 determines relevant to a user's query. 6296 [source,json] 6297 ---- 6298 { 6299 "dateStart": "2018-01-15T03:20:00", 6300 "dateEnd": "2018-01-16T20:22:15", 6301 "description": "The planet of growth and good luck, Jupiter will 6302 make a harmonious connection with power planet Pluto, helping you 6303 connect with influential people", 6304 "recommendation": "Engage in networking during this time." 6305 }, 6306 { 6307 "dateStart": "2018-03-22T00:12:40", 6308 "dateEnd": "2018-03-28T02:45:03", 6309 "description": "Communication planet Mercury enters your sign, 6310 which will find you in a busier and chattier mood.", 6311 "recommendation": "Take charge of work with your newfound energy." 6312 } 6313 ---- 6315 Similar to an interval object, an event object *MUST* contain the 6316 following members: 6318 `dateStart`:: 6319 (datetime, mandatory) This value specifies the start of the period 6320 described by the event. 6322 `dateEnd`:: 6323 (datetime, mandatory) This value specifies the end of the period 6324 described by the event. 6326 In the given example, the keys `description` and `recommendation` 6327 are implementation-specific details. This *MAY* differ in different 6328 algorithms. 6330 [#endpoint-report-errors] 6331 === Report Generation Errors 6333 This specification makes use of normal HTTP error codes with the 6334 following extensions. 6336 Errors *MUST* be returned using the Problem JSON Structure as 6337 accordance with <>. 6339 422 Unprocessable Entity:: 6340 For example, a malformed date-time parameter, or an illogical input, 6341 such as when the subject's birthday occurs after the report target 6342 date period. 6344 473 Beyond Existing Capability:: 6345 The service determines that the outcome is too difficult to predict. 6346 For example, in the case where the calculation is too complex to 6347 complete in a certain time period. The service *SHOULD* issue this 6348 response code to indicate that the client should not try the same 6349 request again. 6351 474 Outcome Impossible:: 6352 The service determines that the outcome is impossible. For example, 6353 when the algorithm determines that the subject will have deceased 6354 before the start of the requested target period. 6356 [#security] 6357 == Security Considerations 6359 * TLS <> and authenticated HTTP requests should be 6360 used to 6361 protect the DIVINE request and responses due to the personal nature 6362 of information transmitted. 6364 * A client *SHOULD* verify the identity of the server on every 6365 request to prevent impersonation or man-in-the-middle attacks, as data 6366 transmitted to and from the server is sensitive information, and at 6367 times critical information to the user. 6369 * Synchronization of client and server time *MUST* be 6370 well-considered in the implementation of this specification. A 6371 mismatch of client and server time *MAY* lead to algorithm 6372 miscalculations that can cause mistaken choices of a user that depends 6373 on the reliability of this system. 6375 [#iana] 6376 == IANA Considerations 6378 === Well-Known URI Registrations 6380 This document defines a well-known URI using the registration 6381 procedure and template from <>. 6383 ==== "fortune" Well-Known URI Registration 6385 URI suffix:: fortune 6387 Change controller:: IETF 6389 Specification document(s):: This document 6391 Related information:: N/A. 6393 [.comment] 6394 tag::sample[] 6395 // begin::sample[] 6397 [bibliography] 6398 == Normative References 6400 ++++ 6402 6404 6405 Key words for use in RFCs to Indicate Requirement 6406 Levels 6407 6408 6409 6410 6411 In many standards track documents several 6412 words are 6413 used to signify the requirements in the specification. These 6414 words are often capitalized. This document defines these words 6415 as they should be interpreted in IETF documents. This 6416 document specifies an Internet Best Current Practices for the 6417 Internet Community, and requests discussion and suggestions 6418 for improvements. 6419 6420 6421 6422 6423 6425 6427 6428 Defining Well-Known Uniform Resource Identifiers 6429 (URIs) 6430 6432 6433 6434 6436 6437 6438 6439 This memo defines a path prefix for 6440 "well-known 6441 locations", "/.well-known/", in 6442 selected Uniform 6443 Resource Identifier (URI) schemes. 6444 [STANDARDS-TRACK] 6445 6446 6447 6448 6450 6452 6453 Hypertext Transfer Protocol (HTTP/1.1): Message Syntax 6454 and 6455 Routing 6456 6458 6459 6460 6462 6463 6464 6465 The Hypertext Transfer Protocol (HTTP) is a 6466 stateless 6467 application-level protocol for distributed, collaborative, 6468 hypertext information systems. This document provides an 6469 overview of HTTP architecture and its associated terminology, 6470 defines the "http" and 6471 "https" Uniform 6472 Resource Identifier (URI) schemes, defines the HTTP/1.1 6473 message syntax and parsing requirements, and describes related 6474 security concerns for 6475 implementations. 6476 6477 6478 6479 6481 6483 6484 Hypertext Transfer Protocol (HTTP/1.1): 6485 Caching 6486 6488 6489 6490 6493 6494 6495 6497 6498 6499 6500 The Hypertext Transfer Protocol (HTTP) is a 6501 stateless 6502 \%application- level protocol for distributed, collaborative, 6503 hypertext information systems. This document defines HTTP 6504 caches and the associated header fields that control cache 6505 behavior or indicate cacheable response 6506 messages. 6507 6508 6509 6510 6512 6514 6515 Problem Details for HTTP APIs 6516 6518 6519 6520 6521 6522 6523 6524 This document defines a "problem 6525 detail" 6526 as a way to carry machine- readable details of errors in a 6527 HTTP response to avoid the need to define new error response 6528 formats for HTTP APIs. 6529 6530 6531 6532 6534 6536 6537 Ambiguity of Uppercase vs Lowercase in RFC 2119 Key 6538 Words 6539 6540 6541 6542 6543 RFC 2119 specifies common key words that 6544 may be used 6545 in protocol specifications. This document aims to reduce 6546 the ambiguity by clarifying that only UPPERCASE usage of the 6547 key words have the defined special 6548 meanings. 6549 6550 6551 6552 6553 6554 6556 6557 The JavaScript Object Notation (JSON) Data Interchange 6558 Format 6559 6561 6562 6563 6564 JavaScript Object Notation (JSON) is a 6565 lightweight, 6566 text-based, language-independent data interchange format. 6567 It was derived from the ECMAScript Programming Language 6568 Standard. JSON defines a small set of formatting rules for 6569 the portable representation of structured data. 6570 This document removes inconsistencies with other 6571 specifications of JSON, repairs specification errors, and 6572 offers experience-based interoperability 6573 guidance. 6574 6575 6576 6577 6578 6579 6580 ++++ 6582 [bibliography] 6583 == Informative References 6585 ++++ 6587 6589 6590 ISO/DIS 8601-1:2018, Data elements and interchange 6591 formats -- Information interchange -- Representation of dates 6592 and times -- Part 1: Basic rules 6593 6594 ISO/IEC 6595
6596 http://www.iso.org 6597
6598 6599 6600 6601 6602 6604 6606 6607 Date and Time on the Internet: Timestamps 6608 6609 6610 6611 6612 6613 6614 6615 6616 6617 6618 6620 6622 6623 The Transport Layer Security (TLS) Protocol 6624 Version 1.2 6625 6626 6627 6628 6630 6631 6632 6633 This document specifies Version 1.2 of the 6634 Transport 6635 Layer Security (TLS) protocol. The TLS protocol provides 6636 communications security over the Internet. The protocol 6637 allows client/server applications to communicate in a way 6638 that is designed to prevent eavesdropping, tampering, or 6639 message forgery. [STANDARDS-TRACK] 6640 6641 6642 6643 6644 ++++ 6646 [appendix] 6647 == Acknowledgements 6649 The authors thank the following individuals for their valuable 6650 feedback on this specification, and commend them for making fortune 6651 heuristics more accessible for the benefit of mankind. 6653 // end::sample[] 6654 [.comment] 6655 end::sample[] 6656 6658 A.4. Rendered as RFC XML v3 6660 6661 6662 6663 6664 6665 6666 6667 6668 6669 6670 6671 6674 6675 An API For 6676 Calendar-Based Fortune Heuristics Services 6677 6679 6681 6683 Divination Inc. 6684
6685 6686 9288 N Divine Street 6687 Dunn 6688 NC 6689 28334 6690 United States of America 6691 6692 gabriel.destiny@ribose.com 6693
6694 6695 6696 Divination Inc. 6697
6698 6699 9288 N Divine Street 6700 Dunn 6701 NC 6702 28334 6703 United States of America 6704 6705 charise.luck@ribose.com 6706
6707 6708 6709 Internet 6711 6712 6714 This document describes a JSON HTTP API for online services 6715 that 6716 provide calendar-based fortune heuristics. 6717 6718
IntroductionFortune-telling, 6720 the practice of predicting information about a 6721 person’s life, is an activity practiced throughout 6722 history. 6723 While there are myriad forms of fortune telling methodologies, 6724 this 6725 document applies to a particular form of service that provides fortune 6726 heuristics, commonly known as "luck", for a particular subject based 6727 on a calendar-based input. 6728 Since HTTP status codes are 6729 insufficient to convey 6730 information about fortune heuristics, this specification defines a 6731 simple JSON document format for this 6732 purpose. The 6733 response can be used by HTTP APIs to deliver results to non-human 6734 clients or to an end-user.
6735
Conventions Used in This 6737 DocumentThe key words 6738 "MUST", "MUST 6739 NOT", "REQUIRED", 6740 "SHALL", 6741 "SHALL NOT", 6742 "SHOULD", "SHOULD 6743 NOT", "RECOMMENDED", 6744 "NOT RECOMMENDED", 6745 "MAY", and 6746 "OPTIONAL" in this document 6747 are to be interpreted as described in BCP 14 6749 when, and only when, they appear in all capitals, as shown 6750 here. 6751 The following definitions apply in this document: 6752
6753
Well-known URI
6754
This specification makes use of the "well-known URI" 6755 feature of HTTP servers to provide a 6756 bootstrapping URI for 6757 the client usage of fortune heuristics services.
6758
Root of Fortune
6759
The service discovery endpoint that provides a URI 6760 list of available fortune heuristic endpoints available, in accordance 6761 with .
6762
6763
Fortune Heuristics Service Well-Known 6765 URIA well-known URI called "fortune" is registered 6766 by this specification 6767 for fortune heuristics services (see ). 6769 Services complying with this document 6770 SHOULD have its well-known 6771 URI pointing (directly or through redirection) to the Root of 6772 Fortune. 6773 The Root of Fortune can be used by the client for service 6774 discovery, 6775 namely, the available calendar-based fortune heuristics services 6776 available on the server, as specified in . 6778
Well-Known URI 6780 RedirectionServers MUST 6781 redirect HTTP requests for that resource to the 6782 actual "context path" using one of the available mechanisms provided 6783 by HTTP (e.g., using a 301, 303, or 307 6784 response). 6785 Clients MUST handle HTTP redirects 6786 on the well-known URI.
6787
6788 Well-Known URI Cache Behavior 6789 Servers SHOULD set an appropriate 6790 Cache-Control header value (as 6791 according to ) in the redirect response to set 6793 caching behavior as required by the type of response 6794 generated. 6795
6796
New HTTP Methods: SEEK and 6798 DIVINEThis specification defines two new HTTP 6799 methods: "SEEK" and "DIVINE" 6800 methods for HTTP . 6801 While HTTP GET requests are treated equivalently as the "SEEK" 6802 and 6803 "DIVINE" requests, its usage is discouraged and therefore 6804 SHOULD NOT 6805 be used. 6806 Usage of these methods are defined in the sections 6807 below.
6808
Defined Data Types: Date-Time 6810 FormatsThis specification defines a number of 6811 date-time formats as according 6812 to the conventions of for the unambiguous 6813 communication 6814 between client and server. 6815 The types defined are as follows. 6816
6817
6818 DATETIME 6819
6820
6821 As described in , with the addition that reduced 6823 accuracy representations described in are 6825 supported. Reduced accuracy date and times are accepted where a 6826 date or time component (2-digits long) is replaced by "--". 6827 For example, the date time "2018-04---T01:02:00Z" 6828 represents the UTC 6829 time of 1:02am, on an unknown day within April of the year 6830 2018. 6831
6832
6833 DATE 6834
6835
As described in "DATETIME", but the "time" component will 6836 not be 6837 taken into account in the algorithm.
6838
6839
6840 Fortune Heuristics Service Discovery 6841
Root of Fortune Path URI 6843 ("/")The Root of Fortune URI, defined as "/" in 6844 this document, is used for 6845 service discovery on types of calendar-based fortune heuristics 6846 available. 6847 An empty SEEK request with the "application/json" request type 6848 MUST be sent to this endpoint to retrieve the 6849 available endpoints. 6850 All other HTTP methods MUST NOT be supported 6851 at this URI. 6852 An example of such a response is as follows: 6853
6854 HTTP/1.1 200 Success 6855 Content-Type: application/json 6856 Content-Language: en 6858 { 6859 "diviners" : [ 6860 "/astrology", 6861 "/bazi", 6862 ] 6863 } 6864
6865 A service discovery object MUST have 6866 the following members: 6867
6868
6869 diviners 6870
6871
(JSON array) 6872 An array that contains endpoints that conform to this specification. 6873 All endpoints listed here are relative to the Root of Fortune path. 6874 For example, the path "/astrology" listed in the example has an 6875 endpoint path of "[root-of-fortune]/astrology", where 6876 "[root-of-fortune]" indicates the real path of the Root of 6877 Fortune.
6878
6880 6881
6882
6883
Fortune Heuristics Service 6885 EndpointAn endpoint offering fortune heuristics 6886 services MUST adhere to 6887 specifications in this section. 6888 A service MAY implement multiple 6889 divination services based on 6890 different divination methods, such as the digital oracle shown 6891 in . 6892
6893 Dimensional Eye, a digital oracle that communicates 6894 through one button 6895 __ 6897 __===^-\ 6898 __=== -\ 6899 __===- -\ 6900 __===- -\ 6901 ___===- -\ 6902 ===- ---__ -\ 6903 \\\ |||^^\ \__ -\ 6904 \\\ ||| \__ -\ 6905 \\\ ||| ______\_ -\ 6906 \\\ ||| _/-******\\__ -\ 6907 \\\ || /-****_****-\ \_ -\ 6908 \\\ || |-***/ \***-\ \_ -\ 6909 \\\ || |-***\___/***-| \ -\ 6910 \\\ || \-*********-/ __--/ -\ 6911 \\\ || \-******/__-- -\ 6912 \\\ || __-- -\ 6913 \\\ || __-- -\ 6914 \\\ ||__-- -\ 6915 \\\ -\ 6916 \\\ -\ 6917 \\\ -\ 6918 \\\ -\ 6919 \\\ __ -\ 6920 \\\ //##\\ -\ 6921 \\\ \\##// -\ 6922 \\\ ^^ __--==^ 6923 \\\ __--=== 6924 \\\ __--=== 6925 \\\ __--=== 6926 \\\ __--== 6927 \\= 6928 6929
6930
Service Specification 6932 RequestTo retrieve capabilities and parameters of 6933 an endpoint complying with 6934 this specification, a service specification JSON object is 6935 returned. 6936 An empty SEEK request with the "application/json" request type 6937 MUST be sent to this endpoint to retrieve the 6938 service 6939 specification that describes parameters accepted by this 6940 endpoint. 6941 Two examples of such a response are given below. 6942
6943 HTTP/1.1 200 Success 6944 Content-Type: application/json 6945 Content-Language: en 6947 { 6948 "description": "Gaze into your upcoming luck!", 6949 "details": "https://divine.example.com/manual/astrology-api", 6950 "parameters": { 6951 "birthday": { 6952 "type": "DATE", 6953 "description": "Your birth date in UTC" 6954 }, 6955 "targetDateBegin": { 6956 "type": "DATE", 6957 "description": "Start of the target date range to report on" 6958 }, 6959 "targetDateEnd": { 6960 "type": "DATE", 6961 "description": "End of the target date range to report on" 6962 }, 6963 "interval": { 6964 "values": { 6965 "D": "Daily", 6966 "M": "Monthly", 6967 "Y": "Yearly" 6968 }, 6969 "description": "Available intervals to report on." 6970 } 6971 } 6972 } 6973
6974
6975 HTTP/1.1 200 Success 6976 Content-Type: application/json 6977 Content-Language: en 6979 { 6980 "description": "Matches and mis-matches according to the " 6981 "Yin Yang and Five Elements techniques", 6982 "details": "https://divine.example.com/manual/bazi-api", 6983 "parameters": { 6984 "birthday": { 6985 "type": "DATETIME", 6986 "description": "Your birth date and time in UTC" 6987 }, 6988 "targetDateBegin": { 6989 "type": "DATETIME", 6990 "description": "Start of the target date/time range to report on" 6991 }, 6992 "targetDateEnd": { 6993 "type": "DATETIME", 6994 "description": "End of the target date/time range to report on" 6995 }, 6996 "interval": { 6997 "values": { 6998 "H": "Hourly", 6999 "D": "Daily", 7000 "M": "Monthly", 7001 "Y": "Yearly" 7002 }, 7003 "description": "Available intervals to report on." 7004 } 7005 } 7006 } 7007
7008
Service Specification 7010 ObjectA service specification object 7011 MUST contain the following members. 7012
7013
7014 description 7015
7016
(string) A short, human-readable summary of the fortune 7017 heuristic 7018 service at this endpoint. This SHOULD be a 7019 stable reference.
7020
7021 details 7022
7023
(URI, optional) A URI reference that provides further 7024 details for 7025 human consumption, such as API documentation that includes details of 7026 parameters accepted or response states.
7027
7028 parameters 7029
7030
(object, mandatory) An object that specifies what parameters 7031 are accepted by this endpoint. Each parameter key within this object 7032 specifies an accepted parameter name, and its value is a parameter 7033 specification object, which is described below.
7034
7035 A parameter specification object 7036 SHOULD contain the following 7037 members: 7038
7039
7040 type 7041
7042
(string, optional) The value type accepted by this 7043 parameter. Value 7044 types are described in this document. This member is mutually 7045 exclusive with values.
7046
7047 description 7048
7049
(string, mandatory) The purpose of this 7050 parameter.
7051
7052 values 7053
7054
(object, optional) The accepted values of this parameter, 7055 unlisted 7056 values SHOULD not be accepted by the 7057 parameter. Each key within 7058 this object specifies an accepted value, and its value provides a 7059 description of the purpose of the value.
7060
7061
Fortune Heuristics Report Request and 7063 Response
Fortune Heuristics Report 7065 RequestA request using the HTTP "DIVINE" method 7066 and the "application/json" 7067 type MUST be sent to the fortune heuristic 7068 endpoint to retrieve 7069 results for a fortune heuristic query. 7070 The request made MUST conform to the 7071 specifications of the 7072 endpoint, as retrieved via the "SEEK" method described in 7073 . 7074 An example of a request is provided below. 7075
7076 URI: /divination/astrology 7077 Method: DIVINE 7078 Content-Type: application/json 7079 Content-Language: en 7081 { 7082 "birthday": "1976-02-11T00:00:00Z", 7083 "targetDateBegin": "2018-01-01T00:00:00Z", 7084 "targetDateEnd": "2019-01-01T00:00:00Z", 7085 "interval": "M" 7086 } 7087
7088
Fortune Heuristics Report 7090 ResponseA fortune heuristic query using the 7091 "DIVINE" method triggers a 7092 response that contains a fortune heuristics report. 7093 A successful response returns a JSON object that 7094 MUST conform 7095 to the object structure described in this section. 7096 A report object SHOULD contain the 7097 following members: 7098
7099
7100 type 7101
7102
(URI, mandatory) A URI that defines the type of the report 7103 located 7104 at the report key of this object.
7105
7106 report 7107
7108
(object, mandatory) An object that contains two keys, 7109 intervals 7110 and events. The intervals 7111 object contains an array of interval 7112 objects that matches the demanded intervals in the request within 7113 the target date range. 7114 The events object contains an array of significant 7115 event objects 7116 within the target date range.
7117
7118 An example of a response is provided below. 7119
7120 URI: /divination/astrology 7121 Method: DIVINE 7122 HTTP/1.1 200 Success 7123 Content-Type: application/json 7124 Content-Language: en 7126 { 7127 "type": "https://association-of.astrology/reports/monthly", 7128 "report": { 7129 "intervals": [ 7130 { 7131 "dateStart": "2018-01-01T00:00:00Z", 7132 "dateEnd": "2018-02-01T00:00:00Z", 7133 "categories": [ 7134 { 7135 "category": 7136 "https://divine.example.com/astrology/categories/health" 7137 "value": 80, 7138 "description": "Charge ahead with excellent health." 7139 }, 7140 { 7141 "category": 7142 "https://divine.example.com/astrology/categories/love" 7143 "value": 70, 7144 "description": 7145 "Give a certain person or situation another try!" 7146 }, 7147 { 7148 "category": 7149 "https://divine.example.com/astrology/categories/finance" 7150 "value": 5, 7151 "description": "You've just realized that you don't have 7152 any cash on hand." 7153 } 7154 ] 7155 }, 7156 { 7157 "dateStart": "2018-02-01T00:00:00Z", 7158 "dateEnd": "2018-03-01T00:00:00Z", 7159 "..." 7160 }, 7161 "..." 7162 ], 7163 "events": [ 7164 { 7165 "dateStart": "2018-01-15T03:20:00", 7166 "dateEnd": "2018-01-16T20:22:15", 7167 "description": "The planet of growth and good luck, Jupiter 7168 will make a harmonious connection with power planet Pluto, 7169 helping you connect with influential people", 7170 "recommendation": "Engage in networking during this time." 7171 }, 7172 { 7173 "dateStart": "2018-03-22T00:12:40", 7174 "dateEnd": "2018-03-28T02:45:03", 7175 "description": "Communication planet Mercury enters your sign, 7176 which will find you in a busier and chattier mood.", 7177 "recommendation": 7178 "Take charge of work with your newfound energy." 7179 } 7180 "..." 7181 ] 7182 } 7183 } 7184
7185 Fortune heuristic reports are created by a divination output 7186 that 7187 MAY requires quantitative interpretation. A 7188 sample representation of 7189 interpreting a graphical divination output is provided in 7190 . 7191
7192 Forty-nine yarrow sticks reveals a mystical message on 7193 fortune 7194 7195 0000000000000000000000000 7196 0000000000000000000000001 G 1000000000000000000000000 7197 0000000000000000000000011 R 1100000000000000000000000 7198 0000000000000000000000111 A 1110000000000000000000000 7199 0000000000000000000001111 C 1111000000000000000000000 7200 0000000000000000000011111 E 1111100000000000000000000 7201 0000000000000000000111111 , 1111110000000000000000000 7202 0000000000000000001111111 1111111000000000000000000 7203 0000000011111111111111111 M 1111111111111111100000000 7204 0000000111111111111111111 E 1111111111111111110000000 7205 0000001111111111111111111 R 1111111111111111111000000 7206 0000011111111111111111111 C 1111111111111111111100000 7207 0000111111111111111111111 Y 1111111111111111111110000 7208 0001111111111111111111111 , 1111111111111111111111000 7209 0011111111111111111111111 1111111111111111111111100 7210 0111111111111111111111111 A 1111111111111111111111110 7211 0000000000000000011111111 N 1111111100000000000000000 7212 0000000000000000111111111 D 1111111110000000000000000 7213 0000000000000001111111111 1111111111000000000000000 7214 0000000000000011111111111 P 1111111111100000000000000 7215 0000000000000111111111111 E 1111111111110000000000000 7216 0000000000001111111111111 A 1111111111111000000000000 7217 0000000000011111111111111 C 1111111111111100000000000 7218 0000000000111111111111111 E 1111111111111110000000000 7219 0000000001111111111111111 . 7220 1111111111111111000000000 7221
7222
Report Interval 7224 ObjectThe intervals value of 7225 a report object contains a number of report 7226 intervals — each representing a 7227 non-overlapping period of the 7228 selected interval length. When all of these intervals are put 7229 together, the combined period MUST fully 7230 cover the requested 7231 report target period. 7232 An example interval object is shown below. 7233
7234 { 7235 "dateStart": "2018-01-01T00:00:00Z", 7236 "dateEnd": "2018-02-01T00:00:00Z", 7237 "categories": [ 7238 { 7239 "category": 7240 "https://divine.example.com/astrology/categories/health" 7241 "value": 80, 7242 "description": "Charge ahead with your excellent health." 7243 }, 7244 { 7245 "category": 7246 "https://divine.example.com/astrology/categories/love" 7247 "value": 70, 7248 "description": "Give a certain person or situation another try!" 7249 }, 7250 { 7251 "category": 7252 "https://divine.example.com/astrology/categories/finance" 7253 "value": 5, 7254 "description": "You've just realized that you don't have 7255 any cash on hand." 7256 } 7257 ] 7258 } 7259
7260 An interval object MUST contain the 7261 following members: 7262
7263
7264 dateStart 7265
7266
(datetime, mandatory) This value specifies the start of the 7267 period 7268 which this interval object applies to.
7269
7270 dateEnd 7271
7272
(datetime, mandatory) This value specifies the end of the 7273 period 7274 which this interval object applies to.
7275
7276 In the given example, the categories key 7277 is an implementation 7278 specific object that details heuristic results returned by the 7279 selected algorithm. This MAY differ in 7280 different algorithms.
7281
Report Events 7283 ObjectThe events value of a 7284 report object contains a number of event 7285 objects. Each event object represents an event relevant to the 7286 calculation of fortune heuristics during a target report period. These 7287 events MAY be of variable time lengths, and 7288 MAY be overlapping 7289 amongst each other. 7290 The following example demonstrates two event objects the 7291 service 7292 determines relevant to a user’s query. 7293
7294 { 7295 "dateStart": "2018-01-15T03:20:00", 7296 "dateEnd": "2018-01-16T20:22:15", 7297 "description": "The planet of growth and good luck, Jupiter will 7298 make a harmonious connection with power planet Pluto, helping you 7299 connect with influential people", 7300 "recommendation": "Engage in networking during this time." 7301 }, 7302 { 7303 "dateStart": "2018-03-22T00:12:40", 7304 "dateEnd": "2018-03-28T02:45:03", 7305 "description": "Communication planet Mercury enters your sign, 7306 which will find you in a busier and chattier mood.", 7307 "recommendation": "Take charge of work with your newfound energy." 7308 } 7309
7310 Similar to an interval object, an event object 7311 MUST contain the 7312 following members: 7313
7314
7315 dateStart 7316
7317
(datetime, mandatory) This value specifies the start of the 7318 period 7319 described by the event.
7320
7321 dateEnd 7322
7323
(datetime, mandatory) This value specifies the end of the 7324 period 7325 described by the event.
7326
7327 In the given example, the keys description 7328 and recommendation 7329 are implementation-specific details. This MAY 7330 differ in different 7331 algorithms.
7332
Report Generation 7334 ErrorsThis specification makes use of normal HTTP 7335 error codes with the 7336 following extensions. 7337 Errors MUST be returned using the 7338 Problem JSON Structure as 7339 accordance with . 7340
7341
422 Unprocessable Entity
7342
For example, a malformed date-time parameter, or an 7343 illogical input, 7344 such as when the subject’s birthday occurs after the report 7345 target 7346 date period.
7347
473 Beyond Existing Capability
7348
The service determines that the outcome is too difficult to 7349 predict. 7350 For example, in the case where the calculation is too complex to 7351 complete in a certain time period. The service 7352 SHOULD issue this 7353 response code to indicate that the client should not try the same 7354 request again.
7355
474 Outcome Impossible
7356
The service determines that the outcome is impossible. For 7357 example, 7358 when the algorithm determines that the subject will have deceased 7359 before the start of the requested target period.
7360
7361
7362 Security Considerations 7363
    7364
  • TLS and authenticated HTTP 7365 requests should be used to 7366 protect the DIVINE request and responses due to the personal nature 7367 of information transmitted.
    • 7368
  • A client SHOULD verify the 7369 identity of the server on every 7370 request to prevent impersonation or man-in-the-middle attacks, as data 7371 transmitted to and from the server is sensitive information, and at 7372 times critical information to the user.
    • 7373
  • Synchronization of client and server time 7374 MUST be 7375 well-considered in the implementation of this specification. A 7376 mismatch of client and server time MAY lead 7377 to algorithm 7378 miscalculations that can cause mistaken choices of a user that depends 7379 on the reliability of this system.
    • 7380
7381
7382
7383 IANA Considerations 7384
Well-Known URI 7386 RegistrationsThis document defines a well-known 7387 URI using the registration 7388 procedure and template from . 7390
"fortune" Well-Known URI 7392 Registration
7393
URI suffix
7394
fortune
7395
Change controller
7396
IETF
7397
Specification document(s)
7398
This document
7399
Related information
7400
N/A.
7401
7403 7404
7405
7406 7407 7408 Normative References 7409 7412 7415 7418 7421 7424 7427 7430 7431 7432 Informative References 7433 7435 7436 ISO/DIS 8601-1:2018, Data elements and interchange 7437 formats -- Information interchange -- Representation of dates 7438 and times -- Part 1: Basic rules 7439 7440 ISO/IEC 7441
7442 http://www.iso.org 7443
7444 7445 7446 7447 7448 7449 7452 7455 7456
AcknowledgementsThe 7458 authors thank the following individuals for their valuable 7459 feedback on this specification, and commend them for making fortune 7460 heuristics more accessible for the benefit of mankind. 7462 7463
7464 7465 7466 7468 Appendix B. Acknowledgements 7470 The authors would like to thank the following persons for their 7471 valuable advice and input. 7473 o Adrian Farrel for his comprehensive review of the document and 7474 numerous beneficial suggestions. 7476 Authors' Addresses 7478 Ronald Henry Tse 7479 Ribose 7480 Suite 1111, 1 Pedder Street 7481 Central, Hong Kong 7482 Hong Kong 7484 Email: ronald.tse@ribose.com 7485 URI: https://www.ribose.com 7487 Nick Nicholas 7488 Ribose 7489 Australia 7491 Email: nick.nicholas@ribose.com 7492 URI: https://www.ribose.com 7494 Jeffrey Lau 7495 Ribose 7496 Suite 1111, 1 Pedder Street 7497 Central, Hong Kong 7498 Hong Kong 7500 Email: jeffrey.lau@ribose.com 7501 URI: https://www.ribose.com 7502 Paolo Brasolin 7503 Ribose 7504 Italy 7506 Email: paolo.brasolin@ribose.com 7507 URI: https://www.ribose.com