1 =======================
2 Odt Writer for Docutils
3 =======================
6 :Contact: docutils-develop@lists.sourceforge.net
9 :Copyright: This document has been placed in the public domain.
11 :abstract: This document describes the Docutils odtwriter
23 What it does -- ``rst2odt.py`` translates reST
24 (reStructuredText) into a Open Document Format ``.odt`` file. You
25 can learn more about the ODF format here:
27 - `OASIS Open Document Format for Office Applications
30 - `Open Document at Wikipedia`_
32 You should be able to open documents (.odt files) generated with
33 ``rst2odt.py`` in ``OpenOffice/oowriter``.
35 You can learn more about Docutils and reST here: `Docutils`_
41 In addition to the Docutils standard requirements, ``odtwriter``
44 - ElementTree -- Python (version 2.5 or later) now includes
45 ElementTree (``xml.etree.ElementTree``).
47 - Optional -- `Pygments`_ is required if you want syntax
48 highlighting of code in literal blocks. See section `Syntax
51 - Optional -- `Python Imaging Library`_ (PIL) is required if on an
52 image or figure directive, you specify ``scale`` but not ``width``
53 and ``height``. See section `Images and figures`_.
60 Run it from the command line as follows::
62 $ rst2odt.py myinput.txt myoutput.odt
64 To see usage information and to learn about command line options
65 that you can use, run the following::
71 $ rst2odt.py -s -g python_comments.txt python_comments.odt
73 $ rst2odt.py --source-url=odtwriter.txt --generator --stylesheet=/myconfigs/styles.odt odtwriter.txt odtwriter.odt
79 The options described below can also be set in a configuration file.
80 Use section ``[odf_odt writer]`` to set options specific to the
81 ``odtwriter``. For example::
84 stylesheet: styles1.odt
86 See the "Docutils Configuration" document for more information on
87 Docutils configuration files, including locations which are
94 The following command line options are specific to ``odtwriter``:
96 --stylesheet=<URL> Specify a stylesheet URL, used verbatim.
97 Default: writers/odf_odt/styles.odt in the
98 installation directory.
99 --odf-config-file=<file>
100 Specify a configuration/mapping file relative to the
101 current working directory for additional ODF options.
102 In particular, this file may contain a section named
103 "Formats" that maps default style names to names to be
104 used in the resulting output file allowing for
105 adhering to external standards. For more info and the
106 format of the configuration/mapping file, see the
108 --cloak-email-addresses
109 Obfuscate email addresses to confuse harvesters while
110 still keeping email links usable with standards-
112 --no-cloak-email-addresses
113 Do not obfuscate email addresses.
114 --table-border-thickness=TABLE_BORDER_THICKNESS
115 Specify the thickness of table borders in thousands of
117 --add-syntax-highlighting
118 Add syntax highlighting in literal code blocks.
119 --no-syntax-highlighting
120 Do not add syntax highlighting in literal code blocks.
122 --create-sections Create sections for headers. (default)
123 --no-sections Do not create sections for headers.
124 --create-links Create links.
125 --no-links Do not create links. (default)
126 --endnotes-end-doc Generate endnotes at end of document, not footnotes at
128 --no-endnotes-end-doc Generate footnotes at bottom of page, not endnotes at
129 end of document. (default)
130 --generate-list-toc Generate a bullet list table of contents, not an
131 ODF/``oowriter`` table of contents.
132 --generate-oowriter-toc
133 Generate an ODF/``oowriter`` table of contents,
134 not a bullet list. (default) **Note:**
135 ``odtwriter`` is not able to determine page
136 numbers, so you will need to open the
137 generated document in ``oowriter``, then
138 right-click on the table of contents and
139 select "Update" to insert page numbers.
140 --custom-odt-header=CUSTOM_HEADER
141 Specify the contents of an custom header line. See
142 odf_odt writer documentation for details about special
143 field character sequences. See section
144 `Custom header/footers: inserting page numbers, date, time, etc`_
146 --custom-odt-footer=CUSTOM_FOOTER
147 Specify the contents of an custom footer line. See
148 odf_odt writer documentation for details about special
149 field character sequences. See section
150 `Custom header/footers: inserting page numbers, date, time, etc`_
158 ``odtwriter`` uses a number of styles that are defined in
159 ``styles.xml`` in the default ``styles.odt``. This section
160 describes those styles.
162 Note that with the ``--stylesheet`` command line option, you can
163 use either ``styles.odt`` or ``styles.xml``, as described below.
164 Use of ``styles.odt`` is recommended over ``styles.xml``.
166 You can modify the look of documents generated by ``odtwriter`` in
169 - Open (a copy of) ``styles.odt`` in ``OpenOffice/oowriter`` and
170 modify the style you wish to change. Now, save this document,
171 then generate your documents using this modified copy of
174 In my version of ``oowriter``, to modify styles, either (1)
175 press F11 or (2) use menu item "Format/Styles and Formatting",
176 then right-click on the relevant style and select "Modify".
177 Modify the style, then save your document.
179 - Open a document generated by ``odtwriter`` in `oowriter``. Now,
180 edit the style you are interested in modifying. Now, you
181 can extract the styles.xml file from your document and either
182 (1) use this as your default styles file or (2) copy and paste
183 the relevant style definition into your styles.xml.
185 - Extract ``styles.xml`` from ``styles.odt`` using your favorite
186 ``zip/unzip`` tool. Then modify ``styles.xml`` with a text
187 editor. Now re-zip it back into your own ``styles.odt``, or use
188 it directly by specifying it with the ``--stylesheet`` command
189 line option. **Hint:** If you intend to extract ``styles.xml``
190 from an ``.odt`` file (and then "re-zip" it), you should turn off
191 XML optimization/compression in ``oowriter``. In order to this
192 in ``oowriter``, use Tools --> Options... --> Load-Save -->
193 General and turn off "Size optimization for XML format".
195 - Open an empty (or new) document in ``oowriter``. Define all of
196 the styles described in this section. Then, use that document (a
197 .odt file) as your stylesheet. ``odtwriter`` will extract the
198 ``styles.xml`` file from that document and insert it into the
201 - Some combination of the above.
204 Styles used by odtwriter
205 ------------------------
207 This section describes the styles used by ``odtwriter``.
209 Note that we do not describe the "look" of these styles. That can
210 be easily changed by using ``oowriter`` to edit the document
211 ``styles.odt`` (or a copy of it), and modifying any of the styles
214 To change the definition and appearance of these styles, open
215 ``styles.odt`` in ``oowriter`` and open the Styles and Formatting
216 window by using the following menu item::
218 Format --> Styles and Formatting
220 Then, click on the Paragraph Styles button or the Character Styles
221 button at the top of the Styles and Formatting window. You may
222 also need to select "All Styles" from the drop-down selection list
223 at the bottom of the Styles and Formatting window in order to see
224 the styles used by ``odtwriter``.
226 Notice that you can make a copy of file ``styles.odt``, modify it
227 using ``oowriter``, and then use your copy with the
228 ``--stylesheet=<file>`` command line option. Example::
230 $ rst2odt.py --stylesheet=mystyles.odt test2.txt test2.odt
237 The style for attributions, for example, the attribution in a
238 ``.. epigraph::`` directive. Derived from
239 ``rststyle-blockquote``.
247 rststyle-blockquote-bulletitem
248 The style for bullet list items inside block quote.
250 rststyle-blockquote-enumitem
251 The style for enumerated list items inside block quote.
257 An item in an bullet list.
260 The caption in a figure or image. Also see
264 Literal code blocks -- A block of example code. Created with
265 double colon ("::") followed by an indented block or with the
266 ``.. parsed-literal::`` directive. Derived from the
267 ``Preformatted Text`` style in ``oowriter``.
270 An item in an enumerated list.
273 The style for epigraphs, for example, the body of an
274 ``.. epigraph::`` directive. Derived from
275 ``rststyle-blockquote``.
277 rststyle-epigraph-bulletitem
278 The style for bullet list items inside epigraphs.
280 rststyle-epigraph-enumitem
281 The style for enumerated list items inside epigraphs.
284 The style for footers. The footer content originates from the
285 ``..footer::`` directive and in response to the command line
286 flags for generator (``--generator``), date/time generated
287 (``--date`` and ``--time``), and view source link
288 (``--source-link`` and ``--source-url=URL``).
291 The style for headers. The header content originates from the
292 ``..header::`` directive.
295 The style for highlightss, for example, the body of an
296 ``.. highlights::`` directive. Derived from
297 ``rststyle-blockquote``.
299 rststyle-highlights-bulletitem
300 The style for bullet list items inside highlights.
302 rststyle-highlights-enumitem
303 The style for enumerated list items inside highlights.
305 rststyle-horizontalline
306 A horizontal line, e.g. used for transitions.
309 The legend in a figure. See the Docutils figure directive. Also
310 see ``rststyle-caption``.
313 The style for titles of tables. See section `The table
317 Normal text. The style for paragraphs. Derived from the ``Text
318 body`` style in ``oowriter``.
325 Emphasis. Normally rendered as italics.
327 rststyle-inlineliteral
331 Strong emphasis. Normally rendered as boldface.
334 In-line quoted material.
336 rststyle-codeblock-classname
337 Syntax highlighting in literal code blocks -- class names.
339 rststyle-codeblock-comment
340 Syntax highlighting in literal code blocks -- comments.
342 rststyle-codeblock-functionname
343 Syntax highlighting in literal code blocks -- function names.
345 rststyle-codeblock-keyword
346 Syntax highlighting in literal code blocks -- Python language
349 rststyle-codeblock-name
350 Syntax highlighting in literal code blocks -- other names, for
353 rststyle-codeblock-number
354 Syntax highlighting in literal code blocks -- literal numbers,
355 including integers, floats, hex numbers, and octal numbers.
357 rststyle-codeblock-operator
358 Syntax highlighting in literal code blocks -- Python operators.
360 rststyle-codeblock-string
361 Syntax highlighting in literal code blocks -- literal strings.
368 Bullet lists (but not in the table of contents)
370 rststyle-blockquote-bulletlist
371 Bullet lists in block quotes.
373 rststyle-blockquote-enumlist
374 Enumerated lists in block quotes.
376 rststyle-enumlist-arabic
377 Enumerated lists, arabic (but not in the table of contents)
379 rststyle-enumlist-loweralpha
380 Enumerated lists, lower alpha (but not in the table of contents)
382 rststyle-enumlist-lowerroman
383 Enumerated lists, lower roman (but not in the table of contents)
385 rststyle-enumlist-upperalpha
386 Enumerated lists, upper alpha (but not in the table of contents)
388 rststyle-enumlist-upperroman
389 Enumerated lists, upper roman (but not in the table of contents)
391 rststyle-epigraph-bulletlist
392 Bullet lists in epigraphs. See the ``.. epigraph::``
395 rststyle-epigraph-enumlist
396 Enumerated lists in epigraphs. See the ``.. epigraph::``
399 rststyle-highlights-bulletlist
400 Bullet lists in highlights blocks. See the ``.. highlights::``
403 rststyle-highlights-enumlist
404 Enumerated lists in highlights blocks. See the ``.. highlights::``
407 rststyle-tocbulletlist
408 Lists in the table of contents when section numbering is off.
411 Lists in the table of contents when section numbering is on.
417 rststyle-admon-attention-hdr
418 The style for the attention admonition header/title.
420 rststyle-admon-attention-body
421 The style for the attention admonition body/paragraph.
423 rststyle-admon-caution-hdr
424 The style for the caution admonition header/title.
426 rststyle-admon-caution-body
427 The style for the caution admonition body/paragraph.
429 rststyle-admon-danger-hdr
430 The style for the admonition header/title.
432 rststyle-admon-danger-body
433 The style for the danger admonition body/paragraph.
435 rststyle-admon-error-hdr
436 The style for the error admonition header/title.
438 rststyle-admon-error-body
439 The style for the error admonition body/paragraph.
441 rststyle-admon-hint-hdr
442 The style for the hint admonition header/title.
444 rststyle-admon-hint-body
445 The style for the hint admonition body/paragraph.
447 rststyle-admon-hint-hdr
448 The style for the hint admonition header/title.
450 rststyle-admon-hint-body
451 The style for the hint admonition body/paragraph.
453 rststyle-admon-important-hdr
454 The style for the important admonition header/title.
456 rststyle-admon-important-body
457 The style for the important admonition body/paragraph.
459 rststyle-admon-note-hdr
460 The style for the note admonition header/title.
462 rststyle-admon-note-hdr
463 The style for the note admonition header/title.
465 rststyle-admon-tip-body
466 The style for the tip admonition body/paragraph.
468 rststyle-admon-tip-hdr
469 The style for the tip admonition header/title.
471 rststyle-admon-warning-body
472 The style for the warning admonition body/paragraph.
474 rststyle-admon-warning-hdr
475 The style for the warning admonition header/title.
477 rststyle-admon-generic-body
478 The style for the generic admonition body/paragraph.
480 rststyle-admon-generic-hdr
481 The style for the generic admonition header/title.
488 The style for the text in a rubric directive.
490 The rubric directive recognizes a "class" option. If entered,
491 odtwriter uses the value of that option instead of the
492 ``rststyle-rubric`` style. Here is an example which which attaches
493 the ``rststyle-heading1`` style to the generated rubric::
495 .. rubric:: This is my first rubric
496 :class: rststyle-heading1
502 A table style is generated by ``oowriter`` for each table that you
503 create. Therefore, ``odtwriter`` attempts to do something similar.
504 These styles are created in the ``content.xml`` document in the
505 generated ``.odt`` file. These styles have names prefixed with
508 There are two ways in which you can control the styles of your
509 tables: one simple, the other a bit more complex, but more
512 First, you can change the thickness of the borders of all tables
513 generated in a document using the "--table-border-thickness"
516 Second, you can control additional table properties and you can
517 apply different styles to different tables within the same document
518 by customizing and using tables in your stylesheet: ``styles.odt``
519 or whatever you name your copy of it using the --stylesheet command
520 line option. Then, follow these rules to apply a table style to
521 the tables in your document:
523 - The default table style -- Optionally, alter and customize the
524 style applied by default to tables in your document by modifying
525 table "rststyle-table-0" in your stylesheet (``styles.odt`` or a
526 copy). Caution: Do not change the name of this table.
528 - User-created table styles -- Add one or more new table styles to
529 be applied selectively to tables in your document by doing the
532 1. Using ``oowriter``, add a table to your stylesheet and give it
533 a name that starts with the prefix "rststyle-table-", for
534 example "rststyle-table-vegetabledata". Customize the table's
535 border thickness, border color, and table background color.
537 2. In your reStructuredText document, apply your new table style
538 to a specific table by placing the ".. class::" directive
539 immediately before the table, for example::
541 .. class:: rststyle-table-vegetabledata
543 The default table style will be applied to all tables for which you
544 do not specify a style with the ".. class::" directive.
546 Customize the table properties in ``oowriter`` using the table
547 properties dialog for the table (style) that you wish to customize.
549 Note that "--table-border-thickness" command line option overrides
550 the border thickness specified in the stylesheet.
552 The specific properties that you can control with this second
553 method are the following:
555 - Border thickness and border color.
557 - Background color -- When you change the background color of a
558 table to be used as a style (in ``styles.odt`` or whatever you
559 name it), make sure you change the background color for the
560 *table* and *not* for a cell in the table. ``odtwriter`` picks
561 the background color from the table, not from a cell within the
568 The line block styles wrap the various nested levels of line
569 blocks. There is one line block style for each indent level.
572 Line block style for line block with no indent.
575 Line block style for line block indented 1 level.
578 Line block style for line block indented 2 levels.
581 Line block style for line block indented 3 levels.
584 Line block style for line block indented 4 levels.
587 Line block style for line block indented 5 levels.
591 - ``odtwriter`` does not check for a maximum level of indents
592 within line blocks. Therefore, you can define additional line
593 block styles for additional levels if you need them. Define
594 these styles with the names ``rststyle-lineblock7``,
595 ``rststyle-lineblock8``, ...
597 - Since the line block style is used to create indentation, a line
598 block that is inside a block quote will use
599 ``rststyle-lineblock2`` as its first level of indentation.
602 Footnote and citation styles
603 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
606 The style for footnotes. This style affects the footnote
607 content, *not* the footnote reference in the body of the document.
610 The style for citations. This style affects the citation
611 content, *not* the citation reference in the body of the document.
612 You might need to adjust the indentation in this style
613 depending on the length of the label used in your citations.
616 Heading and title styles
617 ~~~~~~~~~~~~~~~~~~~~~~~~~
619 rststyle-heading{1|2|3|4|5}
620 The styles for headings (section titles and sub-titles). Five
621 levels of sub-headings are provided: rststyle-heading1 through
625 The style for the document title.
628 The style for the document sub-title.
631 Image and figure styles
632 ~~~~~~~~~~~~~~~~~~~~~~~~~
635 The style applied to an image, either an image by itself or an
639 The style applied to a figure (actually to the frame that
644 Defining and using a custom stylesheet
645 ---------------------------------------
647 You can create your own custom stylesheet. Here is how:
649 1. Make a copy of ``styles.odt``, which is in the distribution.
651 2. Open your copy of ``styles.odt`` in ``oowriter``. Modify styles
652 in that document. Then, save it.
654 3. When you run ``rst2odt.py``, use the ``--stylesheet`` command
655 line option to use your custom stylesheet. Run ``rst2odt.py
656 --help`` to learn more about these options.
659 Why custom stylesheets
660 ~~~~~~~~~~~~~~~~~~~~~~~
662 Here are a few reasons and ideas:
664 - The page size is stored in the style sheet. The default page
665 size is ``Letter``. You can change the page size (for example,
666 to ``A4``) in your custom stylesheet by opening it in
667 ``oowriter``, then clicking on menu: ``Format/Page...``, then
668 clicking on the ``Page`` tab.
672 Defining and using custom style names
673 -------------------------------------
675 [Credits: Stefan Merten designed and implemented the custom style names
676 capability. Thank you, Stefan.]
678 You can also instruct ``odtwriter`` to use style names of your own
682 Why custom style names
683 ~~~~~~~~~~~~~~~~~~~~~~
685 Here are a few reasons and ideas:
687 - Suppose that your organization has a standard set of styles in
688 OOo ``oowriter`` and suppose that the use of these styles is
689 required. You would like to generate ODF documents from
690 reST text files, and you want the generated documents to contain
693 - Suppose that your company or organization has a policy of using a
694 certain MS Word template for some set of documents. You would
695 like to generate ODF documents that use these custom style names,
696 so that you can export these documents from ODF ``oowriter`` to MS
697 Word documents that use these style names.
699 - Suppose that your documents are written in a language other than
700 English. You would like the style names visible in the "Styles
701 and Formatting" window in OOo ``oowriter`` (menu item
702 ``Format/Styles and Formatting``) to be understandable in the
703 language of your users.
705 - ``odtwriter`` maps single asterisks/stars (for example, \*stuff\*)
706 to emphasis and double stars to strong. You'd like to reverse
707 these. Or, you would like to generate headings level 3 and 4
708 where headings level 1 and 2 would normally be produced.
711 How to use custom style names
712 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
714 In order to define custom style names and to generate documents that
715 contain them, do the following:
718 1. Create a configuration file containing a "Formats" section. The
719 configuration file obeys the file format supported by the Python
721 `ConfigParser -- Configuration file parser --
722 http://docs.python.org/lib/module-ConfigParser.html
723 <http://docs.python.org/lib/module-ConfigParser.html>`_.
725 2. In the "Formats" section of the configuration file, create one
726 option (a name-value pair) for each custom style name that you
727 wish to define. The option name is the standard ``odtwriter``
728 style name (without "rststyle-"), and the value is your custom
729 style name. Here is an example::
733 bulletitem: mybulletitem
739 3. Create a styles document that defines the styles generated by
740 ``odtwriter``. You can create and edit the styles in OOo
741 ``oowriter``. It may be helpful to begin by making a copy of the
742 styles document that is part of the ``odtwriter`` distribution
745 4. When you run ``odtwriter``, specify the ``--odf-config-file``
746 option. You might also want to specify your styles document
747 using the ``--stylesheet`` option in order to include your
748 custom style definitions. For example::
750 rst2odt.py --odf-config-file=mymappingfile.ini --stylesheet=mystyles.odt mydoc.txt mydoc.odt
756 ``odtwriter`` uses the following Docutils class to provide additional
757 control of the generation of ODF content:
759 - Class ``wrap`` -- Use this to cause the wrapping of text around
760 an image. The default is *not* to wrap text around images.
764 .. image:: images/flower01.png
765 :alt: A bright yellow flower
773 You can use a Docutils custom interpreted text role to attach a
774 character style to an inline area of text. This capability also
775 enables you to attach a new character style (with a new name) that
776 you define yourself. Do this by defining your role in a stylesheet
777 as a character style with "rststyle-" prefixed to your role name,
778 then use the ``role`` directive and inline markup to apply your
781 In order to use this capability, do the following:
783 - Define the character style for your custom role in a stylesheet
784 (a copy of ``styles.odt``) with the prefix "rststyle-".
785 Remember: (1) If the name of your custom role is "pretty", then
786 define a character style named "rststyle-pretty". (2) Define the
787 style as a *character* style, and *not*, for example as a
790 - Declare your role in the source reStructuredText document in a
791 ``role`` directive. Example::
795 - Use inline markup to apply your role to text. Example::
797 We have :pretty:`very nice` apples.
799 Here is another example::
803 Here is some :fancy:`pretty text` that looks fancy.
805 For more on roles see:
806 `Custom Interpreted Text Roles --
807 http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
808 <http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles>`_.
810 **Note:** The ability to base a role on another existing role is
811 *not* supported by ``odtwriter``.
814 Hints and Suggestions and Features
815 ==================================
820 The ``..contents::`` directive causes ``odtwriter`` to generate
823 1. A static, outline style table of contents, if the
824 ``--generate-list-toc`` command line option is specified, or
826 2. An ODF/``oowriter`` style table of contents containing
827 dynamically updated page numbers and with the formatting control
828 that ``oowriter`` gives you. This is the default, or use the
829 command line option ``--generate-list-toc``. **Note:**
830 ``odtwriter`` is not able to determine page numbers, so you will
831 need to open the generated document in ``oowriter``, then
832 right-click on the table of contents and select "Update" to
833 insert correct page numbers.
839 ``odtwriter`` can add syntax highlighting to code in code
840 blocks. In order to activate this, do all of the following:
842 1. Install `Pygments`_ and ...
844 2. Use the command line option ``--add-syntax-highlighting``.
847 $ rst2odt.py --add-syntax-highlight test.txt test.odt
849 The following styles are defined in styles.odt and are used for
850 literal code blocks and syntax highlighting:
854 - rststyle-codeblock -- The style for the code block as a whole.
858 - rststyle-codeblock-classname -- class names.
860 - rststyle-codeblock-comment -- comments.
862 - rststyle-codeblock-functionname -- function names.
864 - rststyle-codeblock-keyword -- Python language keywords.
866 - rststyle-codeblock-name -- other names, for example,
869 - rststyle-codeblock-number -- literal numbers, including
870 integers, floats, hex numbers, and octal numbers.
872 - rststyle-codeblock-operator -- Python operators.
874 - rststyle-codeblock-string -- literal strings.
876 Each of the above styles has a default appearance that is defined
877 in ``styles.odt``. To change that definition and appearance, open
878 ``styles.odt`` in ``oowriter`` and use menu item::
880 Format --> Styles and Formatting
882 Then, click on the Paragraph Styles button or the Character Styles
883 button at the top of the Styles and Formatting window. You may
884 also need to select "All Styles" from the drop-down selection list
885 at the bottom of the Styles and Formatting window.
889 The container directive
890 -----------------------
892 There is limited support for the ``container`` directive. The
893 limitations and rules for the container directive are the following:
895 - Only the first class in the list of classes (arguments) is used.
897 - That class/style must be a paragraph style and not (for example) a
900 - The style/class given to the container directive will have a
901 "rststyle-" prefix in the odt file.
905 .. container:: style-1 style-2 style-3
909 - Only ``style-1`` is used; ``style-2`` and ``style-3`` are ignored.
911 - ``rststyle-style-1`` must be defined. It should be an existing,
912 predefined style, or you should define it in your stylesheet
913 (``styles.odt`` or the argument to the ``--stylesheet`` command
916 - ``rststyle-style-1`` must be a paragraph style.
918 To define a paragraph style, use the following menu item in
921 Format --> Styles and Formatting
923 Then, click on the Paragraph Styles button.
925 The following example attaches the ``rststyle-heading2`` style (a
926 predefined style) to each paragraph/line in the container::
928 .. container:: heading2
934 More information on how to define a new style (for example, in your
935 ``styles.odt``) can be found in section
936 `Defining and using custom style names`_.
943 The ``table`` directive can be used to add a title to a table.
946 .. table:: A little test table
948 =========== =============
950 =========== =============
953 =========== =============
955 The above will insert the title "A little test table" at the top of the
956 table. You can modify the appearance of the title by modifying the
957 paragraph style ``rststyle-table-title``.
960 Footnotes and citations
961 -----------------------
963 Footnotes and citations are supported.
965 There are additional styles ``rststyle-footnote`` and
966 ``rststyle-citation`` for footnotes and citations. See
967 `Footnote and citation styles`_.
969 You may need to modify the citation style to fit the length of your
972 Endnotes -- There are command line options that control whether
973 ``odtwriter`` creates endnotes instead of footnotes. Endnotes
974 appear at the end of the document instead of at the bottom of the
975 page. See flags ``--endnotes-end-doc`` and
976 ``--no-endnotes-end-doc`` in section `Command line options`_.
982 If on the image or the figure directive you provide the scale option
983 but do not provide the width and height options, then ``odtwriter``
984 will attempt to determine the size of the image using the `Python
985 Imaging Library`_ (PIL). If ``odtwriter`` cannot find and import
986 Python Imaging Library, it will raise an exception. If this
987 ocurrs, you can fix it by doing one of the following:
989 - Install the Python Imaging Library or
991 - Remove the ``scale`` option or
993 - Add both the ``width`` and the ``height`` options.
995 So, the rule is: if on any image or figure, you specify scale but
996 not both width and height, you must install the `Python Imaging
999 For more information about PIL, see: `Python Imaging Library`_.
1005 The ``raw`` directive is supported. Use output format type "odt".
1007 You will need to be careful about the formatting of the raw
1008 content. In particular, introduced whitespace might be a problem.
1010 In order to produce content for the raw directive for use by
1011 ``odtwriter``, you might want to extract the file ``content.xml``
1012 from a ``.odt`` file (using some Zip tool), and then clip, paste,
1013 and modify a selected bit of it.
1015 Here is an example::
1019 <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
1020 determined by a lexical scan of the code. If a variable is assigned a
1021 value <text:span text:style-name="rststyle-emphasis">anywhere</text:span> in a scope (specifically within a function or method
1022 body), then that variable is local to that scope. If Python does not
1023 find a variable in the local scope, then it looks next in the global
1024 scope (also sometimes called the module scope) and then in the
1025 built-ins scope. But, the <text:span text:style-name="rststyle-inlineliteral">global</text:span> statement can be used to force
1026 Python to find and use a global variable (a variable defined at top
1027 level in a module) rather than create a local one.</text:p>
1033 ``odtwriter`` supports the ``meta`` directive. Two fields are
1034 recognized: "keywords" and "description". Here is an example::
1037 :keywords: reStructuredText, docutils, formatting
1038 :description lang=en: A reST document, contains formatted
1039 text in a formatted style.
1041 To see the results of the ``meta`` directive in ``oowriter``,
1042 select menu item "File/Properties...", then click on the
1046 Footnote references inside footnotes
1047 ------------------------------------
1051 Get a grip. Be serious. Try a dose of reality.
1053 ``odtwriter`` ignores them.
1055 They cause ``oowriter`` to croak.
1061 The default page size, in documents generated by ``odtwriter`` is
1062 ``Letter``. You can change this (for example to ``A4``) by using a
1063 custom stylesheet. See `Defining and using a custom stylesheet`_
1064 for instructions on how to do this.
1066 On machines which support ``paperconf``, ``odtwriter`` can insert
1067 the default page size for your locale. In order for this to work,
1068 the following conditions must be met:
1070 1. The program ``paperconf`` must be available on your system.
1071 ``odtwriter`` uses ``paperconf -s`` to obtain the paper size.
1072 See ``man paperconf`` for more information.
1074 2. The default page height and width must be removed from the
1075 ``styles.odt`` used to generate the document. A Python script
1076 ``rst2odt_prepstyles.py`` is distributed with ``odtwriter`` and
1077 is installed in the ``bin`` directory. You can remove the page
1078 height and width with something like the following::
1080 $ rst2odt_prepstyles.py styles.odt
1082 .. warning:: If you edit your stylesheet in ``oowriter`` and then
1083 save it, ``oowriter`` automatically inserts a page height and
1084 width in the styles for that (stylesheet) document. If that is
1085 not the page size that you want and you want ``odtwriter`` to
1086 insert a default page size using ``paperconf``, then you will
1087 need to strip the page size from your stylesheet each time you
1088 edit that stylesheet with ``oowriter``.
1092 Custom header/footers: inserting page numbers, date, time, etc
1093 ----------------------------------------------------------------
1095 You can specify custom headers and footers for your document from
1096 the command line. These headers and footers can be used to insert
1097 fields such as the page number, page count, date, time, etc. See
1098 below for a complete list.
1100 To insert a custom header or footer, use the "--custom-odt-header"
1101 or "--custom-odt-footer" command line options. For example, the
1102 following inserts a footer containing the page number and page
1105 $ rst2odt.py --custom-odt-footer="Page %p% of %P%" f1.txt f1.odt
1111 You can use the following field specifiers to insert ``oowriter``
1112 fields in your custom headers and footers:
1115 The current page number.
1118 The number of pages in the document.
1121 The current date in format 12/31/99.
1124 The current date in format 12/31/1999.
1127 The current date in format Dec 31, 1999.
1130 The current date in format December 31, 1999.
1133 The current date in format 1999-12-31.
1136 The current time in format 14:22.
1139 The current time in format 14:22:33.
1142 The current time in format 02:22 PM.
1145 The current time in format 02:22:33 PM.
1148 The author of the document (actually the initial creator).
1154 The document subject.
1157 **Note:** The use of the above field specifiers in the body of your
1158 reStructuredText document is **not** supported, because these
1159 specifiers are not standard across Docutils writers.
1166 Stefan Merten designed and implemented the custom style names
1167 capability. Thank you, Stefan.
1169 Michael Schutte supports the Debian GNU/Linux distribution of
1170 ``odtwriter``. Thank you, Michael, for providing and supporting
1173 Michael Schutte implemented the fix that enables ``odtwriter`` to
1174 pick up the default paper size on platforms where the program
1175 ``paperconf`` is available. Thank you.
1181 http://pygments.pocoo.org/
1184 http://docutils.sourceforge.net/
1186 .. _`Python Imaging Library`:
1187 http://www.pythonware.com/products/pil/
1189 .. _`Open Document at Wikipedia`:
1190 http://en.wikipedia.org/wiki/OpenDocument
1192 .. _`OASIS Open Document Format for Office Applications (OpenDocument) TC`:
1193 http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=office