1 .. include:: ../header.txt
3 =======================
4 ODT Writer for Docutils
5 =======================
8 :Contact: docutils-develop@lists.sourceforge.net
11 :Copyright: This document has been placed in the public domain.
13 :abstract: This document describes the Docutils writer for
14 OpenDocument Text (.odt) documents.
24 The Docutils front end rst2odt.py_ translates reStructuredText_ into an
25 `OpenDocument Text`_ (.odt) file.
26 OpenDocument files `can be opened by most modern office software`__.
27 It is the native file format for LibreOffice_ Writer.
29 __ https://en.wikipedia.org/wiki/OpenDocument#Software
35 In addition to the Docutils standard requirements, ``odtwriter``
38 - Optional -- `Pygments`_ is required if you want syntax
39 highlighting of code in literal blocks. See section `Syntax
42 - Optional -- `Python Imaging Library`_ (PIL) is required if on an
43 image or figure directive, you specify ``scale`` but not ``width``
44 and ``height``. See section `Images and figures`_.
51 Run it from the command line as follows::
53 $ rst2odt.py myinput.txt > myoutput.odt
55 To see usage information and to learn about command line options
56 that you can use, run the following::
62 $ rst2odt.py -s -g python_comments.txt > python_comments.odt
64 $ rst2odt.py --source-url=odtwriter.txt --generator \
65 --stylesheet=/myconfigs/styles.odt odtwriter.txt > odtwriter.odt
71 The options described below can also be set in a `configuration file`_.
72 Use section `[odf_odt writer]`_ to set options specific to the
73 ``odtwriter``. For example::
76 stylesheet: styles1.odt
78 See the `Docutils Configuration`_ document for more information on
79 Docutils configuration files, including locations which are
82 .. _Docutils Configuration: config.html
83 .. _configuration file: config.html#configuration-files
84 .. _[odf_odt writer]: config.html#odf-odt-writer
90 The following command line options are specific to ``odtwriter``:
92 --stylesheet=<URL> Specify a stylesheet URL, used verbatim.
93 Default: writers/odf_odt/styles.odt in the
94 installation directory.
95 --odf-config-file=<file>
96 Specify a configuration/mapping file relative to the
97 current working directory for additional ODF options.
98 In particular, this file may contain a section named
99 "Formats" that maps default style names to names to be
100 used in the resulting output file allowing for
101 adhering to external standards. For more info and the
102 format of the configuration/mapping file, see the
104 --cloak-email-addresses
105 Obfuscate email addresses to confuse harvesters while
106 still keeping email links usable with standards-
108 --no-cloak-email-addresses
109 Do not obfuscate email addresses.
110 --table-border-thickness=TABLE_BORDER_THICKNESS
111 Specify the thickness of table borders in thousands of
113 --add-syntax-highlighting
114 Add syntax highlighting in literal code blocks.
115 --no-syntax-highlighting
116 Do not add syntax highlighting in literal code blocks.
118 --create-sections Create sections for headers. (default)
119 --no-sections Do not create sections for headers.
120 --create-links Create links.
121 --no-links Do not create links. (default)
122 --endnotes-end-doc Generate endnotes at end of document, not footnotes at
124 --no-endnotes-end-doc Generate footnotes at bottom of page, not endnotes at
125 end of document. (default)
126 --generate-list-toc Generate a bullet list table of contents, not an
127 ODF/``oowriter`` table of contents.
128 --generate-oowriter-toc
129 Generate an ODF/``oowriter`` table of contents,
130 not a bullet list. (default) **Note:**
131 ``odtwriter`` is not able to determine page
132 numbers, so you will need to open the
133 generated document in ``oowriter``, then
134 right-click on the table of contents and
135 select "Update" to insert page numbers.
136 --custom-odt-header=CUSTOM_HEADER
137 Specify the contents of an custom header line. See
138 odf_odt writer documentation for details about special
139 field character sequences. See section
140 `Custom header/footers: inserting page numbers, date, time, etc`_
142 --custom-odt-footer=CUSTOM_FOOTER
143 Specify the contents of an custom footer line. See
144 odf_odt writer documentation for details about special
145 field character sequences. See section
146 `Custom header/footers: inserting page numbers, date, time, etc`_
154 ``odtwriter`` uses a number of styles that are defined in
155 ``styles.xml`` in the default ``styles.odt``. This section
156 describes those styles.
158 Note that with the ``--stylesheet`` command line option, you can
159 use either ``styles.odt`` or ``styles.xml``, as described below.
160 Use of ``styles.odt`` is recommended over ``styles.xml``.
162 You can modify the look of documents generated by ``odtwriter`` in
165 - Open (a copy of) ``styles.odt`` in ``OpenOffice/oowriter`` and
166 modify the style you wish to change. Now, save this document,
167 then generate your documents using this modified copy of
170 In my version of ``oowriter``, to modify styles, either (1)
171 press F11 or (2) use menu item "Format/Styles and Formatting",
172 then right-click on the relevant style and select "Modify".
173 Modify the style, then save your document.
175 - Open a document generated by ``odtwriter`` in `oowriter``. Now,
176 edit the style you are interested in modifying. Now, you
177 can extract the styles.xml file from your document and either
178 (1) use this as your default styles file or (2) copy and paste
179 the relevant style definition into your styles.xml.
181 - Extract ``styles.xml`` from ``styles.odt`` using your favorite
182 ``zip/unzip`` tool. Then modify ``styles.xml`` with a text
183 editor. Now re-zip it back into your own ``styles.odt``, or use
184 it directly by specifying it with the ``--stylesheet`` command
185 line option. **Hint:** If you intend to extract ``styles.xml``
186 from an ``.odt`` file (and then "re-zip" it), you should turn off
187 XML optimization/compression in ``oowriter``. In order to this
188 in ``oowriter``, use Tools --> Options... --> Load-Save -->
189 General and turn off "Size optimization for XML format".
191 - Open an empty (or new) document in ``oowriter``. Define all of
192 the styles described in this section. Then, use that document (a
193 .odt file) as your stylesheet. ``odtwriter`` will extract the
194 ``styles.xml`` file from that document and insert it into the
197 - Some combination of the above.
200 Styles used by odtwriter
201 ------------------------
203 This section describes the styles used by ``odtwriter``.
205 Note that we do not describe the "look" of these styles. That can
206 be easily changed by using ``oowriter`` to edit the document
207 ``styles.odt`` (or a copy of it), and modifying any of the styles
210 To change the definition and appearance of these styles, open
211 ``styles.odt`` in ``oowriter`` and open the Styles and Formatting
212 window by using the following menu item::
214 Format --> Styles and Formatting
216 Then, click on the Paragraph Styles button or the Character Styles
217 button at the top of the Styles and Formatting window. You may
218 also need to select "All Styles" from the drop-down selection list
219 at the bottom of the Styles and Formatting window in order to see
220 the styles used by ``odtwriter``.
222 Notice that you can make a copy of file ``styles.odt``, modify it
223 using ``oowriter``, and then use your copy with the
224 ``--stylesheet=<file>`` command line option. Example::
226 $ rst2odt.py --stylesheet=mystyles.odt test2.txt test2.odt
233 The style for attributions, for example, the attribution in a
234 ``.. epigraph::`` directive. Derived from
235 ``rststyle-blockquote``.
243 rststyle-blockquote-bulletitem
244 The style for bullet list items inside block quote.
246 rststyle-blockquote-enumitem
247 The style for enumerated list items inside block quote.
253 An item in an bullet list.
256 The caption in a figure or image. Also see
260 Literal code blocks -- A block of example code. Created with
261 double colon ("::") followed by an indented block or with the
262 ``.. parsed-literal::`` directive. Derived from the
263 ``Preformatted Text`` style in ``oowriter``.
266 An item in an enumerated list.
269 The style for epigraphs, for example, the body of an
270 ``.. epigraph::`` directive. Derived from
271 ``rststyle-blockquote``.
273 rststyle-epigraph-bulletitem
274 The style for bullet list items inside epigraphs.
276 rststyle-epigraph-enumitem
277 The style for enumerated list items inside epigraphs.
280 The style for footers. The footer content originates from the
281 ``..footer::`` directive and in response to the command line
282 flags for generator (``--generator``), date/time generated
283 (``--date`` and ``--time``), and view source link
284 (``--source-link`` and ``--source-url=URL``).
287 The style for headers. The header content originates from the
288 ``..header::`` directive.
291 The style for highlightss, for example, the body of an
292 ``.. highlights::`` directive. Derived from
293 ``rststyle-blockquote``.
295 rststyle-highlights-bulletitem
296 The style for bullet list items inside highlights.
298 rststyle-highlights-enumitem
299 The style for enumerated list items inside highlights.
301 rststyle-horizontalline
302 A horizontal line, e.g. used for transitions.
305 The legend in a figure. See the Docutils figure directive. Also
306 see ``rststyle-caption``.
309 The style for titles of tables. See section `The table
313 Normal text. The style for paragraphs. Derived from the ``Text
314 body`` style in ``oowriter``.
321 Emphasis. Normally rendered as italics.
323 rststyle-inlineliteral
327 Strong emphasis. Normally rendered as boldface.
330 In-line quoted material.
332 rststyle-codeblock-classname
333 Syntax highlighting in literal code blocks -- class names.
335 rststyle-codeblock-comment
336 Syntax highlighting in literal code blocks -- comments.
338 rststyle-codeblock-functionname
339 Syntax highlighting in literal code blocks -- function names.
341 rststyle-codeblock-keyword
342 Syntax highlighting in literal code blocks -- Python language
345 rststyle-codeblock-name
346 Syntax highlighting in literal code blocks -- other names, for
349 rststyle-codeblock-number
350 Syntax highlighting in literal code blocks -- literal numbers,
351 including integers, floats, hex numbers, and octal numbers.
353 rststyle-codeblock-operator
354 Syntax highlighting in literal code blocks -- Python operators.
356 rststyle-codeblock-string
357 Syntax highlighting in literal code blocks -- literal strings.
364 Bullet lists (but not in the table of contents)
366 rststyle-blockquote-bulletlist
367 Bullet lists in block quotes.
369 rststyle-blockquote-enumlist
370 Enumerated lists in block quotes.
372 rststyle-enumlist-arabic
373 Enumerated lists, arabic (but not in the table of contents)
375 rststyle-enumlist-loweralpha
376 Enumerated lists, lower alpha (but not in the table of contents)
378 rststyle-enumlist-lowerroman
379 Enumerated lists, lower roman (but not in the table of contents)
381 rststyle-enumlist-upperalpha
382 Enumerated lists, upper alpha (but not in the table of contents)
384 rststyle-enumlist-upperroman
385 Enumerated lists, upper roman (but not in the table of contents)
387 rststyle-epigraph-bulletlist
388 Bullet lists in epigraphs. See the ``.. epigraph::``
391 rststyle-epigraph-enumlist
392 Enumerated lists in epigraphs. See the ``.. epigraph::``
395 rststyle-highlights-bulletlist
396 Bullet lists in highlights blocks. See the ``.. highlights::``
399 rststyle-highlights-enumlist
400 Enumerated lists in highlights blocks. See the ``.. highlights::``
403 rststyle-tocbulletlist
404 Lists in the table of contents when section numbering is off.
407 Lists in the table of contents when section numbering is on.
413 rststyle-admon-attention-hdr
414 The style for the attention admonition header/title.
416 rststyle-admon-attention-body
417 The style for the attention admonition body/paragraph.
419 rststyle-admon-caution-hdr
420 The style for the caution admonition header/title.
422 rststyle-admon-caution-body
423 The style for the caution admonition body/paragraph.
425 rststyle-admon-danger-hdr
426 The style for the admonition header/title.
428 rststyle-admon-danger-body
429 The style for the danger admonition body/paragraph.
431 rststyle-admon-error-hdr
432 The style for the error admonition header/title.
434 rststyle-admon-error-body
435 The style for the error admonition body/paragraph.
437 rststyle-admon-hint-hdr
438 The style for the hint admonition header/title.
440 rststyle-admon-hint-body
441 The style for the hint admonition body/paragraph.
443 rststyle-admon-hint-hdr
444 The style for the hint admonition header/title.
446 rststyle-admon-hint-body
447 The style for the hint admonition body/paragraph.
449 rststyle-admon-important-hdr
450 The style for the important admonition header/title.
452 rststyle-admon-important-body
453 The style for the important admonition body/paragraph.
455 rststyle-admon-note-hdr
456 The style for the note admonition header/title.
458 rststyle-admon-note-hdr
459 The style for the note admonition header/title.
461 rststyle-admon-tip-body
462 The style for the tip admonition body/paragraph.
464 rststyle-admon-tip-hdr
465 The style for the tip admonition header/title.
467 rststyle-admon-warning-body
468 The style for the warning admonition body/paragraph.
470 rststyle-admon-warning-hdr
471 The style for the warning admonition header/title.
473 rststyle-admon-generic-body
474 The style for the generic admonition body/paragraph.
476 rststyle-admon-generic-hdr
477 The style for the generic admonition header/title.
484 The style for the text in a rubric directive.
486 The rubric directive recognizes a "class" option. If entered,
487 odtwriter uses the value of that option instead of the
488 ``rststyle-rubric`` style. Here is an example which which attaches
489 the ``rststyle-heading1`` style to the generated rubric::
491 .. rubric:: This is my first rubric
492 :class: rststyle-heading1
498 A table style is generated by ``oowriter`` for each table that you
499 create. Therefore, ``odtwriter`` attempts to do something similar.
500 These styles are created in the ``content.xml`` document in the
501 generated ``.odt`` file. These styles have names prefixed with
504 There are two ways in which you can control the styles of your
505 tables: one simple, the other a bit more complex, but more
508 First, you can change the thickness of the borders of all tables
509 generated in a document using the "--table-border-thickness"
512 Second, you can control additional table properties and you can
513 apply different styles to different tables within the same document
514 by customizing and using tables in your stylesheet: ``styles.odt``
515 or whatever you name your copy of it using the --stylesheet command
516 line option. Then, follow these rules to apply a table style to
517 the tables in your document:
519 - The default table style -- Optionally, alter and customize the
520 style applied by default to tables in your document by modifying
521 table "rststyle-table-0" in your stylesheet (``styles.odt`` or a
522 copy). Caution: Do not change the name of this table.
524 - User-created table styles -- Add one or more new table styles to
525 be applied selectively to tables in your document by doing the
528 1. Using ``oowriter``, add a table to your stylesheet and give it
529 a name that starts with the prefix "rststyle-table-", for
530 example "rststyle-table-vegetabledata". Customize the table's
531 border thickness, border color, and table background color.
533 2. In your reStructuredText document, apply your new table style
534 to a specific table by placing the ".. class::" directive
535 immediately before the table, for example::
537 .. class:: rststyle-table-vegetabledata
539 The default table style will be applied to all tables for which you
540 do not specify a style with the ".. class::" directive.
542 Customize the table properties in ``oowriter`` using the table
543 properties dialog for the table (style) that you wish to customize.
545 Note that "--table-border-thickness" command line option overrides
546 the border thickness specified in the stylesheet.
548 The specific properties that you can control with this second
549 method are the following:
551 - Border thickness and border color.
553 - Background color -- When you change the background color of a
554 table to be used as a style (in ``styles.odt`` or whatever you
555 name it), make sure you change the background color for the
556 *table* and *not* for a cell in the table. ``odtwriter`` picks
557 the background color from the table, not from a cell within the
564 The line block styles wrap the various nested levels of line
565 blocks. There is one line block style for each indent level.
568 Line block style for line block with no indent.
571 Line block style for line block indented 1 level.
574 Line block style for line block indented 2 levels.
577 Line block style for line block indented 3 levels.
580 Line block style for line block indented 4 levels.
583 Line block style for line block indented 5 levels.
587 - ``odtwriter`` does not check for a maximum level of indents
588 within line blocks. Therefore, you can define additional line
589 block styles for additional levels if you need them. Define
590 these styles with the names ``rststyle-lineblock7``,
591 ``rststyle-lineblock8``, ...
593 - Since the line block style is used to create indentation, a line
594 block that is inside a block quote will use
595 ``rststyle-lineblock2`` as its first level of indentation.
598 Footnote and citation styles
599 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
602 The style for footnotes. This style affects the footnote
603 content, *not* the footnote reference in the body of the document.
606 The style for citations. This style affects the citation
607 content, *not* the citation reference in the body of the document.
608 You might need to adjust the indentation in this style
609 depending on the length of the label used in your citations.
612 Heading and title styles
613 ~~~~~~~~~~~~~~~~~~~~~~~~~
615 rststyle-heading{1|2|3|4|5}
616 The styles for headings (section titles and sub-titles). Five
617 levels of sub-headings are provided: rststyle-heading1 through
621 The style for the document title.
624 The style for the document sub-title.
627 Image and figure styles
628 ~~~~~~~~~~~~~~~~~~~~~~~~~
631 The style applied to an image, either an image by itself or an
635 The style applied to a figure (actually to the frame that
640 Defining and using a custom stylesheet
641 ---------------------------------------
643 You can create your own custom stylesheet. Here is how:
645 1. Make a copy of ``styles.odt``, which is in the distribution.
647 2. Open your copy of ``styles.odt`` in ``oowriter``. Modify styles
648 in that document. Then, save it.
650 3. When you run ``rst2odt.py``, use the ``--stylesheet`` command
651 line option to use your custom stylesheet. Run ``rst2odt.py
652 --help`` to learn more about these options.
655 Why custom stylesheets
656 ~~~~~~~~~~~~~~~~~~~~~~~
658 Here are a few reasons and ideas:
660 - The `page size`_ is stored in the style sheet. The default page
661 size is ``US Letter``. You can change the page size (for example,
662 to ``A4``) in your custom stylesheet by opening it in
663 ``oowriter``, then clicking on menu: ``Format/Page...``, then
664 clicking on the ``Page`` tab.
667 Defining and using custom style names
668 -------------------------------------
670 [Credits: Stefan Merten designed and implemented the custom style names
671 capability. Thank you, Stefan.]
673 You can also instruct ``odtwriter`` to use style names of your own
677 Why custom style names
678 ~~~~~~~~~~~~~~~~~~~~~~
680 Here are a few reasons and ideas:
682 - Suppose that your organization has a standard set of styles in
683 OOo ``oowriter`` and suppose that the use of these styles is
684 required. You would like to generate ODF documents from
685 reST text files, and you want the generated documents to contain
688 - Suppose that your company or organization has a policy of using a
689 certain MS Word template for some set of documents. You would
690 like to generate ODF documents that use these custom style names,
691 so that you can export these documents from ODF ``oowriter`` to MS
692 Word documents that use these style names.
694 - Suppose that your documents are written in a language other than
695 English. You would like the style names visible in the "Styles
696 and Formatting" window in OOo ``oowriter`` (menu item
697 ``Format/Styles and Formatting``) to be understandable in the
698 language of your users.
700 - ``odtwriter`` maps single asterisks/stars (for example, \*stuff\*)
701 to emphasis and double stars to strong. You'd like to reverse
702 these. Or, you would like to generate headings level 3 and 4
703 where headings level 1 and 2 would normally be produced.
706 How to use custom style names
707 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
709 In order to define custom style names and to generate documents that
710 contain them, do the following:
713 1. Create a configuration file containing a "Formats" section. The
714 configuration file obeys the file format supported by the Python
716 `ConfigParser -- Configuration file parser --
717 https://docs.python.org/3/library/configparser.html
718 <https://docs.python.org/3/library/configparser.html>`_.
720 2. In the "Formats" section of the configuration file, create one
721 option (a name-value pair) for each custom style name that you
722 wish to define. The option name is the standard ``odtwriter``
723 style name (without "rststyle-"), and the value is your custom
724 style name. Here is an example::
728 bulletitem: mybulletitem
734 3. Create a styles document that defines the styles generated by
735 ``odtwriter``. You can create and edit the styles in OOo
736 ``oowriter``. It may be helpful to begin by making a copy of the
737 styles document that is part of the ``odtwriter`` distribution
740 4. When you run ``odtwriter``, specify the ``--odf-config-file``
741 option. You might also want to specify your styles document
742 using the ``--stylesheet`` option in order to include your
743 custom style definitions. For example::
745 rst2odt.py --odf-config-file=mymappingfile.ini \
746 --stylesheet=mystyles.odt mydoc.txt mydoc.odt
752 ``odtwriter`` uses the following Docutils class to provide additional
753 control of the generation of ODF content:
755 - Class ``wrap`` -- Use this to cause the wrapping of text around
756 an image. The default is *not* to wrap text around images.
760 .. image:: images/flower01.png
761 :alt: A bright yellow flower
769 You can use a Docutils custom interpreted text role to attach a
770 character style to an inline area of text. This capability also
771 enables you to attach a new character style (with a new name) that
772 you define yourself. Do this by defining your role in a stylesheet
773 as a character style with "rststyle-" prefixed to your role name,
774 then use the ``role`` directive and inline markup to apply your
777 In order to use this capability, do the following:
779 - Define the character style for your custom role in a stylesheet
780 (a copy of ``styles.odt``) with the prefix "rststyle-".
781 Remember: (1) If the name of your custom role is "pretty", then
782 define a character style named "rststyle-pretty". (2) Define the
783 style as a *character* style, and *not*, for example as a
786 - Declare your role in the source reStructuredText document in a
787 ``role`` directive. Example::
791 - Use inline markup to apply your role to text. Example::
793 We have :pretty:`very nice` apples.
795 Here is another example::
799 Here is some :fancy:`pretty text` that looks fancy.
801 For more on roles see:
802 `Custom Interpreted Text Roles --
803 https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-text-roles
804 <https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-text-roles>`_.
806 **Note:** The ability to base a role on another existing role is
807 *not* supported by ``odtwriter``.
810 Hints and Suggestions and Features
811 ==================================
816 The ``..contents::`` directive causes ``odtwriter`` to generate
819 1. A static, outline style table of contents, if the
820 ``--generate-list-toc`` command line option is specified, or
822 2. An ODF/``oowriter`` style table of contents containing
823 dynamically updated page numbers and with the formatting control
824 that ``oowriter`` gives you. This is the default, or use the
825 command line option ``--generate-list-toc``. **Note:**
826 ``odtwriter`` is not able to determine page numbers, so you will
827 need to open the generated document in ``oowriter``, then
828 right-click on the table of contents and select "Update" to
829 insert correct page numbers.
835 ``odtwriter`` can add syntax highlighting to code in code
836 blocks. In order to activate this, do all of the following:
838 1. Install `Pygments`_ and ...
840 2. Use the command line option ``--add-syntax-highlighting``.
843 $ rst2odt.py --add-syntax-highlight test.txt test.odt
845 The following styles are defined in styles.odt and are used for
846 literal code blocks and syntax highlighting:
850 - rststyle-codeblock -- The style for the code block as a whole.
854 - rststyle-codeblock-classname -- class names.
856 - rststyle-codeblock-comment -- comments.
858 - rststyle-codeblock-functionname -- function names.
860 - rststyle-codeblock-keyword -- Python language keywords.
862 - rststyle-codeblock-name -- other names, for example,
865 - rststyle-codeblock-number -- literal numbers, including
866 integers, floats, hex numbers, and octal numbers.
868 - rststyle-codeblock-operator -- Python operators.
870 - rststyle-codeblock-string -- literal strings.
872 Each of the above styles has a default appearance that is defined
873 in ``styles.odt``. To change that definition and appearance, open
874 ``styles.odt`` in ``oowriter`` and use menu item::
876 Format --> Styles and Formatting
878 Then, click on the Paragraph Styles button or the Character Styles
879 button at the top of the Styles and Formatting window. You may
880 also need to select "All Styles" from the drop-down selection list
881 at the bottom of the Styles and Formatting window.
885 The container directive
886 -----------------------
888 There is limited support for the ``container`` directive. The
889 limitations and rules for the container directive are the following:
891 - Only the first class in the list of classes (arguments) is used.
893 - That class/style must be a paragraph style and not (for example) a
896 - The style/class given to the container directive will have a
897 "rststyle-" prefix in the odt file.
901 .. container:: style-1 style-2 style-3
905 - Only ``style-1`` is used; ``style-2`` and ``style-3`` are ignored.
907 - ``rststyle-style-1`` must be defined. It should be an existing,
908 predefined style, or you should define it in your stylesheet
909 (``styles.odt`` or the argument to the ``--stylesheet`` command
912 - ``rststyle-style-1`` must be a paragraph style.
914 To define a paragraph style, use the following menu item in
917 Format --> Styles and Formatting
919 Then, click on the Paragraph Styles button.
921 The following example attaches the ``rststyle-heading2`` style (a
922 predefined style) to each paragraph/line in the container::
924 .. container:: heading2
930 More information on how to define a new style (for example, in your
931 ``styles.odt``) can be found in section
932 `Defining and using custom style names`_.
939 The ``table`` directive can be used to add a title to a table.
942 .. table:: A little test table
944 =========== =============
946 =========== =============
949 =========== =============
951 The above will insert the title "A little test table" at the top of the
952 table. You can modify the appearance of the title by modifying the
953 paragraph style ``rststyle-table-title``.
956 Footnotes and citations
957 -----------------------
959 Footnotes and citations are supported.
961 There are additional styles ``rststyle-footnote`` and
962 ``rststyle-citation`` for footnotes and citations. See
963 `Footnote and citation styles`_.
965 You may need to modify the citation style to fit the length of your
968 Endnotes -- There are command line options that control whether
969 ``odtwriter`` creates endnotes instead of footnotes. Endnotes
970 appear at the end of the document instead of at the bottom of the
971 page. See flags ``--endnotes-end-doc`` and
972 ``--no-endnotes-end-doc`` in section `Command line options`_.
978 If on the image or the figure directive you provide the scale option
979 but do not provide the width and height options, then ``odtwriter``
980 will attempt to determine the size of the image using the `Python
981 Imaging Library`_ (PIL). If ``odtwriter`` cannot find and import
982 Python Imaging Library, it will raise an exception. If this
983 ocurrs, you can fix it by doing one of the following:
985 - Install the Python Imaging Library or
987 - Remove the ``scale`` option or
989 - Add both the ``width`` and the ``height`` options.
991 So, the rule is: if on any image or figure, you specify scale but
992 not both width and height, you must install the `Python Imaging
995 For more information about PIL, see: `Python Imaging Library`_.
1001 The ``raw`` directive is supported. Use output format type "odt".
1003 You will need to be careful about the formatting of the raw
1004 content. In particular, introduced whitespace might be a problem.
1006 In order to produce content for the raw directive for use by
1007 ``odtwriter``, you might want to extract the file ``content.xml``
1008 from a ``.odt`` file (using some Zip tool), and then clip, paste,
1009 and modify a selected bit of it.
1011 Here is an example::
1015 <text:p text:style-name="rststyle-textbody">Determining
1016 <text:span text:style-name="rststyle-emphasis">which</text:span>
1017 namespace a name is in is static. It can be determined by a
1018 lexical scan of the code. If a variable is assigned a value
1019 <text:span text:style-name="rststyle-emphasis">anywhere</text:span>
1020 in a scope (specifically within a function or method body),
1021 then that variable is local to that scope. If Python does
1022 not find a variable in the local scope, then it looks next
1023 in the global scope (also sometimes called the module scope)
1024 and then in the built-ins scope. But, the
1025 <text:span text:style-name="rststyle-inlineliteral">global</text:span>
1026 statement can be used to force Python to find and use a global
1027 variable (a variable defined at top level in a module) rather
1028 than create a local one.</text:p>
1034 ``odtwriter`` supports the ``meta`` directive. "keywords"
1035 and "description" are set in their respective odt fields.
1036 Other meta fields are set as "Custom Properties".
1037 Here is an example::
1040 :keywords: reStructuredText, docutils, formatting
1041 :description lang=en: A reST document, contains formatted
1042 text in a formatted style.
1045 To see the results of the ``meta`` directive in ``oowriter``,
1046 select menu item "File/Properties...", then click on the
1047 "Description" tab ("keywords" and "description" fields) and the
1048 "Custom Properties" tab.
1051 Footnote references inside footnotes
1052 ------------------------------------
1056 Get a grip. Be serious. Try a dose of reality.
1058 ``odtwriter`` ignores them.
1060 They cause ``oowriter`` to croak.
1066 The default page size, in documents generated by the ODT writer is
1067 "US Letter". You can change this (for example to ``A4``) by using a
1068 custom stylesheet. See `Defining and using a custom stylesheet`_
1069 for instructions on how to do this.
1071 On machines which support ``paperconf``, the ODT writer can insert
1072 the default page size for your locale. In order for this to work,
1073 the following conditions must be met:
1075 1. The program ``paperconf`` must be available on your system.
1076 ``odtwriter`` uses ``paperconf -s`` to obtain the paper size.
1077 See ``man paperconf`` for more information.
1079 2. The page height and width settings must be absent from the stylesheet
1080 used to generate the document.
1082 You can use the Python script ``prepstyles.py`` distributed with
1083 Docutils to remove the page height and width settings from a
1084 stylesheet file ``STYLES.odt`` with ::
1086 $ python3 -m docutils.writers.odf_odt.prepstyles STYLES.odt
1088 (the command changed in Docutils 0.20.1).
1090 .. warning:: If you edit your stylesheet in ``oowriter`` and then
1091 save it, ``oowriter`` automatically inserts a page height and
1092 width in the styles for that (stylesheet) document. If that is
1093 not the page size that you want and you want ``odtwriter`` to
1094 insert a default page size using ``paperconf``, then you will
1095 need to strip the page size from your stylesheet each time you
1096 edit that stylesheet with ``oowriter``.
1100 Custom header/footers: inserting page numbers, date, time, etc
1101 ----------------------------------------------------------------
1103 You can specify custom headers and footers for your document from
1104 the command line. These headers and footers can be used to insert
1105 fields such as the page number, page count, date, time, etc. See
1106 below for a complete list.
1108 To insert a custom header or footer, use the "--custom-odt-header"
1109 or "--custom-odt-footer" command line options. For example, the
1110 following inserts a footer containing the page number and page
1113 $ rst2odt.py --custom-odt-footer="Page %p% of %P%" f1.txt f1.odt
1119 You can use the following field specifiers to insert ``oowriter``
1120 fields in your custom headers and footers:
1123 The current page number.
1126 The number of pages in the document.
1129 The current date in format 12/31/99.
1132 The current date in format 12/31/1999.
1135 The current date in format Dec 31, 1999.
1138 The current date in format December 31, 1999.
1141 The current date in format 1999-12-31.
1144 The current time in format 14:22.
1147 The current time in format 14:22:33.
1150 The current time in format 02:22 PM.
1153 The current time in format 02:22:33 PM.
1156 The author of the document (actually the initial creator).
1162 The document subject.
1165 **Note:** The use of the above field specifiers in the body of your
1166 reStructuredText document is **not** supported, because these
1167 specifiers are not standard across Docutils writers.
1174 Stefan Merten designed and implemented the custom style names
1175 capability. Thank you, Stefan.
1177 Michael Schutte supports the Debian GNU/Linux distribution of
1178 ``odtwriter``. Thank you, Michael, for providing and supporting
1181 Michael Schutte implemented the fix that enables ``odtwriter`` to
1182 pick up the default paper size on platforms where the program
1183 ``paperconf`` is available. Thank you.
1188 tools.html#rst2odt-py
1189 .. _reStructuredText:
1190 ../ref/rst/restructuredtext.html
1191 .. _`OpenDocument Text`:
1192 https://en.wikipedia.org/wiki/OpenDocument
1194 https://libreoffice.org/
1196 https://pygments.org/
1197 .. _`Python Imaging Library`:
1198 https://en.wikipedia.org/wiki/Python_Imaging_Library