docs/user/odt.txt

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