docutils/docs/user/odt.txt

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