idnits 2.17.1 

draft-gieben-pandoc2rfc-01.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 :
  ----------------------------------------------------------------------------

  ** There are 3 instances of too long lines in the document, the longest one
     being 3 characters in excess of 72.


  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  == The copyright year in the IETF Trust and authors Copyright Line does not
     match the current year

  -- The document date (April 10, 2013) is 4033 days in the past.  Is this
     intentional?

  -- Found something which looks like a code comment -- if you have code
     sections in the document, please surround them with '<CODE BEGINS>' and
     '<CODE ENDS>' lines.


  Checking references for intended status: Informational
  ----------------------------------------------------------------------------

  ** Obsolete normative reference: RFC 2629 (Obsoleted by RFC 7749)


     Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 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                            April 10, 2013
5	Expires: October 12, 2013

7	                   Writing I-Ds and RFCs using Pandoc
8	                       draft-gieben-pandoc2rfc-01

10	Abstract

12	   This document presents a technique for using a Markdown syntax
13	   variant, called Pandoc, as a source format for documents in the
14	   Internet-Drafts (I-Ds) and Request for Comments (RFC) series.

16	Status of This Memo

18	   This Internet-Draft is submitted in full conformance with the
19	   provisions of BCP 78 and BCP 79.

21	   Internet-Drafts are working documents of the Internet Engineering
22	   Task Force (IETF).  Note that other groups may also distribute
23	   working documents as Internet-Drafts.  The list of current Internet-
24	   Drafts is at http://datatracker.ietf.org/drafts/current/.

26	   Internet-Drafts are draft documents valid for a maximum of six months
27	   and may be updated, replaced, or obsoleted by other documents at any
28	   time.  It is inappropriate to use Internet-Drafts as reference
29	   material or to cite them other than as "work in progress."

31	   This Internet-Draft will expire on October 12, 2013.

33	Copyright Notice

35	   Copyright (c) 2013 IETF Trust and the persons identified as the
36	   document authors.  All rights reserved.

