idnits 2.17.1 draft-ribose-asciirfc-01.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 67 instances of too long lines in the document, the longest one being 9 characters in excess of 72. == 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 (November 25, 2017) is 2344 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 1971 -- Looks like a reference, but probably isn't: '2' on line 1973 -- Looks like a reference, but probably isn't: '3' on line 1975 -- Looks like a reference, but probably isn't: '4' on line 1977 -- Looks like a reference, but probably isn't: '5' on line 1979 == Missing Reference: 'NOTE' is mentioned on line 987, but not defined -- Looks like a reference, but probably isn't: '6' on line 1981 -- Looks like a reference, but probably isn't: '7' on line 1983 -- Looks like a reference, but probably isn't: '8' on line 1985 -- Looks like a reference, but probably isn't: '9' on line 1987 -- Looks like a reference, but probably isn't: '10' on line 1989 -- Looks like a reference, but probably isn't: '11' on line 1992 -- Obsolete informational reference (is this intentional?): RFC 7749 (Obsoleted by RFC 7991) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 13 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: May 29, 2018 P. Brasolin 6 Ribose 7 November 25, 2017 9 Writing Internet-Drafts And RFCs In AsciiDoc (AsciiRFC) 10 draft-ribose-asciirfc-01 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 XML RFC 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 XML RFC v2 27 (RFC7749) and XML RFC 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 May 29, 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. Simple illustration . . . . . . . . . . . . . . . . . . . 7 69 4. Header And Document Attributes . . . . . . . . . . . . . . . 15 70 5. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 22 71 6. Sections and Paragraphs . . . . . . . . . . . . . . . . . . . 24 72 7. Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 73 8. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 74 9. Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . . 30 75 10. Notes And Asides . . . . . . . . . . . . . . . . . . . . . . 31 76 11. Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 77 12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . . 35 78 13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 79 14. Crossreferences . . . . . . . . . . . . . . . . . . . . . . . 36 80 15. Inclusions . . . . . . . . . . . . . . . . . . . . . . . . . 38 81 16. Encoding and Entities . . . . . . . . . . . . . . . . . . . . 39 82 17. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 39 83 17.1. Using Raw RFC XML . . . . . . . . . . . . . . . . . . . 40 84 17.2. Using preprocessing . . . . . . . . . . . . . . . . . . 41 85 18. RFC XML features not supported in Asciidoctor . . . . . . . . 43 86 19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 43 87 20. Security Considerations . . . . . . . . . . . . . . . . . . . 44 88 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45 89 22. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 45 90 22.1. Example 1 . . . . . . . . . . . . . . . . . . . . . . . 45 91 23. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 92 23.1. Normative References . . . . . . . . . . . . . . . . . . 45 93 23.2. Informative References . . . . . . . . . . . . . . . . . 45 94 23.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 47 96 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 47 97 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47 99 1. Introduction 101 Internet-Drafts and RFCs intended for publication submission to the 102 IETF can be written in a multitude of formats today, including: 104 o XML: RFC XML v2 [RFC7749] and v3 [RFC7991] 106 o nroff: through "NroffEdit" [NroffEdit] 108 o Microsoft Word: through usage of [RFC5385] 110 o Lyx: through [lyx2rfc] 112 o Pandoc: [RFC7328], through [pandoc2rfc] or [draftr] 114 o Kramdown: through [kramdown-rfc2629] 116 o mmark: through [mmark] 118 Interestingly, the last three are Markdown [RFC7763] variants. 120 As specified in [RFC7990], the IETF intends for the canonical format 121 of RFCs to transition from plain-text ASCII to RFC XML v3 [RFC7991]. 122 While plain-text will continue to be accepted from authors by the 123 IETF, at least in the short- to medium-term, XML will be preferred 124 for submission, and any plain-text submissions will need to be 125 converted to RFC XML v3. 127 While this need is already met for RFC XML v2 [RFC7749] by the tools 128 specified above, the transition to RFC XML v3 [RFC7991] places added 129 onus on authors to generate compliant XML. 131 [AsciiDoc] is an alternative markup language to Markdown, with 132 features that make it attractive as a markup language for RFC with 133 XML output. This document describes the use of [Asciidoctor], a 134 Ruby-based enhancement of the original AsciiDoc markup language, for 135 RFC XML markup, with a Ruby gem written by the authors used to render 136 Asciidoctor documents as RFC XML. The markup language used 137 specifically for the purpose of generating RFC XML document is called 138 "AsciiRFC". 140 Section 1.2 of [RFC7764] famously states that "there is no such thing 141 as "invalid" Markdown, there is no standard demanding adherence to 142 the Markdown syntax, and there is no governing body that guides or 143 impedes its development." While there are contexts where that lack 144 of rigour is helpful, the authoring of RFCs does have a standard and 145 a governing body, and there is such a thing as invalid RFC XML. A 146 more rigorous counterpart to Markdown, which still preserves its 147 basic approach to formatting, is useful in generating RFC XML that 148 encompasses a fuller subset of the specification, and preempting 149 malformed RFC XML output. 151 Compared to Markdown [1], 153 o AsciiDoc was designed from the beginning as a publishing language: 154 it was initially intended as a plain-text alternative to the 155 DocBook XML schema. For that reason, Asciidoctor natively 156 supports the full range of formatting required by RFC XML 157 (including notes, tables, bibliographies, source-code blocks, and 158 definition lists), without resorting to embedded HTML or Markdown 159 "flavours". 161 o AsciiDoc in its Ruby-based Asciidoctor implementation is 162 extensible, with a well-defined API. (Extensions have been 163 harnessed to deal with bibliographic preprocessing for AsciiRFC.) 165 o AsciiRFC allows granular control of rendering, including user- 166 specified attributes of text blocks. 168 o The Asciidoctor implementation allows document inclusion, for 169 managing large-scale documentation projects. 171 o AsciiRFC allows granular control of permutations of block nesting, 172 such as source code within lists or definition lists within 173 unordered lists. 175 o As a more formal counterpart to Markdown, AsciiDoc is well-suited 176 to generating XML that needs to conform to a specified schema. 178 As with Markdown, there is a wide range of tools that can render 179 AsciiDoc; so AsciiRFC drafts of RFC documents can be previewed and 180 accessed without depending on the RFC tools ecosystem. Our 181 realisation of RFC XML in AsciiRFC has aimed to ensure that, as much 182 as possible, the markup language can be can be processed by generic 183 Asciidoctor tools. (The only exception to this as an add-on is the 184 optional bibliography module, which allows bibliographies to be 185 assembled on the fly based on citations in a document: see 186 Section 17.2.) 188 2. Conventions Used in This Document 190 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 191 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*MAY*", 192 and "*OPTIONAL*" in this document are to be interpreted as described 193 in [RFC2119]. 195 2.1. Definitions 197 In this document, _AsciiDoc_ refers to the markup language 198 generically. _Asciidoctor_ refers specifically to the Ruby-based 199 implementation of the markup language, which has enhanced the 200 original markup language. The RFC XML document converter contributed 201 by the authors uses a subset of _Asciidoctor_, with some minor 202 additions (a few document attributes specific to RFC XML, some macros 203 specific to citation processing, and some templated use of 204 _Asciidoctor_ crossreferences). This variant of _Asciidoctor_ markup 205 is referred to as _AsciiRFC_. 207 3. Document Structure And AsciiDoctor Syntax 209 The syntax of Asciidoctor is presented in the Asciidoctor user manual 210 [2]. AsciiRFC is a subset of Asciidoctor syntax, with the addition 211 of bibliographic macros (Section 17.2). 213 Asciidoctor consists of: 215 o A document header, containing a title, a list of authors, and 216 document attributes in lines prefixed with ":". 218 o An optional document preamble, separated from document header by a 219 blank line. 221 o A number of sections, set off by a section title (a line prefixed 222 with two or more "=". A section may contain: 224 * Other sections, whose level of nesting is indicated by the 225 number of "=" in their header. 227 * Blocks of text. Blocks can have metadata (including a title, 228 an anchor for cross-references, and attributes.) Blocks can 229 be: 231 + Paragraphs, which are terminated by blank lines. 233 + Lists. List items are by default paragraphs, but can span 234 over multiple paragraphs. 236 + Delimited blocks (with a line delimiter on either side of 237 them); these include tables, notes, sidebars, source code, 238 block quotes, examples, and unprocessed content (e.g. raw 239 XML). Delimited blocks contain by default one or more 240 paragraphs. 242 + List items can contain other blocks, including both nested 243 lists and delimited blocks. 245 + Some delimited blocks can contain other delimited blocks; 246 for example, examples can contain source code as well as 247 discussion in paragraphs. 249 * Blocks of text consist of inline text, which themselves can 250 contain markup. 252 Inline markup includes: 254 o Text formatting: bold, italic, superscript, subscript, monospace. 256 o Custom markup macros. (AsciiRFC uses one: "bcp14".) 258 o URLs, including display text. 260 o Inline anchors. 262 o Cross-references to anchors (IDs of blocks or spans of text), 263 including display text. 265 o Images, audio, and visual files. (AsciiRFC only supports images.) 267 o Index terms. 269 o Equations (native support for AsciiMathML [3] and TeX/LaTeX [4], 270 via the MathJax [5] tool). (Not supported in AsciiRFC, since 271 there is no RFC XML equivalent.) 273 o Footnotes. (Not supported in AsciiRFC.) 275 The Asciidoctor document structure aligns with the RFC XML v2 and v3 276 structure. In the following, v3 equivalences are given: 278 o Header: "" attributes, most "front" elements. 280 o Preamble: "front/abstract" and "front/note". 282 o Sections: "middle/section" elements. 284 o Sections with "bibliography" style attributes: "back/references" 285 elements. 287 o Sections with "appendix" style attributes: "back/section" 288 elements. 290 o Paragraphs: "t" elements. 292 o Lists: "ul", "ol", "dl" elements. 294 o Delimited blocks: "artwork", "aside", "blockquote", "figure", 295 "note", "sourcecode", "table". 297 o Inline markup: "bcp14", "br", "cref", "em", "eref", "iref", 298 "relref", "strong", "sub", "sup", "tt", "xref". 300 Full details of the mapping of AsciiRFC elements to RFC XML v2 and v3 301 elements, and of how to convert AsciiRFC documents to RFC XML, are 302 given in . The following gives an overview of how to create an 304 RFC XML document in AsciiRFC, with some pitfalls to be aware of. 305 Illustrations are in RFC XML v3, although the converter deals with 306 both versions of RFC XML. 308 3.1. Simple illustration 310 The following is an illustration of a simple AsciiRFC document, and 311 its corresponding rendering in RFC XML v3: 313 = Four Yorkshiremen Sketch 314 Tim Brooke-Taylor; John Cleese; Graham Chapman; Marty Feldman 315 :doctype: internet-draft 316 :abbrev: 4 Yorkshiremen 317 :obsoletes: 10, 120 318 :updates: 2010, 2120 319 :status: informational 320 :name: draft-four-yorkshiremen-00 321 :ipr: trust200902 322 :area: Internet 323 :workgroup: Network Working Group 324 :keyword: yorkshire, memory 325 :revdate: 1990-04-01T00:00:00Z 326 :organization: BBC 327 :phone: (555) 555-5555 328 :uri: http://example.com 329 :street: 10 Moulton Street 330 :city: Cambridge 331 :code: MA 02238 332 :email: tbt@example.com 333 :email_2: jc@example.com 334 :email_3: gc@example.com 335 :email_4: mf@bcc.co.uk 336 :smart-quotes: false 337 :link: https://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch describedby 339 [abstract] 340 The sketch is a parody of nostalgic conversations about humble 341 beginnings or difficult childhoods, featuring four men from Yorkshire 342 who reminisce about their upbringing. As the conversation progresses 343 they try to outdo one another, and their accounts of deprived 344 childhoods become increasingly absurd. <> <> 346 NOTE: See also Wikipedia summary 348 [#michaelpalin] 349 == Claim: Michael Palin 350 You were lucky. We lived for three months in a brown paper bag in a septic 351 tank. We used to have to get up at six o'clock in the morning, clean the 352 bag, eat a crust of stale bread, go to work down mill for fourteen hours 353 a day week in-week out. When we got home, out Dad would thrash us to 354 sleep with his belt! <> 356 === Response: Graham Chapman 357 Luxury. We used to have to get out of the lake at three o'clock in the morning, 358 clean the lake, eat a handful of hot gravel, go to work at the mill every day 359 for tuppence a month, come home, and Dad would beat us around the head and 360 neck with a broken bottle, if we were *lucky*! 362 === Response: Terry Gilliam 363 Well we had it tough. We used to have to get up out of the shoebox at 364 twelve o'clock at night, and *lick* the road clean with our tongues. We had 365 half a handful of freezing cold gravel, worked twenty-four hours a day at the 366 mill for fourpence every six years, and when we got home, our Dad would 367 slice us in two with a bread knife. 369 [#ericidle] 370 === Response: Eric Idle 371 Right. 373 I had to get up in the morning at ten o'clock at night, half an hour 374 before I went to bed, (_pause for laughter_), eat a lump of cold poison, 375 work twenty-nine hours a day down mill, and pay mill owner for permission to come 376 to work, and when we got home, our Dad would kill us, and dance about on our 377 graves singing "Hallelujah." 379 [bibliography] 380 == Normative References 381 ++++ 382 384 385 Guidelines for Writing an IANA Considerations 386 Section in RFCs 387 388 Sacramento State 389 390 391 UC Davis 392 393 394 395 396 397 ++++ 399 [appendix] 400 == Addendum 401 But you try and tell the young people today that... and they won't believe ya'. 403 The first block of text, from "= Four Yorkshiremen Sketch" through to 404 ":link: https ://en.wikipedia.org/wiki/Four_Yorkshiremen_sketch 405 describedby", is the document header. It contains a title in the 406 first line, an author attribution, and then a set of document 407 attributes, conveying information about the document as well as 408 information about its authors. This information ends up either as 409 attributes of the root "rfc" tag, elements of the "front" tag, or 410 processing instructions. 412 The following blocks of text, up until the first section header ("== 413 Claim: Michael Palin"), are the document preamble. They are treated 414 by the document converter as containing the document abstract 415 ("abstract"), followed by any notes ("note", identified above by the 416 "NOTE:" heading). 418 The first section header ("== Claim: Michael Palin") is preceded by 419 an anchor for that section ("[#michaelpalin]"). There is a cross- 420 reference to that anchor already in place in the abstract 421 ("<>"). The document converter treats the first 422 section of the document as the start of the "middle" section of the 423 document. 425 The first section header is followed by a paragraph, and other 426 sections and paragraphs. The number of "=" signs are one higher than 427 the initial section header, which indicates that they are subsections 428 of that section. The paragraphs contains some inline formatting 429 (italics: "_pause for laughter_"; boldface: "*lick*"). The first 430 paragraph also contains a citation of a reference, which in this 431 version of AsciiRFC is treated identically to a cross-reference 432 ("<>"). (If the bibliography preprocessor were used, it 433 would be encoded differently.) 435 The second last section is tagged with the style attribute 436 "[bibliography]", which identifies it as a references container; the 437 document converter accordingly inserts this into the "back" element 438 of the document. The contents of the references section are in this 439 instance raw XML, delimited as a passthrough block (with "++++"), 440 which the converter does not alter. The final section is tagged with 441 the style attribute "[appendix]", and is treated as such. 443 The RFC XML v3 document generated from this AsciiRFC document is: 445 446 447 449 451 452 Four Yorkshiremen Sketch 453 455 456 BBC 457
458 459 10 Moulton Street 460 Cambridge 461 MA 02238 462 463 (555) 555-5555 464 tbt@example.com 465 http://example.com 466
467 468 469
470 jc@example.com 471
472 473 474
475 gc@example.com 477
478 479 480
481 mf@bcc.co.uk 482
483 484 485 Internet 486 Network Working Group 487 yorkshire 488 memory 489 490 The sketch is a parody of nostalgic conversations about humble 491 beginnings or difficult childhoods, featuring four men from Yorkshire who 492 reminisce about their upbringing. As the conversation progresses they try 493 to outdo one another, and their accounts of deprived childhoods become 494 increasingly absurd. 495 496 497 498 See also Wikipedia summary 499 500 501 502
503 Claim: Michael Palin 504 You were lucky. We lived for three months in a brown paper bag in a 505 septic tank. We used to have to get up at six o'clock in the morning, 506 clean the bag, eat a crust of stale bread, go to work down mill for 507 fourteen hours a day week in-week out. When we got home, out Dad would 508 thrash us to sleep with his belt! 509
510 Response: Graham Chapman 511 Luxury. We used to have to get out of the lake at three o'clock in 512 the morning, clean the lake, eat a handful of hot gravel, go to work 513 at the mill every day for tuppence a month, come home, and Dad would 514 beat us around the head and neck with a broken bottle, if we were 515 lucky! 516
517
518 Response: Terry Gilliam 519 Well we had it tough. We used to have to get up out of the shoebox at 520 twelve o'clock at night, and lick 521 the road clean with our tongues. We had half a handful of freezing 522 cold gravel, worked twenty-four hours a day at the mill for fourpence 523 every six years, and when we got home, our Dad would slice us in two 524 with a bread knife. 526
527
528 Response: Eric Idle 529 Right. 530 I had to get up in the morning at ten o'clock at night, half an hour 531 before I went to bed, (pause for laughter), eat a lump of 532 cold poison, work twenty-nine hours a day down mill, and pay mill 533 owner for permission to come to work, and when we got home, our Dad 534 would kill us, and dance about on our graves singing "Hallelujah." 535
536
537 538 539 540 Normative References 541 542 543 Guidelines for Writing an IANA Considerations Section 544 in RFCs<title> 545 <author initials="T." surname="Krovetz"> 546 <organization>Sacramento State<organization> 547 </author> 548 <author initials="P." surname="Rogaway"> 549 <organization>UC Davis<organization> 550 </author> 551 <date month="May" year="2014" /> 552 </front> 553 <seriesInfo name="RFC" value="7253" /> 554 </reference> 555 </references> 556 <section anchor="_addendum" numbered="false"> 557 <name>Addendum<name> 558 <t>But you try and tell the young people today that…​ 559 and they won't believe ya'.<t> 560 </section> 561 </back> 562 </rfc> 564 Some default processing instructions have already been prefixed to 565 the XML. 567 Although we do not describe it extensively in this document, our 568 AsciiRFC converter also generates RFC XML v2 from the same source 569 AsciiRFC. For illustration, the foregoing AsciiRFC document 570 generates the following RFC XML v2 output: 572 <rfc ipr="trust200902" obsoletes="10, 120" updates="2010, 2120" 573 category="info" submissionType="IETF" 574 docName="draft-four-yorkshiremen-00"> 575 <front> 576 <title abbrev="4 Yorkshiremen">Four Yorkshiremen Sketch<title> 577 <author fullname="Tim Brooke-Taylor" surname="Brooke-Taylor"> 578 <organization>BBC</organization> 579 <address> 580 <postal> 581 <street>10 Moulton Street</street> 582 <city>Cambridge</city> 583 <code>MA 02238</code> 584 </postal> 585 <phone>(555) 555-5555</phone> 586 <email>tbt@example.com</email> 587 <uri>http://example.com</uri> 588 </address> 589 </author> 590 <author fullname="John Cleese" surname="Cleese"> 591 <address> 592 <email>jc@example.com</email> 593 </address> 594 </author> 595 <author fullname="Graham Chapman" surname="Chapman"> 596 <address> 597 <email>gc@example.com</email> 598 </address> 599 </author> 600 <author fullname="Marty Feldman" surname="Feldman"> 601 <address> 602 <email>mf@bcc.co.uk</email> 603 </address> 604 </author> 605 <date day="1" month="April" year="1990" /> 606 <area>Internet</area> 607 <workgroup>Network Working Group</workgroup> 608 <keyword>yorkshire</keyword> 609 <keyword>memory</keyword> 610 <abstract> 611 <t>The sketch is a parody of nostalgic conversations about humble 612 beginnings or difficult childhoods, featuring four men from Yorkshire 613 who reminisce about their upbringing. As the conversation progresses 614 they try to outdo one another, and their accounts of deprived 615 childhoods become increasingly absurd. <xref target="michaelpalin" /> 616 <xref target="ericidle" /></t> 617 </abstract> 618 <note title="NOTE"> 619 <t>See also Wikipedia summary</t> 620 </note> 621 </front> 622 <middle> 623 <section anchor="michaelpalin" title="Claim: Michael Palin"> 624 <t>You were lucky. We lived for three months in a brown paper bag in a 625 septic tank. We used to have to get up at six o'clock in the morning, 626 clean the bag, eat a crust of stale bread, go to work down mill for 627 fourteen hours a day week in-week out. When we got home, out Dad would 628 thrash us to sleep with his belt! <xref target="RFC7253" /> </t> 629 <section anchor="_response_graham_chapman" 630 title="Response: Graham Chapman"> 631 <t>Luxury. We used to have to get out of the lake at three o'clock in 632 the morning, clean the lake, eat a handful of hot gravel, go to work 633 at the mill every day for tuppence a month, come home, and Dad would 634 beat us around the head and neck with a broken bottle, if we were 635 <spanx style="strong">lucky</spanx>!</t> 636 </section> 637 <section anchor="_response_terry_gilliam" title="Response: Terry Gilliam"> 638 <t>Well we had it tough. We used to have to get up out of the shoebox at 639 twelve o'clock at night, and <spanx style="strong">lick</spanx> the 640 road clean with our tongues. We had half a handful of freezing cold 641 gravel, worked twenty-four hours a day at the mill for fourpence every 642 six years, and when we got home, our Dad would slice us in two with a 643 bread knife.</t> 644 </section> 645 <section anchor="ericidle" title="Response: Eric Idle"> 646 <t>Right.</t> 647 <t>I had to get up in the morning at ten o'clock at night, half an hour 648 before I went to bed, (<spanx style="emph">pause for 649 laughter</spanx>), eat a lump of cold poison, work twenty-nine hours a 650 day down mill, and pay mill owner for permission to come to work, and 651 when we got home, our Dad would kill us, and dance about on our graves 652 singing "Hallelujah."</t> 653 </section> 654 </section> 655 </middle> 656 <back> 657 <references title="Normative References"> 658 <reference anchor="RFC7253" target="https://tools.ietf.org/html/rfc7253"> 659 <front> 660 <title>Guidelines for Writing an IANA Considerations Section in 661 RFCs 662 663 Sacramento State 664 665 666 UC Davis 667 668 669 670 671 672 673
674 But you try and tell the young people today that…​ 675 and they won't believe ya'. 676
677 678 680 4. Header And Document Attributes 682 The header gives the document title, followed by an optional author 683 attribution, and a series of document attributes, with no carriage 684 return breaks. 686 For example: 688 = Four Yorkshiremen Sketch 689 Tim Brooke-Taylor 690 :doctype: internet-draft 691 :abbrev: 4 Yorkshiremen 692 :obsoletes: 10, 120 693 :updates: 2010, 2120 694 :status: informational 695 :name: draft-four-yorkshiremen-00 696 :ipr: trust200902 697 :area: Internet 698 :workgroup: Network Working Group 699 :keyword: yorkshire, memory 700 :revdate: 1990-04-01T00:00:00Z 702 The document attributes are used to populate attributes of the root 703 "rfc" element, "front" elements, and document-level processing 704 instructions. 706 o ":doctype:" determines whether the document will be considered 707 "rfc" or "internet-draft", and interprets other attributes 708 accordingly. 710 o Certain attributes ("workgroup", "area", "keyword") are comma 711 delimited, and result in repeated RFC XML elements. 713 The foregoing AsciiRFC renders into RFC XML v3 as: 715 717 718 Four Yorkshiremen Sketch 719 721 722
723 tbt@example.com 724
725 726 727 Internet 728 Network Working Group 729 yorkshire 730 memory 732 The document header can spell out further information about authors, 733 including contact details: 735 = Four Yorkshiremen Sketch 736 Tim Brooke-Taylor 737 :doctype: internet-draft 738 :abbrev: 4 Yorkshiremen 739 :obsoletes: 10, 120 740 :updates: 2010, 2120 741 :status: informational 742 :name: draft-four-yorkshiremen-00 743 :ipr: trust200902 744 :area: Internet 745 :workgroup: Network Working Group 746 :keyword: yorkshire, memory 747 :revdate: 1990-04-01T00:00:00Z 748 :organization: BBC 749 :phone: (555) 555-5555 750 :uri: http://bbn.com 751 :street: 10 Moulton Street 752 :city: Cambridge 753 :code: MA 02238 755 757 758 Four Yorkshiremen Sketch 759 761 762 BBC 763
764 765 10 Moulton Street 766 Cambridge 767 MA 02238 768 769 (555) 555-5555 770 tbt@example.com 771 http://bbn.com 772
773 774 775 Internet 776 Network Working Group 777 yorkshire 778 memory 780 Details of a second, third etc. author, including their organization 781 and contact details, are provided by suffixing the relevant author 782 attributes with "_2", "_3" etc.: 784 = Four Yorkshiremen Sketch 785 Tim Brooke-Taylor ; John Cleese 786 :doctype: internet-draft 787 :status: informational 788 :name: draft-four-yorkshiremen-00 789 :ipr: trust200902 790 :organization: BBC 791 :phone: (555) 555-5555 792 :uri: http://example.com 793 :street: 10 Moulton Street 794 :city: Cambridge 795 :code: MA 02238 796 :forename_initials: T. 797 :lastname: Brooke-Taylor 798 :street: 12 Moulton Street 799 :city: London 800 :country: United Kingdom 801 :forename_initials_2: J. 802 :lastname_2: Cleese 803 :uri_2: https://twitter.com/johncleese 804 806 807 Four Yorkshiremen Sketch 808 810 812 BBC 813
814 815 12 Moulton Street 816 London 817 MA 02238 818 United Kingdom 819 820 (555) 555-5555 821 tbt@example.com 822 http://example.com 823
824 825 826
827 jc@example.com 828 https://twitter.com/johncleese 829
830 831 833 The initial author attribution in AsciiRFC, e.g. "Tim Brooke-Taylor 834 ; John Cleese " in the example 835 above, expects a strict format of First Name, zero or more Middle 836 Names, Last name, and cannot process honorifics like "Dr." or 837 suffixes like "Jr.". 839 Name attributes with any degree of complexity should be overriden by 840 using the ":fullname:" and ":lastname:" attributes. The AsciiRFC 841 ":forename_initials:" attribute replaces the built-in Asciidoctor 842 ":initials:" attribute (which includes the surname initial), and is 843 not automatically populated from the name attribution. 845 A document header may also contain attribute headers which are 846 treated as XML processing instructions: 848 = Four Yorkshiremen Sketch 849 Tim Brooke-Taylor 850 :doctype: internet-draft 851 :status: informational 852 :name: draft-four-yorkshiremen-00 853 :ipr: trust200902 854 :revdate: 1990-04-01T00:00:00Z 855 :rfcedstyle: yes 856 :text-list-symbols: yes 857 :rfc2629xslt: true 859 861 862 Four Yorkshiremen Sketch 863 865 866
867 tbt@example.com 868
869 870 872 A few document attributes are specific to the operation of the RFC 873 XML document converter: 875 :no-rfc-bold-bcp14: false 877 overrides the wrapping by default of boldface uppercase BCP14 878 [RFC2119] words (e.g. "*MUST NOT*") with the "bcp14" element. 880 :smart-quotes: false 882 overrides Asciidoctor's conversion of straight quotes and 883 apostrophes to smart quotes and apostrophes. 885 :inline-definition-lists: true 887 overrides the RFC XML v2 "idnits" requirement that a blank line be 888 inserted between a definition list term and its definition. 890 = Four Yorkshiremen Sketch 891 Tim Brooke-Taylor 892 :doctype: internet-draft 893 :status: informational 894 :name: draft-four-yorkshiremen-00 896 == Section 1 897 The specification *MUST NOT* use the word _doesn't_. 899 900 901 Four Yorkshiremen Sketch 902 904 905
906 tbt@example.com 907
908 909 910 911 912
913 Section 1 914 The specification MUST NOT 915 use the word doesn’t. 916
917 918 920 = Four Yorkshiremen Sketch 921 Tim Brooke-Taylor 922 :doctype: internet-draft 923 :status: informational 924 :name: draft-four-yorkshiremen-00 925 :no-rfc-bold-bcp14: false 926 :smart-quotes: false 928 == Section 1 929 The specification *MUST NOT* use the word _doesn't_. 931 932 933 Four Yorkshiremen Sketch 934 936 937
938 tbt@example.com 939
940 941 942 943 944
945 Section 1 946 The specification MUST NOT 947 use the word doesn't. 948
949 950 952 5. Preamble 954 The preamble in AsciiRFC is the text between the end of the document 955 header (which terminates with a blank line) and the first section of 956 text. 958 Any paragraphs of text in the preamble are treated as an abstract, 959 and may optionally be tagged with the "abstract" style attribute. 961 Any notes in the preamble are treated as a "note" element. 963 For example: 965 = Four Yorkshiremen Sketch 966 Tim Brooke-Taylor 967 :doctype: internet-draft 968 :status: informational 969 :name: draft-four-yorkshiremen-00 971 The "Four Yorkshiremen" sketch is a comedy sketch written by 972 Tim Brooke-Taylor, John Cleese, Graham Chapman and Marty Feldman and 973 originally performed on their TV series _At Last the 1948 Show_ in 1967. 974 It later became associated with the comedy group Monty Python 975 (which included Cleese and Chapman), who performed it in their live shows, 976 including _Monty Python Live at the Hollywood Bowl_. 978 The sketch is a parody of nostalgic conversations about humble 979 beginnings or difficult childhoods, featuring four men from Yorkshire 980 who reminisce about their upbringing. As the conversation progresses 981 they try to outdo one another, and their accounts of deprived 982 childhoods become increasingly absurd. 984 NOTE: Barry Cryer is the wine waiter in the original performance 985 and may have contributed to the writing. 987 [NOTE] 988 .Original Recording 989 ==== 990 The original performance of the sketch by the four creators is one of the 991 surviving sketches from the programme and can be seen on the 992 _At Last the 1948 Show_ DVD. 993 ==== 994 995 996 Four Yorkshiremen Sketch 997 999 1000
1001 tbt@example.com 1002
1003 1004 1005 1006 The "Four Yorkshiremen" sketch is a comedy sketch written by 1007 Tim Brooke-Taylor, John Cleese, Graham Chapman and Marty Feldman and 1008 originally performed on their TV series At Last the 1948 Show 1009 in 1967. It later became associated with the comedy group Monty Python 1010 (which included Cleese and Chapman), who performed it in their live 1011 shows, including Monty Python Live at the Hollywood Bowl. 1012 The sketch is a parody of nostalgic conversations about humble 1013 beginnings or difficult childhoods, featuring four men from Yorkshire 1014 who reminisce about their upbringing. As the conversation progresses 1015 they try to outdo one another, and their accounts of deprived childhoods 1016 become increasingly absurd. 1017 1018 1019 Barry Cryer is the wine waiter in the original performance and may 1020 have contributed to the writing. 1021 1022 1023 Original Recording 1024 The original performance of the sketch by the four creators is one of 1025 the surviving sketches from the programme and can be seen on the 1026 At Last the 1948 Show DVD. 1027 1028 1030 6. Sections and Paragraphs 1032 Section headers are given with a sequence of "=", the number of "=" 1033 giving the header level. Section numbering is toggled with the in- 1034 document attribute ":sectnums:" (on), ":sectnums!:" (off). The "toc" 1035 attribute can also be set on sections, indicating whether the section 1036 can be included in the document's table of contents. 1038 :sectnums: 1039 [toc=exclude] 1040 == Section 1 1041 Para 1 1043 === Subsection 1.1 1044 Para 1a 1046 :sectnums!: 1047 [toc=default] 1048 === Subsection 1.2 1049 Para 2 1051 ==== Subsection 1.2.1 1052 Para 3 1054
1055 Section 1 1056 Para 1 1057
1058 Subsection 1.1 1059 Para 1a 1060
1061
1062 Subsection 1.2 1063 Para 2 1064
1065 Subsection 1.2.1 1066 Para 3 1067
1068
1069
1071 7. Figures 1073 AsciiRFC examples (corresponding to RFC XML Figures), source code 1074 Listings, and Literals (preformatted text) are all delimited blocks. 1075 Listings and Literals can occur nested within Examples: 1077 .Figure 1 1078 ==== 1079 .figure1.txt 1080 .... 1081 Figures are only permitted to contain listings 1082 (sourcecode), images (artwork), or literal (artwork) 1084 This is some ASCII Art: 1086 _____ ___ ____ _ _ 1087 | ___|_ _/ ___| | ___| |_ 1088 | |_ | | | _| |/ _ \ __| 1089 | _| | | |_| | | __/ |_ 1090 |_| |___\____|_|\___|\__| 1091 .... 1093 [source,ruby] 1094 ---- 1095 def listing(node) 1096 result = [] 1097 if node.parent.context != :example 1098 result << "
" 1099 end 1100 end 1101 ---- 1102 ==== 1103
1104 Figure 1 1105 1106 Figures are only permitted to contain listings 1107 (sourcecode), images (artwork), or literal (artwork) 1109 This is some ASCII Art: 1111 _____ ___ ____ _ _ 1112 | ___|_ _/ ___| | ___| |_ 1113 | |_ | | | _| |/ _ \ __| 1114 | _| | | |_| | | __/ |_ 1115 |_| |___\____|_|\___|\__| 1116 1117 def listing(node) 1118 result = [] 1119 if node.parent.context != :example 1120 result << "<figure>" 1121 end 1122 end 1123 1124
1126 If an AsciiRFC Listing or Literal occurs outside of an Example, the 1127 RFC XML converter will supply the surrounding Figure element: 1129 .... 1130 This is some ASCII Art: 1132 _____ ___ ____ _ _ 1133 | ___|_ _/ ___| | ___| |_ 1134 | |_ | | | _| |/ _ \ __| 1135 | _| | | |_| | | __/ |_ 1136 |_| |___\____|_|\___|\__| 1137 .... 1139
1140 This is some ASCII Art: 1142 _____ ___ ____ _ _ 1143 | ___|_ _/ ___| | ___| |_ 1144 | |_ | | | _| |/ _ \ __| 1145 | _| | | |_| | | __/ |_ 1146 |_| |___\____|_|\___|\__| 1147
1149 8. Lists 1151 AsciiRFC supports ordered, unordered, and definition lists. 1152 Indentation of ordered and unordered lists is indicated by repeating 1153 the list item prefix ("*" and "." respectively.) List attributes 1154 specify the type of symbol used for ordered lists: 1156 [loweralpha] 1157 . First 1158 . Second 1159 [upperalpha] 1160 .. Third 1161 .. Fourth 1162 . Fifth 1163 . Sixth 1165
    1166
  1. First
    2. 1167
  2. 1168 Second 1169
      1170
    1. Third
      2. 1171
    2. Fourth
      3. 1172
    1173
    3. 1174
  3. Fifth
    4. 1175
  4. Sixth
    5. 1176
