idnits 2.17.1 draft-gieben-pandoc2rfc-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC2629]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 15, 2013) is 3808 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Click' is mentioned on line 424, but not defined -- Looks like a reference, but probably isn't: '1' on line 424 == Missing Reference: 'RFC2199' is mentioned on line 430, but not defined ** Obsolete normative reference: RFC 2629 (Obsoleted by RFC 7749) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 RFC Beautification Working Group R. Gieben 3 Internet-Draft Google 4 Intended status: Informational October 15, 2013 5 Expires: April 18, 2014 7 Writing I-Ds and RFCs using Pandoc and a bit of XML 8 draft-gieben-pandoc2rfc-03 10 Abstract 12 This document presents a technique for using a Markdown syntax 13 variant, called Pandoc, and a (bit) of XML [RFC2629] as a source 14 format for documents in the Internet-Drafts (I-Ds) and Request for 15 Comments (RFC) series. 17 The goal of this technique is to let an author of an I-D focus on the 18 main body of text without being distracted too much by XML tags, it 19 does however not alleviate the need to typeset some files in XML. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on April 18, 2014. 38 Copyright Notice 40 Copyright (c) 2013 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Pandoc to RFC . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Dependencies . . . . . . . . . . . . . . . . . . . . . . 4 58 3. Building an Internet-Draft . . . . . . . . . . . . . . . . . 4 59 4. Supported Features . . . . . . . . . . . . . . . . . . . . . 5 60 5. Unsupported Features and Limitations . . . . . . . . . . . . 6 61 6. Pandoc Style . . . . . . . . . . . . . . . . . . . . . . . . 7 62 6.1. Figures . . . . . . . . . . . . . . . . . . . . . . . . . 7 63 6.2. Tables . . . . . . . . . . . . . . . . . . . . . . . . . 7 64 6.3. References . . . . . . . . . . . . . . . . . . . . . . . 7 65 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 8 66 8. Security Considerations . . . . . . . . . . . . . . . . . . . 8 67 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 68 10. Normative References . . . . . . . . . . . . . . . . . . . . 8 69 Appendix A. Changelog . . . . . . . . . . . . . . . . . . . . . 8 70 A.1. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 A.2. -01 . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 72 A.3. -02 . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 73 A.4. -03 . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 Appendix B. Cheat Sheet . . . . . . . . . . . . . . . . . . . . 9 75 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 77 1. Introduction 79 This document presents a technique for using a Markdown [Markdown] 80 syntax variant, called Pandoc [Pandoc], and a bit of XML [RFC2629] as 81 a source format for documents in the Internet-Drafts (I-Ds) and 82 Request for Comments (RFC) series. 84 The goal of this technique is to let an author of an I-D focus on the 85 main body of text without being distracted too much by XML tags, it 86 does however not alleviate the need to typeset some files in XML. 88 Pandoc is an almost plain text format and therefor particularly well 89 suited for editing RFC-like documents. The syntax itself is a super 90 set of the syntax championed by Markdown. 92 2. Pandoc to RFC 94 Pandoc's syntax is easy to learn and write and it can be translated 95 to numerous output formats, including, but not limited to: HTML, 96 EPUB, (plain) Markdown and DocBook XML. 98 Pandoc2rfc allows authors to write in Pandoc syntax which is then 99 transformed to XML and given to xml2rfc. The conversions are, in a 100 way amusing, as we start off with (almost) plain text, use elaborate 101 XML and end up with plain text again. 103 +-------------------+ pandoc +---------+ 104 | ALMOST PLAIN TEXT | ------> | DOCBOOK | 105 +-------------------+ 1 +---------+ 106 | | 107 non-existent | 2 | xsltproc 108 faster way | | 109 v v 110 +------------+ xml2rfc +---------+ 111 | PLAIN TEXT | <-------- | XML | 112 +------------+ 3 +---------+ 114 Figure 1: Attempt to justify Pandoc2rfc. 116 The output of step 2 in Figure 1 is XML which is suitable for 117 inclusion in either the "middle" or "back" section of an RFC. 119 Even though Pandoc2rfc abstracts away a lot of XML details, there are 120 still places left where XML files needs to be edited. Most notably 121 in the "front" section of an RFC. 123 The simplest way to start using Pandoc2rfc is to create a template 124 XML file and include the appropriate XML for the "front", "middle" 125 and "back" section: 127 128 130 131 132 133 ]> 135 136 137 Writing I-Ds and RFCs using Pandoc 138 139 140
http://www.example.com
141
142 143 144 &pandocAbstract; 145 146
147 148 &pandocMiddle; 149 150 151 152 &rfc.2629; 153 154 &pandocBack; 155 156
158 Figure 2: A minimal template.xml. 160 In this case you will need to edit four documents: 162 1. "abstract.mkd" - contains the abstract; 164 2. "middle.mkd" - contains the main body of text; 166 3. "back.mkd" - holds the appendices (if any); 168 4. And this "template.xml" - probably a fairly static file, among 169 other things, it holds the author(s) and the references. 171 Up to date source code for Pandoc2rfc can be found at [Pandoc2rfc], 172 this includes the style sheet "transform.xsl" which used for the XML 173 transformation (also see Section 3). 175 2.1. Dependencies 177 Pandoc2rfc needs "xsltproc" [XSLT] and "pandoc" [Pandoc] to be 178 installed. The conversion to xml2rfc XML is done with a style sheet 179 based on XSLT version 1.0 [W3C.REC-xslt-19991116]. 181 When using the template from Figure 2 xml2rfc version 2 (or higher) 182 must be used. 184 3. Building an Internet-Draft 186 Assuming the setup from Section 2, we can build an I-D as follows (in 187 a Unix-like environment): 189 for i in abstract middle back; do 190 pandoc -st docbook $i.mkd | xsltproc --nonet transform.xsl - > $i.xml 191 done 193 xml2rfc template.xml -f draft.txt --text # create text output 194 xml2rfc template.xml -f draft.html --html # or create HTML output 195 xml2rfc template.xml -f draft.xml --exp # or create XML output 197 Figure 3: Building an I-D. 199 Note that the output file names (abstract.xml, middle.xml and 200 back.xml) must match the names used as the XML entities in 201 "template.xml" (See the "!ENTITY" lines in Figure 2). The Pandoc2rfc 202 source repository includes a shell script that incorporates the above 203 transformations. Creating a "draft.txt" or a "draft.xml" can be done 204 with "pandoc2rfc *.mkd" and "pandoc2rfc -X *.mkd" respectively. 206 4. Supported Features 208 The full description of Pandoc's syntax can be found in 209 [PandocGuide]. The following features of xml2rfc are supported by 210 Pandoc2rfc (also see Table 1 in Appendix B for a "cheat sheet"): 212 o Sections with an anchor and title attributes; 214 o Several lists styles: 216 * style="symbols", use "* " for each item; 218 * style="numbers", use digits: "1. " for each item; 220 * style="empty", use "#. " for each item; 222 * style="format %i", use roman lowercase numerals: "ii. "; 224 * style="format (%d)", use roman uppercase numerals "II. "; 226 * style="letters", use lower- or uppercase letters: "a. " and 227 "A. " (note: two spaces as mandated by Pandoc); 229 * style="hanging", use the Pandoc definition list syntax: 231 Term 1 233 : Definition 1 235 Figure 4: Pandoc syntax used for a hanging paragraph. 237 o Spanx style="verb", style="emph" and style="strong", respectively 238 use: "`text`", "_text_" or "**text**"; 240 o Block quote is converted to "" paragraph; 242 o Figures with an anchor and title (Section 6.1); 244 o Tables with an anchor and title (Section 6.2); 246 o References (Section 6.3) 248 * external (""); 250 * internal (""), to: 252 + sections (handled by Pandoc); 254 + figures (handled by XSLT); 256 + tables (handled by XSLT). 258 o Citations, by using internal references; 260 o Processing Instructions ("PI"s: ""), may be used after a 261 section header, they are carried over to the generated XML; 263 o The ""-tag is supported and carried over to the generated 264 XML. 266 5. Unsupported Features and Limitations 268 With Pandoc2rfc an author of an I-D can get a long way without 269 needing to input XML, but it is not a 100% solution. The initial 270 setup and the reference library still forces the author to edit XML 271 files. The meta data feature (Pandoc's "Title Block" extension) is 272 not used in Pandoc2rfc. This information (authors, date, keyword and 273 URLs) should be put in the "template.xml". 275 Some other quirks: 277 o An index is not supported; 279 o Comments are supported via HTML comments in the Pandoc source 280 files; 282 o Citations are supported via internal references, the citation 283 syntax of Pandoc is not used; 285 o Authors still need to know how to deal with possible errors from 286 xml2rfc. 288 6. Pandoc Style 290 The following sections detail how to use the Pandoc syntax for 291 figures, tables and references to get the desired output. 293 6.1. Figures 295 Indent the paragraph with 4 spaces as mandated by Pandoc. If you add 296 an inline footnote _directly_ after the figure, the artwork gets a 297 title attribute with the text of that footnote (and a possible 298 anchor). 300 6.2. Tables 302 A table can be entered by using Pandoc's table syntax. You can 303 choose multiple styles as input, but they all are converted to the 304 same style (plain "") table in xml2rfc. If you add an 305 inline footnote _directly_ after the table, it will get a title 306 attribute with the text of that footnote (and a possible anchor). 307 The built in syntax of Pandoc to create a caption with "Table:" 308 should not be used. 310 6.3. References 312 Pandoc provides a syntax that can be used for references. Its syntax 313 is repeated in this paragraph. Any reference like: "[Click 314 here](URI)", is an external reference. An internal (i.e. see 315 Section X) reference is typeset with: "[](#localid)". 317 For referencing RFCs (and other citations), you will need add the 318 reference source in the template, as an external XML entity, Figure 2 319 provides an example. After that you can use an internal reference: 320 "[](#RFC2629)" to reference RFC 2629. 322 There is no direct support for referencing tables, figures and 323 artworks, but pandoc2rfc employs the following "hack". If an inline 324 footnote is added after the figure or table, the text of the footnote 325 is used as the title. The first word up until a double colon "::" 326 will be used as the anchor. If a figure has an anchor it will be 327 centered on the page. 329 Figure 2 for instance, is followed by this inline footnote: 331 ^[fig:minimal::A minimal template.xml.] 333 7. Acknowledgements 335 The following people have helped shape Pandoc2rfc: Benno Overeinder, 336 Erlend Hamnaberg, Matthijs Mekking and Trygve Laugstoel. 338 8. Security Considerations 340 This document raises no security issues. 342 9. IANA Considerations 344 This document has no actions for IANA. 346 10. Normative References 348 [Markdown] 349 Gruber, J., "Markdown", 2004, 350 . 352 [Pandoc2rfc] 353 Gieben, R., "Pandoc2rfc git repository", October 2012, 354 . 356 [PandocGuide] 357 MacFarlane, J., "Pandoc User's Guide", 2006, 358 . 360 [Pandoc] MacFarlane, J., "Pandoc, a universal document converter", 361 2006, . 363 [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 364 June 1999. 366 [W3C.REC-xslt-19991116] 367 Clark, J., "XSL Transformations (XSLT) Version 1.0", World 368 Wide Web Consortium Recommendation REC-xslt-19991116, 369 November 1999, 370 . 372 [XSLT] Veillard, D., "The XSLT C library for GNOME", 2006, 373 . 375 Appendix A. Changelog 377 [This section should be removed by the RFC editor before publishing] 379 A.1. -00 380 1. Initial document. 382 A.2. -01 384 1. Lots of updates; 386 2. Added the style sheet use in an appendix. 388 A.3. -02 390 1. Make "template.xml" actually valid XML; 392 2. Removed the style sheet from the appendix; 394 3. Make more explicit that typesetting some XML files is still 395 needed; 397 4. Fix blockquote text and conversion; 399 5. Overhauled the way references to figures and tables work; 401 6. Cleaned up and removed duplicate text. 403 A.4. -03 405 1. Change affiliation for R. Gieben. 407 Appendix B. Cheat Sheet 409 +---------------------+-----------------+--------------+ 410 | Textual construct | Pandoc syntax | Text output | 411 +---------------------+-----------------+--------------+ 412 | Section Header | "# Section" | 1. Section | 413 | Unordered List | "* item" | o item | 414 | Unordered List | "#. item" | item | 415 | Ordered List | "1. item" | 1. item | 416 | Ordered List | "a. item" | a. item | 417 | Ordered List | "ii. item" | i. item | 418 | Ordered List | "II. item" | (1) item | 419 | Ordered List | "A. item" | A. item | 420 | Emphasis | "_text_" | _text_ | 421 | Strong Emphasis | "**text**" | *text* | 422 | Verbatim | "`text`" | "text" | 423 | Block Quote | "> quote" | quote | 424 | External Reference | "[Click](URI)" | Click [1] | 425 | Internal Reference | "[](#id)" | Section 1 | 426 | Figure Anchor | "^[fid::text]" | N/A | 427 | Figure Reference | "[](#fid)" | Figure 1 | 428 | Table Anchor | "^[tid::text]" | N/A | 429 | Table Reference | "[](#tid)" | Table 1 | 430 | Citations | "[](#RFC2119)" | [RFC2199] | 431 | Table | Tables | | 432 | Figures | Code Blocks | | 433 | Definition List | Definition | | 434 +---------------------+-----------------+--------------+ 436 Table 1: The most important textual constructs that can be used in 437 Pandoc2rfc. The bottom three create output to voluminous to show in 438 this table. 440 Author's Address 442 R. (Miek) Gieben 443 Google 445 Email: miek@google.com