38	   This document is subject to BCP 78 and the IETF Trust's Legal
39	   Provisions Relating to IETF Documents
40	   (http://trustee.ietf.org/license-info) in effect on the date of
41	   publication of this document.  Please review these documents
42	   carefully, as they describe your rights and restrictions with respect
43	   to this document.  Code Components extracted from this document must
44	   include Simplified BSD License text as described in Section 4.e of
45	   the Trust Legal Provisions and are provided without warranty as
46	   described in the Simplified BSD License.

48	Table of Contents
49	   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
50	   2.  Pandoc to RFC . . . . . . . . . . . . . . . . . . . . . . . .   2
51	     2.1.  Dependencies  . . . . . . . . . . . . . . . . . . . . . .   4
52	   3.  Building an Internet-Draft  . . . . . . . . . . . . . . . . .   4
53	   4.  Supported Features  . . . . . . . . . . . . . . . . . . . . .   5
54	   5.  Unsupported Features  . . . . . . . . . . . . . . . . . . . .   6
55	   6.  Pandoc Style  . . . . . . . . . . . . . . . . . . . . . . . .   6
56	     6.1.  Figure/Artwork  . . . . . . . . . . . . . . . . . . . . .   6
57	     6.2.  Tables  . . . . . . . . . . . . . . . . . . . . . . . . .   6
58	     6.3.  References  . . . . . . . . . . . . . . . . . . . . . . .   7
59	     6.4.  Indexes . . . . . . . . . . . . . . . . . . . . . . . . .   7
60	   7.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   8
61	   8.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
62	   9.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   8
63	   10. Normative References  . . . . . . . . . . . . . . . . . . . .   8
64	   Appendix A.  Changelog  . . . . . . . . . . . . . . . . . . . . .   8
65	     A.1.  -00 . . . . . . . . . . . . . . . . . . . . . . . . . . .   8
66	     A.2.  -01 . . . . . . . . . . . . . . . . . . . . . . . . . . .   9
67	   Appendix B.  Cheat Sheet  . . . . . . . . . . . . . . . . . . . .   9
68	   Appendix C.  XSLT . . . . . . . . . . . . . . . . . . . . . . . .   9
69	   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  25

71	1.  Introduction

73	   This document presents a technique for using Pandoc syntax as a
74	   source format for documents in the Internet-Drafts (I-Ds) and Request
75	   for Comments (RFC) series.

77	   Pandoc [Pandoc] is an "almost plain text" format and therefor
78	   particularly well suited for editing RFC-like documents.  The syntax
79	   itself is a superset of the syntax championed by Markdown [Markdown].

81	   Pandoc2rfc generates XML compatible with [RFC2629].

83	2.  Pandoc to RFC

85	   During the last few years people have been developing markup
86	   languages that are very easy to remember and type.  These languages
87	   have become known as "almost plain text"-markup languages.  One of
88	   the first was the Markdown ([Markdown]) syntax.  One that was
89	   developed later and incorporates Markdown syntax and a number of
90	   extensions is Pandoc ([Pandoc]).  The power of Pandoc comes from the
91	   fact that it can be translated to numerous output formats, including,
92	   but not limited to: HTML, EPUB, (plain) Markdown and DocBook XML.

94	   Pandoc2rfc allows authors to write in (the simple) Pandoc syntax
95	   which is then transformed to XML and given to xml2rfc.  The
96	   conversions are, in some way amusing, as we start off with (almost)
97	   plain text, use elaborate XML and end up with plain text again.

99	             +-------------------+   pandoc   +---------+
100	             | ALMOST PLAIN TEXT |   ------>  | DOCBOOK |
101	             +-------------------+            +---------+
102	                           |                       |
103	             non-existent  |                       | xsltproc
104	               faster way  |                       |
105	                           v                       v
106	                   +------------+    xml2rfc  +---------+
107	                   | PLAIN TEXT |  <--------  |   XML   |
108	                   +------------+             +---------+

110	                      Attempt to justify Pandoc2rfc.

112	                                 Figure 1

114	   The XML generated (the output after the "xsltproc" step in Figure 1)
115	   is suitable for inclusion in either the "middle" or "back" section of
116	   an RFC.

118	   Even though Pandoc2rfc abstracts away a lot of XML details, there are
119	   still a few places left where some XML needs to be edited.  Most
120	   notably in the "front" section of an RFC.

122	   The simplest way to start is to create a template XML file and
123	   include the appropriate XML for this "front" section:

125	       <?xml version='1.0' ?>
126	       <!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [
127	       <!ENTITY pandocMiddle PUBLIC '' 'middle.xml'>
128	       <!ENTITY pandocBack   PUBLIC '' 'back.xml'>
129	       <!ENTITY rfc.2629     PUBLIC '' 'reference.RFC.2629.xml'>
130	       ]>

132	       <rfc ipr='trust200902' docName='draft-gieben-pandoc2rfc-01'>
133	        <front>
134	           <title>Writing I-Ds and RFCs using Pandoc</title>
135	       </front>
136	       <middle>
137	           &pandocMiddle;
138	       </middle>
139	       <back>
140	           <references title="Normative References">
141	                &rfc.2629;
142	           </references>
143	           &pandocBack;

145	       </back>
146	       </rfc>

148	                       A very minimal template.xml.

150	                                 Figure 2

152	   In this case you need to edit three documents:

154	   1.  "middle.txt" - contains the main body of text;

156	   2.  "back.txt" - holds appendices;

158	   3.  this "template.xml" - probably a fairly static file, among other
159	       things, it holds the authors and the references.

161	   The up to date source code for Pandoc2rfc can be found at
162	   [Pandoc2rfc], this includes the stylesheet "transform.xsl" used for
163	   the transformation.

165	2.1.  Dependencies

167	   Pandoc2rfc needs "xsltproc" [XSLT] and "pandoc" [Pandoc] to be
168	   installed.  The conversion to xml2rfc XML is done with a stylesheet
169	   based on XSLT version 1.0 [W3C.REC-xslt-19991116].  See Figure 4 in
170	   Appendix C for the contents of that stylesheet.

172	   When using the template from Figure 2 xml2rfc version 2 must be used.

174	3.  Building an Internet-Draft

176	   Assuming the setup from Section 2, we can build an I-D as follows (in
177	   a Unix-like environment):

179	    pandoc -st docbook middle.txt | xsltproc --nonet transform.xsl - \
180	        > middle.xml
181	    pandoc -st docbook back.txt | xsltproc --nonet transform.xsl - \
182	        > back.xml

184	    # Create text output
185	    xml2rfc template.xml -f draft.txt --text

187	    # ... or create HTML output
188	    xml2rfc template.xml -f draft.html --html

190	    # ... or create (self-contained) XML output
191	    xml2rfc template.xml -f draft.xml --exp
192	                     Building an I-D with Pandoc2rfc.

194	                                 Figure 3

196	   Note that the output file names ("middle.xml" and "back.xml") must
197	   match the names used as the XML entities in "template.xml".  The
198	   Pandoc2rfc source repository includes a shell script that
199	   incorporates the above transformations.  Creating a "draft.txt" or a
200	   "draft.xml" can be done with "pandoc2rfc *.txt" and "pandoc2rfc -X
201	   *.txt" respectively.

203	4.  Supported Features

205	   Almost everything xml2rfc can do is supported, see Table 1 in
206	   Appendix B for a "cheat sheet".

208	   o  Sections with an anchor and title attributes

210	   o  Lists

212	      *  style="symbols", use "* " for each item;

214	      *  style="numbers", use digits: "1. " for each item;

216	      *  style="empty", use "#. " for each item;

218	      *  style="format %i", use roman lowercase numerals: "ii. ";

220	      *  style="format (%d)", use roman uppercase numerals "II. ";

222	      *  style="letters", use lower- or uppercase letters: "a.  " and
223	         "A.  " (note: two spaces);

225	      *  style="hanging", use the Pandoc definition list syntax;

227	   o  Spanx style="verb", style="emph" and style="strong", respectively
228	      use: "`text`", "_text_" or "**text**";

230	   o  Block quote - not supported by xml2rfc, so this is converted to
231	      "<list style="hanging">" paragraph;

233	   o  Figure/artwork with an anchor and postamble (Section 6.1);

235	   o  Tables with an anchor and postamble (Section 6.2);

237	   o  References (Section 6.3)

239	      *  external (eref);
240	      *  internal (xref):

242	         +  section (handled by Pandoc);

244	         +  figures (handled by XSLT);

246	         +  tables (handled by XSLT).

248	   o  Citations, by using internal references;

250	   o  Indexes, by (ab)using footnotes (Section 6.4).

252	5.  Unsupported Features

254	   o  Pandoc markup in the caption for figures/artwork.  Pandoc markup
255	      for table captions _is_ supported;

257	   o  Crefs: for comments, but you can use HTML comments: "<!-- ... -->"
258	      in the Pandoc source files;

260	   o  Preamble in figures and tables.

262	6.  Pandoc Style

264	   In some cases the Pandoc syntax is slightly misused to get the
265	   desired output, in the following paragraphs we will detail these.
266	   Also the meta data feature (Pandoc's "Title Block" extension) of
267	   Pandoc is not used in Pandoc2rfc.  This information must be put in
268	   the "template.xml".

270	6.1.  Figure/Artwork

272	   Indent the paragraph with 4 spaces as mandated by Pandoc.  Note that
273	   xml2rfc supports a caption with "<artwork>".  If you add a "@Figure:
274	   some text" as the last line, the artwork gets a "<postamble>" with
275	   the text after "@Figure: ".  It will also be possible to reference
276	   the artwork.  If such a caption is supplied the artwork will be
277	   centered on the page.  If a caption is needed but the figure should
278	   not be centered use "@figure: ".

280	6.2.  Tables

282	   A table can be entered by using Pandoc's table syntax.  You can
283	   choose multiple styles as input, but they all are converted to the
284	   same style (plain "<texttable>") table in xml2rfc.

286	   The table caption is _always_ translated to a "<postamble>".  The
287	   "<preamble>" tag isn't supported.  If a table has a caption, it will
288	   also be possible to reference the table.

290	6.3.  References

292	   Pandoc provides a syntax that can be used for references.  Its syntax
293	   is repeated in this paragraph.  Any reference like: "[Click
294	   here](URI)", is an external reference.  An internal (i.e.  see
295	   Section X) reference is typeset with: "[Click here](#localid)" or
296	   "[](#localid)".

