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