RFC 7328

Writing I-Ds and RFCs Using Pandoc and a Bit of XML

📅 published August 2014, from ietf

Writing I-Ds and RFCs Using Pandoc and a Bit of XML 🎀

RFC 7328 💖 Writing I-Ds and RFCs Using Pandoc and a Bit of XML by R. Gieben from Google, published August 2014. It's an Independent Submission and its category is Informational ✨ (ISSN 2070-1721). The title block doesn't list any RFCs it obsoletes or updates, so it's a standalone little gem 🦋

Abstract

okay so this doc shows off a technique for writing Internet-Drafts (I-Ds) and RFCs in Pandoc, which is a Markdown-ish syntax variant, plus a tiny bit of XML (from RFC 2629) 🧚 the whole point is that the author gets to focus on the actual writing instead of getting distracted by XML tags every five seconds 💅

the technique is called Pandoc2rfc, and the vibe is "you can ignore the XML mostly" 🌸 but it doesn't let you skip typing some files in XML. no cap, you still gotta do that part 🙈

Status of This Memo

this document is not an Internet Standards Track specification. it's published for informational purposes 📚

it's a contribution to the RFC Series, totally independent of any other RFC stream. the RFC Editor picked to publish it at their discretion and makes no statement about its value for implementation or deployment. docs approved for publication by the RFC Editor are not a candidate for any level of Internet Standard, see Section 2 of RFC 5741 ✨

info about the current status of this doc, any errata, and how to give feedback is at http://www.rfc-editor.org/info/rfc7328 🔗

Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. 🔒

this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication. please read those carefully because they describe your rights and restrictions for this doc 💜

Table of Contents 🗂️

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
2.  Pandoc to RFC . . . . . . . . . . . . . . . . . . . . . . . .   2
  2.1.  Dependencies  . . . . . . . . . . . . . . . . . . . . . .   5
3.  Building an Internet-Draft  . . . . . . . . . . . . . . . . .   5
4.  Supported Features  . . . . . . . . . . . . . . . . . . . . .   5
5.  Unsupported Features and Limitations  . . . . . . . . . . . .   7
6.  Pandoc Style  . . . . . . . . . . . . . . . . . . . . . . . .   7
  6.1.  Figures . . . . . . . . . . . . . . . . . . . . . . . . .   7
  6.2.  Tables  . . . . . . . . . . . . . . . . . . . . . . . . .   7
  6.3.  References  . . . . . . . . . . . . . . . . . . . . . . .   7
  6.4.  Index . . . . . . . . . . . . . . . . . . . . . . . . . .   8
7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   8
8.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
9.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   8
  9.1.  Normative References  . . . . . . . . . . . . . . . . . .   8
  9.2.  Informative References  . . . . . . . . . . . . . . . . .   9
Appendix A.  Cheat Sheet  . . . . . . . . . . . . . . . . . . . .  10

1. Introduction ✨

okay so this doc presents a technique for using a Markdown [Markdown] syntax variant, called Pandoc [Pandoc], plus a bit of XML [RFC2629], as a source format for documents that are Internet-Drafts (I-Ds) or RFCs 🦋

the goal is to let an I-D author focus on the main body of text without being distracted too much by XML tags. however, it does not get rid of the need to typeset some files in XML 🙈

Pandoc is basically plain text, so it's super well suited for editing RFC-like docs 💅 the syntax itself is a superset of the syntax championed by Markdown.

2. Pandoc to RFC 🌈

Pandoc's syntax is easy to learn and write, and it can be translated into a bunch of output formats, including but not limited to: HTML, EPUB, (plain) Markdown, and DocBook XML 🍓

Pandoc2rfc lets authors write in Pandoc syntax, which then gets transformed to XML and handed to xml2rfc. it's kinda funny honestly, because we start with (almost) plain text, go through elaborate XML, and end up with plain text again 😭

          +-------------------+   pandoc   +---------+
          | ALMOST PLAIN TEXT |   ------>  | DOCBOOK |
          +-------------------+     1      +---------+
                        |                       |
          non-existent  |                     2 | xsltproc
            faster way  |                       |
                        v                       v
                +------------+    xml2rfc  +---------+
                | PLAIN TEXT |  <--------  |   XML   |
                +------------+      3      +---------+

               Figure 1: Attempt to justify Pandoc2rfc

the output of step 2 in Figure 1 is XML that's suitable for inclusion in either the "middle" or "back" section of an RFC 🧚

even though Pandoc2rfc hides a lot of XML details, there are still places where you need to edit XML files, most notably in the "front" section of an RFC 🙃