298	   For referencing RFCs (and other citations), you will need add the
299	   reference source in the template, as an external XML entity, Figure 2
300	   provides an example.  After that you can use: "[](#RFC2629)"

302	   Note that referencing figures/artworks and tables is done slightly
303	   different.  The reason for this is that Pandoc does not have native
304	   support/syntax for this.  We work around it, by "faking" the
305	   reference in the XSLT.  Thus for referencing figures/artworks and
306	   tables, you need:

308	   o  To take the first 10 characters of the caption (i.e.  this is the
309	      text _after_ the string "Table: " or "@Figure: ");

311	   o  Translate spaces and single quotes ' to a minus "-";

313	   o  Translate uppercase letters to lowercase;

315	   o  For tables prefix the anchor with "tab:" and for figures use
316	      "fig:".

318	   The figure from Section 2 will get "fig:a-very-min" as an anchor.

320	   Note that duplicate anchors are an XML validation error which will
321	   make xml2rfc fail.  These are not detected during the XSL
322	   transformation.

324	6.4.  Indexes

326	   The footnote syntax of Pandoc is slightly abused to support an index.
327	   Sub items are also supported.  Use an exclamation mark ("!") to
328	   separate them:

330	   [^1]: item!sub item

332	7.  Acknowledgements

334	   The following people have helped shape Pandoc2rfc: Benno Overeinder,
335	   Erlend Hamnaberg, Matthijs Mekking and Trygve Laugstoel.

337	   This document was prepared using Pandoc2rfc.

339	8.  Security Considerations

341	   This document raises no security issues.

343	9.  IANA Considerations

345	   This document has no actions for IANA.

347	10.  Normative References

349	   [Markdown]
350	              Gruber, J., "Markdown", 2004,
351	              <http://daringfireball.net/projects/markdown/>.

353	   [Pandoc2rfc]
354	              Gieben, R., "Pandoc2rfc git repository", October 2012,
355	              <http://github.com/miekg/pandoc2rfc>.

357	   [Pandoc]   MacFarlane, J., "Pandoc, a universal document converter",
358	              2006, <http://johnmacfarlane.net/pandoc/>.

360	   [RFC2629]  Rose, M.T., "Writing I-Ds and RFCs using XML", RFC 2629,
361	              June 1999.

363	   [W3C.REC-xslt-19991116]
364	              Clark, J., "XSL Transformations (XSLT) Version 1.0", World
365	              Wide Web Consortium Recommendation REC-xslt-19991116,
366	              November 1999,
367	              <http://www.w3.org/TR/1999/REC-xslt-19991116>.

369	   [XSLT]     Veillard, D., "The XSLT C library for GNOME", 2006,
370	              <http://xmlsoft.org/XSLT/xsltproc2.html>.

372	Appendix A.  Changelog

374	   [This section should be removed by the RFC editor before publishing]

376	A.1.  -00

378	   1.  Initial document.

380	A.2.  -01

382	   1.  Lots of updates;

384	   2.  Added the stylesheet use in an appendix.

386	Appendix B.  Cheat Sheet

388	   +--------------------+------------------+---------------------------+
389	   | Textual construct  | Pandoc syntax    | xml2rfc Syntax            |
390	   +--------------------+------------------+---------------------------+
391	   | Section Header     | "# Section"      | "<section title= ...>"    |
392	   | Unordered List     | "* item"         | "<list style="symbols">"  |
393	   | Unordered List     | "#. item"        | "<list style="empty">"    |
394	   | Ordered List       | "1. item"        | "<list style="numbers">"  |
395	   | Ordered List       | "a.  item"       | "<list style="letters">"  |
396	   | Ordered List       | "ii. item"       | "<list style="format      |
397	   |                    |                  | %i">"                     |
398	   | Ordered List       | "II. item"       | "<list style="format      |
399	   |                    |                  | (%d)">"                   |
400	   | Ordered List       | "A.  item"       | "<list style="format      |
401	   |                    |                  | (%C)">"                   |
402	   | Definition List    | Definition       | "<list style="hanging">"  |
403	   | Emphasis           | "_text_"         | "<spanx style="emph">"    |
404	   | Strong Emphasis    | "**text**"       | "<spanx style="strong">"  |
405	   | Verbatim           | "`text`"         | "<spanx style="verb">"    |
406	   | Block Quote        | "> quote"        | "<list style="hanging">"  |
407	   | Index              | Footnotes        | "<iref item="index"/>"    |
408	   | Table              | Tables           | "<texttable>"             |
409	   | Figure/Artwork     | Code Blocks      | "<figure><artwork>"       |
410	   | External Reference | "[Click](URI)"   | "<eref target="..."/>"    |
411	   | Internal Reference | "[](#id)"        | "<xref target="id">"      |
412	   | Figure Reference   | "[](#fig:...)"   | "<xref target="..."/>"    |
413	   | Table Reference    | "[](#tab:...)"   | "<xref target="..."/>"    |
414	   | Citations          | "[](#RFC2119)"   | "<xref target="RFC2119">" |
415	   +--------------------+------------------+---------------------------+

417	   The most important textual constructs that can be used in Pandoc2rfc.

419	                                  Table 1

421	Appendix C.  XSLT

423	   This is the XSLT with Git version
424	   "f0cc985e291ae25a24c91934b8192930df1ad6f6", that is used for the
425	   transformation.

427	   <?xml version="1.0"?>
428	   <!-- vim: set shiftwidth=1 tabstop=1: -->
429	   <xsl:stylesheet
430	    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
431	    xmlns:exsl="http://exslt.org/common" version="1.0"
432	    extension-element-prefixes="exsl">
433	   <!--
434	       (c) Miek Gieben 2013, Licensed under the GPL version 2.
435	   -->
436	     <xsl:output method="xml" omit-xml-declaration="yes"/>
437	     <xsl:variable name="smallcase" select="'abcdefghijklmnopqrstuvwxyz'"/>
438	     <xsl:variable name="uppercase" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"/>
439	     <xsl:variable name="ure" select="'igure: '"/>
440	     <xsl:variable name="Fig" select="concat('@F', $ure)"/>
441	     <xsl:variable name="fig" select="concat('@f', $ure)"/>
442	     <xsl:template match="/">
443	      <xsl:comment>
444	       This document was prepared using Pandoc2rfc
445	       https://github.com/miekg/pandoc2rfc
446	      </xsl:comment>
447	      <xsl:apply-templates/>
448	     </xsl:template>
449	     <xsl:template match="article">
450	      <xsl:apply-templates/>
451	     </xsl:template>
452	   <!--
453	   Remove the article info section, this should be handled
454	   in the <front> matter of the draft
455	   -->
456	     <xsl:template match="articleinfo">
457	     </xsl:template>
458	   <!-- Use footnotes for indexes (iref) -->
459	     <xsl:template match="footnote">
460	      <xsl:element name="iref">
461	       <xsl:choose>
462	        <xsl:when test="contains(./para, '!')">
463	         <xsl:attribute name="item">
464	          <xsl:value-of select="substring-before (normalize-space(
465	           translate(./para, '&#10;', ' ')), '!')"/>
466	         </xsl:attribute>
467	         <xsl:attribute name="subitem">
468	          <xsl:value-of select="substring-after (normalize-space(
469	           translate(./para, '&#10;', ' ')), '!')"/>
470	         </xsl:attribute>
471	        </xsl:when>
472	        <xsl:otherwise>
473	         <xsl:attribute name="item">
474	          <xsl:value-of select="normalize-space(
475	           translate(./para, '&#10;', ' '))"/>

477	         </xsl:attribute>
478	        </xsl:otherwise>
479	       </xsl:choose>
480	      </xsl:element>
481	     </xsl:template>
482	   <!-- Merge section with the title tags into one section -->
483	     <xsl:template match="section | simplesect |
484	      sect1 | sect2 | sect3 | sect4 | sect5">
485	      <section>
486	       <xsl:attribute name="title">
487	        <xsl:value-of select="normalize-space(
488	         translate(./title, '&#10;', ' '))"/>
489	       </xsl:attribute>
490	       <xsl:attribute name="anchor">
491	        <xsl:value-of select="@id"/>
492	       </xsl:attribute>
493	       <xsl:apply-templates/>
494	      </section>
495	     </xsl:template>
496	   <!--
497	   Transform a <para> to <t>, not in lists, then it is discarded
498	   -->
499	     <xsl:template match="para | simpara">
500	      <xsl:choose>
501	       <xsl:when test="ancestor::orderedlist">
502	        <xsl:if test="position() &gt; 2">
503	         <vspace blankLines="1"/>
504	        </xsl:if>
505	        <xsl:apply-templates/>
506	       </xsl:when>
507	       <xsl:when test="ancestor::itemizedlist">
508	        <xsl:if test="position() &gt; 2">
509	         <vspace blankLines="1"/>
510	        </xsl:if>
511	        <xsl:apply-templates/>
512	       </xsl:when>
513	       <xsl:when test="ancestor::variablelist">
514	        <xsl:if test="position() &gt; 2">
515	         <vspace blankLines="1"/>
516	        </xsl:if>
517	        <xsl:apply-templates/>
518	       </xsl:when>
519	       <xsl:when test="ancestor::tbody">
520	        <xsl:apply-templates/>
521	       </xsl:when>
522	       <xsl:otherwise>
523	        <t>
524	         <xsl:apply-templates/>

526	        </t>
527	       </xsl:otherwise>
528	      </xsl:choose>
529	     </xsl:template>
530	   <!--
531	   Transform a <listitem> to a <t> for lists, except in description lists
532	   -->
533	     <xsl:template match="listitem">
534	      <xsl:choose>
535	       <xsl:when test="parent::varlistentry">
536	        <xsl:apply-templates/>
537	       </xsl:when>
538	       <xsl:otherwise>
539	        <t>
540	         <xsl:apply-templates/>
541	        </t>
542	       </xsl:otherwise>
543	      </xsl:choose>
544	     </xsl:template>
545	   <!--
546	   Transform lists, for lists in list we do not put it in a new <t></t>
547	   -->
548	     <xsl:template match="orderedlist">
549	      <xsl:choose>
550	       <xsl:when test="contains(@numeration,'arabic')">
551	        <xsl:choose>
552	         <xsl:when test="ancestor::orderedlist">
553	          <list style="numbers">
554	           <xsl:apply-templates/>
555	          </list>
556	         </xsl:when>
557	         <xsl:when test="ancestor::itemizedlist">
558	          <list style="numbers">
559	           <xsl:apply-templates/>
560	          </list>
561	         </xsl:when>
562	         <xsl:when test="ancestor::variablelist">
563	          <list style="numbers">
564	           <xsl:apply-templates/>
565	          </list>
566	         </xsl:when>
567	         <xsl:otherwise>
568	          <t>
569	           <list style="numbers">
570	            <xsl:apply-templates/>
571	           </list>
572	          </t>
573	         </xsl:otherwise>

575	        </xsl:choose>
576	       </xsl:when>
577	       <xsl:when test="contains(@numeration,'lowerroman')">
578	        <xsl:choose>
579	         <xsl:when test="ancestor::orderedlist">
580	          <list style="format %i.">
581	           <xsl:apply-templates/>
582	          </list>
583	         </xsl:when>
584	         <xsl:when test="ancestor::itemizedlist">
585	          <list style="format %i.">
586	           <xsl:apply-templates/>
587	          </list>
588	         </xsl:when>
589	         <xsl:when test="ancestor::variablelist">
590	          <list style="format %i.">
591	           <xsl:apply-templates/>
592	          </list>
593	         </xsl:when>
594	         <xsl:otherwise>
595	          <t>
596	           <list style="format %i.">
597	            <xsl:apply-templates/>
598	           </list>
599	          </t>
600	         </xsl:otherwise>
601	        </xsl:choose>
602	       </xsl:when>
603	       <xsl:when test="contains(@numeration,'upperroman')">
604	        <xsl:choose>
605	         <xsl:when test="ancestor::orderedlist">
606	          <list style="format (%d)">
607	           <xsl:apply-templates/>
608	          </list>
609	         </xsl:when>
610	         <xsl:when test="ancestor::itemizedlist">
611	          <list style="format (%d)">
612	           <xsl:apply-templates/>
613	          </list>
614	         </xsl:when>
615	         <xsl:when test="ancestor::variablelist">
616	          <list style="format (%d)">
617	           <xsl:apply-templates/>
618	          </list>
619	         </xsl:when>
620	         <xsl:otherwise>
621	          <t>
622	           <list style="format (%d)">
623	            <xsl:apply-templates/>
624	           </list>
625	          </t>
626	         </xsl:otherwise>
627	        </xsl:choose>
628	       </xsl:when>
629	       <xsl:when test="contains(@numeration,'upperalpha')">
630	        <xsl:choose>
631	         <xsl:when test="ancestor::orderedlist">
632	          <list style="format %C.">
633	           <xsl:apply-templates/>
634	          </list>
635	         </xsl:when>
636	         <xsl:when test="ancestor::itemizedlist">
637	          <list style="format %C.">
638	           <xsl:apply-templates/>
639	          </list>
640	         </xsl:when>
641	         <xsl:when test="ancestor::variablelist">
642	          <list style="format %C.">
643	           <xsl:apply-templates/>
644	          </list>
645	         </xsl:when>
646	         <xsl:otherwise>
647	          <t>
648	           <list style="format %C.">
649	            <xsl:apply-templates/>
650	           </list>
651	          </t>
652	         </xsl:otherwise>
653	        </xsl:choose>
654	       </xsl:when>
655	       <xsl:when test="contains(@numeration,'loweralpha')">
656	        <xsl:choose>
657	         <xsl:when test="ancestor::orderedlist">
658	          <list style="letters">
659	           <xsl:apply-templates/>
660	          </list>
661	         </xsl:when>
662	         <xsl:when test="ancestor::itemizedlist">
663	          <list style="letters">
664	           <xsl:apply-templates/>
665	          </list>
666	         </xsl:when>
667	         <xsl:when test="ancestor::variablelist">
668	          <list style="letters">
669	           <xsl:apply-templates/>
670	          </list>

672	         </xsl:when>
673	         <xsl:otherwise>
674	          <t>
675	           <list style="letters">
676	            <xsl:apply-templates/>
677	           </list>
678	          </t>
679	         </xsl:otherwise>
680	        </xsl:choose>
681	       </xsl:when>
682	       <xsl:otherwise>
683	        <xsl:choose>
684	         <xsl:when test="ancestor::orderedlist">
685	          <list style="empty">
686	           <xsl:apply-templates/>
687	          </list>
688	         </xsl:when>
689	         <xsl:when test="ancestor::itemizedlist">
690	          <list style="empty">
691	           <xsl:apply-templates/>
692	          </list>
693	         </xsl:when>
694	         <xsl:when test="ancestor::variablelist">
695	          <list style="empty">
696	           <xsl:apply-templates/>
697	          </list>
698	         </xsl:when>
699	         <xsl:otherwise>
700	          <t>
701	           <list style="empty">
702	            <xsl:apply-templates/>
703	           </list>
704	          </t>
705	         </xsl:otherwise>
706	        </xsl:choose>
707	       </xsl:otherwise>
708	      </xsl:choose>
709	     </xsl:template>
710	     <xsl:template match="itemizedlist">
711	      <xsl:choose>
712	       <xsl:when test="ancestor::orderedlist">
713	        <list style="symbols">
714	         <xsl:apply-templates/>
715	        </list>
716	       </xsl:when>
717	       <xsl:when test="ancestor::itemizedlist">
718	        <list style="symbols">
719	         <xsl:apply-templates/>