1178 A list item by default spans a single paragraph. A following 1179 paragraph or other block element can be appended to the current list 1180 item by prefixing it with "+" in a separate line (Asciidoctor list 1181 continuation [6].) 1183 Notes:: Note 1. 1184 + 1185 Note 2. 1186 + 1187 Note 3. 1189
1190
Notes
1191
1192 Note 1. 1193 Note 2. 1194 Note 3. 1195
1196
1197 (Multiple paragraphs are not permitted within a list item in RFC XML 1198 v2. The RFC XML converter deals with this by converting paragraph 1199 breaks into line breaks within a list item.) 1201 List continuations can also be embed to populate a list item with a 1202 sequence of blocks as a unit (in an Asciidoctor open block): 1204 * List Entry 1 1205 * List Entry 2 1206 + 1207 -- 1208 Note 2. 1210 .... 1211 Literal 1212 .... 1214 Note 3. 1215 -- 1217
    1218
  • List Entry 1
    • 1219
  • 1220 1221 List Entry 2 1222 1223 1224 Note 2. 1225 1226
    1227 1228 Literal 1229 1230
    1231 1232 Note 3. 1233 1234
    • 1235
1237 AsciiDoc, and thus AsciiRFC, considers paragraphs to be the basic 1238 level of blocks, and does not permit lists to be nested within them: 1239 text after a list is considered to be a new paragraph. So markup 1240 like the following cannot be generated via AsciiRFC: 1242 1243 This is the start of a paragraph. 1244
    1245
  • List Entry 1
    • 1246
  • 1247 List Entry 2 1248 Note 2. 1249
    • 1250
1251 And this is the continuation of the paragraph. 1252 1254 9. Blockquotes 1256 Asciidoctor supports blockquotes and quotations of verse; its block 1257 quotations permit arbitrary levels of quote nesting. RFC XML v3, and 1258 thus AsciiRFC, only supports one level of blockquotes. Unlike RFC 1259 XML v2, RFC XML v3 does not support line breaks outside of tables; so 1260 verse quotations are converted to prose in the v3 converter. 1262 [quote,attribution="Monty Python",citetitle="http://example.com"] 1263 ____ 1264 Dennis: Come and see the violence inherent in the system. 1265 Help! Help! I'm being repressed! 1267 King Arthur: Bloody peasant! 1269 Dennis: Oh, what a giveaway! 1270 * Did you hear that? 1271 * Did you hear that, eh? 1272 * That's what I'm on about! 1273 ** Did you see him repressing me? 1274 ** You saw him, Didn't you? 1275 ____ 1276
1277 Dennis: Come and see the violence inherent in the system. 1278 Help! Help! I’m being repressed! 1279 King Arthur: Bloody peasant! 1280 Dennis: Oh, what a giveaway! 1281
    1282
  • Did you hear that?
    • 1283
  • Did you hear that, eh?
    • 1284
  • 1285 That’s what I’m on about! 1286
      1287
    • Did you see him repressing me?
      • 1288
    • You saw him, Didn’t you?
      • 1289
    1290
    • 1291
