| Server IP : 127.0.0.2 / Your IP : 18.217.108.153 Web Server : Apache/2.4.18 (Ubuntu) System : User : www-data ( ) PHP Version : 7.0.33-0ubuntu0.16.04.16 Disable Function : disk_free_space,disk_total_space,diskfreespace,dl,exec,fpaththru,getmyuid,getmypid,highlight_file,ignore_user_abord,leak,listen,link,opcache_get_configuration,opcache_get_status,passthru,pcntl_alarm,pcntl_fork,pcntl_waitpid,pcntl_wait,pcntl_wifexited,pcntl_wifstopped,pcntl_wifsignaled,pcntl_wexitstatus,pcntl_wtermsig,pcntl_wstopsig,pcntl_signal,pcntl_signal_dispatch,pcntl_get_last_error,pcntl_strerror,pcntl_sigprocmask,pcntl_sigwaitinfo,pcntl_sigtimedwait,pcntl_exec,pcntl_getpriority,pcntl_setpriority,php_uname,phpinfo,posix_ctermid,posix_getcwd,posix_getegid,posix_geteuid,posix_getgid,posix_getgrgid,posix_getgrnam,posix_getgroups,posix_getlogin,posix_getpgid,posix_getpgrp,posix_getpid,posix,_getppid,posix_getpwnam,posix_getpwuid,posix_getrlimit,posix_getsid,posix_getuid,posix_isatty,posix_kill,posix_mkfifo,posix_setegid,posix_seteuid,posix_setgid,posix_setpgid,posix_setsid,posix_setuid,posix_times,posix_ttyname,posix_uname,pclose,popen,proc_open,proc_close,proc_get_status,proc_nice,proc_terminate,shell_exec,source,show_source,system,virtual MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : ON | Sudo : ON | Pkexec : ON Directory : /usr/share/doc/docutils-doc/docs/user/ |
Upload File : |
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>Odt Writer for Docutils</title>
<meta name="author" content="Dave Kuhlman" />
<meta name="date" content="2012-10-13" />
<meta name="copyright" content="This document has been placed in the public domain." />
<link rel="stylesheet" href="../../css/html4css1.css" type="text/css" />
</head>
<body>
<div class="document" id="odt-writer-for-docutils">
<h1 class="title">Odt Writer for Docutils</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Dave Kuhlman</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:docutils-develop@lists.sourceforge.net">docutils-develop@lists.sourceforge.net</a></td></tr>
<tr><th class="docinfo-name">Revision:</th>
<td>7528</td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2012-10-13</td></tr>
<tr><th class="docinfo-name">Copyright:</th>
<td>This document has been placed in the public domain.</td></tr>
</tbody>
</table>
<div class="abstract topic">
<p class="topic-title first">Abstract</p>
<p>This document describes the Docutils odtwriter
(rst2odt.py).</p>
</div>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#introduction" id="id1">1 Introduction</a></li>
<li><a class="reference internal" href="#requirements" id="id2">2 Requirements</a></li>
<li><a class="reference internal" href="#how-to-use-it" id="id3">3 How to Use It</a><ul class="auto-toc">
<li><a class="reference internal" href="#configuration-file" id="id4">3.1 Configuration file</a></li>
<li><a class="reference internal" href="#command-line-options" id="id5">3.2 Command line options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#styles-and-classes" id="id6">4 Styles and Classes</a><ul class="auto-toc">
<li><a class="reference internal" href="#styles-used-by-odtwriter" id="id7">4.1 Styles used by odtwriter</a><ul class="auto-toc">
<li><a class="reference internal" href="#paragraph-styles" id="id8">4.1.1 Paragraph styles</a></li>
<li><a class="reference internal" href="#character-styles" id="id9">4.1.2 Character styles</a></li>
<li><a class="reference internal" href="#list-styles" id="id10">4.1.3 List styles</a></li>
<li><a class="reference internal" href="#admonition-styles" id="id11">4.1.4 Admonition styles</a></li>
<li><a class="reference internal" href="#rubric-style" id="id12">4.1.5 Rubric style</a></li>
<li><a class="reference internal" href="#table-styles" id="id13">4.1.6 Table styles</a></li>
<li><a class="reference internal" href="#line-block-styles" id="id14">4.1.7 Line block styles</a></li>
<li><a class="reference internal" href="#footnote-and-citation-styles" id="id15">4.1.8 Footnote and citation styles</a></li>
<li><a class="reference internal" href="#heading-and-title-styles" id="id16">4.1.9 Heading and title styles</a></li>
<li><a class="reference internal" href="#image-and-figure-styles" id="id17">4.1.10 Image and figure styles</a></li>
</ul>
</li>
<li><a class="reference internal" href="#defining-and-using-a-custom-stylesheet" id="id18">4.2 Defining and using a custom stylesheet</a><ul class="auto-toc">
<li><a class="reference internal" href="#why-custom-stylesheets" id="id19">4.2.1 Why custom stylesheets</a></li>
</ul>
</li>
<li><a class="reference internal" href="#defining-and-using-custom-style-names" id="id20">4.3 Defining and using custom style names</a><ul class="auto-toc">
<li><a class="reference internal" href="#why-custom-style-names" id="id21">4.3.1 Why custom style names</a></li>
<li><a class="reference internal" href="#how-to-use-custom-style-names" id="id22">4.3.2 How to use custom style names</a></li>
</ul>
</li>
<li><a class="reference internal" href="#classes" id="id23">4.4 Classes</a></li>
<li><a class="reference internal" href="#roles" id="id24">4.5 Roles</a></li>
</ul>
</li>
<li><a class="reference internal" href="#hints-and-suggestions-and-features" id="id25">5 Hints and Suggestions and Features</a><ul class="auto-toc">
<li><a class="reference internal" href="#table-of-contents" id="id26">5.1 Table of contents</a></li>
<li><a class="reference internal" href="#syntax-highlighting" id="id27">5.2 Syntax highlighting</a></li>
<li><a class="reference internal" href="#the-container-directive" id="id28">5.3 The container directive</a></li>
<li><a class="reference internal" href="#the-table-directive" id="id29">5.4 The table directive</a></li>
<li><a class="reference internal" href="#footnotes-and-citations" id="id30">5.5 Footnotes and citations</a></li>
<li><a class="reference internal" href="#images-and-figures" id="id31">5.6 Images and figures</a></li>
<li><a class="reference internal" href="#the-raw-directive" id="id32">5.7 The raw directive</a></li>
<li><a class="reference internal" href="#the-meta-directive" id="id33">5.8 The meta directive</a></li>
<li><a class="reference internal" href="#footnote-references-inside-footnotes" id="id34">5.9 Footnote references inside footnotes</a></li>
<li><a class="reference internal" href="#page-size" id="id35">5.10 Page size</a></li>
<li><a class="reference internal" href="#custom-header-footers-inserting-page-numbers-date-time-etc" id="id36">5.11 Custom header/footers: inserting page numbers, date, time, etc</a><ul class="auto-toc">
<li><a class="reference internal" href="#field-specifiers" id="id37">5.11.1 Field specifiers</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#credits" id="id38">6 Credits</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id1">1 Introduction</a></h1>
<p>What it does -- <tt class="docutils literal">rst2odt.py</tt> translates reST
(reStructuredText) into a Open Document Format <tt class="docutils literal">.odt</tt> file. You
can learn more about the ODF format here:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office">OASIS Open Document Format for Office Applications
(OpenDocument) TC</a></li>
<li><a class="reference external" href="http://en.wikipedia.org/wiki/OpenDocument">Open Document at Wikipedia</a></li>
</ul>
<p>You should be able to open documents (.odt files) generated with
<tt class="docutils literal">rst2odt.py</tt> in <tt class="docutils literal">OpenOffice/oowriter</tt>.</p>
<p>You can learn more about Docutils and reST here: <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a></p>
</div>
<div class="section" id="requirements">
<h1><a class="toc-backref" href="#id2">2 Requirements</a></h1>
<p>In addition to the Docutils standard requirements, <tt class="docutils literal">odtwriter</tt>
requires:</p>
<ul class="simple">
<li>ElementTree -- Python (version 2.5 or later) now includes
ElementTree (<tt class="docutils literal">xml.etree.ElementTree</tt>).</li>
<li>Optional -- <a class="reference external" href="http://pygments.pocoo.org/">Pygments</a> is required if you want syntax
highlighting of code in literal blocks. See section <a class="reference internal" href="#syntax-highlighting">Syntax
highlighting</a>.</li>
<li>Optional -- <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging Library</a> (PIL) is required if on an
image or figure directive, you specify <tt class="docutils literal">scale</tt> but not <tt class="docutils literal">width</tt>
and <tt class="docutils literal">height</tt>. See section <a class="reference internal" href="#images-and-figures">Images and figures</a>.</li>
</ul>
</div>
<div class="section" id="how-to-use-it">
<h1><a class="toc-backref" href="#id3">3 How to Use It</a></h1>
<p>Run it from the command line as follows:</p>
<pre class="literal-block">
$ rst2odt.py myinput.txt myoutput.odt
</pre>
<p>To see usage information and to learn about command line options
that you can use, run the following:</p>
<pre class="literal-block">
$ rst2odt.py --help
</pre>
<p>Examples:</p>
<pre class="literal-block">
$ 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
</pre>
<div class="section" id="configuration-file">
<h2><a class="toc-backref" href="#id4">3.1 Configuration file</a></h2>
<p>The options described below can also be set in a configuration file.
Use section <tt class="docutils literal">[odf_odt writer]</tt> to set options specific to the
<tt class="docutils literal">odtwriter</tt>. For example:</p>
<pre class="literal-block">
[odf_odt writer]
stylesheet: styles1.odt
</pre>
<p>See the "Docutils Configuration" document for more information on
Docutils configuration files, including locations which are
searched.</p>
</div>
<div class="section" id="command-line-options">
<h2><a class="toc-backref" href="#id5">3.2 Command line options</a></h2>
<p>The following command line options are specific to <tt class="docutils literal">odtwriter</tt>:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--stylesheet=<var><URL></var></span></kbd></td>
</tr>
<tr><td> </td><td>Specify a stylesheet URL, used verbatim.
Default: writers/odf_odt/styles.odt in the
installation directory.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--odf-config-file=<var><file></var></span></kbd></td>
</tr>
<tr><td> </td><td>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.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--cloak-email-addresses</span></kbd></td>
</tr>
<tr><td> </td><td>Obfuscate email addresses to confuse harvesters while
still keeping email links usable with standards-
compliant browsers.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--no-cloak-email-addresses</span></kbd></td>
</tr>
<tr><td> </td><td>Do not obfuscate email addresses.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--table-border-thickness=<var>TABLE_BORDER_THICKNESS</var></span></kbd></td>
</tr>
<tr><td> </td><td>Specify the thickness of table borders in thousands of
a cm. Default is 35.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--add-syntax-highlighting</span></kbd></td>
</tr>
<tr><td> </td><td>Add syntax highlighting in literal code blocks.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--no-syntax-highlighting</span></kbd></td>
</tr>
<tr><td> </td><td>Do not add syntax highlighting in literal code blocks.
(default)</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--create-sections</span></kbd></td>
</tr>
<tr><td> </td><td>Create sections for headers. (default)</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--no-sections</span></kbd></td>
<td>Do not create sections for headers.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--create-links</span></kbd></td>
<td>Create links.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--no-links</span></kbd></td>
<td>Do not create links. (default)</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--endnotes-end-doc</span></kbd></td>
</tr>
<tr><td> </td><td>Generate endnotes at end of document, not footnotes at
bottom of page.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--no-endnotes-end-doc</span></kbd></td>
</tr>
<tr><td> </td><td>Generate footnotes at bottom of page, not endnotes at
end of document. (default)</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--generate-list-toc</span></kbd></td>
</tr>
<tr><td> </td><td>Generate a bullet list table of contents, not an
ODF/<tt class="docutils literal">oowriter</tt> table of contents.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--generate-oowriter-toc</span></kbd></td>
</tr>
<tr><td> </td><td>Generate an ODF/<tt class="docutils literal">oowriter</tt> table of contents,
not a bullet list. (default) <strong>Note:</strong>
<tt class="docutils literal">odtwriter</tt> is not able to determine page
numbers, so you will need to open the
generated document in <tt class="docutils literal">oowriter</tt>, then
right-click on the table of contents and
select "Update" to insert page numbers.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--custom-odt-header=<var>CUSTOM_HEADER</var></span></kbd></td>
</tr>
<tr><td> </td><td>Specify the contents of an custom header line. See
odf_odt writer documentation for details about special
field character sequences. See section
<a class="reference internal" href="#custom-header-footers-inserting-page-numbers-date-time-etc">Custom header/footers: inserting page numbers, date, time, etc</a>
for details</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--custom-odt-footer=<var>CUSTOM_FOOTER</var></span></kbd></td>
</tr>
<tr><td> </td><td>Specify the contents of an custom footer line. See
odf_odt writer documentation for details about special
field character sequences. See section
<a class="reference internal" href="#custom-header-footers-inserting-page-numbers-date-time-etc">Custom header/footers: inserting page numbers, date, time, etc</a>
for details</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="styles-and-classes">
<h1><a class="toc-backref" href="#id6">4 Styles and Classes</a></h1>
<p><tt class="docutils literal">odtwriter</tt> uses a number of styles that are defined in
<tt class="docutils literal">styles.xml</tt> in the default <tt class="docutils literal">styles.odt</tt>. This section
describes those styles.</p>
<p>Note that with the <tt class="docutils literal"><span class="pre">--stylesheet</span></tt> command line option, you can
use either <tt class="docutils literal">styles.odt</tt> or <tt class="docutils literal">styles.xml</tt>, as described below.
Use of <tt class="docutils literal">styles.odt</tt> is recommended over <tt class="docutils literal">styles.xml</tt>.</p>
<p>You can modify the look of documents generated by <tt class="docutils literal">odtwriter</tt> in
several ways:</p>
<ul>
<li><p class="first">Open (a copy of) <tt class="docutils literal">styles.odt</tt> in <tt class="docutils literal">OpenOffice/oowriter</tt> and
modify the style you wish to change. Now, save this document,
then generate your documents using this modified copy of
<tt class="docutils literal">styles.odt</tt>.</p>
<p>In my version of <tt class="docutils literal">oowriter</tt>, 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.</p>
</li>
<li><p class="first">Open a document generated by <tt class="docutils literal">odtwriter</tt> in <span class="incremental">oowriter`</span>. 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.</p>
</li>
<li><p class="first">Extract <tt class="docutils literal">styles.xml</tt> from <tt class="docutils literal">styles.odt</tt> using your favorite
<tt class="docutils literal">zip/unzip</tt> tool. Then modify <tt class="docutils literal">styles.xml</tt> with a text
editor. Now re-zip it back into your own <tt class="docutils literal">styles.odt</tt>, or use
it directly by specifying it with the <tt class="docutils literal"><span class="pre">--stylesheet</span></tt> command
line option. <strong>Hint:</strong> If you intend to extract <tt class="docutils literal">styles.xml</tt>
from an <tt class="docutils literal">.odt</tt> file (and then "re-zip" it), you should turn off
XML optimization/compression in <tt class="docutils literal">oowriter</tt>. In order to this
in <tt class="docutils literal">oowriter</tt>, use Tools --> Options... --> Load-Save -->
General and turn off "Size optimization for XML format".</p>
</li>
<li><p class="first">Open an empty (or new) document in <tt class="docutils literal">oowriter</tt>. Define all of
the styles described in this section. Then, use that document (a
.odt file) as your stylesheet. <tt class="docutils literal">odtwriter</tt> will extract the
<tt class="docutils literal">styles.xml</tt> file from that document and insert it into the
output document.</p>
</li>
<li><p class="first">Some combination of the above.</p>
</li>
</ul>
<div class="section" id="styles-used-by-odtwriter">
<h2><a class="toc-backref" href="#id7">4.1 Styles used by odtwriter</a></h2>
<p>This section describes the styles used by <tt class="docutils literal">odtwriter</tt>.</p>
<p>Note that we do not describe the "look" of these styles. That can
be easily changed by using <tt class="docutils literal">oowriter</tt> to edit the document
<tt class="docutils literal">styles.odt</tt> (or a copy of it), and modifying any of the styles
described here.</p>
<p>To change the definition and appearance of these styles, open
<tt class="docutils literal">styles.odt</tt> in <tt class="docutils literal">oowriter</tt> and open the Styles and Formatting
window by using the following menu item:</p>
<pre class="literal-block">
Format --> Styles and Formatting
</pre>
<p>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 <tt class="docutils literal">odtwriter</tt>.</p>
<p>Notice that you can make a copy of file <tt class="docutils literal">styles.odt</tt>, modify it
using <tt class="docutils literal">oowriter</tt>, and then use your copy with the
<tt class="docutils literal"><span class="pre">--stylesheet=<file></span></tt> command line option. Example:</p>
<pre class="literal-block">
$ rst2odt.py --stylesheet=mystyles.odt test2.txt test2.odt
</pre>
<div class="section" id="paragraph-styles">
<h3><a class="toc-backref" href="#id8">4.1.1 Paragraph styles</a></h3>
<dl class="docutils">
<dt>rststyle-attribution</dt>
<dd>The style for attributions, for example, the attribution in a
<tt class="docutils literal">.. epigraph::</tt> directive. Derived from
<tt class="docutils literal"><span class="pre">rststyle-blockquote</span></tt>.</dd>
<dt>rststyle-blockindent</dt>
<dd>An indented block.</dd>
<dt>rststyle-blockquote</dt>
<dd>A block quote.</dd>
<dt>rststyle-blockquote-bulletitem</dt>
<dd>The style for bullet list items inside block quote.</dd>
<dt>rststyle-blockquote-enumitem</dt>
<dd>The style for enumerated list items inside block quote.</dd>
<dt>rststyle-bodyindent</dt>
<dd>An indented block.</dd>
<dt>rststyle-bulletitem</dt>
<dd>An item in an bullet list.</dd>
<dt>rststyle-caption</dt>
<dd>The caption in a figure or image. Also see
<tt class="docutils literal"><span class="pre">rststyle-legend</span></tt>.</dd>
<dt>rststyle-codeblock</dt>
<dd>Literal code blocks -- A block of example code. Created with
double colon ("::") followed by an indented block or with the
<tt class="docutils literal">.. <span class="pre">parsed-literal::</span></tt> directive. Derived from the
<tt class="docutils literal">Preformatted Text</tt> style in <tt class="docutils literal">oowriter</tt>.</dd>
<dt>rststyle-enumitem</dt>
<dd>An item in an enumerated list.</dd>
<dt>rststyle-epigraph</dt>
<dd>The style for epigraphs, for example, the body of an
<tt class="docutils literal">.. epigraph::</tt> directive. Derived from
<tt class="docutils literal"><span class="pre">rststyle-blockquote</span></tt>.</dd>
<dt>rststyle-epigraph-bulletitem</dt>
<dd>The style for bullet list items inside epigraphs.</dd>
<dt>rststyle-epigraph-enumitem</dt>
<dd>The style for enumerated list items inside epigraphs.</dd>
<dt>rststyle-footer</dt>
<dd>The style for footers. The footer content originates from the
<tt class="docutils literal">..footer::</tt> directive and in response to the command line
flags for generator (<tt class="docutils literal"><span class="pre">--generator</span></tt>), date/time generated
(<tt class="docutils literal"><span class="pre">--date</span></tt> and <tt class="docutils literal"><span class="pre">--time</span></tt>), and view source link
(<tt class="docutils literal"><span class="pre">--source-link</span></tt> and <tt class="docutils literal"><span class="pre">--source-url=URL</span></tt>).</dd>
<dt>rststyle-header</dt>
<dd>The style for headers. The header content originates from the
<tt class="docutils literal">..header::</tt> directive.</dd>
<dt>rststyle-highlights</dt>
<dd>The style for highlightss, for example, the body of an
<tt class="docutils literal">.. highlights::</tt> directive. Derived from
<tt class="docutils literal"><span class="pre">rststyle-blockquote</span></tt>.</dd>
<dt>rststyle-highlights-bulletitem</dt>
<dd>The style for bullet list items inside highlights.</dd>
<dt>rststyle-highlights-enumitem</dt>
<dd>The style for enumerated list items inside highlights.</dd>
<dt>rststyle-horizontalline</dt>
<dd>A horizontal line, e.g. used for transitions.</dd>
<dt>rststyle-legend</dt>
<dd>The legend in a figure. See the Docutils figure directive. Also
see <tt class="docutils literal"><span class="pre">rststyle-caption</span></tt>.</dd>
<dt>rststyle-table-title</dt>
<dd>The style for titles of tables. See section <a class="reference internal" href="#the-table-directive">The table
directive</a>.</dd>
<dt>rststyle-textbody</dt>
<dd>Normal text. The style for paragraphs. Derived from the <tt class="docutils literal">Text
body</tt> style in <tt class="docutils literal">oowriter</tt>.</dd>
</dl>
</div>
<div class="section" id="character-styles">
<h3><a class="toc-backref" href="#id9">4.1.2 Character styles</a></h3>
<dl class="docutils">
<dt>rststyle-emphasis</dt>
<dd>Emphasis. Normally rendered as italics.</dd>
<dt>rststyle-inlineliteral</dt>
<dd>An inline literal.</dd>
<dt>rststyle-strong</dt>
<dd>Strong emphasis. Normally rendered as boldface.</dd>
<dt>rststyle-quotation</dt>
<dd>In-line quoted material.</dd>
<dt>rststyle-codeblock-classname</dt>
<dd>Syntax highlighting in literal code blocks -- class names.</dd>
<dt>rststyle-codeblock-comment</dt>
<dd>Syntax highlighting in literal code blocks -- comments.</dd>
<dt>rststyle-codeblock-functionname</dt>
<dd>Syntax highlighting in literal code blocks -- function names.</dd>
<dt>rststyle-codeblock-keyword</dt>
<dd>Syntax highlighting in literal code blocks -- Python language
keywords.</dd>
<dt>rststyle-codeblock-name</dt>
<dd>Syntax highlighting in literal code blocks -- other names, for
example, variables.</dd>
<dt>rststyle-codeblock-number</dt>
<dd>Syntax highlighting in literal code blocks -- literal numbers,
including integers, floats, hex numbers, and octal numbers.</dd>
<dt>rststyle-codeblock-operator</dt>
<dd>Syntax highlighting in literal code blocks -- Python operators.</dd>
<dt>rststyle-codeblock-string</dt>
<dd>Syntax highlighting in literal code blocks -- literal strings.</dd>
</dl>
</div>
<div class="section" id="list-styles">
<h3><a class="toc-backref" href="#id10">4.1.3 List styles</a></h3>
<dl class="docutils">
<dt>rststyle-bulletlist</dt>
<dd>Bullet lists (but not in the table of contents)</dd>
<dt>rststyle-blockquote-bulletlist</dt>
<dd>Bullet lists in block quotes.</dd>
<dt>rststyle-blockquote-enumlist</dt>
<dd>Enumerated lists in block quotes.</dd>
<dt>rststyle-enumlist-arabic</dt>
<dd>Enumerated lists, arabic (but not in the table of contents)</dd>
<dt>rststyle-enumlist-loweralpha</dt>
<dd>Enumerated lists, lower alpha (but not in the table of contents)</dd>
<dt>rststyle-enumlist-lowerroman</dt>
<dd>Enumerated lists, lower roman (but not in the table of contents)</dd>
<dt>rststyle-enumlist-upperalpha</dt>
<dd>Enumerated lists, upper alpha (but not in the table of contents)</dd>
<dt>rststyle-enumlist-upperroman</dt>
<dd>Enumerated lists, upper roman (but not in the table of contents)</dd>
<dt>rststyle-epigraph-bulletlist</dt>
<dd>Bullet lists in epigraphs. See the <tt class="docutils literal">.. epigraph::</tt>
directive.</dd>
<dt>rststyle-epigraph-enumlist</dt>
<dd>Enumerated lists in epigraphs. See the <tt class="docutils literal">.. epigraph::</tt>
directive.</dd>
<dt>rststyle-highlights-bulletlist</dt>
<dd>Bullet lists in highlights blocks. See the <tt class="docutils literal">.. highlights::</tt>
directive.</dd>
<dt>rststyle-highlights-enumlist</dt>
<dd>Enumerated lists in highlights blocks. See the <tt class="docutils literal">.. highlights::</tt>
directive.</dd>
<dt>rststyle-tocbulletlist</dt>
<dd>Lists in the table of contents when section numbering is off.</dd>
<dt>rststyle-tocenumlist</dt>
<dd>Lists in the table of contents when section numbering is on.</dd>
</dl>
</div>
<div class="section" id="admonition-styles">
<h3><a class="toc-backref" href="#id11">4.1.4 Admonition styles</a></h3>
<dl class="docutils">
<dt>rststyle-admon-attention-hdr</dt>
<dd>The style for the attention admonition header/title.</dd>
<dt>rststyle-admon-attention-body</dt>
<dd>The style for the attention admonition body/paragraph.</dd>
<dt>rststyle-admon-caution-hdr</dt>
<dd>The style for the caution admonition header/title.</dd>
<dt>rststyle-admon-caution-body</dt>
<dd>The style for the caution admonition body/paragraph.</dd>
<dt>rststyle-admon-danger-hdr</dt>
<dd>The style for the admonition header/title.</dd>
<dt>rststyle-admon-danger-body</dt>
<dd>The style for the danger admonition body/paragraph.</dd>
<dt>rststyle-admon-error-hdr</dt>
<dd>The style for the error admonition header/title.</dd>
<dt>rststyle-admon-error-body</dt>
<dd>The style for the error admonition body/paragraph.</dd>
<dt>rststyle-admon-hint-hdr</dt>
<dd>The style for the hint admonition header/title.</dd>
<dt>rststyle-admon-hint-body</dt>
<dd>The style for the hint admonition body/paragraph.</dd>
<dt>rststyle-admon-hint-hdr</dt>
<dd>The style for the hint admonition header/title.</dd>
<dt>rststyle-admon-hint-body</dt>
<dd>The style for the hint admonition body/paragraph.</dd>
<dt>rststyle-admon-important-hdr</dt>
<dd>The style for the important admonition header/title.</dd>
<dt>rststyle-admon-important-body</dt>
<dd>The style for the important admonition body/paragraph.</dd>
<dt>rststyle-admon-note-hdr</dt>
<dd>The style for the note admonition header/title.</dd>
<dt>rststyle-admon-note-hdr</dt>
<dd>The style for the note admonition header/title.</dd>
<dt>rststyle-admon-tip-body</dt>
<dd>The style for the tip admonition body/paragraph.</dd>
<dt>rststyle-admon-tip-hdr</dt>
<dd>The style for the tip admonition header/title.</dd>
<dt>rststyle-admon-warning-body</dt>
<dd>The style for the warning admonition body/paragraph.</dd>
<dt>rststyle-admon-warning-hdr</dt>
<dd>The style for the warning admonition header/title.</dd>
<dt>rststyle-admon-generic-body</dt>
<dd>The style for the generic admonition body/paragraph.</dd>
<dt>rststyle-admon-generic-hdr</dt>
<dd>The style for the generic admonition header/title.</dd>
</dl>
</div>
<div class="section" id="rubric-style">
<h3><a class="toc-backref" href="#id12">4.1.5 Rubric style</a></h3>
<dl class="docutils">
<dt>rststyle-rubric</dt>
<dd>The style for the text in a rubric directive.</dd>
</dl>
<p>The rubric directive recognizes a "class" option. If entered,
odtwriter uses the value of that option instead of the
<tt class="docutils literal"><span class="pre">rststyle-rubric</span></tt> style. Here is an example which which attaches
the <tt class="docutils literal"><span class="pre">rststyle-heading1</span></tt> style to the generated rubric:</p>
<pre class="literal-block">
.. rubric:: This is my first rubric
:class: rststyle-heading1
</pre>
</div>
<div class="section" id="table-styles">
<h3><a class="toc-backref" href="#id13">4.1.6 Table styles</a></h3>
<p>A table style is generated by <tt class="docutils literal">oowriter</tt> for each table that you
create. Therefore, <tt class="docutils literal">odtwriter</tt> attempts to do something similar.
These styles are created in the <tt class="docutils literal">content.xml</tt> document in the
generated <tt class="docutils literal">.odt</tt> file. These styles have names prefixed with
"rststyle-table-".</p>
<p>There are two ways in which you can control the styles of your
tables: one simple, the other a bit more complex, but more
powerful.</p>
<p>First, you can change the thickness of the borders of all tables
generated in a document using the "--table-border-thickness"
command line option.</p>
<p>Second, you can control additional table properties and you can
apply different styles to different tables within the same document
by customizing and using tables in your stylesheet: <tt class="docutils literal">styles.odt</tt>
or whatever you name your copy of it using the --stylesheet command
line option. Then, follow these rules to apply a table style to
the tables in your document:</p>
<ul>
<li><p class="first">The default table style -- Optionally, alter and customize the
style applied by default to tables in your document by modifying
table "rststyle-table-0" in your stylesheet (<tt class="docutils literal">styles.odt</tt> or a
copy). Caution: Do not change the name of this table.</p>
</li>
<li><p class="first">User-created table styles -- Add one or more new table styles to
be applied selectively to tables in your document by doing the
following:</p>
<ol class="arabic">
<li><p class="first">Using <tt class="docutils literal">oowriter</tt>, add a table to your stylesheet and give it
a name that starts with the prefix "rststyle-table-", for
example "rststyle-table-vegetabledata". Customize the table's
border thickness, border color, and table background color.</p>
</li>
<li><p class="first">In your reStructuredText document, apply your new table style
to a specific table by placing the ".. class::" directive
immediately before the table, for example:</p>
<pre class="literal-block">
.. class:: rststyle-table-vegetabledata
</pre>
</li>
</ol>
</li>
</ul>
<p>The default table style will be applied to all tables for which you
do not specify a style with the ".. class::" directive.</p>
<p>Customize the table properties in <tt class="docutils literal">oowriter</tt> using the table
properties dialog for the table (style) that you wish to customize.</p>
<p>Note that "--table-border-thickness" command line option overrides
the border thickness specified in the stylesheet.</p>
<p>The specific properties that you can control with this second
method are the following:</p>
<ul class="simple">
<li>Border thickness and border color.</li>
<li>Background color -- When you change the background color of a
table to be used as a style (in <tt class="docutils literal">styles.odt</tt> or whatever you
name it), make sure you change the background color for the
<em>table</em> and <em>not</em> for a cell in the table. <tt class="docutils literal">odtwriter</tt> picks
the background color from the table, not from a cell within the
table.</li>
</ul>
</div>
<div class="section" id="line-block-styles">
<h3><a class="toc-backref" href="#id14">4.1.7 Line block styles</a></h3>
<p>The line block styles wrap the various nested levels of line
blocks. There is one line block style for each indent level.</p>
<dl class="docutils">
<dt>rststyle-lineblock1</dt>
<dd>Line block style for line block with no indent.</dd>
<dt>rststyle-lineblock2</dt>
<dd>Line block style for line block indented 1 level.</dd>
<dt>rststyle-lineblock3</dt>
<dd>Line block style for line block indented 2 levels.</dd>
<dt>rststyle-lineblock4</dt>
<dd>Line block style for line block indented 3 levels.</dd>
<dt>rststyle-lineblock5</dt>
<dd>Line block style for line block indented 4 levels.</dd>
<dt>rststyle-lineblock6</dt>
<dd>Line block style for line block indented 5 levels.</dd>
</dl>
<p>Notes:</p>
<ul class="simple">
<li><tt class="docutils literal">odtwriter</tt> 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 <tt class="docutils literal"><span class="pre">rststyle-lineblock7</span></tt>,
<tt class="docutils literal"><span class="pre">rststyle-lineblock8</span></tt>, ...</li>
<li>Since the line block style is used to create indentation, a line
block that is inside a block quote will use
<tt class="docutils literal"><span class="pre">rststyle-lineblock2</span></tt> as its first level of indentation.</li>
</ul>
</div>
<div class="section" id="footnote-and-citation-styles">
<h3><a class="toc-backref" href="#id15">4.1.8 Footnote and citation styles</a></h3>
<dl class="docutils">
<dt>rststyle-footnote</dt>
<dd>The style for footnotes. This style affects the footnote
content, <em>not</em> the footnote reference in the body of the document.</dd>
<dt>rststyle-citation</dt>
<dd>The style for citations. This style affects the citation
content, <em>not</em> 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.</dd>
</dl>
</div>
<div class="section" id="heading-and-title-styles">
<h3><a class="toc-backref" href="#id16">4.1.9 Heading and title styles</a></h3>
<dl class="docutils">
<dt>rststyle-heading{1|2|3|4|5}</dt>
<dd>The styles for headings (section titles and sub-titles). Five
levels of sub-headings are provided: rststyle-heading1 through
rststyle-heading5.</dd>
<dt>rststyle-title</dt>
<dd>The style for the document title.</dd>
<dt>rststyle-subtitle</dt>
<dd>The style for the document sub-title.</dd>
</dl>
</div>
<div class="section" id="image-and-figure-styles">
<h3><a class="toc-backref" href="#id17">4.1.10 Image and figure styles</a></h3>
<dl class="docutils">
<dt>rststyle-image</dt>
<dd>The style applied to an image, either an image by itself or an
image in a figure.</dd>
<dt>rststyle-figureframe</dt>
<dd>The style applied to a figure (actually to the frame that
surrounds a figure).</dd>
</dl>
</div>
</div>
<div class="section" id="defining-and-using-a-custom-stylesheet">
<h2><a class="toc-backref" href="#id18">4.2 Defining and using a custom stylesheet</a></h2>
<p>You can create your own custom stylesheet. Here is how:</p>
<ol class="arabic simple">
<li>Make a copy of <tt class="docutils literal">styles.odt</tt>, which is in the distribution.</li>
<li>Open your copy of <tt class="docutils literal">styles.odt</tt> in <tt class="docutils literal">oowriter</tt>. Modify styles
in that document. Then, save it.</li>
<li>When you run <tt class="docutils literal">rst2odt.py</tt>, use the <tt class="docutils literal"><span class="pre">--stylesheet</span></tt> command
line option to use your custom stylesheet. Run <tt class="docutils literal">rst2odt.py
<span class="pre">--help</span></tt> to learn more about these options.</li>
</ol>
<div class="section" id="why-custom-stylesheets">
<h3><a class="toc-backref" href="#id19">4.2.1 Why custom stylesheets</a></h3>
<p>Here are a few reasons and ideas:</p>
<ul class="simple">
<li>The page size is stored in the style sheet. The default page
size is <tt class="docutils literal">Letter</tt>. You can change the page size (for example,
to <tt class="docutils literal">A4</tt>) in your custom stylesheet by opening it in
<tt class="docutils literal">oowriter</tt>, then clicking on menu: <tt class="docutils literal"><span class="pre">Format/Page...</span></tt>, then
clicking on the <tt class="docutils literal">Page</tt> tab.</li>
</ul>
</div>
</div>
<div class="section" id="defining-and-using-custom-style-names">
<h2><a class="toc-backref" href="#id20">4.3 Defining and using custom style names</a></h2>
<p>[Credits: Stefan Merten designed and implemented the custom style names
capability. Thank you, Stefan.]</p>
<p>You can also instruct <tt class="docutils literal">odtwriter</tt> to use style names of your own
choice.</p>
<div class="section" id="why-custom-style-names">
<h3><a class="toc-backref" href="#id21">4.3.1 Why custom style names</a></h3>
<p>Here are a few reasons and ideas:</p>
<ul class="simple">
<li>Suppose that your organization has a standard set of styles in
OOo <tt class="docutils literal">oowriter</tt> 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.</li>
<li>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 <tt class="docutils literal">oowriter</tt> to MS
Word documents that use these style names.</li>
<li>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 <tt class="docutils literal">oowriter</tt> (menu item
<tt class="docutils literal">Format/Styles and Formatting</tt>) to be understandable in the
language of your users.</li>
<li><tt class="docutils literal">odtwriter</tt> 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.</li>
</ul>
</div>
<div class="section" id="how-to-use-custom-style-names">
<h3><a class="toc-backref" href="#id22">4.3.2 How to use custom style names</a></h3>
<p>In order to define custom style names and to generate documents that
contain them, do the following:</p>
<ol class="arabic">
<li><p class="first">Create a configuration file containing a "Formats" section. The
configuration file obeys the file format supported by the Python
ConfigParser module:
<a class="reference external" href="http://docs.python.org/lib/module-ConfigParser.html">ConfigParser -- Configuration file parser --
http://docs.python.org/lib/module-ConfigParser.html</a>.</p>
</li>
<li><p class="first">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 <tt class="docutils literal">odtwriter</tt>
style name (without "rststyle-"), and the value is your custom
style name. Here is an example:</p>
<pre class="literal-block">
[Formats]
textbody: mytextbody
bulletitem: mybulletitem
heading1: myheading1
o
o
o
</pre>
</li>
<li><p class="first">Create a styles document that defines the styles generated by
<tt class="docutils literal">odtwriter</tt>. You can create and edit the styles in OOo
<tt class="docutils literal">oowriter</tt>. It may be helpful to begin by making a copy of the
styles document that is part of the <tt class="docutils literal">odtwriter</tt> distribution
(<tt class="docutils literal">styles.odt</tt>).</p>
</li>
<li><p class="first">When you run <tt class="docutils literal">odtwriter</tt>, specify the <tt class="docutils literal"><span class="pre">--odf-config-file</span></tt>
option. You might also want to specify your styles document
using the <tt class="docutils literal"><span class="pre">--stylesheet</span></tt> option in order to include your
custom style definitions. For example:</p>
<pre class="literal-block">
rst2odt.py --odf-config-file=mymappingfile.ini --stylesheet=mystyles.odt mydoc.txt mydoc.odt
</pre>
</li>
</ol>
</div>
</div>
<div class="section" id="classes">
<h2><a class="toc-backref" href="#id23">4.4 Classes</a></h2>
<p><tt class="docutils literal">odtwriter</tt> uses the following Docutils class to provide additional
control of the generation of ODF content:</p>
<ul>
<li><p class="first">Class <tt class="docutils literal">wrap</tt> -- Use this to cause the wrapping of text around
an image. The default is <em>not</em> to wrap text around images.
Here is an example:</p>
<pre class="literal-block">
.. class:: wrap
.. image:: images/flower01.png
:alt: A bright yellow flower
:height: 55
:width: 60
</pre>
</li>
</ul>
</div>
<div class="section" id="roles">
<h2><a class="toc-backref" href="#id24">4.5 Roles</a></h2>
<p>You can use a Docutils custom interpreted text role to attach a
character style to an inline area of text. This capability also
enables you to attach a new character style (with a new name) that
you define yourself. Do this by defining your role in a stylesheet
as a character style with "rststyle-" prefixed to your role name,
then use the <tt class="docutils literal">role</tt> directive and inline markup to apply your
role.</p>
<p>In order to use this capability, do the following:</p>
<ul>
<li><p class="first">Define the character style for your custom role in a stylesheet
(a copy of <tt class="docutils literal">styles.odt</tt>) with the prefix "rststyle-".
Remember: (1) If the name of your custom role is "pretty", then
define a character style named "rststyle-pretty". (2) Define the
style as a <em>character</em> style, and <em>not</em>, for example as a
paragraph style.</p>
</li>
<li><p class="first">Declare your role in the source reStructuredText document in a
<tt class="docutils literal">role</tt> directive. Example:</p>
<pre class="literal-block">
.. role:: pretty
</pre>
</li>
<li><p class="first">Use inline markup to apply your role to text. Example:</p>
<pre class="literal-block">
We have :pretty:`very nice` apples.
</pre>
</li>
</ul>
<p>Here is another example:</p>
<pre class="literal-block">
.. role:: fancy
Here is some :fancy:`pretty text` that looks fancy.
</pre>
<p>For more on roles see:
<a class="reference external" href="http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles">Custom Interpreted Text Roles --
http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles</a>.</p>
<p><strong>Note:</strong> The ability to base a role on another existing role is
<em>not</em> supported by <tt class="docutils literal">odtwriter</tt>.</p>
</div>
</div>
<div class="section" id="hints-and-suggestions-and-features">
<h1><a class="toc-backref" href="#id25">5 Hints and Suggestions and Features</a></h1>
<div class="section" id="table-of-contents">
<h2><a class="toc-backref" href="#id26">5.1 Table of contents</a></h2>
<p>The <tt class="docutils literal">..contents::</tt> directive causes <tt class="docutils literal">odtwriter</tt> to generate
either:</p>
<ol class="arabic simple">
<li>A static, outline style table of contents, if the
<tt class="docutils literal"><span class="pre">--generate-list-toc</span></tt> command line option is specified, or</li>
<li>An ODF/<tt class="docutils literal">oowriter</tt> style table of contents containing
dynamically updated page numbers and with the formatting control
that <tt class="docutils literal">oowriter</tt> gives you. This is the default, or use the
command line option <tt class="docutils literal"><span class="pre">--generate-list-toc</span></tt>. <strong>Note:</strong>
<tt class="docutils literal">odtwriter</tt> is not able to determine page numbers, so you will
need to open the generated document in <tt class="docutils literal">oowriter</tt>, then
right-click on the table of contents and select "Update" to
insert correct page numbers.</li>
</ol>
</div>
<div class="section" id="syntax-highlighting">
<h2><a class="toc-backref" href="#id27">5.2 Syntax highlighting</a></h2>
<p><tt class="docutils literal">odtwriter</tt> can add syntax highlighting to code in code
blocks. In order to activate this, do all of the following:</p>
<ol class="arabic">
<li><p class="first">Install <a class="reference external" href="http://pygments.pocoo.org/">Pygments</a> and ...</p>
</li>
<li><p class="first">Use the command line option <tt class="docutils literal"><span class="pre">--add-syntax-highlighting</span></tt>.
Example:</p>
<pre class="literal-block">
$ rst2odt.py --add-syntax-highlight test.txt test.odt
</pre>
</li>
</ol>
<p>The following styles are defined in styles.odt and are used for
literal code blocks and syntax highlighting:</p>
<ul class="simple">
<li>Paragraph styles:<ul>
<li>rststyle-codeblock -- The style for the code block as a whole.</li>
</ul>
</li>
<li>Character styles:<ul>
<li>rststyle-codeblock-classname -- class names.</li>
<li>rststyle-codeblock-comment -- comments.</li>
<li>rststyle-codeblock-functionname -- function names.</li>
<li>rststyle-codeblock-keyword -- Python language keywords.</li>
<li>rststyle-codeblock-name -- other names, for example,
variables.</li>
<li>rststyle-codeblock-number -- literal numbers, including
integers, floats, hex numbers, and octal numbers.</li>
<li>rststyle-codeblock-operator -- Python operators.</li>
<li>rststyle-codeblock-string -- literal strings.</li>
</ul>
</li>
</ul>
<p>Each of the above styles has a default appearance that is defined
in <tt class="docutils literal">styles.odt</tt>. To change that definition and appearance, open
<tt class="docutils literal">styles.odt</tt> in <tt class="docutils literal">oowriter</tt> and use menu item:</p>
<pre class="literal-block">
Format --> Styles and Formatting
</pre>
<p>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.</p>
</div>
<div class="section" id="the-container-directive">
<h2><a class="toc-backref" href="#id28">5.3 The container directive</a></h2>
<p>There is limited support for the <tt class="docutils literal">container</tt> directive. The
limitations and rules for the container directive are the following:</p>
<ul class="simple">
<li>Only the first class in the list of classes (arguments) is used.</li>
<li>That class/style must be a paragraph style and not (for example) a
character style.</li>
<li>The style/class given to the container directive will have a
"rststyle-" prefix in the odt file.</li>
</ul>
<p>So, for example:</p>
<pre class="literal-block">
.. container:: style-1 style-2 style-3
a block of text
</pre>
<ul class="simple">
<li>Only <tt class="docutils literal"><span class="pre">style-1</span></tt> is used; <tt class="docutils literal"><span class="pre">style-2</span></tt> and <tt class="docutils literal"><span class="pre">style-3</span></tt> are ignored.</li>
<li><tt class="docutils literal"><span class="pre">rststyle-style-1</span></tt> must be defined. It should be an existing,
predefined style, or you should define it in your stylesheet
(<tt class="docutils literal">styles.odt</tt> or the argument to the <tt class="docutils literal"><span class="pre">--stylesheet</span></tt> command
line option).</li>
<li><tt class="docutils literal"><span class="pre">rststyle-style-1</span></tt> must be a paragraph style.</li>
</ul>
<p>To define a paragraph style, use the following menu item in
<tt class="docutils literal">oowriter</tt>:</p>
<pre class="literal-block">
Format --> Styles and Formatting
</pre>
<p>Then, click on the Paragraph Styles button.</p>
<p>The following example attaches the <tt class="docutils literal"><span class="pre">rststyle-heading2</span></tt> style (a
predefined style) to each paragraph/line in the container:</p>
<pre class="literal-block">
.. container:: heading2
Line 1 of container.
Line 2 of container.
</pre>
<p>More information on how to define a new style (for example, in your
<tt class="docutils literal">styles.odt</tt>) can be found in section
<a class="reference internal" href="#defining-and-using-custom-style-names">Defining and using custom style names</a>.</p>
</div>
<div class="section" id="the-table-directive">
<h2><a class="toc-backref" href="#id29">5.4 The table directive</a></h2>
<p>The <tt class="docutils literal">table</tt> directive can be used to add a title to a table.
Example:</p>
<pre class="literal-block">
.. table:: A little test table
=========== =============
Name Value
=========== =============
Dave Cute
Mona Smart
=========== =============
</pre>
<p>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 <tt class="docutils literal"><span class="pre">rststyle-table-title</span></tt>.</p>
</div>
<div class="section" id="footnotes-and-citations">
<h2><a class="toc-backref" href="#id30">5.5 Footnotes and citations</a></h2>
<p>Footnotes and citations are supported.</p>
<p>There are additional styles <tt class="docutils literal"><span class="pre">rststyle-footnote</span></tt> and
<tt class="docutils literal"><span class="pre">rststyle-citation</span></tt> for footnotes and citations. See
<a class="reference internal" href="#footnote-and-citation-styles">Footnote and citation styles</a>.</p>
<p>You may need to modify the citation style to fit the length of your
citation references.</p>
<p>Endnotes -- There are command line options that control whether
<tt class="docutils literal">odtwriter</tt> creates endnotes instead of footnotes. Endnotes
appear at the end of the document instead of at the bottom of the
page. See flags <tt class="docutils literal"><span class="pre">--endnotes-end-doc</span></tt> and
<tt class="docutils literal"><span class="pre">--no-endnotes-end-doc</span></tt> in section <a class="reference internal" href="#command-line-options">Command line options</a>.</p>
</div>
<div class="section" id="images-and-figures">
<h2><a class="toc-backref" href="#id31">5.6 Images and figures</a></h2>
<p>If on the image or the figure directive you provide the scale option
but do not provide the width and height options, then <tt class="docutils literal">odtwriter</tt>
will attempt to determine the size of the image using the <a class="reference external" href="http://www.pythonware.com/products/pil/">Python
Imaging Library</a> (PIL). If <tt class="docutils literal">odtwriter</tt> 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:</p>
<ul class="simple">
<li>Install the Python Imaging Library or</li>
<li>Remove the <tt class="docutils literal">scale</tt> option or</li>
<li>Add both the <tt class="docutils literal">width</tt> and the <tt class="docutils literal">height</tt> options.</li>
</ul>
<p>So, the rule is: if on any image or figure, you specify scale but
not both width and height, you must install the <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging
Library</a> library.</p>
<p>For more information about PIL, see: <a class="reference external" href="http://www.pythonware.com/products/pil/">Python Imaging Library</a>.</p>
</div>
<div class="section" id="the-raw-directive">
<h2><a class="toc-backref" href="#id32">5.7 The raw directive</a></h2>
<p>The <tt class="docutils literal">raw</tt> directive is supported. Use output format type "odt".</p>
<p>You will need to be careful about the formatting of the raw
content. In particular, introduced whitespace might be a problem.</p>
<p>In order to produce content for the raw directive for use by
<tt class="docutils literal">odtwriter</tt>, you might want to extract the file <tt class="docutils literal">content.xml</tt>
from a <tt class="docutils literal">.odt</tt> file (using some Zip tool), and then clip, paste,
and modify a selected bit of it.</p>
<p>Here is an example:</p>
<pre class="literal-block">
.. 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>
</pre>
</div>
<div class="section" id="the-meta-directive">
<h2><a class="toc-backref" href="#id33">5.8 The meta directive</a></h2>
<p><tt class="docutils literal">odtwriter</tt> supports the <tt class="docutils literal">meta</tt> directive. Two fields are
recognized: "keywords" and "description". Here is an example:</p>
<pre class="literal-block">
.. meta::
:keywords: reStructuredText, docutils, formatting
:description lang=en: A reST document, contains formatted
text in a formatted style.
</pre>
<p>To see the results of the <tt class="docutils literal">meta</tt> directive in <tt class="docutils literal">oowriter</tt>,
select menu item "File/Properties...", then click on the
"Description" tab.</p>
</div>
<div class="section" id="footnote-references-inside-footnotes">
<h2><a class="toc-backref" href="#id34">5.9 Footnote references inside footnotes</a></h2>
<p>Not supported.</p>
<p>Get a grip. Be serious. Try a dose of reality.</p>
<p><tt class="docutils literal">odtwriter</tt> ignores them.</p>
<p>They cause <tt class="docutils literal">oowriter</tt> to croak.</p>
</div>
<div class="section" id="page-size">
<h2><a class="toc-backref" href="#id35">5.10 Page size</a></h2>
<p>The default page size, in documents generated by <tt class="docutils literal">odtwriter</tt> is
<tt class="docutils literal">Letter</tt>. You can change this (for example to <tt class="docutils literal">A4</tt>) by using a
custom stylesheet. See <a class="reference internal" href="#defining-and-using-a-custom-stylesheet">Defining and using a custom stylesheet</a>
for instructions on how to do this.</p>
<p>On machines which support <tt class="docutils literal">paperconf</tt>, <tt class="docutils literal">odtwriter</tt> can insert
the default page size for your locale. In order for this to work,
the following conditions must be met:</p>
<ol class="arabic">
<li><p class="first">The program <tt class="docutils literal">paperconf</tt> must be available on your system.
<tt class="docutils literal">odtwriter</tt> uses <tt class="docutils literal">paperconf <span class="pre">-s</span></tt> to obtain the paper size.
See <tt class="docutils literal">man paperconf</tt> for more information.</p>
</li>
<li><p class="first">The default page height and width must be removed from the
<tt class="docutils literal">styles.odt</tt> used to generate the document. A Python script
<tt class="docutils literal">rst2odt_prepstyles.py</tt> is distributed with <tt class="docutils literal">odtwriter</tt> and
is installed in the <tt class="docutils literal">bin</tt> directory. You can remove the page
height and width with something like the following:</p>
<pre class="literal-block">
$ rst2odt_prepstyles.py styles.odt
</pre>
</li>
</ol>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you edit your stylesheet in <tt class="docutils literal">oowriter</tt> and then
save it, <tt class="docutils literal">oowriter</tt> 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 <tt class="docutils literal">odtwriter</tt> to
insert a default page size using <tt class="docutils literal">paperconf</tt>, then you will
need to strip the page size from your stylesheet each time you
edit that stylesheet with <tt class="docutils literal">oowriter</tt>.</p>
</div>
</div>
<div class="section" id="custom-header-footers-inserting-page-numbers-date-time-etc">
<h2><a class="toc-backref" href="#id36">5.11 Custom header/footers: inserting page numbers, date, time, etc</a></h2>
<p>You can specify custom headers and footers for your document from
the command line. These headers and footers can be used to insert
fields such as the page number, page count, date, time, etc. See
below for a complete list.</p>
<p>To insert a custom header or footer, use the "--custom-odt-header"
or "--custom-odt-footer" command line options. For example, the
following inserts a footer containing the page number and page
count:</p>
<pre class="literal-block">
$ rst2odt.py --custom-odt-footer="Page %p% of %P%" f1.txt f1.odt
</pre>
<div class="section" id="field-specifiers">
<h3><a class="toc-backref" href="#id37">5.11.1 Field specifiers</a></h3>
<p>You can use the following field specifiers to insert <tt class="docutils literal">oowriter</tt>
fields in your custom headers and footers:</p>
<dl class="docutils">
<dt>%p%</dt>
<dd>The current page number.</dd>
<dt>%P%</dt>
<dd>The number of pages in the document.</dd>
<dt>%d1%</dt>
<dd>The current date in format 12/31/99.</dd>
<dt>%d2%</dt>
<dd>The current date in format 12/31/1999.</dd>
<dt>%d3%</dt>
<dd>The current date in format Dec 31, 1999.</dd>
<dt>%d4%</dt>
<dd>The current date in format December 31, 1999.</dd>
<dt>%d5%</dt>
<dd>The current date in format 1999-12-31.</dd>
<dt>%t1%</dt>
<dd>The current time in format 14:22.</dd>
<dt>%t2%</dt>
<dd>The current time in format 14:22:33.</dd>
<dt>%t3%</dt>
<dd>The current time in format 02:22 PM.</dd>
<dt>%t4%</dt>
<dd>The current time in format 02:22:33 PM.</dd>
<dt>%a%</dt>
<dd>The author of the document (actually the initial creator).</dd>
<dt>%t%</dt>
<dd>The document title.</dd>
<dt>%s%</dt>
<dd>The document subject.</dd>
</dl>
<p><strong>Note:</strong> The use of the above field specifiers in the body of your
reStructuredText document is <strong>not</strong> supported, because these
specifiers are not standard across Docutils writers.</p>
</div>
</div>
</div>
<div class="section" id="credits">
<h1><a class="toc-backref" href="#id38">6 Credits</a></h1>
<p>Stefan Merten designed and implemented the custom style names
capability. Thank you, Stefan.</p>
<p>Michael Schutte supports the Debian GNU/Linux distribution of
<tt class="docutils literal">odtwriter</tt>. Thank you, Michael, for providing and supporting
the Debian package.</p>
<p>Michael Schutte implemented the fix that enables <tt class="docutils literal">odtwriter</tt> to
pick up the default paper size on platforms where the program
<tt class="docutils literal">paperconf</tt> is available. Thank you.</p>
</div>
</div>
</body>
</html>