721	        </list>
722	       </xsl:when>
723	       <xsl:when test="ancestor::variablelist">
724	        <list style="symbols">
725	         <xsl:apply-templates/>
726	        </list>
727	       </xsl:when>
728	       <xsl:otherwise>
729	        <t>
730	         <list style="symbols">
731	          <xsl:apply-templates/>
732	         </list>
733	        </t>
734	       </xsl:otherwise>
735	      </xsl:choose>
736	     </xsl:template>
737	   <!--
738	   Hanging lists are specified as <variablelist>
739	   -->
740	     <xsl:template match="variablelist">
741	      <xsl:choose>
742	       <xsl:when test="ancestor::orderedlist">
743	        <list style="hanging">
744	         <xsl:apply-templates/>
745	        </list>
746	       </xsl:when>
747	       <xsl:when test="ancestor::itemizedlist">
748	        <list style="hanging">
749	         <xsl:apply-templates/>
750	        </list>
751	       </xsl:when>
752	       <xsl:when test="ancestor::variablelist">
753	        <list style="hanging">
754	         <xsl:apply-templates/>
755	        </list>
756	       </xsl:when>
757	       <xsl:otherwise>
758	        <t>
759	         <list style="hanging">
760	          <xsl:apply-templates/>
761	         </list>
762	        </t>
763	       </xsl:otherwise>
764	      </xsl:choose>
765	     </xsl:template>
766	     <xsl:template match="varlistentry">
767	      <t>
768	       <xsl:attribute name="hangText">
769	        <xsl:value-of select="normalize-space(translate(./term,
770	         ' &#9;&#13;&#10;', ' '))"/>
771	       </xsl:attribute>
772	   <!--
773	   OPTION: enable this to get a newline after the hangText
774	   -->
775	   <!-- <xsl:element name="vspace"/> -->
776	       <xsl:apply-templates select="./listitem"/>
777	      </t>
778	     </xsl:template>
779	   <!--
780	   Transform <link> to <xref> crosslinks
781	   -->
782	     <xsl:template match="link">
783	      <xref>
784	       <xsl:attribute name="target">
785	        <xsl:value-of select="@linkend"/>
786	       </xsl:attribute>
787	       <xsl:apply-templates/>
788	      </xref>
789	     </xsl:template>
790	   <!--
791	   Transform <ulink> to <eref> links
792	   -->
793	     <xsl:template match="ulink">
794	      <eref>
795	       <xsl:attribute name="target">
796	        <xsl:value-of select="@url"/>
797	       </xsl:attribute>
798	       <xsl:apply-templates/>
799	      </eref>
800	     </xsl:template>
801	   <!--
802	   Transform <blockquote> to <list style="hanging">
803	   -->
804	     <xsl:template match="blockquote">
805	      <t>
806	       <list style="hanging" hangIndent="3">
807	        <xsl:apply-templates/>
808	       </list>
809	      </t>
810	     </xsl:template>
811	   <!--
812	   Transform <screen> and <programlisting> to <figure><artwork>
813	   -->
814	     <xsl:template match="screen | programlisting">
815	      <figure>
816	       <xsl:choose>
817	        <xsl:when test="contains(., $Fig)">
818	         <xsl:attribute name="anchor">
819	          <xsl:text>fig:</xsl:text>
820	          <xsl:value-of select="translate(
821	           translate(substring(normalize-space(
822	           translate( substring-after(., $Fig) ,
823	           &quot;&#10;'&quot;, &quot;  &quot;)), 1, 10),
824	           &quot; &quot;, &quot;-&quot;), $uppercase, $smallcase)"/>
825	         </xsl:attribute>
826	   <!-- If there is an caption, center the figure -->
827	             <xsl:attribute name="align">
828	              <xsl:text>center</xsl:text>
829	             </xsl:attribute>
830	             <artwork>
831	              <xsl:value-of select="substring-before(., $Fig)"/>
832	             </artwork>
833	             <postamble>
834	              <xsl:value-of select="substring-after(., $Fig)"/>
835	             </postamble>
836	            </xsl:when>
837	            <xsl:when test="contains(., $fig)">
838	             <xsl:attribute name="anchor">
839	              <xsl:text>fig:</xsl:text>
840	              <xsl:value-of select="translate(
841	               translate(substring(normalize-space(
842	               translate( substring-after(., $fig) ,
843	               &quot;&#10;'&quot;, &quot;  &quot;)), 1, 10),
844	               &quot; &quot;, &quot;-&quot;), $uppercase, $smallcase)"/>
845	             </xsl:attribute>
846	             <artwork>
847	              <xsl:value-of select="substring-before(., $fig)"/>
848	             </artwork>
849	             <postamble>
850	              <xsl:value-of select="substring-after(., $fig)"/>
851	             </postamble>
852	            </xsl:when>
853	            <xsl:otherwise>
854	             <artwork>
855	              <xsl:value-of select="."/>
856	             </artwork>
857	            </xsl:otherwise>
858	           </xsl:choose>
859	          </figure>
860	         </xsl:template>
861	         <xsl:template match="title"/>
862	         <xsl:template match="literal">
863	          <spanx style="verb">
864	           <xsl:apply-templates/>

866	          </spanx>
867	         </xsl:template>
868	         <xsl:template match="emphasis">
869	          <xsl:choose>
870	           <xsl:when test="contains(@role,'strong')">
871	            <spanx style="strong">
872	             <xsl:apply-templates/>
873	            </spanx>
874	           </xsl:when>
875	           <xsl:otherwise>
876	            <spanx style="emph">
877	             <xsl:apply-templates/>
878	            </spanx>
879	           </xsl:otherwise>
880	          </xsl:choose>
881	         </xsl:template>
882	         <xsl:template match="literal" mode="post">
883	          <spanx style="verb">
884	           <xsl:apply-templates mode="post"/>
885	          </spanx>
886	         </xsl:template>
887	         <xsl:template match="emphasis" mode="post">
888	          <xsl:choose>
889	           <xsl:when test="contains(@role,'strong')">
890	            <spanx style="strong">
891	             <xsl:apply-templates mode="post"/>
892	            </spanx>
893	           </xsl:when>
894	           <xsl:otherwise>
895	            <spanx style="emph">
896	             <xsl:apply-templates mode="post"/>
897	            </spanx>
898	           </xsl:otherwise>
899	          </xsl:choose>
900	         </xsl:template>
901	   <!-- Tables -->
902	     <xsl:template match="table | informaltable">
903	      <texttable>
904	   <!-- If there is a caption, fake an anchor attribute -->
905	         <xsl:if test="./caption">
906	          <xsl:attribute name="anchor">
907	           <xsl:text>tab:</xsl:text>
908	           <xsl:value-of select="translate(
909	            translate(substring(normalize-space(translate(
910	            ./caption, &quot;&#10;'&quot;, &quot;  &quot;)), 1, 10),
911	            &quot; &quot;, &quot;-&quot;), $uppercase, $smallcase)"/>
912	          </xsl:attribute>
913	         </xsl:if>
914	         <xsl:if test="./title">
915	          <xsl:attribute name="anchor">
916	           <xsl:text>tab:</xsl:text>
917	           <xsl:value-of select="translate( translate(
918	            substring(normalize-space(translate(./title,
919	            &quot;&#10;'&quot;, &quot;  &quot;)), 1, 10),
920	            &quot; &quot;, &quot;-&quot;), $uppercase, $smallcase)"/>
921	          </xsl:attribute>
922	         </xsl:if>
923	         <xsl:apply-templates/>
924	         <xsl:if test="./title">
925	   <!-- create postamble of the title -->
926	           <postamble>
927	            <xsl:apply-templates select="./title" mode="post"/>
928	           </postamble>
929	          </xsl:if>
930	          <xsl:if test="./caption">
931	   <!-- create postamble of the caption -->
932	           <postamble>
933	            <xsl:apply-templates select="./caption" mode="post"/>
934	           </postamble>
935	          </xsl:if>
936	         </texttable>
937	        </xsl:template>
938	   <!-- Table headers -->
939	     <xsl:template match="table/thead/tr/th |
940	      informaltable/thead/tr/th">
941	      <ttcol>
942	       <xsl:attribute name="align">
943	        <xsl:value-of select="@align"/>
944	       </xsl:attribute>
945	   <!--
946	   Every even position() need to be dealt with:
947	   2 look back to 1, 4 look back to 2, etc.
948	   -->
949	         <xsl:if test="position() = 2">
950	          <xsl:call-template name="get_col">
951	           <xsl:with-param name="column" select="1"/>
952	          </xsl:call-template>
953	         </xsl:if>
954	         <xsl:if test="position() = 4">
955	          <xsl:call-template name="get_col">
956	           <xsl:with-param name="column" select="2"/>
957	          </xsl:call-template>
958	         </xsl:if>
959	         <xsl:if test="position() = 6">
960	          <xsl:call-template name="get_col">
961	           <xsl:with-param name="column" select="3"/>

963	          </xsl:call-template>
964	         </xsl:if>
965	         <xsl:if test="position() = 8">
966	          <xsl:call-template name="get_col">
967	           <xsl:with-param name="column" select="4"/>
968	          </xsl:call-template>
969	         </xsl:if>
970	         <xsl:if test="position() = 10">
971	          <xsl:call-template name="get_col">
972	           <xsl:with-param name="column" select="5"/>
973	          </xsl:call-template>
974	         </xsl:if>
975	         <xsl:if test="position() = 12">
976	          <xsl:call-template name="get_col">
977	           <xsl:with-param name="column" select="6"/>
978	          </xsl:call-template>
979	         </xsl:if>
980	         <xsl:if test="position() = 14">
981	          <xsl:call-template name="get_col">
982	           <xsl:with-param name="column" select="7"/>
983	          </xsl:call-template>
984	         </xsl:if>
985	         <xsl:if test="position() = 16">
986	          <xsl:call-template name="get_col">
987	           <xsl:with-param name="column" select="8"/>
988	          </xsl:call-template>
989	         </xsl:if>
990	         <xsl:apply-templates/>
991	        </ttcol>
992	       </xsl:template>
993	       <xsl:template name="get_col">
994	        <xsl:param name="column"/>
995	        <xsl:if test="../../../col[$column]">
996	         <xsl:attribute name="width">
997	          <xsl:value-of select="../../../col[$column]/@width"/>
998	         </xsl:attribute>
999	        </xsl:if>
1000	       </xsl:template>
1001	   <!-- Table headers for CALS tables -->
1002	     <xsl:template match="table/tgroup/thead/row/entry">
1003	      <ttcol>
1004	       <xsl:if test="position() = 2">
1005	        <xsl:call-template name="get_colspec">
1006	         <xsl:with-param name="column" select="1"/>
1007	        </xsl:call-template>
1008	       </xsl:if>
1009	       <xsl:if test="position() = 4">
1010	        <xsl:call-template name="get_colspec">
1011	         <xsl:with-param name="column" select="2"/>
1012	        </xsl:call-template>
1013	       </xsl:if>
1014	       <xsl:if test="position() = 6">
1015	        <xsl:call-template name="get_colspec">
1016	         <xsl:with-param name="column" select="3"/>
1017	        </xsl:call-template>
1018	       </xsl:if>
1019	       <xsl:if test="position() = 8">
1020	        <xsl:call-template name="get_colspec">
1021	         <xsl:with-param name="column" select="4"/>
1022	        </xsl:call-template>
1023	       </xsl:if>
1024	       <xsl:if test="position() = 10">
1025	        <xsl:call-template name="get_colspec">
1026	         <xsl:with-param name="column" select="5"/>
1027	        </xsl:call-template>
1028	       </xsl:if>
1029	       <xsl:if test="position() = 12">
1030	        <xsl:call-template name="get_colspec">
1031	         <xsl:with-param name="column" select="6"/>
1032	        </xsl:call-template>
1033	       </xsl:if>
1034	       <xsl:if test="position() = 14">
1035	        <xsl:call-template name="get_colspec">
1036	         <xsl:with-param name="column" select="7"/>
1037	        </xsl:call-template>
1038	       </xsl:if>
1039	       <xsl:if test="position() = 16">
1040	        <xsl:call-template name="get_colspec">
1041	         <xsl:with-param name="column" select="8"/>
1042	        </xsl:call-template>
1043	       </xsl:if>
1044	   <!-- If the entry itself has align, we use that -->
1045	         <xsl:if test="@align">
1046	          <xsl:attribute name="align">
1047	           <xsl:value-of select="@align"/>
1048	          </xsl:attribute>
1049	         </xsl:if>
1050	         <xsl:apply-templates/>
1051	        </ttcol>
1052	       </xsl:template>
1053	       <xsl:template name="get_colspec">
1054	        <xsl:param name="column"/>
1055	        <xsl:if test="../../../../tgroup/colspec[$column]">
1056	         <xsl:attribute name="align">
1057	          <xsl:value-of
1058	           select="../../../../tgroup/colspec[$column]/@align"/>

1060	         </xsl:attribute>
1061	   <!-- Optionally colwidth, translate * to % -->
1062	         <xsl:if test="../../../../tgroup/colspec[$column]/@colwidth">
1063	          <xsl:attribute name="width">
1064	           <xsl:value-of select="translate(
1065	            ../../../../tgroup/colspec[$column]/@colwidth, '*', '%')"/>
1066	          </xsl:attribute>
1067	         </xsl:if>
1068	        </xsl:if>
1069	       </xsl:template>
1070	   <!-- Table headers for CALS tables, Pandoc 1.9.x+ -->
1071	     <xsl:template match="informaltable/tgroup/thead/row/entry">
1072	      <ttcol>
1073	       <xsl:if test="position() = 2">
1074	        <xsl:call-template name="get_colspec_informal">
1075	         <xsl:with-param name="column" select="1"/>
1076	        </xsl:call-template>
1077	       </xsl:if>
1078	       <xsl:if test="position() = 4">
1079	        <xsl:call-template name="get_colspec_informal">
1080	         <xsl:with-param name="column" select="2"/>
1081	        </xsl:call-template>
1082	       </xsl:if>
1083	       <xsl:if test="position() = 6">
1084	        <xsl:call-template name="get_colspec_informal">
1085	         <xsl:with-param name="column" select="3"/>
1086	        </xsl:call-template>
1087	       </xsl:if>
1088	       <xsl:if test="position() = 8">
1089	        <xsl:call-template name="get_colspec_informal">
1090	         <xsl:with-param name="column" select="4"/>
1091	        </xsl:call-template>
1092	       </xsl:if>
1093	       <xsl:if test="position() = 10">
1094	        <xsl:call-template name="get_colspec_informal">
1095	         <xsl:with-param name="column" select="5"/>
1096	        </xsl:call-template>
1097	       </xsl:if>
1098	       <xsl:if test="position() = 12">
1099	        <xsl:call-template name="get_colspec_informal">
1100	         <xsl:with-param name="column" select="6"/>
1101	        </xsl:call-template>
1102	       </xsl:if>
1103	       <xsl:if test="position() = 14">
1104	        <xsl:call-template name="get_colspec_informal">
1105	         <xsl:with-param name="column" select="7"/>
1106	        </xsl:call-template>
1107	       </xsl:if>
1108	       <xsl:if test="position() = 16">
1109	        <xsl:call-template name="get_colspec_informal">
1110	         <xsl:with-param name="column" select="8"/>
1111	        </xsl:call-template>
1112	       </xsl:if>
1113	   <!-- If the entry itself has align, we use that -->
1114	         <xsl:if test="@align">
1115	          <xsl:attribute name="align">
1116	           <xsl:value-of select="@align"/>
1117	          </xsl:attribute>
1118	         </xsl:if>
1119	         <xsl:apply-templates/>
1120	        </ttcol>
1121	       </xsl:template>
1122	       <xsl:template name="get_colspec_informal">
1123	        <xsl:param name="column"/>
1124	        <xsl:if test="../../../../tgroup/colspec[$column]">
1125	         <xsl:attribute name="align">
1126	          <xsl:value-of
1127	           select="../../../../tgroup/colspec[$column]/@align"/>
1128	         </xsl:attribute>
1129	   <!-- Optionally colwidth, translate * to % -->
1130	         <xsl:if test="../../../../tgroup/colspec[$column]/@colwidth">
1131	          <xsl:attribute name="width">
1132	           <xsl:value-of
1133	            select="translate(
1134	            ../../../../tgroup/colspec[$column]/@colwidth,
1135	            '*', '%')"/>
1136	          </xsl:attribute>
1137	         </xsl:if>
1138	        </xsl:if>
1139	       </xsl:template>
1140	       <xsl:template match="table/tbody/tr/td |
1141	        informaltable/tbody/tr/td |
1142	        table/tgroup/tbody/row/entry |
1143	        informaltable/tgroup/tbody/row/entry">
1144	        <c>
1145	         <xsl:apply-templates/>
1146	        </c>
1147	       </xsl:template>
1148	   <!-- CALS table -->
1149	     <xsl:template match="table/tbody/row/entry">
1150	      <c>
1151	       <xsl:apply-templates/>
1152	      </c>
1153	     </xsl:template>
1154	    </xsl:stylesheet>

1156	   XSLT used for the transformation.

1158	                                 Figure 4

1160	Author's Address

1162	   R. (Miek) Gieben
1163	   Google

1165	   Email: miek@google.com