.. -*- mode: rst -*- ====================== Odtwriter for Docutils ====================== :Author: Dave Kuhlman :address: dkuhlman@rexx.com http://www.rexx.com/~dkuhlman :revision: 1.2c :date: April 21, 2008 :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, an Open Source license. :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.3 in my testing. You can learn more about Docutils and reST here: `Docutils`_ 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.2b.tar.gz `_. ``odtwriter`` is also available via Subversion from the Docutils repository under ``docutils/sandbox/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`_. - One of the following: - Lxml -- See: http://codespeak.net/lxml/. - ElementTree -- See: http://effbot.org/zone/element-index.htm. - ElementTree from that Python standard library -- Python 2.5 and later comes with ElementTree included. ``odtwriter`` will try first to use Lxml; if that fails, it will try to use a separately installed version of ElementTree; and if that fails, it will try to use ElementTree from the standard library. - Optional -- `Pygments`_ is required if you want syntax highlighting of code in literal blocks. See section `Syntax highlighting`_. - Optional -- `Python Imaging Library`_ (PIL) is required if on an image or figure directive, you specify ``scale`` but not ``width`` and ``height``. See section `Images and figures`_. 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= Specify a stylesheet URL, used verbatim. Overrides --stylesheet-path. --stylesheet-path= 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=`` 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. 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. 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 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 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. 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. 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-path`` option in order to include your custom style definitions. For example:: rst2odt.py --odf-config-file=mymappingfile.ini --stylesheet-path=mystyles.odt mydoc.txt mydoc.odt Hints and Suggestions and Features ================================== 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 ------------------- **Note:** Syntax highlighting uses the Docutils class ``docutils.parsers.rst.Directive``. Therefore, it requires a very recent version of Docutils, specifically version 0.5 or later. ``odtwriter`` can add Python 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 -g --add-syntax-highlight test.txt test.odt and ... 3. In your reST (.txt) file, include code to which syntax highlighting is to be applied inside a ``sourcecode`` directive, for example:: .. sourcecode:: lexer-language def test(): print 'hi' return 'something' where ``lexer-language`` is the programming language, for example "python", "java", etc. See the Pygments documentation for a list of lexers/languages supported by Pygments: `Available lexers -- http://pygments.org/docs/lexers/ `_ 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 `_, 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 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. 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`_. 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`_. 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 Determining which 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 anywhere 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 global 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. 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. Footnote references inside footnotes ------------------------------------ Not supported. Get a grip. Be serious. Try a dose of reality. ``odtwriter`` ignores them. They cause ``oowriter`` to croak. Credits ======= Stefan Merten designed and implemented the custom style names capability. Thank you, Stefan. .. _`Pygments`: http://pygments.pocoo.org/ .. _`Docutils`: http://docutils.sourceforge.net/ .. _`Python Imaging Library`: http://www.pythonware.com/products/pil/ .. Configuration for Emacs .. Local Variables: mode: rst indent-tabs-mode: nil sentence-end-double-space: t fill-column: 68 End: