2.1   Where to get it

The distribution file is here: source distribution of ODF/ODT writer for Docutils.

odtwriter is also available via Subversion from the Docutils repository under docutils/sandbox/dkuhlman/OpenDocument/. The following will download Docutils including odtwriter and associated files into your current directory:

$ svn checkout svn://svn.berlios.de/docutils/trunk docutils

For more information about access to the Docutils Subversion repository, see: http://docutils.sourceforge.net/docs/dev/repository.html.

2.2   Requirements

odtwriter requires:

• Python

• A sufficiently recent version of Docutils.

• Either of the following:

  • ElementTree -- See: http://effbot.org/zone/element-index.htm
  • Lxml -- See: http://codespeak.net/lxml/

  odtwriter will try first to use Lxml, and if it is not installed will use ElementTree.

• Optional -- Pygments is required for syntax highlighting of code in literal blocks. See section Syntax highlighting.

2.3   Installation

Install odtwriter with the standard Python installation commands:

$ python setup.py build
$ python setup.py install       # possibly as root

This will install rst2odt.py in your bin directory and the odtwriter and the styles file under docutils/writers/odtwriter within your Docutils installation.

3.1   Command line flags

The following command line flags are specific to odtwriter:

4.1   Styles used by odtwriter

This section describes the styles used by odtwriter.

Note that we do not describe the "look" of these styles. That can be easily changed by using oowriter to edit the document styles.odt (or a copy of it), and modifying any of the styles described here.

To change the definition and appearance of these styles, open styles.odt in oowriter and open the Styles and Formatting window by using the following menu item:

Format --> Styles and Formatting

Then, click on the Paragraph Styles button or the Character Styles button at the top of the Styles and Formatting window. You may also need to select "All Styles" from the drop-down selection list at the bottom of the Styles and Formatting window in order to see the styles used by odtwriter.

Notice that you can make a copy of file styles.odt, modify it using oowriter, and then use your copy with the --stylesheet-path=<file> command line option. Example:

$ rst2odt.py --stylesheet-path=mystyles.odt test2.txt test2.odt

5.1   Table of contents

odtwriter can generate an outline style table of contents. However, if you want an oowriter style table of contents along with the formatting control that oowriter gives you, then you may want to omit the .. contents:: directive and, after generating your document, open it in oowriter and insert a table of contents. That feature is under menu item:

Insert --> Indexes and Tables --> Indexes and Tables

5.2   Syntax highlighting

odtwriter can add Python syntax highlighting to code in literal code blocks. In order to activate this, do both of the following: (1) install Pygments and (2) use the command line flag --add-syntax-highlighting. Example:

$ rst2odt.py -g --add-syntax-highlight test.txt test.odt

Caution: When odtwriter does syntax highlighting, by default, it applies a Python lexer and Python syntax highlighting. If you have literal code blocks that contain code which is not Python code, then you likely to want either (1) to use the .. sourcecode:: directive to change the language/lexer or to turn off highlighting across sections of your document or (2) to not use the --add-syntax-highlighting flag.

You can find Pygments here: Pygments.

The following styles are defined in styles.odt and are used for literal code blocks and syntax highlighting:

• Paragraph styles:
  • rststyle-codeblock -- The style for the code block as a whole.
• Character styles:
  • rststyle-codeblock-classname -- class names.
  • rststyle-codeblock-comment -- comments.
  • rststyle-codeblock-functionname -- function names.
  • rststyle-codeblock-keyword -- Python language keywords.
  • rststyle-codeblock-name -- other names, for example, variables.
  • rststyle-codeblock-number -- literal numbers, including integers, floats, hex numbers, and octal numbers.
  • rststyle-codeblock-operator -- Python operators.
  • rststyle-codeblock-string -- literal strings.

Each of the above styles has a default appearance that is defined in styles.odt. To change that definition and appearance, open styles.odt in oowriter and use menu item:

Format --> Styles and Formatting

Then, click on the Paragraph Styles button or the Character Styles button at the top of the Styles and Formatting window. You may also need to select "All Styles" from the drop-down selection list at the bottom of the Styles and Formatting window.

.. sourcecode newstate

.. sourcecode lexer

.. sourcecode:: on
.. sourcecode:: python
.. sourcecode:: off
.. sourcecode:: java
.. sourcecode:: on

5.3   The container directive

There is limited support for the container directive. The limitations are the following:

• Only the first class in the list of classes (arguments) is used and
• That class/style must be a paragraph style and not (for example) a character style.

So, for example:

.. container:: style-1 style-2 style-3

    a block of text

Only style-1 is used; style-2 and style-3 are ignored. And, style-1 must be a paragraph style.

To define a paragraph style, use the following menu item:

Format --> Styles and Formatting

Then, click on the Paragraph Styles button.

5.4   The table directive

The table directive can be used to add a title to a table. Example:

.. table:: A little test table

    =========== =============
    Name        Value
    =========== =============
    Dave        Cute
    Mona        Smart
    =========== =============

The above will insert the title "A little test table" at the top of the table. You can modify the appearance of the title by modifying the paragraph style rststyle-table-title.