Odtwriter for Docutils

Author: Dave Kuhlman
Address:
dkuhlman@rexx.com
http://www.rexx.com/~dkuhlman
Revision: 1.0c
Date: Feb. 19, 2007
Copyright: Copyright (c) 2006 Dave Kuhlman. All Rights Reserved. This software is subject to the provisions of the MIT License http://www.opensource.org/licenses/mit-license.php.

Abstract

This document describes the Docutils odtwriter.

Contents

1   Introduction

What it does -- rst2odt.py/odtwriter.py translates reST (reStructuredText) into a Open Document Format .odt file. You can learn more about the ODF format here:

You should be able to open documents (.odt files) generated with rst2odt.py in OpenOffice/oowriter. I use OpenOffice version 2.0 in my testing.

2   How to Install It

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:

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   How to Use It

Run it from the command line as follows:

$ rst2odt.py myinput.txt myoutput.odt

To see usage information and to learn about command line flags that you can use, run the following:

$ rst2odt.py --help

Examples:

$ rst2odt.py -s -g python_comments.txt python_comments.odt

$ rst2odt.py --source-url=odtwriter.txt --generator --stylesheet-path=/myconfigs/styles.odt odtwriter.txt odtwriter.odt

3.1   Command line flags

The following command line flags are specific to odtwriter:

--stylesheet=<URL>
 Specify a stylesheet URL, used verbatim. Overrides --stylesheet-path.
--stylesheet-path=<file>
 Specify a stylesheet file, relative to the current working directory. The path is adjusted relative to the output ODF file. Overrides --stylesheet. Default: "/usr/local/lib/python2.5/site- packages/docutils/writers/odtwriter/styles.odt"
--cloak-email-addresses
 Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards- compliant browsers.
--table-border-thickness=TABLE_BORDER_THICKNESS
 Specify the thickness of table borders in thousands of a cm. Default is 35.
--add-syntax-highlighting
 Add syntax highlighting in literal code blocks. Default is no. Requires installation of Pygments.

4   Styles

odtwriter uses a number of styles that are defined in the default styles.xml. This section describes those styles.

You can modify the look of documents generated by odtwriter in several ways:

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

4.1.1   Paragraph styles

rststyle-blockindent
An indented block.
rststyle-blockquote
A block quote.
rststyle-codeblock
Literal code blocks -- A block of example code. Derived from the Preformatted Text style in oowriter.
rststyle-heading{1|2|3|4|5}
Headings (sub-titles). Five levels of sub-headings are provided: rststyle-heading1 through rststyle-heading5.
rststyle-bodyindent
An indented block.
rststyle-bulletitem
An item in an bullet list.
rststyle-enumitem
An item in an enumerated list.
rststyle-footer
The style for footers. The footer content originates from the ..footer:: directive and in response to the command line flags for generator (--generator), date/time generated (--date and --time), and view source link (--source-link and --source-url=URL).
rststyle-header
The style for headers. The header content originates from the ..header:: directive.
rststyle-horizontalline
A horizontal line, e.g. used for transitions.
rststyle-table-title
The style for titles of tables. See section The table directive.
rststyle-textbody
Normal text. The style for paragraphs.

4.1.2   Character styles

rststyle-emphasis
Emphasis. Normally rendered as italics.
rststyle-inlineliteral
An inline literal.
rststyle-strong
Strong emphasis. Normally rendered as boldface.
rststyle-quotation
In-line quoted material.
rststyle-codeblock-classname
Syntax highlighting in literal code blocks -- class names.
rststyle-codeblock-comment
Syntax highlighting in literal code blocks -- comments.
rststyle-codeblock-functionname
Syntax highlighting in literal code blocks -- function names.
rststyle-codeblock-keyword
Syntax highlighting in literal code blocks -- Python language keywords.
rststyle-codeblock-name
Syntax highlighting in literal code blocks -- other names, for example, variables.
rststyle-codeblock-number
Syntax highlighting in literal code blocks -- literal numbers, including integers, floats, hex numbers, and octal numbers.
rststyle-codeblock-operator
Syntax highlighting in literal code blocks -- Python operators.
rststyle-codeblock-string
Syntax highlighting in literal code blocks -- literal strings.

4.1.3   List styles

rststyle-bulletlist
Bullet lists (but not in the table of contents)
rststyle-enumlist
Enumerated lists (but not in the table of contents)
rststyle-tocbulletlist
Lists in the table of contents when section numbering is off
rststyle-tocenumlist
Lists in the table of contents when section numbering is on

4.1.4   Table styles

Table styles are generated by oowriter for each table that you create. Therefore, odtwriter attempts to do something similar. These styles are created in the content.xml document in the generated .odt. These styles have names prefixed with "rststyle-Table".

5   Hints and Suggestions

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.

5.2.1   Controlling syntax highlighting within a document

By default, when you use the --add-syntax-highlighting command line flag, syntax highlighting in literal blocks is on and the Python lexer is used. You can change this within your reST document with the following directive:

.. sourcecode newstate

or:

.. sourcecode lexer

where:

  • newstate is either "on" or "off", which makes highlighting active or inactive.
  • lexer is the Pygments lexer to use. Change the lexer to match the language in literal code blocks. lexer should be one of aliases listed at Pygments Available Lexers, for example "python", "pycon", "java", "cpp", "c", "perl", "javascript", etc.

Examples:

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

A few additional notes and hints:

  • The syntax highlighting state and language/lexer set by this directive remain in effect until the next sourcecode directive is encountered in the reST document.
  • In order to turn syntax highlighting on (or off) and set the lexer, you will need to use this directive twice.
  • Special note to Pythonistas, there is a separate lexer for examples of code from the Python interactive prompt and console output or doctests. The alias for that lexer is "pycon".

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.