Next: , Previous: , Up: OpenDocument Text Exporter for Emacs’ Org Mode   [Contents][Index]

14 Advanced topics in ODT export

If you rely heavily on ODT export, you may want to exploit the full set of features that the exporter offers. This section describes features that would be of interest to power users.

14.1 Configuring a document converter

The ODT exporter can work with popular converters with little or no extra configuration from your side. See Extending ODT export. If you are using a converter that is not supported by default or if you would like to tweak the default converter settings, proceed as below.

  1. Register the converter

    Name your converter and add it to the list of known converters by customizing the variable ‘org-odt-convert-processes’. Also specify how the converter can be invoked via command-line to effect the conversion.

  2. Configure its capabilities

    Specify the set of formats the converter can handle by customizing the variable ‘org-odt-convert-capabilities’. Use the default value for this variable as a guide for configuring your converter. As suggested by the default setting, you can specify the full set of formats supported by the converter and not limit yourself to specifying formats that are related to just the OpenDocument Text format.

  3. Choose the converter

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

14.2 Working with OpenDocument style files

This section explores the internals of the ODT exporter and the means by which it produces styled documents. Read this section if you are interested in exploring the automatic and custom OpenDocument styles used by the exporter.

14.2.1 Factory 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 how various entities - tables, images, equations etc - are numbered.

14.2.2 Overriding factory styles

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

‘org-odt-styles-file’

Use this variable to specify the ‘styles.xml’ that will be used in the final output. You can specify one of the following values:

  1. A ‘styles.xml’ file

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

  2. A ‘.odt’ or ‘.ott’ file

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

  3. A ‘.odt’ or ‘.ott’ file and a subset of files contained within them

    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.

  4. ‘nil’

    Use the default ‘styles.xml’

‘org-odt-content-template-file’

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

14.3 Creating one-off styles

There are times when you would want one-off formatting in the exported document. You can achieve this by embedding raw OpenDocument XML in the Org file. The use of this feature is better illustrated with couple of examples.

  1. Embedding ODT tags as part of regular text

    You can include simple OpenDocument tags by prefixing them with ‘@’. For example, to highlight a region of text do the following: 

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

    Hint: To see the above example in action, edit your ‘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>
  2. Embedding a one-line OpenDocument XML

    You can add a simple OpenDocument one-liner using the ‘#+ODT:’ directive. For example, to force a page break do the following: 

    #+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>
  3. Embedding a block of OpenDocument XML

    You can add a large block of OpenDocument XML using the ‘#+BEGIN_ODT’ … ‘#+END_ODT’ construct.

    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 ODT

14.4 Customizing tables in ODT export

You can override the default formatting of the table 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.14

14.4.1 Custom table styles - an illustration

To have a quick preview of this feature, install the below setting and export the table that follows. 

(setq org-odt-table-styles
      (append org-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 |

In the above example, you used a template named ‘Custom’ and installed two table styles with the names ‘TableWithHeaderRowAndColumn’ and ‘TableWithFirstRowandLastRow’. (Important: The OpenDocument styles needed for producing the above template have been pre-defined for you. These styles are available under the section marked ‘Custom Table Template’ in OrgOdtContentTemplate.xml (see Factory styles). If you need additional templates you have to define these styles yourselves.

14.4.2 Custom table styles - the nitty-gritty

To use this feature proceed as follows:

  1. Create a table template15

    A table template is nothing but a 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.

    Table cell type‘table-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 style16

    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-odt-table-styles
      (append org-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 |

14.5 Validating OpenDocument XML

Occasionally, you will discover that the document created by the ODT exporter cannot be opened by your favorite application. One of the common reasons for this is that the ‘.odt’ file is corrupt. In such cases, you may want to validate the document against the OpenDocument RELAX NG Compact Syntax (RNC) schema.

For de-compressing the ‘.odt’ file17: See (emacs)File Archives. For general help with validation (and schema-sensitive editing) of XML files: See (nxml-mode)Introduction.

If you have ready access to OpenDocument ‘.rnc’ files and the needed schema-locating rules in a single folder, you can customize the variable ‘org-odt-schema-dir’ to point to that directory. The ODT exporter will take care of updating the ‘rng-schema-locating-files’ for you.

Footnotes

(14)

OpenDocument-v1.2 Specification

(15)

See the ‘<table:table-template>’ element of the OpenDocument-v1.2 specification

(16)

See the attributes ‘table:template-name’, ‘table:use-first-row-styles’, ‘table:use-last-row-styles’, ‘table:use-first-column-styles’, ‘table:use-last-column-styles’, ‘table:use-banding-rows-styles’, and ‘table:use-banding-column-styles’ of the ‘<table:table>’ element in the OpenDocument-v1.2 specification

(17)

‘.odt’ files are nothing but ‘zip’ archives

Next: , Previous: , Up: OpenDocument Text Exporter for Emacs’ Org Mode   [Contents][Index]