docutils/docs/user/odt.txt

   1 =======================
   2 Odt Writer for Docutils
   3 =======================
   4
   5 :Author: Dave Kuhlman
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Revision: $Revision$
   8 :Date: $Date$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 :abstract: This document describes the Docutils odtwriter
  12     (rst2odt.py).
  13
  14 .. sectnum::
  15
  16 .. contents::
  17
  18
  19
  20 Introduction
  21 ============
  22
  23 What it does -- ``rst2odt.py`` translates reST
  24 (reStructuredText) into a Open Document Format ``.odt`` file.  You
  25 can learn more about the ODF format here:
  26
  27 - `OASIS Open Document Format for Office Applications
  28   (OpenDocument) TC`_
  29
  30 - `Open Document at Wikipedia`_
  31
  32 You should be able to open documents (.odt files) generated with
  33 ``rst2odt.py`` in ``OpenOffice/oowriter``.
  34
  35 You can learn more about Docutils and reST here: `Docutils`_
  36
  37
  38 Requirements
  39 ============
  40
  41 In addition to the Docutils standard requirements, ``odtwriter``
  42 requires:
  43
  44 - Optional -- `Pygments`_ is required if you want syntax
  45   highlighting of code in literal blocks.  See section `Syntax
  46   highlighting`_.
  47
  48 - Optional -- `Python Imaging Library`_ (PIL) is required if on an
  49   image or figure directive, you specify ``scale`` but not ``width``
  50   and ``height``.  See section `Images and figures`_.
  51
  52
  53
  54 How to Use It
  55 =============
  56
  57 Run it from the command line as follows::
  58
  59     $ rst2odt.py myinput.txt myoutput.odt
  60
  61 To see usage information and to learn about command line options
  62 that you can use, run the following::
  63
  64     $ rst2odt.py --help
  65
  66 Examples::
  67
  68     $ rst2odt.py -s -g python_comments.txt python_comments.odt
  69
  70     $ rst2odt.py --source-url=odtwriter.txt --generator \
  71         --stylesheet=/myconfigs/styles.odt odtwriter.txt odtwriter.odt
  72
  73
  74 Configuration file
  75 ------------------
  76
  77 The options described below can also be set in a configuration file.
  78 Use section ``[odf_odt writer]`` to set options specific to the
  79 ``odtwriter``.  For example::
  80
  81     [odf_odt writer]
  82     stylesheet: styles1.odt
  83
  84 See the "Docutils Configuration" document for more information on
  85 Docutils configuration files, including locations which are
  86 searched.
  87
  88
  89 Command line options
  90 --------------------
  91
  92 The following command line options are specific to ``odtwriter``:
  93
  94 --stylesheet=<URL>      Specify a stylesheet URL, used verbatim.
  95                         Default: writers/odf_odt/styles.odt in the
  96                         installation directory.
  97 --odf-config-file=<file>
  98                         Specify a configuration/mapping file relative to the
  99                         current working directory for additional ODF options.
 100                         In particular, this file may contain a section named
 101                         "Formats" that maps default style names to names to be
 102                         used in the resulting output file allowing for
 103                         adhering to external standards. For more info and the
 104                         format of the configuration/mapping file, see the
 105                         odtwriter doc.
 106 --cloak-email-addresses
 107                         Obfuscate email addresses to confuse harvesters while
 108                         still keeping email links usable with standards-
 109                         compliant browsers.
 110 --no-cloak-email-addresses
 111                         Do not obfuscate email addresses.
 112 --table-border-thickness=TABLE_BORDER_THICKNESS
 113                         Specify the thickness of table borders in thousands of
 114                         a cm.  Default is 35.
 115 --add-syntax-highlighting
 116                         Add syntax highlighting in literal code blocks.
 117 --no-syntax-highlighting
 118                         Do not add syntax highlighting in literal code blocks.
 119                         (default)
 120 --create-sections       Create sections for headers.  (default)
 121 --no-sections           Do not create sections for headers.
 122 --create-links          Create links.
 123 --no-links              Do not create links.  (default)
 124 --endnotes-end-doc      Generate endnotes at end of document, not footnotes at
 125                         bottom of page.
 126 --no-endnotes-end-doc   Generate footnotes at bottom of page, not endnotes at
 127                         end of document. (default)
 128 --generate-list-toc     Generate a bullet list table of contents, not an
 129                         ODF/``oowriter`` table of contents.
 130 --generate-oowriter-toc
 131                         Generate an ODF/``oowriter`` table of contents,
 132                         not a bullet list.  (default) **Note:**
 133                         ``odtwriter`` is not able to determine page
 134                         numbers, so you will need to open the
 135                         generated document in ``oowriter``, then
 136                         right-click on the table of contents and
 137                         select "Update" to insert page numbers.
 138 --custom-odt-header=CUSTOM_HEADER
 139                         Specify the contents of an custom header line.  See
 140                         odf_odt writer documentation for details about special
 141                         field character sequences.  See section
 142                         `Custom header/footers: inserting page numbers, date, time, etc`_
 143                         for details
 144 --custom-odt-footer=CUSTOM_FOOTER
 145                         Specify the contents of an custom footer line.  See
 146                         odf_odt writer documentation for details about special
 147                         field character sequences.  See section
 148                         `Custom header/footers: inserting page numbers, date, time, etc`_
 149                         for details
 150
 151
 152
 153 Styles and Classes
 154 ==================
 155
 156 ``odtwriter`` uses a number of styles that are defined in
 157 ``styles.xml`` in the default ``styles.odt``.  This section
 158 describes those styles.
 159
 160 Note that with the ``--stylesheet`` command line option, you can
 161 use either ``styles.odt`` or ``styles.xml``, as described below.
 162 Use of ``styles.odt`` is recommended over ``styles.xml``.
 163
 164 You can modify the look of documents generated by ``odtwriter`` in
 165 several ways:
 166
 167 - Open (a copy of) ``styles.odt`` in ``OpenOffice/oowriter`` and
 168   modify the style you wish to change. Now, save this document,
 169   then generate your documents using this modified copy of
 170   ``styles.odt``.
 171
 172   In my version of ``oowriter``, to modify styles, either (1)
 173   press F11 or (2) use menu item "Format/Styles and Formatting",
 174   then right-click on the relevant style and select "Modify".
 175   Modify the style, then save your document.
 176
 177 - Open a document generated by ``odtwriter`` in `oowriter``.  Now,
 178   edit the style you are interested in modifying.  Now, you
 179   can extract the styles.xml file from your document and either
 180   (1) use this as your default styles file or (2) copy and paste
 181   the relevant style definition into your styles.xml.
 182
 183 - Extract ``styles.xml`` from ``styles.odt`` using your favorite
 184   ``zip/unzip`` tool.  Then modify ``styles.xml`` with a text
 185   editor.  Now re-zip it back into your own ``styles.odt``, or use
 186   it directly by specifying it with the ``--stylesheet`` command
 187   line option.  **Hint:** If you intend to extract ``styles.xml``
 188   from an ``.odt`` file (and then "re-zip" it), you should turn off
 189   XML optimization/compression in ``oowriter``.  In order to this
 190   in ``oowriter``, use Tools --> Options...  --> Load-Save -->
 191   General and turn off "Size optimization for XML format".
 192
 193 - Open an empty (or new) document in ``oowriter``.  Define all of
 194   the styles described in this section.  Then, use that document (a
 195   .odt file) as your stylesheet.  ``odtwriter`` will extract the
 196   ``styles.xml`` file from that document and insert it into the
 197   output document.
 198
 199 - Some combination of the above.
 200
 201
 202 Styles used by odtwriter
 203 ------------------------
 204
 205 This section describes the styles used by ``odtwriter``.
 206
 207 Note that we do not describe the "look" of these styles.  That can
 208 be easily changed by using ``oowriter`` to edit the document
 209 ``styles.odt`` (or a copy of it), and modifying any of the styles
 210 described here.
 211
 212 To change the definition and appearance of these styles, open
 213 ``styles.odt`` in ``oowriter`` and open the Styles and Formatting
 214 window by using the following menu item::
 215
 216     Format --> Styles and Formatting
 217
 218 Then, click on the Paragraph Styles button or the Character Styles
 219 button at the top of the Styles and Formatting window.  You may
 220 also need to select "All Styles" from the drop-down selection list
 221 at the bottom of the Styles and Formatting window in order to see
 222 the styles used by ``odtwriter``.
 223
 224 Notice that you can make a copy of file ``styles.odt``, modify it
 225 using ``oowriter``, and then use your copy with the
 226 ``--stylesheet=<file>`` command line option.  Example::
 227
 228     $ rst2odt.py --stylesheet=mystyles.odt test2.txt test2.odt
 229
 230
 231 Paragraph styles
 232 ~~~~~~~~~~~~~~~~
 233
 234 rststyle-attribution
 235     The style for attributions, for example, the attribution in a
 236     ``.. epigraph::`` directive.  Derived from
 237     ``rststyle-blockquote``.
 238
 239 rststyle-blockindent
 240     An indented block.
 241
 242 rststyle-blockquote
 243     A block quote.
 244
 245 rststyle-blockquote-bulletitem
 246     The style for bullet list items inside block quote.
 247
 248 rststyle-blockquote-enumitem
 249     The style for enumerated list items inside block quote.
 250
 251 rststyle-bodyindent
 252     An indented block.
 253
 254 rststyle-bulletitem
 255     An item in an bullet list.
 256
 257 rststyle-caption
 258     The caption in a figure or image.  Also see
 259     ``rststyle-legend``.
 260
 261 rststyle-codeblock
 262     Literal code blocks -- A block of example code.  Created with
 263     double colon ("::") followed by an indented block or with the
 264     ``.. parsed-literal::`` directive.  Derived from the
 265     ``Preformatted Text`` style in ``oowriter``.
 266
 267 rststyle-enumitem
 268     An item in an enumerated list.
 269
 270 rststyle-epigraph
 271     The style for epigraphs, for example, the body of an
 272     ``.. epigraph::`` directive.  Derived from
 273     ``rststyle-blockquote``.
 274
 275 rststyle-epigraph-bulletitem
 276     The style for bullet list items inside epigraphs.
 277
 278 rststyle-epigraph-enumitem
 279     The style for enumerated list items inside epigraphs.
 280
 281 rststyle-footer
 282     The style for footers.  The footer content originates from the
 283     ``..footer::`` directive and in response to the command line
 284     flags for generator (``--generator``), date/time generated
 285     (``--date`` and ``--time``), and view source link
 286     (``--source-link`` and ``--source-url=URL``).
 287
 288 rststyle-header
 289     The style for headers.  The header content originates from the
 290     ``..header::`` directive.
 291
 292 rststyle-highlights
 293     The style for highlightss, for example, the body of an
 294     ``.. highlights::`` directive.  Derived from
 295     ``rststyle-blockquote``.
 296
 297 rststyle-highlights-bulletitem
 298     The style for bullet list items inside highlights.
 299
 300 rststyle-highlights-enumitem
 301     The style for enumerated list items inside highlights.
 302
 303 rststyle-horizontalline
 304     A horizontal line, e.g. used for transitions.
 305
 306 rststyle-legend
 307     The legend in a figure.  See the Docutils figure directive.  Also
 308     see ``rststyle-caption``.
 309
 310 rststyle-table-title
 311     The style for titles of tables.  See section `The table
 312     directive`_.
 313
 314 rststyle-textbody
 315     Normal text.  The style for paragraphs.  Derived from the ``Text
 316     body`` style in ``oowriter``.
 317
 318
 319 Character styles
 320 ~~~~~~~~~~~~~~~~
 321
 322 rststyle-emphasis
 323     Emphasis.  Normally rendered as italics.
 324
 325 rststyle-inlineliteral
 326     An inline literal.
 327
 328 rststyle-strong
 329     Strong emphasis.  Normally rendered as boldface.
 330
 331 rststyle-quotation
 332     In-line quoted material.
 333
 334 rststyle-codeblock-classname
 335     Syntax highlighting in literal code blocks -- class names.
 336
 337 rststyle-codeblock-comment
 338     Syntax highlighting in literal code blocks -- comments.
 339
 340 rststyle-codeblock-functionname
 341     Syntax highlighting in literal code blocks -- function names.
 342
 343 rststyle-codeblock-keyword
 344     Syntax highlighting in literal code blocks -- Python language
 345     keywords.
 346
 347 rststyle-codeblock-name
 348     Syntax highlighting in literal code blocks -- other names, for
 349     example, variables.
 350
 351 rststyle-codeblock-number
 352     Syntax highlighting in literal code blocks -- literal numbers,
 353     including integers, floats, hex numbers, and octal numbers.
 354
 355 rststyle-codeblock-operator
 356     Syntax highlighting in literal code blocks -- Python operators.
 357
 358 rststyle-codeblock-string
 359     Syntax highlighting in literal code blocks -- literal strings.
 360
 361
 362 List styles
 363 ~~~~~~~~~~~
 364
 365 rststyle-bulletlist
 366     Bullet lists (but not in the table of contents)
 367
 368 rststyle-blockquote-bulletlist
 369     Bullet lists in block quotes.
 370
 371 rststyle-blockquote-enumlist
 372     Enumerated lists in block quotes.
 373
 374 rststyle-enumlist-arabic
 375     Enumerated lists, arabic (but not in the table of contents)
 376
 377 rststyle-enumlist-loweralpha
 378     Enumerated lists, lower alpha (but not in the table of contents)
 379
 380 rststyle-enumlist-lowerroman
 381     Enumerated lists, lower roman (but not in the table of contents)
 382
 383 rststyle-enumlist-upperalpha
 384     Enumerated lists, upper alpha (but not in the table of contents)
 385
 386 rststyle-enumlist-upperroman
 387     Enumerated lists, upper roman (but not in the table of contents)
 388
 389 rststyle-epigraph-bulletlist
 390     Bullet lists in epigraphs.  See the ``.. epigraph::``
 391     directive.
 392
 393 rststyle-epigraph-enumlist
 394     Enumerated lists in epigraphs.  See the ``.. epigraph::``
 395     directive.
 396
 397 rststyle-highlights-bulletlist
 398     Bullet lists in highlights blocks.  See the ``.. highlights::``
 399     directive.
 400
 401 rststyle-highlights-enumlist
 402     Enumerated lists in highlights blocks.  See the ``.. highlights::``
 403     directive.
 404
 405 rststyle-tocbulletlist
 406     Lists in the table of contents when section numbering is off.
 407
 408 rststyle-tocenumlist
 409     Lists in the table of contents when section numbering is on.
 410
 411
 412 Admonition styles
 413 ~~~~~~~~~~~~~~~~~
 414
 415 rststyle-admon-attention-hdr
 416     The style for the attention admonition header/title.
 417
 418 rststyle-admon-attention-body
 419     The style for the attention admonition body/paragraph.
 420
 421 rststyle-admon-caution-hdr
 422     The style for the caution admonition header/title.
 423
 424 rststyle-admon-caution-body
 425     The style for the caution admonition body/paragraph.
 426
 427 rststyle-admon-danger-hdr
 428     The style for the  admonition header/title.
 429
 430 rststyle-admon-danger-body
 431     The style for the danger admonition body/paragraph.
 432
 433 rststyle-admon-error-hdr
 434     The style for the error admonition header/title.
 435
 436 rststyle-admon-error-body
 437     The style for the error admonition body/paragraph.
 438
 439 rststyle-admon-hint-hdr
 440     The style for the hint admonition header/title.
 441
 442 rststyle-admon-hint-body
 443     The style for the hint admonition body/paragraph.
 444
 445 rststyle-admon-hint-hdr
 446     The style for the hint admonition header/title.
 447
 448 rststyle-admon-hint-body
 449     The style for the hint admonition body/paragraph.
 450
 451 rststyle-admon-important-hdr
 452     The style for the important admonition header/title.
 453
 454 rststyle-admon-important-body
 455     The style for the important admonition body/paragraph.
 456
 457 rststyle-admon-note-hdr
 458     The style for the note admonition header/title.
 459
 460 rststyle-admon-note-hdr
 461     The style for the note admonition header/title.
 462
 463 rststyle-admon-tip-body
 464     The style for the tip admonition body/paragraph.
 465
 466 rststyle-admon-tip-hdr
 467     The style for the tip admonition header/title.
 468
 469 rststyle-admon-warning-body
 470     The style for the warning admonition body/paragraph.
 471
 472 rststyle-admon-warning-hdr
 473     The style for the warning admonition header/title.
 474
 475 rststyle-admon-generic-body
 476     The style for the generic admonition body/paragraph.
 477
 478 rststyle-admon-generic-hdr
 479     The style for the generic admonition header/title.
 480
 481
 482 Rubric style
 483 ~~~~~~~~~~~~
 484
 485 rststyle-rubric
 486     The style for the text in a rubric directive.
 487
 488 The rubric directive recognizes a "class" option.  If entered,
 489 odtwriter uses the value of that option instead of the
 490 ``rststyle-rubric`` style.  Here is an example which which attaches
 491 the ``rststyle-heading1`` style to the generated rubric::
 492
 493     .. rubric:: This is my first rubric
 494        :class: rststyle-heading1
 495
 496
 497 Table styles
 498 ~~~~~~~~~~~~
 499
 500 A table style is generated by ``oowriter`` for each table that you
 501 create.  Therefore, ``odtwriter`` attempts to do something similar.
 502 These styles are created in the ``content.xml`` document in the
 503 generated ``.odt`` file.  These styles have names prefixed with
 504 "rststyle-table-".
 505
 506 There are two ways in which you can control the styles of your
 507 tables: one simple, the other a bit more complex, but more
 508 powerful.
 509
 510 First, you can change the thickness of the borders of all tables
 511 generated in a document using the "--table-border-thickness"
 512 command line option.
 513
 514 Second, you can control additional table properties and you can
 515 apply different styles to different tables within the same document
 516 by customizing and using tables in your stylesheet: ``styles.odt``
 517 or whatever you name your copy of it using the --stylesheet command
 518 line option.  Then, follow these rules to apply a table style to
 519 the tables in your document:
 520
 521 - The default table style -- Optionally, alter and customize the
 522   style applied by default to tables in your document by modifying
 523   table "rststyle-table-0" in your stylesheet (``styles.odt`` or a
 524   copy).  Caution: Do not change the name of this table.
 525
 526 - User-created table styles -- Add one or more new table styles to
 527   be applied selectively to tables in your document by doing the
 528   following:
 529
 530   1. Using ``oowriter``, add a table to your stylesheet and give it
 531      a name that starts with the prefix "rststyle-table-", for
 532      example "rststyle-table-vegetabledata".  Customize the table's
 533      border thickness, border color, and table background color.
 534
 535   2. In your reStructuredText document, apply your new table style
 536      to a specific table by placing the "..  class::" directive
 537      immediately before the table, for example::
 538
 539          .. class:: rststyle-table-vegetabledata
 540
 541 The default table style will be applied to all tables for which you
 542 do not specify a style with the "..  class::" directive.
 543
 544 Customize the table properties in ``oowriter`` using the table
 545 properties dialog for the table (style) that you wish to customize.
 546
 547 Note that "--table-border-thickness" command line option overrides
 548 the border thickness specified in the stylesheet.
 549
 550 The specific properties that you can control with this second
 551 method are the following:
 552
 553 - Border thickness and border color.
 554
 555 - Background color -- When you change the background color of a
 556   table to be used as a style (in ``styles.odt`` or whatever you
 557   name it), make sure you change the background color for the
 558   *table* and *not* for a cell in the table.  ``odtwriter`` picks
 559   the background color from the table, not from a cell within the
 560   table.
 561
 562
 563 Line block styles
 564 ~~~~~~~~~~~~~~~~~~
 565
 566 The line block styles wrap the various nested levels of line
 567 blocks.  There is one line block style for each indent level.
 568
 569 rststyle-lineblock1
 570     Line block style for line block with no indent.
 571
 572 rststyle-lineblock2
 573     Line block style for line block indented 1 level.
 574
 575 rststyle-lineblock3
 576     Line block style for line block indented 2 levels.
 577
 578 rststyle-lineblock4
 579     Line block style for line block indented 3 levels.
 580
 581 rststyle-lineblock5
 582     Line block style for line block indented 4 levels.
 583
 584 rststyle-lineblock6
 585     Line block style for line block indented 5 levels.
 586
 587 Notes:
 588
 589 - ``odtwriter`` does not check for a maximum level of indents
 590   within line blocks.  Therefore, you can define additional line
 591   block styles for additional levels if you need them.  Define
 592   these styles with the names ``rststyle-lineblock7``,
 593   ``rststyle-lineblock8``, ...
 594
 595 - Since the line block style is used to create indentation, a line
 596   block that is inside a block quote will use
 597   ``rststyle-lineblock2`` as its first level of indentation.
 598
 599
 600 Footnote and citation styles
 601 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 602
 603 rststyle-footnote
 604     The style for footnotes.  This style affects the footnote
 605     content, *not* the footnote reference in the body of the document.
 606
 607 rststyle-citation
 608     The style for citations.  This style affects the citation
 609     content, *not* the citation reference in the body of the document.
 610     You might need to adjust the indentation in this style
 611     depending on the length of the label used in your citations.
 612
 613
 614 Heading and title styles
 615 ~~~~~~~~~~~~~~~~~~~~~~~~~
 616
 617 rststyle-heading{1|2|3|4|5}
 618     The styles for headings (section titles and sub-titles).  Five
 619     levels of sub-headings are provided: rststyle-heading1 through
 620     rststyle-heading5.
 621
 622 rststyle-title
 623     The style for the document title.
 624
 625 rststyle-subtitle
 626     The style for the document sub-title.
 627
 628
 629 Image and figure styles
 630 ~~~~~~~~~~~~~~~~~~~~~~~~~
 631
 632 rststyle-image
 633     The style applied to an image, either an image by itself or an
 634     image in a figure.
 635
 636 rststyle-figureframe
 637     The style applied to a figure (actually to the frame that
 638     surrounds a figure).
 639
 640
 641
 642 Defining and using a custom stylesheet
 643 ---------------------------------------
 644
 645 You can create your own custom stylesheet.  Here is how:
 646
 647 1. Make a copy of ``styles.odt``, which is in the distribution.
 648
 649 2. Open your copy of ``styles.odt`` in ``oowriter``.  Modify styles
 650    in that document.  Then, save it.
 651
 652 3. When you run ``rst2odt.py``, use the ``--stylesheet`` command
 653    line option to use your custom stylesheet.  Run ``rst2odt.py
 654    --help`` to learn more about these options.
 655
 656
 657 Why custom stylesheets
 658 ~~~~~~~~~~~~~~~~~~~~~~~
 659
 660 Here are a few reasons and ideas:
 661
 662 - The page size is stored in the style sheet.  The default page
 663   size is ``Letter``.  You can change the page size (for example,
 664   to ``A4``) in your custom stylesheet by opening it in
 665   ``oowriter``, then clicking on menu: ``Format/Page...``, then
 666   clicking on the ``Page`` tab.
 667
 668
 669
 670 Defining and using custom style names
 671 -------------------------------------
 672
 673 [Credits: Stefan Merten designed and implemented the custom style names
 674 capability.  Thank you, Stefan.]
 675
 676 You can also instruct ``odtwriter`` to use style names of your own
 677 choice.
 678
 679
 680 Why custom style names
 681 ~~~~~~~~~~~~~~~~~~~~~~
 682
 683 Here are a few reasons and ideas:
 684
 685 - Suppose that your organization has a standard set of styles in
 686   OOo ``oowriter`` and suppose that the use of these styles is
 687   required. You would like to generate ODF documents from
 688   reST text files, and you want the generated documents to contain
 689   these styles.
 690
 691 - Suppose that your company or organization has a policy of using a
 692   certain MS Word template for some set of documents.  You would
 693   like to generate ODF documents that use these custom style names,
 694   so that you can export these documents from ODF ``oowriter`` to MS
 695   Word documents that use these style names.
 696
 697 - Suppose that your documents are written in a language other than
 698   English.  You would like the style names visible in the "Styles
 699   and Formatting" window in OOo ``oowriter`` (menu item
 700   ``Format/Styles and Formatting``) to be understandable in the
 701   language of your users.
 702
 703 - ``odtwriter`` maps single asterisks/stars (for example, \*stuff\*)
 704   to emphasis and double stars to strong.  You'd like to reverse
 705   these.  Or, you would like to generate headings level 3 and 4
 706   where headings level 1 and 2 would normally be produced.
 707
 708
 709 How to use custom style names
 710 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 711
 712 In order to define custom style names and to generate documents that
 713 contain them, do the following:
 714
 715
 716 1. Create a configuration file containing a "Formats" section.  The
 717    configuration file obeys the file format supported by the Python
 718    ConfigParser module:
 719    `ConfigParser -- Configuration file parser --
 720    http://docs.python.org/lib/module-ConfigParser.html
 721    <http://docs.python.org/lib/module-ConfigParser.html>`_.
 722
 723 2. In the "Formats" section of the configuration file, create one
 724    option (a name-value pair) for each custom style name that you
 725    wish to define.  The option name is the standard ``odtwriter``
 726    style name (without "rststyle-"), and the value is your custom
 727    style name.  Here is an example::
 728
 729        [Formats]
 730        textbody: mytextbody
 731        bulletitem: mybulletitem
 732        heading1: myheading1
 733            o
 734            o
 735            o
 736
 737 3. Create a styles document that defines the styles generated by
 738    ``odtwriter``.  You can create and edit the styles in OOo
 739    ``oowriter``.  It may be helpful to begin by making a copy of the
 740    styles document that is part of the ``odtwriter`` distribution
 741    (``styles.odt``).
 742
 743 4. When you run ``odtwriter``, specify the ``--odf-config-file``
 744    option.  You might also want to specify your styles document
 745    using the ``--stylesheet`` option in order to include your
 746    custom style definitions.  For example::
 747
 748        rst2odt.py --odf-config-file=mymappingfile.ini \
 749          --stylesheet=mystyles.odt mydoc.txt mydoc.odt
 750
 751
 752 Classes
 753 -------
 754
 755 ``odtwriter`` uses the following Docutils class to provide additional
 756 control of the generation of ODF content:
 757
 758 - Class ``wrap`` -- Use this to cause the wrapping of text around
 759   an image.  The default is *not* to wrap text around images.
 760   Here is an example::
 761
 762       .. class:: wrap
 763       .. image:: images/flower01.png
 764           :alt: A bright yellow flower
 765           :height: 55
 766           :width: 60
 767
 768
 769 Roles
 770 -------
 771
 772 You can use a Docutils custom interpreted text role to attach a
 773 character style to an inline area of text.  This capability also
 774 enables you to attach a new character style (with a new name) that
 775 you define yourself.  Do this by defining your role in a stylesheet
 776 as a character style with "rststyle-" prefixed to your role name,
 777 then use the ``role`` directive and inline markup to apply your
 778 role.
 779
 780 In order to use this capability, do the following:
 781
 782 - Define the character style for your custom role in a stylesheet
 783   (a copy of ``styles.odt``) with the prefix "rststyle-".
 784   Remember: (1) If the name of your custom role is "pretty", then
 785   define a character style named "rststyle-pretty".  (2) Define the
 786   style as a *character* style, and *not*, for example as a
 787   paragraph style.
 788
 789 - Declare your role in the source reStructuredText document in a
 790   ``role`` directive.  Example::
 791
 792       .. role:: pretty
 793
 794 - Use inline markup to apply your role to text.  Example::
 795
 796       We have :pretty:`very nice` apples.
 797
 798 Here is another example::
 799
 800     .. role:: fancy
 801
 802     Here is some :fancy:`pretty text` that looks fancy.
 803
 804 For more on roles see:
 805 `Custom Interpreted Text Roles --
 806 http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
 807 <http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles>`_.
 808
 809 **Note:** The ability to base a role on another existing role is
 810 *not* supported by ``odtwriter``.
 811
 812
 813 Hints and Suggestions and Features
 814 ==================================
 815
 816 Table of contents
 817 -----------------
 818
 819 The ``..contents::`` directive causes ``odtwriter`` to generate
 820 either:
 821
 822 1. A static, outline style table of contents, if the
 823    ``--generate-list-toc`` command line option is specified, or
 824
 825 2. An ODF/``oowriter`` style table of contents containing
 826    dynamically updated page numbers and with the formatting control
 827    that ``oowriter`` gives you.  This is the default, or use the
 828    command line option ``--generate-list-toc``.  **Note:**
 829    ``odtwriter`` is not able to determine page numbers, so you will
 830    need to open the generated document in ``oowriter``, then
 831    right-click on the table of contents and select "Update" to
 832    insert correct page numbers.
 833
 834
 835 Syntax highlighting
 836 -------------------
 837
 838 ``odtwriter`` can add syntax highlighting to code in code
 839 blocks.  In order to activate this, do all of the following:
 840
 841 1. Install `Pygments`_ and ...
 842
 843 2. Use the command line option ``--add-syntax-highlighting``.
 844    Example::
 845
 846        $ rst2odt.py --add-syntax-highlight test.txt test.odt
 847
 848 The following styles are defined in styles.odt and are used for
 849 literal code blocks and syntax highlighting:
 850
 851 - Paragraph styles:
 852
 853   - rststyle-codeblock -- The style for the code block as a whole.
 854
 855 - Character styles:
 856
 857   - rststyle-codeblock-classname -- class names.
 858
 859   - rststyle-codeblock-comment -- comments.
 860
 861   - rststyle-codeblock-functionname -- function names.
 862
 863   - rststyle-codeblock-keyword -- Python language keywords.
 864
 865   - rststyle-codeblock-name -- other names, for example,
 866     variables.
 867
 868   - rststyle-codeblock-number -- literal numbers, including
 869     integers, floats, hex numbers, and octal numbers.
 870
 871   - rststyle-codeblock-operator -- Python operators.
 872
 873   - rststyle-codeblock-string -- literal strings.
 874
 875 Each of the above styles has a default appearance that is defined
 876 in ``styles.odt``.  To change that definition and appearance, open
 877 ``styles.odt`` in ``oowriter`` and use menu item::
 878
 879     Format --> Styles and Formatting
 880
 881 Then, click on the Paragraph Styles button or the Character Styles
 882 button at the top of the Styles and Formatting window.  You may
 883 also need to select "All Styles" from the drop-down selection list
 884 at the bottom of the Styles and Formatting window.
 885
 886
 887
 888 The container directive
 889 -----------------------
 890
 891 There is limited support for the ``container`` directive.  The
 892 limitations and rules for the container directive are the following:
 893
 894 - Only the first class in the list of classes (arguments) is used.
 895
 896 - That class/style must be a paragraph style and not (for example) a
 897   character style.
 898
 899 - The style/class given to the container directive will have a
 900   "rststyle-" prefix in the odt file.
 901
 902 So, for example::
 903
 904     .. container:: style-1 style-2 style-3
 905
 906         a block of text
 907
 908 - Only ``style-1`` is used; ``style-2`` and ``style-3`` are ignored.
 909
 910 - ``rststyle-style-1`` must be defined.  It should be an existing,
 911   predefined style, or you should define it in your stylesheet
 912   (``styles.odt`` or the argument to the ``--stylesheet`` command
 913   line option).
 914
 915 - ``rststyle-style-1`` must be a paragraph style.
 916
 917 To define a paragraph style, use the following menu item in
 918 ``oowriter``::
 919
 920     Format --> Styles and Formatting
 921
 922 Then, click on the Paragraph Styles button.
 923
 924 The following example attaches the ``rststyle-heading2`` style (a
 925 predefined style) to each paragraph/line in the container::
 926
 927     .. container:: heading2
 928
 929        Line 1 of container.
 930
 931        Line 2 of container.
 932
 933 More information on how to define a new style (for example, in your
 934 ``styles.odt``) can be found in section
 935 `Defining and using custom style names`_.
 936
 937
 938
 939 The table directive
 940 -------------------
 941
 942 The ``table`` directive can be used to add a title to a table.
 943 Example::
 944
 945     .. table:: A little test table
 946
 947         =========== =============
 948         Name        Value
 949         =========== =============
 950         Dave        Cute
 951         Mona        Smart
 952         =========== =============
 953
 954 The above will insert the title "A little test table" at the top of the
 955 table.  You can modify the appearance of the title by modifying the
 956 paragraph style ``rststyle-table-title``.
 957
 958
 959 Footnotes and citations
 960 -----------------------
 961
 962 Footnotes and citations are supported.
 963
 964 There are additional styles ``rststyle-footnote`` and
 965 ``rststyle-citation`` for footnotes and citations. See
 966 `Footnote and citation styles`_.
 967
 968 You may need to modify the citation style to fit the length of your
 969 citation references.
 970
 971 Endnotes -- There are command line options that control whether
 972 ``odtwriter`` creates endnotes instead of footnotes.  Endnotes
 973 appear at the end of the document instead of at the bottom of the
 974 page.  See flags ``--endnotes-end-doc`` and
 975 ``--no-endnotes-end-doc`` in section `Command line options`_.
 976
 977
 978 Images and figures
 979 ------------------
 980
 981 If on the image or the figure directive you provide the scale option
 982 but do not provide the width and height options, then ``odtwriter``
 983 will attempt to determine the size of the image using the `Python
 984 Imaging Library`_ (PIL).  If ``odtwriter`` cannot find and import
 985 Python Imaging Library, it will raise an exception.  If this
 986 ocurrs, you can fix it by doing one of the following:
 987
 988 - Install the Python Imaging Library or
 989
 990 - Remove the ``scale`` option or
 991
 992 - Add both the ``width`` and the ``height`` options.
 993
 994 So, the rule is: if on any image or figure, you specify scale but
 995 not both width and height, you must install the `Python Imaging
 996 Library`_ library.
 997
 998 For more information about PIL, see: `Python Imaging Library`_.
 999
