13.12.12 Advanced topics in ODT export

The ODT export back-end has extensive features useful for power users and frequent uses of ODT formats.

Configuring a document converter

The ODT export back-end works with popular converters with little or no extra configuration. See Extending ODT export. The following is for unsupported converters or tweaking existing defaults.

Register the converter ¶

Add the name of the converter to the org-odt-convert-processes variable. Note that it also requires how the converter is invoked on the command line. See the variable’s docstring for details.

Configure its capabilities ¶

Specify which formats the converter can handle by customizing the variable org-odt-convert-capabilities. Use the entry for the default values in this variable for configuring the new converter. Also see its docstring for details.

Choose the converter ¶

Select the newly added converter as the preferred one by customizing the option org-odt-convert-process.

Working with OpenDocument style files

This section explores the internals of the ODT exporter; the means by which it produces styled documents; the use of automatic and custom OpenDocument styles.

The ODT exporter relies on two files for generating its output. These files are bundled with the distribution under the directory pointed to by the variable org-odt-styles-dir. The two files are:

‘OrgOdtStyles.xml’

This file contributes to the ‘styles.xml’ file of the final ODT document. This file gets modified for the following purposes:

1. To control outline numbering based on user settings;
2. To add styles generated by ‘htmlfontify.el’ for fontification of code blocks.

‘OrgOdtContentTemplate.xml’

This file contributes to the ‘content.xml’ file of the final ODT document. The contents of the Org outline are inserted between the ‘<office:text>’ … ‘</office:text>’ elements of this file.

Apart from serving as a template file for the final ‘content.xml’, the file serves the following purposes:

1. It contains automatic styles for formatting of tables which are referenced by the exporter;
2. It contains ‘<text:sequence-decl>’ … ‘</text:sequence-decl>’ elements that control numbering of tables, images, equations, and similar entities.

The following two variables control the location from where the ODT exporter picks up the custom styles and content template files. Customize these variables to override the factory styles used by the exporter.

org-odt-styles-file

The ODT export back-end uses the file pointed to by this variable, such as ‘styles.xml’, for the final output. It can take one of the following values:

‘FILE.xml’

Use this file instead of the default ‘styles.xml’

‘FILE.odt’ or ‘FILE.ott’

Use the ‘styles.xml’ contained in the specified OpenDocument Text or Template file

‘FILE.odt’ or ‘FILE.ott’ and a subset of included files

Use the ‘styles.xml’ contained in the specified OpenDocument Text or Template file. Additionally extract the specified member files and embed those within the final ODT document.

Use this option if the ‘styles.xml’ file references additional files like header and footer images.

nil

Use the default ‘styles.xml’.

org-odt-content-template-file

Use this variable to specify the blank ‘content.xml’ used in the final output.

Creating one-off styles

The ODT export back-end can read embedded raw OpenDocument XML from the Org file. Such direct formatting is useful for one-off instances.

Embedding ODT tags as part of regular text

Enclose OpenDocument syntax in ‘@@odt:...@@’ for inline markup. For example, to highlight a region of text do the following:

@@odt:<text:span text:style-name="Highlight">This is highlighted
text</text:span>@@.  But this is regular text.

Hint: To see the above example in action, edit the ‘styles.xml’ (see Factory styles) and add a custom Highlight style as shown below:

<style:style style:name="Highlight" style:family="text">
  <style:text-properties fo:background-color="#ff0000"/>
</style:style>

Embedding a one-line OpenDocument XML ¶

The ODT export back-end can read one-liner options with ‘#+ODT:’ in the Org file. For example, to force a page break:

#+ODT: <text:p text:style-name="PageBreak"/>

Hint: To see the above example in action, edit your ‘styles.xml’ (see Factory styles) and add a custom ‘PageBreak’ style as shown below.

<style:style style:name="PageBreak" style:family="paragraph"
             style:parent-style-name="Text_20_body">
  <style:paragraph-properties fo:break-before="page"/>
</style:style>

Embedding a block of OpenDocument XML

The ODT export back-end can also read ODT export blocks for OpenDocument XML. Such blocks use the ‘#+BEGIN_EXPORT odt’ … ‘#+END_EXPORT’ constructs.

For example, to create a one-off paragraph that uses bold text, do the following:

#+BEGIN_EXPORT odt
  <text:p text:style-name="Text_20_body_20_bold">
  This paragraph is specially formatted and uses bold text.
  </text:p>
#+END_EXPORT

Customizing tables in ODT export

Override the default table format by specifying a custom table style with the ‘#+ATTR_ODT’ line. For a discussion on default formatting of tables, see Tables in ODT export.

