Odt Writer for Docutils

Author: Dave Kuhlman
Contact: dkuhlman@rexx.com
Revision: 5965
Date: 2009-05-28
Copyright: This document has been placed in the public domain.

Abstract

This document describes the Docutils odtwriter (rst2odt.py).

Contents

1   Introduction

What it does -- rst2odt.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.

You can learn more about Docutils and reST here: Docutils

2   Requirements

In addition to the Docutils standard requirements, odtwriter requires:

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=/myconfigs/styles.odt odtwriter.txt odtwriter.odt

3.1   Command line options

The following command line flags are specific to odtwriter:

--stylesheet=<URL>
 Specify a stylesheet URL, used verbatim. Default: writers/odf_odt/styles.odt in the installation directory.
--odf-config-file=<file>
 Specify a configuration/mapping file relative to the current working directory for additional ODF options. In particular, this file may contain a section named "Formats" that maps default style names to names to be used in the resulting output file allowing for adhering to external standards. For more info and the format of the configuration/mapping file, see the odtwriter doc.
--cloak-email-addresses
 Obfuscate email addresses to confuse harvesters while still keeping email links usable with standards- compliant browsers.
--no-cloak-email-addresses
 Do not obfuscate email addresses.
--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.
--no-syntax-highlighting
 Do not add syntax highlighting in literal code blocks. (default)
--create-sections
 Create sections for headers. (default)
--no-sections Do not create sections for headers.
--create-links Create links.
--no-links Do not create links. (default)
--endnotes-end-doc
 Generate endnotes at end of document, not footnotes at bottom of page.
--no-endnotes-end-doc
 Generate footnotes at bottom of page, not endnotes at end of document. (default)
--generate-list-toc
 Generate a bullet list table of contents, not an ODF/oowriter table of contents.
--generate-oowriter-toc
 Generate an ODF/oowriter table of contents, not a bullet list. (default) Note: odtwriter is not able to determine page numbers, so you will need to open the generated document in oowriter, then right-click on the table of contents and select "Update" to insert page numbers.

4   Styles and Classes

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

Note that with the --stylesheet command line option, you can use either styles.odt or styles.xml, as described below. Use of styles.odt is recommended over styles.xml.

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=<file> command line option. Example:

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

4.1.1   Paragraph styles

rststyle-attribution
The style for attributions, for example, the attribution in a .. epigraph:: directive. Derived from rststyle-blockquote.
rststyle-blockindent
An indented block.
rststyle-blockquote
A block quote.
rststyle-blockquote-bulletitem
The style for bullet list items inside block quote.
rststyle-blockquote-enumitem
The style for enumerated list items inside block quote.
rststyle-bodyindent
An indented block.
rststyle-bulletitem
An item in an bullet list.
rststyle-codeblock
Literal code blocks -- A block of example code. Created with double colon ("::") followed by an indented block or with the .. parsed-literal:: directive. Derived from the Preformatted Text style in oowriter.
rststyle-enumitem
An item in an enumerated list.
rststyle-epigraph
The style for epigraphs, for example, the body of an .. epigraph:: directive. Derived from rststyle-blockquote.
rststyle-epigraph-bulletitem
The style for bullet list items inside epigraphs.
rststyle-epigraph-enumitem
The style for enumerated list items inside epigraphs.
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-highlights
The style for highlightss, for example, the body of an .. highlights:: directive. Derived from rststyle-blockquote.
rststyle-highlights-bulletitem
The style for bullet list items inside highlights.
rststyle-highlights-enumitem
The style for enumerated list items inside highlights.
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. Derived from the Text body style in oowriter.

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-blockquote-bulletlist
Bullet lists in block quotes.
rststyle-blockquote-enumlist
Enumerated lists in block quotes.
rststyle-enumlist-arabic
Enumerated lists, arabic (but not in the table of contents)
rststyle-enumlist-loweralpha
Enumerated lists, lower alpha (but not in the table of contents)
rststyle-enumlist-lowerroman
Enumerated lists, lower roman (but not in the table of contents)
rststyle-enumlist-upperalpha
Enumerated lists, upper alpha (but not in the table of contents)
rststyle-enumlist-upperroman
Enumerated lists, upper roman (but not in the table of contents)
rststyle-epigraph-bulletlist
Bullet lists in epigraphs. See the .. epigraph:: directive.
rststyle-epigraph-enumlist
Enumerated lists in epigraphs. See the .. epigraph:: directive.
rststyle-highlights-bulletlist
Bullet lists in highlights blocks. See the .. highlights:: directive.
rststyle-highlights-enumlist
Enumerated lists in highlights blocks. See the .. highlights:: directive.
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   Admonition styles