the simplest way to start is to make a template XML file and include the right XML for the "front", "middle", and "back" sections 💖

<?xml version='1.0' ?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
<!ENTITY pandocAbstract PUBLIC '' 'abstract.xml'>
<!ENTITY pandocMiddle   PUBLIC '' 'middle.xml'>
<!ENTITY pandocBack     PUBLIC '' 'back.xml'>
<!ENTITY rfc.2629       PUBLIC '' 'reference.RFC.2629.xml'>
]>

<rfc ipr='trust200902' docName='draft-string-example'>
 <front>
    <title>Writing I-Ds and RFCs using Pandoc</title>
    <author>
       <organization/>
       <address><uri>http://www.example.com</uri></address>
    </author>
    <date/>
    <abstract>
        &pandocAbstract;
    </abstract>
</front>
<middle>
    &pandocMiddle;
</middle>
<back>
    <references title="Normative References">
        &rfc.2629;
    </references>
    &pandocBack;
</back>
</rfc>

                  Figure 2: A minimal template.xml

in this case you'll need to edit four docs:

  1. "abstract.mkd" - contains the abstract;
  2. "middle.mkd" - contains the main body of text;
  3. "back.mkd" - holds the appendices (if any);
  4. and this "template.xml" -- probably a fairly static file; among other things, it holds the author(s) and the references.

the up-to-date source code for Pandoc2rfc is at [Pandoc2rfc]. it includes the style sheet "transform.xsl", which does the XML transformation (also see Section 3) 🫶

2.1. Dependencies 🧰

Pandoc2rfc needs "xsltproc" [XSLT] and "pandoc" [Pandoc] installed. the conversion to xml2rfc XML is done with a style sheet based on XSLT version 1.0 [W3C.REC-xslt-19991116] 💅

when you use the template from Figure 2, xml2rfc version 2 (or higher) must be used.

3. Building an Internet-Draft 🏗️

assuming the setup from Section 2, here's how to build an I-D (in a Unix-like environment) 🐧

for i in abstract middle back; do
pandoc -st docbook $i.mkd | xsltproc --nonet transform.xsl - > $i.xml
done

xml2rfc template.xml -f draft.txt --text  # create text output
xml2rfc template.xml -f draft.html --html # or create HTML output
xml2rfc template.xml -f draft.xml --exp   # or create XML output

                      Figure 3: Building an I-D

okay important bit: the output file names (abstract.xml, middle.xml, and back.xml) must match the names used as the XML entities in "template.xml". (See the "!ENTITY" lines in Figure 2.) the Pandoc2rfc source repo includes a shell script that bundles all of the above transformations. you can make a "draft.txt" or a "draft.xml" with "pandoc2rfc *.mkd" and "pandoc2rfc -X *.mkd", respectively 🎀

4. Supported Features 💜

the full description of Pandoc's syntax is in [PandocGuide]. the following xml2rfc features are supported by Pandoc2rfc (also see Table 1 in Appendix A for a "cheat sheet") 📝

  • Sections with an anchor and title attributes;
  • Several list styles:
    • style="symbols", use "* " for each item;
    • style="numbers", use digits: "1. " for each item;
    • style="empty", use "#. " for each item;
    • style="format %i", use lowercase Roman numerals: "ii. ";
    • style="format (%d)", use uppercase Roman numerals "II. ";
    • style="format ...", use strike-through text at the start in the first element, "1. ~~REQ%d.~~ ";
    • style="letters", use lower- or uppercase letters: "a. " and "A. " (note: two spaces as mandated by Pandoc);
    • style="hanging", use the Pandoc definition list syntax:

Term 1

: Definition 1

  • Spanx style="verb", style="emph", and style="strong", respectively, use: "text", "_text_" or "text";
  • Block quote, which is converted to a paragraph within a "<list style="empty">";
  • Figures with an anchor and title (Section 6.1);
  • Tables with an anchor and title (Section 6.2);
  • References (Section 6.3)
    • external ("<eref>");
    • cross-reference ("<xref>"), to:
      • sections (handled by Pandoc);
      • figures (handled by XSLT);
      • tables (handled by XSLT).
  • Index, by using footnotes and superscript text (Section 6.4);
  • Citations, by using cross-references;
  • Processing Instructions (PIs), which appear as "<?rfc?>", may be used after a section header. They are carried over to the generated XML.
  • The "<vspace>" tag is supported and carried over to the generated XML.

5. Unsupported Features and Limitations 🥺