This feature closely mimics the way table templates are defined in the OpenDocument-v1.2 specification¹³⁸.

For quick preview of this feature, install the settings below and export the table that follows:

(setq org-export-odt-table-styles
      (append org-export-odt-table-styles
              '(("TableWithHeaderRowAndColumn" "Custom"
                 ((use-first-row-styles . t)
                  (use-first-column-styles . t)))
                ("TableWithFirstRowandLastRow" "Custom"
                 ((use-first-row-styles . t)
                  (use-last-row-styles . t))))))

#+ATTR_ODT: :style TableWithHeaderRowAndColumn
| Name  | Phone | Age |
| Peter |  1234 |  17 |
| Anna  |  4321 |  25 |

The example above used ‘Custom’ template and installed two table styles ‘TableWithHeaderRowAndColumn’ and ‘TableWithFirstRowandLastRow’. Important: The OpenDocument styles needed for producing the above template were pre-defined. They are available in the section marked ‘Custom Table Template’ in ‘OrgOdtContentTemplate.xml’ (see Factory styles). For adding new templates, define new styles there.

To use this feature proceed as follows:

1. Create a table template¹³⁹.

   A table template is set of ‘table-cell’ and ‘paragraph’ styles for each of the following table cell categories:

   • Body
   • First column
   • Last column
   • First row
   • Last row
   • Even row
   • Odd row
   • Even column
   • Odd Column

   The names for the above styles must be chosen based on the name of the table template using a well-defined convention.

   The naming convention is better illustrated with an example. For a table template with the name ‘Custom’, the needed style names are listed in the following table.

   Cell type	Cell style	Paragraph style
   Body	‘CustomTableCell’	‘CustomTableParagraph’
   First column	‘CustomFirstColumnTableCell’	‘CustomFirstColumnTableParagraph’
   Last column	‘CustomLastColumnTableCell’	‘CustomLastColumnTableParagraph’
   First row	‘CustomFirstRowTableCell’	‘CustomFirstRowTableParagraph’
   Last row	‘CustomLastRowTableCell’	‘CustomLastRowTableParagraph’
   Even row	‘CustomEvenRowTableCell’	‘CustomEvenRowTableParagraph’
   Odd row	‘CustomOddRowTableCell’	‘CustomOddRowTableParagraph’
   Even column	‘CustomEvenColumnTableCell’	‘CustomEvenColumnTableParagraph’
   Odd column	‘CustomOddColumnTableCell’	‘CustomOddColumnTableParagraph’

   To create a table template with the name ‘Custom’, define the above styles in the ‘<office:automatic-styles>’ … ‘</office:automatic-styles>’ element of the content template file (see Factory styles).

2. Define a table style¹⁴⁰.

   To define a table style, create an entry for the style in the variable org-odt-table-styles and specify the following:

   • the name of the table template created in step (1),
   • the set of cell styles in that template that are to be activated.

   For example, the entry below defines two different table styles ‘TableWithHeaderRowAndColumn’ and ‘TableWithFirstRowandLastRow’ based on the same template ‘Custom’. The styles achieve their intended effect by selectively activating the individual cell styles in that template.

   (setq org-export-odt-table-styles
         (append org-export-odt-table-styles
                 '(("TableWithHeaderRowAndColumn" "Custom"
                    ((use-first-row-styles . t)
                     (use-first-column-styles . t)))
                   ("TableWithFirstRowandLastRow" "Custom"
                    ((use-first-row-styles . t)
                     (use-last-row-styles . t))))))
   

3. Associate a table with the table style.

   To do this, specify the table style created in step (2) as part of the ‘ATTR_ODT’ line as shown below.

   #+ATTR_ODT: :style TableWithHeaderRowAndColumn
   | Name  | Phone | Age |
   | Peter |  1234 |  17 |
   | Anna  |  4321 |  25 |
   

Validating OpenDocument XML

Sometimes ODT format files may not open due to ‘.odt’ file corruption. To verify if such a file is corrupt, validate it against the OpenDocument Relax NG Compact (RNC) syntax schema. But first the ‘.odt’ files have to be decompressed using ‘zip’. Note that ‘.odt’ files are ZIP archives: (emacs)File Archives. The contents of ODT files are in XML. For general help with validation—and schema-sensitive editing—of XML files: (nxml-mode)Introduction.

Customize org-odt-schema-dir to point to a directory with OpenDocument RNC files and the needed schema-locating rules. The ODT export back-end takes care of updating the rng-schema-locating-files.