\input texinfo
@c %**start of header
@setfilename ../../info/org-odt
@settitle The Org/OpenDocument Text Exporter Manual
@set VERSION 7.7
@set DATE October 2011
@c Use proper quote and backtick for code sections in PDF output
@c Cf. Texinfo manual 14.2
@set txicodequoteundirected
@set txicodequotebacktick
@c Version and Contact Info
@set MAINTAINERSITE @uref{http://orgmode.org,maintainers webpage}
@set AUTHOR Jambunathan K
@set MAINTAINER Jambunathan K
@set MAINTAINEREMAIL @email{kjambunathan at gmail dot com}
@set MAINTAINERCONTACT @uref{mailto:kjambunathan at gmail dot com,contact the maintainer}
@c %**end of header
@finalout
@c -----------------------------------------------------------------------------
@c Macro definitions for commands and keys
@c =======================================
@c The behavior of the key/command macros will depend on the flag cmdnames
@c When set, commands names are shown. When clear, they are not shown.
@set cmdnames
@c Below we define the following macros for Org key tables:
@c orgkey{key} A key item
@c orgcmd{key,cmd} Key with command name
@c xorgcmd{key,cmmand} Key with command name as @itemx
@c orgcmdnki{key,cmd} Like orgcmd, but do not index the key
@c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key
@c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or"
@c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but
@c different functions, so format as @itemx
@c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short"
@c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx
@c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands
@c a key but no command
@c Inserts: @item key
@macro orgkey{key}
@kindex \key\
@item @kbd{\key\}
@end macro
@macro xorgkey{key}
@kindex \key\
@itemx @kbd{\key\}
@end macro
@c one key with a command
@c Inserts: @item KEY COMMAND
@macro orgcmd{key,command}
@ifset cmdnames
@kindex \key\
@findex \command\
@iftex
@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
@end iftex
@ifnottex
@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
@end ifnottex
@end ifset
@ifclear cmdnames
@kindex \key\
@item @kbd{\key\}
@end ifclear
@end macro
@c One key with one command, formatted using @itemx
@c Inserts: @itemx KEY COMMAND
@macro xorgcmd{key,command}
@ifset cmdnames
@kindex \key\
@findex \command\
@iftex
@itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
@end iftex
@ifnottex
@itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
@end ifnottex
@end ifset
@ifclear cmdnames
@kindex \key\
@itemx @kbd{\key\}
@end ifclear
@end macro
@c one key with a command, bit do not index the key
@c Inserts: @item KEY COMMAND
@macro orgcmdnki{key,command}
@ifset cmdnames
@findex \command\
@iftex
@item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
@end iftex
@ifnottex
@item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
@end ifnottex
@end ifset
@ifclear cmdnames
@item @kbd{\key\}
@end ifclear
@end macro
@c one key with a command, and special text to replace key in item
@c Inserts: @item TEXT COMMAND
@macro orgcmdtkc{text,key,command}
@ifset cmdnames
@kindex \key\
@findex \command\
@iftex
@item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
@end iftex
@ifnottex
@item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
@end ifnottex
@end ifset
@ifclear cmdnames
@kindex \key\
@item @kbd{\text\}
@end ifclear
@end macro
@c two keys with one command
@c Inserts: @item KEY1 or KEY2 COMMAND
@macro orgcmdkkc{key1,key2,command}
@ifset cmdnames
@kindex \key1\
@kindex \key2\
@findex \command\
@iftex
@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
@end iftex
@ifnottex
@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
@end ifnottex
@end ifset
@ifclear cmdnames
@kindex \key1\
@kindex \key2\
@item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
@end ifclear
@end macro
@c Two keys with one command name, but different functions, so format as
@c @itemx
@c Inserts: @item KEY1
@c @itemx KEY2 COMMAND
@macro orgcmdkxkc{key1,key2,command}
@ifset cmdnames
@kindex \key1\
@kindex \key2\
@findex \command\
@iftex
@item @kbd{\key1\}
@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
@end iftex
@ifnottex
@item @kbd{\key1\}
@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
@end ifnottex
@end ifset
@ifclear cmdnames
@kindex \key1\
@kindex \key2\
@item @kbd{\key1\}
@itemx @kbd{\key2\}
@end ifclear
@end macro
@c Same as previous, but use "or short"
@c Inserts: @item KEY1 or short KEY2 COMMAND
@macro orgcmdkskc{key1,key2,command}
@ifset cmdnames
@kindex \key1\
@kindex \key2\
@findex \command\
@iftex
@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
@end iftex
@ifnottex
@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
@end ifnottex
@end ifset
@ifclear cmdnames
@kindex \key1\
@kindex \key2\
@item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
@end ifclear
@end macro
@c Same as previous, but use @itemx
@c Inserts: @itemx KEY1 or short KEY2 COMMAND
@macro xorgcmdkskc{key1,key2,command}
@ifset cmdnames
@kindex \key1\
@kindex \key2\
@findex \command\
@iftex
@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
@end iftex
@ifnottex
@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
@end ifnottex
@end ifset
@ifclear cmdnames
@kindex \key1\
@kindex \key2\
@itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
@end ifclear
@end macro
@c two keys with two commands
@c Inserts: @item KEY1 COMMAND1
@c @itemx KEY2 COMMAND2
@macro orgcmdkkcc{key1,key2,command1,command2}
@ifset cmdnames
@kindex \key1\
@kindex \key2\
@findex \command1\
@findex \command2\
@iftex
@item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
@itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
@end iftex
@ifnottex
@item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
@itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
@end ifnottex
@end ifset
@ifclear cmdnames
@kindex \key1\
@kindex \key2\
@item @kbd{\key1\}
@itemx @kbd{\key2\}
@end ifclear
@end macro
@c -----------------------------------------------------------------------------
@iftex
@c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
@end iftex
@c Subheadings inside a table.
@macro tsubheading{text}
@ifinfo
@subsubheading \text\
@end ifinfo
@ifnotinfo
@item @b{\text\}
@end ifnotinfo
@end macro
@copying
This manual is for Org version @value{VERSION}.
Copyright @copyright{} 2004-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below. A copy of the license
is included in the section entitled ``GNU Free Documentation License.''
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
This document is part of a collection distributed under the GNU Free
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
@end quotation
@end copying
@dircategory Emacs
@direntry
* Org Mode: (org). Outline-based notes management and organizer
@end direntry
@titlepage
@title The Org/OpenDocument Text Exporter Manual
@subtitle Release @value{VERSION}
@author by Jambunathan K
@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@c Output the table of contents at the beginning.
@contents
@ifnottex
@node Top, Exporting, (dir), (dir)
@top Org/OpenDocument Text Exporter Mode Manual
@insertcopying
@end ifnottex
@menu
* Exporting::
* Main Index::
* Key Index::
* Command and Function Index::
* Variable Index::
@end menu
@node Exporting, Main Index, Top, Top
@chapter Exporting
@cindex exporting
Org-mode documents can be exported into a variety of other formats. For
printing and sharing of notes, ASCII export produces a readable and simple
version of an Org file. HTML export allows you to publish a notes file on
the web, while the XOXO format provides a solid base for exchange with a
broad range of other applications. @LaTeX{} export lets you use Org-mode and
its structured editing functions to easily create @LaTeX{} files. DocBook
export makes it possible to convert Org files to many other formats using
DocBook tools. OpenDocument Text(@acronym{ODT}) export allows seamless
colloboration across organizational boundaries. For project management you
can create gantt and resource charts by using TaskJuggler export. To
incorporate entries with associated times like deadlines or appointments into
a desktop calendar program like iCal, Org-mode can also produce extracts in
the iCalendar format. Currently Org-mode only supports export, not import of
these different formats.
Org supports export of selected regions when @code{transient-mark-mode} is
enabled (default in Emacs 23).
@menu
* OpenDocument Text export:: Exporting to OpenDocument Text
@end menu
@node OpenDocument Text export, , Exporting, Exporting
@section OpenDocument Text export
@cindex K, Jambunathan
@cindex ODT
@cindex OpenDocument
@cindex export, OpenDocument
@cindex LibreOffice
@cindex org-odt.el
@cindex org-modules
Orgmode@footnote{Versions 7.6 or later} supports export to OpenDocument
Text(@acronym{ODT}) format using @file{org-odt.el} module. Documents created
by this exporter use @cite{OpenDocument-v1.2
specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
are compatible with LibreOffice 3.4.
@menu
* Installing ODT exporter:: How to install @acronym{ODT} exporter
* @acronym{ODT} export commands:: How to invoke @acronym{ODT} export
* Exporting and Converting to Other formats::
* Applying Custom Styles:: How to apply custom styles to the output
* Links in @acronym{ODT} export:: How links will be interpreted and formatted
* Tables in @acronym{ODT} export:: How Tables are exported
* Images in @acronym{ODT} export:: How to insert images
* Math formatting in @acronym{ODT} export:: How @LaTeX{} fragments are formatted
* Literal Examples in @acronym{ODT} export:: How source and example blocks are formatted
* Working with raw OpenDocument XML::
* Additional Documentation:: Where to find more information
@end menu
@node Installing ODT exporter, @acronym{ODT} export commands, OpenDocument Text export, OpenDocument Text export
@subsection Installing @acronym{ODT} exporter
@subsubheading Obtaining and Installing @acronym{ODT} exporter
The @acronym{ODT} exporter can be enabled in one of the following ways based
on your mode of installation.
@enumerate
@item
If you have downloaded Org, either as a distribution @file{.zip} or
@file{.tar} file, or as a @file{git} archive, add the @file{contrib} subdir
to @code{load-path} and customize variable @code{org-modules} to include the
@samp{odt} option.
@item
If you are using Org that comes bundled with Emacs, then you can install the
@samp{org-odt} package using the package manager (@inforef{Packages,,emacs}).
@end enumerate
@subsubheading Pre-requisites for @acronym{ODT} exporter
@cindex zip
@acronym{ODT} exporter relies on @file{zip} program to create the final
output. Check the availability of this program before proceeding further.
@node @acronym{ODT} export commands, Exporting and Converting to Other formats, Installing ODT exporter, OpenDocument Text export
@subsection @acronym{ODT} export commands
@subsubheading Exporting to @acronym{ODT}
@anchor{x-export-to-odt}
@cindex region, active
@cindex active region
@cindex transient-mark-mode
@table @kbd
@orgcmd{C-c C-e o,org-export-as-odt}
@cindex property EXPORT_FILE_NAME
Export as OpenDocument Text file.
@vindex org-export-odt-preferred-output-format
If @code{org-export-odt-preferred-output-format} is specfied, automatically
convert the exported file to that format.
@xref{x-export-to-other-formats,,Automatically Exporting to Other formats}.
For an Org file, @file{myfile.org}, the @acronym{ODT} file will be
@file{myfile.odt}. The file will be overwritten without warning. If there
is an active region@footnote{This requires @code{transient-mark-mode} to be
turned on}, only the region will be exported. If the selected region is a
single tree@footnote{To select the current subtree, use @kbd{C-c @@}.}, the
tree head will become the document title. If the tree head entry has, or
inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the
export.
@orgcmd{C-c C-e O,org-export-as-odt-and-open}
Export as OpenDocument Text file and open the resulting file.
@vindex org-export-odt-preferred-output-format
If @code{org-export-odt-preferred-output-format} is specified, open the
converted file instead.
@xref{x-export-to-other-formats,,Automatically Exporting to Other formats}.
@end table
@subsubheading Automatically Exporting to Other formats
@anchor{x-export-to-other-formats}
@vindex org-export-odt-preferred-output-format
Very often, you will find yourself exporting to @acronym{ODT} format, only to
immediately save the exported document to a different format like @samp{doc},
@samp{pdf} etc. In such cases, you will find it convenient to configure a
converter (@pxref{Configuring a converter}) and specify your preferred
output format by customizing the variable
@code{org-export-odt-preferred-output-format}. This way the export commands
(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to also export to
the preferred format.
@node Exporting and Converting to Other formats, Applying Custom Styles, @acronym{ODT} export commands, OpenDocument Text export
@subsection Exporting and Converting to Other formats
@cindex convert
@cindex doc, docx
@acronym{ODT} exporter adds support for exporting Org outlines to formats
that are not supported natively by Org. It also adds support to convert
document from one format to another. To use these features, you need to
configure a command-line converter.
@menu
* Configuring a converter:: How to install a converter
* Using the converter:: How to use the converter
@end menu
@node Configuring a converter, Using the converter, Exporting and Converting to Other formats, Exporting and Converting to Other formats
@subsubsection Configuring a converter
@subsubheading Pre-configured converters
@cindex converter
The @acronym{ODT} exporter supports two converters out of the box:
@enumerate
@cindex @file{unoconv}
@item @file{unoconv}
This converter is available as an installable package in your favorite
distribution.
@cindex @file{BasicODConverter}
@item @file{BasicODConverter}
@vindex org-odt-data-dir
This converter is distributed as a LibreOffice extension and can be found in
the your Org distribution. See the subdirectory pointed to by the variable
@code{org-odt-data-dir}.
@end enumerate
@subsubheading Installing a new converter
If you prefer to use a converter other than the two mentioned above, then you
may have to do additional configuration. You can proceed as follows:
@enumerate
@item Register the converter
@vindex org-export-odt-convert-processes
Name your converter and add it to the list of known converters by customizing
the variable @code{org-export-odt-convert-processes}. Also specify how the
converter can be invoked via command-line to effect the conversion.
@item Configure it's capabilities
@vindex org-export-odt-convert-capabilities
@anchor{x-odt-converter-capabilities}
Specify the set of formats the converter can handle by customizing the
variable @code{org-export-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 full set of formats supported by the
converter and not limit yourself to specifying formats that are related to
just the OpenDocument Text format.
@item Choose the converter
@vindex org-export-odt-convert-process
Select the newly added converter as the preferred one by customizing the
variable @code{org-export-odt-convert-process}.
@end enumerate
@node Using the converter, , Configuring a converter, Exporting and Converting to Other formats
@subsubsection Using the converter
Once a command-line converter is configured you can use it to extend the list
of formats to which Org can export
to. @xref{x-export-to-other-formats,,Automatically Exporting to Other
formats}. You can also use it to perform one-off document conversion as
detailed below.
@vindex org-export-odt-convert
@table @kbd
@item M-x org-export-odt-convert
Convert an existing document from one format to another format as determined
by variable @code{org-export-odt-convert-capabilities}
(@pxref{x-odt-converter-capabilities,,Configure converter capabilities}).
Note that you can use this command to even convert documents that is produced
outside of Org and in formats that is different from @acronym{ODT} format.
@end table
@node Applying Custom Styles, Links in @acronym{ODT} export, Exporting and Converting to Other formats, OpenDocument Text export
@subsection Applying Custom Styles
@cindex styles, custom
@cindex template, custom
@vindex org-export-odt-styles-file
@subsubheading A note on the internals
@acronym{ODT} exporter relies on two files for generating it's output. These
files are bundled under the @file{styles} subdirectory of the data directory
(See variable @code{org-odt-data-dir}). The two files are:
@c `org-export-odt-styles-file'
@c `org-export-odt-content-template-file'
@itemize
@item
@file{OrgOdtStyles.xml}
This file contributes to @file{styles.xml} file of the final @samp{ODT}
document. This file gets modified for the following purposes:
@enumerate
@item
To control outline numbering based on user settings.
@item
To add styles generated by the @file{htmlfontify.el} for fontification of
code blocks.
@end enumerate
@item
@file{OrgOdtContentTemplate.xml}
This file contributes to the @file{content.xml} file of the final @samp{ODT}
document. The contents of the Org outline is inserted between the
@samp{}@dots{}@samp{} elements of this file.
Apart from serving as a template file for the final @file{content.xml}, the
file serves the following purposes:
@enumerate
@item
It contains Automatic Styles for formatting of tables which are referenced by
the exporter.
@item
It contains @samp{}@dots{}@samp{}
elements that control how various entities - Tables, Images, Equations etc -
are numbered.
@end enumerate
@end itemize
@subsubheading Overriding the default styles
The default styles that ship with the @acronym{ODT} exporter would suffice
for generating well-formatted document. However it may not cater to your
specific tastes. If this is the case, you can replace the factory defaults
with your own by customizing the following variables:
@itemize
@item
@code{org-export-odt-styles-file}
Use this variable to specify the @file{styles.xml} that will be used in the
final output. You can specify one of the following values:
@enumerate
@item A @file{styles.xml} file
Use this file instead of the default @file{styles.xml}
@item A @file{.odt} or @file{.ott} file
Use the @file{styles.xml} contained in the specified OpenDocument Text or
Template file
@item A @file{.odt} or @file{.ott} file and a subset of files contained within them
Use the @file{styles.xml} contained in the specified OpenDocument Text or
Template file. Additionally extract the specified member files and embed
those within the final @samp{ODT} document.
Use this option if the @file{styles.xml} references additional files like
header and footer images.
@item @code{nil}
Use the default @file{styles.xml}
@end enumerate
@item
@code{org-export-odt-content-template-file}
Use this variable to specify the blank @file{content.xml} that will be used
in the final output.
@end itemize
@noindent
@strong{Caution:} For best results with custom styles, you need to ensure
that all style names emitted by the @acronym{ODT} exporter be apriori defined
in @file{styles.xml} and the template @file{content.xml} files. Unless
sufficient care is exercised in choosing the custom style files, the result
could be less than satisfactory. So it is highly recommended that you build
your custom @file{styles.xml} from the default @file{styles.xml} bundled with
the exporter.
@subsubheading Specifying Custom Styles on per-file basis
@cindex #+ODT_STYLES_FILE
You can use @code{#+ODT_STYLES_FILE} option to specify custom styles on
per-file basis. This option effectively overrides the value of
@code{org-export-odt-styles-file} with the specified value just for this
buffer. A typical setting will look like
@example
#+ODT_STYLES_FILE: "/path/to/styles.xml"
@end example
or
@example
#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
@end example
@node Links in @acronym{ODT} export, Tables in @acronym{ODT} export, Applying Custom Styles, OpenDocument Text export
@subsection Links in @acronym{ODT} export
@cindex tables, in DocBook export
@acronym{ODT} exporter creates cross-references (aka bookmarks) for links
that are destined locally. It creates internet style links for all other
links.
@node Tables in @acronym{ODT} export, Images in @acronym{ODT} export, Links in @acronym{ODT} export, OpenDocument Text export
@subsection Tables in @acronym{ODT} export
@cindex tables, in DocBook export
Export of native Org-mode tables (@inforef{Tables,,org}) and simple
@file{table.el} tables is supported. However export of complex
@file{table.el} tables - tables that have column or row spans - are not
supported. Such tables are stripped from the exported document.
By default, a table is exported with with top and bottom frames and with
rules separating row and column groups (@inforef{Column groups,,org}). If
the table specifies alignment and relative width for it's columns
(@inforef{Column width and alignment,,org}) then these are honored on
export@footnote{The column widths are interpreted as weighted ratios with the
default weight being 1}.
@cindex #+ATTR_ODT
You can override the default formatting of the table by specifying a custom
table style with the @code{#+ATTR_ODT} line.
This feature closely mimics the way table templates are defined in the
OpenDocument-v1.2
specification@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
OpenDocument-v1.2 Specification}}.
To use this feature proceed as follows:
@enumerate
@item
Create a table template@footnote{See @code{} element of
OpenDocument-v1.2 specification}
A table template is nothing but a set of @samp{table-cell} and
@samp{paragraph} style for each of the following table cell categories:
@itemize @minus
@item Body
@item First column
@item Last column
@item First row
@item Last row
@item Even row
@item Odd row
@item Even column
@item Odd Column
@end itemize
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 name @samp{Custom}, the needed style names are listed in the
following table.
@multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph}
@item Table cell type
@tab @code{table-cell} style
@tab @code{paragraph} style
@item
@tab
@tab
@item Body
@tab @samp{CustomTableCell}
@tab @samp{CustomTableParagraph}
@item First column
@tab @samp{CustomFirstColumnTableCell}
@tab @samp{CustomFirstColumnTableParagraph}
@item Last column
@tab @samp{CustomLastColumnTableCell}
@tab @samp{CustomLastColumnTableParagraph}
@item First row
@tab @samp{CustomFirstRowTableCell}
@tab @samp{CustomFirstRowTableParagraph}
@item Last row
@tab @samp{CustomLastRowTableCell}
@tab @samp{CustomLastRowTableParagraph}
@item Even row
@tab @samp{CustomEvenRowTableCell}
@tab @samp{CustomEvenRowTableParagraph}
@item Odd row
@tab @samp{CustomOddRowTableCell}
@tab @samp{CustomOddRowTableParagraph}
@item Even column
@tab @samp{CustomEvenColumnTableCell}
@tab @samp{CustomEvenColumnTableParagraph}
@item Odd column
@tab @samp{CustomOddColumnTableCell}
@tab @samp{CustomOddColumnTableParagraph}
@end multitable
To create a table template with name @samp{Custom}, define the above styles
in the @code{}...@code{}
element of the content template file (see docstring of variable
@code{org-export-odt-content-template-file}).
@item
Define a table style@footnote{See attributes - @code{table:template-name},
@code{table:use-first-row-styles}, @code{table:use-last-row-styles},
@code{table:use-first-column-styles}, @code{table:use-last-column-styles},
@code{table:use-banding-rows-styles}, @code{table:use-banding-column-styles}
- of @code{} element in OpenDocument-v1.2 specification}
@vindex org-export-odt-table-styles
To define a table style, create an entry for the style in the variable
@code{org-export-odt-table-styles} and specify the following:
@itemize @minus
@item name of the table template created in step (1)
@item set of cell styles in that template that are to be activated
@end itemize
For example, the entry below defines two different table styles
@samp{TableWithHeaderRowsAndColumns} and @samp{TableWithHeaderColumns} based
on the same template @samp{Custom}. The styles achieve their intended effect
by selectively activating the individual cell styles in that template.
@lisp
(setq org-export-odt-table-styles
'(("TableWithHeaderRowsAndColumns"
"Custom"
((use-first-row-styles . t)
(use-first-column-styles . t)))
("TableWithHeaderColumns"
"Custom" ((use-first-column-styles . t)))))
@end lisp
@item
Associate a table with the table style
To do this, specify the table style created in step (2) as part of
@code{ATTR_ODT} line as show below.
@example
#+ATTR_ODT: TableWithHeaderColumns
| Name | Phone | Age |
| Peter | 1234 | 17 |
| Anna | 4321 | 25 |
@end example
@end enumerate
@node Images in @acronym{ODT} export, Math formatting in @acronym{ODT} export, Tables in @acronym{ODT} export, OpenDocument Text export
@subsection Images in @acronym{ODT} export
@cindex images, embedding in @acronym{ODT}
@cindex embedding images in @acronym{ODT}
@subsubheading Embedding images
You can embed images within the exported document by providing a link to the
desired image file with no link description. For example, to embed
@samp{img.png} do either of the following:
@example
[[file:img.png]]
@end example
@example
[[./img.png]]
@end example
@subsubheading Embedding clickable images
You can create clickable images by providing a link whose description is a
link to an image file. For example, to embed a image
@file{org-mode-unicorn.png} which when clicked jumps to
@uref{http://Orgmode.org} website, do the following
@example
[[http://orgmode.org][./org-mode-unicorn.png]]
@end example
You can control the size and scale of the embedded images using the
@code{#+ATTR_ODT} attribute.
@subsubheading How image size is computed
In order to scale the embedded images, the exporter needs to compute the size
of the image. This is done by retrieving the image size in pixels and
converting the pixel units to centimetres using
@code{org-export-odt-pixels-per-inch}. The default value of this variable is
set to @code{display-pixels-per-inch}. You can tweak this variable to
achieve the best results.
@subsubheading Sizing and scaling of embedded images
@c @vindex org-export-odt-pixels-per-inch
Note that the exporter specifies the desired size of the image in the final
document in units of centimetres. To compute the size of the original image
in centimetres, the To convert the image size in pixels to equivalent units
in cms @code{org-export-odt-pixels-per-inch} is used.
The examples below illustrate the various possibilities.
@table @asis
@item Explicitly size the image
To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
@example
#+ATTR_ODT: (:width 10 :height 10)
[[./img.png]]
@end example
@item Scale the image
To embed @file{img.png} at half it's size, do the following:
@example
#+ATTR_ODT: (:scale 0.5)
[[./img.png]]
@end example
@item Scale the image to a specific width
To embed @file{img.png} to occupy a width of 10 cm while retaining the
original height:width ratio, do the following:
@example
#+ATTR_ODT: (:width 10)
[[./img.png]]
@end example
@item Scale the image to a specific height
To embed @file{img.png} to occupy a height of 10 cm while retaining the
original height:width ratio, do the following
@example
#+ATTR_ODT: (:height 10)
[[./img.png]]
@end example
@end table
@node Math formatting in @acronym{ODT} export, Literal Examples in @acronym{ODT} export, Images in @acronym{ODT} export, OpenDocument Text export
@subsection Math formatting in @acronym{ODT} export
@LaTeX{} math snippets (@inforef{LaTeX fragments,,org}) can be embedded in
the ODT document using one of the following ways:
@cindex MathML
@enumerate
@item MathML
This option is activated on a per-file basis with
@example
#+OPTIONS: LaTeX:t
@end example
With this option, @LaTeX{} fragments are first converted in to MathML
fragments using an external LaTeX-to-MathML converter program. The resulting
MathML fragments are then embedded as a OpenDocument Formula in the exported
document.
@vindex org-latex-to-mathml-convert-command
@vindex org-latex-to-mathml-jar-file
You can specify the LaTeX-to-MathML converter by customizing the variables
@code{org-latex-to-mathml-convert-command} and
@code{org-latex-to-mathml-jar-file}.
If you prefer to use @file{MathToWeb}@footnote{See
@uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}} as your
converter, you can configure the above variables as shown below.
@lisp
(setq org-latex-to-mathml-convert-command
"java -jar %j -unicode -force -df %o %I"
org-latex-to-mathml-jar-file
"/path/to/mathtoweb.jar")
@end lisp
@cindex dvipng
@item png
This option is activated on a per-file basis with
@example
#+OPTIONS: LaTeX:dvipng
@end example
With this option, @LaTeX{} fragments are processed into png images and the
resulting images are embedded in the exported document. This method requires
that the @file{dvipng} program be available on your system.
@end enumerate
@node Literal Examples in @acronym{ODT} export, Working with raw OpenDocument XML, Math formatting in @acronym{ODT} export, OpenDocument Text export
@subsection Literal Examples in @acronym{ODT} export
Export of Literal examples (@inforef{Literal examples,,org}) with full
fontification is supported. This feature is enabled by default and is
activated automatically if an enhanced version of @file{htmlfontify.el} is
available in the @code{load-path}@footnote{@file{htmlfontify.el} that ships
with standard Emacs <= 24.1 has no support for @acronym{ODT} fontification}.
@vindex org-export-odt-fontify-srcblocks
The character styles used for fontification of the Literal blocks are
auto-generated by the exporter in conjunction with @file{htmlfontify.el}
library and need not be included in the default @file{styles.xml} file.
These auto-generated styles have @samp{OrgSrc} prefix and inherit their color
based on the face used by Emacs @code{font-lock} library.
@vindex org-export-odt-create-custom-styles-for-srcblocks
If you prefer to use your own custom styles for fontification and disable
their auto-generation altogether, you can do so by customizing the variable
@code{org-export-odt-create-custom-styles-for-srcblocks}.
You can turn off fontification support for Literal examples by customizing
the variable @code{org-export-odt-fontify-srcblocks}.
@node Working with raw OpenDocument XML, Additional Documentation, Literal Examples in @acronym{ODT} export, OpenDocument Text export
@subsection Working with raw OpenDocument XML
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.
@enumerate
@item Embedding ODT tags as part of regular text
You can include simple OpenDocument tags by prepending them with them with
@samp{@@}. For example, to highlight a region of text do the following:
@example
@@This is a
highlighted text@@. But this is a
regular text.
@end example
@strong{Hint:} To see the above example in action, edit your
@file{styles.xml} and add a custom @samp{Highlight} style as shown below.
@example
@end example
@item Embedding a one-line OpenDocument XML
You can add a simple OpenDocument one-liner using the @code{#+ODT:}
directive. For example to force a page break do the following
@example
#+ODT:
@end example
@strong{Hint:} To see the above example in action, edit your
@file{styles.xml} and add a custom @samp{PageBreak} style as shown below.
@example
@end example
@item Embedding a block of OpenDocument XML
You can add a large block of OpenDocument XML using the
@code{#+BEGIN_ODT}@dots{}@code{#+END_ODT} construct.
For example to create a one-off paragraph that uses bold text do the
following:
@example
#+BEGIN_ODT
This paragraph is specially formatted and uses bold text.
#+END_ODT
@end example
@end enumerate
@node Additional Documentation, , Working with raw OpenDocument XML, OpenDocument Text export
@subsection Additional documentation
The @acronym{ODT} exporter is still in development. For up to date
information, please follow Org mailing list @email{emacs-orgmode@@gnu.org}
closely.
@c end opendocument
@node Main Index, Key Index, Exporting, Top
@unnumbered Concept index
@printindex cp
@node Key Index, Command and Function Index, Main Index, Top
@unnumbered Key index
@printindex ky
@node Command and Function Index, Variable Index, Key Index, Top
@unnumbered Command and function index
@printindex fn
@node Variable Index, , Command and Function Index, Top
@unnumbered Variable index
This is not a complete index of variables and faces, only the ones that are
mentioned in the manual. For a more complete list, use @kbd{M-x
org-customize @key{RET}} and then click yourself through the tree.
@printindex vr
@bye
@c Local variables:
@c fill-column: 77
@c indent-tabs-mode: nil
@c paragraph-start: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$"
@c paragraph-separate: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$"
@c End:
@c LocalWords: webdavhost pre