Network Working Group R. Tse Internet-Draft N. Nicholas Intended status: Informational J. Lau Expires: September 24, 2018 P. Brasolin Ribose March 23, 2018 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc draft-ribose-asciirfc-06 Abstract This document describes an AsciiDoc syntax extension called AsciiRFC, designed for authoring IETF Internet-Drafts and RFCs. AsciiDoc is a human readable document markup language which affords more granular control over markup than comparable schemes such as Markdown. The AsciiRFC syntax is designed to allow the author to entirely focus on text, providing the full power of the resulting RFC XML through the AsciiDoc language, while abstracting away the need to manually edit XML, including references. This document itself was written and generated into RFC XML v2 (RFC7749) and RFC XML v3 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC generator. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on September 24, 2018. Tse, et al. Expires September 24, 2018 [Page 1] Internet-Draft AsciiRFC Specifications March 2018 Copyright Notice Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Designed for authoring RFCs and Internet-Drafts . . . . . 3 1.2. Relationship between AsciiRFC, AsciiDoc and Asciidoctor . 4 1.3. Comparison with RFC XML tools based on Markdown variants 4 2. Conventions Used in This Document . . . . . . . . . . . . . . 6 3. Document Structure and Syntax . . . . . . . . . . . . . . . . 6 3.1. Unsupported features compared with Asciidoctor syntax . . 7 3.2. Mapping To RFC XML syntax . . . . . . . . . . . . . . . . 8 3.3. Example Illustrations . . . . . . . . . . . . . . . . . . 9 3.4. Simple Illustration . . . . . . . . . . . . . . . . . . . 9 4. Header And Document Attributes . . . . . . . . . . . . . . . 24 4.1. Title And Basic Attributes . . . . . . . . . . . . . . . 24 4.2. Detailed Author Information . . . . . . . . . . . . . . . 26 4.3. XML Processing Information . . . . . . . . . . . . . . . 31 4.4. AsciiRFC-specific Document Attributes . . . . . . . . . . 32 5. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 35 6. Sections and Paragraphs . . . . . . . . . . . . . . . . . . . 37 7. Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 8. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 8.1. Basic Lists . . . . . . . . . . . . . . . . . . . . . . . 44 8.2. List Continuation . . . . . . . . . . . . . . . . . . . . 50 9. Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . . 53 10. Notes And Asides . . . . . . . . . . . . . . . . . . . . . . 54 11. Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . . 60 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts . 60 12.2. Formatting BCP 14 Keywords . . . . . . . . . . . . . . . 61 12.3. Escaping AsciiRFC Syntax . . . . . . . . . . . . . . . . 62 13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 14. Cross-References . . . . . . . . . . . . . . . . . . . . . . 64 14.1. Basic Referencing . . . . . . . . . . . . . . . . . . . 64 14.2. Referencing With Attributes . . . . . . . . . . . . . . 65 14.3. Indexing . . . . . . . . . . . . . . . . . . . . . . . . 66 15. Inclusions . . . . . . . . . . . . . . . . . . . . . . . . . 67 Tse, et al. Expires September 24, 2018 [Page 2] Internet-Draft AsciiRFC Specifications March 2018 16. Encoding and Entities . . . . . . . . . . . . . . . . . . . . 68 17. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 70 17.1. Using Raw RFC XML . . . . . . . . . . . . . . . . . . . 71 17.2. Preprocessing Using "asciidoctor-bibliography" . . . . . 74 18. RFC XML features not supported in Asciidoctor . . . . . . . . 77 19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 77 19.1. Using the "rfc-asciirfc-minimal" template . . . . . . . 77 19.2. Installing AsciiRFC Backend Processors . . . . . . . . . 77 19.3. Iterating AsciiRFC Content . . . . . . . . . . . . . . . 78 20. Security Considerations . . . . . . . . . . . . . . . . . . . 78 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 22. References . . . . . . . . . . . . . . . . . . . . . . . . . 79 22.1. Normative References . . . . . . . . . . . . . . . . . . 79 22.2. Informative References . . . . . . . . . . . . . . . . . 79 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 82 A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" . . . . 82 A.1.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 83 A.1.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 89 A.2. Example 2: "The Holy Hand Grenade of Antioch" . . . . . . 93 A.2.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 93 A.2.2. Rendered as RFC XML v3 . . . . . . . . . . . . . . . 111 A.3. Example 3: "An API For Calendar-Based Fortune Heuristics Services" in AsciiRFC . . . . . . . . . . . . . . . . . . 127 A.3.1. In AsciiRFC . . . . . . . . . . . . . . . . . . . . . 128 A.4. Rendered as RFC XML v3 . . . . . . . . . . . . . . . . . 148 Appendix B. Acknowledgements . . . . . . . . . . . . . . . . . . 165 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 165 1. Introduction This document describes a markup language called "AsciiRFC", developed specifically for the purpose of generating RFC XML document, based on Asciidoctor syntax. AsciiRFC can be used to generate compliant RFC XML v2 and v3 documents through the usage of an open source, MIT-licensed Ruby gem called "asciidoctor-rfc" written by the authors [asciidoctor-rfc]. 1.1. Designed for authoring RFCs and Internet-Drafts Internet-Drafts and RFCs intended for publication submission to the IETF can be written in a multitude of formats today, including: o XML: RFC XML v2 [RFC7749] and v3 [RFC7991] o nroff: through [NroffEdit] o Microsoft Word: through usage of [RFC5385] Tse, et al. Expires September 24, 2018 [Page 3] Internet-Draft AsciiRFC Specifications March 2018 o Lyx: through [lyx2rfc] o Pandoc: [RFC7328], through [pandoc2rfc] or [draftr] o Kramdown: through [kramdown-rfc2629] o mmark: through [mmark] Interestingly, the last three are Markdown [RFC7763] variants. As specified in [RFC7990], the IETF intends for the canonical format of RFCs to transition from plain-text ASCII to RFC XML v3 [RFC7991]. While plain-text will continue to be accepted from authors by the IETF, at least in the short- to medium-term, XML will be preferred for submission, and any plain-text submissions will need to be converted to RFC XML v3. While this need is already met for RFC XML v2 [RFC7749] by the tools specified above, the transition to RFC XML v3 [RFC7991] places added onus on authors to generate compliant XML. 1.2. Relationship between AsciiRFC, AsciiDoc and Asciidoctor [AsciiDoc] is a lightweight markup language and an alternative to Markdown, with features that make it attractive as a markup language for RFC with XML output. [Asciidoctor] is an open source, MIT-licensed Ruby implementation of [AsciiDoc] that provides an enhancement of the original AsciiDoc markup language. The variant of AsciiDoc syntax accepted by [Asciidoctor] is hereafter called "Asciidoctor syntax". AsciiRFC, as described in this document, is an AsciiDoc variant developed on Asciidoctor syntax, created for the purpose of generating RFC XML documents. 1.3. Comparison with RFC XML tools based on Markdown variants Section 1.2 of [RFC7764] famously states that "there is no such thing as 'invalid' Markdown, there is no standard demanding adherence to the Markdown syntax, and there is no governing body that guides or impedes its development." While there are contexts where that flexibility is useful, the authoring of RFCs does have a standard and a governing body, and there is such a thing as invalid RFC XML. A more rigorous and extensible counterpart to Markdown, which still preserves its basic approach to formatting, can generate RFC XML that Tse, et al. Expires September 24, 2018 [Page 4] Internet-Draft AsciiRFC Specifications March 2018 encompasses a fuller subset of the specification, and preempts malformed RFC XML output. The proposed markup language and associated Ruby gem has several advantages that we believe make it worth considering as an approach to generating RFC XML. o AsciiDoc was designed from the beginning as a publishing language: it was initially intended as a plain-text alternative to the DocBook XML schema. For that reason, Asciidoctor natively supports the full range of formatting required by RFC XML (including notes, tables, bibliographies, source-code blocks, and definition lists), without resorting to embedded HTML or Markdown "flavours". o AsciiRFC covers the full range of elements in RFC XML v2 and RFC XML v3. o AsciiDoc in its Ruby-based Asciidoctor implementation is extensible, with a well-defined API. (Extensions have been harnessed to deal with bibliographic preprocessing for AsciiRFC.) o AsciiRFC allows granular control of rendering, including user- specified attributes of text blocks. o The Asciidoctor implementation allows document inclusion, for managing large-scale documentation projects. o AsciiRFC allows granular control of permutations of block nesting, such as source code within lists or definition lists within unordered lists. o As a more formal counterpart to Markdown, AsciiDoc is well-suited to generating XML that needs to conform to a specified schema. The asciidoctor-rfc Ruby gem developed around AsciiDoc validates its RFC XML output against the RelaxNG schema defined for RFC XML, and reports any issues to the end user. o The asciidoctor-rfc Ruby gem incorporates validation not only of the XML structure of the standard, but also of the IETF workgroups it mentions against the latest listing online, and the bibliographic entries for RFC and other standards registered on . The gem also dynamically fetches bibliographic entries from the xml2rfc site, and uses them to populate the RFC XML document. As with Markdown, there is a wide range of tools that can render AsciiDoc; so AsciiRFC drafts of RFC documents can be previewed and accessed without depending on the RFC tools ecosystem. Our realisation of RFC XML in AsciiRFC has aimed to ensure that, as much Tse, et al. Expires September 24, 2018 [Page 5] Internet-Draft AsciiRFC Specifications March 2018 as possible, the markup language can be can be processed by generic Asciidoctor tools. The only exception to this as an add-on is the optional bibliography module, which allows bibliographies to be assembled on the fly based on citations in a document: see Section 17.2. 2. Conventions Used in This Document The following terms and definitions apply to this document: AsciiDoc The AsciiDoc markup language generically, as described in [AsciiDoc]. Asciidoctor syntax The enhanced AsciiDoc syntax implemented by the [Asciidoctor] Ruby gem. AsciiRFC The AsciiDoc syntax developed for the purpose of generating RFC XML document based on Asciidoctor syntax, as described in this document. 3. Document Structure and Syntax AsciiRFC consists of a subset of Asciidoctor syntax with the addition of bibliographic macros (Section 17.2). Asciidoctor syntax is presented in the Asciidoctor user manual [Asciidoctor-Manual]. AsciiRFC syntax consists of: o A document header, containing a title, a list of authors, and document attributes in lines prefixed with ":". o An optional document preamble, separated from the document header by a blank line, and not containing any section titles. o A number of sections, set off by a section title (a line prefixed with two or more "=".) A section may contain: o Other sections, whose level of nesting is indicated by the number of "=" in their header. o Blocks of text. Blocks can have metadata (including a title, an anchor for cross-references, and attributes.) Tse, et al. Expires September 24, 2018 [Page 6] Internet-Draft AsciiRFC Specifications March 2018 Blocks can be: o Paragraphs, which are terminated by blank lines. o Lists. List items are by default paragraphs, but can span over multiple paragraphs. o Delimited blocks (with a line delimiter on either side of them); these include tables, notes, sidebars, source code, block quotes, examples, and unprocessed content (e.g. raw XML). Delimited blocks contain by default one or more paragraphs. o List items can contain other blocks, including both nested lists and delimited blocks. o Some delimited blocks can contain other delimited blocks; for example, examples can contain source code as well as discussion in paragraphs. o Blocks of text consist of inline text, which itself can contain markup. Inline markup includes: o Text formatting: Bold, italic, superscript, subscript, monospace. o Markup macros: the "bcp14" and "comment" macros. (Asciidoctor syntax supports custom markup macros.) o URLs, including display text to render. o Inline anchors. o Cross-references to anchors (IDs of blocks or spans of text), including display text to render. o Images: SVG only, as specified in [RFC7996]. o Index terms. 3.1. Unsupported features compared with Asciidoctor syntax Several features from Asciidoctor are not supported within AsciiRFC due to the lack of support within RFC XML, including: o Audio and video files are not supported in AsciiRFC as today's RFC XML structure does not support audio or video. Tse, et al. Expires September 24, 2018 [Page 7] Internet-Draft AsciiRFC Specifications March 2018 o Equations are not supported as there is no current RFC XML equivalent. Asciidoctor provides native support for [AsciiMathML] and [TeX-LaTeX], via the [MathJax] tool. o Footnotes are not supported in AsciiRFC as there is no equivalent semantic representation in RFC XML. These carved out features can be easily supported by AsciiRFC once RFC XML allows these elements. 3.2. Mapping To RFC XML syntax The Asciidoctor syntax document structure aligns with both the RFC XML v2 and the RFC XML v3 structure. In the following, RFC XML v3 equivalences are given to the basic Asciidoctor structure. Header "" attributes, most "front" elements. Preamble "front/abstract" and "front/note". Sections "middle/section" elements. Sections with bibliography style attribute "back/references" elements. Sections with appendix style attribute "back/section" elements. Paragraphs "t" elements. Lists "ul", "ol", "dl" elements. Delimited blocks "artwork", "aside", "blockquote", "figure", "note", "sourcecode", "table". Inline markup "bcp14", "br", "cref", "em", "eref", "iref", "relref", "strong", "sub", "sup", "tt", "xref". Full details of the mapping of AsciiRFC elements to RFC XML v2 and v3 elements, and of how to convert AsciiRFC documents to RFC XML, are given in the documentation of [asciidoctor-rfc]. Tse, et al. Expires September 24, 2018 [Page 8] Internet-Draft AsciiRFC Specifications March 2018 3.3. Example Illustrations This document utilizes example documents provided in Appendix A for demonstration of AsciiRFC syntax and usage. The source files and published versions (at the IETF Datatracker) of these example documents are available in Appendix A. o "A Minimal Internet-Draft In AsciiRFC" Appendix A.1.1 o "The Holy Hand Grenade of Antioch" Appendix A.2.1 o "An API For Calendar-Based Fortune Heuristics Services" Appendix A.3.1 3.4. Simple Illustration This section gives an overview of how to create an RFC XML document in AsciiRFC, with some pitfalls to be aware of. Illustrations are in RFC XML v3 and RFC XML v2. A sample AsciiRFC document is provided in Figure 1, together with its corresponding rendering in: o RFC XML v3 (Figure 2) o RFC XML v2 (Figure 3) = A Minimal Internet-Draft In AsciiRFC :doctype: internet-draft :name: draft-asciirfc-minimal-01 :abbrev: AsciiRFC Example :status: informational :ipr: trust200902 :submissionType: individual :area: Internet :intended-series: full-standard :revdate: 2018-03-23T00:00:00Z :fullname: Josiah Stinkney Carberry :lastname: Carberry :forename_initials: J. S. :organization: Brown University :phone: +1 401 863 1000 :street: Box K, 69 Brown Street :city: Providence :code: 02912 :country: United States of America Tse, et al. Expires September 24, 2018 [Page 9] Internet-Draft AsciiRFC Specifications March 2018 :uri: https://www.brown.edu :email: josiah.carberry@ribose.com :fullname_2: Truman Grayson :lastname_2: Grayson :forename_initials_2: T. :organization_2: Brown University :phone_2: +1 401 863 1000 :street_2: Box G, 69 Brown Street :city_2: Providence :code_2: 02912 :country_2: United States of America :uri_2: https://www.brown.edu :email_2: truman.grayson@ribose.com [abstract] This document provides a template on how to author (or migrate!) a new Internet-Draft / RFC in AsciiRFC format. This template requires usage of the `asciidoctor-rfc` Ruby gem. [#introduction] == Introduction AsciiRFC <> is an extremely simple way to author Internet-Drafts and RFCs without needing to manually craft RFC XML <>. This is a template for authors to easily start with <>. [#conventions] == Terms and Definitions The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document are to be interpreted as described in BCP 14 <> <> when, and only when, they appear in all capitals, as shown here. //// Note: do not break formatted strings over carriage return. Bad things happen. (In this instance, the carriage return is suppressed, and no space takes its place.) This is an Asciidoctor issue, not an asciidoctor-rfc issue. Tse, et al. Expires September 24, 2018 [Page 10] Internet-Draft AsciiRFC Specifications March 2018 //// [#symbols] == Symbols And Abbreviations [#operators] === Operators AsciiRFC:: As defined in <>. [#security] == Security Considerations * Please beware of implementation issues caused by <>. * Here's how you include references <>, <>, <>. [#iana] == IANA Considerations This document does not require any action by IANA. [bibliography] == Normative References //bibliography::norm[] ++++ Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF Tse, et al. Expires September 24, 2018 [Page 11] Internet-Draft AsciiRFC Specifications March 2018 documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The "xml2rfc" Version 3 Vocabulary This document defines the "xml2rfc" version 3 vocabulary: an XML-based language used for writing RFCs and Internet-Drafts. It is heavily derived from the version 2 vocabulary that is also under discussion. This document obsoletes the v2 grammar described in RFC 7749. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Tse, et al. Expires September 24, 2018 [Page 12] Internet-Draft AsciiRFC Specifications March 2018 ++++ [bibliography] == Informative References //bibliography::info[] ++++ RNP: A C library approach to OpenPGP Ribose Inc.
Suite 1111, 1 Pedder Street Central Hong Kong Hong Kong open.source@ribose.com https://www.ribose.com
AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc This document describes an AsciiDoc syntax extension called AsciiRFC, designed for authoring IETF Internet-Drafts and RFCs. AsciiDoc is a human readable document markup language which affords more granular control over markup than comparable schemes such as Markdown. The AsciiRFC syntax is designed to allow the author to entirely focus on text, providing the full power of the resulting RFC XML through the AsciiDoc language, while abstracting away the need to manually edit XML, including references. This document itself was written and generated into RFC XML v2 (RFC7749) and RFC XML v3 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC generator. The SM4 Blockcipher Algorithm And Its Modes Of Operations This document describes the SM4 symmetric blockcipher algorithm published as GB/T 32907-2016 by the State Cryptography Administration of China (SCA). This document is a product of the Crypto Forum Research Group (CFRG). Tse, et al. Expires September 24, 2018 [Page 14] Internet-Draft AsciiRFC Specifications March 2018 The OCB Authenticated-Encryption Algorithm This document specifies OCB, a shared-key blockcipher-based encryption scheme that provides confidentiality and authenticity for plaintexts and authenticity for associated data. This document is a product of the Crypto Forum Research Group (CFRG). ++++ [appendix] [#appendix-a] == Examples === Example 1 Here's an example. [source,json] ---- { "code": { "encoding": "ascii", "type": "rfc", "authors": [ "Josiah Carberry", "Truman Grayson" ] } } ---- [#acknowledgements] == Acknowledgements Tse, et al. Expires September 24, 2018 [Page 15] Internet-Draft AsciiRFC Specifications March 2018 The authors would like to thank their families. Figure 1: Sample Internet-Draft in AsciiRFC The first block of text, from "= Template For Writing An Internet- Draft In AsciiRFC" through to ":email_2: thomas.kandell@brown.edu", is the document header. It contains a title in the first line, an author attribution ("Josiah Carberry; Thomas Kandell"), and then a set of document attributes, conveying information about the document as well as information about its authors. This information ends up in RFC XML either as attributes of the root "rfc" tag, elements of the "front" tag, or processing instructions. The following blocks of text, up until the first section header ("== Introduction"), are the document preamble. They are treated by the document converter as containing the document abstract ("abstract"), followed by any notes if present. Section headers delimit the sections of the main body of the document, starting with "== Introduction". The document converter treats the first section of the document as the start of the "middle" section in RFC XML. The first section header is followed by a paragraph, and other sections and paragraphs. The number of "=" signs can be one higher than that of the preceding section header, which indicates that they are subsections of that section; so "=== Operators" is a subsection of the preceding "== Symbols And Abbreviations". The paragraphs contain some inline formatting (e.g. boldface: "*MUST*", monospace: "`type`"), and sections can also contain blocks other than normal paragraphs; the section "== Operators", for example, contains a definition list (whose terms are delimited by "::"), and the subsection "=== Example 1" contains a code snippet (delimited by "----", and tagged with the style attribute "[source,json]", indicating that this is a JSON sourcecode listing). The document can also include comments ("//" for inline, "////" for blocks), which are not rendered when the document is processed. The introductory section in this example contains a citation of a reference, which in this version of AsciiRFC is treated identically to a cross-reference ("<>") -- the crossreference being to the references section of the document. Sections and blocks of texts within the document can also be the target of crossreferences; for example, the section header "=== Operators" is preceded by the anchor "[#operators]", and that anchor is already referenced in the section "== Security Considerations". Tse, et al. Expires September 24, 2018 [Page 16] Internet-Draft AsciiRFC Specifications March 2018 The third last and second last section are tagged with the style attribute "[bibliography]", which identifies them as references containers; the document converter accordingly inserts them into the "back" element under RFC XML. The contents of the references sections are in this instance raw XML, delimited as a passthrough block (with "++++"), which the converter does not alter. The final section is tagged with the style attribute "[appendix]", and is treated as such. The RFC XML v3 document generated from this AsciiRFC document is: A Minimal Internet-Draft In AsciiRFC Brown University
Box K, 69 Brown Street Providence 02912 United States of America +1 401 863 1000 josiah.carberry@ribose.com https://www.brown.edu
Brown University
Box G, 69 Brown Street Providence 02912 United States of America +1 401 863 1000 truman.grayson@ribose.com https://www.brown.edu
Internet This document provides a template on how to author (or migrate!) a new Internet-Draft / RFC in AsciiRFC format. This template requires usage of the asciidoctor-rfc Ruby gem.
IntroductionAsciiRFC is an extremely simple way to author Internet-Drafts and RFCs without needing to manually craft RFC XML . This is a template for authors to easily start with .
Terms and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. Tse, et al. Expires September 24, 2018 [Page 18] Internet-Draft AsciiRFC Specifications March 2018
Symbols And Abbreviations
Operators
AsciiRFC
As defined in .
Security Considerations
  • Please beware of implementation issues caused by .
  • Here’s how you include references , , .
IANA Considerations This document does not require any action by IANA.
Normative References Informative References RNP: A C library approach to OpenPGP Ribose Inc.
Tse, et al. Expires September 24, 2018 [Page 19] Internet-Draft AsciiRFC Specifications March 2018 Suite 1111, 1 Pedder Street Central Hong Kong Hong Kong open.source@ribose.com https://www.ribose.com
Examples
Example 1Here’s an example.
{ "code": { "encoding": "ascii", "type": "rfc", "authors": [ "Josiah Carberry", "Truman Grayson" ] } }
Acknowledgements The authors would like to thank their families.
Figure 2: Sample Internet-Draft In AsciiRFC, Output In RFC XML v3 Format Tse, et al. Expires September 24, 2018 [Page 20] Internet-Draft AsciiRFC Specifications March 2018 Some default processing instructions have already been prefixed to the XML. Our AsciiRFC converter can also generate RFC XML v2 from the same source AsciiRFC, as shown in Figure 3. Output in RFC XML v2 is not extensively described in this document. ]> A Minimal Internet-Draft In AsciiRFC Brown University
Box K, 69 Brown Street Providence 02912 United States of America +1 401 863 1000 josiah.carberry@ribose.com Tse, et al. Expires September 24, 2018 [Page 21] Internet-Draft AsciiRFC Specifications March 2018 https://www.brown.edu
Brown University
Box G, 69 Brown Street Providence 02912 United States of America +1 401 863 1000 truman.grayson@ribose.com https://www.brown.edu
Internet This document provides a template on how to author (or migrate!) a new Internet-Draft / RFC in AsciiRFC format. This template requires usage of the asciidoctor-rfc Ruby gem.
AsciiRFC is an extremely simple way to author Internet-Drafts and RFCs without needing to manually craft RFC XML . This is a template for authors to easily start with .
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.
As defined in .
Please beware of implementation issues caused by . Here’s how you include references , , .
This document does not require any action by IANA.
&RFC2119; &RFC7991; &RFC8174; RNP: A C library approach to OpenPGP Ribose Inc.
Suite 1111, 1 Pedder Street Central Hong Kong Tse, et al. Expires September 24, 2018 [Page 23] Internet-Draft AsciiRFC Specifications March 2018 Hong Kong open.source@ribose.com https://www.ribose.com
&I-D.ribose-asciirfc; &I-D.ribose-cfrg-sm4; &RFC7253;
Here’s an example.
{ "code": { "encoding": "ascii", "type": "rfc", "authors": [ "Josiah Carberry", "Truman Grayson" ] } }
The authors would like to thank their families.
Figure 3: Sample Internet-Draft In AsciiRFC, Output In RFC XML v2 Format 4. Header And Document Attributes The header gives the document title, followed by an optional author attribution, and a series of document attributes, with no empty lines. 4.1. Title And Basic Attributes Document attributes are used to populate attributes of the root "rfc" element, "front" elements, and document-level processing instructions. Tse, et al. Expires September 24, 2018 [Page 24] Internet-Draft AsciiRFC Specifications March 2018 o ":doctype:" determines whether the document will be considered "rfc" or "internet-draft", and interprets other attributes accordingly. o Certain attributes ("workgroup", "area", "keyword") are comma delimited, and result in repeated RFC XML elements. Figure 4 demonstrates how to set the document header in AsciiRFC, with its rendering in RFC XML v3 shown in Figure 5. = The Holy Hand Grenade of Antioch Arthur son of Uther Pendragon :doctype: internet-draft :abbrev: Hand Grenade of Antioch :updates: 8140 :submission-type: independent :name: draft-camelot-holy-grenade-00 :status: informational :consensus: false :area: General, Operations and Management :keyword: rabbits, grenades, antioch, camelot :ipr: trust200902 :toc-include: true :sort-refs: true :revdate: 2018-04-01 Figure 4: AsciiRFC Document Header Tse, et al. Expires September 24, 2018 [Page 25] Internet-Draft AsciiRFC Specifications March 2018 The Holy Hand Grenade of Antioch Camelot
Palace Camel Lot 1 Camelot antioch Figure 5: AsciiRFC Document Header Rendered As RFC XML v3 4.2. Detailed Author Information The document header can spell out further information about authors, including contact details. The AsciiRFC header is shown in Figure 6 with its rendering in RFC XML v3 shown in Figure 7. Tse, et al. Expires September 24, 2018 [Page 26] Internet-Draft AsciiRFC Specifications March 2018 = The Holy Hand Grenade of Antioch Arthur son of Uther Pendragon :doctype: internet-draft :abbrev: Hand Grenade of Antioch :updates: 8140 :submission-type: independent :name: draft-camelot-holy-grenade-00 :status: informational :consensus: false :area: General, Operations and Management :keyword: rabbits, grenades, antioch, camelot :ipr: trust200902 :toc-include: true :sort-refs: true :revdate: 2018-04-01 :fullname: Arthur son of Uther Pendragon :forename_initials: A. :lastname: Pendragon :email: arthur.pendragon@ribose.com :organization: Camelot :uri: http://camelot.gov.example :street: Palace\ Camel Lot 1 :city: Camelot :country: England :comments: yes Figure 6: AsciiRFC Document Header With One Author Tse, et al. Expires September 24, 2018 [Page 27] Internet-Draft AsciiRFC Specifications March 2018 The Holy Hand Grenade of Antioch Camelot
Palace Camel Lot 1 Camelot England arthur.pendragon@ribose.com http://camelot.gov.example
General Operations and Management rabbits grenades antioch camelot Figure 7: AsciiRFC Document Header With One Author (RFC XML v3) Details of a second, third etc. author, including their organization and contact details, are provided by suffixing the relevant author attributes with "_2", "_3" etc., as shown in Figure 8 and its RFC XML v3 rendering Figure 9. Tse, et al. Expires September 24, 2018 [Page 28] Internet-Draft AsciiRFC Specifications March 2018 = An API For Calendar-Based Fortune Heuristics Services Gabriel Destiny; Charise Luck :doctype: internet-draft :abbrev: Calendar Fortune Heuristics API :name: draft-divination-cfapi-00 :status: informational :ipr: trust200902 :area: Internet :submission-type: independent :intended-series: informational :revdate: 2018-03-23T00:00:00Z :lastname: Destiny :fullname: Gabriel Destiny :forename_initials: G. :organization: Divination Inc. :email: gabriel.destiny@ribose.com :street: 9288 N Divine Street :city: Dunn :code: 28334 :region: NC :country: United States of America :lastname_2: Luck :fullname_2: Charise Luck :forename_initials_2: C. :organization_2: Divination Inc. :email_2: charise.luck@ribose.com :street_2: 9288 N Divine Street :city_2: Dunn :code_2: 28334 :region_2: NC :country_2: United States of America Figure 8 Tse, et al. Expires September 24, 2018 [Page 29] Internet-Draft AsciiRFC Specifications March 2018 An API For Calendar-Based Fortune Heuristics Services Divination Inc.
9288 N Divine Street Dunn NC 28334 United States of America gabriel.destiny@ribose.com
Divination Inc.
9288 N Divine Street Dunn NC 28334 United States of America charise.luck@ribose.com
Internet Figure 9: AsciiRFC Document Header With Multiple Authors (RFC XML v3) Tse, et al. Expires September 24, 2018 [Page 30] Internet-Draft AsciiRFC Specifications March 2018 The initial author attribution in AsciiRFC, e.g. "Gabriel Destiny; Charlise Luck" in the example above, expects a strict format of First Name, zero or more Middle Names, Last name, and cannot process honorifics like "Dr." or suffixes like "Jr.". Name attributes with any degree of complexity should be overriden by using the ":fullname:" and ":lastname:" attributes. The AsciiRFC ":forename_initials:" attribute replaces the built-in Asciidoctor syntax ":initials:" attribute (which includes the surname initial), and is not automatically populated from the name attribution. 4.3. XML Processing Information A document header may also contain attribute headers which are treated as XML processing instructions. An AsciiRFC example is shown in Figure 10 with its rendering in Figure 11. (Note that several processing instructions are included by default in the output of the AsciiRFC processor.) = The Holy Hand Grenade of Antioch Arthur son of Uther Pendragon :doctype: internet-draft :abbrev: Hand Grenade of Antioch :updates: 8140 :submission-type: independent :name: draft-camelot-holy-grenade-00 :status: informational :consensus: false :ipr: trust200902 :notedraftinprogress: yes :smart-quotes: false Figure 10: AsciiRFC Document Header With XML Processing Information Tse, et al. Expires September 24, 2018 [Page 31] Internet-Draft AsciiRFC Specifications March 2018 The Holy Hand Grenade of Antioch Camelot
Palace Camel Lot 1 Camelot antioch Figure 11: AsciiRFC Document Header With XML Processing Information (RFC XML v3) In the foregoing, values for the processing instructions "strict", "compact", "toc" etc are included by default; but "comments" and "notedraftinprogress" are included as specified in the AsciiRFC document header. The default values provided for processing instructions can in fact be overriden through the AsciiRFC document header. 4.4. AsciiRFC-specific Document Attributes A few document attributes are specific to the operation of the RFC XML document converter: Tse, et al. Expires September 24, 2018 [Page 32] Internet-Draft AsciiRFC Specifications March 2018 :no-rfc-bold-bcp14: false overrides the wrapping by default of boldface uppercase BCP14 [RFC2119] words (e.g. "*MUST NOT*") with the "bcp14" element. :smart-quotes: false overrides Asciidoctor's conversion of straight quotes and apostrophes to smart quotes and apostrophes. :inline-definition-lists: true overrides the RFC XML v2 "idnits" requirement that a blank line be inserted between a definition list term and its definition. = The Holy Hand Grenade of Antioch Arthur son of Uther Pendragon :doctype: internet-draft :status: informational :name: draft-camelot-holy-grenade-00 == Section 1 The specification *MUST NOT* use the word _doesn't_. Figure 12: AsciiRFC Document Header Without RFC-specific Attributes Tse, et al. Expires September 24, 2018 [Page 33] Internet-Draft AsciiRFC Specifications March 2018 The Holy Hand Grenade of Antioch
Section 1 The specification MUST NOT use the word doesn’t.
Figure 13: AsciiRFC Document Header Without RFC-specific Attributes (RFC XML v3) = The Holy Hand Grenade of Antioch Arthur son of Uther Pendragon :doctype: internet-draft :status: informational :name: draft-camelot-holy-grenade-00 :no-rfc-bold-bcp14: false :smart-quotes: false == Section 1 The specification *MUST NOT* use the word _doesn't_. Figure 14: AsciiRFC Document Header With Overridden RFC-specific Attributes Tse, et al. Expires September 24, 2018 [Page 34] Internet-Draft AsciiRFC Specifications March 2018 The Holy Hand Grenade of Antioch
Section 1 The specification MUST NOT use the word doesn't.
Figure 15: AsciiRFC Document Header With Overridden RFC-specific Attributes (RFC XML v3) 5. Preamble The preamble in AsciiRFC is the text between the end of the document header (which terminates with a blank line) and the first section of text. Any paragraphs of text in the preamble are treated as an abstract, and may optionally be tagged with the "abstract" style attribute. Any notes in the preamble are treated as a "note" element. An example of setting the preamble is given in Figure 16 with its rendering in Figure 17. Tse, et al. Expires September 24, 2018 [Page 35] Internet-Draft AsciiRFC Specifications March 2018 [abstract] The menagerie of beasts and artefacts depicted in RFC8140 may be usefully supplemented by other renowned figures of Internet and more general lore. This document extends the menagerie to the seminal fable of the "Holy Hand Grenade of Antioch", as depicted in the Monty Python film "Monty Python and the Holy Grail", as well as "Spamalot", the musical inspired by the movie. [NOTE,remove-in-rfc=false] .Spamalot The relevance of the musical "Spamalot" to Internet lore should be obvious to the reader; but in case of doubt, see also Section 1 ("What is Spam*?") of RFC2635. Figure 16: AsciiRFC With Preamble The menagerie of beasts and artefacts depicted in RFC8140 may be usefully supplemented by other renowned figures of Internet and more general lore. This document extends the menagerie to the seminal fable of the "Holy Hand Grenade of Antioch", as depicted in the Monty Python film "Monty Python and the Holy Grail", as well as "Spamalot", the musical inspired by the movie. Spamalot The relevance of the musical "Spamalot" to Internet lore should be obvious to the reader; but in case of doubt, see also Section 1 ("What is Spam*?") of RFC2635. Figure 17: AsciiRFC With Preamble (RFC XML v3) Tse, et al. Expires September 24, 2018 [Page 36] Internet-Draft AsciiRFC Specifications March 2018 6. Sections and Paragraphs Section headers are given with a sequence of "=", where the number of instances of "=" gives the header level. The document itself opens with a single "=", and sections within it must be started with a minimum of "==". Section numbering is toggled with the in-document attribute ":sectnums:" (on), ":sectnums!:" (off). The boolean "toc" attribute can also be set on sections, indicating whether the section can be included in the document's table of contents. Figure 18 shows how sections and paragraphs are used in AsciiRFC, and its rendered form is shown in Figure 19. [toc=exclude] :sectnums!: == Terminology The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document are to be interpreted as described in BCP 14 <> <> when, and only when, they appear in all capitals, as shown here. :sectnums: == Introduction <> refers to the intended move of RFC formatting to XML2RFC v3 <>, in the following terms: Figure 18: AsciiRFC With Sections Tse, et al. Expires September 24, 2018 [Page 37] Internet-Draft AsciiRFC Specifications March 2018
Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.
Introduction refers to the intended move of RFC formatting to XML2RFC v3 , in the following terms: Figure 19: AsciiRFC With Sections (RFC XML v3) Note that skipped sections, such as defining a section using "====" within a section defined using "==", is not allowed in AsciiRFC syntax. Doing so will trigger an error with the following message: asciidoctor: WARNING: _filename_: line _X_: section title out of sequence: expected level 2, got level 3 7. Figures AsciiRFC examples (corresponding to RFC XML Figures), source code Listings, and Literals (preformatted text) are all delimited blocks. Listings and Literals can occur nested within Examples. An AsciiRFC example with a figure is given in Figure 20, and its rendering in Figure 21. Tse, et al. Expires September 24, 2018 [Page 38] Internet-Draft AsciiRFC Specifications March 2018 [[killer-bunny]] .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret ==== [alt=The Killer Bunny, in ASCII] .... \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ MW \\/\||v v|| -\\-------___ . ., \ | \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ ) /--------^-^ ,. \|// # \(/ .\\|x// " ' ' . , \\||// \||\\\// \\ .... ==== [[killer-source]] .C Code To Lure Killer Rabbit Back To Cave ==== [source,c] ---- /* Locate the Killer Rabbit */ int type; Tse, et al. Expires September 24, 2018 [Page 39] Internet-Draft AsciiRFC Specifications March 2018 unsigned char *killerRabbit = LocateCreature(&caerbannog, "killer rabbit"); if( killerRabbit == 0 ){ puts("The Killer Rabbit of Caerbannog is out of town."); return LOST_CREATURE; } /* Load Cave */ unsigned char *cave = LoadPlace(&caerbannog, "The Cave Of Caerbannog"); if( cave == 0 ){ puts("The Cave of Caerbannog must have moved."); return LOST_PLACE; } /* Lure the Killer Rabbit back into the Cave */ unsigned char *carrot = allocateObjectInPlace( carrot("fresh"), cave); if( carrot == 0 ){ puts("No carrot, no rabbit."); return LOST_LURE; } /* Finally, notify the Killer Rabbit to act */ return notifyCreature(killerRabbit, &carrot); ---- ==== Figure 20: AsciiRFC With A Figure
A Photo Of The Killer Rabbit of Caerbannog Taken In Secret \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ Tse, et al. Expires September 24, 2018 [Page 40] Internet-Draft AsciiRFC Specifications March 2018 \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ MW \\/\||v v|| -\\-------___ . ., \ | \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ ) /--------^-^ ,. \|// # \(/ .\\|x// " ' ' . , \\||// \||\\\// \\
C Code To Lure Killer Rabbit Back To Cave <CODE BEGINS> /* Locate the Killer Rabbit */ int type; unsigned char *killerRabbit = LocateCreature(&caerbannog, "killer rabbit"); if( killerRabbit == 0 ){ puts("The Killer Rabbit of Caerbannog is out of town."); return LOST_CREATURE; } /* Load Cave */ unsigned char *cave = LoadPlace(&caerbannog, "The Cave Of Caerbannog"); if( cave == 0 ){ puts("The Cave of Caerbannog must have moved."); return LOST_PLACE; } /* Lure the Killer Rabbit back into the Cave */ unsigned char *carrot = allocateObjectInPlace( Tse, et al. Expires September 24, 2018 [Page 41] Internet-Draft AsciiRFC Specifications March 2018 carrot("fresh"), cave); if( carrot == 0 ){ puts("No carrot, no rabbit."); return LOST_LURE; } /* Finally, notify the Killer Rabbit to act */ return notifyCreature(killerRabbit, &carrot); <CODE ENDS>
Figure 21: AsciiRFC With A Figure (RFC XML v3) If an AsciiRFC Listing or Literal occurs outside of an Example (Figure 22), the RFC XML converter will supply the surrounding Figure element (Figure 23). [[hand-grenade-figure]] .The Holy Hand Grenade of Antioch (don't pull the pin) Figure 22: AsciiRFC With ASCII Art Without Figure Wrapping Tse, et al. Expires September 24, 2018 [Page 42] Internet-Draft AsciiRFC Specifications March 2018 ______ \\/ \/ __\\ /__ || //\ | ||__\\/ __| || | ,---, || |====`\ | || | '---' ,--'*`--, _||#|***|#| _,/.-'#|* *|#`-._ ,,-'#####| |#####`-. ,,'########| |########`, //##########| o |##########\ ||###########| |###########| ||############| o |############| ||------------' '------------| ||o o o o o o o o o o| |-----------------------------| ||###########################| \\#########################/ `..#####################,' ``..###############_,' ``--.._____..--' `''-----''` Tse, et al. Expires September 24, 2018 [Page 43] Internet-Draft AsciiRFC Specifications March 2018
The Holy Hand Grenade of Antioch (don't pull the pin) ______ \\/ \/ __\\ /__ || //\ | ||__\\/ __| || | ,---, || |====`\ | || | '---' ,--'*`--, _||#|***|#| _,/.-'#|* *|#`-._ ,,-'#####| |#####`-. ,,'########| |########`, //##########| o |##########\ ||###########| |###########| ||############| o |############| ||------------' '------------| ||o o o o o o o o o o| |-----------------------------| ||###########################| \\#########################/ `..#####################,' ``..###############_,' ``--.._____..--' `''-----''`
Figure 23: AsciiRFC With ASCII Art Without Figure Wrapping (RFC XML v3) 8. Lists 8.1. Basic Lists AsciiRFC supports ordered, unordered, and definition lists. Indentation of ordered and unordered lists is indicated by repeating the list item prefix ("*" and "." respectively); for definition lists, it is indicated by incrementing the number of definition term delimiters ("::"). Tse, et al. Expires September 24, 2018 [Page 44] Internet-Draft AsciiRFC Specifications March 2018 List attributes can be used to specify the type of symbol used for ordered lists. An example of an unordered list is shown in Figure 24 (with its rendered version in Figure 25). An example of an ordered list with ordered and unordered sublists is shown in Figure 26 (with its rendered version in Figure 27). An example of a definition list is shown in Figure 28 (with its rendered version in Figure 29). * Killed ** Sir Bors ** Sir Gawain ** Sir Ector * Soiled Himself ** Sir Robin * Panicked ** King Arthur * Employed Ordnance ** The Lector ** Brother Maynard * Scoffed ** Tim the Enchanter Figure 24: AsciiRFC With Unordered lists Tse, et al. Expires September 24, 2018 [Page 45] Internet-Draft AsciiRFC Specifications March 2018
  • Killed
    • Sir Bors
    • Sir Gawain
    • Sir Ector
  • Soiled Himself
    • Sir Robin
  • Panicked
    • King Arthur
  • Employed Ordnance
    • The Lector
    • Brother Maynard
  • Scoffed
    • Tim the Enchanter
Figure 25: AsciiRFC With Unordered Lists (RFC XML v3) Tse, et al. Expires September 24, 2018 [Page 46] Internet-Draft AsciiRFC Specifications March 2018 . Preamble: St Attila Benediction . Feast of the People on Sundry Foods ** Lambs ** Sloths ** Carp ** Anchovies ** Orangutangs ** Breakfast Cereals ** Fruit Bats ** _et hoc genus omne_ . Take out the Holy Pin . The Count [upperalpha] .. Count is to Three: no more, no less .. Not Four .. Nor Two, except if the count then proceeds to Three .. Five is Right Out . Lob the Holy Hand Grenade of Antioch towards the Foe . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it Figure 26: AsciiRFC With Ordered lists Tse, et al. Expires September 24, 2018 [Page 47] Internet-Draft AsciiRFC Specifications March 2018
  1. Preamble: St Attila Benediction
  2. Feast of the People on Sundry Foods
    • Lambs
    • Sloths
    • Carp
    • Anchovies
    • Orangutangs
    • Breakfast Cereals
    • Fruit Bats
    • et hoc genus omne
  3. Take out the Holy Pin
  4. The Count
    1. Count is to Three: no more, no less
    2. Not Four
    3. Nor Two, except if the count then proceeds to Three
    4. Five is Right Out
  5. Lob the Holy Hand Grenade of Antioch towards the Foe
  6. The Foe, being naughty in the LORD's sight, SHALL snuff it
Figure 27: AsciiRFC With Ordered Lists (RFC XML v3) Tse, et al. Expires September 24, 2018 [Page 48] Internet-Draft AsciiRFC Specifications March 2018 Holy Hand Grenade of Antioch:: Ordnance deployed by Brother Maynard under the incantation of a lector, in order to dispense with the Foes of the Virtuous. See <>. Holy Spear of Antioch:: A supposed relic of the crucifixion of Jesus Christ, this is one of at least four claimed instances of the lance that pierced Christ's side. Its historical significance lies in inspiring crusaders to continue their siege of Antioch in 1098. Sovereign's Orb of the United Kingdom:: Part of the Crown Jewels of the United Kingdom, the Sovereign's Orb is a hollow gold sphere set with jewels and topped with a cross. It was made for Charles II in 1661. See <>. Figure 28: AsciiRFC With Definition lists
Holy Hand Grenade of Antioch
Ordnance deployed by Brother Maynard under the incantation of a lector, in order to dispense with the Foes of the Virtuous. See .
Holy Spear of Antioch
A supposed relic of the crucifixion of Jesus Christ, this is one of at least four claimed instances of the lance that pierced Christ's side. Its historical significance lies in inspiring crusaders to continue their siege of Antioch in 1098.
Sovereign's Orb of the United Kingdom
Part of the Crown Jewels of the United Kingdom, the Sovereign's Orb is a hollow gold sphere set with jewels and topped with a cross. It was made for Charles II in 1661. See .
Figure 29: AsciiRFC With Definition Lists (RFC XML v3) Tse, et al. Expires September 24, 2018 [Page 49] Internet-Draft AsciiRFC Specifications March 2018 8.2. List Continuation A list item by default spans a single paragraph. A following paragraph or other block element can be appended to the current list item by prefixing it with "+" in a separate line. See the "List Continuation" section in [Asciidoctor-Manual] for more information. An example of list continuation with text is shown in Figure 30 with its rendered version in Figure 31. Trojan Rabbit:: In their siege of the French-occupied castle which may already contain an instance of the Grail, Sir Bedevere the Wise proposes to use a Trojan Rabbit to infiltrate the castle, with a raiding party to take the French "not only by surprise, but totally unarmed." + The proposal, unsurprisingly, proved abortive. The more so as the raiding party forgot to hide within the Trojan Rabbit, before the French soldiers took the Trojan Rabbit inside the castle. Killer Rabbit of Caerbannog:: Guarding the entrance to the Cave of Caerbannog; see <>. Figure 30: AsciiRFC List With Text Continuation Tse, et al. Expires September 24, 2018 [Page 50] Internet-Draft AsciiRFC Specifications March 2018
Trojan Rabbit
In their siege of the French-occupied castle which may already contain an instance of the Grail, Sir Bedevere the Wise proposes to use a Trojan Rabbit to infiltrate the castle, with a raiding party to take the French "not only by surprise, but totally unarmed." The proposal, unsurprisingly, proved abortive. The more so as the raiding party forgot to hide within the Trojan Rabbit, before the French soldiers took the Trojan Rabbit inside the castle.
Killer Rabbit of Caerbannog
Guarding the entrance to the Cave of Caerbannog; see .
Figure 31: AsciiRFC List With Text Continuation (RFC XML v3) (Multiple paragraphs are not permitted within a list item in RFC XML v2. The RFC XML converter deals with this by converting paragraph breaks into line breaks within a list item.) List continuations can also be embedded to populate a list item with a sequence of blocks as a unit (in an Asciidoctor syntax open block). An example of list continuation with a delimited block is shown in Figure 32 with its rendered version in Figure 33. Tse, et al. Expires September 24, 2018 [Page 51] Internet-Draft AsciiRFC Specifications March 2018 . Take out the Holy Pin . The Count + ---- integer count; for count := 1 step 1 until 3 do say(count) comment Five is Right Out ---- . Lob the Holy Hand Grenade of Antioch towards the Foe . Foe snuffs it Figure 32: AsciiRFC List With Block Continuation
  1. Take out the Holy Pin
  2. The Count
    integer count; for count := 1 step 1 until 3 do say(count) comment Five is Right Out
  3. Lob the Holy Hand Grenade of Antioch towards the Foe
  4. Foe snuffs it
Figure 33: AsciiRFC List With Block Continuation (RFC XML v3) AsciiDoc, and thus AsciiRFC, considers paragraphs to be the basic level of blocks, and does not permit lists to be nested within them: any text after a list is considered to be a new paragraph. Therefore, markup as shown in Figure 34 cannot be generated via AsciiRFC. Tse, et al. Expires September 24, 2018 [Page 52] Internet-Draft AsciiRFC Specifications March 2018 This is the start of a paragraph.
  • List Entry 1
  • List Entry 2 Note 2.
And this is the continuation of the paragraph.
Figure 34: This RFC XML v3 Output Cannot Be Generated Using AsciiRFC 9. Blockquotes Asciidoctor syntax supports blockquotes and quotations of verse; its block quotations permit arbitrary levels of quote nesting. RFC XML v3, and thus AsciiRFC, only supports one level of blockquotes. Unlike RFC XML v2, RFC XML v3 does not support line breaks outside of tables, so verse quotations are converted to prose in the v3 converter. An example of using AsciiRFC Blockquotes is given in Figure 35 with its rendered version in Figure 36. [quote,attribution="A. Farrel"] ____ Although the RFC Editor has recently dragged the IETF kicking and screaming into the twentieth century [RFC7990] [RFC7996], there is a yearning among all right-thinking Internet architects to "keep it simple" and to return to the olden days when pigs could be given thrust without anyone taking undue offence. ____ Figure 35: AsciiRFC Blockquote Usage Tse, et al. Expires September 24, 2018 [Page 53] Internet-Draft AsciiRFC Specifications March 2018
Although the RFC Editor has recently dragged the IETF kicking and screaming into the twentieth century [RFC7990] [RFC7996], there is a yearning among all right-thinking Internet architects to "keep it simple" and to return to the olden days when pigs could be given thrust without anyone taking undue offence.
Figure 36: AsciiRFC Blockquote Usage (RFC XML v3) 10. Notes And Asides Asciidoctor syntax supports a range of "admonitions", including notes, warnings, and tips. They are indicated by a paragraph prefix (e.g. "WARNING:"), or as a block with an admonition style attribute. All admonitions are conflated in AsciiRFC, being converted to "note" elements in the document preamble, and "cref" elements in the main document. This means that no admonitions will therefore appear in the textual output, unless forced to through the "comments" processing instruction. A sample admonition is shown in Figure 37, with its rendered output in Figure 38. [NOTE,display=true,source=Author] ==== Image courtesy of https://camelot.gov.example/creatures-in-ascii/ ==== Figure 37: An AsciiRFC Adminition Block Tse, et al. Expires September 24, 2018 [Page 54] Internet-Draft AsciiRFC Specifications March 2018 Image courtesy of Figure 38: An AsciiRFC Adminition Block (RFC XML v3) With RFC XML v2, note that no inline formatting is permitted for "cref" elements, and any such formatting is therefore stripped for v2 by the converter. Because paragraphs in AsciiRFC cannot contain any other blocks, a comment at the end of a paragraph is treated as a new block. In the document converter, any such comments are moved inside the preceding RFC XML paragraph; if the comment is at the start of a section, as in the example above, it is wrapped inside a paragraph. The RFC XML v3 converter also supports "asides" (Asciidoctor syntax Sidebars). A sample is shown in Figure 39, with its rendered output in Figure 40. **** While the exchange at the French-occupied castle is one of the more memorable scenes of _Monty Python and the Holy Grail_, the Trojan Rabbit has not reached the same level of cultural resonance as its more murderous counterpart. Reasons for this may include: * Less overall screen-time dedicated to the Trojan Rabbit. * The Trojan Rabbit as projectile has already been anticipated by the Cow as projectile. **** Figure 39: An AsciiRFC Sidebar Block Tse, et al. Expires September 24, 2018 [Page 55] Internet-Draft AsciiRFC Specifications March 2018 Figure 40: An AsciiRFC Sidebar Block Rendered As An Aside (RFC XML v3) Comments given in AsciiDoc syntax (notated with initial "//") are not intended to be shown in the rendered output, and will not appear in the output as XML comments. XML comments can be generated by using the "[comment]#...#" inline formatting macro, or the "[.comment]" role attribute on blocks. A sample is shown in Figure 39 with its rendered output in Figure 40. The exchange of projectile animals was the beginning of a long-running fruitful relationship between the British and the French peoples, [comment]#TODO: Will need to verify that claim.# which arguably predates the traditional English enmity with the French. [comment]#Strictly speaking, the Knights are Welsh.# [.comment] -- This document, as it turns out, has a profusion of XML comments. As expected, they are ignored in any rendering of the document. -- Figure 41: AsciiRFC delimited text intended as an XML Comment Tse, et al. Expires September 24, 2018 [Page 56] Internet-Draft AsciiRFC Specifications March 2018 The exchange of projectile animals was the beginning of a long-running fruitful relationship between the British and the French peoples, which arguably predates the traditional English enmity with the French. Figure 42: AsciiRFC delimited text Rendered As An XML Comment (RFC XML v3) 11. Tables AsciiRFC tables, like RFC XML v3, support distinct table heads, bodies and feet; cells spanning multiple rows and columns; and horizontal alignment. The larger range of table formatting options available in RFC XML v2 is also supported. A sample of an AsciiRFC table is shown in Figure 43, with its rendered output in Figure 44. Neither version of RFC XML is as expressive in its table structure as Asciidoctor syntax. RFC XML, for example, does not permit blocks within table cells. Tse, et al. Expires September 24, 2018 [Page 57] Internet-Draft AsciiRFC Specifications March 2018 [grid=all,options="footer"] |=== |French Castle | Cave of Caerbannog 2+|King Arthur 2+|Patsy 2+|Sir Bedevere the Wise 2+|Sir Galahad the Pure 2+|Sir Lancelot the Brave 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot |French Guard with Outrageous Accent| Tim the Enchanter |Other French Guards | Brother Maynard | | The Lector .3+^|not yet recruited >|Sir Bors >|Sir Gawain >|Sir Ector |Retinue of sundry knights |Retinue of sundry more knights than at the French Castle |=== Figure 43: An AsciiRFC Table Tse, et al. Expires September 24, 2018 [Page 58] Internet-Draft AsciiRFC Specifications March 2018
French Castle Cave of Caerbannog
King Arthur
Patsy
Sir Bedevere the Wise
Sir Galahad the Pure
Sir Lancelot the Brave
Sir Robin the Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous Accent Tim the Enchanter
Other French Guards Brother Maynard
The Lector
not yet recruited Sir Bors
Sir Gawain
Sir Ector
Retinue of sundry knights Retinue of sundry more knights than at the French Castle
Figure 44: An AsciiRFC Table (RFC XML v3) Tse, et al. Expires September 24, 2018 [Page 59] Internet-Draft AsciiRFC Specifications March 2018 12. Inline Formatting 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts AsciiRFC supports italics, boldface, monospace, subscripts and superscripts, just like RFC XML v3. The inline formatting syntax given in Figure 45 produces the RFC XML v3 output given in Figure 46. The participants of that renowned exercise in cross-cultural communication, to wit the exchange between the _Knights of the Round Table_ and the taunting French soldiers serving under *Guy de Lombard* are, properly speaking, outside the scope of this `menagerie`, being more or less human. Notwithstanding, several^ish^ beasts both animate~d~ and wooden played a significant part in this encounter; most notably: * The Projectile Cow, see <> * The Trojan Rabbit, see <> Figure 45: Inline Formatting In AsciiRFC Tse, et al. Expires September 24, 2018 [Page 60] Internet-Draft AsciiRFC Specifications March 2018 The participants of that renowned exercise in cross-cultural communication, to wit the exchange between the Knights of the Round Table and the taunting French soldiers serving under Guy de Lombard are, properly speaking, outside the scope of this menagerie, being more or less human. Notwithstanding, severalish beasts both animated and wooden played a significant part in this encounter; most notably:
  • The Projectile Cow, see
  • The Trojan Rabbit, see
Figure 46: Inline Formatting In AsciiRFC (RFC XML v3) 12.2. Formatting BCP 14 Keywords RFC XML v3 also supports tagging of BCP14 keywords [RFC2119] [RFC8174]; this is done in AsciiRFC either by tagging them with a custom formatting span (e.g. "MUST NOT"), or by converting any boldface all-caps words recognised as BCP14 words (unless the ":no- rfc-bold-bcp14: false" document attribute is set). Any spans of BCP14 text delimited by inline formatting delimiters need to be contained within a single line of text; in Asciidoctor syntax, formatting spans are broken up across line breaks. This usage is demonstrated in Figure 47 with the rendered output in Figure 48. Tse, et al. Expires September 24, 2018 [Page 61] Internet-Draft AsciiRFC Specifications March 2018 The instructions in the _Book of Armaments_ on the proper deployment of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as follows, although this summary *SHALL NOT* be used as a substitute for a reading from the Book of Armaments: Figure 47: BCP14 Keywords In AsciiRFC The instructions in the Book of Armaments on the proper deployment of the Holy Hand Grenade of Antioch MAY be summarized as follows, although this summary SHALL NOT be used as a substitute for a reading from the Book of Armaments: Figure 48: BCP14 Keywords In AsciiRFC (RFC XML v3) 12.3. Escaping AsciiRFC Syntax Formatting delimiters like "*" can be escaped with backslash ("\*"); double formatting delimiters, like "**" and "__", need to be escaped with double backslash ("\\**"). Escaping delimiters is not always reliable, and for double delimiters it is preferable to use HTML entities ("**"), or attribute references (references to the value of attributes set in the document header) as shown in Figure 49. :dblast: ** `{dblast}` Figure 49: Escaping AsciiRFC Syntax Using Attributes In extreme circumstances (such as quoting AsciiDoc syntax), you may need to resort to altering the substitutions behaviour within a given block of of AsciiDoc; see the "Applying Substitutions" section of [Asciidoctor-Manual]. Tse, et al. Expires September 24, 2018 [Page 62] Internet-Draft AsciiRFC Specifications March 2018 13. Links Common URL formats are recognised automatically as hyperlinks in AsciiRFC, which inherits this excellent feature from AsciiDoc, and are rendered as such. Any hyperlinked text is appended after the hyperlink in square brackets. An example is given in Figure 50 with its rendered version in Figure 51. <> of the fearsome beast has been sourced from http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], <> by C code that was used in this accurate depiction of the Killer Rabbit: Figure 50: An AsciiRFC Link The following depiction of the fearsome beast has been sourced from Rabbit-SCII, accompanied by C code that was used in this accurate depiction of the Killer Rabbit: Figure 51: An AsciiRFC Link (RFC XML v3) To prevent hyperlinking of a URL, prefix it with a backslash, as shown in Figure 52 with its rendered version in Figure 53. Tse, et al. Expires September 24, 2018 [Page 63] Internet-Draft AsciiRFC Specifications March 2018 The screaming move into the twenty-*first* century is accompanied by a move back to the late twentieth century, with ASCII stylings more wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be accessible in 1996.) Figure 52: A Literal AsciiRFC Link The screaming move into the twenty-first century is accompanied by a move back to the late twentieth century, with ASCII stylings more wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be accessible in 1996.) Figure 53: A Literal AsciiRFC Link (RFC XML v3) 14. Cross-References 14.1. Basic Referencing Anchors for cross-references are notated as "[[...]]" or "[#...]", and can be inserted on their own line in front of most blocks. Asciidoctor syntax supports anchors in a much wider range of contexts than is supported than RFC XML v3 (let alone v2); anchors that are not supported for that version of RFC XML are simply ignored by the converter. Note that anchors in RFC XML are constrained to the format "[A-Za- z_:][[A-Za-z0-9_:.-]*" (i.e. "xsd:ID"). Cross-references to anchors are notated as "<<...>>"; cross- references with custom text as "<>". An example of using cross-references in AsciiRFC is given in Figure 54 with its rendered output in Figure 55. Tse, et al. Expires September 24, 2018 [Page 64] Internet-Draft AsciiRFC Specifications March 2018 The _Cave of Caerbannog_ has been well-established in the mythology of Camelot (as recounted by Monty Python) as the lair of the Legendary Black Beast of Arrrghhh, more commonly known today as the *Killer Rabbit of Caerbannog* <>. It is the encounter between the Killer Rabbit of Caerbannog and the Knights of the Round Table, armed with the Holy Hand Grenade of Antioch (see the <>), that we recount here through monospace font and multiple spaces. [[killer_rabbit_caerbannog]] === The Killer Rabbit of Caerbannog Figure 54: Setting And Referring To Cross-References In AsciiRFC The Cave of Caerbannog has been well-established in the mythology of Camelot (as recounted by Monty Python) as the lair of the Legendary Black Beast of Arrrghhh, more commonly known today as the Killer Rabbit of Caerbannog . It is the encounter between the Killer Rabbit of Caerbannog and the Knights of the Round Table, armed with the Holy Hand Grenade of Antioch (see the following section), that we recount here through monospace font and multiple spaces.
The Killer Rabbit of Caerbannog Figure 55: Setting And Referring To Cross-References In AsciiRFC (RFC XML v3) 14.2. Referencing With Attributes While Asciidoctor syntax natively does not support attributes on cross-references, AsciiRFC works around that by embedding formatting information as templated text within cross-references: o "format=x: text" populates the "xref@format" attribute Tse, et al. Expires September 24, 2018 [Page 65] Internet-Draft AsciiRFC Specifications March 2018 o a section number followed by one of the words "of", "parens", "bare", "text" is treated as a "relref" reference to an external document. An example of referencing with attributes is given in Figure 56 with its output in Figure 57. The *Killer Rabbit of Caerbannog*, that most formidable foe of the Knights and of all that is holy or carrot-like, has been depicted diversely in lay and in song. We venture to say, _contra_ the claim made in <>, that the Killer Rabbit of Caerbannog truly is the most afeared of all the creatures. Short of sanctified ordnance such as <>, there are few remedies known against its awful lapine powers. Figure 56: Cross-References With Attributes In AsciiRFC The Killer Rabbit of Caerbannog, that most formidable foe of the Knights and of all that is holy or carrot-like, has been depicted diversely in lay and in song. We venture to say, contra the claim made in Ze Vompyre, that the Killer Rabbit of Caerbannog truly is the most afeared of all the creatures. Short of sanctified ordnance such as , there are few remedies known against its awful lapine powers. Figure 57: Cross-References With Attributes In AsciiRFC (RFC XML v3) 14.3. Indexing Inline index entries are notated as "((...))". Index entries which do not appear in the text are notated as "(((...)))"; such entries may include a separate sub-entry, separated from the main entry by comma. Tse, et al. Expires September 24, 2018 [Page 66] Internet-Draft AsciiRFC Specifications March 2018 The solution to the impasse at the ((Cave of Caerbannog)) was provided by the successful deployment of the *Holy Hand Grenade of Antioch* (see <>) (((Holy Hand Grenade of Antioch))). Any similarity between the Holy Hand Grenade of Antioch and the mythical _Holy Spear of Antioch_ is purely intentional; (((relics, Christian))) any similarity between the Holy Hand Grenade of Antioch and the _Sovereign's Orb of the United Kingdom_ (see <>) is putatively fortuitous. (((relics, monarchic))) Figure 58: AsciiRFC Index Entries The solution to the impasse at the Cave of Caerbannog was provided by the successful deployment of the Holy Hand Grenade of Antioch (see ) . Any similarity between the Holy Hand Grenade of Antioch and the mythical Holy Spear of Antioch is purely intentional; any similarity between the Holy Hand Grenade of Antioch and the Sovereign's Orb of the United Kingdom (see ) is putatively fortuitous. Figure 59: AsciiRFC Index Entries (RFC XML v3) 15. Inclusions AsciiRFC inherits the Asciidoctor syntax "include" directive [Asciidoctor-Manual] to include external files in a master AsciiRFC document. This directive is capable of sophisticated document merging, including adjusting the heading levels of the included text, Tse, et al. Expires September 24, 2018 [Page 67] Internet-Draft AsciiRFC Specifications March 2018 selecting text within specified tags or line numbers to be included, and adjusting the indentation of code snippets in merged text. Its basic syntax is given in Figure 60. include::path[ leveloffset=_offset_, lines=_ranges_, tag(s)=_name(s)_, indent=_depth_ ] Figure 60: Inclusions In AsciiRFC If a file is included in an AsciiRFC document, ensure it ends with a blank line. An inclusion that results in its final block not being delimited with a blank line from what follows can lead to unpredictable results. 16. Encoding and Entities XML accepts the full range of characters in the world's languages through UTF-8 character encoding, and one of the motivations for the move by the IETF from plain text to RFC XML has been to allow non- ASCII characters to be included in RFCs. However, current RFC XML v2 tools still do not support UTF-8, and alternative tooling support for UTF-8 also remains patchy. Out of an abundance of caution, the RFC XML converter uses US-ASCII for its character encoding, and renders any non-ASCII characters as HTML entities. AsciiRFC accepts HTML entities as input, even though they are not part of the W3C XML specification. HTML entities such as " " feature in examples of RFC XML provided by the IETF. In order to prevent dependence of the XML output from extraneous entity definitions, any such entities are rendered in the XML as decimal character entities. An example of how AsciiRFC renders non-ASCII UTF-8 characters are given in Figure 61 with the output in Figure 62. Tse, et al. Expires September 24, 2018 [Page 68] Internet-Draft AsciiRFC Specifications March 2018 ____ .כאן אולי ימצאו המילים האחרונות של יוסף מארמתיה .מי אשר יהיה אמיץ ובעל נפש טהורה יוכל למצוא את הגביע הקדוש בטירת אאאאאאאה "Here may be found the last words of Joseph of Arimathea. He who is valiant and pure of spirit may find the Holy Grail in the castle of — Aaaargh." ____ Figure 61: UTF-8 Characters In AsciiRFC Tse, et al. Expires September 24, 2018 [Page 69] Internet-Draft AsciiRFC Specifications March 2018
.כאן אולי ימצאו המילים האחרונות של יוסף מארמתיה .מי אשר יהיה אמיץ ובעל נפש טהורה יוכל למצוא את הגביע הקדוש בטירת אאאאאאאה "Here may be found the last words of Joseph of Arimathea. He who is valiant and pure of spirit may find the Holy Grail in the castle of — Aaaargh."
Figure 62: UTF-8 Characters In AsciiRFC Rendered As RFC XML v3 Note that because initial period is a formatting character in Asciidoctor, we have had to use "." to escape the period at the end of Hebrew sentences (which appears at the start of the line, Hebrew being written Right-to-Left). Asciidoctor is not natively equipped to deal with Right-to-Left languages in its formatting parsing. 17. Bibliography The simple encoding of bibliography syntax provided by AsciiDoc (and Asciidoctor syntax) is inadequate for the complexity of bibliographic markup required by RFC XML. RFC documents overwhelmingly cite other RFC documents, and canonical RFC XML bibliographic entries are available at [IETF-BibXML]; so it would be inefficient to encode those entries natively in AsciiRFC, only to have them converted back to RFC XML. Tse, et al. Expires September 24, 2018 [Page 70] Internet-Draft AsciiRFC Specifications March 2018 The converter provides two means of incorporating bibliographies into RFC documents authored in AsciiRFC: o using raw RFC XML; and o assembling bibliographies in preprocessing. In either case, the RFC XML needs to be well-formed; missing closing tags can lead to erratic behaviour in the converter. 17.1. Using Raw RFC XML In the first method, bibliographic citations are handled like all other AsciiRFC cross-references. The bibliographic entries for normative and informative references are given in the AsciiRFC as passthrough blocks, which contain the raw RFC XML for all references; document conversion leaves the raw RFC XML in place. This approach requires authors to maintain the normative and informative bibliographies within the document, to update them as citations are added and removed, and to sort them manually. However, if the citation is stored on the IETF's RFC XML citation libraries (see ), AsciiRFC will automatically replace it with an external reference to that citation. So the body of the citation XML can be left out. For example, the AsciiRFC in Figure 63 will generate the corresponding RFC XML v3 output in Figure 64. [bibliography] == Normative References ++++ Key words for use in RFCs to Indicate Requirement Levels Tse, et al. Expires September 24, 2018 [Page 71] Internet-Draft AsciiRFC Specifications March 2018 ++++ [bibliography] == Informative References ++++ Monty Python and the Holy Grail DON'T SPEW A Set of Guidelines for Mass Unsolicited Mailings and Postings (spam*) RFC Format Framework Tse, et al. Expires September 24, 2018 [Page 72] Internet-Draft AsciiRFC Specifications March 2018 The Arte of ASCII: Or, An True and Accurate Representation of an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of Character Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. ++++ Figure 63: AsciiRFC Inline Bibliography Tse, et al. Expires September 24, 2018 [Page 73] Internet-Draft AsciiRFC Specifications March 2018
Normative References Informative References Monty Python and the Holy Grail Figure 64: AsciiRFC Inline Bibliography Rendered As RFC XML v3 17.2. Preprocessing Using "asciidoctor-bibliography" The alternative method is to use a preprocessing tool, [asciidoctor-bibliography], to import citations into the AsciiRFC document from an external file of references. Tse, et al. Expires September 24, 2018 [Page 74] Internet-Draft AsciiRFC Specifications March 2018 The references file consists of RFC XML reference entries, and still needs to be managed manually; however the bibliographies are assembled from that file, sorted, and inserted into the normative and informative references in preprocessing. Citations in the document itself are given as macros to be interpreted by the preprocessor; this allows them to be split into normative and informative references. (The MMark tool likewise splits reference citations into normative and informative.) Integration with the "asciidoc-bibliography" gem proceeds as follows: 1. Create an RFC XML references file, consisting of a "" element with individual "" elements inserted, as would be done for the informative and normative references normally. The references file will contain all possible references to be used in the file; the bibliography gem will select which references have actually been cited in the document. A. Rather than hand crafting RFC XML references for RFC documents, you should download them from an authoritative source; e.g., "http://xml.resource.org/public/rfc/bibxml/ reference.RFC.2119.xml". Note that RFC XML references from this link contains the XML document declaration, which needs to be removed before being used in the XML bibliography. B. Unlike the case for RFC XML documents created manually, the references file does not recognise XML entities and will not attempt to download them during processing. Any references to "http://xml.resource.org/public/rfc/bibxml/" will need to be downloaded and inserted into the references file. C. The RFC XML in the references file will need to be appropriate to the version of RFC XML used in the main document, as usual. Note that RFC XML v2 references are forward compatible with v3; v3 contains a couple of additional elements. 2. Add to the main document header attributes referencing the references file (":bibliography-database:"), and the bibliography style (":bibliography-style: rfc-v3"). 3. References to a normative reference are inserted with the macro "cite:norm[id]" instead of "<>", where "id" is the anchor of the reference. 4. References to an informative reference are inserted with the macro "cite:info[id]" instead of "<>", where "id" is the anchor of the reference. Tse, et al. Expires September 24, 2018 [Page 75] Internet-Draft AsciiRFC Specifications March 2018 5. Formatted crossreferences and "relref" crossreferences are entered by inserting the expected raw XML in the "text" attribute. Do not use the "{cite}" interpolation of the citation. For example: * "<>" = "cite:norm[id, text="words"]" * "<>" (processed as a formatted cross-reference) = "cite:norm[id, text="words"]" * "<>" (processed as relref) = "cite:norm[id, text=""]" * "<>" (processed as relref with a cross-document internal reference) = "cite:norm[id, text=""]" 6. Normative and Informative References are inserted in the document through a macro, which occurs where the RFC XML references would be inserted, as shown in Figure 65. [bibliography] == Normative References ++++ bibliography::norm[] ++++ [bibliography] == Informative References ++++ bibliography::info[] ++++ Figure 65: Using asciidoctor-bibliography For Bibliography Preprocessing Tse, et al. Expires September 24, 2018 [Page 76] Internet-Draft AsciiRFC Specifications March 2018 18. RFC XML features not supported in Asciidoctor The following features of RFC XML v3 [RFC7991] and v2 [RFC7749] are not supported by the AsciiRFC converter, and would need to be adjusted manually after RFC XML is generated: +------------------------+--------------------+---------------------+ | RFC XML element | RFC XML v3 | RFC XML v2 | +------------------------+--------------------+---------------------+ | "front/boilerplate" | Not added by the | Not added by the | | | converter | converter | | "iref@primary" | N | N | | "reference" (and all | As Raw XML | As Raw XML | | children) | | | | "table/preamble" | Deprecated | N | | "table/postamble" | Deprecated | N | | "artwork@width" | Only on images | Only on images | | "artwork@height" | Only on images | Only on images | +------------------------+--------------------+---------------------+ 19. Authoring To author an AsciiRFC document, you should first familiarise yourself with the [Asciidoctor-Manual]. The [asciidoctor-rfc] Ruby gem source code distribution also has samples of individual RFC XML features in v2 and v3, and examples of self-standing AsciiRFC documents, along with their RFC XML renderings. (This includes round-tripped RFC XML documents.) 19.1. Using the "rfc-asciirfc-minimal" template In addition, you can clone the sample "rfc-asciirfc-minimal" repository as a template, and populate it for your AsciiRFC document using the steps shown in Figure 66. $ git clone https://github.com/riboseinc/rfc-asciirfc-minimal Figure 66: Cloning The AsciiRFC Document Template 19.2. Installing AsciiRFC Backend Processors Converting your AsciiRFC to RFC XML is a simple as installing the Asciidoctor Ruby gem "asciidoctor" (see "Installation" at [Asciidoctor]) and the "asciidoctor-rfc" gem in Ruby (through RubyGems), then running the "asciidoctor" executable on the document, specifying the "asciidoctor-rfc" gem as a library. Tse, et al. Expires September 24, 2018 [Page 77] Internet-Draft AsciiRFC Specifications March 2018 The necessary steps are shown in Figure 67. $ gem install asciidoctor-rfc $ asciidoctor -b rfc3 -r 'asciidoctor-rfc' foo.adoc # RFC XML v3 output $ asciidoctor -b rfc2 -r 'asciidoctor-rfc' foo.adoc # RFC XML v2 output Figure 67: Installing The AsciiRFC Backend Processors 19.3. Iterating AsciiRFC Content As you author AsciiRFC content, you should iterate by running the AsciiRFC conversion frequently, to ensure that you are still generating valid XML through your markup. The converter makes an effort to ensure that its XML output is valid, and it issues warnings about likely issues; it also validates its own XML output against the RFC XML schema (of the corresponding version), and reports errors in the XML output in the format shown in Figure 68. V3 RELAXNG Validation: 12:0: ERROR: Invalid attribute sortRefs for element rfc Figure 68: Sample Validation Error Message From AsciiRFC Note that validation against the Relax NG RFC XML schema includes confirming the referential integrity of all cross-references in the document. It may be necessary to intervene in the XML output generated by the converter, either because the block model of AsciiRFC does not conform with the intended RFC XML (e.g. lists embedded in paragraphs), or because RFC XML features are required that are not supported within AsciiRFC. 20. Security Considerations o Ensure your AsciiRFC generator comes from a geniune and trustworthy source. This protects your own machine and also prevents injection of malicious content in your resulting document. o An AsciiRFC generator may cause errors in textual rendering or link generation that may lead to security issues. o Creating cross-references (and also bibliographic references) to external documents may pose risks since the specified external location may become controlled by a malicious party. Tse, et al. Expires September 24, 2018 [Page 78] Internet-Draft AsciiRFC Specifications March 2018 o URIs that start with the "http:" or "https:" prefix are automatically converted into links in AsciiRFC except when escaped with a backslash before the prefix. A URI that is intended to be text but unintentionally rendered as a link may cause users to visit a malicious website with security consequences. o AsciiRFC contains syntax that can directly incorporate remote URI content, such as "include::" which allows remotely-located AsciiRFC content files. If a remote URI contains malicious content, this content will be included in the resulting AsciiRFC document compiled as RFC XML. Remotely-linked URIs should always be checked for malicious content prior to compiling AsciiRFC into RFC XML. 21. IANA Considerations This document does not require any action by IANA. 22. References 22.1. Normative References [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", RFC 7991, DOI 10.17487/RFC7991, December 2016, . 22.2. Informative References [AsciiDoc] Rackham, S., "AsciiDoc: Text based document generation", November 2013, . [Asciidoctor] Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more.", November 2017, . [asciidoctor-bibliography] Ribose Inc., "Citations and Bibliography the 'asciidoctor- way'", November 2017, . [Asciidoctor-Manual] Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more.", November 2017, . Tse, et al. Expires September 24, 2018 [Page 79] Internet-Draft AsciiRFC Specifications March 2018 [asciidoctor-rfc] Ribose Inc., "asciidoctor-rfc lets you write Internet- Drafts and RFCs in AsciiDoc, the "asciidoctor-way".", November 2017, . [AsciiMathML] "AsciiMath is an easy-to-write markup language for mathematics.", November 2017, . [datatracker-asciirfc-minimal] Carberry, J. and T. Grayson, "IETF Datatracker: A Minimal Internet-Draft In AsciiRFC", March 2018, . [datatracker-camelot-holy-grenade] Pendragon, A., "IETF Datatracker: The Holy Hand Grenade of Antioch", March 2018, . [datatracker-divination-cfapi] Destiny, G. and C. Luck, "IETF Datatracker: An API For Calendar-Based Fortune Heuristics Services", March 2018, . [draftr] Barnes, R., "draftr: an HTML front-end to pandoc2rfc", Nov 2017, . [git-asciirfc-minimal] Carberry, J. and T. Grayson, "Git repository: A Minimal Internet-Draft In AsciiRFC", March 2018, . [git-camelot-holy-grenade] Pendragon, A., "Git repository: The Holy Hand Grenade of Antioch", March 2018, . [git-divination-cfapi] Destiny, G. and C. Luck, "Git repository: An API For Calendar-Based Fortune Heuristics Services", March 2018, . Tse, et al. Expires September 24, 2018 [Page 80] Internet-Draft AsciiRFC Specifications March 2018 [I-D.asciirfc-minimal] Carberry, J. and T. Grayson, "A Minimal Internet-Draft In AsciiRFC", draft-asciirfc-minimal-01 (work in progress), March 2018. [I-D.camelot-holy-grenade] Pendragon, A., "The Holy Hand Grenade of Antioch", draft- camelot-holy-grenade-00 (work in progress), March 2018. [I-D.divination-cfapi] Destiny, G. and C. Luck, "An API For Calendar-Based Fortune Heuristics Services", draft-divination-cfapi-00 (work in progress), March 2018. [IETF-BibXML] "IETF BibXML Library", November 2017, . [kramdown-rfc2629] Bormann, C., "kramdown-rfc2629: An RFC2629 (XML2RFC) backend for Thomas Leitner's kramdown markdown parser", Nov 2017, . [lyx2rfc] Williams, N., "LyX to I-D/RFC export by way of Lyx export to XHTML and XSLT conversion to xml2rfc schema", 2014, . [MathJax] "MathJax: A JavaScript display engine for mathematics that works in all browsers.", November 2017, . [mmark] Gieben, R., "Using mmark to create I-Ds and RFCs", June 2015, . [NroffEdit] Santesson, S., "WYSIWYG Internet-Draft Nroff Editor", May 2011, . [pandoc2rfc] Gieben, R., "pandoc2rfc: Use pandoc to create XML suitable for xml2rfc", 2012, . [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . Tse, et al. Expires September 24, 2018 [Page 81] Internet-Draft AsciiRFC Specifications March 2018 [RFC5385] Touch, J., "Version 2.0 Microsoft Word Template for Creating Internet Drafts and RFCs", RFC 5385, DOI 10.17487/RFC5385, February 2010, . [RFC7328] Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit of XML", RFC 7328, DOI 10.17487/RFC7328, August 2014, . [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", RFC 7749, DOI 10.17487/RFC7749, February 2016, . [RFC7763] Leonard, S., "The text/markdown Media Type", RFC 7763, DOI 10.17487/RFC7763, March 2016, . [RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations", RFC 7764, DOI 10.17487/RFC7764, March 2016, . [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990, DOI 10.17487/RFC7990, December 2016, . [RFC7996] Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC", RFC 7996, DOI 10.17487/RFC7996, December 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [TeX-LaTeX] "LaTeX is document preparation software that runs on top of Donald E. Knuth's TeX typesetting system.", November 2017, . Appendix A. Examples A.1. Example 1: "A Minimal Internet-Draft In AsciiRFC" This example is available in the following formats: o AsciiRFC [git-asciirfc-minimal] o Internet-Draft [I-D.asciirfc-minimal] Tse, et al. Expires September 24, 2018 [Page 82] Internet-Draft AsciiRFC Specifications March 2018 o Text, RFC XML, PDF and HTML on the IETF Datatracker [datatracker-asciirfc-minimal] A.1.1. In AsciiRFC = A Minimal Internet-Draft In AsciiRFC :doctype: internet-draft :name: draft-asciirfc-minimal-01 :abbrev: AsciiRFC Example :status: informational :ipr: trust200902 :submissionType: individual :area: Internet :intended-series: full-standard :revdate: 2018-03-23T00:00:00Z :fullname: Josiah Stinkney Carberry :lastname: Carberry :forename_initials: J. S. :organization: Brown University :phone: +1 401 863 1000 :street: Box K, 69 Brown Street :city: Providence :code: 02912 :country: United States of America :uri: https://www.brown.edu :email: josiah.carberry@ribose.com :fullname_2: Truman Grayson :lastname_2: Grayson :forename_initials_2: T. :organization_2: Brown University :phone_2: +1 401 863 1000 :street_2: Box G, 69 Brown Street :city_2: Providence :code_2: 02912 :country_2: United States of America :uri_2: https://www.brown.edu :email_2: truman.grayson@ribose.com [abstract] This document provides a template on how to author (or migrate!) a new Internet-Draft / RFC in AsciiRFC format. This template requires usage of the `asciidoctor-rfc` Ruby gem. [#introduction] == Introduction Tse, et al. Expires September 24, 2018 [Page 83] Internet-Draft AsciiRFC Specifications March 2018 AsciiRFC <> is an extremely simple way to author Internet-Drafts and RFCs without needing to manually craft RFC XML <>. This is a template for authors to easily start with <>. [#conventions] == Terms and Definitions The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document are to be interpreted as described in BCP 14 <> <> when, and only when, they appear in all capitals, as shown here. //// Note: do not break formatted strings over carriage return. Bad things happen. (In this instance, the carriage return is suppressed, and no space takes its place.) This is an Asciidoctor issue, not an asciidoctor-rfc issue. //// [#symbols] == Symbols And Abbreviations [#operators] === Operators AsciiRFC:: As defined in <>. [#security] == Security Considerations * Please beware of implementation issues caused by <>. * Here's how you include references <>, <>, <>. [#iana] Tse, et al. Expires September 24, 2018 [Page 84] Internet-Draft AsciiRFC Specifications March 2018 == IANA Considerations This document does not require any action by IANA. // References must be given before appendixes [bibliography] == Normative References //bibliography::norm[] ++++ Key words for use in RFCs to Indicate Requirement Levels In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. The "xml2rfc" Version 3 Vocabulary Tse, et al. Expires September 24, 2018 [Page 85] Internet-Draft AsciiRFC Specifications March 2018 This document defines the "xml2rfc" version 3 vocabulary: an XML-based language used for writing RFCs and Internet-Drafts. It is heavily derived from the version 2 vocabulary that is also under discussion. This document obsoletes the v2 grammar described in RFC 7749. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. ++++ [bibliography] == Informative References //bibliography::info[] ++++ RNP: A C library approach to OpenPGP Ribose Inc.
Tse, et al. Expires September 24, 2018 [Page 86] Internet-Draft AsciiRFC Specifications March 2018 Suite 1111, 1 Pedder Street Central Hong Kong Hong Kong open.source@ribose.com https://www.ribose.com
AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc This document describes an AsciiDoc syntax extension called AsciiRFC, designed for authoring IETF Internet-Drafts and RFCs. AsciiDoc is a human readable document markup language which affords more granular control over markup than comparable schemes such as Markdown. The AsciiRFC syntax is designed to allow the author to entirely focus on text, providing the full power of the resulting RFC XML through the AsciiDoc language, while abstracting away the need to manually edit XML, including references. This document itself was written and generated into RFC XML v2 (RFC7749) and RFC XML v3 (RFC7991) directly through asciidoctor-rfc, an AsciiRFC generator. Tse, et al. Expires September 24, 2018 [Page 87] Internet-Draft AsciiRFC Specifications March 2018 The SM4 Blockcipher Algorithm And Its Modes Of Operations This document describes the SM4 symmetric blockcipher algorithm published as GB/T 32907-2016 by the State Cryptography Administration of China (SCA). This document is a product of the Crypto Forum Research Group (CFRG). The OCB Authenticated-Encryption Algorithm This document specifies OCB, a shared-key blockcipher-based encryption scheme that provides confidentiality and authenticity for plaintexts and authenticity for associated data. This document is a product of the Crypto Forum Research Group (CFRG). Tse, et al. Expires September 24, 2018 [Page 88] Internet-Draft AsciiRFC Specifications March 2018 ++++ [appendix] [#appendix-a] == Examples === Example 1 Here's an example. [source,json] ---- { "code": { "encoding": "ascii", "type": "rfc", "authors": [ "Josiah Carberry", "Truman Grayson" ] } } ---- [#acknowledgements] == Acknowledgements The authors would like to thank their families. A.1.2. Rendered as RFC XML v3 Tse, et al. Expires September 24, 2018 [Page 89] Internet-Draft AsciiRFC Specifications March 2018 A Minimal Internet-Draft In AsciiRFC Brown University
Box K, 69 Brown Street Providence 02912 United States of America +1 401 863 1000 josiah.carberry@ribose.com https://www.brown.edu
Brown University
Box G, 69 Brown Street Providence 02912 United States of America +1 401 863 1000 truman.grayson@ribose.com https://www.brown.edu
Internet This document provides a template on how to author (or migrate!) a new Internet-Draft / RFC in AsciiRFC format. This template requires usage of the asciidoctor-rfc Ruby gem.
IntroductionAsciiRFC is an extremely simple way to author Internet-Drafts and RFCs without needing to manually craft RFC XML . This is a template for authors to easily start with .
Terms and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.
Symbols And Abbreviations
Operators
AsciiRFC
As defined in .
Security Considerations
  • Please beware of implementation issues caused by .
  • Here’s how you include references , , .
IANA Considerations This document does not require any action by IANA.
Tse, et al. Expires September 24, 2018 [Page 91] Internet-Draft AsciiRFC Specifications March 2018
Normative References Informative References RNP: A C library approach to OpenPGP Ribose Inc.
Suite 1111, 1 Pedder Street Central Hong Kong Hong Kong open.source@ribose.com https://www.ribose.com
Examples
Example 1Here’s an example.
{ "code": { "encoding": "ascii", "type": "rfc", "authors": [ "Josiah Carberry", "Truman Grayson" ] } }
Acknowledgements The authors would like to thank their families.
A.2. Example 2: "The Holy Hand Grenade of Antioch" This example is available in the following formats: o AsciiRFC [git-camelot-holy-grenade] o Internet-Draft [I-D.camelot-holy-grenade] o Text, RFC XML, PDF and HTML on the IETF Datatracker [datatracker-camelot-holy-grenade] A.2.1. In AsciiRFC = The Holy Hand Grenade of Antioch Arthur son of Uther Pendragon :doctype: internet-draft :abbrev: Hand Grenade of Antioch :updates: 8140 :submission-type: independent :name: draft-camelot-holy-grenade-00 :status: informational :consensus: false :area: General, Operations and Management :keyword: rabbits, grenades, antioch, camelot :ipr: trust200902 :toc-include: true :sort-refs: true Tse, et al. Expires September 24, 2018 [Page 93] Internet-Draft AsciiRFC Specifications March 2018 :revdate: 2018-04-01 :fullname: Arthur son of Uther Pendragon :forename_initials: A. :lastname: Pendragon :email: arthur.pendragon@ribose.com :organization: Camelot :uri: http://camelot.gov.example :street: Palace\ Camel Lot 1 :city: Camelot :country: England :comments: yes :notedraftinprogress: yes :smart-quotes: false [.comment] tag::preamble1[] // tag::preamble[] [abstract] The menagerie of beasts and artefacts depicted in RFC8140 may be usefully supplemented by other renowned figures of Internet and more general lore. This document extends the menagerie to the seminal fable of the "Holy Hand Grenade of Antioch", as depicted in the Monty Python film "Monty Python and the Holy Grail", as well as "Spamalot", the musical inspired by the movie. [NOTE,remove-in-rfc=false] .Spamalot The relevance of the musical "Spamalot" to Internet lore should be obvious to the reader; but in case of doubt, see also Section 1 ("What is Spam*?") of RFC2635. // end::preamble[] [.comment] end::preamble1[] [.comment] tag::sectnums1[] // tag::sectnums[] [toc=exclude] :sectnums!: == Terminology The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document Tse, et al. Expires September 24, 2018 [Page 94] Internet-Draft AsciiRFC Specifications March 2018 are to be interpreted as described in BCP 14 <> <> when, and only when, they appear in all capitals, as shown here. :sectnums: == Introduction <> refers to the intended move of RFC formatting to XML2RFC v3 <>, in the following terms: // end::sectnums[] [.comment] end::sectnums1[] [.comment] tag::quote1[] // tag::quote[] [quote,attribution="A. Farrel"] ____ Although the RFC Editor has recently dragged the IETF kicking and screaming into the twentieth century [RFC7990] [RFC7996], there is a yearning among all right-thinking Internet architects to "keep it simple" and to return to the olden days when pigs could be given thrust without anyone taking undue offence. ____ // end::quote[] [.comment] end::quote1[] While no pigs, flying or otherwise, are involved in the transition to RFC XML v3, it is opportune to enhance the <> legendarium in the service of RFC XML v3, by illustrating its functionality through references to the mythology of Camelot, and particularly the incidents at the Cave of Caerbannog. [.comment] tag::escaped_hyperlink1[] // tag::escaped_hyperlink[] The screaming move into the twenty-*first* century is accompanied by a move back to the late twentieth century, with ASCII stylings more wonted in haunts like \ftp://ftp.wwa.com/pub/Scarecrow (known to be accessible in 1996.) // end::escaped_hyperlink[] [.comment] Tse, et al. Expires September 24, 2018 [Page 95] Internet-Draft AsciiRFC Specifications March 2018 end::escaped_hyperlink1[] There are two references to rabbits in _Monty Python and the Holy Grail_ which are expounded on herewith: [.comment] tag::listcontinuation1[] // tag::listcontinuation[] Trojan Rabbit:: In their siege of the French-occupied castle which may already contain an instance of the Grail, Sir Bedevere the Wise proposes to use a Trojan Rabbit to infiltrate the castle, with a raiding party to take the French "not only by surprise, but totally unarmed." + The proposal, unsurprisingly, proved abortive. The more so as the raiding party forgot to hide within the Trojan Rabbit, before the French soldiers took the Trojan Rabbit inside the castle. Killer Rabbit of Caerbannog:: Guarding the entrance to the Cave of Caerbannog; see <>. // end::listcontinuation[] [.comment] end::listcontinuation1[] == The French-occupied castle [.comment] tag::inline_formatting1[] // tag::inline_formatting[] The participants of that renowned exercise in cross-cultural communication, to wit the exchange between the _Knights of the Round Table_ and the taunting French soldiers serving under *Guy de Lombard* are, properly speaking, outside the scope of this `menagerie`, being more or less human. Notwithstanding, several^ish^ beasts both animate~d~ and wooden played a significant part in this encounter; most notably: * The Projectile Cow, see <> * The Trojan Rabbit, see <> // end::inline_formatting[] [.comment] end::inline_formatting1[] Tse, et al. Expires September 24, 2018 [Page 96] Internet-Draft AsciiRFC Specifications March 2018 [[projectile-cow]] .The Projectile Cow with an accompanying cannon ==== [alt=The Projectile Cow with an accompanying cannon in ASCII] .... .-.-.-.-.-.-.-.-.-.-.-.--.-.-.-.-.-.-.--.-.-.-.-.-.-.-.--.-. _-_---__--__--___-___-__-____---___-________---____-____-__- ._.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-...-.-.--..-.-.-.-.-.-..--.- ,..,.,.,.,.,..,.,,..,.,.,.,.,.,, ^^ .,,.,., ^^ .,.,.,.= _>-.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-. .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # .,.,.,. .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ' '! .,.,..,.,.- .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_] . ., . . , .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / -.-<>.,.,..-.-, .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,. ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,. ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,., .._...{WITHHONEY}-.-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_> GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASSPC SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS CLAY_ROCKS_REBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY>< CLAY_CLAY_SKLETONS_MORESOIL_CLAY_CLAY_CLAY_CLAY_CLAY_VR .... ==== [[trojan-rabbit]] .The Trojan Rabbit with an automatic sliding door ==== [alt=The Trojan Rabbit with an automatic sliding door, in ASCII] .... ___ ____ //_ \//\__\ || || | Tse, et al. Expires September 24, 2018 [Page 97] Internet-Draft AsciiRFC Specifications March 2018 -__||_||__| // \--_ // ____ --___ // // \ \-_ // \\ @/ o || // ---- _____|| // // //\_//__ // //-- --- \____ // // --- \______ // // , . ----- \_//_ // ,. --- \____ // .,v --- \___ // __ -- \_ || , _______________ //|| |-_ || | |''''''''''| // || | | || ' | | | || | | || | | | || | | || " | | 0 | ___||___ | | || | | | -------- | | ||___ | | | ______ | |- // \ | | | // \| _| \ // \ ____|---|__________|______// \/ | || X | / || X | / \\ /\\____/ \\ /___/ \\_____/ ----- \\_____/--- ----- ----- .... ==== [.comment] tag::aside1[] // tag::aside[] **** While the exchange at the French-occupied castle is one of the more memorable scenes of _Monty Python and the Holy Grail_, the Trojan Rabbit has not reached the same level of cultural resonance as its more murderous counterpart. Reasons for this may include: * Less overall screen-time dedicated to the Trojan Rabbit. * The Trojan Rabbit as projectile has already been anticipated by the Cow as projectile. **** // end::aside[] Tse, et al. Expires September 24, 2018 [Page 98] Internet-Draft AsciiRFC Specifications March 2018 [.comment] end::aside1[] [.comment] tag::note1[] // tag::note[] [NOTE,display=true,source=Author] ==== Image courtesy of https://camelot.gov.example/creatures-in-ascii/ ==== // end::note[] [.comment] end::note1[] [.comment] tag::comment1[] // tag::comment[] The exchange of projectile animals was the beginning of a long-running fruitful relationship between the British and the French peoples, [comment]#TODO: Will need to verify that claim.# which arguably predates the traditional English enmity with the French. [comment]#Strictly speaking, the Knights are Welsh.# [.comment] -- This document, as it turns out, has a profusion of XML comments. As expected, they are ignored in any rendering of the document. -- // end::comment[] [.comment] end::comment1[] [[caerbannog]] == The Mythos of Caerbannog [.comment] tag::xref1[] // tag::xref[] Tse, et al. Expires September 24, 2018 [Page 99] Internet-Draft AsciiRFC Specifications March 2018 The _Cave of Caerbannog_ has been well-established in the mythology of Camelot (as recounted by Monty Python) as the lair of the Legendary Black Beast of Arrrghhh, more commonly known today as the *Killer Rabbit of Caerbannog* <>. It is the encounter between the Killer Rabbit of Caerbannog and the Knights of the Round Table, armed with the Holy Hand Grenade of Antioch (see the <>), that we recount here through monospace font and multiple spaces. [[killer_rabbit_caerbannog]] === The Killer Rabbit of Caerbannog // end::xref[] [.comment] end::xref1[] [.comment] tag::relref1[] // tag::relref[] The *Killer Rabbit of Caerbannog*, that most formidable foe of the Knights and of all that is holy or carrot-like, has been depicted diversely in lay and in song. We venture to say, _contra_ the claim made in <>, that the Killer Rabbit of Caerbannog truly is the most afeared of all the creatures. Short of sanctified ordnance such as <>, there are few remedies known against its awful lapine powers. // end::relref[] [.comment] end::relref1[] [.comment] tag::hyperlink1[] // tag::hyperlink[] <> of the fearsome beast has been sourced from http://camelot.gov.example/avatars/rabbit[Rabbit-SCII], <> by C code that was used in this accurate depiction of the Killer Rabbit: // end::hyperlink[] [.comment] Tse, et al. Expires September 24, 2018 [Page 100] Internet-Draft AsciiRFC Specifications March 2018 end::hyperlink1[] [.comment] tag::figure1[] // tag::figure1a[] [[killer-bunny]] .A Photo Of The Killer Rabbit of Caerbannog Taken In Secret ==== [alt=The Killer Bunny, in ASCII] .... \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ MW \\/\||v v|| -\\-------___ . ., \ | \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ ) /--------^-^ ,. \|// # \(/ .\\|x// " ' ' . , \\||// \||\\\// \\ .... ==== [[killer-source]] .C Code To Lure Killer Rabbit Back To Cave Tse, et al. Expires September 24, 2018 [Page 101] Internet-Draft AsciiRFC Specifications March 2018 ==== [source,c] ---- /* Locate the Killer Rabbit */ int type; unsigned char *killerRabbit = LocateCreature(&caerbannog, "killer rabbit"); if( killerRabbit == 0 ){ puts("The Killer Rabbit of Caerbannog is out of town."); return LOST_CREATURE; } /* Load Cave */ unsigned char *cave = LoadPlace(&caerbannog, "The Cave Of Caerbannog"); if( cave == 0 ){ puts("The Cave of Caerbannog must have moved."); return LOST_PLACE; } /* Lure the Killer Rabbit back into the Cave */ unsigned char *carrot = allocateObjectInPlace( carrot("fresh"), cave); if( carrot == 0 ){ puts("No carrot, no rabbit."); return LOST_LURE; } /* Finally, notify the Killer Rabbit to act */ return notifyCreature(killerRabbit, &carrot); ---- ==== // end::figure1a[] [.comment] end::figure1[] On the beast's encounter with the Knights of the Round Table, the following personnel engaged with it in combat: [.comment] tag::ul1[] // tag::ul[] * Killed Tse, et al. Expires September 24, 2018 [Page 102] Internet-Draft AsciiRFC Specifications March 2018 ** Sir Bors ** Sir Gawain ** Sir Ector * Soiled Himself ** Sir Robin * Panicked ** King Arthur * Employed Ordnance ** The Lector ** Brother Maynard * Scoffed ** Tim the Enchanter // end::ul[] [.comment] end::ul1[] [[holy_hand_grenade]] === Holy Hand Grenade of Antioch [.comment] tag::figure2[] // tag::figure2a[] [[hand-grenade-figure]] .The Holy Hand Grenade of Antioch (don't pull the pin) ==== [alt=Holy Hand Grenade of Antioch, in ASCII] .... ______ \\/ \/ __\\ /__ || //\ | ||__\\/ __| || | ,---, || |====`\ | || | '---' ,--'*`--, _||#|***|#| _,/.-'#|* *|#`-._ ,,-'#####| |#####`-. ,,'########| |########`, //##########| o |##########\ ||###########| |###########| Tse, et al. Expires September 24, 2018 [Page 103] Internet-Draft AsciiRFC Specifications March 2018 ||############| o |############| ||------------' '------------| ||o o o o o o o o o o| |-----------------------------| ||###########################| \\#########################/ `..#####################,' ``..###############_,' ``--.._____..--' `''-----''` .... ==== // end::figure2a[] [.comment] end::figure2[] [[sovereign-orb]] .The Sovereign's Orb made invisible ==== .Outlines of the Sovereign's Orb [link=https://camelot.gov.example/sovereigns_orb.jpg,align=right] image::https://camelot.gov.example/sovereigns_orb.jpg[Orb,124,135] ==== [.comment] tag::index1[] // tag::index[] The solution to the impasse at the ((Cave of Caerbannog)) was provided by the successful deployment of the *Holy Hand Grenade of Antioch* (see <>) (((Holy Hand Grenade of Antioch))). Any similarity between the Holy Hand Grenade of Antioch and the mythical _Holy Spear of Antioch_ is purely intentional; (((relics, Christian))) any similarity between the Holy Hand Grenade of Antioch and the _Sovereign's Orb of the United Kingdom_ (see <>) is putatively fortuitous. (((relics, monarchic))) // end::index[] [.comment] end::index1[] [.comment] tag::dl1[] Tse, et al. Expires September 24, 2018 [Page 104] Internet-Draft AsciiRFC Specifications March 2018 // tag::dl[] Holy Hand Grenade of Antioch:: Ordnance deployed by Brother Maynard under the incantation of a lector, in order to dispense with the Foes of the Virtuous. See <>. Holy Spear of Antioch:: A supposed relic of the crucifixion of Jesus Christ, this is one of at least four claimed instances of the lance that pierced Christ's side. Its historical significance lies in inspiring crusaders to continue their siege of Antioch in 1098. Sovereign's Orb of the United Kingdom:: Part of the Crown Jewels of the United Kingdom, the Sovereign's Orb is a hollow gold sphere set with jewels and topped with a cross. It was made for Charles II in 1661. See <>. // end::dl[] [.comment] end::dl1[] [.comment] tag::bcp14_1[] // tag::bcp14[] The instructions in the _Book of Armaments_ on the proper deployment of the Holy Hand Grenade of Antioch [bcp14]#may# be summarized as follows, although this summary *SHALL NOT* be used as a substitute for a reading from the Book of Armaments: // end::bcp14[] [.comment] end::bcp14_1[] [.comment] tag::ol1[] // tag::ol[] . Preamble: St Attila Benediction . Feast of the People on Sundry Foods ** Lambs ** Sloths ** Carp ** Anchovies ** Orangutangs Tse, et al. Expires September 24, 2018 [Page 105] Internet-Draft AsciiRFC Specifications March 2018 ** Breakfast Cereals ** Fruit Bats ** _et hoc genus omne_ . Take out the Holy Pin . The Count [upperalpha] .. Count is to Three: no more, no less .. Not Four .. Nor Two, except if the count then proceeds to Three .. Five is Right Out . Lob the Holy Hand Grenade of Antioch towards the Foe . The Foe, being naughty in the *LORD's* sight, [bcp14]#shall# snuff it // end::ol[] [.comment] end::ol1[] This could also be represented in pseudocode as follows: [.comment] tag::listcontinuationblock1[] // tag::listcontinuationblock[] . Take out the Holy Pin . The Count + ---- integer count; for count := 1 step 1 until 3 do say(count) comment Five is Right Out ---- . Lob the Holy Hand Grenade of Antioch towards the Foe . Foe snuffs it // end::listcontinuationblock[] [.comment] end::listcontinuationblock1[] == Dramatis Personae The following human (more-or-less) protagonists were involved in the two incidents recounted as lore of the Knights of the Round Table: [.comment] tag::table1[] // tag::table[] Tse, et al. Expires September 24, 2018 [Page 106] Internet-Draft AsciiRFC Specifications March 2018 [grid=all,options="footer"] |=== |French Castle | Cave of Caerbannog 2+|King Arthur 2+|Patsy 2+|Sir Bedevere the Wise 2+|Sir Galahad the Pure 2+|Sir Lancelot the Brave 2+|Sir Robin the Not-quite-so-brave-as-Sir-Lancelot |French Guard with Outrageous Accent| Tim the Enchanter |Other French Guards | Brother Maynard | | The Lector .3+^|not yet recruited >|Sir Bors >|Sir Gawain >|Sir Ector |Retinue of sundry knights |Retinue of sundry more knights than at the French Castle |=== // end::table[] [.comment] end::table1[] === Past the Killer Rabbit Once the Killer Rabbit of Caerbannog (<>) had been dispatched, the Knights of the Round Table uncovered the last words of Joseph of Arimathea, inscribed on the Cave of Caerbannog in Aramaic. While the precise Aramaic wording has not survived, we trust the following Hebrew subtitles will serve as an acceptable substitute: [.comment] tag::hebrew1[] // tag::hebrew[] ____ .כאן אולי ימצאו המילים האחרונות של יוסף מארמתיה .מי אשר Tse, et al. Expires September 24, 2018 [Page 107] Internet-Draft AsciiRFC Specifications March 2018 יהיה אמיץ ובעל נפש טהורה יוכל למצוא את הגביע הקדוש בטירת אאאאאאאה "Here may be found the last words of Joseph of Arimathea. He who is valiant and pure of spirit may find the Holy Grail in the castle of — Aaaargh." ____ // end::hebrew[] [.comment] end::hebrew1[] == IANA Considerations IANA might consider a registry to track the mythical, especially ravaging beasts, such as the Killer Rabbit, who haunt the Internet. == Security Considerations Do not let the Killer Rabbit out under any circumstance. I repeat. Do not let the Killer Rabbit (<>) out. [.comment] tag::bibliography1[] // tag::bibliography[] [bibliography] == Normative References ++++ Key words for use in RFCs to Indicate Requirement Levels Tse, et al. Expires September 24, 2018 [Page 108] Internet-Draft AsciiRFC Specifications March 2018 ++++ [bibliography] == Informative References ++++ Monty Python and the Holy Grail DON'T SPEW A Set of Guidelines for Mass Unsolicited Mailings and Postings (spam*) RFC Format Framework Tse, et al. Expires September 24, 2018 [Page 109] Internet-Draft AsciiRFC Specifications March 2018 The Arte of ASCII: Or, An True and Accurate Representation of an Menagerie of Thynges Fabulous and Wonderful in Ye Forme of Character Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. ++++ Tse, et al. Expires September 24, 2018 [Page 110] Internet-Draft AsciiRFC Specifications March 2018 // end::bibliography[] [.comment] end::bibliography1[] A.2.2. Rendered as RFC XML v3 The Holy Hand Grenade of Antioch Camelot
Palace Camel Lot 1 Camelot England arthur.pendragon@ribose.com http://camelot.gov.example
General Operations and Management rabbits grenades Tse, et al. Expires September 24, 2018 [Page 111] Internet-Draft AsciiRFC Specifications March 2018 antioch camelot The menagerie of beasts and artefacts depicted in RFC8140 may be usefully supplemented by other renowned figures of Internet and more general lore. This document extends the menagerie to the seminal fable of the "Holy Hand Grenade of Antioch", as depicted in the Monty Python film "Monty Python and the Holy Grail", as well as "Spamalot", the musical inspired by the movie. Spamalot The relevance of the musical "Spamalot" to Internet lore should be obvious to the reader; but in case of doubt, see also Section 1 ("What is Spam*?") of RFC2635.
Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.
Introduction refers to the intended move of RFC formatting to XML2RFC v3 , in the following Tse, et al. Expires September 24, 2018 [Page 112] Internet-Draft AsciiRFC Specifications March 2018 terms:
Although the RFC Editor has recently dragged the IETF kicking and screaming into the twentieth century [RFC7990] [RFC7996], there is a yearning among all right-thinking Internet architects to "keep it simple" and to return to the olden days when pigs could be given thrust without anyone taking undue offence.
While no pigs, flying or otherwise, are involved in the transition to RFC XML v3, it is opportune to enhance the legendarium in the service of RFC XML v3, by illustrating its functionality through references to the mythology of Camelot, and particularly the incidents at the Cave of Caerbannog. The screaming move into the twenty-first century is accompanied by a move back to the late twentieth century, with ASCII stylings more wonted in haunts like ftp://ftp.wwa.com/pub/Scarecrow (known to be accessible in 1996.) There are two references to rabbits in Monty Python and the Holy Grail which are expounded on herewith:
Trojan Rabbit
In their siege of the French-occupied castle which may already contain an instance of the Grail, Sir Bedevere the Wise proposes to Tse, et al. Expires September 24, 2018 [Page 113] Internet-Draft AsciiRFC Specifications March 2018 use a Trojan Rabbit to infiltrate the castle, with a raiding party to take the French "not only by surprise, but totally unarmed." The proposal, unsurprisingly, proved abortive. The more so as the raiding party forgot to hide within the Trojan Rabbit, before the French soldiers took the Trojan Rabbit inside the castle.
Killer Rabbit of Caerbannog
Guarding the entrance to the Cave of Caerbannog; see .
The French-occupied castle The participants of that renowned exercise in cross-cultural communication, to wit the exchange between the Knights of the Round Table and the taunting French soldiers serving under Guy de Lombard are, properly speaking, outside the scope of this menagerie, being more or less human. Notwithstanding, severalish beasts both animated and wooden played a significant part in this encounter; most notably:
  • The Projectile Cow, see
  • The Trojan Rabbit, see
The Projectile Cow with an accompanying cannon .-.-.-.-.-.-.-.-.-.-.-.--.-.-.-.-.-.-.--.-.-.-.-.-.-.-.--.-. _-_---__--__--___-___-__-____---___-________---____-____-__- ._.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-…-.-.--..-.-.-.-.-.-..--.- ,..,.,.,.,.,..,.,,..,.,.,.,.,.,, ^^ .,,.,., ^^ .,.,.,.= Tse, et al. Expires September 24, 2018 [Page 114] Internet-Draft AsciiRFC Specifications March 2018 _>-.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-. .,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,., .,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {o} . ]> # .,.,.,. .-.-.--.-.-.-.-.-.--.-.-.-.--.-.-. [ ______] .-.-.-. .-.--.-.-.-.--.-.-.-.--.-.-.,.,., / [ ! ‘ ‘! .,.,..,.,.- .,.,.,.-.-,l,-,l.-,.,.,.,-.,*. / {_!MOO!_] . ., . . , .-.-.-.-.-.-.-.-.-.-.-.-.-.- /M / -.-<>.,.,..-.-, .-.-.--.-.-.-.-.-.-.-.-.--.. /MI LK\____ .-.-.-.-.-. .-.-.-.--.-.-.-.-.-.-.-.-.- /MILK mil_____k ,.,.,..-,- .-,-.-,-.,-.-,-.`-.-/-.. // -` // .-.p . .-.-. .-.--.-.-.-.-.-.-.-. // ., // .-.-.-.-.-.-.-.- .-.-.--.-.-.-.-.-.-. %____============ .-.-.--.-.-.-.-.- -.-.-.-.--.-.-.-.-.-. ! ! .,-.-.-,-,--,-.-,- ,--.-.-,--.--.-.,--, \ \ .-,-,--.-,--,-.---,-.-, ,-.-.-,-,-.-,-,-.--, + > .-,--,-.--,-,-.-.-,--,- ,--.-,--,-,--.---,- .-,-,--.--,--,-.---,-,-.-. .,.,.,.,..,.,.,.{A\ .,.,.,.,..,.,.,.,.,.,..,.,.,.,..,., .,.,.,.,.,.,.{GLASS\ .,..,.,.,.,.,..,.,.,.,.,.,.,..,.,.,. ,..,.,,.,,.,{OF|MILK\..,.,.,.,.,..,.,.,.,.,.,..,.,.,.,.,.,. ,.,..,.,,.,{ISWORTH},.,.,..,.,.,.,.,..,..,.,.,..,.,.,.,.,.,. .,.,.,.,.{EVERYTNG}.-.-.--..-.-.-.-.--..--.-.-.-.-.--.-.-.-. -.-.-.-{FORINFANTS}___--___-_-__-___--*(0~`~.,.,.,.,><><.><> _-__-_{BUTBETTER}-.-,-,-,-,-,-,-,-,.-^^^^.-.-.-.-.^^^7>>>,., .._...{WITHHONEY}-.-.-.-.-.-.-.-.-.-.-.RANDOM(BUSH)SHRUBS>_> GRASS_GRASS_GRASS_GRASS_GRASS_SOMEROCKS>GRASS>GRASS<GRASS>PC SOIL_ROOTS_SOIL_SOIL_ROCKS_SOIL_GRASS_GRASS_GRASS_ROCKS CLAY_ROCKS_REBBLES_CLAY_CLAY_CLAY_CLAY_GOLD_CLAY_CLAY>< CLAY_CLAY_SKLETONS_MORESOIL_CLAY_CLAY_CLAY_CLAY_CLAY_VR
The Trojan Rabbit with an automatic sliding door ___ ____ //_ \//\__\ || || | -__||_||__| // \--_ // ____ --___ // // \ \-_ // \\ @/ o || // ---- _____|| // // //\_//__ // Tse, et al. Expires September 24, 2018 [Page 115] Internet-Draft AsciiRFC Specifications March 2018 //-- --- \____ // // --- \______ // // , . ----- \_//_ // ,. --- \____ // .,v --- \___ // __ -- \_ || , _______________ //|| |-_ || | |''''''''''| // || | | || ' | | | || | | || | | | || | | || " | | 0 | ___||___ | | || | | | -------- | | ||___ | | | ______ | |- // \ | | | // \| _| \ // \ ____|---|__________|______// \/ | || X | / || X | / \\ /\\____/ \\ /___/ \\_____/ ----- \\_____/--- ----- -----
Image courtesy of Tse, et al. Expires September 24, 2018 [Page 116] Internet-Draft AsciiRFC Specifications March 2018 The exchange of projectile animals was the beginning of a long-running fruitful relationship between the British and the French peoples, which arguably predates the traditional English enmity with the French.
The Mythos of Caerbannog The Cave of Caerbannog has been well-established in the mythology of Camelot (as recounted by Monty Python) as the lair of the Legendary Black Beast of Arrrghhh, more commonly known today as the Killer Rabbit of Caerbannog . It is the encounter between the Killer Rabbit of Caerbannog and the Knights of the Round Table, armed with the Holy Hand Grenade of Antioch (see the following section), that we recount here through monospace font and multiple spaces.
The Killer Rabbit of Caerbannog The Killer Rabbit of Caerbannog, that most formidable foe of the Knights and of all that is holy or carrot-like, has been depicted diversely in lay and in song. We venture to say, Tse, et al. Expires September 24, 2018 [Page 117] Internet-Draft AsciiRFC Specifications March 2018 contra the claim made in Ze Vompyre, that the Killer Rabbit of Caerbannog truly is the most afeared of all the creatures. Short of sanctified ordnance such as , there are few remedies known against its awful lapine powers. The following depiction of the fearsome beast has been sourced from Rabbit-SCII, accompanied by C code that was used in this accurate depiction of the Killer Rabbit:
A Photo Of The Killer Rabbit of Caerbannog Taken In Secret \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\\\^^^^^^^^^^^^^^^^^^^^^^\\\\\\\\\\\\\\\\\ \\\\\\\\\\\\\\\\\\\<<#MWSHARPMWMWMWTEETHWMWWM>>>\\\\\\\\\\\\ \\\\\\\\\\\\\\\<<<#WMMWMWDEEPMDARKWCAVEMWWMMWM##>>>>\\\\\\\\ \\\\\\\\\\\\\<<#WMWMWMWMWWM/^MWMWMWMWMWMW^WMWMWMMW#>>>\\\\\\ \\\\\\\\\\\\<<#WMWMBEASTMW// \MWABBITWMW/ \MWMWMWMW##\\\\\\\ \\\\\\\\\\##MWMWMMWMWMWMWM\\ \MWMWMWMW/ /MWMWMWMWM##\\\\\\ \\\\\\\\##WMWMWMWMMWMWMWMWM\\ \MWMWMW/ /MWMWMWMMWMWMWM##\\ \\\\\\\##MWMMRAVENOUSMWMWMWM\\ \====/ /MWMRABBITMWMWMWMW## \\\\\\##MWMWMWMWMMWMWMWMWMW[[ ]WMWMWMMWMWMWMWMWMW \\\\\##MWMWMWMWCARNIVOROUSW[[ 3 3 ]MWMWTOOMDARKWMWMMW \\\\##MWMWDARKMWMWMWMWMWMWM//\ o /MWMWMWMMWMWMWMMWMWM \\##MWMWMMKILLERABBITWMWMM//| \___vv___/ \WMPITCHWBLACKWMWMW \##MWMWMWMMWMWMWMWMWMMWMW// | \-^^-/ |MWMWMWMMWMWMWMWMWM MWMWMWMMWMWVERYMDARKWMMW// | |MWMCAERBANNOGWMWMW MWMWMWMMWMWMWMWMWMWMWMM{{ / /MWMWMMWMWMWMWMWMWM Tse, et al. Expires September 24, 2018 [Page 118] Internet-Draft AsciiRFC Specifications March 2018 MULTRADARKWMWMHELPMWMWMW\\ \ | | |MWMCANMMWMWMWMMWMWW MWMWMWMWMMWMWMWMWMMWMWMWM\\ | |_ | |_WMWMMYOUMWMMWWMWMW MWMMWMWMWMWMBLACKWMWMWMWWM\_|__-\-----\__-\MWMWMWMREADMWMWWM MWMWMWMMWMWMWMWMMWMWMWWMWMWMWMMWMWMWMWMWMWMWMWMWMWMWMMTHISWW MWVERYMMSCARYMWMWWMWMMWMWMWMWMWMWMWMWMWMWMWMWWMWMMWMWIWM'.', MWMWMMWMW======MWMMCANTWSEEMAMTHINGMMWMWMWMWMWMWMBETMMW` . ` MWMWMWM// SKULL \MWMWMWMMWSCREAMMMWMWMWMMWMNOTMWMWMWW ` . \ MWMWMW|| |X||X| |MWMWCALLMMEWMMWMWMMWMWMWMWWM - ` ~ . , ' MWMWMW||___ O __|MWMWMWMMWMWMWMWMMW' ___________// -_^_- MWMWMW \\||_|_||MWMW ' . . <_|_|_||_|__| \O/ MW \\/\||v v|| -\\-------___ . ., \ | \\| \_CHIN/ ==-(|CARROT/)\> \\/||// v\/||/ ) /--------^-^ ,. \|// # \(/ .\\|x// " ' ' . , \\||// \||\\\// \\
C Code To Lure Killer Rabbit Back To Cave <CODE BEGINS> /* Locate the Killer Rabbit */ int type; unsigned char *killerRabbit = LocateCreature(&caerbannog, "killer rabbit"); if( killerRabbit == 0 ){ puts("The Killer Rabbit of Caerbannog is out of town."); return LOST_CREATURE; } /* Load Cave */ unsigned char *cave = LoadPlace(&caerbannog, "The Cave Of Caerbannog"); if( cave == 0 ){ puts("The Cave of Caerbannog must have moved."); return LOST_PLACE; } /* Lure the Killer Rabbit back into the Cave */ unsigned char *carrot = allocateObjectInPlace( carrot("fresh"), cave); if( carrot == 0 ){ puts("No carrot, no rabbit."); return LOST_LURE; } /* Finally, notify the Killer Rabbit to act */ return notifyCreature(killerRabbit, &carrot); <CODE ENDS>
Tse, et al. Expires September 24, 2018 [Page 119] Internet-Draft AsciiRFC Specifications March 2018 On the beast's encounter with the Knights of the Round Table, the following personnel engaged with it in combat:
  • Killed
    • Sir Bors
    • Sir Gawain
    • Sir Ector
  • Soiled Himself
    • Sir Robin
  • Panicked
    • King Arthur
  • Employed Ordnance
    • The Lector
    • Brother Maynard
  • Scoffed
    • Tim the Enchanter