rststyle-admon-attention-hdr
The style for the attention admonition header/title.
rststyle-admon-attention-body
The style for the attention admonition body/paragraph.
rststyle-admon-caution-hdr
The style for the caution admonition header/title.
rststyle-admon-caution-body
The style for the caution admonition body/paragraph.
rststyle-admon-danger-hdr
The style for the admonition header/title.
rststyle-admon-danger-body
The style for the danger admonition body/paragraph.
rststyle-admon-error-hdr
The style for the error admonition header/title.
rststyle-admon-error-body
The style for the error admonition body/paragraph.
rststyle-admon-hint-hdr
The style for the hint admonition header/title.
rststyle-admon-hint-body
The style for the hint admonition body/paragraph.
rststyle-admon-hint-hdr
The style for the hint admonition header/title.
rststyle-admon-hint-body
The style for the hint admonition body/paragraph.
rststyle-admon-important-hdr
The style for the important admonition header/title.
rststyle-admon-important-body
The style for the important admonition body/paragraph.
rststyle-admon-note-hdr
The style for the note admonition header/title.
rststyle-admon-note-hdr
The style for the note admonition header/title.
rststyle-admon-tip-body
The style for the tip admonition body/paragraph.
rststyle-admon-tip-hdr
The style for the tip admonition header/title.
rststyle-admon-warning-body
The style for the warning admonition body/paragraph.
rststyle-admon-warning-hdr
The style for the warning admonition header/title.
rststyle-admon-generic-body
The style for the generic admonition body/paragraph.
rststyle-admon-generic-hdr
The style for the generic admonition header/title.

4.1.5   Rubric style

rststyle-rubric
The style for the text in a rubric directive.

The rubric directive recognizes a "class" option. If entered, odtwriter uses the value of that option instead of the rststyle-rubric style. Here is an example which which attaches the rststyle-heading1 style to the generated rubric:

.. rubric:: This is my first rubric
   :class: rststyle-heading1

4.1.6   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".

4.1.7   Line block styles

The line block styles wrap the various nested levels of line blocks. There is one line block style for each indent level.

rststyle-lineblock1
Line block style for line block with no indent.
rststyle-lineblock2
Line block style for line block indented 1 level.
rststyle-lineblock3
Line block style for line block indented 2 levels.
rststyle-lineblock4
Line block style for line block indented 3 levels.
rststyle-lineblock5
Line block style for line block indented 4 levels.
rststyle-lineblock6
Line block style for line block indented 5 levels.

Notes:

  • odtwriter does not check for a maximum level of indents within line blocks. Therefore, you can define additional line block styles for additional levels if you need them. Define these styles with the names rststyle-lineblock7, rststyle-lineblock8, ...
  • Since the line block style is used to create indentation, a line block that is inside a block quote will use rststyle-lineblock2 as its first level of indentation.

4.1.8   Footnote and citation styles

rststyle-footnote
The style for footnotes. This style affects the footnote content, not the footnote reference in the body of the document.
rststyle-citation
The style for citations. This style affects the citation content, not the citation reference in the body of the document. You might need to adjust the indentation in this style depending on the length of the label used in your citations.

4.1.9   Heading and title styles

rststyle-heading{1|2|3|4|5}
The styles for headings (section titles and sub-titles). Five levels of sub-headings are provided: rststyle-heading1 through rststyle-heading5.
rststyle-title
The style for the document title.
rststyle-subtitle
The style for the document sub-title.

