======================
Odtwriter for Docutils
======================

:Author: Dave Kuhlman
:address: dkuhlman@rexx.com
    http://www.rexx.com/~dkuhlman

:revision: 1.0d
:date: March 13, 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.

.. sectnum::

.. contents::



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:

- `OASIS Open Document Format for Office Applications
  (OpenDocument) TC`_

- `Open Document at Wikipedia`_

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.


How to Install It
=================

Where to get it
---------------

The source distribution of 
ODF/ODT writer for Docutils 
is here:
`http://www.rexx.com/~dkuhlman/odtwriter-1.0d.tar.gz
<http://www.rexx.com/~dkuhlman/odtwriter-1.0d.tar.gz>`_.

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


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


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.


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

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.


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:

- Open (a copy of) ``styles.odt`` in ``OpenOffice/oowriter`` and
  modify the style you wish to change. Now, save this document,
  then generate your documents using this modified copy of
  ``styles.odt``.

  In my version of ``oowriter``, to modify styles, either (1)
  press F11 or (2) use menu item "Format/Styles and Formatting",
  then right-click on the relevant style and select "Modify".
  Modify the style, then save your document.

- Open a document generated by ``odtwriter`` in `oowriter``.  Now,
  edit the style you are interested in modifying.  Now, you
  can extract the styles.xml file from your document and either
  (1) use this as your default styles file or (2) copy and paste
  the relevant style definition into your styles.xml.

- Extract ``styles.xml`` from ``styles.odt`` using your favorite
  ``zip/unzip`` tool.  Then modify ``styles.xml`` with a text
  editor.  Now re-zip it back into your own ``styles.odt``, or use
  it directly by specifying it with a command line flag.
  **Hint:** If you intend to extract ``styles.xml`` from an
  ``.odt`` file (and then "re-zip" it), you should turn off XML
  optimization/compression in ``oowriter``.  In order to this in
  ``oowriter``, use Tools --> Options... --> Load-Save --> General
  and turn off "Size optimization for XML format".

- Open an empty (or new) document in ``oowriter``.  Define the
  styles described in this section.  Then, use that document (a
  .odt file) as your stylesheet.  ``odtwriter`` will extract the
  ``styles.xml`` file from that document and insert it into the
  output document.

- Some combination of the above.


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


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-footnote
    The style for footnotes.  This style affects the footnote
    content, not the footnote reference in the body of the document.

rststyle-header
    The style for headers.  The header content originates from the
    ``..header::`` directive.

rststyle-heading{1|2|3|4|5}
    Headings (sub-titles).  Five levels of sub-headings are
    provided: rststyle-heading1 through rststyle-heading5.

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

rststyle-lineblock
    The style for line blocks created either with the ``.. line-block::``
    directive or with vertical bars.  Derived from the
    ``rststyle-textbody`` style.


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.


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
    Enumerated lists (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.





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



.. _`Open Document at Wikipedia`:
    http://en.wikipedia.org/wiki/OpenDocument

.. _`OASIS Open Document Format for Office Applications (OpenDocument) TC`:
    http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office


Hints and Suggestions
=====================

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


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.


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
  <http://pygments.pocoo.org/docs/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".


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


Footnotes
---------

Footnotes are supported.

There is an additional style ``rststyle-footnote`` for footnotes.
See `Paragraph styles`_.




.. _`Pygments`:
    http://pygments.pocoo.org/




.. Configuration for Emacs
..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 68
   End:


