idnits 2.17.1 draft-ribose-asciirfc-00.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 (November 20, 2017) is 2348 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '1' on line 1289 -- Looks like a reference, but probably isn't: '2' on line 1291 -- Looks like a reference, but probably isn't: '3' on line 1293 -- Looks like a reference, but probably isn't: '4' on line 1295 -- Looks like a reference, but probably isn't: '5' on line 1297 -- Looks like a reference, but probably isn't: '6' on line 1299 -- Looks like a reference, but probably isn't: '7' on line 1301 -- Looks like a reference, but probably isn't: '8' on line 1303 -- Looks like a reference, but probably isn't: '9' on line 1305 == Missing Reference: 'NOTE' is mentioned on line 437, but not defined -- Looks like a reference, but probably isn't: '10' on line 1307 -- Looks like a reference, but probably isn't: '11' on line 1309 -- Looks like a reference, but probably isn't: '12' on line 1311 -- Looks like a reference, but probably isn't: '13' on line 1313 -- Looks like a reference, but probably isn't: '14' on line 1315 -- Looks like a reference, but probably isn't: '15' on line 1318 == Unused Reference: 'RFC5385' is defined on line 1265, but no explicit reference was found in the text == Unused Reference: 'RFC7328' is defined on line 1270, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7749 (Obsoleted by RFC 7991) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 16 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 24, 2018 P. Brasolin 6 Ribose 7 November 20, 2017 9 Writing Internet-Drafts And RFCs In AsciiDoc (AsciiRFC) 10 draft-ribose-asciirfc-00 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 24, 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 . . . . . . . . . . . . . . 4 66 2.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. Document Structure And AsciiDoctor Syntax . . . . . . . . . . 4 68 4. Header And Document Attributes . . . . . . . . . . . . . . . 6 69 5. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 6. Sections and Paragraphs . . . . . . . . . . . . . . . . . . . 11 71 7. Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 72 8. Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 73 9. Blockquotes . . . . . . . . . . . . . . . . . . . . . . . . . 15 74 10. Notes And Asides . . . . . . . . . . . . . . . . . . . . . . 16 75 11. Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 76 12. Inline Formatting . . . . . . . . . . . . . . . . . . . . . . 20 77 13. Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 78 14. Crossreferences . . . . . . . . . . . . . . . . . . . . . . . 21 79 15. Inclusions . . . . . . . . . . . . . . . . . . . . . . . . . 23 80 16. Encoding and Entities . . . . . . . . . . . . . . . . . . . . 23 81 17. Bibliography . . . . . . . . . . . . . . . . . . . . . . . . 23 82 17.1. Using Raw RFC XML . . . . . . . . . . . . . . . . . . . 24 83 17.2. Using preprocessing . . . . . . . . . . . . . . . . . . 25 84 18. RFC XML features not supported in Asciidoctor . . . . . . . . 27 85 19. Authoring . . . . . . . . . . . . . . . . . . . . . . . . . . 27 86 20. Security Considerations . . . . . . . . . . . . . . . . . . . 28 87 21. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 88 22. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 29 89 22.1. Example 1 . . . . . . . . . . . . . . . . . . . . . . . 29 90 23. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 91 23.1. Normative References . . . . . . . . . . . . . . . . . . 29 92 23.2. Informative References . . . . . . . . . . . . . . . . . 29 93 23.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 30 94 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 30 95 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30 97 1. Introduction 99 As specified in [RFC7990], the IETF intends for the canonical format 100 of RFCs to transition from plain-text ASCII to RFC XML v3 [RFC7991]. 101 While plain-text will continue to be accepted from authors by the 102 IETF, at least in the short- to medium-term, XML will be preferred 103 for submission, and any plain-text submissions will need to be 104 converted to RFC XML v3. 106 The transition to RFC XML v3 places added onus on authors to generate 107 compliant XML. This need is already met for RFC XML v2 [RFC7749] by 108 tools such as MMark [1] and Kramdown [2], both based on the popular 109 Markdown markup language [3] [RFC7763] [RFC7764]. 111 Asciidoctor [4] is an alternative markup language to Markdown, with 112 features that make it attractive as a markup language for RFC with 113 XML output. 115 Compared to Markdown [5], 117 o Asciidoctor was designed from the beginning as a publishing 118 language: it was initially intended as a plain-text alternative to 119 the DocBook XML schema. For that reason, Asciidoctor natively 120 supports the full range of formatting required by RFC XML 121 (including notes, tables, bibliographies, source-code blocks, and 122 definition lists), without resorting to embedded HTML or Markdown 123 "flavours". 125 o Asciidoctor is extensible, with a well-defined API. 127 o Asciidoctor allows granular control of rendering, including user- 128 specified attribute of text blocks. 130 o Asciidoctor allows document inclusion, for managing large-scale 131 documentation projects. 133 o Asciidoctor allows granular control of permutations of block 134 nesting, such as source code within lists or definition lists 135 within unordered lists. 137 o As a more formal counterpart to Markdown, Asciidoctor is well- 138 suited to generating XML that needs to conform to a specified 139 schema. 141 Section 1.2 of [RFC7764] famously states that "there is no such thing 142 as "invalid" Markdown, there is no standard demanding adherence to 143 the Markdown syntax, and there is no governing body that guides or 144 impedes its development." While there are contexts where that lack 145 of rigour is helpful, the authoring of RFCs does have a standard and 146 a governing body, and there is such a thing as invalid RFC XML. A 147 more rigorous counterpart to Markdown, which still preserves its 148 basic approach to formatting, is useful in generating RFC XML that 149 encompasses a fuller subset of the specification, and preempting 150 malformed RFC XML output. 152 As with Markdown, there is a wide range of tools that can render 153 Asciidoctor; so Asciidoctor drafts of RFC documents can be previewed 154 and accessed without depending on the RFC tools ecosystem. Our 155 porting of RFC XML to Asciidoctor has aimed to ensure that, as much 156 as possible, the Asciidoctor being used for RFC is generic 157 Asciidoctor, which can be processed by Asciidoctor tools in general. 158 (The only exception to this as an add-on is the optional bibliography 159 module, which allows bibliographies to be assembled on the fly based 160 on citations in a document.) 162 2. Conventions Used in This Document 164 The key words "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", 165 "*SHALL NOT*", "*SHOULD*", "*SHOULD NOT*", "*RECOMMENDED*", "*MAY*", 166 and "*OPTIONAL*" in this document are to be interpreted as described 167 in [RFC2119]. 169 2.1. Definitions 171 TODO. 173 3. Document Structure And AsciiDoctor Syntax 175 The syntax of Asciidoctor is presented in the Asciidoctor user manual 176 [6]. 178 Asciidoctor consists of: 180 o A document header, containing a title, a list of authors, and 181 document attributes in lines prefixed with ":" 183 o An optional document preamble, separated from document header by a 184 blank line 186 o A number of sections, set off by a section title (a line prefixed 187 with two or more "=". A section may contain: 189 * Other sections, whose level of nesting is indicated by the 190 number of "=" in their header 192 * Blocks of text. Blocks can have metadata (including a title, 193 an anchor for cross-references, and attributes.) Blocks can 194 be: 196 + Paragraphs, which are terminated by blank lines. 198 + Lists. List items are by default paragraphs, but can span 199 over multiple paragraphs. 201 + Delimited blocks (with a line delimiter on either side of 202 them); these include tables, notes, sidebars, source code, 203 block quotes, examples, and unprocessed content (e.g. raw 204 XML). Delimited blocks contain by default one or more 205 paragraphs. 207 + List items can contain other blocks, including both nested 208 lists and delimited blocks. 210 + Some delimited blocks can contain other delimited blocks; 211 for example, examples can contain source code as well as 212 discussion in paragraphs. 214 * Blocks of text consist of inline text, which themselves can 215 contain markup. 217 Inline markup includes: 219 o Text formatting: bold, italic, superscript, subscript, monospace 221 o Custom markup macros 223 o URLs, including display text 225 o Inline anchors 227 o Cross-references to anchors (IDs of blocks or spans of text), 228 including display text 230 o Images, audio, and visual files 232 o Index terms 234 o Equations (native support for AsciiMathML [7] and TeX/LaTeX [8], 235 via the MathJax [9] tool 237 o Footnotes 238 The Asciidoctor document structure aligns with the RFC XML v2 and v3 239 structure. In the following, v3 equivalences are given: 241 o Header: "" attributes, most "front" elements 243 o Preamble: "front/abstract" and "front/note" 245 o Sections: "middle/section" elements 247 o Sections with "bibliography" style attributes: "back/references" 248 elements. 250 o Sections with "appendix" style attributes: "back/section" 251 elements. 253 o Paragraphs: "t" elements 255 o Lists: "ul", "ol", "dl" elements 257 o Delimited blocks: "artwork", "aside", "blockquote", "figure", 258 "note", "sourcecode", "table" 260 o Inline markup: "bcp14", "br", "cref", "em", "eref", "iref", 261 "relref", "strong", "sub", "sup", "tt", "xref" 263 Full details of the mapping of Asciidoctor elements to RFC XML v2 and 264 v3 elements, and of how to convert Asciidoctor documents to RFC XML, 265 are given in . The following gives an overview of how 267 to create an RFC XML document in Asciidoctor, with some pitfalls to 268 be aware of. Illustrations are in RFC XML v3, although the converter 269 deals with both versions of RFC XML. 271 4. Header And Document Attributes 273 The header gives the document title, followed by an optional author 274 attribution, and a series of document attributes, with no carriage 275 return breaks. 277 For example: 279 = Transmission of IP Datagrams on Avian Carriers 280 David Waitzman 281 :doctype: internet-draft 282 :abbrev: IP Datagrams on Avian Carriers 283 :obsoletes: 10, 120 284 :updates: 2010, 2120 285 :status: informational 286 :name: internet-draft-avian-transmission-00 287 :ipr: trust200902 288 :area: Internet 289 :workgroup: Network Working Group 290 :keyword: avians, datagrams 291 :revdate: 1990-04-01T00:00:00Z 292 :organization: BBN STC 293 :phone: (617) 873-4323 294 :uri: http://bbn.com 295 :street: 10 Moulton Street 296 :city: Cambridge 297 :code: MA 02238 298 :rfcedstyle: yes 299 :text-list-symbols: yes 300 :rfc2629xslt: true 302 The document attributes are used to populate "rfc" attributes, 303 "front" elements, and document-level processing instructions. 305 o ":doctype:" determines whether the document will be considered 306 "rfc" or "internet-draft", and interprets other attributes 307 accordingly. 309 o Certain attributes ("workgroup", "area", "keyword") are comma 310 delimited, and result in repeated RFC XML elements. 312 o A few attributes are specific to the operation of the RFC XML 313 document converter: 315 * ":no-rfc-bold-bcp14: false" overrides the conversion of 316 boldface uppercase BCP14 [RFC2119] words with the "bcp14" 317 element. 319 * ":smart-quotes false:" overrides Asciidoctor's conversion of 320 straight quotes and apostrophes to smart quotes and 321 apostrophes. 323 * ":inline-definition-lists: true" overrides the RFC XML v2 324 "idnits" requirement that a blank line be inserted between a 325 definition list term and its definition. 327 The foregoing Asciidoc renders into RFC XML v3 as: 329 330 331 332 333 334 335 336 337 338 339 340 341 343 344 345 A Standard for the Transmission of IP 346 Datagrams on Avian Carriers 347 348 350 351 BBN STC 352
353 354 10 Moulton Street 355 Cambridge 356 MA 02238 357 358 (617) 873-4323 359 dwaitzman@BBN.COM 360 http://bbn.com 361
362 363 364 Internet 365 Network Working Group 366 avians 367 datagrams 369 Details of a second, third etc. author, including their organization 370 and contact details, are provided by suffixing the author attribute 371 with "_2", "_3" etc.: 373 John Doe Horton ; 374 Billy Bob Thornton 375 :fullname: John Doe Horton 376 :lastname: Horton 377 :forename_initials: J. D. 378 :role: editor 379 :organization: Ribose 380 :fax: 555 5555 381 :email: john.doe@email.com 382 :uri: http://example.com 383 :phone: 555 5655 384 :street: 57 Mt Pleasant St 385 :city: Dullsville 386 :region: NSW 387 :country: Australia 388 :code: 3333 389 :fullname_2: Billy Bob Thornton 390 :lastname_2: Thornton 391 :forename_initials_2: B. B. 392 :role_2: editor 393 :organization_2: IBM 394 :fax_2: 555 6666 395 :email_2: billy.thornton@email.com 396 :uri_2: http://ibm.com 397 :phone_2: 555 6655 398 :street_2: 67 Mt Pleasant St 399 :city_2: Dulltown 400 :region_2: VIC 401 :country_2: UK 402 :code_2: 44444 404 The initial author attribution in Asciidoctor, e.g. "John Doe 405 Horton; Billy Bob Thornton 406 " in the example above, expects a strict 407 format of First Name, zero or more Middle Names, Last name, and 408 cannot process honorifics like "Dr" or suffixes like "Jr". Name 409 attributes with any degree of complexity should be overriden by using 410 the ":fullname:" and ":lastname:" attributes. The 411 ":forename_initials:" replaces the built-in ":initials:" attribute 412 (which includes the surname initial), and is not automatically 413 populated from the name attribution. 415 5. Preamble 417 The preamble in Asciidoctor is the text between the end of the 418 document header (which terminates with a blank line) and the first 419 section of text. Any paragraphs of text in the preamble are treated 420 as an abstract, and may optionally be tagged with the "abstract" 421 style attribute. Any notes in the preamble are treated as a "note" 422 element. For example: 424 = A Standard for the Transmission of IP Datagrams on Avian Carriers 425 David Waitzman 426 :doctype: internet-draft 427 :abbrev: IP Datagrams on Avian Carriers 428 :status: informational 429 :name: internet-draft-avian-transmission-00 431 Preamble content. 433 More Preamble content. 435 NOTE: This is a note. 437 [NOTE] 438 .Title of Note 439 ==== 440 This is another note. 441 ==== 443 444 445 446 A Standard for the Transmission of IP Datagrams on Avian Carriers 447 448 450 451
452 dwaitzman@BBN.COM 453
454 455 457 Preamble content. 458 More Preamble content. 459 460 461 This is a note. 462 463 464 Title of Note 465 This is another note. 466 467 468 6. Sections and Paragraphs 470 Section headers are given with a sequence of "=", the number of "=" 471 giving the header level. Section numbering is toggled with the in- 472 document attribute ":sectnums:" (on), ":sectnums!:" (off) 474 :sectnums: 475 [toc=exclude] 476 == Section 1 477 Para 1 479 === Subsection 1.1 480 Para 1a 482 :sectnums!: 483 [toc=default] 485 === Subsection 1.2 486 Para 2 488 ==== Subsection 1.2.1 489 Para 3 491
492 Section 1 493 Para 1 494
495 Subsection 1.1 496 Para 1a 497
498
499 Subsection 1.2 500 Para 2 501
502 Subsection 1.2.1 503 Para 3 504
505
506
508 7. Figures 510 AsciiDoc Examples (corresponding to RFC XML figures), source code 511 listings, and literals (preformatted text) are all delimited blocks. 512 Listings and literals can occur nested within examples. If an 513 Asciidoctor listing or literal occurs outside of an example, the RFC 514 XML converter will supply the surrounding figure element: 516 .Figure 1 517 ==== 518 .figure1.txt 519 .... 520 Figures are only permitted to contain listings 521 (sourcecode), images (artwork), or literal (artwork) 522 .... 524 [source,ruby] 525 ---- 526 def listing(node) 527 result = [] 528 if node.parent.context != :example 529 result << "
" 530 end 531 end 532 ---- 533 ==== 535
536 Figure 1 537 538 Figures are only permitted to contain listings 539 (sourcecode), images (artwork), or literal (artwork) 540 541 542 def listing(node) 543 result = [] 544 if node.parent.context != :example 545 result << "<figure>" 546 end 547 end 548 549
551 8. Lists 553 Asciidoctor supports ordered, unordered, and definition lists. 554 Indentation of ordered and unordered lists is indicated by repeating 555 the list item prefix ("*" and "." respectively.) List attributes 556 specify the type of symbol used for ordered lists: 558 [loweralpha] 559 . First 560 . Second 561 [upperalpha] 562 .. Third 563 .. Fourth 564 . Fifth 565 . Sixth 567
    568
  1. First
    2. 569
  2. 570 Second 571
      572
    1. Third
      2. 573
    2. Fourth
      3. 574
    575
    3. 576
  3. Fifth
    4. 577
  4. Sixth
    5. 578
580 A list item by default spans a single paragraph. A following 581 paragraph or other block element can be appended to the current list 582 item by prefixing it with "+" in a separate line (Asciidoc list 583 continuation [10].) 585 Notes:: Note 1. 586 + 587 Note 2. 588 + 589 Note 3. 591
592
Notes
593
594 Note 1. 595 Note 2. 596 Note 3. 597
598
600 List continuations can also be embed to populate a list item with a 601 sequence of blocks as a unit (in an Asciidoc open block): 603 * List Entry 1 604 * List Entry 2 605 + 606 -- 607 Note 2. 609 .... 610 Literal 611 .... 613 Note 3. 614 -- 616
    617
  • List Entry 1
    • 618
  • 619 620 List Entry 2 621 622 623 Note 2. 624 625
    626 627 Literal 628 629
    630 631 Note 3. 632 633
    • 634
636 Asciidoctor considers paragraphs to be the basic level of blocks, and 637 does not permit lists to be nested within them: text after a list is 638 considered to be a new paragraph. So markup like the following 639 cannot be generated via Asciidoctor: 641 642 This is the start of a paragraph. 643
    644
  • List Entry 1
    • 645
  • 646 List Entry 2 647 Note 2. 648
    649 650 Literal 651 652
    653 Note 3. 654
    • 655
657 9. Blockquotes 659 Asciidoctor supports blockquotes and quotations of verse; its block 660 quotations permit arbitrary levels of quote nesting. RFC XML v3 only 661 supports one level of blockquotes. RFC XML v3 does not support line 662 breaks outside of tables, so verse quotations are converted to prose. 664 [quote,attribution="Monty Python",citetitle="http://foo.bar"] 665 ____ 666 Dennis: Come and see the violence inherent in the system. 667 Help! Help! I'm being repressed! 669 King Arthur: Bloody peasant! 671 Dennis: Oh, what a giveaway! 672 * Did you hear that? 673 * Did you hear that, eh? 674 * That's what I'm on about! 675 ** Did you see him repressing me? 676 ** You saw him, Didn't you? 677 ____ 678
679 Dennis: Come and see the violence inherent in the system. 680 Help! Help! I’m being repressed! 681 King Arthur: Bloody peasant! 682 Dennis: Oh, what a giveaway! 683
    684
  • Did you hear that?
    • 685
  • Did you hear that, eh?
    • 686
  • 687 That’s what I’m on about! 688
      689
    • Did you see him repressing me?
      • 690
    • You saw him, Didn’t you?
      • 691
    692
    • 693
694
696 10. Notes And Asides 698 Asciidoctor supports a range of "admonitions", including notes, 699 warnings, and tips. They are indicated by a paragraph prefix (e.g. 700 "WARNING:"), or as a block with an admonition style attribute. All 701 admonitions are converted to "note" elements in the document 702 preamble, and "cref" documents in the main document. RFC XML v3 also 703 supports asides (Asciidoctor sidebars): 705 == Section 1 706 [NOTE,source=GBS] 707 .Note Title 708 ==== 709 Any admonition inside the body of the text is a comment. 710 ==== 712 **** 713 Sidebar 715 Another sidebar 717 * This is a list 719 .... 720 And this is ascii-art 721 .... 722 **** 723
724 Section 1 725 726 727 Any admonition inside the body of the text is a comment. 728 729 730 743 Note that no inline formatting is permitted in RFC XML v2, and it is 744 stripped for v2 by the converter. 746 Because paragraphs in Asciidoctor cannot contain any other blocks, a 747 comment at the end of a paragraph is treated as a new block. In the 748 document converter, any such comments are moved inside the preceding 749 RFC XML paragraph; if the comment is at the start of a section, as in 750 the example above, it is wrapped inside a paragraph. 752 While Asciidoctor has comments proper, notated with initial "//", 753 they are ignore by the document converter, so they will not appear as 754 XML comments in the converter output. 756 11. Tables 758 Asciidoctor tables, like RFC XML v3, support distinct table heads, 759 bodies and feet, cells spanning multiple rows and columns, and 760 horizontal alignment. The larger range of formatting options 761 available in RFC XML v2 is also supported. 763 .Table Title 764 |=== 765 |head | head 767 h|header cell | body cell 768 | | body cell 769 2+| colspan of 2 770 .2+|rowspan of 2 | cell 771 |cell 772 ^|centre aligned cell | cell 773 <|left aligned cell | cell 774 >|right aligned cell | cell 776 |foot | foot 777 |=== 778 779 Table Title 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824
headhead
header cellbody cell
body cell
colspan of 2
rowspan of 2cell
cell
centre aligned cellcell
left aligned cellcell
right aligned cellcell
footfoot
825 Neither version of RFC XML is as expressive in its table structure as 826 Asciidoctor; RFC XML for example does not permit blocks within table 827 cells. 829 12. Inline Formatting 831 Like RFC XML v3, Asciidoctor supports italics, boldface, monospace, 832 subscripts and superscripts: 834 _Text_ *Text* `Text` ^Superscript^ ~Subscript~ 836 Text Text Text 837 Superscript Subscript 839 RFC XML v3 also supports tagging of BCP14 keywords [RFC2119]; this is 840 done in Asciidoctor either by tagging them with a custom formatting 841 span ("bcp14#mustnot#"), or by converting by default BCP14 boldface 842 all-caps words: 844 This [bcp14]#must not# stand 846 This *MUST NOT* stand 848 This MUST NOT stand 850 This MUST NOT stand 852 Any spans of BCP14 text delimited by inline formatting delimiters 853 needs to be contained within a single line of text; the Asciidoctor 854 API breaks up formatting spans across line breaks. 856 Formatting delimiters like "*" can be escaped with backslash; double 857 formatting delimiters, like "" and "__", need 858 to be escaped with double backslash("\\"). Escaping 859 delimiters is not always reliable, and for double delimiters it is 860 preferable to use HTML entities ("**"), or attribute 861 references: 863 :dblast: ** 865 `{dblast}` 867 13. Links 869 Common URL formats are recognised automatically as hyperlinks, and 870 are rendered as such; any hyperlinked text is appended after the 871 hyperlink in square brackets: 873 http://example.com/[linktext] 875 linktext 877 To prevent hyperlinking of a URL, prefix it with a backslash. 879 14. Crossreferences 881 Anchors for crossreferences are notated as "[[...]]" or "[#...]". 882 Anchors can be inserted on their own line in front of most blocks. 883 Asciidoctor supports anchors in a much wider range of contexts than 884 is supported than RFC XML v3 (let alone v2); anchors that are not 885 supported for that version of RFC XML are simply ignored by the 886 converter. Note that anchors in RFC XML are constrained to the 887 format "[A-Za-z_:][[A-Za-z0-9_:.-]*". 889 Cross-references to anchors are notated as "<""..."">"; cross- 890 references with custom text as "<""reference,text"">". Asciidoctor 891 does not otherwise support attributes on cross-references, but the 892 converter extracts format information from templated text within 893 cross-references: "format=x:text" populates the "xref@format" 894 attribute, while a section number followed by one of the words "of, 895 parens, bare, text" is treated as a "relref" reference to an external 896 document. 898 [[crossreference]] 899 == Section 1 901 == Section 2 902 See <>. 904 == Section 3 905 See <> 907 == Section 4 908 See <> 910 == Section 5 911 See <> 913 See <> 914 <> 915 <> 916 <> 918
919 Section 1 920
921
922 Section 2 923 924 See 925 926 . 927 928
929
930 Section 3 931 932 See 933 934 text 935 936 937
938
939 Section 4 940 941 See 942 943 text 944 945 946
947
948 949 Section 5 950 951 952 See 953 954 955 956 See 957 959 961 text 962 963 965 967 text 968 970 971
973 15. Inclusions 975 The Asciidoctor "include" directive [11] is used to include external 976 files in a master Asciidoctor document. The directive is capable of 977 sophisticated document merging, including adjusting the heading 978 levels of the included text, selecting text within specified tags or 979 line numbers to be included, and adjusting the indentation of code 980 snippets in merged text: 982 \include::path[ 983 leveloffset=_offset_, 984 lines=_ranges_, 985 tag(s)=_name(s)_, 986 indent=_depth_ 987 ] 989 16. Encoding and Entities 991 XML accepted the full range of characters in the world's languages 992 through UTF-8 character encoding, and one of the motivations for the 993 move from plain text to RFC XML has been to allow non-ASCII 994 characters to be included in RFCs. However, current RFC XML v2 tools 995 still do not support UTF-8, and other tool support for UTF-8 also 996 remains patchy. Out of an abundance of caution, the RFC XML 997 converter uses US-ASCII for its character encoding, and renders any 998 non-ASCII characters as entities. 1000 The converter accepts HTML entities in Asciidoctor, even though they 1001 are not part of the XML specification; HTML entities such as " " 1002 feature in examples of RFC XML provided by the IETF. In order to 1003 prevent dependence of the XML output from extraneous entity 1004 definitions, any such entities are rendered in the XML as decimal 1005 character entities. 1007 17. Bibliography 1009 Asciidoctor has a simple encoding of bibliographies, but it is not 1010 adequate for the complexity of bibliographic markup supported in RFC 1011 XML. RFC documents overwhelmingly cite other RFC documents, and 1012 canonical RFC XML bibliographic entries are available at 1013 ; so it would be 1014 inefficient to encode those entries in Asciidoctor, only to have them 1015 converted back to RFC XML. 1017 The converter provides two means of incorporating bibliographies into 1018 RFC documents authored in Asciidoctor: 1020 o using raw RFC XML; and 1022 o assembling bibliographies in preprocessing. 1024 In either case, the RFC XML needs to be well-formed; missing closing 1025 tags can lead to erratic behaviour in the converter. 1027 17.1. Using Raw RFC XML 1029 In the first, bibliographic citations are handled like all other 1030 cross-references. The bibliographic entries for normative and 1031 informative references are given in the Asciidoctor as passthrough 1032 blocks, which contain the raw RFC XML for all references; document 1033 conversion leaves the raw RFC XML in place. This approach requires 1034 authors to maintain the normative and informative bibliographies 1035 within the document, to update them as citations are added and 1036 removed, and to sort them manually. 1038 Some datagram padding may be needed.<> 1040 [bibliography] 1041 == Normative References 1042 ++++ 1043 1045 1046 Guidelines for Writing an IANA Considerations 1047 Section in RFCs 1048 1049 Sacramento State 1050 1051 1052 UC Davis 1053 1054 1055 1056 1057 1058 ++++ 1060 Some datagram padding may be needed 1062 1063 1064 Normative References 1065 1067 1068 Guidelines for Writing an IANA Considerations 1069 Section in RFCs 1070 Sacramento State 1071 1072 1073 UC Davis 1074 1075 1076 1077 1078 1079 1081 17.2. Using preprocessing 1083 The alternative method is to use a preprocessing tool, asciidoc- 1084 bibliography [12], to import citations into the Asciidoctor document 1085 from an external file of references. 1087 The references file consists of RFC XML reference entries, and still 1088 needs to be managed manually; however the bibliographies are 1089 assembled from that file, sorted, and inserted into the normative and 1090 informative references in preprocessing. Citations in the document 1091 itself are given as macros to be interpreted by the preprocessor; 1092 this allows them to be split into normative and informative 1093 references. (The MMark tool likewise splits reference citations into 1094 normative and informative.) 1096 Integration with the asciidoc-bibliography gem proceeds as follows: 1098 1. Create an RFC XML references file, consisting of a "" 1099 element with individual "" elements inserted, as would 1100 be done for the informative and normative references normally. 1101 The references file will contain all possible references to be 1102 used in the file; the bibliography gem will select which 1103 references have actually been cited in the document. 1105 A. Rather than hand crafting RFC XML references for RFC 1106 documents, you should download them from an authoritative 1107 source; e.g. 1110 B. Unlike the case for RFC XML documents created manually, the 1111 references file does not recognise XML entities and will not 1112 attempt to download them during processing. Any references 1113 to will need to 1114 be downloaded and inserted into the references file. 1116 C. The RFC XML in the references file will need to be 1117 appropriate to the version of RFC XML used in the main 1118 document, as usual. Note that RFC XML v2 references are 1119 forward compatible with v3; v3 contains a couple of 1120 additional elements. 1122 2. Add to the main document header attributes referencing the 1123 references file (":bibliography-database:"), and the bibliography 1124 style (":bibliography-style:rfc-v3"). 1126 3. References to a normative reference are inserted with the macro 1127 "cite:norm[id]" instead of "<""id"">", where "id" is the anchor 1128 of the reference. 1130 4. References to an infomrative reference are inserted with the 1131 macro "cite:info[id]" instead of "<""id"">", where "id" is the 1132 anchor of the reference. 1134 5. Normative and Informative References are inserted in the document 1135 through a macro, which occurs where the RFC XML references would 1136 be inserted: 1138 [bibliography] 1139 == Normative References 1141 ++++ 1142 bibliography::norm[] 1143 ++++ 1145 [bibliography] 1146 == Informative References 1148 ++++ 1149 bibliography::info[] 1150 ++++ 1152 18. RFC XML features not supported in Asciidoctor 1154 The following features of RFC XML are not supported by the 1155 Asciidoctor converter, and would need to be adjusted manually: 1157 +----------------------------+-----------------------+--------------+ 1158 | RFC XML element | RFC XML v3 | RFC XML v2 | 1159 +----------------------------+-----------------------+--------------+ 1160 | "front/boilerplate" | Not added by the | N/A | 1161 | | converter | | 1162 | "iref@primary" | N | N | 1163 | "reference" (and all | As Raw XML | As Raw XML | 1164 | children) | | | 1165 | "table/preamble" | Deprecated | N | 1166 | "table/postamble" | Deprecated | N | 1167 | "artwork@width" | Only on images | Only on | 1168 | | | images | 1169 | "artwork@height" | Only on images | Only on | 1170 | | | images | 1171 +----------------------------+-----------------------+--------------+ 1173 19. Authoring 1175 To author an Asciidoctor RFC document, you should familiarise 1176 yourself with the Asciidoctor specification [13]. The converter Ruby 1177 gem source code distribution also has samples of individual RFC XML 1178 features [14], in v2 and v3, and examples of self-standing 1179 Asciidoctor RFC XML documents [15], along with their RFC XML 1180 renderings. (This includes round-tripped RFC XML documents.) 1182 In addition, you can clone the sample "rfc-in-asciidoc-template" 1183 repository as a template, and populate it for your AsciiDoc RFCs and 1184 Internet-Drafts: 1186 $ git clone https://github.com/riboseinc/rfc-in-asciidoc-template 1188 Converting your AsciiDoc to RFC XML is a simple as installing 1189 asciidoctor (see ) and the 1190 "asciidoctor-rfc" gem in Ruby, then running the asciidoctor 1191 executable on the document, specifying the asciidoctor-rfc gem as a 1192 library: 1194 $ git clone https://github.com/riboseinc/asciidoctor-rfc.git 1195 $ cd asciidoctor-rfc 1196 $ bundle install 1197 $ gem build asciidoctor-rfc.gemspec 1198 $ gem install asciidoctor-rfc 1199 $ asciidoctor -b rfc3 -r 'asciidoctor-rfc' a.adoc # RFC XML v3 output 1200 $ asciidoctor -b rfc2 -r 'asciidoctor-rfc' a.adoc # RFC XML v2 output 1202 As you author Asciidoctor content, you should iterate through running 1203 the Asciidoctor conversion frequently, to ensure that you are still 1204 generating valid XML through your markup. The converter makes an 1205 effort to ensure that its XML output is valid, and it issues warnings 1206 about likely issues; it also validates its own XML output against the 1207 Asciidoctor schema, and reports errors in the XML output in the 1208 following format: 1210 V3 RELAXNG Validation: 12:0: ERROR: Invalid attribute 1211 sortRefs for element rfc 1213 Note that validation against the RELAXNG RFC XML schema includes 1214 confirming the referential integrity of all cross-references in the 1215 document. 1217 It may be necessary to intervene in the XML output generated by the 1218 converter, either because the block model of Asciidoctor does not 1219 conform with the intended RFC XML (e.g. lists embedded in 1220 paragraphs), or because RFC XML features are required that are not 1221 supported within Asciidoctor. 1223 20. Security Considerations 1225 o Ensure your AsciiRFC generator comes from a geniune and 1226 trustworthy source. This protects your own machine and also 1227 prevents injection of malicious content in your document. 1229 o An AsciiRFC generator may cause errors in textual rendering or 1230 link generation that may lead to security issues. 1232 o Creating cross-references (and also bibliographic references) to 1233 external documents may pose risks since the external document's 1234 location may become controlled by a malicious party. 1236 21. IANA Considerations 1238 This document does not require any action by IANA. 1240 22. Examples 1242 22.1. Example 1 1244 TODO. 1246 23. References 1248 23.1. Normative References 1250 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1251 Requirement Levels", BCP 14, RFC 2119, 1252 DOI 10.17487/RFC2119, March 1997, 1253 . 1255 [RFC7749] Reschke, J., "The "xml2rfc" Version 2 Vocabulary", 1256 RFC 7749, DOI 10.17487/RFC7749, February 2016, 1257 . 1259 [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", 1260 RFC 7991, DOI 10.17487/RFC7991, December 2016, 1261 . 1263 23.2. Informative References 1265 [RFC5385] Touch, J., "Version 2.0 Microsoft Word Template for 1266 Creating Internet Drafts and RFCs", RFC 5385, 1267 DOI 10.17487/RFC5385, February 2010, 1268 . 1270 [RFC7328] Gieben, R., "Writing I-Ds and RFCs Using Pandoc and a Bit 1271 of XML", RFC 7328, DOI 10.17487/RFC7328, August 2014, 1272 . 1274 [RFC7763] Leonard, S., "The text/markdown Media Type", RFC 7763, 1275 DOI 10.17487/RFC7763, March 2016, 1276 . 1278 [RFC7764] Leonard, S., "Guidance on Markdown: Design Philosophies, 1279 Stability Strategies, and Select Registrations", RFC 7764, 1280 DOI 10.17487/RFC7764, March 2016, 1281 . 1283 [RFC7990] Flanagan, H., "RFC Format Framework", RFC 7990, 1284 DOI 10.17487/RFC7990, December 2016, 1285 . 1287 23.3. URIs 1289 [1] https://github.com/miekg/mmark 1291 [2] https://github.com/cabo/kramdown-rfc2629 1293 [3] https://daringfireball.net/projects/markdown/ 1295 [4] http://asciidoctor.org 1297 [5] http://asciidoctor.org/docs/user-manual/#compared-to-markdown 1299 [6] http://asciidoctor.org/docs/user-manual/#compared-to-markdown 1301 [7] http://docs.mathjax.org/en/latest/asciimath.html 1303 [8] http://docs.mathjax.org/en/latest/tex.html 1305 [9] https://www.mathjax.org 1307 [10] http://asciidoctor.org/docs/user-manual/#complex-list-content 1309 [11] http://asciidoctor.org/docs/user-manual/#include-directive 1311 [12] https://github.com/riboseinc/asciidoctor-bibliography 1313 [13] http://asciidoctor.org/docs/user-manual 1315 [14] https://github.com/riboseinc/asciidoctor- 1316 rfc/tree/master/spec/asciidoctor/rfc 1318 [15] https://github.com/riboseinc/asciidoctor-rfc/tree/master/spec/ 1319 examples 1321 Appendix A. Acknowledgements 1323 The authors would like to thank the following persons for their 1324 valuable advice and input. 1326 o TODO. 1328 Authors' Addresses 1329 Ronald Henry Tse 1330 Ribose 1331 Suite 1111, 1 Pedder Street 1332 Central, Hong Kong 1333 Hong Kong 1335 Email: ronald.tse@ribose.com 1336 URI: https://www.ribose.com 1338 Nick Nicholas 1339 Ribose 1340 Australia 1342 Email: nick.nicholas@ribose.com 1343 URI: https://www.ribose.com 1345 Paolo Brasolin 1346 Ribose 1347 Suite 1111, 1 Pedder Street 1348 Central, Hong Kong 1349 Hong Kong 1351 Email: jeffrey.lau@ribose.com 1352 URI: https://www.ribose.com 1354 Paolo Brasolin 1355 Ribose 1356 Italy 1358 Email: paolo.brasolin@ribose.com 1359 URI: https://www.ribose.com