1292
1294 10. Notes And Asides 1296 Asciidoctor supports a range of "admonitions", including notes, 1297 warnings, and tips. They are indicated by a paragraph prefix (e.g. 1298 "WARNING:"), or as a block with an admonition style attribute. All 1299 admonitions are conflated in AsciiRFC, being converted to "note" 1300 elements in the document preamble, and "cref" documents in the main 1301 document. 1303 == Section 1 1304 [NOTE,source=GBS] 1305 .Note Title 1306 ==== 1307 Any admonition inside the body of the text is a comment. 1308 ==== 1310
1311 Section 1 1312 1313 1314 Any admonition inside the body of the text is a comment. 1315 1316 1317
1319 Note that no inline formatting is permitted in RFC XML v2 "cref" 1320 elements, and it is stripped for v2 by the converter. 1322 Because paragraphs in AsciiRFC cannot contain any other blocks, a 1323 comment at the end of a paragraph is treated as a new block. In the 1324 document converter, any such comments are moved inside the preceding 1325 RFC XML paragraph; if the comment is at the start of a section, as in 1326 the example above, it is wrapped inside a paragraph. 1328 The RFC XML v3 converter also supports asides (Asciidoctor sidebars): 1330 == Section 1 1331 **** 1332 Sidebar 1334 Another sidebar 1336 * This is a list 1338 .... 1339 And this is ascii-art 1340 .... 1341 **** 1343
1344 Section 1 1345 1357
1359 While AsciiDoc has comments proper, notated with initial "//", they 1360 are ignored by the Asciidoctor document converter; so they will not 1361 appear as XML comments in the converter output. 1363 11. Tables 1365 AsciiRFC tables, like RFC XML v3, support distinct table heads, 1366 bodies and feet; cells spanning multiple rows and columns; and 1367 horizontal alignment. The larger range of table formatting options 1368 available in RFC XML v2 is also supported. 1370 .Table Title 1371 |=== 1372 |head | head 1374 h|header cell | body cell 1375 | | body cell 1376 2+| colspan of 2 1377 .2+|rowspan of 2 | cell 1378 |cell 1379 ^|centre aligned cell | cell 1380 <|left aligned cell | cell 1381 >|right aligned cell | cell 1383 |foot | foot 1384 |=== 1385 1386 Table Title 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431
headhead
header cellbody cell
body cell
colspan of 2
rowspan of 2cell
cell
centre aligned cellcell
left aligned cellcell
right aligned cellcell
footfoot
1432 Neither version of RFC XML is as expressive in its table structure as 1433 Asciidoctor. RFC XML, for example, does not permit blocks within 1434 table cells. 1436 12. Inline Formatting 1438 Like RFC XML v3, AsciiRFC supports italics, boldface, monospace, 1439 subscripts and superscripts: 1441 _Text_ *Text* `Text` ^Superscript^ ~Subscript~ 1443 Text Text Text 1444 Superscript Subscript 1446 RFC XML v3 also supports tagging of BCP14 keywords [RFC2119]; this is 1447 done in AsciiRFC either by tagging them with a custom formatting span 1448 ("bcp14#must not#"), or by converting BCP14 boldface all-caps words 1449 (unless the ":no-rfc-bold-bcp14: false" document attribute is set): 1451 This [bcp14]#must not# stand 1453 This *MUST NOT* stand 1455 This MUST NOT stand 1457 This MUST NOT stand 1459 Any spans of BCP14 text delimited by inline formatting delimiters 1460 needs to be contained within a single line of text; the Asciidoctor 1461 API breaks up formatting spans across line breaks. 1463 Formatting delimiters like "*" can be escaped with backslash ("\*"); 1464 double formatting delimiters, like "**" and "__", need to be escaped 1465 with double backslash ("\\**"). Escaping delimiters is not always 1466 reliable, and for double delimiters it is preferable to use HTML 1467 entities ("**"), or attribute references (references to the 1468 value of attributes set in the document header): 1470 :dblast: ** 1472 `{dblast}` 1474 In extreme circumstances (such as quoting AsciiDoc syntax), you may 1475 need to resort to altering the substitutions behaviour within a given 1476 block of of AsciiDoc; see 1479 13. Links 1481 Common URL formats are recognised automatically as hyperlinks, and 1482 are rendered as such; any hyperlinked text is appended after the 1483 hyperlink in square brackets: 1485 http://example.com/[linktext] 1487 linktext 1489 To prevent hyperlinking of a URL, prefix it with a backslash. 1491 \http://example.com/[linktext] 1493 http://example.com/[linktext] 1495 14. Crossreferences 1497 Anchors for crossreferences are notated as "[[...]]" or "[#...]". 1498 Anchors can be inserted on their own line in front of most blocks. 1499 Asciidoctor supports anchors in a much wider range of contexts than 1500 is supported than RFC XML v3 (let alone v2); anchors that are not 1501 supported for that version of RFC XML are simply ignored by the 1502 converter. Note that anchors in RFC XML are constrained to the 1503 format "[A-Za-z_:][[A-Za-z0-9_:.-]*". 1505 Cross-references to anchors are notated as "<<...>>"; cross- 1506 references with custom text as "<>". 1508 [[crossreference]] 1509 == Section 1 1511 == Section 2 1512 See <>. 1514 == Section 3 1515 See <> 1516
1517 Section 1 1518
1519
1520 Section 2 1521 1522 See 1523 1524 . 1525 1526
1527
1528 Section 3 1529 1530 See 1531 1532 text 1533 1534 1535
1537 Asciidoctor natively does not otherwise support attributes on cross- 1538 references. AsciiRFC works around that by embedding formatting 1539 information as templated text within cross-references: "format=x: 1540 text" populates the "xref@format" attribute, while a section number 1541 followed by one of the words "of, parens, bare, text" is treated as a 1542 "relref" reference to an external document. 1544 == Section 4 1545 See <> 1547 == Section 5 1548 See <> 1550 See <> 1551 <> 1552 <> 1553 <> 1554
1555 Section 4 1556 1557 See 1558 1559 text 1560 1561 1562
1563
1564 1565 Section 5 1566 1567 1568 See 1569 1570 1571 1572 See 1573 1575 1577 text 1578 1579 1581 1583 text 1584 1585 1586
1588 15. Inclusions 1590 The Asciidoctor "include" directive [7] is used to include external 1591 files in a master AsciiRFC document. The directive is capable of 1592 sophisticated document merging, including adjusting the heading 1593 levels of the included text, selecting text within specified tags or 1594 line numbers to be included, and adjusting the indentation of code 1595 snippets in merged text: 1597 include::path[ 1598 leveloffset=_offset_, 1599 lines=_ranges_, 1600 tag(s)=_name(s)_, 1601 indent=_depth_ 1602 ] 1604 If a file is included in an AsciiRFC document, ensure it ends with a 1605 blank line. An inclusion that results in its final block not being 1606 delimited with a blank line from what follows can lead to 1607 unpredictable results. 1609 16. Encoding and Entities 1611 XML accepts the full range of characters in the world's languages 1612 through UTF-8 character encoding, and one of the motivations for the 1613 move from plain text to RFC XML has been to allow non-ASCII 1614 characters to be included in RFCs. However, current RFC XML v2 tools 1615 still do not support UTF-8, and other tool support for UTF-8 also 1616 remains patchy. Out of an abundance of caution, the RFC XML 1617 converter uses US-ASCII for its character encoding, and renders any 1618 non-ASCII characters as entities. 1620 The converter accepts HTML entities in AsciiRFC, even though they are 1621 not part of the XML specification; HTML entities such as " " 1622 feature in examples of RFC XML provided by the IETF. In order to 1623 prevent dependence of the XML output from extraneous entity 1624 definitions, any such entities are rendered in the XML as decimal 1625 character entities. 1627 Это 1628 Русский 1629 Язык. 1630 — This is not George's.† 1632 Это 1633 Русский 1634 Язык. — 1635 This is not George's.† 1637 17. Bibliography 1639 Asciidoctor natively has a simple encoding of bibliographies, which 1640 is not adequate for the complexity of bibliographic markup required 1641 by RFC XML. RFC documents overwhelmingly cite other RFC documents, 1642 and canonical RFC XML bibliographic entries are available at 1643 ; so it would be 1644 inefficient to encode those entries in AsciiRFC, only to have them 1645 converted back to RFC XML. 1647 The converter provides two means of incorporating bibliographies into 1648 RFC documents authored in AsciiRFC: 1650 o using raw RFC XML; and 1652 o assembling bibliographies in preprocessing. 1654 In either case, the RFC XML needs to be well-formed; missing closing 1655 tags can lead to erratic behaviour in the converter. 1657 17.1. Using Raw RFC XML 1659 In the first method, bibliographic citations are handled like all 1660 other AsciiRFC cross-references. The bibliographic entries for 1661 normative and informative references are given in the AsciiRFC as 1662 passthrough blocks, which contain the raw RFC XML for all references; 1663 document conversion leaves the raw RFC XML in place. This approach 1664 requires authors to maintain the normative and informative 1665 bibliographies within the document, to update them as citations are 1666 added and removed, and to sort them manually. For example: 1668 Some datagram padding may be needed.<> 1670 [bibliography] 1671 == Normative References 1672 ++++ 1673 1675 1676 Guidelines for Writing an IANA Considerations 1677 Section in RFCs 1678 1679 Sacramento State 1680 1681 1682 UC Davis 1683 1684 1685 1686 1687 1688 ++++ 1690 Some datagram padding may be needed 1692 1693 1694 Normative References 1695 1697 1698 Guidelines for Writing an IANA Considerations 1699 Section in RFCs 1700 Sacramento State 1701 1702 1703 UC Davis 1704 1705 1706 1707 1708 1709 1711 17.2. Using preprocessing 1713 The alternative method is to use a preprocessing tool, asciidoc- 1714 bibliography [8], to import citations into the AsciiRFC document from 1715 an external file of references. 1717 The references file consists of RFC XML reference entries, and still 1718 needs to be managed manually; however the bibliographies are 1719 assembled from that file, sorted, and inserted into the normative and 1720 informative references in preprocessing. Citations in the document 1721 itself are given as macros to be interpreted by the preprocessor; 1722 this allows them to be split into normative and informative 1723 references. (The MMark tool likewise splits reference citations into 1724 normative and informative.) 1726 Integration with the asciidoc-bibliography gem proceeds as follows: 1728 1. Create an RFC XML references file, consisting of a "" 1729 element with individual "" elements inserted, as would 1730 be done for the informative and normative references normally. 1731 The references file will contain all possible references to be 1732 used in the file; the bibliography gem will select which 1733 references have actually been cited in the document. 1735 A. Rather than hand crafting RFC XML references for RFC 1736 documents, you should download them from an authoritative 1737 source; e.g. 1740 B. Unlike the case for RFC XML documents created manually, the 1741 references file does not recognise XML entities and will not 1742 attempt to download them during processing. Any references 1743 to will need to 1744 be downloaded and inserted into the references file. 1746 C. The RFC XML in the references file will need to be 1747 appropriate to the version of RFC XML used in the main 1748 document, as usual. Note that RFC XML v2 references are 1749 forward compatible with v3; v3 contains a couple of 1750 additional elements. 1752 2. Add to the main document header attributes referencing the 1753 references file (":bibliography-database:"), and the bibliography 1754 style (":bibliography-style:rfc-v3"). 1756 3. References to a normative reference are inserted with the macro 1757 "cite:norm[id]" instead of "<>", where "id" is the anchor of 1758 the reference. 1760 4. References to an infomrative reference are inserted with the 1761 macro "cite:info[id]" instead of "<>", where "id" is the 1762 anchor of the reference. 1764 5. Formatted crossreferences and "relref" crossreferences are 1765 entered by inserting the expected raw XML in the "text" 1766 attribute. Do not use the "{cite}" interpolation of the 1767 citation. For example: 1769 * "<>" = "cite:norm[id, text="words"]" 1772 * "<>" (processed as a formatted 1773 crossreference) = "cite:norm[id, text="words"]" 1776 * "<>" (processed as relref) = 1777 "cite:norm[id, text=""]" 1780 * "<>" (processed as relref with 1781 a cross-document internal reference) = "cite:norm[id, 1782 text=""]" 1785 6. Normative and Informative References are inserted in the document 1786 through a macro, which occurs where the RFC XML references would 1787 be inserted: 1789 [bibliography] 1790 == Normative References 1792 ++++ 1793 bibliography::norm[] 1794 ++++ 1796 [bibliography] 1797 == Informative References 1799 ++++ 1800 bibliography::info[] 1801 ++++ 1803 18. RFC XML features not supported in Asciidoctor 1805 The following features of RFC XML are not supported by the AsciiRFC 1806 converter, and would need to be adjusted manually after RFC XML is 1807 generated: 1809 +------------------------+--------------------+---------------------+ 1810 | RFC XML element | RFC XML v3 | RFC XML v2 | 1811 +------------------------+--------------------+---------------------+ 1812 | "front/boilerplate" | Not added by the | Not added by the | 1813 | | converter | converter | 1814 | "iref@primary" | N | N | 1815 | "reference" (and all | As Raw XML | As Raw XML | 1816 | children) | | | 1817 | "table/preamble" | Deprecated | N | 1818 | "table/postamble" | Deprecated | N | 1819 | "artwork@width" | Only on images | Only on images | 1820 | "artwork@height" | Only on images | Only on images | 1821 +------------------------+--------------------+---------------------+ 1823 19. Authoring 1825 To author an AsciiRFC document, you should familiarise yourself with 1826 the Asciidoctor specification [9]. The converter Ruby gem source 1827 code distribution also has samples of individual RFC XML features 1828 [10], in v2 and v3, and examples of self-standing AsciiRFC documents 1829 [11], along with their RFC XML renderings. (This includes round- 1830 tripped RFC XML documents.) 1831 In addition, you can clone the sample "rfc-in-asciidoc-template" 1832 repository as a template, and populate it for your AsciiRFC 1833 documents: 1835 $ git clone https://github.com/riboseinc/rfc-in-asciidoc-template 1837 Converting your AsciiRFC to RFC XML is a simple as installing 1838 Asciidoctor (see ) and the 1839 "asciidoctor-rfc" gem in Ruby, then running the asciidoctor 1840 executable on the document, specifying the asciidoctor-rfc gem as a 1841 library: 1843 $ git clone https://github.com/riboseinc/asciidoctor-rfc 1844 $ cd asciidoctor-rfc 1845 $ bundle install 1846 $ gem build asciidoctor-rfc.gemspec 1847 $ gem install asciidoctor-rfc 1848 $ asciidoctor -b rfc3 -r 'asciidoctor-rfc' a.adoc # RFC XML v3 output 1849 $ asciidoctor -b rfc2 -r 'asciidoctor-rfc' a.adoc # RFC XML v2 output 1851 As you author AsciiRFC content, you should iterate through running 1852 the Asciidoctor conversion frequently, to ensure that you are still 1853 generating valid XML through your markup. The converter makes an 1854 effort to ensure that its XML output is valid, and it issues warnings 1855 about likely issues; it also validates its own XML output against the 1856 Asciidoctor schema, and reports errors in the XML output in the 1857 following format: 1859 V3 RELAXNG Validation: 12:0: ERROR: Invalid attribute 1860 sortRefs for element rfc 1862 Note that validation against the RELAXNG RFC XML schema includes 1863 confirming the referential integrity of all cross-references in the 1864 document. 1866 It may be necessary to intervene in the XML output generated by the 1867 converter, either because the block model of AsciiRFC does not 1868 conform with the intended RFC XML (e.g. lists embedded in 1869 paragraphs), or because RFC XML features are required that are not 1870 supported within AsciiRFC. 1872 20. Security Considerations 1874 o Ensure your AsciiRFC generator comes from a geniune and 1875 trustworthy source. This protects your own machine and also 1876 prevents injection of malicious content in your document. 1878 o An AsciiRFC generator may cause errors in textual rendering or 1879 link generation that may lead to security issues. 1881 o Creating cross-references (and also bibliographic references) to 1882 external documents may pose risks since the external document's 1883 location may become controlled by a malicious party. 1885 21. IANA Considerations 1887 This document does not require any action by IANA. 1889 22. Examples 1891 22.1. Example 1 1893 TODO. 1895 23. References 1897 23.1. Normative References 1899 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1900 Requirement Levels", BCP 14, RFC 2119, 1901 DOI 10.17487/RFC2119, March 1997, 1902 . 1904 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 1905 RFC 7991, DOI 10.17487/RFC7991, December 2016, 1906 . 1908 23.2. Informative References 1910 [AsciiDoc] 1911 Rackham, S., "AsciiDoc: Text based document generation", 1912 November 2013, . 1914 [Asciidoctor] 1915 Allen, D., Waldron, R., and S. White, "Asciidoctor: A fast 1916 text processor & publishing toolchain for converting 1917 AsciiDoc to HTML5, DocBook & more.", November 2017, 1918 . 1920 [draftr] Barnes, R., "draftr: an HTML front-end to pandoc2rfc", Nov 1921 2017, . 1923 [kramdown-rfc2629] 1924 Bormann, C., "kramdown-rfc2629: An RFC2629 (XML2RFC) 1925 backend for Thomas Leitner's kramdown markdown parser", 1926 Nov 2017, . 1928 [lyx2rfc] Williams, N., "LyX to I-D/RFC export by way of Lyx export 1929 to XHTML and XSLT conversion to xml2rfc schema", 2014, 1930 . 1932 [mmark] Gieben, R., "Using mmark to create I-Ds and RFCs", June 1933 2015, . 1935 [NroffEdit] 1936 Santesson, S., "WYSIWYG Internet-Draft Nroff Editor", May 1937 2011, . 1939 [pandoc2rfc] 1940 Gieben, R., "pandoc2rfc: Use pandoc to create XML suitable 1941 for xml2rfc", 2012, . 1943 [RFC5385] Touch, J., "Version 2.0 Microsoft Word Template for 1944 Creating Internet Drafts and RFCs", RFC 5385, 1945 DOI 10.17487/RFC5385, February 2010, 1946 . 1948 [RFC7328] Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit 1949 of XML", RFC 7328, DOI 10.17487/RFC7328, August 2014, 1950 . 1952 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 1953 RFC 7749, DOI 10.17487/RFC7749, February 2016, 1954 . 1956 [RFC7763] Leonard, S., "The text/markdown Media Type", RFC 7763, 1957 DOI 10.17487/RFC7763, March 2016, 1958 . 1960 [RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies, 1961 Stability Strategies, and Select Registrations", RFC 7764, 1962 DOI 10.17487/RFC7764, March 2016, 1963 . 1965 [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990, 1966 DOI 10.17487/RFC7990, December 2016, 1967 . 1969 23.3. URIs 1971 [1] http://asciidoctor.org/docs/user-manual/#compared-to-markdown 1973 [2] http://asciidoctor.org/docs/user-manual/#compared-to-markdown 1975 [3] http://docs.mathjax.org/en/latest/asciimath.html 1977 [4] http://docs.mathjax.org/en/latest/tex.html 1979 [5] https://www.mathjax.org 1981 [6] http://asciidoctor.org/docs/user-manual/#complex-list-content 1983 [7] http://asciidoctor.org/docs/user-manual/#include-directive 1985 [8] https://github.com/riboseinc/asciidoctor-bibliography 1987 [9] http://asciidoctor.org/docs/user-manual 1989 [10] https://github.com/riboseinc/asciidoctor- 1990 rfc/tree/master/spec/asciidoctor/rfc 1992 [11] https://github.com/riboseinc/asciidoctor-rfc/tree/master/spec/ 1993 examples 1995 Appendix A. Acknowledgements 1997 The authors would like to thank the following persons for their 1998 valuable advice and input. 2000 o TODO. 2002 Authors' Addresses 2004 Ronald Henry Tse 2005 Ribose 2006 Suite 1111, 1 Pedder Street 2007 Central, Hong Kong 2008 Hong Kong 2010 Email: ronald.tse@ribose.com 2011 URI: https://www.ribose.com 2012 Nick Nicholas 2013 Ribose 2014 Australia 2016 Email: nick.nicholas@ribose.com 2017 URI: https://www.ribose.com 2019 Jeffrey Lau 2020 Ribose 2021 Suite 1111, 1 Pedder Street 2022 Central, Hong Kong 2023 Hong Kong 2025 Email: jeffrey.lau@ribose.com 2026 URI: https://www.ribose.com 2028 Paolo Brasolin 2029 Ribose 2030 Italy 2032 Email: paolo.brasolin@ribose.com 2033 URI: https://www.ribose.com