Network Working Group R. Gieben Internet-Draft SIDN Intended status: Informational April 2012 Expires: October 3, 2012 Creating Internet Drafts and RFCs using Pandoc draft-gieben-creating-rfcs-pandoc-00 Abstract This memo presents a technique for using Pandoc syntax as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series. Using Pandoc syntax this way minimizes the need to directly edit the raw XML, but it does not completely make the XML invisible. Status of this Memo This document is an Internet-Draft and is NOT offered in accordance with Section 10 of RFC 2026, and the author does not provide the IETF with any rights other than to publish as an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on October 3, 2012. Gieben Expires October 3, 2012 [Page 1] Internet-Draft Pandoc for RFC creation April 2012 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Using Pandoc for RFC creation . . . . . . . . . . . . . . . . . 4 3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. References . . . . . . . . . . . . . . . . . . . . . . . . 7 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 8 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 8 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 8 7. Normative References . . . . . . . . . . . . . . . . . . . . . 8 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 9 Gieben Expires October 3, 2012 [Page 2] Internet-Draft Pandoc for RFC creation April 2012 1. Introduction This memo presents a technique for using Pandoc [1] syntax as a source format for documents in the Internet-Drafts (I-Ds) and Request for Comments (RFC) series. Pandoc is an "almost plain text" format, which is inspired by Markdown Syntax [2] and therefor particularly well suited for editing RFC-like documents. The power of Pandoc also comes from the fact that it can be translated to numerous output formats, including, but not limited to: HTML, Markdown and "docbook" XML. In this case the Pandoc sources are converted to "docbook" XML. This XML is then converted again, using an XSLT stylesheet, to XML suitable as input for "xml2rfc" [RFC2629]. The conversions are collectively called Pandoc2rfc [pandoc2rfc]. Pandoc2rfc is in some way amusing, as we start off with (almost) plain text, use elaborate XML and end up with plain text again, as shown in Figure 1. Attempt to justify Pandoc2rfc. +-------------------+ Pandoc +---------+ | ALMOST PLAIN TEXT | ------> | DOCBOOK | +-------------------+ +---------+ | | non-existent | | XSLT (transform.xsl) quicker way | | v v +------------+ xml2rfc +---------+ | PLAIN TEXT | <-------- | XML2RFC | +------------+ +---------+ Figure 1 For the conversion to work the following tools and files need to be installed: o xml2rfc [3]; o xsltproc [4] (or any other XSLT (v1) processor); o Pandoc [1]; Gieben Expires October 3, 2012 [Page 3] Internet-Draft Pandoc for RFC creation April 2012 o transform.xsl [5]. 2. Using Pandoc for RFC creation As said in the introduction the use of Pandoc does not eliminate the need to setup some files in XML. Particularly the "" matter of "xml2rfc" can not be codified in Pandoc, so a template like this is still needed: A minimal template.xml. Creating Internet Drafts and RFCs using Pandoc SIDN Figure 2 The template shown in Figure 2 includes 3 (not counting the reference) XML files: Gieben Expires October 3, 2012 [Page 4] Internet-Draft Pandoc for RFC creation April 2012 1. abstract.xml; 2. middle.xml; 3. back.xml. To create the complete document you will need to edit three Pandoc files and the template, (".pdc" is the extension for Pandoc files): 1. abtract.pdc; 2. middle.pdc; 3. back.pdc; 4. template.xml (probably a fairly static file once setup). To convert, for instance, the "middle.pdc" file to XML the following command is executed on a Unix-like system: pandoc -t docbook -s middle.pdc|xsltproc transform.xsl - > middle.xml This is also done for "abstract.pdc" and "back.pdc". After which "xml2rfc" is called: xml2rfc template.xml draft.txt Which creates the final output. Of course this process can be automated using a tool like "make". When using Pandoc2rfc consider adding the following sentence to an Acknowledgements section: This document was prepared using Pandoc2rfc. 3. Syntax Almost all features of "xml2rfc" are supported. A notable exception is the "crefs" tag, but HTML comments are allowed within Pandoc sources so they may be used as a substitute. Sections are started by using a header [README#headers]. Paragraphs are separated by an empty line. Hanging paragraphs are entered by using a definition list [README#deflists]. Footnotes are not supported. Pandoc2rfc (ab)uses the footnote syntax Gieben Expires October 3, 2012 [Page 5] Internet-Draft Pandoc for RFC creation April 2012 to support indices. Block quotes are not directly supported in "xml2rfc" so they get translated to a hanging paragraph. A good number of different type of lists are supported, they are translated according to the following table. List conversions from Pandoc to "xml2rfc". +---------------------------------+------------------------------+ | Pandoc | Converts to | +---------------------------------+------------------------------+ | "* First item" | "" | | "1. First item" | "" | | "#. First item" | "" | | "a. First item" | "" | | "A. First item" | "list style="format %C.">" | | "i. First item" | "" | | "I. First item" | "" | +---------------------------------+------------------------------+ Table 1 A figure or artwork is created with a paragraph that is indented with four spaces [README#codeblocks]. A figure caption is always translated to a "". A figure caption is created by using this text as the last line in the artwork: "Figure: ...caption text..." The different tables [README#tables] Pandoc supports are all mapped to "". A table caption is always translated to a "". A table caption is added by using "Table: ...caption text..." after a table. The caption is _always_ translated to a "". The "" tag isn't supported. If a table has a caption, it will *also* get a reference. See Section 3.1 for the details. As footnotes are not supported in RFCs the syntax in Pandoc is used to support an index. Footnotes in Pandoc (and thus an index in the RFC) are entered in two steps, you have a marker in the text, and later you give actual footnote text. Like this: [^1] [^1]: footnote text This text translates to: "". It points to the page where to footnote marker was placed. Sub items are also Gieben Expires October 3, 2012 [Page 6] Internet-Draft Pandoc for RFC creation April 2012 supported. Use an exclamation mark ("!") to separate them: "[^1]: item!sub item". 3.1. References References to section are created automatically by Pandoc and the normal Pandoc rules are followed. Reference conversions from Pandoc to "xml2rfc". +-------------------------+------------------------------+----------+ | Pandoc | Converts to | Type | +-------------------------+------------------------------+----------+ | "[Click](URL)" | "Click..." | | | "[See](#local)" | "See..." | | | "[](#RFC2119)" | "" | Citation | +-------------------------+------------------------------+----------+ Table 2 Internal references will add "Section:", "Table:" or "Figure:" depending on where it points to (this is the default behavior of "xml2rfc"). For the citations to work the reference anchor must be known (i.e. the RFC reference.xml must be included in the template). References to tables and figures are not handled by Pandoc, this behavior is implemented in the XSLT stylesheets, therefor the rules are slightly different (and less flexible). A figure and table only get a reference when they have a caption. If a figure has a caption it is also centered on the page. The reference anchor attribute will be: "fig:" + "first 10 (normalized) characters from the caption" for figures and "tab:" + "first 10 (normalized) characters from the caption" for tables. Normalized is: o Take the first 10 characters of the caption (i.e. this is the text _after_ the string "Figure:" or "Table:"); o Spaces are translated to a minus "-"; o Uppercase letters translated to lowercase. For example a figure with a caption "Figure: A minimal template" will get the anchor "fig:a-minimal-" Gieben Expires October 3, 2012 [Page 7] Internet-Draft Pandoc for RFC creation April 2012 4. Security Considerations This memo raises no security issues. 5. IANA Considerations This memo has no actions for IANA. 6. Acknowledgements The following people have helped to make Pandoc2rfc what it is today: Benno Overeinder, Erlend Hamnaberg, Matthijs Mekking, and Trygve Laugstoel. This document was prepared using Pandoc2rfc. 7. Normative References [README#codeblocks] MacFarlane, J., "PANDOC Documentation", 2006, . [README#deflists] MacFarlane, J., "PANDOC Documentation", 2006, . [README#headers] MacFarlane, J., "PANDOC Documentation", 2006, . [README#tables] MacFarlane, J., "PANDOC Documentation", 2006, . [RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999. [pandoc2rfc] Gieben, R., "Pandoc2rfc", 2012, . [1] [2] Gieben Expires October 3, 2012 [Page 8] Internet-Draft Pandoc for RFC creation April 2012 [3] [4] [5] Author's Address R. (Miek) Gieben SIDN Meander 501 Arnhem, 6825 MD NL Phone: Email: miek@miek.nl URI: http://miek.nl/ Gieben Expires October 3, 2012 [Page 9]