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