Writing I-Ds and RFCs Using Pandoc and a Bit of XML
RFC 7328
Document | Type |
RFC - Informational
(August 2014; No errata)
Was draft-gieben-pandoc2rfc (individual)
|
|
---|---|---|---|
Last updated | 2018-12-20 | ||
Stream | ISE | ||
Formats | plain text html pdf htmlized bibtex | ||
IETF conflict review | conflict-review-gieben-pandoc2rfc | ||
Stream | ISE state | Published RFC | |
Consensus Boilerplate | Unknown | ||
Document shepherd | Adrian Farrel | ||
Shepherd write-up | Show (last changed 2014-06-09) | ||
IESG | IESG state | RFC 7328 (Informational) | |
Telechat date | |||
Responsible AD | (None) | ||
Send notices to | (None) | ||
IANA | IANA review state | IANA OK - No Actions Needed | |
IANA action state | No IANA Actions |
Independent Submission R. Gieben Request for Comments: 7328 Google Category: Informational August 2014 ISSN: 2070-1721 Writing I-Ds and RFCs Using Pandoc and a Bit of XML Abstract This document presents a technique for using a Markdown syntax variant, called Pandoc, and a bit of XML (as defined in RFC 2629) as a source format for documents that are Internet-Drafts (I-Ds) or RFCs. The goal of this technique (which is called Pandoc2rfc) is to let an author of an I-D focus on the main body of text without being distracted too much by XML tags; however, it does not alleviate the need to typeset some files in XML. Status of This Memo This document is not an Internet Standards Track specification; it is published for informational purposes. This is a contribution to the RFC Series, independently of any other RFC stream. The RFC Editor has chosen to publish this document at its discretion and makes no statement about its value for implementation or deployment. Documents approved for publication by the RFC Editor are not a candidate for any level of Internet Standard; see Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7328. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document 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 of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Gieben Informational [Page 1] RFC 7328 Pandoc2rfc August 2014 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 This document presents a technique for using a Markdown [Markdown] syntax variant, called Pandoc [Pandoc], and a bit of XML [RFC2629] as a source format for documents that are Internet-Drafts (I-Ds) or RFCs. The goal of this technique is to let an author of an I-D focus on the main body of text without being distracted too much by XML tags; however, it does not alleviate the need to typeset some files in XML. Pandoc is a format that is almost plain text and therefore particularly well suited for editing RFC-like documents. 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 to numerous output formats, including, but not limited to: HTML, EPUB, (plain) Markdown, and DocBook XML. Pandoc2rfc allows authors to write in Pandoc syntax that is then transformed to XML and given to xml2rfc. The conversions are, in a way, amusing, as we start off with (almost) plain text, use elaborate XML, and end up with plain text again. Gieben Informational [Page 2] RFC 7328 Pandoc2rfc August 2014 +-------------------+ pandoc +---------+ | ALMOST PLAIN TEXT | ------> | DOCBOOK | +-------------------+ 1 +---------+ | | non-existent | 2 | xsltproc faster way | | v v +------------+ xml2rfc +---------+Show full document text