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<title> 583 <author initials="T." surname="Krovetz"> 584 <organization>Sacramento State<organization> 585 </author> 586 <author initials="P." surname="Rogaway"> 587 <organization>UC Davis<organization> 588 </author> 589 <date month="May" year="2014" /> 590 </front> 591 <seriesInfo name="RFC" value="7253" /> 592 </reference> 593 </references> 594 <section anchor="_addendum" numbered="false"> 595 <name>Addendum<name> 596 <t>But you try and tell the young people today that…​ 597 and they won't believe ya'.<t> 598 </section> 599 </back> 600 </rfc> 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 <rfc ipr="trust200902" obsoletes="10, 120" updates="2010, 2120" 613 category="info" submissionType="IETF" 614 docName="draft-four-yorkshiremen-00"> 615 <front> 616 <title abbrev="4 Yorkshiremen">Four Yorkshiremen Sketch<title> 617 <author fullname="Tim Brooke-Taylor" surname="Brooke-Taylor"> 618 <organization>BBC</organization> 619 <address> 620 <postal> 621 <street>10 Moulton Street</street> 622 <city>Cambridge</city> 623 <code>MA 02238</code> 624 </postal> 625 <phone>(555) 555-5555</phone> 626 <email>tbt@example.com</email> 627 <uri>http://example.com</uri> 628 </address> 629 </author> 630 <author fullname="John Cleese" surname="Cleese"> 631 <address> 632 <email>jc@example.com</email> 633 </address> 634 </author> 635 <author fullname="Graham Chapman" surname="Chapman"> 636 <address> 637 <email>gc@example.com</email> 638 </address> 639 </author> 640 <author fullname="Marty Feldman" surname="Feldman"> 641 <address> 642 <email>mf@bcc.co.uk</email> 643 </address> 644 </author> 645 <date day="1" month="April" year="1990" /> 646 <area>Internet</area> 647 <workgroup>Network Working Group</workgroup> 648 <keyword>yorkshire</keyword> 649 <keyword>memory</keyword> 650 <abstract> 651 <t>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 <xref target="michaelpalin" /> 657 <xref target="ericidle" /></t> 658 </abstract> 659 <note title="NOTE"> 660 <t>See also Wikipedia summary</t> 661 </note> 662 </front> 663 <middle> 664 <section anchor="michaelpalin" title="Claim: Michael Palin"> 665 <t>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 <xref target="RFC7253" /></t> 671 <section anchor="_response_graham_chapman" 672 title="Response: Graham Chapman"> 673 <t>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 <spanx style="strong">lucky</spanx>!</t> 679 </section> 680 <section anchor="_response_terry_gilliam" 681 title="Response: Terry Gilliam"> 682 <t>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 <spanx style="strong">lick<spanx> 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.</t> 689 </section> 690 <section anchor="ericidle" title="Response: Eric Idle"> 691 <t>Right.</t> 692 <t>I had to get up in the morning at ten o'clock at night, half 693 an hour before I went to bed, (<spanx style="emph">pause 694 for laughter</spanx>), 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."</t> 699 </section> 700 </section> 701 </middle> 702 <back> 703 <references title="Normative References"> 704 <reference anchor="RFC7253" 705 target="https://tools.ietf.org/html/rfc7253"> 706 <front> 707 <title>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
1208 Figure 1 1209 1210 Figures are only permitted to contain listings 1211 (sourcecode), images (artwork), or literal (artwork) 1213 This is some ASCII Art: 1215 _____ ___ ____ _ _ 1216 | ___|_ _/ ___| | ___| |_ 1217 | |_ | | | _| |/ _ \ __| 1218 | _| | | |_| | | __/ |_ 1219 |_| |___\____|_|\___|\__| 1220 1221 def listing(node) 1222 result = [] 1223 if node.parent.context != :example 1224 result << "<figure>" 1225 end 1226 end 1227 1228
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
1249 This is some ASCII Art: 1251 _____ ___ ____ _ _ 1252 | ___|_ _/ ___| | ___| |_ 1253 | |_ | | | _| |/ _ \ __| 1254 | _| | | |_| | | __/ |_ 1255 |_| |___\____|_|\___|\__| 1256
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
  1. First
  2. 1287
  3. 1288 Second 1289
      1290
    1. Third
    2. 1291
    3. Fourth
    4. 1292
    1293
  4. 1294
  5. Fifth
  6. 1295
  7. Sixth
  8. 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
    1357
  • List Entry 1
  • 1358
  • 1359 List Entry 2 1360 Note 2. 1361
    1362 1363 Literal 1364 1365
    1366 Note 3. 1367
  • 1368
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 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607
headhead
header cellbody cell
body cell
colspan of 2
rowspan of 2cell
cell
centre aligned cellcell
left aligned cellcell
right aligned cellcell
footfoot
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 Text Text Text 1626 Superscript Subscript 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
      1. 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.
      2. 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
      1. 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.
      2. 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
2738 Figure 1 2739 2741 /\ /| 2742 |||| | 2743 \ | \ 2744 _ _ / @ @ 2745 / \ =>X<= 2746 /| | / 2747 \| /__| | 2748 \_____\ \__\ 2750 unknown 2751 2752
2753 2754 Dramatis Personae 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786
ActorRole
Graham ChapmanKing Arthur
John CleeseTim the Enchanter
Eric IdleSir Robin
Brother Maynard
Terry GilliamSir Bors
Michael PalinThe Lector
2787
2788 Holy Hand Grenade of Antioch 2789
2790 Figure 2 2791 2795
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
2839 2840 ready = True 2841 if ready: 2842 print("Hello World!") 2843 2844
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