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