]>
AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDocRiboseSuite 1111, 1 Pedder StreetCentralHong KongHong Kongronald.tse@ribose.comhttps://www.ribose.comRiboseAustralianick.nicholas@ribose.comhttps://www.ribose.comRiboseSuite 1111, 1 Pedder StreetCentralHong KongHong Kongjeffrey.lau@ribose.comhttps://www.ribose.comRiboseItalypaolo.brasolin@ribose.comhttps://www.ribose.com
Internet
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.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
.Internet-Drafts and RFCs intended for publication submission to the
IETF can be written in a multitude of formats today, including:XML: RFC XML v2 and v3 nroff: through Microsoft Word: through usage of Lyx: through Pandoc: , through or Kramdown: through mmark: through Interestingly, the last three are Markdown variants.As specified in , the IETF intends for the canonical format
of RFCs to transition from plain-text ASCII to RFC XML v3 .
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 by the tools
specified above, the transition to RFC XML v3 places added
onus on authors to generate compliant XML. 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. is an open source,
MIT-licensed Ruby implementation of that provides an
enhancement of the original AsciiDoc markup language.The variant of AsciiDoc syntax accepted by 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.Section 1.2 of 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 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.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".AsciiRFC covers the full range of elements in RFC XML v2 and RFC XML v3.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.)AsciiRFC allows granular control of rendering, including
user-specified attributes of text blocks.The Asciidoctor implementation allows document inclusion, for
managing large-scale documentation projects.AsciiRFC allows granular control of permutations of block nesting,
such as source code within lists or definition lists within unordered
lists.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.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 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 .The following terms and definitions apply to this document:The AsciiDoc markup language generically, as described in .The enhanced AsciiDoc syntax implemented by the
Ruby gem.The AsciiDoc syntax developed for the purpose of generating RFC XML
document based on Asciidoctor syntax, as described in this document.AsciiRFC consists of a subset of Asciidoctor syntax
with the addition of bibliographic macros
().
Asciidoctor syntax is presented in the Asciidoctor user manual
.AsciiRFC syntax consists of:A document header, containing a title, a list of authors, and
document attributes in lines prefixed with :.An optional document preamble, separated from the document header by a
blank line, and not containing any section titles.A number of sections, set off by a section title (a line prefixed
with two or more =.)A section may contain:Other sections, whose level of nesting is indicated by the number of
= in their header.Blocks of text. Blocks can have metadata (including a title, an
anchor for cross-references, and attributes.)Blocks can be:Paragraphs, which are terminated by blank lines.Lists. List items are by default paragraphs, but can span over
multiple paragraphs.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.List items can contain other blocks, including both nested lists and
delimited blocks.Some delimited blocks can contain other delimited blocks; for
example, examples can contain source code as well as discussion in
paragraphs.Blocks of text consist of inline text, which itself can contain
markup.Inline markup includes:Text formatting: Bold, italic, superscript, subscript, monospace.Markup macros: the bcp14 and comment macros. (Asciidoctor syntax supports custom markup macros.)URLs, including display text to render.Inline anchors.Cross-references to anchors (IDs of blocks or spans of text),
including display text to render.Images: SVG only, as specified in .Index terms.Several features from Asciidoctor are not supported within AsciiRFC
due to the lack of support within RFC XML, including:Audio and video files are not supported in AsciiRFC as today’s
RFC XML structure does not support audio or video.Equations are not supported as there is no current RFC XML
equivalent. Asciidoctor provides native support for
and , via the tool.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.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.<rfc> attributes, most front elements.front/abstract and front/note.middle/section elements.back/references elements.back/section elements.t elements.ul, ol, dl elements.artwork, aside, blockquote, figure, note, sourcecode, table.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 .This document utilizes example documents provided in for
demonstration of AsciiRFC syntax and usage. The source files and published
versions (at the IETF Datatracker) of these example documents are
available in ."A Minimal Internet-Draft In AsciiRFC" "The Holy Hand Grenade of Antioch" "An API For Calendar-Based Fortune Heuristics Services" 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 ,
together with its corresponding rendering in:RFC XML v3 ()RFC XML v2 ()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
(<<RFC7253>>) -- 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.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: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 .
Output in RFC XML v2 is not extensively described in this document.
]>
A Minimal Internet-Draft In
AsciiRFCBrown UniversityBox K, 69 Brown StreetProvidence02912United States of America+1 401 863 1000josiah.carberry@ribose.comhttps://www.brown.eduBrown UniversityBox G, 69 Brown StreetProvidence02912United States of America+1 401 863 1000truman.grayson@ribose.comhttps://www.brown.edu
Internet
This document provides a template on how to author (or
migrate!)
a new Internet-Draft / RFC in the 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 conforming to .This is a template specifically made for authors to easily
start with creating an Internet-Draft conforming to
and submittable to the IETF datatracker.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.This document also refers to the following terms and
definitions:an AsciiDoc-derived
syntax used for authoring RFCs and
Internet-Drafts, as defined in .abbreviated form of
AsciiRFCThis is where you place
the main content, and the following
serves as a placeholder for your text.Subsections are used here for demonstration purposes.The
AsciiRFC and RFC toolchains MUST be
available locally to
build this document template.You will need to have:Ruby: for running the AsciiRFC toolchainasciidoctor-rfc gem: for converting
AsciiRFC into XML RFC
(v2 or v3)You
will need to have:Python: for running xml2rfcxml2rfc: for converting RFC XML (v2
or v3) into TXTidnits: for submission preflightThis is a published RFC This is an Internet-Draft This is an external reference Code snippets should be wrapped with <CODE
BEGINS> and
<CODE ENDS> blocks, as required by
the IETF Trust Legal
Provisions (TLP) specified in .Any
security considerations should be placed here.As described in (here’s how you refer a
local anchor),
local tools have to be installed before the document template
can be built.Running of these local tools MAY
produce unintended side
effects that impact security.This document
does not require any action by IANA.But if it does, such as proposing changes to IANA registries,
please include them here.
&RFC2119;
&RFC7991;
&RFC8174;
IETF Trust Legal Provisions (TLP)IETFRNP: A C library approach to OpenPGPRibose Inc.Suite 1111, 1 Pedder StreetCentralHong KongHong Kongopen.source@ribose.comhttps://www.ribose.com
&I-D.ribose-asciirfc;
&RFC5378;
&RFC7253;
Here’s an
example of a properly wrapped code snippet in
accordance with rules specified in .
{
"code": {
"encoding": "ascii",
"type": "rfc",
"authors": [ "Josiah Carberry", "Truman Grayson" ]
}
}
]]]]>The authors would like to thank their families.
]]>The header gives the document title, followed by an optional author
attribution, and a series of document attributes, with no empty lines.Document attributes are used to populate attributes of the root rfc
element, front elements, and document-level processing instructions.:doctype: determines whether the document will be considered
rfc or internet-draft, and interprets other attributes
accordingly.Certain attributes (workgroup, area, keyword) are comma
delimited, and result in repeated RFC XML elements. demonstrates how to set the document header
in AsciiRFC, with its rendering in RFC XML v3 shown in
.
= 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
]]>The Holy Hand Grenade of
AntiochCamelotPalaceCamel Lot 1Camelotantioch
]]>The document header can spell out further information about authors,
including contact details. The AsciiRFC header is shown in
with its rendering in RFC XML v3
shown in .
= 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
]]>The Holy Hand Grenade of
AntiochCamelotPalaceCamel Lot 1CamelotEnglandarthur.pendragon@ribose.comhttp://camelot.gov.example
General
Operations and Management
rabbitsgrenadesantiochcamelot
]]>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 and
its RFC XML v3 rendering .
= 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
]]>An API For
Calendar-Based Fortune Heuristics ServicesDivination Inc.9288 N Divine StreetDunnNC28334United States of Americagabriel.destiny@ribose.comDivination Inc.9288 N Divine StreetDunnNC28334United States of Americacharise.luck@ribose.com
Internet
]]>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.A document header may also contain attribute headers which are treated
as XML processing instructions. An AsciiRFC example is shown in
with its rendering in
. (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
]]>The Holy Hand Grenade of
AntiochCamelotPalaceCamel Lot 1Camelotantioch
]]>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.A few document attributes are specific to the operation of the RFC XML
document converter:overrides the wrapping by default of boldface uppercase BCP14
words (e.g. *MUST NOT*) with the bcp14 element.overrides Asciidoctor’s conversion of straight quotes and
apostrophes to smart quotes and apostrophes.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_.
]]>The Holy Hand Grenade of AntiochSection 1The specification MUST NOT
use the word doesn’t.
]]>
= 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_.
]]>The Holy Hand Grenade of AntiochSection 1The specification MUST NOT
use the word doesn't.
]]>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
with its rendering in
.
[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.
]]>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.SpamalotThe 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.
]]>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. shows how sections and paragraphs are
used in AsciiRFC, and its rendered form is shown in
.
[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:
]]>TerminologyThe 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:
]]>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: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
, and its rendering in
.
[[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;
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);
----
====
]]>A Photo Of The Killer Rabbit of Caerbannog Taken In
Secret>>\\\\\\\\\\\\
\\\\\\\\\\\\\\\<<<#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// " ' '
. , \\||// \||\\\// \\
]]]]>C Code To Lure Killer Rabbit Back To Cave
/* 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);
]]]]>
]]>If an AsciiRFC Listing or Literal occurs outside of an Example
(), the RFC XML converter will supply the
surrounding Figure element ().
[[hand-grenade-figure]]
.The Holy Hand Grenade of Antioch (don't pull the pin)
]]><CODE ENDS>The Holy Hand Grenade of Antioch (don't pull the pin)
]]>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
(::).List attributes can be used to specify the type of symbol used for
ordered lists.An example of an unordered list is shown in
(with its rendered
version in
). An example of an
ordered list
with ordered and unordered sublists is
shown in (with its
rendered version
in ). An example of a
definition
list is shown in (with
its
rendered version in ).
* Killed
** Sir Bors
** Sir Gawain
** Sir Ector
* Soiled Himself
** Sir Robin
* Panicked
** King Arthur
* Employed Ordnance
** The Lector
** Brother Maynard
* Scoffed
** Tim the Enchanter
]]>
Killed
Sir Bors
Sir Gawain
Sir Ector
Soiled Himself
Sir Robin
Panicked
King Arthur
Employed Ordnance
The Lector
Brother Maynard
Scoffed
Tim the Enchanter
]]>
. 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
]]>
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
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,
SHALL snuff it
]]>
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 <>.
]]>
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 .
]]>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 for more
information.An example of list continuation with text is shown in
with its rendered version in
.
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 <>.
]]>
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 .
]]>(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
with its rendered version
in
.
. 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
]]>
Take out the Holy Pin
The Count
Lob the Holy Hand Grenade of Antioch towards the Foe
Foe snuffs it
]]>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
cannot be generated via AsciiRFC.
This is the start of a paragraph.
List Entry 1
List Entry 2Note 2.
And this is the continuation of the paragraph.
]]>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
with its rendered version
in
.
[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.
____
]]>
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.
]]>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 ,
with its rendered output in .
[NOTE,display=true,source=Author]
====
Image courtesy of
https://camelot.gov.example/creatures-in-ascii/
====
]]>Image courtesy of
]]>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 , with its
rendered output in .
****
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.
****
]]>
]]>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 with its
rendered output in .
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.
--
]]>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.
]]>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 ,
with its rendered output in .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.
[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
|===
]]>
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
]]>
AsciiRFC supports
italics, boldface, monospace, subscripts and
superscripts, just like RFC XML v3.The inline formatting syntax given in
produces the RFC XML v3 output given in .
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 <>
]]>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
]]>RFC XML v3 also supports tagging of BCP14 keywords ; 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
with the
rendered output in .
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:
]]>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:
]]>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 .
:dblast: **
`{dblast}`
]]>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
.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 with
its rendered
version in .
<> 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:
]]>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:
]]>To prevent hyperlinking of a URL, prefix it with a backslash, as
shown
in with its rendered version
in
.
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.)
]]>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.)
]]>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 <<reference,text>>.An example of using cross-references in AsciiRFC is given in
with its rendered output in
.
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
]]>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
]]>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:format= x: text populates the xref@format attributea 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
with its output in
.
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.
]]>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.
]]>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.
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)))
]]>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.
]]>AsciiRFC inherits
the Asciidoctor syntax "include" directive
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, 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 .
include::path[
leveloffset=_offset_,
lines=_ranges_,
tag(s)=_name(s)_,
indent=_depth_
]
]]>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.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 with the output in
.
____
.כאן אולי
ימצאו
המילים
האחרונות של
יוסף
.מארמתיה
.מי אשר יהיה
אמיץ ובעל
נפש טהורה
יוכל למצוא
את הגביע
הקדוש בטירת
.אאאאאאאה
"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."
____
]]>
כאן אולי
ימצאו
המילים
האחרונות של
יוסף
.מארמתיה
מי אשר יהיה
אמיץ ובעל
נפש טהורה
יוכל למצוא
את הגביע
הקדוש בטירת
.אאאאאאאה"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."
]]>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.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 ; so it
would be inefficient to encode those entries natively in AsciiRFC, only
to have
them converted back to RFC XML.The converter provides two means of incorporating bibliographies into
RFC documents authored in AsciiRFC:using raw RFC XML; andassembling 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.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 will
generate the corresponding RFC XML v3 output in .
[bibliography]
== Normative References
++++
Key words for use in RFCs to Indicate
Requirement Levels
++++
[bibliography]
== Informative References
++++
Monty Python and the Holy GrailDON'T SPEW A Set of Guidelines for Mass Unsolicited
Mailings and Postings (spam*)RFC Format Framework
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
WordsRFC 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.
++++
]]>Normative ReferencesInformative ReferencesMonty Python and the Holy Grail
]]>
The alternative method is to
use a preprocessing tool,
, to import citations into the
AsciiRFC
document from an external file of references.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:Create an RFC XML references file, consisting of a <references>
element with individual <reference>
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.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.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.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.Add to the main document header attributes referencing the
references file (:bibliography-database:),
and the bibliography
style (:bibliography-style: rfc-v3).References to a normative reference are inserted with the macro
cite:norm[id] instead of <<id>>, where id is the anchor
of the reference.References to an informative reference are inserted with the
macro
cite:info[id] instead of <<id>>, where id is the anchor
of the reference.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:<<id,words>> = cite:norm[id, text="<xref target=
'id'>words</xref>"]<<id,format= counter:
words>> (processed as a formatted cross-reference) =
cite:norm[id, text="<xref format='counter'
target= 'id'>words</xref>"]<<id,2.4 comma: words>>
(processed as relref) =
cite:norm[id, text="<relref
displayFormat='comma' section='2.4' target= 'id'}/>"]<<id#section2_4,2.4 comma:
words>>
(processed as relref with a cross-document internal reference) =
cite:norm[id, text="<relref
relative='section2_4' displayFormat='comma' section='2.4' target=
'id'/>"]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 .
[bibliography]
== Normative References
++++
bibliography::norm[]
++++
[bibliography]
== Informative References
++++
bibliography::info[]
++++
]]>The following
features of RFC XML v3 and v2 are not
supported by the AsciiRFC converter, and would need to be adjusted
manually
after RFC XML is generated:RFC XML elementRFC XML v3RFC XML v2front/boilerplateNot added by the converterNot added by the converteriref@primaryNNreference (and all children)As Raw XMLAs Raw XMLtable/preambleDeprecatedNtable/postambleDeprecatedNartwork@widthOnly on imagesOnly on imagesartwork@heightOnly on imagesOnly on imagesTo author an
AsciiRFC document, you should first familiarise yourself
with the .The 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.)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 .Converting your AsciiRFC to
RFC XML is a simple as installing the
Asciidoctor Ruby gem asciidoctor (see
"Installation" at
) 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.The necessary steps are shown in .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
.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.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.An AsciiRFC generator may cause errors in textual rendering or
link
generation that may lead to security issues.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.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.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.This document does not require any action by IANA.
&RFC7991;
AsciiDoc: Text based document generationAsciiMath is an easy-to-write markup language for
mathematics.IETF BibXML LibraryMathJax: A JavaScript display engine for mathematics
that works in all browsers.WYSIWYG Internet-Draft Nroff EditorLaTeX is document preparation software that runs on top of
Donald E. Knuth's TeX typesetting system.Citations and Bibliography the 'asciidoctor-way'Ribose Inc.Hong Kongopen.source@ribose.comhttps://www.ribose.comAsciidoctor: A fast text processor & publishing
toolchain for converting AsciiDoc to HTML5,
DocBook & more.asciidoctor-rfc lets you write Internet-Drafts and RFCs
in AsciiDoc, the “asciidoctor-way”.Ribose Inc.Hong Kongopen.source@ribose.comhttps://www.ribose.comAsciidoctor: A fast text processor & publishing
toolchain for converting AsciiDoc to HTML5,
DocBook & more.IETF Datatracker: A Minimal Internet-Draft In
AsciiRFCThis 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.IETF Datatracker: The Holy Hand Grenade of AntiochThe 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.IETF Datatracker: An API For Calendar-Based Fortune Heuristics
ServicesThis document describes a JSON HTTP API for online services
that provide calendar-based fortune heuristics.draftr: an HTML front-end to pandoc2rfcGit repository: A Minimal Internet-Draft In AsciiRFCThis 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.Git repository: The Holy Hand Grenade of AntiochThe 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.Git repository: An API For Calendar-Based Fortune Heuristics
ServicesThis document describes a JSON HTTP API for online services
that provide calendar-based fortune heuristics.kramdown-rfc2629: An RFC2629 (XML2RFC) backend for
Thomas Leitner's kramdown markdown parserLyX to I-D/RFC export by way of Lyx export to
XHTML and XSLT conversion to xml2rfc schemaUsing mmark to create I-Ds and RFCsThis document describes an markdown variant called
mmark [mmark] that can be used to create RFC documents. The
aim of mmark is to make writing document as natural as
possible, while providing a lot of power on how to structure
and layout the document.pandoc2rfc: Use pandoc to create XML
suitable for xml2rfc
&I-D.asciirfc-minimal;
&I-D.camelot-holy-grenade;
&I-D.divination-cfapi;
&RFC2119;
&RFC5385;
&RFC7328;
&RFC7749;
&RFC7763;
&RFC7764;
&RFC7990;
&RFC7996;
&RFC8174;
This example is available in the following
formats:AsciiRFC Internet-Draft Text, RFC XML, PDF and HTML on the IETF Datatracker
= A Minimal Internet-Draft In AsciiRFC
:doctype: internet-draft
:name: draft-asciirfc-minimal-02
:abbrev: AsciiRFC Example
:status: informational
:ipr: trust200902
:submissionType: individual
:area: Internet
:intended-series: full-standard
:revdate: 2018-04-12T00: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 the 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 conforming to <>.
This is a template specifically made for authors to easily
start with creating an Internet-Draft conforming to <>
and submittable to the IETF datatracker.
[#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.
This document also refers to the following terms and
definitions:
AsciiRFC::
an AsciiDoc-derived syntax used for authoring RFCs and
Internet-Drafts, as defined in <>.
[#symbols]
== Symbols And Abbreviations
ADRFC::
abbreviated form of AsciiRFC
[#main]
== Main content
This is where you place the main content, and the following
serves as a placeholder for your text.
Subsections are used here for demonstration purposes.
=== Getting started
The AsciiRFC and RFC toolchains *MUST* be available locally to
build this document template.
==== AsciiRFC toolchain
You will need to have:
* Ruby: for running the AsciiRFC toolchain
* `asciidoctor-rfc` gem: for converting AsciiRFC into XML RFC
(v2 or v3)
==== XML RFC toolchain
You will need to have:
* Python: for running `xml2rfc`
* `xml2rfc`: for converting RFC XML (v2 or v3) into TXT
* `idnits`: for submission preflight
=== Referencing external content
* This is a published RFC <>
* This is an Internet-Draft <>
* This is an external reference <>
[#code-snippets]
=== Code snippets
Code snippets should be wrapped with `` and
`` blocks, as required by the IETF Trust Legal
Provisions (TLP) <> specified in <>.
[#security]
== Security Considerations
Any security considerations should be placed here.
As described in <> (here's how you refer a local anchor),
local tools have to be installed before the document template
can be built.
Running of these local tools *MAY* produce unintended side
effects that impact security.
[#iana]
== IANA Considerations
This document does not require any action by IANA.
But if it does, such as proposing changes to IANA registries,
please include them here.
// References must be given before appendixes
[bibliography]
== Normative References
//bibliography::norm[]
++++
Key words for use in RFCs to Indicate Requirement
LevelsIn 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 VocabularyThis 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 WordsRFC 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[]
++++
IETF Trust Legal Provisions (TLP)IETFRNP: A C library approach to OpenPGPRibose Inc.Suite 1111, 1 Pedder StreetCentralHong Kong
Hong Kongopen.source@ribose.comhttps://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.Rights Contributors Provide to the IETF TrustThe IETF policies about rights in Contributions
to the IETF are designed to ensure that such Contributions
can be made available to the IETF and Internet communities
while permitting the authors to retain as many rights as
possible. This memo details the IETF policies on rights in
Contributions to the IETF. It also describes the
objectives that the policies are designed to meet. This
memo obsoletes RFCs 3978 and 4748 and, with BCP 79 and
RFC 5377, replaces Section 10 of RFC 2026. This document
specifies an Internet Best Current Practices for the
Internet Community, and requests discussion and
suggestions for improvements.The OCB Authenticated-Encryption AlgorithmThis 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 of a properly wrapped code snippet in
accordance with rules specified in <>.
[source,json]
----
{
"code": {
"encoding": "ascii",
"type": "rfc",
"authors": [ "Josiah Carberry", "Truman Grayson" ]
}
}
----
[#acknowledgements]
== Acknowledgements
The authors would like to thank their families.
]]>A Minimal Internet-Draft In
AsciiRFCBrown UniversityBox K, 69 Brown StreetProvidence02912United States of America+1 401 863 1000josiah.carberry@ribose.comhttps://www.brown.eduBrown UniversityBox G, 69 Brown StreetProvidence02912United States of America+1 401 863 1000truman.grayson@ribose.comhttps://www.brown.edu
Internet
This document provides a template on how to author (or
migrate!)
a new Internet-Draft / RFC in the 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 conforming to .This is a template specifically made for authors to easily
start with creating an Internet-Draft conforming to
and submittable to the IETF datatracker.Terms and
DefinitionsThe 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.This document also refers to the following terms and
definitions:
AsciiRFC
an AsciiDoc-derived syntax used for authoring RFCs and
Internet-Drafts, as defined in .
Symbols And Abbreviations
ADRFC
abbreviated form of AsciiRFC
Main
contentThis is where you place the main content, and the
following
serves as a placeholder for your text.Subsections are used here for demonstration purposes.Getting
startedThe AsciiRFC and RFC toolchains MUST be
available locally to
build this document template.AsciiRFC
toolchainYou will need to have:
Ruby: for running the AsciiRFC toolchain
asciidoctor-rfc gem: for converting AsciiRFC into XML RFC
(v2 or v3)
XML RFC
toolchainYou will need to have:
Python: for running xml2rfc
xml2rfc: for converting RFC XML (v2 or v3) into TXT
idnits: for submission preflight
Referencing external content
This is a published RFC
This is an Internet-Draft
This is an external reference
Code snippetsCode snippets should be wrapped with <CODE BEGINS>
and
<CODE ENDS> blocks, as required by the IETF Trust Legal
Provisions (TLP) specified in .Security
ConsiderationsAny security considerations should be placed
here.As described in (here’s how you refer a
local anchor),
local tools have to be installed before the document template
can be built.Running of these local tools MAY produce unintended
side
effects that impact security.IANA
ConsiderationsThis document does not require any action by
IANA.But if it does, such as proposing changes to IANA registries,
please include them here.Normative ReferencesInformative ReferencesIETF Trust Legal Provisions (TLP)IETFRNP: A C library approach to OpenPGPRibose Inc.Suite 1111, 1 Pedder StreetCentralHong KongHong Kongopen.source@ribose.comhttps://www.ribose.comExamplesExample
1Here’s an example of a properly wrapped code snippet in
accordance with rules specified in .
{
"code": {
"encoding": "ascii",
"type": "rfc",
"authors": [ "Josiah Carberry", "Truman Grayson" ]
}
}
]]]]>AcknowledgementsThe authors would like to thank their families.
]]>This example is available in the following
formats:AsciiRFC Internet-Draft Text, RFC XML, PDF and HTML on the IETF Datatracker
= 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
: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
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]
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[]
[[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]
....
___ ____
//_ \//\__\
|| || |
-__||_||__|
// \--_
// ____ --___
// // \ \-_
// \\ @/ 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[]
[.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[]
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]
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
====
[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
** 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 |##########\
||###########| |###########|
||############| 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[]
// 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
** 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[]
[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[]
____
.כאן אולי
ימצאו
המילים
האחרונות של
יוסף
.מארמתיה
.מי אשר יהיה
אמיץ ובעל
נפש טהורה
יוכל למצוא
את הגביע
הקדוש בטירת
.אאאאאאאה
"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
++++
[bibliography]
== Informative References
++++
Monty Python and the Holy GrailDON'T SPEW A Set of Guidelines for Mass Unsolicited
Mailings and Postings (spam*)RFC Format Framework
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
WordsRFC 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.
++++
// end::bibliography[]
[.comment]
end::bibliography1[]
]]>
The Holy Hand Grenade of
AntiochCamelotPalaceCamel Lot 1CamelotEnglandarthur.pendragon@ribose.comhttp://camelot.gov.example
General
Operations and Management
rabbitsgrenadesantiochcamelotThe 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.SpamalotThe 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.TerminologyThe 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:
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
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 castleThe 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-.-.-.-._>_>_>_.-.-.-.-.-.-.-. \\\ .,.,. /// .-.-.-.-.
.,.,.,.,..,.,..,.,.,..,.,.,,..,., \ \_______/ / .,.,.,.,
.,.,.,.,..,.,.,.,..,,..,,.,.,.,.,. <[ {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
]]]]>The Trojan Rabbit with an automatic sliding doorImage courtesy of
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
CaerbannogThe 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 CaerbannogThe 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.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>>\\\\\\\\\\\\
\\\\\\\\\\\\\\\<<<#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// " ' '
. , \\||// \||\\\// \\
]]]]>C Code To Lure Killer Rabbit Back To Cave
/* 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);
]]]]>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 AntiochThe Holy Hand Grenade of Antioch (don't pull the pin)The Sovereign's Orb made invisibleThe 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.
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:
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
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,
SHALL snuff it
This could also be represented in pseudocode as follows:
Take out the Holy Pin
The Count
Lob the Holy Hand Grenade of Antioch towards the Foe
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:
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
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 ConsiderationsIANA 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.Normative ReferencesInformative ReferencesMonty Python and the Holy Grail
]]>
This
example is available in the following formats:AsciiRFC Internet-Draft Text, RFC XML, PDF and HTML on the IETF Datatracker
= 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
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 <>.
=== 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 "--".
+
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.
// 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]
....
__
__===^-\
__=== -\
__===- -\
__===- -\
___===- -\
===- ---__ -\
\\\ |||^^\ \__ -\
\\\ ||| \__ -\
\\\ ||| ______\_ -\
\\\ ||| _/-******\\__ -\
\\\ || /-****_****-\ \_ -\
\\\ || |-***/ \***-\ \_ -\
\\\ || |-***\___/***-| \ -\
\\\ || \-*********-/ __--/ -\
\\\ || \-******/__-- -\
\\\ || __-- -\
\\\ || __-- -\
\\\ ||__-- -\
\\\ -\
\\\ -\
\\\ -\
\\\ -\
\\\ __ -\
\\\ //##\\ -\
\\\ \\##// -\
\\\ ^^ __--==^
\\\ __--===
\\\ __--===
\\\ __--===
\\\ __--==
\\=
....
====
[#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"
},
"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.
`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.
[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
{
"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",
"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
....
====
[#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`::
(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
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
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
LevelsIn 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
RoutingThe 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): CachingThe 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
messages.Problem Details for HTTP APIsThis 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
WordsRFC 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.The JavaScript Object Notation (JSON) Data Interchange
FormatJavaScript 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 rulesISO/IEChttp://www.iso.orgDate and Time on the Internet: TimestampsThe Transport Layer Security (TLS) Protocol
Version 1.2This 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]
== 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[]
]]>An API For
Calendar-Based Fortune Heuristics ServicesDivination Inc.9288 N Divine StreetDunnNC28334United States of Americagabriel.destiny@ribose.comDivination Inc.9288 N Divine StreetDunnNC28334United States of Americacharise.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
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 BehaviorServers 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 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.
Fortune Heuristics Service DiscoveryRoot 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: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
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
buttonService Specification RequestTo 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.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
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 ResponseFortune 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.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.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
fortuneReport 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.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
(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.Similar to an interval object, an event object MUST
contain the
following members:
dateStart
(datetime, mandatory) This value specifies the start of the period
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
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 ConsiderationsWell-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 ReferencesInformative ReferencesISO/DIS 8601-1:2018, Data elements and interchange
formats -- Information interchange -- Representation of dates
and times -- Part 1: Basic rulesISO/IEChttp://www.iso.orgAcknowledgementsThe 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.
]]>The
authors would like to thank the following persons for their
valuable advice and input.Adrian Farrel for his comprehensive review of the document and
numerous beneficial suggestions.