4.2   Defining and using a custom stylesheet

You can create your own custom stylesheet. Here is how:

  1. Make a copy of styles.odt, which is in the distribution.
  2. Open your copy of styles.odt in oowriter. Modify styles in that document. Then, save it.
  3. When you run rst2odt.py, use the --stylesheet command line option to use your custom stylesheet. Run rst2odt.py --help to learn more about these options.

4.2.1   Why custom stylesheets

Here are a few reasons and ideas:

  • The page size is stored in the style sheet. The default page size is Letter. You can change the page size (for example, to A4) in your custom stylesheet by opening it in oowriter, then clicking on menu: Format/Page..., then clicking on the Page tab.

4.3   Defining and using custom style names

[Credits: Stefan Merten designed and implemented the custom style names capability. Thank you, Stefan.]

You can also instruct odtwriter to use style names of your own choice.

4.3.1   Why custom style names

Here are a few reasons and ideas:

  • Suppose that your organization has a standard set of styles in OOo oowriter and suppose that the use of these styles is required. You would like to generate ODF documents from reST text files, and you want the generated documents to contain these styles.
  • Suppose that your company or organization has a policy of using a certain MS Word template for some set of documents. You would like to generate ODF documents that use these custom style names, so that you can export these documents from ODF oowriter to MS Word documents that use these style names.
  • Suppose that your documents are written in a language other than English. You would like the style names visible in the "Styles and Formatting" window in OOo oowriter (menu item Format/Styles and Formatting) to be understandable in the language of your users.
  • odtwriter maps single asterisks/stars (for example, *stuff*) to emphasis and double stars to strong. You'd like to reverse these. Or, you would like to generate headings level 3 and 4 where headings level 1 and 2 would normally be produced.

4.3.2   How to use custom style names

In order to define custom style names and to generate documents that contain them, do the following:

  1. Create a configuration file containing a "Formats" section. The configuration file obeys the file format supported by the Python ConfigParser module: ConfigParser -- Configuration file parser -- http://docs.python.org/lib/module-ConfigParser.html.

  2. In the "Formats" section of the configuration file, create one option (a name-value pair) for each custom style name that you wish to define. The option name is the standard odtwriter style name (without "rststyle-"), and the value is your custom style name. Here is an example:

    [Formats]
    textbody: mytextbody
    bulletitem: mybulletitem
    heading1: myheading1
        o
        o
        o
    
  3. Create a styles document that defines the styles generated by odtwriter. You can create and edit the styles in OOo oowriter. It may be helpful to begin by making a copy of the styles document that is part of the odtwriter distribution (styles.odt).

  4. When you run odtwriter, specify the --odf-config-file option. You might also want to specify your styles document using the --stylesheet option in order to include your custom style definitions. For example:

    rst2odt.py --odf-config-file=mymappingfile.ini --stylesheet=mystyles.odt mydoc.txt mydoc.odt
    

4.4   Classes

odtwriter uses the following Docutils class to provide additional control of the generation of ODF content:

  • Class wrap -- Use this to cause the wrapping of text around an image. The default is not to wrap text around images. Here is an example:

    .. class:: wrap
    .. image:: images/flower01.png
        :alt: A bright yellow flower
        :height: 55
        :width: 60
    

5   Hints and Suggestions and Features

5.1   Table of contents

The ..contents:: directive causes odtwriter to generate either:

  1. A static, outline style table of contents, if the --generate-list-toc command line option is specified, or
  2. An ODF/oowriter style table of contents containing dynamically updated page numbers and with the formatting control that oowriter gives you. This is the default, or use the command line option --generate-list-toc. Note: odtwriter is not able to determine page numbers, so you will need to open the generated document in oowriter, then right-click on the table of contents and select "Update" to insert correct page numbers.

5.2   Syntax highlighting

odtwriter can add syntax highlighting to code in code blocks. In order to activate this, do all of the following:

  1. Install Pygments and ...

  2. Use the command line flag --add-syntax-highlighting. Example:

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

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.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.

The following example attaches the rststyle-heading2 style (a predefined style) to each paragraph/line in the container:

.. container:: rststyle-heading2

   Line 1 of container.

   Line 2 of container.

You could also define a new style (for example, in your styles.odt) and reference that in a container directive.

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.

5.5   Footnotes and citations

Footnotes and citations are supported.

There are additional styles rststyle-footnote and rststyle-citation for footnotes and citations. See Footnote and citation styles.

You may need to modify the citation style to fit the length of your citation references.

Endnotes -- There are command line flags that control whether odtwriter creates endnotes instead of footnotes. Endnotes appear at the end of the document instead of at the bottom of the page. See flags --endnotes-end-doc and --no-endnotes-end-doc in section Command line options.

5.6   Images and figures

If on the image or the figure directive you provide the scale option but do not provide the width and height options, then odtwriter will attempt to determine the size of the image using the Python Imaging Library (PIL). If odtwriter cannot find and import Python Imaging Library, it will raise an exception. If this ocurrs, you can fix it by doing one of the following:

  • Install the Python Imaging Library or
  • Remove the scale option or
  • Add both the width and the height options.

So, the rule is: if on any image or figure, you specify scale but not both width and height, you must install the Python Imaging Library library.

For more information about PIL, see: Python Imaging Library.

5.7   The raw directive

The raw directive is supported. Use output format type "odt".

You will need to be careful about the formatting of the raw content. In particular, introduced whitespace might be a problem.

In order to produce content for the raw directive for use by odtwriter, you might want to extract the file content.xml from a .odt file (using some Zip tool), and then clip, paste, and modify a selected bit of it.

Here is an example:

.. raw:: odt

    <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
    determined by a lexical scan of the code.  If a variable is assigned a
    value <text:span text:style-name="rststyle-emphasis">anywhere</text:span> in a scope (specifically within a function or method
    body), then that variable is local to that scope.  If Python does not
    find a variable in the local scope, then it looks next in the global
    scope (also sometimes called the module scope) and then in the
    built-ins scope.  But, the <text:span text:style-name="rststyle-inlineliteral">global</text:span> statement can be used to force
    Python to find and use a global variable (a variable defined at top
    level in a module) rather than create a local one.</text:p>

5.8   The meta directive

odtwriter supports the meta directive. Two fields are recognized: "keywords" and "description". Here is an example:

.. meta::
   :keywords: reStructuredText, docutils, formatting
   :description lang=en: A reST document, contains formatted
       text in a formatted style.

To see the results of the meta directive in oowriter, select menu item "File/Properties...", then click on the "Description" tab.

5.9   Footnote references inside footnotes

Not supported.

Get a grip. Be serious. Try a dose of reality.

odtwriter ignores them.

They cause oowriter to croak.

5.10   Page size

The default page size, in documents generated by odtwriter is Letter. You can change this (for example to A4) by using a custom stylesheet. See Defining and using a custom stylesheet for instructions on how to do this.

On machines which support paperconf, odtwriter can insert the default page size for your locale. In order for this to work, the following conditions must be met:

  1. The program paperconf must be available on your system. odtwriter uses paperconf -s to obtain the paper size. See man paperconf for more information.

  2. The default page height and width must be removed from the styles.odt used to generate the document. A Python script rst2odt_prepstyles.py is distributed with odtwriter and is installed in the bin directory. You can remove the page height and width with something like the following:

    $ rst2odt_prepstyles.py styles.odt
    

Warning

If you edit your stylesheet in oowriter and then save it, oowriter automatically inserts a page height and width in the styles for that (stylesheet) document. If that is not the page size that you want and you want odtwriter to insert a default page size using paperconf, then you will need to strip the page size from your stylesheet each time you edit that stylesheet with oowriter.

6   Credits

Stefan Merten designed and implemented the custom style names capability. Thank you, Stefan.

Michael Schutte supports the Debian GNU/Linux distribution of odtwriter. Thank you, Michael, for providing and supporting the Debian package.

Michael Schutte implemented the fix that enables odtwriter to pick up the default paper size on platforms where the program paperconf is available. Thank you.