Holy Hand Grenade of Antioch Tse, et al. Expires September 24, 2018 [Page 120] Internet-Draft AsciiRFC Specifications March 2018
The Holy Hand Grenade of Antioch (don't pull the pin) ______ \\/ \/ __\\ /__ || //\ | ||__\\/ __| || | ,---, || |====`\ | || | '---' ,--'*`--, _||#|***|#| _,/.-'#|* *|#`-._ ,,-'#####| |#####`-. ,,'########| |########`, //##########| o |##########\ ||###########| |###########| ||############| o |############| ||------------' '------------| ||o o o o o o o o o o| |-----------------------------| ||###########################| \\#########################/ `..#####################,' ``..###############_,' ``--.._____..--' `''-----''`
The Sovereign's Orb made invisible
The solution to the impasse at the Cave of Caerbannog was provided by the successful deployment of the Holy Hand Grenade of Antioch (see ) . Tse, et al. Expires September 24, 2018 [Page 121] Internet-Draft AsciiRFC Specifications March 2018 Any similarity between the Holy Hand Grenade of Antioch and the mythical Holy Spear of Antioch is purely intentional; any similarity between the Holy Hand Grenade of Antioch and the Sovereign's Orb of the United Kingdom (see ) is putatively fortuitous.
Holy Hand Grenade of Antioch
Ordnance deployed by Brother Maynard under the incantation of a lector, in order to dispense with the Foes of the Virtuous. See .
Holy Spear of Antioch
A supposed relic of the crucifixion of Jesus Christ, this is one of at least four claimed instances of the lance that pierced Christ's side. Its historical significance lies in inspiring crusaders to continue their siege of Antioch in 1098.
Sovereign's Orb of the United Kingdom
Part of the Crown Jewels of the United Kingdom, the Sovereign's Orb is a hollow gold sphere set with jewels and topped with a cross. It was made for Charles II in 1661. See .
The instructions in the Book of Armaments on the proper deployment of the Holy Hand Grenade of Antioch MAY be summarized as follows, although this summary SHALL NOT be used as a substitute for a reading from the Book of Armaments: Tse, et al. Expires September 24, 2018 [Page 122] Internet-Draft AsciiRFC Specifications March 2018
  1. Preamble: St Attila Benediction
  2. Feast of the People on Sundry Foods
    • Lambs
    • Sloths
    • Carp
    • Anchovies
    • Orangutangs
    • Breakfast Cereals
    • Fruit Bats
    • et hoc genus omne
  3. Take out the Holy Pin
  4. The Count
    1. Count is to Three: no more, no less
    2. Not Four
    3. Nor Two, except if the count then proceeds to Three
    4. Five is Right Out
  5. Lob the Holy Hand Grenade of Antioch towards the Foe
  6. The Foe, being naughty in the LORD's sight, SHALL snuff it
This could also be represented in pseudocode as follows:
    Tse, et al. Expires September 24, 2018 [Page 123] Internet-Draft AsciiRFC Specifications March 2018
  1. Take out the Holy Pin
  2. The Count
    integer count; for count := 1 step 1 until 3 do say(count) comment Five is Right Out
  3. Lob the Holy Hand Grenade of Antioch towards the Foe
  4. Foe snuffs it
Dramatis PersonaeThe following human (more-or-less) protagonists were involved in the two incidents recounted as lore of the Knights of the Round Table: Tse, et al. Expires September 24, 2018 [Page 124] Internet-Draft AsciiRFC Specifications March 2018
French Castle Cave of Caerbannog
King Arthur
Patsy
Sir Bedevere the Wise
Sir Galahad the Pure
Sir Lancelot the Brave
Sir Robin the Not-quite-so-brave-as-Sir-Lancelot
French Guard with Outrageous Accent Tim the Enchanter
Other French Guards Brother Maynard
The Lector
not yet recruited Sir Bors
Sir Gawain
Sir Ector
Retinue of sundry knights Retinue of sundry more knights than at the French Castle
Past the Killer RabbitOnce the Killer Rabbit of Caerbannog () had been dispatched, the Knights of the Round Table uncovered the last words of Joseph of Arimathea, inscribed on the Cave of Caerbannog Tse, et al. Expires September 24, 2018 [Page 125] Internet-Draft AsciiRFC Specifications March 2018 in Aramaic. While the precise Aramaic wording has not survived, we trust the following Hebrew subtitles will serve as an acceptable substitute:
.כאן אולי ימצאו המילים האחרונות של יוסף מארמתיה .מי אשר יהיה אמיץ ובעל נפש טהורה יוכל למצוא את הגביע הקדוש בטירת אאאאאאאה "Here may be found the last words of Joseph of Arimathea. He who is valiant and pure of spirit may find the Holy Grail in the castle of — Aaaargh."
IANA Considerations IANA might consider a registry to track the mythical, especially ravaging beasts, such as the Killer Rabbit, who haunt the Internet.
Security ConsiderationsDo not let the Killer Rabbit out under any circumstance. I repeat. Do not let the Killer Rabbit () out. Tse, et al. Expires September 24, 2018 [Page 126] Internet-Draft AsciiRFC Specifications March 2018
Normative References Informative References Monty Python and the Holy Grail
A.3. Example 3: "An API For Calendar-Based Fortune Heuristics Services" in AsciiRFC This example is available in the following formats: o AsciiRFC [git-divination-cfapi] o Internet-Draft [I-D.divination-cfapi] Tse, et al. Expires September 24, 2018 [Page 127] Internet-Draft AsciiRFC Specifications March 2018 o Text, RFC XML, PDF and HTML on the IETF Datatracker [datatracker-divination-cfapi] A.3.1. In AsciiRFC = An API For Calendar-Based Fortune Heuristics Services Gabriel Destiny; Charise Luck :doctype: internet-draft :abbrev: Calendar Fortune Heuristics API :name: draft-divination-cfapi-00 :status: informational :ipr: trust200902 :area: Internet :submission-type: independent :intended-series: informational :revdate: 2018-03-23T00:00:00Z :lastname: Destiny :fullname: Gabriel Destiny :forename_initials: G. :organization: Divination Inc. :email: gabriel.destiny@ribose.com :street: 9288 N Divine Street :city: Dunn :code: 28334 :region: NC :country: United States of America :lastname_2: Luck :fullname_2: Charise Luck :forename_initials_2: C. :organization_2: Divination Inc. :email_2: charise.luck@ribose.com :street_2: 9288 N Divine Street :city_2: Dunn :code_2: 28334 :region_2: NC :country_2: United States of America [.comment] tag::sample[] // tag::sample[] [abstract] This document describes a JSON HTTP API for online services that provide calendar-based fortune heuristics. == Introduction Tse, et al. Expires September 24, 2018 [Page 128] Internet-Draft AsciiRFC Specifications March 2018 Fortune-telling, the practice of predicting information about a person's life, is an activity practiced throughout history. While there are myriad forms of fortune telling methodologies, this document applies to a particular form of service that provides fortune heuristics, commonly known as "luck", for a particular subject based on a calendar-based input. Since HTTP <> status codes are insufficient to convey information about fortune heuristics, this specification defines a simple JSON <> document format for this purpose. The response can be used by HTTP APIs to deliver results to non-human clients or to an end-user. == Conventions Used in This Document The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*NOT RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document are to be interpreted as described in BCP 14 <> <> when, and only when, they appear in all capitals, as shown here. The following definitions apply in this document: Well-known URI:: This specification makes use of the "well-known URI" feature of HTTP servers <> to provide a bootstrapping URI for the client usage of fortune heuristics services. Root of Fortune:: The service discovery endpoint that provides a URI list of available fortune heuristic endpoints available, in accordance with <>. == Fortune Heuristics Service Well-Known URI A well-known URI called "fortune" is registered by this specification for fortune heuristics services (see <>). Services complying with this document *SHOULD* have its well-known URI pointing (directly or through redirection) to the Root of Fortune. The Root of Fortune can be used by the client for service discovery, namely, the available calendar-based fortune heuristics services available on the server, as specified in Tse, et al. Expires September 24, 2018 [Page 129] Internet-Draft AsciiRFC Specifications March 2018 <>. === Well-Known URI Redirection Servers *MUST* redirect HTTP requests for that resource to the actual "context path" using one of the available mechanisms provided by HTTP <> (e.g., using a 301, 303, or 307 response). Clients *MUST* handle HTTP redirects on the well-known URI. === Well-Known URI Cache Behavior Servers *SHOULD* set an appropriate Cache-Control header value (as according to <>) in the redirect response to set caching behavior as required by the type of response generated. == New HTTP Methods: SEEK and DIVINE This specification defines two new HTTP methods: "SEEK" and "DIVINE" methods for HTTP <>. While HTTP GET requests are treated equivalently as the "SEEK" and "DIVINE" requests, its usage is discouraged and therefore *SHOULD NOT* be used. Usage of these methods are defined in the sections below. == Defined Data Types: Date-Time Formats This specification defines a number of date-time formats as according to the conventions of <> for the unambiguous communication between client and server. The types defined are as follows. `DATETIME`:: As described in <>, with the addition that reduced accuracy representations described in <> are supported. Reduced accuracy date and times are accepted where a date or time component (2-digits long) is replaced by "--". Tse, et al. Expires September 24, 2018 [Page 130] Internet-Draft AsciiRFC Specifications March 2018 + For example, the date time "2018-04---T01:02:00Z" represents the UTC time of 1:02am, on an unknown day within April of the year 2018. `DATE`:: As described in "DATETIME", but the "time" component will not be taken into account in the algorithm. [#service-discovery] == Fortune Heuristics Service Discovery [#root-of-fortune] === Root of Fortune Path URI ("/") The Root of Fortune URI, defined as "/" in this document, is used for service discovery on types of calendar-based fortune heuristics available. An empty SEEK request with the "application/json" request type *MUST* be sent to this endpoint to retrieve the available endpoints. All other HTTP methods *MUST NOT* be supported at this URI. An example of such a response is as follows: [source,json] ---- HTTP/1.1 200 Success Content-Type: application/json Content-Language: en { "diviners" : [ "/astrology", "/bazi", ] } ---- A service discovery object *MUST* have the following members: `diviners`:: (JSON array) An array that contains endpoints that conform to this specification. All endpoints listed here are relative to the Root of Fortune path. For example, the path "/astrology" listed in the example has an endpoint path of "[root-of-fortune]/astrology", where "[root-of-fortune]" indicates the real path of the Root of Fortune. Tse, et al. Expires September 24, 2018 [Page 131] Internet-Draft AsciiRFC Specifications March 2018 // end::sample[] [.comment] end::sample[] [#service-endpoint] == Fortune Heuristics Service Endpoint An endpoint offering fortune heuristics services *MUST* adhere to specifications in this section. A service *MAY* implement multiple divination services based on different divination methods, such as the digital oracle shown in <>. [[digital-oracle]] .Dimensional Eye, a digital oracle that communicates through one button ==== [alt=An incarnation of the Dimensional Eye, in ASCII] .... __ __===^-\ __=== -\ __===- -\ __===- -\ ___===- -\ ===- ---__ -\ \\\ |||^^\ \__ -\ \\\ ||| \__ -\ \\\ ||| ______\_ -\ \\\ ||| _/-******\\__ -\ \\\ || /-****_****-\ \_ -\ \\\ || |-***/ \***-\ \_ -\ \\\ || |-***\___/***-| \ -\ \\\ || \-*********-/ __--/ -\ \\\ || \-******/__-- -\ \\\ || __-- -\ \\\ || __-- -\ \\\ ||__-- -\ \\\ -\ \\\ -\ \\\ -\ \\\ -\ \\\ __ -\ \\\ //##\\ -\ \\\ \\##// -\ \\\ ^^ __--==^ Tse, et al. Expires September 24, 2018 [Page 132] Internet-Draft AsciiRFC Specifications March 2018 \\\ __--=== \\\ __--=== \\\ __--=== \\\ __--== \\= .... ==== [#endpoint-specification-request] === Service Specification Request To retrieve capabilities and parameters of an endpoint complying with this specification, a service specification JSON object is returned. An empty SEEK request with the "application/json" request type *MUST* be sent to this endpoint to retrieve the service specification that describes parameters accepted by this endpoint. Two examples of such a response are given below. [source,json] ---- HTTP/1.1 200 Success Content-Type: application/json Content-Language: en { "description": "Gaze into your upcoming luck!", "details": "https://divine.example.com/manual/astrology-api", "parameters": { "birthday": { "type": "DATE", "description": "Your birth date in UTC" }, "targetDateBegin": { "type": "DATE", "description": "Start of the target date range to report on" }, "targetDateEnd": { "type": "DATE", "description": "End of the target date range to report on" }, "interval": { "values": { "D": "Daily", "M": "Monthly", "Y": "Yearly" Tse, et al. Expires September 24, 2018 [Page 133] Internet-Draft AsciiRFC Specifications March 2018 }, "description": "Available intervals to report on." } } } ---- [source,json] ---- HTTP/1.1 200 Success Content-Type: application/json Content-Language: en { "description": "Matches and mis-matches according to the " "Yin Yang and Five Elements techniques", "details": "https://divine.example.com/manual/bazi-api", "parameters": { "birthday": { "type": "DATETIME", "description": "Your birth date and time in UTC" }, "targetDateBegin": { "type": "DATETIME", "description": "Start of the target date/time range to report on" }, "targetDateEnd": { "type": "DATETIME", "description": "End of the target date/time range to report on" }, "interval": { "values": { "H": "Hourly", "D": "Daily", "M": "Monthly", "Y": "Yearly" }, "description": "Available intervals to report on." } } } ---- [#service-endpoint-specification] === Service Specification Object A service specification object *MUST* contain the following members. Tse, et al. Expires September 24, 2018 [Page 134] Internet-Draft AsciiRFC Specifications March 2018 `description`:: (string) A short, human-readable summary of the fortune heuristic service at this endpoint. This *SHOULD* be a stable reference. `details`:: (URI, optional) A URI reference that provides further details for human consumption, such as API documentation that includes details of parameters accepted or response states. `parameters`:: (object, mandatory) An object that specifies what parameters are accepted by this endpoint. Each parameter key within this object specifies an accepted parameter name, and its value is a parameter specification object, which is described below. A parameter specification object *SHOULD* contain the following members: `type`:: (string, optional) The value type accepted by this parameter. Value types are described in this document. This member is mutually exclusive with `values`. `description`:: (string, mandatory) The purpose of this parameter. `values`:: (object, optional) The accepted values of this parameter, unlisted values *SHOULD* not be accepted by the parameter. Each key within this object specifies an accepted value, and its value provides a description of the purpose of the value. [#endpoint-report] == Fortune Heuristics Report Request and Response [#endpoint-report-request] === Fortune Heuristics Report Request A request using the HTTP "DIVINE" method and the "application/json" type *MUST* be sent to the fortune heuristic endpoint to retrieve results for a fortune heuristic query. The request made *MUST* conform to the specifications of the endpoint, as retrieved via the "SEEK" method described in <>. An example of a request is provided below. Tse, et al. Expires September 24, 2018 [Page 135] Internet-Draft AsciiRFC Specifications March 2018 [source] ---- URI: /divination/astrology Method: DIVINE Content-Type: application/json Content-Language: en { "birthday": "1976-02-11T00:00:00Z", "targetDateBegin": "2018-01-01T00:00:00Z", "targetDateEnd": "2019-01-01T00:00:00Z", "interval": "M" } ---- [#endpoint-report-response] === Fortune Heuristics Report Response A fortune heuristic query using the "DIVINE" method triggers a response that contains a fortune heuristics report. A successful response returns a JSON object that *MUST* conform to the object structure described in this section. A report object *SHOULD* contain the following members: `type`:: (URI, mandatory) A URI that defines the type of the report located at the `report` key of this object. `report`:: (object, mandatory) An object that contains two keys, `intervals` and `events`. The `intervals` object contains an array of interval objects that matches the demanded intervals in the request within the target date range. The `events` object contains an array of significant event objects within the target date range. An example of a response is provided below. [source] ---- URI: /divination/astrology Method: DIVINE HTTP/1.1 200 Success Content-Type: application/json Content-Language: en Tse, et al. Expires September 24, 2018 [Page 136] Internet-Draft AsciiRFC Specifications March 2018 { "type": "https://association-of.astrology/reports/monthly", "report": { "intervals": [ { "dateStart": "2018-01-01T00:00:00Z", "dateEnd": "2018-02-01T00:00:00Z", "categories": [ { "category": "https://divine.example.com/astrology/categories/health" "value": 80, "description": "Charge ahead with excellent health." }, { "category": "https://divine.example.com/astrology/categories/love" "value": 70, "description": "Give a certain person or situation another try!" }, { "category": "https://divine.example.com/astrology/categories/finance" "value": 5, "description": "You've just realized that you don't have any cash on hand." } ] }, { "dateStart": "2018-02-01T00:00:00Z", "dateEnd": "2018-03-01T00:00:00Z", "..." }, "..." ], "events": [ { "dateStart": "2018-01-15T03:20:00", "dateEnd": "2018-01-16T20:22:15", "description": "The planet of growth and good luck, Jupiter will make a harmonious connection with power planet Pluto, helping you connect with influential people", "recommendation": "Engage in networking during this time." }, { "dateStart": "2018-03-22T00:12:40", Tse, et al. Expires September 24, 2018 [Page 137] Internet-Draft AsciiRFC Specifications March 2018 "dateEnd": "2018-03-28T02:45:03", "description": "Communication planet Mercury enters your sign, which will find you in a busier and chattier mood.", "recommendation": "Take charge of work with your newfound energy." } "..." ] } } ---- Fortune heuristic reports are created by a divination output that *MAY* requires quantitative interpretation. A sample representation of interpreting a graphical divination output is provided in <>. [[divination-message]] .Forty-nine yarrow sticks reveals a mystical message on fortune ==== [alt=A mystical pattern in ASCII] .... 0000000000000000000000000 0000000000000000000000001 G 1000000000000000000000000 0000000000000000000000011 R 1100000000000000000000000 0000000000000000000000111 A 1110000000000000000000000 0000000000000000000001111 C 1111000000000000000000000 0000000000000000000011111 E 1111100000000000000000000 0000000000000000000111111 , 1111110000000000000000000 0000000000000000001111111 1111111000000000000000000 0000000011111111111111111 M 1111111111111111100000000 0000000111111111111111111 E 1111111111111111110000000 0000001111111111111111111 R 1111111111111111111000000 0000011111111111111111111 C 1111111111111111111100000 0000111111111111111111111 Y 1111111111111111111110000 0001111111111111111111111 , 1111111111111111111111000 0011111111111111111111111 1111111111111111111111100 0111111111111111111111111 A 1111111111111111111111110 0000000000000000011111111 N 1111111100000000000000000 0000000000000000111111111 D 1111111110000000000000000 0000000000000001111111111 1111111111000000000000000 0000000000000011111111111 P 1111111111100000000000000 0000000000000111111111111 E 1111111111110000000000000 0000000000001111111111111 A 1111111111111000000000000 0000000000011111111111111 C 1111111111111100000000000 0000000000111111111111111 E 1111111111111110000000000 0000000001111111111111111 . 1111111111111111000000000 Tse, et al. Expires September 24, 2018 [Page 138] Internet-Draft AsciiRFC Specifications March 2018 .... ==== [#endpoint-report-interval-obj] === Report Interval Object The `intervals` value of a report object contains a number of report intervals -- each representing a non-overlapping period of the selected interval length. When all of these intervals are put together, the combined period *MUST* fully cover the requested report target period. An example interval object is shown below. [source,json] ---- { "dateStart": "2018-01-01T00:00:00Z", "dateEnd": "2018-02-01T00:00:00Z", "categories": [ { "category": "https://divine.example.com/astrology/categories/health" "value": 80, "description": "Charge ahead with your excellent health." }, { "category": "https://divine.example.com/astrology/categories/love" "value": 70, "description": "Give a certain person or situation another try!" }, { "category": "https://divine.example.com/astrology/categories/finance" "value": 5, "description": "You've just realized that you don't have any cash on hand." } ] } ---- An interval object *MUST* contain the following members: `dateStart`:: Tse, et al. Expires September 24, 2018 [Page 139] Internet-Draft AsciiRFC Specifications March 2018 (datetime, mandatory) This value specifies the start of the period which this interval object applies to. `dateEnd`:: (datetime, mandatory) This value specifies the end of the period which this interval object applies to. In the given example, the `categories` key is an implementation specific object that details heuristic results returned by the selected algorithm. This *MAY* differ in different algorithms. [#endpoint-report-event-obj] === Report Events Object The `events` value of a report object contains a number of event objects. Each event object represents an event relevant to the calculation of fortune heuristics during a target report period. These events *MAY* be of variable time lengths, and *MAY* be overlapping amongst each other. The following example demonstrates two event objects the service determines relevant to a user's query. [source,json] ---- { "dateStart": "2018-01-15T03:20:00", "dateEnd": "2018-01-16T20:22:15", "description": "The planet of growth and good luck, Jupiter will make a harmonious connection with power planet Pluto, helping you connect with influential people", "recommendation": "Engage in networking during this time." }, { "dateStart": "2018-03-22T00:12:40", "dateEnd": "2018-03-28T02:45:03", "description": "Communication planet Mercury enters your sign, which will find you in a busier and chattier mood.", "recommendation": "Take charge of work with your newfound energy." } ---- Similar to an interval object, an event object *MUST* contain the following members: `dateStart`:: (datetime, mandatory) This value specifies the start of the period Tse, et al. Expires September 24, 2018 [Page 140] Internet-Draft AsciiRFC Specifications March 2018 described by the event. `dateEnd`:: (datetime, mandatory) This value specifies the end of the period described by the event. In the given example, the keys `description` and `recommendation` are implementation-specific details. This *MAY* differ in different algorithms. [#endpoint-report-errors] === Report Generation Errors This specification makes use of normal HTTP error codes with the following extensions. Errors *MUST* be returned using the Problem JSON Structure as accordance with <>. 422 Unprocessable Entity:: For example, a malformed date-time parameter, or an illogical input, such as when the subject's birthday occurs after the report target date period. 473 Beyond Existing Capability:: The service determines that the outcome is too difficult to predict. For example, in the case where the calculation is too complex to complete in a certain time period. The service *SHOULD* issue this response code to indicate that the client should not try the same request again. 474 Outcome Impossible:: The service determines that the outcome is impossible. For example, when the algorithm determines that the subject will have deceased before the start of the requested target period. [#security] == Security Considerations * TLS <> and authenticated HTTP requests should be used to protect the DIVINE request and responses due to the personal nature of information transmitted. * A client *SHOULD* verify the identity of the server on every Tse, et al. Expires September 24, 2018 [Page 141] Internet-Draft AsciiRFC Specifications March 2018 request to prevent impersonation or man-in-the-middle attacks, as data transmitted to and from the server is sensitive information, and at times critical information to the user. * Synchronization of client and server time *MUST* be well-considered in the implementation of this specification. A mismatch of client and server time *MAY* lead to algorithm miscalculations that can cause mistaken choices of a user that depends on the reliability of this system. [#iana] == IANA Considerations === Well-Known URI Registrations This document defines a well-known URI using the registration procedure and template from <>. ==== "fortune" Well-Known URI Registration URI suffix:: fortune Change controller:: IETF Specification document(s):: This document Related information:: N/A. [.comment] tag::sample[] // begin::sample[] [bibliography] == Normative References ++++ Key words for use in RFCs to Indicate Requirement Levels Tse, et al. Expires September 24, 2018 [Page 142] Internet-Draft AsciiRFC Specifications March 2018 In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Defining Well-Known Uniform Resource Identifiers (URIs) This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. [STANDARDS-TRACK] Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing Tse, et al. Expires September 24, 2018 [Page 143] Internet-Draft AsciiRFC Specifications March 2018 The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations. Hypertext Transfer Protocol (HTTP/1.1): Caching The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response Tse, et al. Expires September 24, 2018 [Page 144] Internet-Draft AsciiRFC Specifications March 2018 messages. Problem Details for HTTP APIs This document defines a "problem detail" as a way to carry machine- readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Tse, et al. Expires September 24, 2018 [Page 145] Internet-Draft AsciiRFC Specifications March 2018 The JavaScript Object Notation (JSON) Data Interchange Format JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. ++++ [bibliography] == Informative References ++++ ISO/DIS 8601-1:2018, Data elements and interchange formats -- Information interchange -- Representation of dates and times -- Part 1: Basic rules ISO/IEC
http://www.iso.org
Tse, et al. Expires September 24, 2018 [Page 146] Internet-Draft AsciiRFC Specifications March 2018
Date and Time on the Internet: Timestamps The Transport Layer Security (TLS) Protocol Version 1.2 This document specifies Version 1.2 of the Transport Layer Security (TLS) protocol. The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. [STANDARDS-TRACK] ++++ [appendix] Tse, et al. Expires September 24, 2018 [Page 147] Internet-Draft AsciiRFC Specifications March 2018 == Acknowledgements The authors thank the following individuals for their valuable feedback on this specification, and commend them for making fortune heuristics more accessible for the benefit of mankind. // end::sample[] [.comment] end::sample[] A.4. Rendered as RFC XML v3 An API For Calendar-Based Fortune Heuristics Services Divination Inc.
9288 N Divine Street Dunn NC 28334 United States of America gabriel.destiny@ribose.com
Tse, et al. Expires September 24, 2018 [Page 148] Internet-Draft AsciiRFC Specifications March 2018 Divination Inc.
9288 N Divine Street Dunn NC 28334 United States of America charise.luck@ribose.com
Internet This document describes a JSON HTTP API for online services that provide calendar-based fortune heuristics.
IntroductionFortune-telling, the practice of predicting information about a person’s life, is an activity practiced throughout history. While there are myriad forms of fortune telling methodologies, this document applies to a particular form of service that provides fortune heuristics, commonly known as "luck", for a particular subject based on a calendar-based input. Since HTTP status codes are insufficient to convey information about fortune heuristics, this specification defines a simple JSON document format for this purpose. The response can be used by HTTP APIs to deliver results to non-human clients or to an end-user.
Conventions Used in This DocumentThe key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD Tse, et al. Expires September 24, 2018 [Page 149] Internet-Draft AsciiRFC Specifications March 2018 NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. The following definitions apply in this document:
Well-known URI
This specification makes use of the "well-known URI" feature of HTTP servers to provide a bootstrapping URI for the client usage of fortune heuristics services.
Root of Fortune
The service discovery endpoint that provides a URI list of available fortune heuristic endpoints available, in accordance with .
Fortune Heuristics Service Well-Known URIA well-known URI called "fortune" is registered by this specification for fortune heuristics services (see ). Services complying with this document SHOULD have its well-known URI pointing (directly or through redirection) to the Root of Fortune. The Root of Fortune can be used by the client for service discovery, namely, the available calendar-based fortune heuristics services available on the server, as specified in .
Well-Known URI RedirectionServers MUST redirect HTTP requests for that resource to the actual "context path" using one of the available mechanisms provided by HTTP (e.g., using a 301, 303, or 307 response). Clients MUST handle HTTP redirects on the well-known URI.
Well-Known URI Cache Behavior Servers SHOULD set an appropriate Cache-Control header value (as Tse, et al. Expires September 24, 2018 [Page 150] Internet-Draft AsciiRFC Specifications March 2018 according to ) in the redirect response to set caching behavior as required by the type of response generated.
New HTTP Methods: SEEK and DIVINEThis specification defines two new HTTP methods: "SEEK" and "DIVINE" methods for HTTP . While HTTP GET requests are treated equivalently as the "SEEK" and "DIVINE" requests, its usage is discouraged and therefore SHOULD NOT be used. Usage of these methods are defined in the sections below.
Defined Data Types: Date-Time FormatsThis specification defines a number of date-time formats as according to the conventions of for the unambiguous communication between client and server. The types defined are as follows.
DATETIME
As described in , with the addition that reduced accuracy representations described in are supported. Reduced accuracy date and times are accepted where a date or time component (2-digits long) is replaced by "--". For example, the date time "2018-04---T01:02:00Z" represents the UTC time of 1:02am, on an unknown day within April of the year 2018.
DATE
As described in "DATETIME", but the "time" component will not be taken into account in the algorithm.
Tse, et al. Expires September 24, 2018 [Page 151] Internet-Draft AsciiRFC Specifications March 2018
Fortune Heuristics Service Discovery
Root of Fortune Path URI ("/")The Root of Fortune URI, defined as "/" in this document, is used for service discovery on types of calendar-based fortune heuristics available. An empty SEEK request with the "application/json" request type MUST be sent to this endpoint to retrieve the available endpoints. All other HTTP methods MUST NOT be supported at this URI. An example of such a response is as follows:
HTTP/1.1 200 Success Content-Type: application/json Content-Language: en { "diviners" : [ "/astrology", "/bazi", ] }
A service discovery object MUST have the following members:
diviners
(JSON array) An array that contains endpoints that conform to this specification. All endpoints listed here are relative to the Root of Fortune path. For example, the path "/astrology" listed in the example has an endpoint path of "[root-of-fortune]/astrology", where "[root-of-fortune]" indicates the real path of the Root of Fortune.
Fortune Heuristics Service EndpointAn endpoint offering fortune heuristics services MUST adhere to Tse, et al. Expires September 24, 2018 [Page 152] Internet-Draft AsciiRFC Specifications March 2018 specifications in this section. A service MAY implement multiple divination services based on different divination methods, such as the digital oracle shown in .
Dimensional Eye, a digital oracle that communicates through one button __ __===^-\ __=== -\ __===- -\ __===- -\ ___===- -\ ===- ---__ -\ \\\ |||^^\ \__ -\ \\\ ||| \__ -\ \\\ ||| ______\_ -\ \\\ ||| _/-******\\__ -\ \\\ || /-****_****-\ \_ -\ \\\ || |-***/ \***-\ \_ -\ \\\ || |-***\___/***-| \ -\ \\\ || \-*********-/ __--/ -\ \\\ || \-******/__-- -\ \\\ || __-- -\ \\\ || __-- -\ \\\ ||__-- -\ \\\ -\ \\\ -\ \\\ -\ \\\ -\ \\\ __ -\ \\\ //##\\ -\ \\\ \\##// -\ \\\ ^^ __--==^ \\\ __--=== \\\ __--=== \\\ __--=== \\\ __--== \\=
Service Specification RequestTo retrieve capabilities and parameters of an endpoint complying with this specification, a service specification JSON object is Tse, et al. Expires September 24, 2018 [Page 153] Internet-Draft AsciiRFC Specifications March 2018 returned. An empty SEEK request with the "application/json" request type MUST be sent to this endpoint to retrieve the service specification that describes parameters accepted by this endpoint. Two examples of such a response are given below.
HTTP/1.1 200 Success Content-Type: application/json Content-Language: en { "description": "Gaze into your upcoming luck!", "details": "https://divine.example.com/manual/astrology-api", "parameters": { "birthday": { "type": "DATE", "description": "Your birth date in UTC" }, "targetDateBegin": { "type": "DATE", "description": "Start of the target date range to report on" }, "targetDateEnd": { "type": "DATE", "description": "End of the target date range to report on" }, "interval": { "values": { "D": "Daily", "M": "Monthly", "Y": "Yearly" }, "description": "Available intervals to report on." } } }
HTTP/1.1 200 Success Content-Type: application/json Content-Language: en { "description": "Matches and mis-matches according to the " "Yin Yang and Five Elements techniques", "details": "https://divine.example.com/manual/bazi-api", Tse, et al. Expires September 24, 2018 [Page 154] Internet-Draft AsciiRFC Specifications March 2018 "parameters": { "birthday": { "type": "DATETIME", "description": "Your birth date and time in UTC" }, "targetDateBegin": { "type": "DATETIME", "description": "Start of the target date/time range to report on" }, "targetDateEnd": { "type": "DATETIME", "description": "End of the target date/time range to report on" }, "interval": { "values": { "H": "Hourly", "D": "Daily", "M": "Monthly", "Y": "Yearly" }, "description": "Available intervals to report on." } } }
Service Specification ObjectA service specification object MUST contain the following members.
description
(string) A short, human-readable summary of the fortune heuristic service at this endpoint. This SHOULD be a stable reference.
details
(URI, optional) A URI reference that provides further details for human consumption, such as API documentation that includes details of parameters accepted or response states.
parameters
(object, mandatory) An object that specifies what parameters Tse, et al. Expires September 24, 2018 [Page 155] Internet-Draft AsciiRFC Specifications March 2018 are accepted by this endpoint. Each parameter key within this object specifies an accepted parameter name, and its value is a parameter specification object, which is described below.
A parameter specification object SHOULD contain the following members:
type
(string, optional) The value type accepted by this parameter. Value types are described in this document. This member is mutually exclusive with values.
description
(string, mandatory) The purpose of this parameter.
values
(object, optional) The accepted values of this parameter, unlisted values SHOULD not be accepted by the parameter. Each key within this object specifies an accepted value, and its value provides a description of the purpose of the value.
Fortune Heuristics Report Request and Response
Fortune Heuristics Report RequestA request using the HTTP "DIVINE" method and the "application/json" type MUST be sent to the fortune heuristic endpoint to retrieve results for a fortune heuristic query. The request made MUST conform to the specifications of the endpoint, as retrieved via the "SEEK" method described in . An example of a request is provided below.
URI: /divination/astrology Method: DIVINE Content-Type: application/json Tse, et al. Expires September 24, 2018 [Page 156] Internet-Draft AsciiRFC Specifications March 2018 Content-Language: en { "birthday": "1976-02-11T00:00:00Z", "targetDateBegin": "2018-01-01T00:00:00Z", "targetDateEnd": "2019-01-01T00:00:00Z", "interval": "M" }
Fortune Heuristics Report ResponseA fortune heuristic query using the "DIVINE" method triggers a response that contains a fortune heuristics report. A successful response returns a JSON object that MUST conform to the object structure described in this section. A report object SHOULD contain the following members:
type
(URI, mandatory) A URI that defines the type of the report located at the report key of this object.
report
(object, mandatory) An object that contains two keys, intervals and events. The intervals object contains an array of interval objects that matches the demanded intervals in the request within the target date range. The events object contains an array of significant event objects within the target date range.
An example of a response is provided below.
URI: /divination/astrology Method: DIVINE HTTP/1.1 200 Success Content-Type: application/json Content-Language: en { Tse, et al. Expires September 24, 2018 [Page 157] Internet-Draft AsciiRFC Specifications March 2018 "type": "https://association-of.astrology/reports/monthly", "report": { "intervals": [ { "dateStart": "2018-01-01T00:00:00Z", "dateEnd": "2018-02-01T00:00:00Z", "categories": [ { "category": "https://divine.example.com/astrology/categories/health" "value": 80, "description": "Charge ahead with excellent health." }, { "category": "https://divine.example.com/astrology/categories/love" "value": 70, "description": "Give a certain person or situation another try!" }, { "category": "https://divine.example.com/astrology/categories/finance" "value": 5, "description": "You've just realized that you don't have any cash on hand." } ] }, { "dateStart": "2018-02-01T00:00:00Z", "dateEnd": "2018-03-01T00:00:00Z", "..." }, "..." ], "events": [ { "dateStart": "2018-01-15T03:20:00", "dateEnd": "2018-01-16T20:22:15", "description": "The planet of growth and good luck, Jupiter will make a harmonious connection with power planet Pluto, helping you connect with influential people", "recommendation": "Engage in networking during this time." }, { "dateStart": "2018-03-22T00:12:40", "dateEnd": "2018-03-28T02:45:03", Tse, et al. Expires September 24, 2018 [Page 158] Internet-Draft AsciiRFC Specifications March 2018 "description": "Communication planet Mercury enters your sign, which will find you in a busier and chattier mood.", "recommendation": "Take charge of work with your newfound energy." } "..." ] } }
Fortune heuristic reports are created by a divination output that MAY requires quantitative interpretation. A sample representation of interpreting a graphical divination output is provided in .
Forty-nine yarrow sticks reveals a mystical message on fortune 0000000000000000000000000 0000000000000000000000001 G 1000000000000000000000000 0000000000000000000000011 R 1100000000000000000000000 0000000000000000000000111 A 1110000000000000000000000 0000000000000000000001111 C 1111000000000000000000000 0000000000000000000011111 E 1111100000000000000000000 0000000000000000000111111 , 1111110000000000000000000 0000000000000000001111111 1111111000000000000000000 0000000011111111111111111 M 1111111111111111100000000 0000000111111111111111111 E 1111111111111111110000000 0000001111111111111111111 R 1111111111111111111000000 0000011111111111111111111 C 1111111111111111111100000 0000111111111111111111111 Y 1111111111111111111110000 0001111111111111111111111 , 1111111111111111111111000 0011111111111111111111111 1111111111111111111111100 0111111111111111111111111 A 1111111111111111111111110 0000000000000000011111111 N 1111111100000000000000000 0000000000000000111111111 D 1111111110000000000000000 0000000000000001111111111 1111111111000000000000000 0000000000000011111111111 P 1111111111100000000000000 0000000000000111111111111 E 1111111111110000000000000 0000000000001111111111111 A 1111111111111000000000000 0000000000011111111111111 C 1111111111111100000000000 0000000000111111111111111 E 1111111111111110000000000 0000000001111111111111111 . 1111111111111111000000000
Report Interval ObjectThe intervals value of a report object contains a number of report intervals — each representing a non-overlapping period of the selected interval length. When all of these intervals are put together, the combined period MUST fully cover the requested report target period. An example interval object is shown below.
{ "dateStart": "2018-01-01T00:00:00Z", "dateEnd": "2018-02-01T00:00:00Z", "categories": [ { "category": "https://divine.example.com/astrology/categories/health" "value": 80, "description": "Charge ahead with your excellent health." }, { "category": "https://divine.example.com/astrology/categories/love" "value": 70, "description": "Give a certain person or situation another try!" }, { "category": "https://divine.example.com/astrology/categories/finance" "value": 5, "description": "You've just realized that you don't have any cash on hand." } ] }
An interval object MUST contain the following members:
dateStart
(datetime, mandatory) This value specifies the start of the period which this interval object applies to.
dateEnd Tse, et al. Expires September 24, 2018 [Page 160] Internet-Draft AsciiRFC Specifications March 2018
(datetime, mandatory) This value specifies the end of the period which this interval object applies to.
In the given example, the categories key is an implementation specific object that details heuristic results returned by the selected algorithm. This MAY differ in different algorithms.
Report Events ObjectThe events value of a report object contains a number of event objects. Each event object represents an event relevant to the calculation of fortune heuristics during a target report period. These events MAY be of variable time lengths, and MAY be overlapping amongst each other. The following example demonstrates two event objects the service determines relevant to a user’s query.
{ "dateStart": "2018-01-15T03:20:00", "dateEnd": "2018-01-16T20:22:15", "description": "The planet of growth and good luck, Jupiter will make a harmonious connection with power planet Pluto, helping you connect with influential people", "recommendation": "Engage in networking during this time." }, { "dateStart": "2018-03-22T00:12:40", "dateEnd": "2018-03-28T02:45:03", "description": "Communication planet Mercury enters your sign, which will find you in a busier and chattier mood.", "recommendation": "Take charge of work with your newfound energy." }
Similar to an interval object, an event object MUST contain the following members:
dateStart
(datetime, mandatory) This value specifies the start of the period Tse, et al. Expires September 24, 2018 [Page 161] Internet-Draft AsciiRFC Specifications March 2018 described by the event.
dateEnd
(datetime, mandatory) This value specifies the end of the period described by the event.
In the given example, the keys description and recommendation are implementation-specific details. This MAY differ in different algorithms.
Report Generation ErrorsThis specification makes use of normal HTTP error codes with the following extensions. Errors MUST be returned using the Problem JSON Structure as accordance with .
422 Unprocessable Entity
For example, a malformed date-time parameter, or an illogical input, such as when the subject’s birthday occurs after the report target date period.
473 Beyond Existing Capability
The service determines that the outcome is too difficult to predict. For example, in the case where the calculation is too complex to complete in a certain time period. The service SHOULD issue this response code to indicate that the client should not try the same request again.
474 Outcome Impossible
The service determines that the outcome is impossible. For example, when the algorithm determines that the subject will have deceased before the start of the requested target period.
Security Considerations
  • TLS and authenticated HTTP requests should be used to protect the DIVINE request and responses due to the personal nature Tse, et al. Expires September 24, 2018 [Page 162] Internet-Draft AsciiRFC Specifications March 2018 of information transmitted.
  • A client SHOULD verify the identity of the server on every request to prevent impersonation or man-in-the-middle attacks, as data transmitted to and from the server is sensitive information, and at times critical information to the user.
  • Synchronization of client and server time MUST be well-considered in the implementation of this specification. A mismatch of client and server time MAY lead to algorithm miscalculations that can cause mistaken choices of a user that depends on the reliability of this system.
IANA Considerations
Well-Known URI RegistrationsThis document defines a well-known URI using the registration procedure and template from .
"fortune" Well-Known URI Registration
URI suffix
fortune
Change controller
IETF
Specification document(s)
This document
Related information
N/A.
Normative References Tse, et al. Expires September 24, 2018 [Page 163] Internet-Draft AsciiRFC Specifications March 2018 Informative References ISO/DIS 8601-1:2018, Data elements and interchange formats -- Information interchange -- Representation of dates and times -- Part 1: Basic rules ISO/IEC
http://www.iso.org
AcknowledgementsThe authors thank the following individuals for their valuable feedback on this specification, and commend them for making fortune heuristics more accessible for the benefit of mankind. Tse, et al. Expires September 24, 2018 [Page 164] Internet-Draft AsciiRFC Specifications March 2018
Appendix B. Acknowledgements The authors would like to thank the following persons for their valuable advice and input. o Adrian Farrel for his comprehensive review of the document and numerous beneficial suggestions. Authors' Addresses Ronald Henry Tse Ribose Suite 1111, 1 Pedder Street Central, Hong Kong Hong Kong Email: ronald.tse@ribose.com URI: https://www.ribose.com Nick Nicholas Ribose Australia Email: nick.nicholas@ribose.com URI: https://www.ribose.com Jeffrey Lau Ribose Suite 1111, 1 Pedder Street Central, Hong Kong Hong Kong Email: jeffrey.lau@ribose.com URI: https://www.ribose.com Tse, et al. Expires September 24, 2018 [Page 165] Internet-Draft AsciiRFC Specifications March 2018 Paolo Brasolin Ribose Italy Email: paolo.brasolin@ribose.com URI: https://www.ribose.com Tse, et al. Expires September 24, 2018 [Page 166]