with Pandoc2rfc, an I-D author can get a long way without typing any XML, but it's not a 100% solution 😅 the initial setup and the reference library still make the author edit XML files. the metadata feature (Pandoc's "Title Block" extension) isn't used in Pandoc2rfc. this info (authors, date, keyword, and URLs) should go in the "template.xml" instead.

some other quirks:

  • Comments are supported via HTML comments in the Pandoc source files.
  • Citations are supported via cross-references; the citation syntax of Pandoc is not used.
  • Authors still need to know how to deal with possible errors from xml2rfc. 🙈

6. Pandoc Style 🎨

the following sections explain how to use Pandoc syntax for figures, tables, and references so you get the output you want ✨

6.1. Figures 🖼️

Indent the paragraph with 4 spaces, as mandated by Pandoc. if you add an inline footnote _directly_ after the figure, the artwork gets a title attribute with the text of that footnote (and a possible anchor).

6.2. Tables 📊

you can enter a table using Pandoc's table syntax. you can pick multiple styles as input, but they all get converted to the same style table (plain "<texttable>") in xml2rfc. if you add an inline footnote _directly_ after the table, it gets a title attribute with the text of that footnote (and a possible anchor). the built-in Pandoc syntax for making a caption with "Table:" should not be used. 💅

6.3. References ✨

okay so pandoc has its own syntax for references 📚 and I'm repeating it here bc it's giving very important. Any reference like [Click here](URI) is an external reference 🔗. An internal reference (aka "see Section X") gets typed as [](#localid) 💅

For referencing RFCs (and other documents), you gotta add the reference source in the template as an external XML entity. Figure 2 shows you how 🎀. After that, you can cite with [](#RFC2629) to cite RFC 2629 ✨.

There's no direct support for referencing tables, figures, and artworks, but Pandoc2rfc uses a little "hack" 🧚. If you put an inline footnote right after the figure or table, the text of that footnote becomes the title. The first word up until a double colon :: becomes the anchor. And if a figure has an anchor, it gets centered on the page 🦋.

Figure 2, for instance, is followed by this inline footnote:

^[fig:minimal::A minimal template.xml.]

6.4. Index 🗂️

you can generate an index with this syntax:

^[ ^item^ subitem ]

where "subitem" is optional 🌸

7. Acknowledgements 🫶

big shoutout to the girlies who helped shape Pandoc2rfc: Benno Overeinder, Erlend Hamnaberg, Matthijs Mekking, and Trygve Laugstoel 👑

8. Security Considerations 🔐

bestie, this document raises no security issues 💅✨

9. References 📚

9.1. Normative References

9.2. Informative References

Appendix A. Cheat Sheet 📋

here's the whole cheat sheet, screenshot it bestie 📸🎀

         +---------------------+-----------------+--------------+
         | Textual construct   | Pandoc syntax   | Text output  |
         +---------------------+-----------------+--------------+
         | Section Header      | "# Section"     | 1. Section   |
         | Unordered List      | "* item"        | o  item      |
         | Unordered List      | "#. item"       | item         |
         | Ordered List        | "1. item"       | 1.  item     |
         | Ordered List        | "a.  item"      | a.  item     |
         | Ordered List        | "ii. item"      | i.  item     |
         | Ordered List        | "II. item"      | (1)  item    |
         | Ordered List        | "A.  item"      | A.  item     |
         | Ordered List        | "1. ~~REQ%d.~~" | REQ1.        |
         | Emphasis            | "_text_"        | _text_       |
         | Strong Emphasis     | "**text**"      | *text*       |
         | Verbatim            | "`text`"        | "text"       |
         | Block Quote         | "> quote"       | quote        |
         | External Reference  | "[Click](URI)"  | Click [1]    |
         | Internal Reference  | "[](#id)"       | Section 1    |
         | Figure Anchor       | "^[fid::text]"  | N/A          |
         | Figure Reference    | "[](#fid)"      | Figure 1     |
         | Table Anchor        | "^[tid::text]"  | N/A          |
         | Table Reference     | "[](#tid)"      | Table 1      |
         | Citations           | "[](#RFC2119)"  | [RFC2119]    |
         | Table               | Tables          | *            |
         | Figures             | Code Blocks     | *            |
         | Definition List     | Definition      | *            |
         | Index               | ^[ ^item^ ]     | *            |
         +---------------------+-----------------+--------------+

   * This construct creates output too voluminous to show in the table.

            Table 1: The most important textual constructs that
                         can be used in Pandoc2rfc

Author's Address 💌

   R. (Miek) Gieben
   Google

   EMail: miek@google.com
📦 where this page comes from