1000
1001 The raw directive
1002 -----------------
1003
1004 The ``raw`` directive is supported.  Use output format type "odt".
1005
1006 You will need to be careful about the formatting of the raw
1007 content.  In particular, introduced whitespace might be a problem.
1008
1009 In order to produce content for the raw directive for use by
1010 ``odtwriter``, you might want to extract the file ``content.xml``
1011 from a ``.odt`` file (using some Zip tool), and then clip, paste,
1012 and modify a selected bit of it.
1013
1014 Here is an example::
1015
1016     .. raw:: odt
1017
1018         <text:p text:style-name="rststyle-textbody">Determining
1019         <text:span text:style-name="rststyle-emphasis">which</text:span>
1020         namespace a name is in is static.  It can be determined by a
1021         lexical scan of the code.  If a variable is assigned a value
1022         <text:span text:style-name="rststyle-emphasis">anywhere</text:span>
1023         in a scope (specifically within a function or method body),
1024         then that variable is local to that scope.  If Python does
1025         not find a variable in the local scope, then it looks next
1026         in the global scope (also sometimes called the module scope)
1027         and then in the built-ins scope.  But, the
1028         <text:span text:style-name="rststyle-inlineliteral">global</text:span>
1029         statement can be used to force Python to find and use a global
1030         variable (a variable defined at top level in a module) rather
1031         than create a local one.</text:p>
1032
1033
1034 The meta directive
1035 ------------------
1036
1037 ``odtwriter`` supports the ``meta`` directive.  "keywords"
1038 and "description" are set in their respective odt fields.
1039 Other meta fields are set as "Custom Properties".
1040 Here is an example::
1041
1042     .. meta::
1043        :keywords: reStructuredText, docutils, formatting
1044        :description lang=en: A reST document, contains formatted
1045            text in a formatted style.
1046        :custom_var: Value
1047
1048 To see the results of the ``meta`` directive in ``oowriter``,
1049 select menu item "File/Properties...", then click on the
1050 "Description" tab ("keywords" and "description" fields) and the
1051 "Custom Properties" tab.
1052
1053
1054 Footnote references inside footnotes
1055 ------------------------------------
1056
1057 Not supported.
1058
1059 Get a grip.  Be serious.  Try a dose of reality.
1060
1061 ``odtwriter`` ignores them.
1062
1063 They cause ``oowriter`` to croak.
1064
1065
1066 Page size
1067 ---------
1068
1069 The default page size, in documents generated by ``odtwriter`` is
1070 ``Letter``.  You can change this (for example to ``A4``) by using a
1071 custom stylesheet.  See `Defining and using a custom stylesheet`_
1072 for instructions on how to do this.
1073
1074 On machines which support ``paperconf``, ``odtwriter`` can insert
1075 the default page size for your locale.  In order for this to work,
1076 the following conditions must be met:
1077
1078 1. The program ``paperconf`` must be available on your system.
1079    ``odtwriter`` uses ``paperconf -s`` to obtain the paper size.
1080    See ``man paperconf`` for more information.
1081
1082 2. The default page height and width must be removed from the
1083    ``styles.odt`` used to generate the document.  A Python script
1084    ``rst2odt_prepstyles.py`` is distributed with ``odtwriter`` and
1085    is installed in the ``bin`` directory.  You can remove the page
1086    height and width with something like the following::
1087
1088        $ rst2odt_prepstyles.py styles.odt
1089
1090 .. warning:: If you edit your stylesheet in ``oowriter`` and then
1091     save it, ``oowriter`` automatically inserts a page height and
1092     width in the styles for that (stylesheet) document.  If that is
1093     not the page size that you want and you want ``odtwriter`` to
1094     insert a default page size using ``paperconf``, then you will
1095     need to strip the page size from your stylesheet each time you
1096     edit that stylesheet with ``oowriter``.
1097
1098
1099
1100 Custom header/footers: inserting page numbers, date, time, etc
1101 ----------------------------------------------------------------
1102
1103 You can specify custom headers and footers for your document from
1104 the command line.  These headers and footers can be used to insert
1105 fields such as the page number, page count, date, time, etc.  See
1106 below for a complete list.
1107
1108 To insert a custom header or footer, use the "--custom-odt-header"
1109 or "--custom-odt-footer" command line options.  For example, the
1110 following inserts a footer containing the page number and page
1111 count::
1112
1113     $ rst2odt.py --custom-odt-footer="Page %p% of %P%" f1.txt f1.odt
1114
1115
1116 Field specifiers
1117 ~~~~~~~~~~~~~~~~~~
1118
1119 You can use the following field specifiers to insert ``oowriter``
1120 fields in your custom headers and footers:
1121
1122 %p%
1123     The current page number.
1124
1125 %P%
1126     The number of pages in the document.
1127
1128 %d1%
1129     The current date in format 12/31/99.
1130
1131 %d2%
1132     The current date in format 12/31/1999.
1133
1134 %d3%
1135     The current date in format Dec 31, 1999.
1136
1137 %d4%
1138     The current date in format December 31, 1999.
1139
1140 %d5%
1141     The current date in format 1999-12-31.
1142
1143 %t1%
1144     The current time in format 14:22.
1145
1146 %t2%
1147     The current time in format 14:22:33.
1148
1149 %t3%
1150     The current time in format 02:22 PM.
1151
1152 %t4%
1153     The current time in format 02:22:33 PM.
1154
1155 %a%
1156     The author of the document (actually the initial creator).
1157
1158 %t%
1159     The document title.
1160
1161 %s%
1162     The document subject.
1163
1164
1165 **Note:** The use of the above field specifiers in the body of your
1166 reStructuredText document is **not** supported, because these
1167 specifiers are not standard across Docutils writers.
1168
1169
1170
1171 Credits
1172 =======
1173
1174 Stefan Merten designed and implemented the custom style names
1175 capability.  Thank you, Stefan.
1176
1177 Michael Schutte supports the Debian GNU/Linux distribution of
1178 ``odtwriter``.  Thank you, Michael, for providing and supporting
1179 the Debian package.
1180
1181 Michael Schutte implemented the fix that enables ``odtwriter`` to
1182 pick up the default paper size on platforms where the program
1183 ``paperconf`` is available.  Thank you.
1184
1185
1186
1187
1188 .. _`Pygments`:
1189     http://pygments.pocoo.org/
1190
1191 .. _`Docutils`:
1192     http://docutils.sourceforge.net/
1193
1194 .. _`Python Imaging Library`:
1195     https://en.wikipedia.org/wiki/Python_Imaging_Library
1196
1197 .. _`Open Document at Wikipedia`:
1198     http://en.wikipedia.org/wiki/OpenDocument
1199
1200 .. _`OASIS Open Document Format for Office Applications (OpenDocument) TC`:
1201     http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office