idnits 2.17.1
draft-ribose-asciirfc-04.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
== There are 2 instances of lines with non-RFC2606-compliant FQDNs in the
document.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (December 12, 2017) is 2299 days in the past. Is this
intentional?
Checking references for intended status: Informational
----------------------------------------------------------------------------
== Missing Reference: 'NOTE' is mentioned on line 1074, but not defined
== Missing Reference: 'Orb' is mentioned on line 2494, but not defined
-- Looks like a reference, but probably isn't: '124' on line 2494
-- Looks like a reference, but probably isn't: '135' on line 2494
-- Obsolete informational reference (is this intentional?): RFC 7749
(Obsoleted by RFC 7991)
Summary: 0 errors (**), 0 flaws (~~), 4 warnings (==), 4 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group R. Tse
3 Internet-Draft N. Nicholas
4 Intended status: Informational J. Lau
5 Expires: June 15, 2018 P. Brasolin
6 Ribose
7 December 12, 2017
9 AsciiRFC: Authoring Internet-Drafts And RFCs Using AsciiDoc
10 draft-ribose-asciirfc-04
12 Abstract
14 This document describes the AsciiDoc syntax extension called AsciiRFC
15 designed for authoring IETF Internet-Drafts and RFCs.
17 AsciiDoc is a human readable document markup language which affords
18 more granular control over markup than comparable schemes such as
19 Markdown.
21 The AsciiRFC syntax is designed to allow the author to entirely focus
22 on text, providing the full power of the resulting RFC XML through
23 the AsciiDoc language, while abstracting away the need to manually
24 edit XML, including references.
26 This document itself was written and generated into RFC XML v2
27 (RFC7749) and RFC XML v3 (RFC7991) directly through asciidoctor-rfc,
28 an AsciiRFC generator.
30 Status of This Memo
32 This Internet-Draft is submitted in full conformance with the
33 provisions of BCP 78 and BCP 79.
35 Internet-Drafts are working documents of the Internet Engineering
36 Task Force (IETF). Note that other groups may also distribute
37 working documents as Internet-Drafts. The list of current Internet-
38 Drafts is at https://datatracker.ietf.org/drafts/current/.
40 Internet-Drafts are draft documents valid for a maximum of six months
41 and may be updated, replaced, or obsoleted by other documents at any
42 time. It is inappropriate to use Internet-Drafts as reference
43 material or to cite them other than as "work in progress."
45 This Internet-Draft will expire on June 15, 2018.
47 Copyright Notice
49 Copyright (c) 2017 IETF Trust and the persons identified as the
50 document authors. All rights reserved.
52 This document is subject to BCP 78 and the IETF Trust's Legal
53 Provisions Relating to IETF Documents
54 (https://trustee.ietf.org/license-info) in effect on the date of
55 publication of this document. Please review these documents
56 carefully, as they describe your rights and restrictions with respect
57 to this document.
59 Table of Contents
61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
62 2. Conventions Used in This Document . . . . . . . . . . . . . . 5
63 2.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 5
64 3. Document Structure And AsciiDoctor Syntax . . . . . . . . . . 5
65 3.1. AsciiRFC Mapping To Asciidoctor . . . . . . . . . . . . . 7
66 3.2. Simple Illustration . . . . . . . . . . . . . . . . . . . 8
67 4. Header And Document Attributes . . . . . . . . . . . . . . . 16
68 4.1. Title And Basic Attributes . . . . . . . . . . . . . . . 16
69 4.2. Detailed Author Information . . . . . . . . . . . . . . . 17
70 4.3. XML Processing Information . . . . . . . . . . . . . . . 20
71 4.4. AsciiRFC-specific Document Attributes . . . . . . . . . . 21
72 5. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 23
73 6. Sections and Paragraphs . . . . . . . . . . . . . . . . . . . 25
74 7. Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
75 8. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
76 8.1. Basic Lists . . . . . . . . . . . . . . . . . . . . . . . 29
77 8.2. List Continuation . . . . . . . . . . . . . . . . . . . . 30
78 9. Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . . 32
79 10. Notes And Asides . . . . . . . . . . . . . . . . . . . . . . 33
80 11. Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
81 12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . . 37
82 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts . 37
83 12.2. Formatting BCP 14 Keywords . . . . . . . . . . . . . . . 37
84 12.3. Escaping AsciiRFC Syntax . . . . . . . . . . . . . . . . 38
85 13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
86 14. Cross-References . . . . . . . . . . . . . . . . . . . . . . 39
87 14.1. Basic Referencing . . . . . . . . . . . . . . . . . . . 39
88 14.2. Referencing With Attributes . . . . . . . . . . . . . . 40
89 15. Inclusions . . . . . . . . . . . . . . . . . . . . . . . . . 42
90 16. Encoding and Entities . . . . . . . . . . . . . . . . . . . . 43
91 17. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 44
92 17.1. Using Raw RFC XML . . . . . . . . . . . . . . . . . . . 44
93 17.2. Preprocessing Using asciidoctor-
94 bibliography . . . . . . . . . . . . . . . . . . 46
96 18. RFC XML features not supported in Asciidoctor . . . . . . . . 48
97 19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 48
98 19.1. Using the rfc-in-asciidoc-
99 template . . . . . . . . . . . . . . . . . . . . 49
100 19.2. Installing AsciiRFC Backend Processors . . . . . . . . . 49
101 19.3. Iterating AsciiRFC Content . . . . . . . . . . . . . . . 49
102 20. Security Considerations . . . . . . . . . . . . . . . . . . . 50
103 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 50
104 22. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 50
105 22.1. Example 1: AsciiRFC . . . . . . . . . . . . . . . . . . 50
106 22.2. Example 1: RFC XML v3 . . . . . . . . . . . . . . . . . 52
107 22.3. Example 2: AsciiRFC . . . . . . . . . . . . . . . . . . 53
108 22.4. Example 2: RFC XML v3 . . . . . . . . . . . . . . . . . 59
109 23. References . . . . . . . . . . . . . . . . . . . . . . . . . 65
110 23.1. Normative References . . . . . . . . . . . . . . . . . . 65
111 23.2. Informative References . . . . . . . . . . . . . . . . . 65
112 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 67
113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 67
115 1. Introduction
117 Internet-Drafts and RFCs intended for publication submission to the
118 IETF can be written in a multitude of formats today, including:
120 o XML: RFC XML v2 [RFC7749] and v3 [RFC7991]
122 o nroff: through "NroffEdit" [NroffEdit]
124 o Microsoft Word: through usage of [RFC5385]
126 o Lyx: through [lyx2rfc]
128 o Pandoc: [RFC7328], through [pandoc2rfc] or [draftr]
130 o Kramdown: through [kramdown-rfc2629]
132 o mmark: through [mmark]
134 Interestingly, the last three are Markdown [RFC7763] variants.
136 As specified in [RFC7990], the IETF intends for the canonical format
137 of RFCs to transition from plain-text ASCII to RFC XML v3 [RFC7991].
138 While plain-text will continue to be accepted from authors by the
139 IETF, at least in the short- to medium-term, XML will be preferred
140 for submission, and any plain-text submissions will need to be
141 converted to RFC XML v3.
143 While this need is already met for RFC XML v2 [RFC7749] by the tools
144 specified above, the transition to RFC XML v3 [RFC7991] places added
145 onus on authors to generate compliant XML.
147 [AsciiDoc] is an alternative markup language to Markdown, with
148 features that make it attractive as a markup language for RFC with
149 XML output. This document describes the use of [Asciidoctor], a
150 Ruby-based enhancement of the original AsciiDoc markup language, for
151 RFC XML markup, with a Ruby gem written by the authors used to render
152 Asciidoctor documents as RFC XML. The markup language used
153 specifically for the purpose of generating RFC XML document is called
154 "AsciiRFC".
156 Section 1.2 of [RFC7764] famously states that "there is no such thing
157 as "invalid" Markdown, there is no standard demanding adherence to
158 the Markdown syntax, and there is no governing body that guides or
159 impedes its development." While there are contexts where that lack
160 of rigour is helpful, the authoring of RFCs does have a standard and
161 a governing body, and there is such a thing as invalid RFC XML. A
162 more rigorous counterpart to Markdown, which still preserves its
163 basic approach to formatting, is useful in generating RFC XML that
164 encompasses a fuller subset of the specification, and preempting
165 malformed RFC XML output.
167 Compared to Markdown [Asciidoctor-Manual],
169 o AsciiDoc was designed from the beginning as a publishing language:
170 it was initially intended as a plain-text alternative to the
171 DocBook XML schema. For that reason, Asciidoctor natively
172 supports the full range of formatting required by RFC XML
173 (including notes, tables, bibliographies, source-code blocks, and
174 definition lists), without resorting to embedded HTML or Markdown
175 "flavours".
177 o AsciiDoc in its Ruby-based Asciidoctor implementation is
178 extensible, with a well-defined API. (Extensions have been
179 harnessed to deal with bibliographic preprocessing for AsciiRFC.)
181 o AsciiRFC allows granular control of rendering, including user-
182 specified attributes of text blocks.
184 o The Asciidoctor implementation allows document inclusion, for
185 managing large-scale documentation projects.
187 o AsciiRFC allows granular control of permutations of block nesting,
188 such as source code within lists or definition lists within
189 unordered lists.
191 o As a more formal counterpart to Markdown, AsciiDoc is well-suited
192 to generating XML that needs to conform to a specified schema.
194 As with Markdown, there is a wide range of tools that can render
195 AsciiDoc; so AsciiRFC drafts of RFC documents can be previewed and
196 accessed without depending on the RFC tools ecosystem. Our
197 realisation of RFC XML in AsciiRFC has aimed to ensure that, as much
198 as possible, the markup language can be can be processed by generic
199 Asciidoctor tools. (The only exception to this as an add-on is the
200 optional bibliography module, which allows bibliographies to be
201 assembled on the fly based on citations in a document: see
202 Section 17.2.)
204 2. Conventions Used in This Document
206 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*",
207 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*MAY*",
208 and "*OPTIONAL*" in this document are to be interpreted as described
209 in [RFC2119].
211 2.1. Definitions
213 In this document, _AsciiDoc_ refers to the markup language
214 generically. _Asciidoctor_ refers specifically to the Ruby-based
215 implementation of the markup language, which has enhanced the
216 original markup language. The RFC XML document converter contributed
217 by the authors uses a subset of _Asciidoctor_, with some minor
218 additions (a few document attributes specific to RFC XML, some macros
219 specific to citation processing, and some templated use of
220 _Asciidoctor_ crossreferences). This variant of _Asciidoctor_ markup
221 is referred to as _AsciiRFC_.
223 3. Document Structure And AsciiDoctor Syntax
225 The syntax of Asciidoctor is presented in the Asciidoctor user manual
226 [Asciidoctor-Manual]. AsciiRFC is a subset of Asciidoctor syntax,
227 with the addition of bibliographic macros (Section 17.2).
229 Asciidoctor consists of:
231 o A document header, containing a title, a list of authors, and
232 document attributes in lines prefixed with ":".
234 o An optional document preamble, separated from document header by a
235 blank line.
237 o A number of sections, set off by a section title (a line prefixed
238 with two or more "=".
240 A section may contain:
242 o Other sections, whose level of nesting is indicated by the number
243 of "=" in their header.
245 o Blocks of text. Blocks can have metadata (including a title, an
246 anchor for cross-references, and attributes.)
248 Blocks can be:
250 o Paragraphs, which are terminated by blank lines.
252 o Lists. List items are by default paragraphs, but can span over
253 multiple paragraphs.
255 o Delimited blocks (with a line delimiter on either side of them);
256 these include tables, notes, sidebars, source code, block quotes,
257 examples, and unprocessed content (e.g. raw XML). Delimited
258 blocks contain by default one or more paragraphs.
260 o List items can contain other blocks, including both nested lists
261 and delimited blocks.
263 o Some delimited blocks can contain other delimited blocks; for
264 example, examples can contain source code as well as discussion in
265 paragraphs.
267 o Blocks of text consist of inline text, which themselves can
268 contain markup.
270 Inline markup includes:
272 o Text formatting: bold, italic, superscript, subscript, monospace.
274 o Custom markup macros. (AsciiRFC uses one: "bcp14".)
276 o URLs, including display text.
278 o Inline anchors.
280 o Cross-references to anchors (IDs of blocks or spans of text),
281 including display text.
283 o Images, audio, and visual files. (AsciiRFC only supports images.)
285 o Index terms.
287 o Equations (native support for [AsciiMathML] and [TeX-LaTeX], via
288 the [MathJax] tool). (Not supported in AsciiRFC, since there is
289 no RFC XML equivalent.)
291 o Footnotes. (Not supported in AsciiRFC.)
293 3.1. AsciiRFC Mapping To Asciidoctor
295 The Asciidoctor document structure aligns with the RFC XML v2 and v3
296 structure. In the following, v3 equivalences are given.
298 Header
299 "" attributes, most "front" elements.
301 Preamble
302 "front/abstract" and "front/note".
304 Sections
305 "middle/section" elements.
307 Sections with bibliography style attributes
308 "back/references" elements.
310 Sections with appendix style attributes
311 "back/section" elements.
313 Paragraphs
314 "t" elements.
316 Lists
317 "ul", "ol", "dl" elements.
319 Delimited blocks
320 "artwork", "aside", "blockquote", "figure", "note", "sourcecode",
321 "table".
323 Inline markup
324 "bcp14", "br", "cref", "em", "eref", "iref", "relref", "strong",
325 "sub", "sup", "tt", "xref".
327 Full details of the mapping of AsciiRFC elements to RFC XML v2 and v3
328 elements, and of how to convert AsciiRFC documents to RFC XML, are
329 given in the documentation of [asciidoctor-rfc].
331 3.2. Simple Illustration
333 This section gives an overview of how to create an RFC XML document
334 in AsciiRFC, with some pitfalls to be aware of.
336 Illustrations are in RFC XML v3, although the converter deals with
337 both versions of RFC XML.
339 A sample AsciiRFC document is provided in Figure 1, and its
340 corresponding rendering in:
342 o RFC XML v3 (Figure 2)
344 o RFC XML v2 (Figure 3)
346 = Four Yorkshiremen Sketch
347 Tim Brooke-Taylor; John Cleese; Graham Chapman; Marty Feldman
348 :doctype: internet-draft
349 :abbrev: 4 Yorkshiremen
350 :obsoletes: 10, 120
351 :updates: 2010, 2120
352 :status: informational
353 :name: draft-four-yorkshiremen-00
354 :ipr: trust200902
355 :area: Internet
356 :workgroup: Network Working Group
357 :keyword: yorkshire, memory
358 :revdate: 1990-04-01T00:00:00Z
359 :organization: BBC
360 :phone: (555) 555-5555
361 :uri: http://example.com
362 :street: 10 Moulton Street
363 :city: Cambridge
364 :code: MA 02238
365 :email: tbt@example.com
366 :email_2: jc@example.com
367 :email_3: gc@example.com
368 :email_4: mf@bcc.co.uk
369 :smart-quotes: false
370 :link: https://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch
372 [abstract]
373 The sketch is a parody of nostalgic conversations about humble
374 beginnings or difficult childhoods, featuring four men from Yorkshire
375 who reminisce about their upbringing. As the conversation progresses
376 they try to outdo one another, and their accounts of deprived
377 childhoods become increasingly absurd. <> <>
378 NOTE: See also Wikipedia summary
380 [#michaelpalin]
381 == Claim: Michael Palin
382 You were lucky. We lived for three months in a brown paper bag in a
383 septic tank. We used to have to get up at six o'clock in the morning,
384 clean the bag, eat a crust of stale bread, go to work down mill for
385 fourteen hours a day week in-week out. When we got home, our Dad would
386 thrash us to sleep with his belt! <>
388 === Response: Graham Chapman
389 Luxury. We used to have to get out of the lake at three o'clock in
390 the morning, clean the lake, eat a handful of hot gravel, go to work
391 at the mill every day for tuppence a month, come home, and Dad would
392 beat us around the head and neck with a broken bottle, if we were
393 *lucky*!
395 === Response: Terry Gilliam
396 Well we had it tough. We used to have to get up out of the shoebox at
397 twelve o'clock at night, and *lick* the road clean with our tongues. We
398 had half a handful of freezing cold gravel, worked twenty-four hours
399 a day at the mill for fourpence every six years, and when we got home,
400 our Dad would slice us in two with a bread knife.
402 [#ericidle]
403 === Response: Eric Idle
404 Right.
406 I had to get up in the morning at ten o'clock at night, half
407 an hour before I went to bed, (_pause for laughter_), eat a lump
408 of cold poison, work twenty-nine hours a day down mill, and pay mill
409 owner for permission to come to work, and when we got home,
410 our Dad would kill us, and dance about on our graves
411 singing "Hallelujah."
413 [bibliography]
414 == Normative References
415 ++++
416
418
419 Guidelines for Writing an IANA Considerations
420 Section in RFCs
421
422 Sacramento State
423
424
425 UC Davis
427
428
429
430
431
432 ++++
434 [appendix]
435 == Addendum
436 But you try and tell the young people today that...
437 and they won't believe ya.
439 Figure 1: Sample Internet-Draft in AsciiRFC
441 The first block of text, from "= Four Yorkshiremen Sketch" through to
442 ":link: https://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch", is
443 the document header. It contains a title in the first line, an
444 author attribution, and then a set of document attributes, conveying
445 information about the document as well as information about its
446 authors. This information ends up either as attributes of the root
447 "rfc" tag, elements of the "front" tag, or processing instructions.
449 The following blocks of text, up until the first section header ("==
450 Claim: Michael Palin"), are the document preamble. They are treated
451 by the document converter as containing the document abstract
452 ("abstract"), followed by any notes ("note", identified above by the
453 "NOTE:" heading).
455 The first section header ("== Claim: Michael Palin") is preceded by
456 an anchor for that section ("[#michaelpalin]"). There is a cross-
457 reference to that anchor already in place in the abstract
458 ("<>"). The document converter treats the first
459 section of the document as the start of the "middle" section of the
460 document.
462 The first section header is followed by a paragraph, and other
463 sections and paragraphs. The number of "=" signs are one higher than
464 the initial section header, which indicates that they are subsections
465 of that section. The paragraphs contains some inline formatting
466 (italics: "_pause for laughter_"; boldface: "*lick*"). The first
467 paragraph also contains a citation of a reference, which in this
468 version of AsciiRFC is treated identically to a cross-reference
469 ("<>"). (If the bibliography preprocessor were used, it
470 would be encoded differently.)
472 The second last section is tagged with the style attribute
473 "[bibliography]", which identifies it as a references container; the
474 document converter accordingly inserts this into the "back" element
475 of the document. The contents of the references section are in this
476 instance raw XML, delimited as a passthrough block (with "++++"),
477 which the converter does not alter. The final section is tagged with
478 the style attribute "[appendix]", and is treated as such.
480 The RFC XML v3 document generated from this AsciiRFC document is:
482
483
484
486
487
488 Four Yorkshiremen Sketch
489
491
492 BBC
493
494
495 10 Moulton Street
496 Cambridge
497 MA 02238
498
499 (555) 555-5555
500 tbt@example.com
501 http://example.com
502
503
504
505
506 jc@example.com
507
508
509
510
511 gc@example.com
512
513
514
515
516 mf@bcc.co.uk
517
518
519
520 Internet
521 Network Working Group
522 yorkshire
523 memory
524
525 The sketch is a parody of nostalgic conversations about humble
526 beginnings or difficult childhoods, featuring four men from
527 Yorkshire who reminisce about their upbringing. As the
528 conversation progresses they try to outdo one another, and their
529 accounts of deprived childhoods become increasingly absurd.
530
531
532
533
534 See also Wikipedia summary
535
536
537
538
539 Claim: Michael Palin
540 You were lucky. We lived for three months in a brown paper bag
541 in a septic tank. We used to have to get up at six o'clock in
542 the morning, clean the bag, eat a crust of stale bread, go to
543 work down mill for fourteen hours a day week in-week out. When
544 we got home, our Dad would thrash us to sleep with his belt!
545
546
547 Response: Graham Chapman
548 Luxury. We used to have to get out of the lake at three
549 o'clock in the morning, clean the lake, eat a handful of hot
550 gravel, go to work at the mill every day for tuppence a month,
551 come home, and Dad would beat us around the head and neck with
552 a broken bottle, if we were lucky!
553
554
555 Response: Terry Gilliam
556 Well we had it tough. We used to have to get up out of the
557 shoebox at twelve o'clock at night, and lick
558 the road clean with our tongues. We had half a handful of
559 freezing cold gravel, worked twenty-four hours a day at the
560 mill for fourpence every six years, and when we got home,
561 our Dad would slice us in two with a bread knife.
562
563
564 Response: Eric Idle
565 Right.
566 I had to get up in the morning at ten o'clock at night, half
567 an hour before I went to bed, (pause for laughter),
568 eat a lump of cold poison, work twenty-nine hours a day down
569 mill, and pay mill owner for permission to come to work, and
570 when we got home, our Dad would kill us, and dance about on
571 our graves singing "Hallelujah."
572
573
574
575
576
577 Normative References
578
580
581 Guidelines for Writing an IANA Considerations
582 Section in RFCs
583
584 Sacramento State
585
586
587 UC Davis
588
589
590
591
592
593
594
595 Addendum
596 But you try and tell the young people today that…
597 and they won't believe ya'.
598
599
600
602 Figure 2: Sample Internet-Draft In AsciiRFC, Output In RFC XML v3
603 Format
605 Some default processing instructions have already been prefixed to
606 the XML.
608 Our AsciiRFC converter can also generate RFC XML v2 from the same
609 source AsciiRFC, as shown in Figure 3. Output in RFC XML v2 is not
610 extensively described in this document.
612
615
616 Four Yorkshiremen Sketch
617
618 BBC
619
620
621 10 Moulton Street
622 Cambridge
623 MA 02238
624
625 (555) 555-5555
626 tbt@example.com
627 http://example.com
628
629
630
631
632 jc@example.com
633
634
635
636
637 gc@example.com
638
639
640
641
642 mf@bcc.co.uk
643
644
645
646 Internet
647 Network Working Group
648 yorkshire
649 memory
650
651 The sketch is a parody of nostalgic conversations about humble
652 beginnings or difficult childhoods, featuring four men from
653 Yorkshire who reminisce about their upbringing. As the
654 conversation progresses they try to outdo one another, and their
655 accounts of deprived childhoods become increasingly absurd.
656
657
658
659
660 See also Wikipedia summary
661
662
663
664
665 You were lucky. We lived for three months in a brown paper bag
666 in a septic tank. We used to have to get up at six o'clock in
667 the morning, clean the bag, eat a crust of stale bread, go to
668 work down mill for fourteen hours a day week in-week out. When
669 we got home, our Dad would thrash us to sleep with his belt!
670
671
673 Luxury. We used to have to get out of the lake at three
674 o'clock in the morning, clean the lake, eat a handful of hot
675 gravel, go to work at the mill every day for tuppence a month,
676 come home, and Dad would beat us around the head and neck with
677 a broken bottle, if we were
678 lucky!
679
680
682 Well we had it tough. We used to have to get up out of the
683 shoebox at twelve o'clock at night, and
684 lick
685 the road clean with our tongues. We had half a handful of
686 freezing cold gravel, worked twenty-four hours a day at the
687 mill for fourpence every six years, and when we got home,
688 our Dad would slice us in two with a bread knife.
689
690
691 Right.
692 I had to get up in the morning at ten o'clock at night, half
693 an hour before I went to bed, (pause
694 for laughter),
695 eat a lump of cold poison, work twenty-nine hours a day down
696 mill, and pay mill owner for permission to come to work, and
697 when we got home, our Dad would kill us, and dance about on
698 our graves singing "Hallelujah."
699
700
701
702
703
704
706
707 Guidelines for Writing an IANA Considerations
708 Section in RFCs
709
710 Sacramento State
711
712
713 UC Davis
714
715
716
717
718
719
720
721 But you try and tell the young people today that…
722 and they won't believe ya'.
723
724
725
727 Figure 3: Sample Internet-Draft In AsciiRFC, Output In RFC XML v2
728 Format
730 4. Header And Document Attributes
732 The header gives the document title, followed by an optional author
733 attribution, and a series of document attributes, with no carriage
734 return breaks.
736 4.1. Title And Basic Attributes
738 Document attributes are used to populate attributes of the root "rfc"
739 element, "front" elements, and document-level processing
740 instructions.
742 o ":doctype:" determines whether the document will be considered
743 "rfc" or "internet-draft", and interprets other attributes
744 accordingly.
746 o Certain attributes ("workgroup", "area", "keyword") are comma
747 delimited, and result in repeated RFC XML elements.
749 Figure 4 demonstrates how to set the document header in AsciiRFC,
750 with its rendering in v3 shown in Figure 5.
752 = Four Yorkshiremen Sketch
753 Tim Brooke-Taylor
754 :doctype: internet-draft
755 :abbrev: 4 Yorkshiremen
756 :obsoletes: 10, 120
757 :updates: 2010, 2120
758 :status: informational
759 :name: draft-four-yorkshiremen-00
760 :ipr: trust200902
761 :area: Internet
762 :workgroup: Network Working Group
763 :keyword: yorkshire, memory
764 :revdate: 1990-04-01T00:00:00Z
766 Figure 4: AsciiRFC Document Header
768
770
771 Four Yorkshiremen Sketch
772
774
775
776 tbt@example.com
777
778
779
780 Internet
781 Network Working Group
782 yorkshire
783 memory
785 Figure 5: AsciiRFC Document Header Rendered As RFC XML v3
787 4.2. Detailed Author Information
789 The document header can spell out further information about authors,
790 including contact details. The AsciiRFC header is shown in Figure 6
791 with its rendering in RFC XML v3 shown in Figure 7.
793 = Four Yorkshiremen Sketch
794 Tim Brooke-Taylor
795 :doctype: internet-draft
796 :abbrev: 4 Yorkshiremen
797 :obsoletes: 10, 120
798 :updates: 2010, 2120
799 :status: informational
800 :name: draft-four-yorkshiremen-00
801 :ipr: trust200902
802 :area: Internet
803 :workgroup: Network Working Group
804 :keyword: yorkshire, memory
805 :revdate: 1990-04-01T00:00:00Z
806 :organization: BBC
807 :phone: (555) 555-5555
808 :uri: http://bbn.com
809 :street: 10 Moulton Street
810 :city: Cambridge
811 :code: MA 02238
813 Figure 6: AsciiRFC Document Header With One Author
815
817
818 Four Yorkshiremen Sketch
819
821
822 BBC
823
824
825 10 Moulton Street
826 Cambridge
827 MA 02238
828
829 (555) 555-5555
830 tbt@example.com
831 http://bbn.com
832
833
834
835 Internet
836 Network Working Group
837 yorkshire
838 memory
840 Figure 7: AsciiRFC Document Header With One Author (RFC XML v3)
842 Details of a second, third etc. author, including their organization
843 and contact details, are provided by suffixing the relevant author
844 attributes with "_2", "_3" etc., as shown in Figure 8 and its v3
845 rendering Figure 9.
847 = Four Yorkshiremen Sketch
848 Tim Brooke-Taylor ; John Cleese
849 :doctype: internet-draft
850 :status: informational
851 :name: draft-four-yorkshiremen-00
852 :ipr: trust200902
853 :organization: BBC
854 :phone: (555) 555-5555
855 :uri: http://example.com
856 :street: 10 Moulton Street
857 :city: Cambridge
858 :code: MA 02238
859 :forename_initials: T.
860 :lastname: Brooke-Taylor
861 :street: 12 Moulton Street
862 :city: London
863 :country: United Kingdom
864 :forename_initials_2: J.
865 :lastname_2: Cleese
866 :uri_2: https://twitter.com/johncleese
868 Figure 8: AsciiRFC Document Header With Multiple Authors
870
872
873 Four Yorkshiremen Sketch
874
876
878 BBC
879
880
881 12 Moulton Street
882 London
883 MA 02238
884 United Kingdom
885
886 (555) 555-5555
887 tbt@example.com
888 http://example.com
889
890
891
892
893 jc@example.com
894 https://twitter.com/johncleese
895
896
897
899 Figure 9: AsciiRFC Document Header With Multiple Authors (RFC XML v3)
901 The initial author attribution in AsciiRFC, e.g. "Tim Brooke-Taylor
902 ; John Cleese " in the example above,
903 expects a strict format of First Name, zero or more Middle Names,
904 Last name, and cannot process honorifics like "Dr." or suffixes like
905 "Jr.".
907 Name attributes with any degree of complexity should be overriden by
908 using the ":fullname:" and ":lastname:" attributes. The AsciiRFC
909 ":forename_initials:" attribute replaces the built-in Asciidoctor
910 ":initials:" attribute (which includes the surname initial), and is
911 not automatically populated from the name attribution.
913 4.3. XML Processing Information
915 A document header may also contain attribute headers which are
916 treated as XML processing instructions. An AsciiRFC example is shown
917 in Figure 10 with its rendering in Figure 11.
919 = Four Yorkshiremen Sketch
920 Tim Brooke-Taylor
921 :doctype: internet-draft
922 :status: informational
923 :name: draft-four-yorkshiremen-00
924 :ipr: trust200902
925 :revdate: 1990-04-01T00:00:00Z
926 :rfcedstyle: yes
927 :text-list-symbols: yes
928 :rfc2629xslt: true
930 Figure 10: AsciiRFC Document Header With XML Processing Information
932
934
935 Four Yorkshiremen Sketch
936
938
939
940 tbt@example.com
941
942
943
945 Figure 11: AsciiRFC Document Header With XML Processing Information
946 (RFC XML v3)
948 4.4. AsciiRFC-specific Document Attributes
950 A few document attributes are specific to the operation of the RFC
951 XML document converter:
953 :no-rfc-bold-bcp14: false
954 overrides the wrapping by default of boldface uppercase BCP14
955 [RFC2119] words (e.g. "*MUST NOT*") with the "bcp14" element.
957 :smart-quotes: false
958 overrides Asciidoctor's conversion of straight quotes and
959 apostrophes to smart quotes and apostrophes.
961 :inline-definition-lists: true
962 overrides the RFC XML v2 "idnits" requirement that a blank line be
963 inserted between a definition list term and its definition.
965 = Four Yorkshiremen Sketch
966 Tim Brooke-Taylor
967 :doctype: internet-draft
968 :status: informational
969 :name: draft-four-yorkshiremen-00
971 == Section 1
972 The specification *MUST NOT* use the word _doesn't_.
974 Figure 12: AsciiRFC Document Header Without RFC-specific Attributes
976
977
978 Four Yorkshiremen Sketch
979
981
982
983 tbt@example.com
984
985
986
987
988
989
990 Section 1
991 The specification MUST NOT
992 use the word doesn’t.
993
994
995
997 Figure 13: AsciiRFC Document Header Without RFC-specific Attributes
998 (RFC XML v3)
1000 = Four Yorkshiremen Sketch
1001 Tim Brooke-Taylor
1002 :doctype: internet-draft
1003 :status: informational
1004 :name: draft-four-yorkshiremen-00
1005 :no-rfc-bold-bcp14: false
1006 :smart-quotes: false
1008 == Section 1
1009 The specification *MUST NOT* use the word _doesn't_.
1011 Figure 14: AsciiRFC Document Header With Overridden RFC-specific
1012 Attributes
1014
1015
1016 Four Yorkshiremen Sketch
1017
1019
1020
1021 tbt@example.com
1022
1023
1024
1025
1026
1027
1028 Section 1
1029 The specification MUST NOT
1030 use the word doesn't.
1031
1032
1033
1035 Figure 15: AsciiRFC Document Header With Overridden RFC-specific
1036 Attributes (RFC XML v3)
1038 5. Preamble
1040 The preamble in AsciiRFC is the text between the end of the document
1041 header (which terminates with a blank line) and the first section of
1042 text.
1044 Any paragraphs of text in the preamble are treated as an abstract,
1045 and may optionally be tagged with the "abstract" style attribute.
1047 Any notes in the preamble are treated as a "note" element.
1049 An example of setting the preamble is given in Figure 16 with its
1050 rendering in Figure 17.
1052 = Four Yorkshiremen Sketch
1053 Tim Brooke-Taylor
1054 :doctype: internet-draft
1055 :status: informational
1056 :name: draft-four-yorkshiremen-00
1058 The "Four Yorkshiremen" sketch is a comedy sketch written by
1059 Tim Brooke-Taylor, John Cleese, Graham Chapman and Marty Feldman and
1060 originally performed on their TV series _At Last the 1948 Show_ in 1967.
1061 It later became associated with the comedy group Monty Python
1062 (which included Cleese and Chapman), who performed it in their live
1063 shows, including _Monty Python Live at the Hollywood Bowl_.
1065 The sketch is a parody of nostalgic conversations about humble
1066 beginnings or difficult childhoods, featuring four men from Yorkshire
1067 who reminisce about their upbringing. As the conversation progresses
1068 they try to outdo one another, and their accounts of deprived
1069 childhoods become increasingly absurd.
1071 NOTE: Barry Cryer is the wine waiter in the original performance
1072 and may have contributed to the writing.
1074 [NOTE]
1075 .Original Recording
1076 ==
1077 The original performance of the sketch by the four creators is one of
1078 the surviving sketches from the programme and can be seen on the
1079 _At Last the 1948 Show_ DVD.
1080 ==
1082 Figure 16: AsciiRFC With Preamble
1084
1085
1086 Four Yorkshiremen Sketch
1087
1089
1090
1091 tbt@example.com
1092
1093
1094
1095
1096 The "Four Yorkshiremen" sketch is a comedy sketch written by
1097 Tim Brooke-Taylor, John Cleese, Graham Chapman and Marty Feldman
1098 and originally performed on their TV series At Last the 1948
1099 Show in 1967. It later became associated with the comedy
1100 group Monty Python (which included Cleese and Chapman), who
1101 performed it in their live shows, including Monty Python
1102 Live at the Hollywood Bowl.
1103 The sketch is a parody of nostalgic conversations about humble
1104 beginnings or difficult childhoods, featuring four men from
1105 Yorkshire who reminisce about their upbringing. As the
1106 conversation progresses they try to outdo one another, and their
1107 accounts of deprived childhoods become increasingly absurd.
1108
1109
1110 Barry Cryer is the wine waiter in the original performance and
1111 may have contributed to the writing.
1112
1113
1114 Original Recording
1115 The original performance of the sketch by the four
1116 creators is one of the surviving sketches from the programme
1117 and can be seen on the At Last the 1948 Show DVD.
1118
1119
1121 Figure 17: AsciiRFC With Preamble (RFC XML v3)
1123 6. Sections and Paragraphs
1125 Section headers are given with a sequence of "=", the number of "="
1126 giving the header level. Section numbering is toggled with the in-
1127 document attribute ":sectnums:" (on), ":sectnums!:" (off). The "toc"
1128 attribute can also be set on sections, indicating whether the section
1129 can be included in the document's table of contents.
1131 Figure 18 shows how sections and paragraphs are used in AsciiRFC, and
1132 its rendered form shown in Figure 19.
1134 :sectnums:
1135 [toc=exclude]
1136 == Section 1
1137 Para 1
1139 === Subsection 1.1
1140 Para 1a
1142 :sectnums!:
1143 [toc=default]
1144 === Subsection 1.2
1145 Para 2
1147 ==== Subsection 1.2.1
1148 Para 3
1150 Figure 18: AsciiRFC With Sections
1152
1153 Section 1
1154 Para 1
1155
1156 Subsection 1.1
1157 Para 1a
1158
1159
1160 Subsection 1.2
1161 Para 2
1162
1163 Subsection 1.2.1
1164 Para 3
1165
1166
1167
1169 Figure 19: AsciiRFC With Sections (RFC XML v3)
1171 7. Figures
1173 AsciiRFC examples (corresponding to RFC XML Figures), source code
1174 Listings, and Literals (preformatted text) are all delimited blocks.
1175 Listings and Literals can occur nested within Examples.
1177 An AsciiRFC example with a figure is given in Figure 20, and its
1178 rendering in Figure 21.
1180 .Figure 1
1181 ====
1182 .figure1.txt
1183 ....
1184 Figures are only permitted to contain listings
1185 (sourcecode), images (artwork), or literal (artwork)
1187 This is some ASCII Art:
1189 _____ ___ ____ _ _
1190 | ___|_ _/ ___| | ___| |_
1191 | |_ | | | _| |/ _ \ __|
1192 | _| | | |_| | | __/ |_
1193 |_| |___\____|_|\___|\__|
1194 ....
1196 [source,ruby]
1197 ----
1198 def listing(node)
1199 result = []
1200 if node.parent.context != :example
1201 result << "
"
1202 end
1203 end
1205 Figure 20: AsciiRFC With A Figure
1207
1230 Figure 21: AsciiRFC With A Figure (RFC XML v3)
1232 If an AsciiRFC Listing or Literal occurs outside of an Example
1233 (Figure 22), the RFC XML converter will supply the surrounding
1234 Figure element (Figure 23).
1236 ....
1237 This is some ASCII Art:
1239 _____ ___ ____ _ _
1240 | ___|_ _/ ___| | ___| |_
1241 | |_ | | | _| |/ _ \ __|
1242 | _| | | |_| | | __/ |_
1243 |_| |___\____|_|\___|\__|
1244 ....
1246 Figure 22: AsciiRFC With ASCII Art Without Figure Wrapping
1248
1258 Figure 23: AsciiRFC With ASCII Art Without Figure Wrapping (RFC XML
1259 v3)
1261 8. Lists
1263 8.1. Basic Lists
1265 AsciiRFC supports ordered, unordered, and definition lists.
1266 Indentation of ordered and unordered lists is indicated by repeating
1267 the list item prefix ("*" and "." respectively).
1269 List attributes specify the type of symbol used for ordered lists.
1271 An example of AsciiRFC List is shown in Figure 24 with its rendered
1272 version in Figure 25.
1274 [loweralpha]
1275 . First
1276 . Second
1277 [upperalpha]
1278 .. Third
1279 .. Fourth
1280 . Fifth
1281 . Sixth
1283 Figure 24: AsciiRFC With Lists
1285
1286
First
1287
1288 Second
1289
1290
Third
1291
Fourth
1292
1293
1294
Fifth
1295
Sixth
1296
1298 Figure 25: AsciiRFC With Lists (RFC XML v3)
1300 8.2. List Continuation
1302 A list item by default spans a single paragraph. A following
1303 paragraph or other block element can be appended to the current list
1304 item by prefixing it with "+" in a separate line.
1306 See the "List Continuation" section in [Asciidoctor-Manual] for more
1307 information.
1309 An example of list containuation with text is shown in Figure 26 with
1310 its rendered version in Figure 27.
1312 Notes:: Note 1.
1313 +
1314 Note 2.
1315 +
1316 Note 3.
1318 Figure 26: AsciiRFC List With Text Continuation
1320
1321
Notes
1322
1323 Note 1.
1324 Note 2.
1325 Note 3.
1326
1327
1329 Figure 27: AsciiRFC List With Text Continuation (RFC XML v3)
1331 (Multiple paragraphs are not permitted within a list item in RFC XML
1332 v2. The RFC XML converter deals with this by converting paragraph
1333 breaks into line breaks within a list item.)
1335 List continuations can also be embed to populate a list item with a
1336 sequence of blocks as a unit (in an Asciidoctor open block).
1338 An example of list containuation with block is shown in Figure 28
1339 with its rendered version in Figure 29.
1341 * List Entry 1
1342 * List Entry 2
1343 +
1344 --
1345 Note 2.
1347 ....
1348 Literal
1349 ....
1351 Note 3.
1352 --
1354 Figure 28: AsciiRFC List With Block Continuation
1356
1370 Figure 29: AsciiRFC List With Block Continuation (RFC XML v3)
1372 AsciiDoc, and thus AsciiRFC, considers paragraphs to be the basic
1373 level of blocks, and does not permit lists to be nested within them:
1374 text after a list is considered to be a new paragraph.
1376 Therefore, markup as shown in Figure 30 cannot be generated via
1377 AsciiRFC.
1379
1380 This is the start of a paragraph.
1381
1382
List Entry 1
1383
1384 List Entry 2
1385 Note 2.
1386
1387
1388 And this is the continuation of the paragraph.
1389
1391 Figure 30: This RFC XML v3 Output Cannot Be Generated Using AsciiRFC
1393 9. Blockquotes
1395 Asciidoctor supports blockquotes and quotations of verse; its block
1396 quotations permit arbitrary levels of quote nesting. RFC XML v3, and
1397 thus AsciiRFC, only supports one level of blockquotes.
1399 Unlike RFC XML v2, RFC XML v3 does not support line breaks outside of
1400 tables, so verse quotations are converted to prose in the v3
1401 converter.
1403 An example of using AsciiRFC Blockquotes is given in Figure 31 with
1404 its rendered version in Figure 32.
1406 [quote,attribution="Monty Python",citetitle="http://example.com"]
1407 ____
1408 Dennis: Come and see the violence inherent in the system.
1409 Help! Help! I'm being repressed!
1411 King Arthur: Bloody peasant!
1413 Dennis: Oh, what a giveaway!
1414 * Did you hear that?
1415 * Did you hear that, eh?
1416 * That's what I'm on about!
1417 ** Did you see him repressing me?
1418 ** You saw him, Didn't you?
1419 ____
1421 Figure 31: AsciiRFC Blockquote Usage
1423
1424 Dennis: Come and see the violence inherent in the system.
1425 Help! Help! I’m being repressed!
1426 King Arthur: Bloody peasant!
1427 Dennis: Oh, what a giveaway!
1428
1429
Did you hear that?
1430
Did you hear that, eh?
1431
1432 That’s what I’m on about!
1433
1434
Did you see him repressing me?
1435
You saw him, Didn’t you?
1436
1437
1438
1439
1441 Figure 32: AsciiRFC Blockquote Usage (RFC XML v3)
1443 10. Notes And Asides
1445 Asciidoctor supports a range of "admonitions", including notes,
1446 warnings, and tips. They are indicated by a paragraph prefix (e.g.
1447 "WARNING:"), or as a block with an admonition style attribute.
1449 All admonitions are conflated in AsciiRFC, being converted to "note"
1450 elements in the document preamble, and "cref" documents in the main
1451 document.
1453 This means that all admonitions will therefore not appear in the
1454 textual output. A sample of this is shown in Figure 33 with its
1455 rendered output in Figure 34.
1457 == Section 1
1458 [NOTE,source=GBS]
1459 .Note Title
1460 ====
1461 Any admonition inside the body of the text is a comment.
1462 ====
1464 Figure 33: An AsciiRFC Adminition Block
1466
1467 Section 1
1468
1469
1470 Any admonition inside the body of the text is a comment.
1471
1472
1473
1475 Figure 34: An AsciiRFC Adminition Block (RFC XML v3)
1477 With RFC XML v2, note that no inline formatting is permitted for
1478 "cref" elements, and is therefore stripped for v2 by the converter.
1480 Because paragraphs in AsciiRFC cannot contain any other blocks, a
1481 comment at the end of a paragraph is treated as a new block. In the
1482 document converter, any such comments are moved inside the preceding
1483 RFC XML paragraph; if the comment is at the start of a section, as in
1484 the example above, it is wrapped inside a paragraph.
1486 The RFC XML v3 converter also supports "asides" (Asciidoctor
1487 sidebars). A sample is shown in Figure 35 with its rendered output
1488 in Figure 36.
1490 == Section 1
1491 ****
1492 Sidebar
1494 Another sidebar
1496 * This is a list
1498 ....
1499 And this is ascii-art
1500 ....
1501 ****
1503 Figure 35: An AsciiRFC Sidebar Block
1505
1506 Section 1
1507
1519
1521 Figure 36: An AsciiRFC Sidebar Block Rendered As An Aside (RFC XML
1522 v3)
1524 Comments given in the AsciiDoc syntax (notated with initial "//") are
1525 not intended to be shown in the rendered output, and will not appear
1526 in the output as XML comments.
1528 11. Tables
1530 AsciiRFC tables, like RFC XML v3, support distinct table heads,
1531 bodies and feet; cells spanning multiple rows and columns; and
1532 horizontal alignment. The larger range of table formatting options
1533 available in RFC XML v2 is also supported.
1535 A sample of an AsciiRFC table is shown in Figure 37 with its rendered
1536 output in Figure 38.
1538 Neither version of RFC XML is as expressive in its table structure as
1539 Asciidoctor. RFC XML, for example, does not permit blocks within
1540 table cells.
1542 .Table Title
1543 |===
1544 |head | head
1546 h|header cell | body cell
1547 | | body cell
1548 2+| colspan of 2
1549 .2+|rowspan of 2 | cell
1550 |cell
1551 ^|centre aligned cell | cell
1552 <|left aligned cell | cell
1553 >|right aligned cell | cell
1555 |foot | foot
1556 |===
1558 Figure 37: An AsciiRFC Table
1560
1561 Table Title
1562
1563
1564
head
1565
head
1566
1567
1568
1569
1570
header cell
1571
body cell
1572
1573
1574
1575
body cell
1576
1577
1578
colspan of 2
1579
1580
1581
rowspan of 2
1582
cell
1583
1584
1585
cell
1586
1587
1588
centre aligned cell
1589
cell
1591
1592
1593
left aligned cell
1594
cell
1595
1596
1597
right aligned cell
1598
cell
1599
1600
1601
1602
1603
foot
1604
foot
1605
1606
1607
1609 Figure 38: An AsciiRFC Table (RFC XML v3)
1611 12. Inline Formatting
1613 12.1. Italics, Boldface, Monospace, Subscripts, Superscripts
1615 AsciiRFC supports italics, boldface, monospace, subscripts and
1616 superscripts, just like RFC XML v3.
1618 The inline formatting syntax given in Figure 39 produces the RFC XML
1619 v3 output given in Figure 40.
1621 _Text_ *Text* `Text` ^Superscript^ ~Subscript~
1623 Figure 39: Inline Formatting In AsciiRFC
1625 TextTextText
1626 SuperscriptSubscript
1628 Figure 40: Inline Formatting In AsciiRFC (RFC XML v3)
1630 12.2. Formatting BCP 14 Keywords
1632 RFC XML v3 also supports tagging of BCP14 keywords [RFC2119]; this is
1633 done in AsciiRFC either by tagging them with a custom formatting span
1634 ("bcp14#must not#"), or by converting BCP14 boldface all-caps words
1635 (unless the ":no-rfc-bold-bcp14: false" document attribute is set).
1637 Any spans of BCP14 text delimited by inline formatting delimiters
1638 needs to be contained within a single line of text; the Asciidoctor
1639 API breaks up formatting spans across line breaks.
1641 This usage is demonstrated in Figure 41 with the rendered output in
1642 Figure 42.
1644 This [bcp14]#must not# stand
1646 This *MUST NOT* stand
1648 Figure 41: BCP14 Keywords In AsciiRFC
1650 This MUST NOT stand
1652 This MUST NOT stand
1654 Figure 42: BCP14 Keywords In AsciiRFC (RFC XML v3)
1656 12.3. Escaping AsciiRFC Syntax
1658 Formatting delimiters like "*" can be escaped with backslash ("\*");
1659 double formatting delimiters, like "**" and "__", need to be escaped
1660 with double backslash ("\\**").
1662 Escaping delimiters is not always reliable, and for double delimiters
1663 it is preferable to use HTML entities ("**"), or attribute
1664 references (references to the value of attributes set in the document
1665 header) as shown in Figure 43.
1667 :dblast: **
1669 `{dblast}`
1671 Figure 43: Escaping AsciiRFC Syntax Using Attributes
1673 In extreme circumstances (such as quoting AsciiDoc syntax), you may
1674 need to resort to altering the substitutions behaviour within a given
1675 block of of AsciiDoc; see the "Applying Substitutions" section of
1676 [Asciidoctor-Manual].
1678 13. Links
1680 Common URL formats are recognised automatically as hyperlinks in
1681 AsciiRFC, inheriting this excellent feature from AsciiDoc, and are
1682 rendered as such.
1684 Any hyperlinked text is appended after the hyperlink in square
1685 brackets.
1687 An example is given in Figure 44 with its rendered version in
1688 Figure 45.
1690 http://example.com/[linktext]
1692 Figure 44: An AsciiRFC Link
1694 linktext
1696 Figure 45: An AsciiRFC Link (RFC XML v3)
1698 To prevent hyperlinking of a URL, prefix it with a backslash, as
1699 shown in Figure 46 with its rendered version in <.
1702 \http://example.com/[linktext]
1704 Figure 46: A Literal AsciiRFC Link
1706 http://example.com/[linktext]
1708 Figure 47: A Literal AsciiRFC Link (RFC XML v3)
1710 14. Cross-References
1712 14.1. Basic Referencing
1714 Anchors for cross-references are notated as "[[...]]" or "[#...]",
1715 and can be inserted on their own line in front of most blocks.
1717 Asciidoctor supports anchors in a much wider range of contexts than
1718 is supported than RFC XML v3 (let alone v2); anchors that are not
1719 supported for that version of RFC XML are simply ignored by the
1720 converter.
1722 Note that anchors in RFC XML are constrained to the format "[A-Za-
1723 z_:][[A-Za-z0-9_:.-]*".
1725 Cross-references to anchors are notated as "<<...>>"; cross-
1726 references with custom text as "<>".
1728 An example of using cross-references in AsciiRFC is given in
1729 Figure 48 with its rendered output in Figure 49.
1731 [[cross-reference]]
1732 == Section 1
1734 == Section 2
1735 See <>.
1737 == Section 3
1738 See <>
1740 Figure 48: Setting And Referring To Cross-References In AsciiRFC
1742
1743 Section 1
1744
1745
1746 Section 2
1747
1748 See
1749
1750 .
1751
1752
1753
1754 Section 3
1755
1756 See
1757
1758 text
1759
1760
1761
1763 Figure 49: Setting And Referring To Cross-References In AsciiRFC (RFC
1764 XML v3)
1766 14.2. Referencing With Attributes
1768 While Asciidoctor natively does not support attributes on cross-
1769 references, AsciiRFC works around that by embedding formatting
1770 information as templated text within cross-references:
1772 o "format=x: text" populates the "xref@format" attribute
1774 o a section number followed by one of the words "of", "parens",
1775 "bare", "text" is treated as a "relref" reference to an external
1776 document.
1778 An example of referencing with attributes is given in Figure 50 with
1779 its output in Figure 51.
1781 == Section 4
1782 See <>
1784 == Section 5
1785 See <>
1787 See <>
1788 <>
1789 <>
1790 <>
1792 Figure 50: Cross-References With Attributes In AsciiRFC
1794
1795 Section 4
1796
1797 See
1798
1799 text
1800
1801
1802
1803
1804
1805 Section 5
1806
1807
1808 See
1809
1810
1811
1812 See
1813
1815
1817 text
1818
1819
1821
1823 text
1824
1825
1826
1828 Figure 51: Cross-References With Attributes In AsciiRFC (RFC XML v3)
1830 15. Inclusions
1832 AsciiRFC inherits the Asciidoctor "include" directive
1833 [Asciidoctor-Manual] to include external files in a master AsciiRFC
1834 document.
1836 This directive is capable of sophisticated document merging,
1837 including adjusting the heading levels of the included text,
1838 selecting text within specified tags or line numbers to be included,
1839 and adjusting the indentation of code snippets in merged text.
1841 Its basic syntax is given in Figure 52.
1843 include::path[
1844 leveloffset=_offset_,
1845 lines=_ranges_,
1846 tag(s)=_name(s)_,
1847 indent=_depth_
1848 ]
1850 Figure 52: Inclusions In AsciiRFC
1852 If a file is included in an AsciiRFC document, ensure it ends with a
1853 blank line. An inclusion that results in its final block not being
1854 delimited with a blank line from what follows can lead to
1855 unpredictable results.
1857 16. Encoding and Entities
1859 XML accepts the full range of characters in the world's languages
1860 through UTF-8 character encoding, and one of the motivations for the
1861 move from plain text to RFC XML has been to allow non-ASCII
1862 characters to be included in RFCs.
1864 However, current RFC XML v2 tools still do not support UTF-8, and
1865 alternative tooling support for UTF-8 also remains patchy. Out of an
1866 abundance of caution, the RFC XML converter uses US-ASCII for its
1867 character encoding, and renders any non-ASCII characters as HTML
1868 entities.
1870 AsciiRFC accepts HTML entities as input even though they are not part
1871 of the XML specification. HTML entities such as " " feature in
1872 examples of RFC XML provided by the IETF. In order to prevent
1873 dependence of the XML output from extraneous entity definitions, any
1874 such entities are rendered in the XML as decimal character entities.
1876 An example of how AsciiRFC renders non-ASCII UTF-8 characters are
1877 given in Figure 53 with the output in Figure 54.
1879 Это
1880 Русский
1881 Язык.
1882 — This is not George's.†
1884 Figure 53: UTF-8 Characters In AsciiRFC
1886 Это
1887 Русский
1888 Язык.
1889 — This is not George's.†
1891 Figure 54: UTF-8 Characters In AsciiRFC Rendered As RFC XML v3
1893 17. Bibliography
1895 The simple encoding of bibliography syntax provided by AsciiDoc (and
1896 Asciidoctor) is inadequate for the complexity of bibliographic markup
1897 required by RFC XML.
1899 RFC documents overwhelmingly cite other RFC documents, and canonical
1900 RFC XML bibliographic entries are available at [IETF-BibXML]; so it
1901 would be inefficient to encode those entries in AsciiRFC, only to
1902 have them converted back to RFC XML.
1904 The converter provides two means of incorporating bibliographies into
1905 RFC documents authored in AsciiRFC:
1907 o using raw RFC XML; and
1909 o assembling bibliographies in preprocessing.
1911 In either case, the RFC XML needs to be well-formed; missing closing
1912 tags can lead to erratic behaviour in the converter.
1914 17.1. Using Raw RFC XML
1916 In the first method, bibliographic citations are handled like all
1917 other AsciiRFC cross-references. The bibliographic entries for
1918 normative and informative references are given in the AsciiRFC as
1919 passthrough blocks, which contain the raw RFC XML for all references;
1920 document conversion leaves the raw RFC XML in place.
1922 This approach requires authors to maintain the normative and
1923 informative bibliographies within the document, to update them as
1924 citations are added and removed, and to sort them manually.
1926 For example, the AsciiRFC in Figure 55 will generate the
1927 corresponding RFC XML in Figure 56.
1929 Some datagram padding may be needed.<>
1931 [bibliography]
1932 == Normative References
1933 ++++
1934
1936
1937 Guidelines for Writing an IANA Considerations
1938 Section in RFCs
1939
1940 Sacramento State
1941
1942
1943 UC Davis
1944
1945
1946
1947
1948
1949 ++++
1951 Figure 55: AsciiRFC Inline Bibliography
1953 Some datagram padding may be needed
1954
1956
1957
1958 Normative References
1959
1961
1962 Guidelines for Writing an IANA Considerations
1963 Section in RFCs
1964 Sacramento State
1965
1966
1967 UC Davis
1968
1969
1970
1971
1972
1973
1974
1976 Figure 56: AsciiRFC Inline Bibliography Rendered As RFC XML v3
1978 17.2. Preprocessing Using asciidoctor-
1979 bibliography
1981 The alternative method is to use a preprocessing tool,
1982 [asciidoctor-bibliography], to import citations into the AsciiRFC
1983 document from an external file of references.
1985 The references file consists of RFC XML reference entries, and still
1986 needs to be managed manually; however the bibliographies are
1987 assembled from that file, sorted, and inserted into the normative and
1988 informative references in preprocessing. Citations in the document
1989 itself are given as macros to be interpreted by the preprocessor;
1990 this allows them to be split into normative and informative
1991 references. (The MMark tool likewise splits reference citations into
1992 normative and informative.)
1994 Integration with the "asciidoc-bibliography" gem proceeds as follows:
1996 1. Create an RFC XML references file, consisting of a ""
1997 element with individual "" elements inserted, as would
1998 be done for the informative and normative references normally.
1999 The references file will contain all possible references to be
2000 used in the file; the bibliography gem will select which
2001 references have actually been cited in the document.
2003 A. Rather than hand crafting RFC XML references for RFC
2004 documents, you should download them from an authoritative
2005 source; e.g. "http://xml.resource.org/public/rfc/bibxml/
2006 reference.RFC.2119.xml"
2008 B. Unlike the case for RFC XML documents created manually, the
2009 references file does not recognise XML entities and will not
2010 attempt to download them during processing. Any references
2011 to "http://xml.resource.org/public/rfc/bibxml/" will need to
2012 be downloaded and inserted into the references file.
2014 C. The RFC XML in the references file will need to be
2015 appropriate to the version of RFC XML used in the main
2016 document, as usual. Note that RFC XML v2 references are
2017 forward compatible with v3; v3 contains a couple of
2018 additional elements.
2020 2. Add to the main document header attributes referencing the
2021 references file (":bibliography-database:"), and the bibliography
2022 style (":bibliography-style: rfc-v3").
2024 3. References to a normative reference are inserted with the macro
2025 "cite:norm[id]" instead of "<>", where "id" is the anchor of
2026 the reference.
2028 4. References to an infomrative reference are inserted with the
2029 macro "cite:info[id]" instead of "<>", where "id" is the
2030 anchor of the reference.
2032 5. Formatted crossreferences and "relref" crossreferences are
2033 entered by inserting the expected raw XML in the "text"
2034 attribute. Do not use the "{cite}" interpolation of the
2035 citation. For example:
2037 * "<>" = "cite:norm[id, text="words"]"
2040 * "<>" (processed as a formatted
2041 cross-reference) = "cite:norm[id, text="words"]"
2044 * "<>" (processed as relref) =
2045 "cite:norm[id, text=""]"
2048 * "<>" (processed as relref with
2049 a cross-document internal reference) = "cite:norm[id,
2050 text=""]"
2053 6. Normative and Informative References are inserted in the document
2054 through a macro, which occurs where the RFC XML references would
2055 be inserted, as shown in Figure 57.
2057 [bibliography]
2058 == Normative References
2060 ++++
2061 bibliography::norm[]
2062 ++++
2064 [bibliography]
2065 == Informative References
2067 ++++
2068 bibliography::info[]
2069 ++++
2071 Figure 57: Using asciidoctor-bibliography For Bibliography
2072 Preprocessing
2074 18. RFC XML features not supported in Asciidoctor
2076 The following features of RFC XML v3 [RFC7991] and v2 [RFC7749] are
2077 not supported by the AsciiRFC converter, and would need to be
2078 adjusted manually after RFC XML is generated:
2080 +------------------------+--------------------+---------------------+
2081 | RFC XML element | RFC XML v3 | RFC XML v2 |
2082 +------------------------+--------------------+---------------------+
2083 | "front/boilerplate" | Not added by the | Not added by the |
2084 | | converter | converter |
2085 | "iref@primary" | N | N |
2086 | "reference" (and all | As Raw XML | As Raw XML |
2087 | children) | | |
2088 | "table/preamble" | Deprecated | N |
2089 | "table/postamble" | Deprecated | N |
2090 | "artwork@width" | Only on images | Only on images |
2091 | "artwork@height" | Only on images | Only on images |
2092 +------------------------+--------------------+---------------------+
2094 19. Authoring
2096 To author an AsciiRFC document, you should first familiarise yourself
2097 with the [Asciidoctor-Manual].
2099 The [asciidoctor-rfc] Ruby gem source code distribution also has
2100 samples of individual RFC XML features in v2 and v3, and examples of
2101 self-standing AsciiRFC documents, along with their RFC XML
2102 renderings. (This includes round-tripped RFC XML documents.)
2104 19.1. Using the rfc-in-asciidoc-template
2106 In addition, you can clone the sample "rfc-in-asciidoc-template"
2107 repository as a template, and populate it for your AsciiRFC document
2108 using the steps shown in Figure 58.
2110 $ git clone https://github.com/riboseinc/rfc-in-asciidoc-template
2112 Figure 58: Cloning The AsciiRFC Document Template
2114 19.2. Installing AsciiRFC Backend Processors
2116 Converting your AsciiRFC to RFC XML is a simple as installing
2117 Asciidoctor (see "Installation" at [Asciidoctor]) and the
2118 "asciidoctor-rfc" gem in Ruby (through RubyGems), then running the
2119 asciidoctor executable on the document, specifying the asciidoctor-
2120 rfc gem as a library.
2122 The necessary steps are shown in Figure 59.
2124 $ gem install asciidoctor-rfc
2125 $ asciidoctor -b rfc3 -r 'asciidoctor-rfc' foo.adoc # RFC XML v3 output
2126 $ asciidoctor -b rfc2 -r 'asciidoctor-rfc' foo.adoc # RFC XML v2 output
2128 Figure 59: Installing The AsciiRFC Backend Processors
2130 19.3. Iterating AsciiRFC Content
2132 As you author AsciiRFC content, you should iterate through running
2133 the Asciidoctor conversion frequently, to ensure that you are still
2134 generating valid XML through your markup. The converter makes an
2135 effort to ensure that its XML output is valid, and it issues warnings
2136 about likely issues; it also validates its own XML output against the
2137 RFC XML schema (of the corresponding version), and reports errors in
2138 the XML output in the format shown in Figure 60.
2140 V3 RELAXNG Validation: 12:0: ERROR: Invalid attribute
2141 sortRefs for element rfc
2143 Figure 60: Sample Validation Error Message From AsciiRFC
2145 Note that validation against the RELAXNG RFC XML schema includes
2146 confirming the referential integrity of all cross-references in the
2147 document.
2149 It may be necessary to intervene in the XML output generated by the
2150 converter, either because the block model of AsciiRFC does not
2151 conform with the intended RFC XML (e.g. lists embedded in
2152 paragraphs), or because RFC XML features are required that are not
2153 supported within AsciiRFC.
2155 20. Security Considerations
2157 o Ensure your AsciiRFC generator comes from a geniune and
2158 trustworthy source. This protects your own machine and also
2159 prevents injection of malicious content in your resulting
2160 document.
2162 o An AsciiRFC generator may cause errors in textual rendering or
2163 link generation that may lead to security issues.
2165 o Creating cross-references (and also bibliographic references) to
2166 external documents may pose risks since the specified external
2167 location may become controlled by a malicious party.
2169 21. IANA Considerations
2171 This document does not require any action by IANA.
2173 22. Examples
2175 22.1. Example 1: AsciiRFC
2177 = The Holy Hand Grenade of Antioch
2178 Arthur Pendragon
2179 :doctype: internet-draft
2180 :name: draft-iab-holy-hand-grenade-antioch-00
2181 :status: informational
2182 :ipr: trust200902
2183 :toc-include: true
2184 :forename_initials: A.
2185 :organization: Camelot
2186 :revdate: 932-06-23
2187 :area: General
2188 :workgroup: Internet Architecture Board
2189 :smart-quotes: false
2191 [abstract]
2192 The Killer Rabbit of Caerbannog is a fictional character in the Monty
2193 Python film _Monty Python and the Holy Grail_. The scene in _Holy Grail_
2194 was written by Graham Chapman and John Cleese. The rabbit is the
2195 antagonist in a major set piece battle, and makes a similar appearance
2196 in _Spamalot_, a musical inspired by the movie.
2198 == Terminology
2199 In this document, the key words *MUST*, *MUST NOT*, *REQUIRED*,
2200 *SHALL*, *SHALL NOT*, *SHOULD*, *SHOULD NOT*, *RECOMMENDED*, *MAY*, and
2201 *OPTIONAL* are to be interpreted as described in BCP 14, <>.
2203 == In The Film
2205 The Cave of Caerbannog (_caer bannog_ being Welsh for "turreted castle",
2206 thus making its title a pun on the English dish "Welsh rabbit") is the
2207 home of the Legendary Black Beast of Arrrghhh (named for the last
2208 utterance of anyone who ever saw it). This is guarded by a monster
2209 which is initially unknown. King Arthur and his knights are led to the
2210 cave by Tim the Enchanter and find that they must face its guardian
2211 beast.
2213 === Holy Hand Grenade of Antioch
2215 The Holy Hand Grenade of Antioch is a visual satire of the Sovereign's
2216 Orb of the United Kingdom, and may refer to the mythical Holy Spear of
2217 Antioch. The Holy Hand Grenade is described as one of the
2218 "sacred relics" carried by Brother Maynard. Despite its ornate
2219 appearance and long-winded instructions, it functions much the same
2220 as any other hand grenade.
2222 [bibliography]
2223 == Normative References
2224 ++++
2225
2227
2228 Key words for use in RFCs to Indicate
2229 Requirement Levels
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239 ++++
2241 [appendix]
2242 == Cultural Impact
2244 The rabbit is now used as a metaphor for something ostensibly harmless
2245 which is, in fact, deadly. Such hidden but real risks may even arise
2246 from similarly cuddly animals.
2248 22.2. Example 1: RFC XML v3
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2262
2263 The Holy Hand Grenade of Antioch
2264
2266
2268 Camelot
2269
2270 arthur@camelot.gov.uk
2271
2272
2273
2274 General
2275 Internet Architecture Board
2276
2277 The Killer Rabbit of Caerbannog is a fictional character in
2278 the Monty Python film Monty Python and the Holy
2279 Grail. The scene in Holy Grail was written by
2280 Graham Chapman and John Cleese. The rabbit is the antagonist
2281 in a major set piece battle, and makes a similar appearance
2282 in Spamalot, a musical inspired by the movie.
2283
2284
2285
2286
2287 Terminology
2288 In this document, the key words
2289 MUST,
2290 MUST NOT,
2291 REQUIRED,
2292 SHALL,
2293 SHALL NOT,
2294 SHOULD,
2295 SHOULD NOT,
2296 RECOMMENDED,
2297 MAY, and
2298 OPTIONAL are to be interpreted as described in
2299 BCP 14, .
2300
2301
2302 In The Film
2303 The Cave of Caerbannog (caer bannog being Welsh for
2304 "turreted castle", thus making its title a pun on the English
2305 dish "Welsh rabbit") is the home of the Legendary Black Beast
2306 of Arrrghhh (named for the last utterance of anyone who ever
2307 saw it). This is guarded by a monster which is initially
2308 unknown. King Arthur and his knights are led to the cave by
2309 Tim the Enchanter and find that they must face its guardian
2310 beast.
2311
2312 Holy Hand Grenade of Antioch
2313 The Holy Hand Grenade of Antioch is a visual satire of the
2314 Sovereign's Orb of the United Kingdom, and may refer to the
2315 mythical Holy Spear of Antioch. The Holy Hand Grenade is
2316 described as one of the "sacred relics" carried by Brother
2317 Maynard. Despite its ornate appearance and long-winded
2318 instructions, it functions much the same as any other hand
2319 grenade.
2320
2321
2322
2323
2324
2325 Normative References
2326
2329
2330
2331 Cultural Impact
2332 The rabbit is now used as a metaphor for something ostensibly
2333 harmless which is, in fact, deadly. Such hidden but real risks
2334 may even arise from similarly cuddly animals.
2335
2336
2337
2339 22.3. Example 2: AsciiRFC
2341 = The Holy Hand Grenade of Antioch
2342 :doctype: internet-draft
2343 :abbrev: Hand Grenade of Antioch
2344 :submission-type: independent
2345 :name: draft-iab-holy-hand-grenade-antioch-01
2346 :status: informational
2347 :consensus: false
2348 :ipr: trust200902
2349 :toc-include: true
2350 :fullname: Arthur son of Uther Pendragon
2351 :forename_initials: A.
2352 :lastname: Pendragon
2353 :email: arthur@camelot.gov.uk
2354 :forename_initials: A.
2355 :organization: Camelot
2356 :uri: http://camelot.gov.uk
2357 :street: Palace\ Camel Lot 1
2358 :city: Camelot
2359 :country: England
2360 :fullname_2: Patsy
2361 :lastname_2: Patsy
2362 :role_2: editor
2363 :email_2: patsy@camelot.gov.uk
2364 :organization_2: Camelot
2365 :postal-line_2: Camel Lot 9\ Camelot\ England
2366 :revdate: 932-06-23
2367 :area: General, Operations and Management
2368 :workgroup: Internet Architecture Board
2369 :keyword: rabbits, grenades
2370 :smart-quotes: false
2371 :obsoletes: 10, 20
2372 :updates: 2010
2373 :sort-refs: true
2374 :comments: yes
2375 :notedraftinprogress: yes
2376 :link: https://en.wikipedia.org/wiki/Rabbit_of_Caerbannog
2377 convertedFrom, http://questionthekillerrabbit.tumblr.com preview
2379 [abstract]
2380 The Killer Rabbit of Caerbannog is a fictional character in the Monty
2381 Python film _Monty Python and the Holy Grail_. The scene in _Holy Grail_
2382 was written by Graham Chapman and John Cleese. The rabbit is the
2383 antagonist in a major set piece battle, and makes a similar appearance
2384 in _Spamalot_, a musical inspired by the movie. See also
2385 <>
2387 [NOTE,remove-in-rfc=false]
2388 .Spamalot
2389 The iconic status of this scene was important in establishing
2390 the viability of the musical.
2392 [toc=exclude]
2393 :sectnums!:
2394 == Terminology
2395 In this document, the key words *MUST*, *MUST NOT*, *REQUIRED*,
2396 *SHALL*, *SHALL NOT*, *SHOULD*, *SHOULD NOT*, *RECOMMENDED*, *MAY*, and
2397 *OPTIONAL* are to be interpreted as described in BCP 14, <>.
2399 :sectnums:
2400 == In The Film
2401 The Cave of Caerbannog (_caer bannog_ being Welsh for "turreted
2402 castle", thus making its title a pun on the English dish "Welsh
2403 rabbit") is the home of the Legendary Black Beast of Arrrghhh
2404 (((Killer Rabbit of Caerbannog)))
2405 (named for the last utterance of anyone who ever saw it). This is
2406 guarded by a monster which is initially unknown. ((King Arthur)) and
2407 his knights are led to the cave by ((Tim the Enchanter)) and find that
2408 they must face its guardian beast.
2410 ****
2411 The rabbit scene was shot outside the Tomnadashan mine, a cave 4 miles
2412 (6.5 km) from the Perthshire village of Killin. For the 25th
2413 anniversary DVD, Michael Palin and Terry Jones returned to be
2414 interviewed in front of the cave but they could not remember the
2415 location.
2416 ****
2418 * Tim verbally paints a picture of
2419 a terrible monster with "nasty, big, pointy teeth!", so terrifying
2420 that Sir Robin soils his armour at the mere description.
2421 (((Sir Robin, soiling armour)))
2422 * When the
2423 guardian appears to be an innocuous white rabbit
2424 (<>:
2425 http://ascii.co.uk/art/rabbit[RABBIT - ASCII ART]), surrounded
2426 by the bones of the fallen, Arthur and his knights no longer take it
2427 seriously.
2428 ** Ignoring Tim's warnings ("a vicious streak a mile wide!"),
2429 King Arthur
2430 orders Bors to chop its head off.
2431 [upperalpha,group=Victims]
2432 ... Bors confidently approaches it,
2433 sword drawn, and is immediately decapitated by the rabbit biting
2434 clean through his neck, to the sound of a can opener.
2435 ** Despite their
2436 initial shock, Sir Robin soiling his armor again, and Tim's loud
2437 scoffing, the knights attack in force.
2438 [upperalpha,group=Victims]
2439 ... But the rabbit injures several
2440 of the knights and kills Gawain and Ector with ease. The knights
2441 themselves have no hope of killing or injuring the rabbit.
2442 ** Arthur
2443 panics and shouts for the knights to retreat ("Run away!").
2444 * Knowing
2445 they cannot risk attacking again, they try to find another way to
2446 defeat the beast.
2447 * The Holy Hand Grenade of Antioch is ultimately
2448 used to kill it and allow the quest to proceed.
2450 [NOTE,display=false,source=Lancelot]
2451 .Tip for the Bridge scene
2452 What is Lancelot's favourite colour? Will come in handy later.
2454 [[killer_bunny]]
2455 .Figure 1
2456 ====
2457 [alt=Killer Bunny]
2458 ....
2460 /\ /|
2461 |||| |
2462 \ | \
2463 _ _ / @ @
2464 / \ =>X<=
2465 /| | /
2466 \| /__| |
2467 \_____\ \__\
2469 unknown
2470 ....
2471 ====
2473 .Dramatis Personae
2474 [grid=all]
2475 |===
2476 |Actor |Role
2478 |Graham Chapman >|King Arthur
2479 |John Cleese >|Tim the Enchanter
2480 .2+|Eric Idle >|Sir Robin
2481 >|Brother Maynard
2482 |Terry Gilliam >|Sir Bors
2483 |Michael Palin >|The Lector
2484 |===
2486 === Holy Hand Grenade of Antioch
2487 [[sovereign_orb]]
2488 .Figure 2
2489 ====
2490 .Sovereign's Orb
2491 [link=https://en.wikipedia.org/wiki/File:British_Sovereigns_Orb.jpg,
2492 align=right]
2493 image::https://en.wikipedia.org/wiki/File:British_Sovereigns_Orb.jpg
2494 [Orb,124,135]
2495 ====
2497 The Holy Hand Grenade of Antioch is a visual satire of the Sovereign's
2498 Orb of the United Kingdom, Figure <>,
2499 and may refer to the mythical Holy Spear of Antioch. The Holy Hand
2500 Grenade is described as one of the "sacred relics" carried by Brother
2501 Maynard. Despite its ornate appearance and long-winded instructions,
2502 it functions much the same as any other hand grenade. At King Arthur's
2503 prompting, instructions for its use are read aloud from the fictitious
2504 _Book of Armaments_, Chapter 2, verses 9-21.
2506 NOTE: Verses parodying the King James Bible and the Athanasian Creed.
2508 [keep-with-previous=true]
2509 [quote,Book of Armaments 2:9-21,
2510 https://genius.com/Monty-python-holy-hand-grenade-of-antioch-lyrics]
2511 And Saint Attila raised the hand grenade up on high, saying,
2512 "O *LORD*, bless this Thy hand grenade that with it Thou
2513 [bcp14]#mayest# blow Thine enemies to tiny bits, in Thy mercy." And
2514 the *LORD* did grin and
2515 the people did feast upon the lambs and sloths and carp and anchovies
2516 and orangutans and breakfast cereals, and fruit bats and large chu...
2517 [At this point, the friar is urged by ((Brother Maynard)) to
2518 "skip a bit, brother"]... And the *LORD* spake, saying, "First
2519 [bcp14]#shalt# thou take out the Holy Pin, then [bcp14]#shalt# thou
2520 count to three, no more, no less. Three
2521 [bcp14]#shall# be the number thou [bcp14]#shalt# count, and the number
2522 of the counting [bcp14]#shall# be three. Four [bcp14]#shalt# thou not
2523 count, neither count thou two,
2524 excepting that thou then proceed to three. Five is right out. Once
2525 the number three, being the third number, be reached, then lobbest
2526 thou thy Holy Hand Grenade of Antioch towards thy foe, who being
2527 naughty in My sight, [bcp14]#shall# snuff it."
2529 === Code Example
2531 .Sample Python program
2532 [source,python,align=center]
2533 ----
2534 ready = True
2535 if ready:
2536 print("Hello World!")
2537 ----
2539 [bibliography]
2540 == Normative References
2541 ++++
2542
2544
2545 Key words for use in RFCs to Indicate
2546 Requirement Levels
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556 ++++
2558 [bibliography]
2559 == Informative References
2560 ++++
2561
2563
2564 DON'T SPEW A Set of Guidelines for Mass Unsolicited
2565 Mailings and Postings (spam*)
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578 ++++
2579 22.4. Example 2: RFC XML v3
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2596
2598
2600
2601 The Holy Hand Grenade
2602 of Antioch
2603
2606
2608 Camelot
2609
2610
2611 Palace
2612 Camel Lot 1
2613 Camelot
2614 England
2615
2616 arthur@camelot.gov.uk
2617 http://camelot.gov.uk
2618
2619
2620
2621 Camelot
2622
2623
2624 Camel Lot 9
2625 Camelot
2626 England
2628
2629 patsy@camelot.gov.uk
2630
2631
2632
2633 General
2634 Operations and Management
2635 Internet Architecture Board
2636 rabbits
2637 grenades
2638
2639 The Killer Rabbit of Caerbannog is a fictional character in
2640 the Monty Python film
2641 Monty Python and the Holy Grail. The scene in
2642 Holy Grail was written by Graham Chapman and John
2643 Cleese. The rabbit is the antagonist in a major set piece
2644 battle, and makes a similar appearance in
2645 Spamalot, a musical inspired by the movie. See also
2646 What
2647 is Spam*?
2648
2649
2650
2651 Spamalot
2652 The iconic status of this scene was important in establishing
2653 the viability of the musical.
2654
2655
2656
2657
2658 Terminology
2659 In this document, the key words
2660 MUST,
2661 MUST NOT,
2662 REQUIRED,
2663 SHALL,
2664 SHALL NOT,
2665 SHOULD,
2666 SHOULD NOT,
2667 RECOMMENDED,
2668 MAY, and
2669 OPTIONAL are to be interpreted as described in
2670 BCP 14, .
2671
2672
2673 In The Film
2674 The Cave of Caerbannog (caer bannog being Welsh for
2675 "turreted castle", thus making its title a pun on the English
2676 dish "Welsh rabbit") is the home of the Legendary Black Beast
2677 of Arrrghhh
2678 (named for the last utterance of anyone who ever saw it). This
2679 is guarded by a monster which is initially unknown. King
2680 Arthur and his knights are led to
2681 the cave by Tim the Enchanter
2682 and find that they must
2683 face its guardian beast.
2684
2691
2692
Tim verbally paints a picture of a terrible monster with
2693 "nasty, big, pointy teeth!", so terrifying that Sir Robin
2694 soils his armour at the mere description.
2695
2696
2697
2698 When the guardian appears to be an innocuous white rabbit
2699 (See depiction:
2700 RABBIT -
2701 ASCII ART), surrounded by the bones of the fallen,
2702 Arthur and his knights no longer take it seriously.
2703
2704
2705 Ignoring Tim's warnings ("a vicious streak a mile
2706 wide!"), King Arthur orders Bors to chop its head off.
2707
2708
Bors confidently approaches it, sword drawn, and is
2709 immediately decapitated by the rabbit biting clean
2710 through his neck, to the sound of a can opener.
2711
2712
2713
2714 Despite their initial shock, Sir Robin soiling his
2715 armor again, and Tim's loud scoffing, the knights attack
2716 in force.
2717
2718
But the rabbit injures several of the knights and
2719 kills Gawain and Ector with ease. The knights
2720 themselves have no hope of killing or injuring the
2721 rabbit.
2722
2723
2724
Arthur panics and shouts for the knights to retreat
2725 ("Run away!").
2726
2727
2728
Knowing they cannot risk attacking again, they try to find
2729 another way to defeat the beast.
2730
The Holy Hand Grenade of Antioch is ultimately used to
2731 kill it and allow the quest to proceed.
2732
2733
2734 What is Lancelot's
2735 favourite colour? Will come in handy later.
2736
2737
2753
2754 Dramatis Personae
2755
2756
2757
Actor
2758
Role
2759
2760
2761
2762
2763
Graham Chapman
2764
King Arthur
2765
2766
2767
John Cleese
2768
Tim the Enchanter
2769
2770
2771
Eric Idle
2772
Sir Robin
2773
2774
2775
Brother Maynard
2776
2777
2778
Terry Gilliam
2779
Sir Bors
2780
2781
2782
Michael Palin
2783
The Lector
2784
2785
2786
2787
2788 Holy Hand Grenade of Antioch
2789
2796 The Holy Hand Grenade of Antioch is a visual satire of the
2797 Sovereign's Orb of the United Kingdom, Figure
2798 , and may
2799 refer to the mythical Holy Spear of Antioch. The Holy Hand
2800 Grenade is described as one of the "sacred relics" carried
2801 by Brother Maynard. Despite its ornate appearance and
2802 long-winded instructions, it functions much the same as any
2803 other hand grenade. At King Arthur's prompting, instructions
2804 for its use are read aloud from the fictitious
2805 Book of Armaments, Chapter 2, verses 9-21.
2806 Verses parodying the King James Bible and the
2807 Athanasian Creed.
2808
2809
And
2812 Saint Attila raised the hand grenade up on high, saying,
2813 "O LORD, bless this Thy hand grenade that
2814 with it Thou MAYEST blow Thine enemies to
2815 tiny bits,
2816 in Thy mercy." And the LORD did grin and
2817 the people did feast upon the lambs and sloths and carp and
2818 anchovies and orangutans and breakfast cereals, and fruit
2819 bats and large
2820 chu… [At this point, the friar is urged by
2821 Brother Maynard to "skip a
2822 bit, brother"]… And the LORD
2823 spake, saying, "First SHALT
2824 thou take out the Holy Pin, then SHALT thou
2825 count to three, no more, no less. Three
2826 SHALL be the number thou
2827 SHALT count, and the number of the counting
2828 SHALL be three. Four SHALT
2829 thou not count, neither count thou two, excepting that thou
2830 then proceed to three. Five is right out. Once
2831 the number three, being the third number, be reached, then
2832 lobbest thou thy Holy Hand Grenade of Antioch towards thy
2833 foe, who being naughty in My sight,
2834 SHALL snuff it."
2835
2836
2837 Code Example
2838
2845
2846
2847
2848
2849
2850 Normative References
2851
2854
2855
2856 Informative References
2857
2860
2861
2862
2863 23. References
2865 23.1. Normative References
2867 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2868 Requirement Levels", BCP 14, RFC 2119,
2869 DOI 10.17487/RFC2119, March 1997,
2870 .
2872 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
2873 RFC 7991, DOI 10.17487/RFC7991, December 2016,
2874 .
2876 23.2. Informative References
2878 [AsciiDoc]
2879 Rackham, S., "AsciiDoc: Text based document generation",
2880 November 2013, .
2882 [Asciidoctor]
2883 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast
2884 text processor & publishing toolchain for converting
2885 AsciiDoc to HTML5, DocBook & more.", November 2017,
2886 .
2888 [asciidoctor-bibliography]
2889 Ribose Inc., "Citations and Bibliography the 'asciidoctor-
2890 way'", November 2017,
2891 .
2893 [Asciidoctor-Manual]
2894 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast
2895 text processor & publishing toolchain for converting
2896 AsciiDoc to HTML5, DocBook & more.", November 2017,
2897 .
2899 [asciidoctor-rfc]
2900 Ribose Inc., "asciidoctor-rfc lets you write Internet-
2901 Drafts and RFCs in AsciiDoc, the "asciidoctor-way".",
2902 November 2017,
2903 .
2905 [AsciiMathML]
2906 "AsciiMath is an easy-to-write markup language for
2907 mathematics.", November 2017, .
2909 [draftr] Barnes, R., "draftr: an HTML front-end to pandoc2rfc", Nov
2910 2017, .
2912 [IETF-BibXML]
2913 "IETF BibXML Library", November 2017,
2914 .
2916 [kramdown-rfc2629]
2917 Bormann, C., "kramdown-rfc2629: An RFC2629 (XML2RFC)
2918 backend for Thomas Leitner's kramdown markdown parser",
2919 Nov 2017, .
2921 [lyx2rfc] Williams, N., "LyX to I-D/RFC export by way of Lyx export
2922 to XHTML and XSLT conversion to xml2rfc schema", 2014,
2923 .
2925 [MathJax] "MathJax: A JavaScript display engine for mathematics that
2926 works in all browsers.", November 2017,
2927 .
2929 [mmark] Gieben, R., "Using mmark to create I-Ds and RFCs", June
2930 2015, .
2932 [NroffEdit]
2933 Santesson, S., "WYSIWYG Internet-Draft Nroff Editor", May
2934 2011, .
2936 [pandoc2rfc]
2937 Gieben, R., "pandoc2rfc: Use pandoc to create XML suitable
2938 for xml2rfc", 2012, .
2940 [RFC5385] Touch, J., "Version 2.0 Microsoft Word Template for
2941 Creating Internet Drafts and RFCs", RFC 5385,
2942 DOI 10.17487/RFC5385, February 2010,
2943 .
2945 [RFC7328] Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit
2946 of XML", RFC 7328, DOI 10.17487/RFC7328, August 2014,
2947 .
2949 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary",
2950 RFC 7749, DOI 10.17487/RFC7749, February 2016,
2951 .
2953 [RFC7763] Leonard, S., "The text/markdown Media Type", RFC 7763,
2954 DOI 10.17487/RFC7763, March 2016,
2955 .
2957 [RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies,
2958 Stability Strategies, and Select Registrations", RFC 7764,
2959 DOI 10.17487/RFC7764, March 2016,
2960 .
2962 [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990,
2963 DOI 10.17487/RFC7990, December 2016,
2964 .
2966 [TeX-LaTeX]
2967 "LaTeX is document preparation software that runs on top
2968 of Donald E. Knuth's TeX typesetting system.", November
2969 2017, .
2971 Appendix A. Acknowledgements
2973 The authors would like to thank the following persons for their
2974 valuable advice and input.
2976 Authors' Addresses
2978 Ronald Henry Tse
2979 Ribose
2980 Suite 1111, 1 Pedder Street
2981 Central, Hong Kong
2982 Hong Kong
2984 Email: ronald.tse@ribose.com
2985 URI: https://www.ribose.com
2987 Nick Nicholas
2988 Ribose
2989 Australia
2991 Email: nick.nicholas@ribose.com
2992 URI: https://www.ribose.com
2994 Jeffrey Lau
2995 Ribose
2996 Suite 1111, 1 Pedder Street
2997 Central, Hong Kong
2998 Hong Kong
3000 Email: jeffrey.lau@ribose.com
3001 URI: https://www.ribose.com
3002 Paolo Brasolin
3003 Ribose
3004 Italy
3006 Email: paolo.brasolin@ribose.com
3007 URI: https://www.ribose.com