| Author: | Dave Kuhlman |
|---|---|
| Address: | dkuhlman@rexx.com http://www.rexx.com/~dkuhlman |
| Revision: | 1.3d |
| Date: | November 28, 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. |
Contents
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.3 in my testing.
You can learn more about Docutils and reST here: Docutils
The source distribution of ODF/ODT writer for Docutils is here: http://www.rexx.com/~dkuhlman/odtwriter-1.3d.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.
odtwriter requires:
Python
A sufficiently recent version of Docutils.
One of the following:
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.
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.
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
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.6/site- packages/docutils/writers/odtwriter/styles.odt" | |
| --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-add-syntax-highlighting | |
| Do not add syntax highlighting in literal code blocks. (default) | |
| --create-sections | |
| Create sections for headers. (default) | |
| --no-create-sections | |
| Do not create sections for headers. | |
| --create-links | Create links. |
| --no-create-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) | |
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.
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
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 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".
The line block styles wrap the various nested levels of line blocks. There is one line block style for each indent level.
Notes:
You can create your own custom stylesheet. Here is how:
Here are a few reasons and ideas:
[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.
Here are a few reasons and ideas:
In order to define custom style names and to generate documents that contain them, do the following:
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.
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
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).
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
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
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 syntax highlighting to code in code blocks. In order to activate this, do all of the following:
Install Pygments and ...
Use the command line flag --add-syntax-highlighting. Example:
$ rst2odt.py -g --add-syntax-highlight test.txt test.odt
and ...
In your reST (.txt) file, include code to which syntax highlighting is to be applied inside a sourcecode directive, for example:
.. sourcecode:: language
def test():
print 'hi'
return 'something'
where language is the programming language, for example "python", "java", etc. See the Pygments documentation for a list of languages supported by Pygments.
The following styles are defined in styles.odt and are used for literal code blocks and syntax highlighting:
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.
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:: language
where:
Examples:
.. sourcecode:: on .. sourcecode:: python .. sourcecode:: off .. sourcecode:: java .. sourcecode:: on
A few additional notes and hints:
There is limited support for the container directive. The limitations are the following:
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 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 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 flags.
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:
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 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>
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.
Not supported.
Get a grip. Be serious. Try a dose of reality.
odtwriter ignores them.
They cause oowriter to croak.
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:
The program paperconf must be available on your system. odtwriter uses paperconf -s to obtain the paper size. See man paperconf for more information.
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.
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.