1<?xml version="1.0" encoding="utf-8"?> 2<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [ 3<!ENTITY pandocMiddle PUBLIC "" "README.xml"> 4<!ENTITY pandocBack PUBLIC "" "back.xml"> 5<!ENTITY pandocRefVim PUBLIC "" "bib/reference.github.vim.xml"> 6<!ENTITY pandocRef2119 PUBLIC "" "bib/reference.RFC.2119.xml"> 7<!ENTITY pandocRef4641 PUBLIC "" "bib/reference.RFC.4641.xml"> 8]> 9<rfc ipr="trust200902" category="info" docName="draft-gieben-writing-rfcs-pandoc-02" obsoletes="" updates="" submissionType="IETF" xml:lang="en"> 10 <?rfc toc="yes"?> 11 <!--generate a table of contents --> 12 <?rfc symrefs="yes"?> 13 <!--use anchors instead of numbers for references --> 14 <?rfc sortrefs="yes" ?> 15 <!--alphabetize the references --> 16 <?rfc compact="yes" ?> 17 <!--conserve vertical whitespace --> 18 <?rfc subcompact="no" ?> 19 <!--but keep a blank line between list items --> 20 <front> 21 <title abbrev="Pandoc2rfc Version 2">Writing I-Ds and RFCs using Pandoc and xml2rfc 2.x</title> 22 <author initials="R." surname="Gieben" fullname="R. (Miek) Gieben"> 23 <organization>Google</organization> 24 <address> 25 <postal> 26 <street>123 Buckingham Palace Road</street> 27 <street/> 28 <city>London</city> 29 <region/> 30 <code>SW1W 9SH</code> 31 <country>UK</country> 32 </postal> 33 <phone/> 34 <email>miek@miek.nl</email> 35 <uri>http://miek.nl/</uri> 36 </address> 37 </author> 38 <?v3xml2rfc silence="The document date .*? is more than 3 days away from today's date" ?> 39 <date month="January" year="2013" day="1"/> 40 <area>General</area> 41 <workgroup>RFC Beautification Working Group</workgroup> 42 <keyword>RFC</keyword> 43 <keyword>Request for Comments</keyword> 44 <keyword>I-D</keyword> 45 <keyword>Internet-Draft</keyword> 46 <keyword>XML</keyword> 47 <keyword>Pandoc</keyword> 48 <keyword>Extensible Markup Language</keyword> 49 <abstract> 50 <t> 51 This memo presents a technique for using Pandoc syntax as a source 52 format for documents in the Internet-Drafts (I-Ds) and Request for 53 Comments (RFC) series. 54 </t> 55 <t> 56 This version is adapted to work with "xml2rfc" version 2.x. 57 </t> 58 </abstract> 59 </front> 60 <middle> 61 <!--This document was prepared using Pandoc2rfc https://github.com/miekg/pandoc2rfc --> 62 <section title="Introduction" anchor="introduction" toc="default"> 63 <t> 64 This document presents a technique for using Pandoc syntax as a 65 source format for documents in the Internet-Drafts (I-Ds) and 66 Request for Comments (RFC) series. 67 </t> 68 <t> 69 This version is adapted to work with 70 <spanx style="verb" xml:space="preserve">xml2rfc</spanx> version 2.x. 71 </t> 72 <t> 73 Pandoc is an "almost plain text" format and therefor particularly 74 well suited for editing RFC-like documents. 75 </t> 76 <t> 77 <list style="empty"> 78 <t> 79 Note: this document is typeset in Pandoc and does not render 80 completely correct when reading it on github. 81 </t> 82 </list> 83 </t> 84 </section> 85 <section title="Pandoc to RFC" anchor="pandoc-to-rfc" toc="default"> 86 <t> 87 <list style="empty"> 88 <t> 89 Pandoc2rfc -- designed to do the right thing, until it doesn't. 90 </t> 91 </list> 92 </t> 93 <t> 94 When writing <xref target="RFC4641" pageno="false" format="default"/> 95 we directly wrote the XML. Needless to say it was tedious even thought 96 the XML of <eref target="http://xml.resource.org/experimental">xml2rfc</eref> 97 is very "light". The 98 <eref target="http://pypi.python.org/pypi/xml2rfc/">latest version of xml2rfc version 2 can be found here</eref>. 99 </t> 100 <t> 101 During the last few years people have been developing markup 102 languages that are very easy to remember and type. These languages 103 have become known as 104 <spanx style="verb" xml:space="preserve">almost plain 105 text</spanx>-markup languages. One of the first was the 106 <eref target="http://daringfireball.net/projects/markdown/">Markdown</eref> 107 syntax. One that was developed later and incorporates Markdown and 108 a number of extensions is 109 <eref target="http://johnmacfarlane.net/pandoc/">Pandoc</eref>. The 110 power of Pandoc also comes from the fact that it can be translated 111 to numerous output formats, including, but not limited to: HTML, 112 (plain) Markdown and 113 <spanx style="verb" xml:space="preserve">docbook</spanx> XML. 114 </t> 115 <t> 116 So using Pandoc for writing RFCs seems like a sane choice. As 117 <spanx style="verb" xml:space="preserve">xml2rfc</spanx> uses XML, 118 the easiest way would be to create 119 <spanx style="verb" xml:space="preserve">docbook</spanx> 120 XML and transform that using XSLT. Pandoc2rfc does just that. The 121 conversions are, in some way amusing, as we start off with 122 (almost) plain text, use elaborate XML and end up with plain text 123 again. 124 </t> 125 <figure anchor="fig-attempt-to" align="center" title="Attempt to justify Pandoc2rfc." suppress-title="false" alt="" width="" height=""> 126 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 127+-------------------+ pandoc +---------+ 128| ALMOST PLAIN TEXT | ------> | DOCBOOK | 129+-------------------+ +---------+ 130 | | 131non-existent | | xsltproc 132 faster way | | 133 v v 134 +------------+ xml2rfc +---------+ 135 | PLAIN TEXT | <-------- | XML2RFC | 136 +------------+ +---------+ 137 </artwork> 138 </figure> 139 <t> 140 The XML generated (the output after the 141 <spanx style="verb" xml:space="preserve">xsltproc</spanx> step in 142 <xref target="fig-attempt-to" pageno="false" format="default"/>) 143 is suitable for inclusion in either the 144 <spanx style="verb" xml:space="preserve">middle</spanx> or 145 <spanx style="verb" xml:space="preserve">back</spanx> section of 146 an RFC. The simplest way is to create a template XML file and 147 include the appropriate XML: 148 </t> 149 <figure anchor="fig-a-minimal-" align="center" title="A minimal template.xml." suppress-title="false" alt="" width="" height=""> 150 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 151<?xml version='1.0' ?> 152<!DOCTYPE rfc SYSTEM 'rfc2629.dtd' [ 153<!ENTITY pandocMiddle PUBLIC '' 'middle.xml'> 154<!ENTITY pandocBack PUBLIC '' 'back.xml'> 155]> 156 157<rfc ipr='trust200902' docName='draft-gieben-pandoc-rfcs-02'> 158 <front> 159 <title>Writing I-Ds and RFCs using Pandoc v2</title> 160</front> 161 162<middle> 163 &pandocMiddle; 164</middle> 165 166<back> 167 &pandocBack; 168</back> 169 170</rfc> 171 </artwork> 172 </figure> 173 <t> 174 See the Makefile for an example of this. In this case you need to 175 edit 3 documents: 176 </t> 177 <t> 178 <list style="numbers"> 179 <t> 180 middle.pdc - contains the main body of text; 181 </t> 182 <t> 183 back.pdc - holds appendices and references; 184 </t> 185 <t> 186 template.xml (probably a fairly static file). 187 </t> 188 </list> 189 </t> 190 <t> 191 The draft ( 192 <spanx style="verb" xml:space="preserve">draft.txt</spanx>) you 193 are reading now, is automatically created when you call 194 <spanx style="verb" xml:space="preserve">make</spanx>. The 195 homepage of Pandoc2rfc is 196 <eref target="https://github.com/miekg/pandoc2rfc">this github 197 repository</eref>. 198 </t> 199 <section title="Dependencies" anchor="dependencies" toc="default"> 200 <t> 201 It needs <spanx style="verb" xml:space="preserve">xsltproc</spanx> 202 and <spanx style="verb" xml:space="preserve">pandoc</spanx> to be 203 installed. See the 204 <eref target="http://johnmacfarlane.net/pandoc/README.html">Pandoc 205 user manual for the details</eref> on how to type in Pandoc style. 206 And of course <spanx style="verb" xml:space="preserve">xml2rfc</spanx> 207 version two. 208 </t> 209 <t> 210 When using Pandoc2rfc consider adding the following sentence to 211 an Acknowledgements section: 212 </t> 213 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 214 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 215This document was produced using the Pandoc2rfc tool. 216 </artwork> 217 </figure> 218 </section> 219 </section> 220 <section title="Starting a new project" anchor="starting-a-new-project" toc="default"> 221 <t> 222 When starting a new project with 223 <spanx style="verb" xml:space="preserve">pandoc2rfc</spanx> you'll 224 need to copy the following files: 225 </t> 226 <t> 227 <list style="symbols"> 228 <t> 229 <spanx style="verb" xml:space="preserve">Makefile</spanx> 230 </t> 231 <t> 232 <spanx style="verb" xml:space="preserve">transform.xslt</spanx> 233 </t> 234 <t> 235 And the above mentioned files: <list style="symbols"> 236 <t> 237 <spanx style="verb" xml:space="preserve">middle.pdc</spanx> 238 </t> 239 <t> 240 <spanx style="verb" xml:space="preserve">back.pdc</spanx> 241 </t> 242 <t> 243 <spanx style="verb" xml:space="preserve">template.xml</spanx> 244 </t> 245 </list> 246 </t> 247 </list> 248 </t> 249 <t> 250 After that you can start editing. 251 </t> 252 </section> 253 <section title="Supported Features" anchor="supported-features" toc="default"> 254 <t> 255 <list style="symbols"> 256 <t> 257 Sections with an anchor and title attributes ( 258 <xref target="section" pageno="false" format="default"/>); 259 </t> 260 <t> 261 Lists <list style="symbols"> 262 <t> 263 style=symbols (<xref target="symbol" pageno="false" format="default"/>); 264 </t> 265 <t> 266 style=numbers (<xref target="number" pageno="false" format="default"/>); 267 </t> 268 <t> 269 style=empty (<xref target="empty" pageno="false" format="default"/>); 270 </t> 271 <t> 272 style=format %i, use roman lowercase numerals, (<xref target="roman" pageno="false" format="default"/>); 273 </t> 274 <t> 275 style=format (%d), use roman uppercase numerals (<xref target="roman" pageno="false" format="default"/>); 276 </t> 277 <t> 278 style=letters (lower- and uppercase, <xref target="letter" pageno="false" format="default"/>); 279 </t> 280 <t> 281 style=hanging (<xref target="hanging" pageno="false" format="default"/>); 282 </t> 283 </list> 284 </t> 285 <t> 286 Figure/artwork with a title (<xref target="figureartwork" pageno="false" format="default"/>); 287 </t> 288 <t> 289 Block quote this is converted to 290 <spanx style="verb" xml:space="preserve"><list style="empty"></spanx> 291 paragraph (<xref target="block-quote" pageno="false" format="default"/>); 292 </t> 293 <t> 294 References <list style="symbols"> 295 <t> 296 external (eref) (<xref target="external" pageno="false" format="default"/>); 297 </t> 298 <t> 299 internal (xref) (<xref target="internal" pageno="false" format="default"/>), you can refer to: <list style="symbols"> 300 <t> 301 section (handled by Pandoc, see <xref target="references-1" pageno="false" format="default"/>)); 302 </t> 303 <t> 304 figures (handled by XSLT, see <xref target="references" pageno="false" format="default"/>); 305 </t> 306 <t> 307 tables (handled by XSLT, see <xref target="references-2" pageno="false" format="default"/>). 308 </t> 309 </list> 310 </t> 311 </list> 312 </t> 313 <t> 314 Citations, by using internal references; 315 </t> 316 <t> 317 Spanx style=verb, style=emph and style=strong (<xref target="spanx-styles" pageno="false" format="default"/>); 318 </t> 319 <t> 320 Tables with an anchor and title (<xref target="tables" pageno="false" format="default"/>); 321 </t> 322 <t> 323 Indexes, by using footnotes (<xref target="indexes" pageno="false" format="default"/>). 324 </t> 325 </list> 326 </t> 327 </section> 328 <section title="Unsupported Features" anchor="unsupported-features" toc="default"> 329 <t> 330 <list style="symbols"> 331 <t> 332 Lists inside a table (<spanx style="verb" xml:space="preserve">xml2rfc</spanx> doesn't handle this); 333 </t> 334 <t> 335 Pandoc markup in the caption for figures/artwork. Pandoc markup for table captions <spanx style="emph" xml:space="preserve">is</spanx> supported; 336 </t> 337 <t> 338 crefs: for comments (no input syntax available), use HTML comments: <spanx style="verb" xml:space="preserve"><!-- ... --></spanx>; 339 </t> 340 </list> 341 </t> 342 </section> 343 <section title="Acknowledgements" anchor="acknowledgements" toc="default"> 344 <t> 345 The following people have helped to make Pandoc2rfc what it is today: Benno Overeinder, Erlend Hamnaberg, Matthijs Mekking, Trygve Laugstoel. 346 </t> 347 <t> 348 This document was prepared using Pandoc2rfc. 349 </t> 350 </section> 351 <section title="Pandoc Constructs" anchor="pandoc-constructs" toc="default"> 352 <t> 353 So, what syntax do you need to use to get the correct output? Well, it is 354 <spanx style="emph" xml:space="preserve">just</spanx> Pandoc. The best introduction 355 to the Pandoc style is given in this 356 <eref target="http://johnmacfarlane.net/pandoc/README.html">README from Pandoc itself</eref>. 357 </t> 358 <t> 359 For convenience we list the most important ones in the following sections. 360 </t> 361 <section title="Paragraph" anchor="paragraph" toc="default"> 362 <t> 363 Paragraphs are separated with an empty line. 364 </t> 365 </section> 366 <section title="Section" anchor="section" toc="default"> 367 <t> 368 Just use the normal sectioning commands available in Pandoc, for instance: 369 </t> 370 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 371 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 372# Section1 One 373Bla 374 </artwork> 375 </figure> 376 <t> 377 Converts to: <spanx style="verb" xml:space="preserve"><section title="Section1 378 One" anchor="section1-one"></spanx> If you have another section that is also 379 named "Section1 One", that anchor will be called "section1-one-1", but 380 <spanx style="emph" xml:space="preserve">only</spanx> when the sections are in 381 the <spanx style="emph" xml:space="preserve">same</spanx> source file! 382 </t> 383 <t> 384 Referencing the section is done with <spanx style="verb" xml:space="preserve">see 385 [](#section1-one)</spanx>, as in see <xref target="section" pageno="false" format="default"/>. 386 </t> 387 </section> 388 <section title="List Styles" anchor="list-styles" toc="default"> 389 <t> 390 A good number of styles are supported. 391 </t> 392 <section title="Symbol" anchor="symbol" toc="default"> 393 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 394 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 395A symbol list. 396 397* Item one; 398* Item two. 399 </artwork> 400 </figure> 401 <t> 402 Converts to <spanx style="verb" xml:space="preserve"><list style="symbol"></spanx>: 403 </t> 404 <t> 405 <list style="symbols"> 406 <t> 407 Item one; 408 </t> 409 <t> 410 Item two. 411 </t> 412 </list> 413 </t> 414 </section> 415 <section title="Number" anchor="number" toc="default"> 416 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 417 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 418A numbered list. 419 4201. Item one; 4211. Item two. 422 </artwork> 423 </figure> 424 <t> 425 Converts to <spanx style="verb" xml:space="preserve"><list style="numbers"></spanx>: 426 </t> 427 <t> 428 <list style="numbers"> 429 <t> 430 Item one; 431 </t> 432 <t> 433 Item two. 434 </t> 435 </list> 436 </t> 437 </section> 438 <section title="Empty" anchor="empty" toc="default"> 439 <t> 440 Using the default list markers from Pandoc: 441 </t> 442 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 443 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 444A list using the default list markers. 445 446#. Item one; 447#. Item two. 448 </artwork> 449 </figure> 450 <t> 451 Converts to <spanx style="verb" xml:space="preserve"><list style="empty"></spanx>: 452 </t> 453 <t> 454 <list style="empty"> 455 <t> 456 Item one; 457 </t> 458 <t> 459 Item two. 460 </t> 461 </list> 462 </t> 463 </section> 464 <section title="Roman" anchor="roman" toc="default"> 465 <t> 466 Use the supported Pandoc syntax: 467 </t> 468 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 469 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 470ii. Item one; 471ii. Item two. 472 </artwork> 473 </figure> 474 <t> 475 Converts to <spanx style="verb" xml:space="preserve"><list style="format %i."></spanx>: 476 </t> 477 <t> 478 <list style="format %i."> 479 <t> 480 Item one; 481 </t> 482 <t> 483 Item two. 484 </t> 485 </list> 486 </t> 487 <t> 488 If you use uppercase Roman numerals, they convert to a different style: 489 </t> 490 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 491 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 492II. Item one; 493II. Item two. 494 </artwork> 495 </figure> 496 <t> 497 Yields <spanx style="verb" xml:space="preserve"><list style="format (%d) "></spanx>: 498 </t> 499 <t> 500 <list style="format (%d)"> 501 <t> 502 Item one; 503 </t> 504 <t> 505 Item two. 506 </t> 507 </list> 508 </t> 509 </section> 510 <section title="Letter" anchor="letter" toc="default"> 511 <t> 512 A numbered list. 513 </t> 514 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 515 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 516a. Item one; 517b. Item two. 518 </artwork> 519 </figure> 520 <t> 521 Converts to <spanx style="verb" xml:space="preserve"><list style="letters"></spanx>: 522 </t> 523 <t> 524 <list style="letters"> 525 <t> 526 Item one; 527 </t> 528 <t> 529 Item two. 530 </t> 531 </list> 532 </t> 533 <t> 534 Uppercasing the letters works too (note two spaces after the letter. 535 </t> 536 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 537 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 538A. Item one; 539B. Item two. 540 </artwork> 541 </figure> 542 <t> 543 Becomes: 544 </t> 545 <t> 546 <list style="format %C."> 547 <t> 548 Item one; 549 </t> 550 <t> 551 Item two. 552 </t> 553 </list> 554 </t> 555 </section> 556 <section title="Hanging" anchor="hanging" toc="default"> 557 <t> 558 This is more like a description list, so we need to use: 559 </t> 560 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 561 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 562First item that needs clarification: 563 564: Explanation one 565More stuff, because item is difficult to explain. 566* item1 567* item2 568 569Second item that needs clarification: 570 571: Explanation two 572 </artwork> 573 </figure> 574 <t> 575 Converts to: <spanx style="verb" xml:space="preserve"><list style="hanging"></spanx> and <spanx style="verb" xml:space="preserve"><t hangText="First item that..."></spanx> 576 </t> 577 <t> 578 If you want a newline after the hangTexts, search for the string <spanx style="verb" xml:space="preserve">OPTION</spanx> in <spanx style="verb" xml:space="preserve">transform.xsl</spanx> and uncomment it. 579 </t> 580 </section> 581 </section> 582 <section title="Figure/Artwork" anchor="figureartwork" toc="default"> 583 <t> 584 Indent the paragraph with 4 spaces. 585 </t> 586 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 587 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 588Like this 589 </artwork> 590 </figure> 591 <t> 592 Converts to: 593 <spanx style="verb" xml:space="preserve"><figure><artwork>...</spanx> 594 Note that <spanx style="verb" xml:space="preserve">xml2rfc</spanx> 595 supports a caption with 596 <spanx style="verb" xml:space="preserve"><artwork></spanx>. Pandoc does not 597 support this, but Pandoc2rfc does. If you add a 598 <spanx style="verb" xml:space="preserve">@Figure: some text</spanx> as the last 599 line, the artwork gets a <spanx style="verb" xml:space="preserve">title</spanx> 600 attribute with the text after 601 <spanx style="verb" xml:space="preserve">@Figure:</spanx>. It will also be 602 possible to reference the artwork. If a caption is supplied the artwork will be 603 centered. If a caption is needed but the figure should not be centered use 604 <spanx style="verb" xml:space="preserve">@figure:\</spanx>. 605 </t> 606 <section title="References" anchor="references" toc="default"> 607 <t> 608 The reference anchor attribute will be: <spanx style="verb" xml:space="preserve">fig:</spanx> 609 + <spanx style="verb" xml:space="preserve">first 10 (normalized) characters from the caption</spanx>. 610 Where normalized means: 611 </t> 612 <t> 613 <list style="symbols"> 614 <t> 615 Take the first 10 characters of the caption (i.e. this is the text 616 <spanx style="emph" xml:space="preserve">after</spanx> the string 617 <spanx style="verb" xml:space="preserve">@Figure:</spanx>); 618 </t> 619 <t> 620 Spaces and single quotes (') are translated to a minus 621 <spanx style="verb" xml:space="preserve">-</spanx>; 622 </t> 623 <t> 624 Uppercase letters translated to lowercase. 625 </t> 626 </list> 627 </t> 628 <t> 629 So the first artwork with a caption will get 630 <spanx style="verb" xml:space="preserve">fig:a-minimal-</spanx> 631 as a reference. See for instance 632 <xref target="fig-a-minimal-" pageno="false" format="default"/>. 633 </t> 634 <t> 635 This anchoring is completely handled from within the 636 <spanx style="verb" xml:space="preserve">xslt</spanx>. 637 Note that duplicate anchors are an XML validation error which will make 638 <spanx style="verb" xml:space="preserve">xml2rfc</spanx> fail. 639 </t> 640 </section> 641 </section> 642 <section title="Block Quote" anchor="block-quote" toc="default"> 643 <t> 644 Any paragraph like: 645 </t> 646 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 647 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 648> quoted text 649 </artwork> 650 </figure> 651 <t> 652 Converts to: <spanx style="verb" xml:space="preserve"><t><list style="empty"> ...</spanx> 653 paragraph, making it indented. 654 </t> 655 </section> 656 <section title="References" anchor="references-1" toc="default"> 657 <section title="External" anchor="external" toc="default"> 658 <t> 659 Any reference like: 660 </t> 661 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 662 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 663[Click here](URI) 664 </artwork> 665 </figure> 666 <t> 667 Converts to: <spanx style="verb" xml:space="preserve"><ulink target="URI">Click here ...</spanx> 668 </t> 669 </section> 670 <section title="Internal" anchor="internal" toc="default"> 671 <t> 672 Any reference like: 673 </t> 674 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 675 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 676[Click here](#localid) 677 </artwork> 678 </figure> 679 <t> 680 Converts to: <spanx style="verb" xml:space="preserve"><link target="localid">Click here ...</spanx> 681 </t> 682 <t> 683 For referring to RFCs (for which you manually need add the reference source in 684 the template, with an external XML entity), you can just use: 685 </t> 686 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 687 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 688[](#RFC2119) 689 </artwork> 690 </figure> 691 <t> 692 And it does the right thing. Referencing sections is done with: 693 </t> 694 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 695 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 696See [](#pandoc-constructs) 697 </artwork> 698 </figure> 699 <t> 700 The word 'Section' is inserted automatically: ... see 701 <xref target="pandoc-constructs" pageno="false" format="default"/> 702 ... For referencing figures/artworks see 703 <xref target="figureartwork" pageno="false" format="default"/>. 704 For referencing tables see <xref target="tables" pageno="false" format="default"/>. 705 </t> 706 </section> 707 </section> 708 <section title="Spanx Styles" anchor="spanx-styles" toc="default"> 709 <t> 710 The verb style can be selected with back-tics: 711 <spanx style="verb" xml:space="preserve">`text`</spanx> 712 Converts to: 713 <spanx style="verb" xml:space="preserve"><spanx style="verb"> ...</spanx> 714 </t> 715 <t> 716 And the emphasis style with asterisks: 717 <spanx style="verb" xml:space="preserve">*text*</spanx> 718 or underscores: <spanx style="verb" xml:space="preserve">_text_</spanx> 719 Converts to: <spanx style="verb" xml:space="preserve"><spanx style="emph"> ...</spanx> 720 </t> 721 <t> 722 And the emphasis style with double asterisks: 723 <spanx style="verb" xml:space="preserve">**text**</spanx> 724 Converts to: <spanx style="verb" xml:space="preserve"><spanx style="strong"> ...</spanx> 725 </t> 726 </section> 727 <section title="Tables" anchor="tables" toc="default"> 728 <t> 729 A table can be entered as: 730 </t> 731 <figure anchor="fig-a-caption-" align="center" title="A caption describing the figure describing the table." suppress-title="false" alt="" width="" height=""> 732 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 733 Right Left Center Default 734 ------- ------ ---------- ------- 735 12 12 12 12 736 123 123 123 123 737 1 1 1 1 738 739 Table: A caption describing the table. 740 </artwork> 741 </figure> 742 <t> 743 Is translated to <spanx style="verb" xml:space="preserve"><texttable></spanx> 744 element in <spanx style="verb" xml:space="preserve">xml2rfc</spanx>. 745 You can choose multiple styles as input, but they all are converted to the same style (plain 746 <spanx style="verb" xml:space="preserve"><texttable></spanx>) table in 747 <spanx style="verb" xml:space="preserve">xml2rfc</spanx>. The column alignment 748 is copied over to the generated XML. 749 </t> 750 <section title="References" anchor="references-2" toc="default"> 751 <t> 752 The caption is <spanx style="emph" xml:space="preserve">always</spanx> 753 translated to a <spanx style="verb" xml:space="preserve">title</spanx> 754 attribute. If a table has a caption, it will 755 <spanx style="emph" xml:space="preserve">also</spanx> get a reference. 756 The reference anchor attribute will be: 757 <spanx style="verb" xml:space="preserve">tab-</spanx> 758 + <spanx style="verb" xml:space="preserve">first 10 (normalized) characters from the caption</spanx>. 759 Where normalized means: 760 </t> 761 <t> 762 <list style="symbols"> 763 <t> 764 Take the first 10 characters of the caption (i.e. this is the text 765 <spanx style="emph" xml:space="preserve">after</spanx> the string 766 <spanx style="verb" xml:space="preserve">Table:</spanx>); 767 </t> 768 <t> 769 Spaces and single quotes (') are translated to a minus 770 <spanx style="verb" xml:space="preserve">-</spanx>; 771 </t> 772 <t> 773 Uppercase letters translated to lowercase. 774 </t> 775 </list> 776 </t> 777 <t> 778 So the first table with a caption will get 779 <spanx style="verb" xml:space="preserve">tab-a-caption-</spanx> 780 for reference use. See for instance 781 </t> 782 <t> 783 This anchoring is completely handled from within the 784 <spanx style="verb" xml:space="preserve">xslt</spanx>. 785 Note that duplicate anchors are an XML validation error which will make 786 <spanx style="verb" xml:space="preserve">xml2rfc</spanx> fail. 787 </t> 788 </section> 789 </section> 790 <section title="Indexes" anchor="indexes" toc="default"> 791 <t> 792 The footnote syntax of Pandoc is slightly abused to support an index. Footnotes are entered in two steps, you have a marker in the text, and later you give actual footnote text. Like this: 793 </t> 794 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 795 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 796[^1] 797 798[^1]: footnote text 799 </artwork> 800 </figure> 801 <t> 802 We re-use this syntax for the <spanx style="verb" xml:space="preserve"><iref></spanx> tag. The above text translates to: 803 </t> 804 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 805 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 806<iref item="footnote text"/> 807 </artwork> 808 </figure> 809 <t> 810 Sub items are also supported. Use an exclamation mark (<spanx style="verb" xml:space="preserve">!</spanx>) to separate them: 811 </t> 812 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 813 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 814[^1]: item!sub item 815 </artwork> 816 </figure> 817 </section> 818 </section> 819 <section title="Usage guidelines" anchor="usage-guidelines" toc="default"> 820 <section title="Working with multiple files" anchor="working-with-multiple-files" toc="default"> 821 <t> 822 As an author you will probably break up a draft in multiple files, each dealing 823 with a subject or section. When doing so sections with the same title will clash 824 with each other. Pandoc can deal with this situation, but only if the different 825 sections are in the <spanx style="emph" xml:space="preserve">same</spanx> file or 826 processed in the same Pandoc run. Concatenating the different section files 827 before processing them is a solution to this problem. You can, for instance, 828 amend the <spanx style="verb" xml:space="preserve">Makefile</spanx> and add 829 something like this: 830 </t> 831 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 832 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 833allsections.pdc: section.pdc.1 section.pdc.2 section.pdc.3 834 cat $@ > allsections.pdc 835 </artwork> 836 </figure> 837 <t> 838 And then process <spanx style="verb" xml:space="preserve">allsection.pdc</spanx> in the normal way. 839 </t> 840 </section> 841 <section title="Setting the title" anchor="setting-the-title" toc="default"> 842 <t> 843 If you use double quotes in the documents title in the 844 <spanx style="verb" xml:space="preserve">docName</spanx> attribute, like: 845 </t> 846 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 847 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 848<rfc ipr="trust200902" docName="draft-gieben-writing-rfcs-pandoc-02"> 849 </artwork> 850 </figure> 851 <t> 852 The Makefile will pick this up automatically and make a symbolic link: 853 </t> 854 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 855 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 856draft-gieben-writing-rfcs-pandoc-00.txt -> draft.txt 857 </artwork> 858 </figure> 859 <t> 860 This makes uploading the file to the i-d tracker a bit easier. 861 </t> 862 </section> 863 <section title="Uploading the XML/txt" anchor="uploading-the-xmltxt" toc="default"> 864 <t> 865 The <spanx style="verb" xml:space="preserve">draft.xml</spanx> target will 866 generate an XML file with all XML included, so you can upload just one file to 867 the I-D tracker. 868 </t> 869 </section> 870 <section title="VIM syntax highlighting" anchor="vim-syntax-highlighting" toc="default"> 871 <t> 872 If you are a VIM user you might be interested in a syntax highlighting file (see 873 <xref target="VIM" pageno="false" format="default"/>) that slightly lightens up 874 your reading experience while viewing a draft.txt from VIM. 875 </t> 876 </section> 877 </section> 878 <section title="Security Considerations" anchor="security-considerations" toc="default"> 879 <t> 880 This document raises no security issues. 881 </t> 882 </section> 883 <section title="IANA Considerations" anchor="iana-considerations" toc="default"> 884 <t> 885 This document has no actions for IANA. 886 </t> 887 </section> 888 </middle> 889 <back> 890 <references title="Informative References"> 891 <reference anchor="VIM" target="http://github.com/miekg/rfc"> 892 <front> 893 <title abbrev="Syntax file for RFCs">VIM syntax file for RFCs and I-Ds</title> 894 <author initials="R." surname="Gieben" fullname="R. (Miek) Gieben"> 895 <organization>Atoom Inc.</organization> 896 <address> 897 <email>miek@miek.nl</email> 898 </address> 899 </author> 900 <date year="2012" month="October"/> 901 </front> 902 <format type="Syntax file" target="http://github.com/miekg/rfc"/> 903 </reference> 904 </references> 905 <references title="Normative References"> 906 <reference anchor="RFC2119"> 907 <front> 908 <title abbrev="RFC Key Words">Key words for use in RFCs to Indicate Requirement Levels</title> 909 <author initials="S." surname="Bradner" fullname="Scott Bradner"> 910 <organization>Harvard University</organization> 911 <address> 912 <postal> 913 <street>1350 Mass. Ave.</street> 914 <street>Cambridge</street> 915 <street>MA 02138</street> 916 </postal> 917 <phone>- +1 617 495 3864</phone> 918 <email>sob@harvard.edu</email> 919 </address> 920 </author> 921 <date year="1997" month="March"/> 922 <area>General</area> 923 <keyword>keyword</keyword> 924 <abstract> 925 <t> 926 In many standards track documents several words are used to signify the 927 requirements in the specification. These words are often capitalized. 928 This document defines these words as they should be interpreted in IETF 929 documents. Authors who follow these guidelines should incorporate this 930 phrase near the beginning of their document: 931 <list> 932 <t> 933 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 934 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 935 document are to be interpreted as described in RFC 2119. 936 </t> 937 </list> 938 </t> 939 <t> 940 Note that the force of these words is modified by the requirement level of 941 the document in which they are used. 942 </t> 943 </abstract> 944 </front> 945 <seriesInfo name="BCP" value="14"/> 946 <seriesInfo name="RFC" value="2119"/> 947 <format type="TXT" octets="4723" target="ftp://ftp.isi.edu/in-notes/rfc2119.txt"/> 948 <format type="HTML" octets="17491" target="http://xml.resource.org/public/rfc/html/rfc2119.html"/> 949 <format type="XML" octets="5777" target="http://xml.resource.org/public/rfc/xml/rfc2119.xml"/> 950 </reference> 951 <reference anchor="RFC4641"> 952 <front> 953 <title>DNSSEC Operational Practices</title> 954 <author initials="O." surname="Kolkman" fullname="O. Kolkman"> 955 <organization/> 956 </author> 957 <author initials="R." surname="Gieben" fullname="R. Gieben"> 958 <organization/> 959 </author> 960 <date year="2006" month="September"/> 961 <abstract> 962 <t> 963 This document describes a set of practices for operating the DNS with 964 security extensions (DNSSEC). The target audience is zone administrators 965 deploying DNSSEC.</t><t> The document discusses operational 966 aspects of using keys and signatures in the DNS. It discusses issues of key 967 generation, key storage, signature generation, key rollover, and related 968 policies.</t><t> This document obsoletes RFC 2541, as it covers 969 more operational ground and gives more up-to-date requirements with respect 970 to key sizes and the new DNSSEC specification. This memo provides 971 information for the Internet community. 972 </t> 973 </abstract> 974 </front> 975 <seriesInfo name="RFC" value="4641"/> 976 <format type="TXT" octets="79894" target="http://www.rfc-editor.org/rfc/rfc4641.txt"/> 977 </reference> 978 </references> 979 <!--This document was prepared using Pandoc2rfc https://github.com/miekg/pandoc2rfc --> 980 <section title="Tests" anchor="tests" toc="default"> 981 <t> 982 This appendix consists out of a few tests that should all render to proper 983 <spanx style="verb" xml:space="preserve">xml2rfc</spanx> XML. 984 </t> 985 <section title="A Very Long Title Considerations With Regards to the Already Deployed Routing Policy" anchor="a-very-long-title-considerations-with-regards-to-the-already-deployed-routing-policy" toc="default"> 986 <t> 987 Test a very long title. 988 </t> 989 </section> 990 <section title="Markup in heading" anchor="markup-in-heading" toc="default"> 991 <t> 992 This is discarded by <spanx style="verb" xml:space="preserve">xml2rfc</spanx>. 993 </t> 994 </section> 995 <section title="Blockquote" anchor="blockquote" toc="default"> 996 <t> 997 <list style="empty"> 998 <t> 999 This is a blockquote, how does it look? 1000 </t> 1001 </list> 1002 </t> 1003 </section> 1004 <section title="Verbatim code blocks" anchor="verbatim-code-blocks" toc="default"> 1005 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1006 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1007A verbatim code block 1008jkasjksajassjasjsajsajkas 1009 </artwork> 1010 </figure> 1011 </section> 1012 <section title="Reference Tests" anchor="reference-tests" toc="default"> 1013 <t> 1014 Refer to <xref target="RFC2119" pageno="false" format="default">RFC 2119</xref> if you will. Or maybe you want to inspect <xref target="fig-a-minimal-" pageno="false" format="default"/> in <xref target="pandoc-to-rfc" pageno="false" format="default"/> again. Or you might want to <eref target="http://miek.nl">Click here</eref>. 1015 </t> 1016 </section> 1017 <section title="Spanx Tests" anchor="spanx-tests" toc="default"> 1018 <t> 1019 <list style="empty"> 1020 <t> 1021 underscores: <spanx style="emph" xml:space="preserve">underscores</spanx> 1022 </t> 1023 <t> 1024 asterisks: <spanx style="emph" xml:space="preserve">asterisks</spanx> 1025 </t> 1026 <t> 1027 double asterisks: <spanx style="strong" xml:space="preserve">double asterisks</spanx> 1028 </t> 1029 <t> 1030 backticks: <spanx style="verb" xml:space="preserve">backticks</spanx> 1031 </t> 1032 </list> 1033 </t> 1034 </section> 1035 <section title="List Tests" anchor="list-tests" toc="default"> 1036 <t> 1037 <list style="numbers"> 1038 <t> 1039 First we do 1040 </t> 1041 <t> 1042 And then <list style="symbols"> 1043 <t> 1044 item 1 1045 </t> 1046 <t> 1047 item 2 1048 </t> 1049 </list> 1050 </t> 1051 </list> 1052 </t> 1053 <t> 1054 And the other around. 1055 </t> 1056 <t> 1057 <list style="symbols"> 1058 <t> 1059 First we do 1060 </t> 1061 <t> 1062 Then <list style="numbers"> 1063 <t> 1064 Something 1065 </t> 1066 <t> 1067 Another thing 1068 </t> 1069 </list> 1070 </t> 1071 </list> 1072 </t> 1073 <t> 1074 Description lists: 1075 </t> 1076 <t> 1077 <list style="hanging"> 1078 <t hangText="Item to explain:">It works because of herbs. 1079 </t> 1080 <t hangText="Another item to explain:">More explaining. <vspace blankLines="1"/> Multiple paragraphs in such a list. 1081 </t> 1082 </list> 1083 </t> 1084 <t> 1085 lists in description lists. 1086 </t> 1087 <t> 1088 <list style="hanging"> 1089 <t hangText="Item to explain:">It works because of <list style="numbers"> 1090 <t> 1091 One 1092 </t> 1093 <t> 1094 Two 1095 </t> 1096 </list> 1097 </t> 1098 <t hangText="Another item to explain:">More explaining 1099 </t> 1100 <t hangText="Item to explain:">It works because of <list style="numbers"> 1101 <t> 1102 One1 1103 </t> 1104 <t> 1105 Two1 <list style="symbols"> 1106 <t> 1107 Itemize list 1108 </t> 1109 <t> 1110 Another item 1111 </t> 1112 </list> 1113 </t> 1114 </list> 1115 </t> 1116 <t hangText="Another item to explain again:">More explaining 1117 </t> 1118 </list> 1119 </t> 1120 <t> 1121 list with description lists. 1122 </t> 1123 <t> 1124 <list style="numbers"> 1125 <t> 1126 More <list style="hanging"> 1127 <t hangText="Item to explain:">Explanation ... 1128 </t> 1129 <t hangText="Item to explain:">Another explanation ... 1130 </t> 1131 </list> 1132 </t> 1133 <t> 1134 Go'bye 1135 </t> 1136 </list> 1137 </t> 1138 <t> 1139 Multiple paragraphs in a list. 1140 </t> 1141 <t> 1142 <list style="numbers"> 1143 <t> 1144 This is the first bullet point and it needs multiple paragraphs... 1145 <vspace blankLines="1"/> ... to be explained properly. 1146 </t> 1147 <t> 1148 This is the next bullet. New paragraphs should be indented with 4 four spaces. 1149 </t> 1150 <t> 1151 Another item with some artwork, indented by 8 spaces. 1152 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1153 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1154Artwork 1155 </artwork> 1156 </figure> 1157 </t> 1158 <t> 1159 Final item. 1160 </t> 1161 </list> 1162 </t> 1163 <t> 1164 xml2rfc does not allow this, so the second paragraph is faked with a 1165 </t> 1166 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1167 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1168<vspace blankLines='1'> 1169 </artwork> 1170 </figure> 1171 <t> 1172 Ordered lists. 1173 </t> 1174 <t> 1175 <list style="numbers"> 1176 <t> 1177 First item 1178 </t> 1179 <t> 1180 Second item 1181 </t> 1182 </list> 1183 </t> 1184 <t> 1185 A lowercase roman list: 1186 </t> 1187 <t> 1188 <list style="format %i."> 1189 <t> 1190 Item 1 1191 </t> 1192 <t> 1193 Item 2 1194 </t> 1195 </list> 1196 </t> 1197 <t> 1198 An uppercase roman list. 1199 </t> 1200 <t> 1201 <list style="format (%d)"> 1202 <t> 1203 Item1 1204 </t> 1205 <t> 1206 Item2 1207 </t> 1208 <t> 1209 Item 3 1210 </t> 1211 </list> 1212 </t> 1213 <t> 1214 And default list markers.<iref item="list" subitem="default markers" primary="false"/> 1215 </t> 1216 <t> 1217 Some surrounding text, to make it look better. 1218 </t> 1219 <t> 1220 <list style="empty"> 1221 <t> 1222 First item. Use lot of text to get a real paragraphs sense. First item. 1223 Use lot of text to get a real paragraphs sense. First item. Use lot of 1224 text to get a real paragraphs sense. First item. Use lot of text to get a 1225 real paragraphs sense. 1226 </t> 1227 <t> 1228 Second item. So this is the second para in your list. Enjoy; 1229 </t> 1230 <t> 1231 Another item. 1232 </t> 1233 </list> 1234 </t> 1235 <t> 1236 Text at the end. 1237 </t> 1238 <t> 1239 Lowercase letters list. 1240 </t> 1241 <t> 1242 <list style="letters"> 1243 <t> 1244 First item 1245 </t> 1246 <t> 1247 Second item 1248 </t> 1249 </list> 1250 </t> 1251 <t> 1252 Uppercase letters list. 1253 </t> 1254 <t> 1255 <list style="format %C."> 1256 <t> 1257 First item 1258 </t> 1259 <t> 1260 Second item 1261 </t> 1262 </list> 1263 </t> 1264 <t> 1265 <iref item="list" subitem="Uppercase Letters" primary="false"/> 1266 </t> 1267 <t> 1268 And artwork in a description list. 1269 </t> 1270 <t> 1271 <list style="hanging"> 1272 <t hangText="Item1:"> 1273 Tell something about it. Tell something about it. Tell something about it. 1274 Tell something about it. Tell something about it. Tell something about it. 1275 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1276 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1277miek.nl. IN NS a.miek.nl. 1278a.miek.nl. IN A 192.0.2.1 ; <- this is glue 1279 </artwork> 1280 </figure> 1281 <vspace blankLines="1"/> 1282 Tell some more about it. Tell some more about it. Tell some more about it. 1283 </t> 1284 <t hangText="Item2:">Another description 1285 </t> 1286 </list> 1287 </t> 1288 <t> 1289 List with a sublist with a paragraph above the sublist 1290 </t> 1291 <t> 1292 <list style="numbers"> 1293 <t> 1294 First Item 1295 </t> 1296 <t> 1297 Second item 1298 </t> 1299 <t> 1300 Third item <vspace blankLines="1"/> A paragraph that comes first <list style="letters"> 1301 <t> 1302 But what do you know 1303 </t> 1304 <t> 1305 This is another list 1306 </t> 1307 </list> 1308 </t> 1309 </list> 1310 </t> 1311 </section> 1312 <section title="Table Tests" anchor="anchor-table-tests" toc="default"> 1313 <texttable anchor="tab-demonstrat" title=" Demonstration of simple table syntax. " suppress-title="false" align="center" style="full"> 1314 <ttcol align="right">Right </ttcol> 1315 <ttcol align="left">Left </ttcol> 1316 <ttcol align="center">Center </ttcol> 1317 <ttcol align="left">Default </ttcol> 1318 <c>12 </c> 1319 <c>12 </c> 1320 <c>12 </c> 1321 <c>12 </c> 1322 <c>123 </c> 1323 <c>123 </c> 1324 <c>123 </c> 1325 <c>123 </c> 1326 <c>1 </c> 1327 <c>1 </c> 1328 <c>1 </c> 1329 <c>1 </c> 1330 </texttable> 1331 <texttable anchor="tab-here-s-the" title=" Here's the caption. It, too, may span multiple lines. This is a multiline table. This is verbatim text. " suppress-title="false" align="center" style="full"> 1332 <ttcol align="center" width="16%">Centered Header </ttcol> 1333 <ttcol align="left" width="11%">Default Aligned </ttcol> 1334 <ttcol align="right" width="22%">Right Aligned </ttcol> 1335 <ttcol align="left" width="34%">Left Aligned </ttcol> 1336 <c>First </c> 1337 <c>row </c> 1338 <c>12.0 </c> 1339 <c>Example of a row that spans multiple lines. </c> 1340 <c>Second </c> 1341 <c>row </c> 1342 <c>5.0 </c> 1343 <c>Here's another one. Note the blank line between rows. </c> 1344 </texttable> 1345 <t> 1346 <iref item="table" subitem="simple" primary="false"/> 1347 </t> 1348 <texttable anchor="tab-sample-gri" title=" Sample grid table. " suppress-title="false" align="center" style="full"> 1349 <ttcol align="left" width="22%">Fruit </ttcol> 1350 <ttcol align="left" width="22%">Price </ttcol> 1351 <ttcol align="left" width="29%">Advantages </ttcol> 1352 <c>Bananas </c> 1353 <c>$1.34 </c> 1354 <c>built-in wrapper </c> 1355 <c>Oranges </c> 1356 <c>$2.10 </c> 1357 <c>cures scurvy </c> 1358 </texttable> 1359 <t> 1360 Grid tables without a caption 1361 </t> 1362 <texttable title="" suppress-title="false" align="center" style="full"> 1363 <ttcol align="left" width="22%">Fruit </ttcol> 1364 <ttcol align="left" width="22%">Price </ttcol> 1365 <ttcol align="left" width="29%">Advantages </ttcol> 1366 <c>Bananas </c> 1367 <c>$1.34 </c> 1368 <c>built-in wrapper </c> 1369 <c>Oranges </c> 1370 <c>$2.10 </c> 1371 <c>cures scurvy </c> 1372 </texttable> 1373 <t> 1374 This table has no caption, and therefor no reference. But you can refer to some of the other tables, with for instance: 1375 </t> 1376 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1377 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1378See [](#tab-here-s-the) 1379 </artwork> 1380 </figure> 1381 <t> 1382 Which will become "See <xref target="tab-here-s-the" pageno="false" format="default"/>". 1383 </t> 1384 <t> 1385 <iref item="table" subitem="grid" primary="false"/> 1386 </t> 1387 <t> 1388 We should also be able to refer to the table numbers directly, to say things like 1389 'Look at Tables 1390 <xref target="tab-demonstrat" format="counter"/>, 1391 <xref target="tab-here-s-the" format="counter"/> 1392 and <xref target="tab-sample-gri" format="counter"/>.' 1393 </t> 1394 </section> 1395 <section title="Numbered examples" anchor="numbered-examples" toc="default"> 1396 <t> 1397 This is another example: 1398 </t> 1399 <t> 1400 <list style="numbers"> 1401 <t> 1402 Another bla bla.. 1403 </t> 1404 </list> 1405 </t> 1406 <t> 1407 as (1) shows... 1408 </t> 1409 </section> 1410 <section title="Figure tests" anchor="anchor-figure-tests" toc="default"> 1411 <figure anchor="fig-this-is-th" align="center" title="This is the caption, with text in `typewriter`. Which isnt converted to a <spanx> style, because this is copied as-is." suppress-title="false" alt="" width="" height=""> 1412 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1413This is a figure 1414This is a figure 1415This is a figure 1416This is a figure 1417 </artwork> 1418 </figure> 1419 <t> 1420 And how a figure that is not centered, do to using <spanx style="verb" xml:space="preserve">figure</spanx> and not <spanx style="verb" xml:space="preserve">Figure</spanx>. 1421 </t> 1422 <figure anchor="fig-a-non-cent" title="A non centered figure." suppress-title="false" align="left" alt="" width="" height=""> 1423 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1424This is a figure 1425This is a figure 1426 </artwork> 1427 </figure> 1428 <t> 1429 Test the use of <spanx style="verb" xml:space="preserve">@title</spanx>: 1430 </t> 1431 <figure title="" suppress-title="false" align="left" alt="" width="" height=""> 1432 <artwork xml:space="preserve" name="" type="" align="left" alt="" width="" height=""> 1433This is a figure with a title 1434This is a figure with a title 1435@title: and here it is: a title, don't mess it up * 1436 </artwork> 1437 </figure> 1438 </section> 1439 <section title="Verse tests" anchor="verse-tests" toc="default"> 1440 <t> 1441 This is a verse text This is another line 1442 </t> 1443 </section> 1444 </section> 1445 </back> 1446</rfc> 1447