From 4ab52c962f010f24489a68dc484b9740fd2081c8 Mon Sep 17 00:00:00 2001 From: Jambunathan K Date: Mon, 5 Dec 2011 00:50:12 +0530 Subject: [PATCH] doc/org.texi: Update ODT section --- doc/org.texi | 850 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 726 insertions(+), 124 deletions(-) diff --git a/doc/org.texi b/doc/org.texi index ba5d3d765..d22a41b9e 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -296,7 +296,7 @@ license to the document, as described in section 6 of the license. @subtitle Release @value{VERSION} @author by Carsten Dominik -with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, and Thomas Dye +with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K. @c The following two commands start the copyright page. @page @@ -573,7 +573,7 @@ Exporting * HTML export:: Exporting to HTML * LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF * DocBook export:: Exporting to DocBook -* OpenDocumentText export:: Exporting to OpenDocumentText +* OpenDocument Text export:: Exporting to OpenDocument Text * TaskJuggler export:: Exporting to TaskJuggler * Freemind export:: Exporting to Freemind mind maps * XOXO export:: Exporting to XOXO @@ -610,15 +610,32 @@ DocBook export * Images in DocBook export:: How to insert figures into DocBook output * Special characters:: How to handle special characters -OpenDocument export +OpenDocument Text export -* OpenDocumentText export commands:: How to invoke OpenDocumentText export +* Installing ODT exporter:: How to install @acronym{ODT} exporter +* @acronym{ODT} export commands:: How to invoke @acronym{ODT} export * Applying Custom Styles:: How to apply custom styles to the output -* Converting to Other formats:: How to convert to formats like doc, docx etc -* Links in OpenDocumentText export:: How links will be interpreted and formatted -* Tables in OpenDocumentText export:: How Tables are handled -* Images in OpenDocumentText export:: How to insert figures -* Additional Documentation:: How to handle special characters +* 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:: +* Advanced topics in @acronym{ODT} export:: +* Additional Documentation:: Where to find more information + +Advanced topics in @acronym{ODT} export + +* Exporting and Converting to Other formats:: +* Configuring a converter:: +* Using the converter:: +* Customizing Tables in @acronym{ODT} export:: +* A note on the internals of @acronym{ODT} exporter:: + +Exporting and Converting to Other formats + +* Configuring a converter:: How to install a converter +* Using the converter:: How to use the converter Publishing @@ -9485,13 +9502,13 @@ 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. OpenDocumentText 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. +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). @@ -9504,7 +9521,7 @@ enabled (default in Emacs 23). * HTML export:: Exporting to HTML * LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF * DocBook export:: Exporting to DocBook -* OpenDocumentText export:: Exporting to OpenDocumentText +* OpenDocument Text export:: Exporting to OpenDocument Text * TaskJuggler export:: Exporting to TaskJuggler * Freemind export:: Exporting to Freemind mind maps * XOXO export:: Exporting to XOXO @@ -10529,7 +10546,7 @@ Here is a simple example Org document that is intended for beamer export. For more information, see the documentation on Worg. -@node DocBook export, OpenDocumentText export, LaTeX and PDF export, Exporting +@node DocBook export, OpenDocument Text export, LaTeX and PDF export, Exporting @section DocBook export @cindex DocBook export @cindex PDF export @@ -10728,39 +10745,67 @@ special characters included in XHTML entities: @c begin opendocument -@node OpenDocumentText export, TaskJuggler export, DocBook export, Exporting -@section OpenDocumentText export -@cindex OpenDocumentText export +@node OpenDocument Text export, TaskJuggler export, DocBook export, Exporting +@section OpenDocument Text export @cindex K, Jambunathan +@cindex ODT +@cindex OpenDocument +@cindex export, OpenDocument +@cindex LibreOffice +@cindex org-odt.el +@cindex org-modules -Org-mode 7.6 supports export to OpenDocumentText format using -@file{org-odt.el} module contributed by Jambunathan K. This module can be -enabled in one of the following ways based on your mode of installation. - -@enumerate -@item -If you have downloaded the Org from the Web, either as a distribution -@file{.zip} or @file{.tar} file, or as a Git archive, enable the @code{odt} -option in variable @code{org-modules}. -@item -If you are using Org that comes bundled with Emacs, then you can install the -OpenDocumentText exporter using the package manager. To do this, customize -the variable @code{package-archives} to include -@uref{http://orgmode.org/pkg/releases/} as one of the package archives. -@end enumerate +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 -* OpenDocumentText export commands::How to invoke OpenDocumentText export +* Installing ODT exporter:: How to install @acronym{ODT} exporter +* @acronym{ODT} export commands:: How to invoke @acronym{ODT} export * Applying Custom Styles:: How to apply custom styles to the output -* Converting to Other formats:: How to convert to formats like doc, docx etc -* Links in OpenDocumentText export:: How links will be interpreted and formatted -* Tables in OpenDocumentText export:: Tables are exported as HTML tables -* Images in OpenDocumentText export:: How to insert figures into DocBook 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:: +* Advanced topics in @acronym{ODT} export:: * Additional Documentation:: Where to find more information @end menu -@node OpenDocumentText export commands, Applying Custom Styles, OpenDocumentText export, OpenDocumentText export -@subsection OpenDocumentText export commands +@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, Applying Custom Styles, 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 @@ -10768,113 +10813,670 @@ the variable @code{package-archives} to include @table @kbd @orgcmd{C-c C-e o,org-export-as-odt} @cindex property EXPORT_FILE_NAME -Export as OpenDocumentText file. For an Org file, @file{myfile.org}, the -OpenDocumentText 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. + +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 OpenDocumentText file and open the resulting file. +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 -@node Applying Custom Styles, Converting to Other formats, OpenDocumentText export commands, OpenDocumentText export +@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 Applying Custom Styles, Links in @acronym{ODT} export, @acronym{ODT} export commands, OpenDocument Text export @subsection Applying Custom Styles @cindex styles, custom @cindex template, custom +@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 (@pxref{Tables}) 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 (@pxref{Column groups}). If the table +specifies alignment and relative width for it's columns (@pxref{Column width +and alignment}) 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. + +@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 (@pxref{LaTeX fragments}) 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 (@pxref{Literal examples}) 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. A copy of the +proposed version is available as an attachment to +@url{http://debbugs.gnu.org/cgi/bugreport.cgi?msg=5;filename=htmlfontify.el;att=9;bug=9914, Emacs Bug #9914}.} + +@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, Advanced topics in @acronym{ODT} export, 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 Advanced topics in @acronym{ODT} export, Additional Documentation, Working with raw OpenDocument XML, OpenDocument Text export +@subsection Advanced topics in @acronym{ODT} export + +@menu +* Exporting and Converting to Other formats:: +* Configuring a converter:: +* Using the converter:: +* Customizing Tables in @acronym{ODT} export:: +* A note on the internals of @acronym{ODT} exporter:: +@end menu + +@node Exporting and Converting to Other formats, Configuring a converter, Advanced topics in @acronym{ODT} export, Advanced topics in @acronym{ODT} export +@subsubsection 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, Advanced topics in @acronym{ODT} export +@subsubheading 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, Customizing Tables in @acronym{ODT} export, Configuring a converter, Advanced topics in @acronym{ODT} export +@subsubheading 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 Customizing Tables in @acronym{ODT} export, A note on the internals of @acronym{ODT} exporter, Using the converter, Advanced topics in @acronym{ODT} export +@subsubsection Customizing Tables in @acronym{ODT} export +@cindex tables, in ODT export + +@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} +@headitem 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 A note on the internals of @acronym{ODT} exporter, , Customizing Tables in @acronym{ODT} export, Advanced topics in @acronym{ODT} export +@subsubsection A note on the internals of @acronym{ODT} exporter +@cindex styles, custom +@cindex template, custom + @vindex org-export-odt-styles-file -OpenDocumentExporter ships with a custom @file{styles.xml} for formatting of -the exported file. To customize the output to suit your needs you can use -one of the following methods: +@acronym{ODT} exporter relies on two files for generating it's output. These +files are bundled with the distribution under the directory pointed to by +variable @code{org-odt-styles-dir}. The two files are: +@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 -Customize the variable @code{org-export-odt-styles-file} to point to either a -@file{styles.xml} file, a OpenDocument Text Template file @code{.ott} or a -combination of Text or Template Document together with a set of member files. -Use the first two options if the styles.xml has no references to additional -set of files and use the last option if the @file{styles.xml} references -additional files like header and footer images. +To control outline numbering based on user settings. + @item -Use an external tool like unoconv to apply custom templates. +To add styles generated by the @file{htmlfontify.el} for fontification of +code blocks. @end enumerate -For best results, it is necessary that the style names used by -OpenDocumentText exporter match that used in the @file{styles.xml}. +@item +@file{OrgOdtContentTemplate.xml} -@node Converting to Other formats, Links in OpenDocumentText export, Applying Custom Styles, OpenDocumentText export -@subsection Converting to Other formats +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. -@cindex convert -@cindex doc, docx +Apart from serving as a template file for the final @file{content.xml}, the +file serves the following purposes: +@enumerate -@vindex org-export-odt-styles-file +@item +It contains Automatic Styles for formatting of tables which are referenced by +the exporter. -Often times there is a need to convert OpenDocumentText files to other -formats like doc, docx or pdf. You can accomplish this by one of the -following methods: +@item +It contains @samp{}@dots{}@samp{} +elements that control how various entities - Tables, Images, Equations etc - +are numbered. +@end enumerate +@end itemize -@table @kbd -@item M-x org-lparse -Export the outline first to one of the native formats (like OpenDocumentText) -and immediately post-process it to other formats using an external converter. - -@item M-x org-lparse-convert -Export an existing document to other formats using an external converter. -@end table - -You can choose the converter used for conversion by customizing the variable -@code{org-lparse-convert-process}. - -@node Links in OpenDocumentText export, Tables in OpenDocumentText export, Converting to Other formats, OpenDocumentText export -@subsection Links in OpenDocumentText export -@cindex tables, in DocBook export - -OpenDocumentExporter creates cross-references (aka bookmarks) for links that -are destined locally. It creates internet style links for all other links. - -@node Tables in OpenDocumentText export, Images in OpenDocumentText export, Links in OpenDocumentText export, OpenDocumentText export -@subsection Tables in OpenDocumentText export -@cindex tables, in DocBook export - -Export of @file{table.el} tables with row or column spanning is not -supported. Such tables are stripped from the exported document. - -@node Images in OpenDocumentText export, Additional Documentation, Tables in OpenDocumentText export, OpenDocumentText export -@subsection Images in OpenDocumentText export -@cindex images, embedding in OpenDocumentText -@cindex embedding images in OpenDocumentText - -OpenDocumentText exporter can embed images within the exported document. To -embed images, provide a link to the desired image file with no link -description. For example, the following links @samp{[[file:img.jpg]]} or -@samp{[[./img.jpg]]}, will result in embedding of @samp{img.jpg} in the -exported file. - -The exporter can also embed scaled and explicitly sized images within the -exported document. The markup of the scale and size specifications has not -been standardized yet and is hence conveniently skipped in this document. - -The exporter can also make an image the clickable part of a link. To create -clickable images, provide a link whose description is a link to an image -file. For example, the following link -@samp{[[http://orgmode.org][./img.jpg]]}, will result in a clickable image -that links to @uref{http://Orgmode.org} website. - -@node Additional Documentation, , Images in OpenDocumentText export, OpenDocumentText export +@node Additional Documentation, , Advanced topics in @acronym{ODT} export, OpenDocument Text export @subsection Additional documentation -The OpenDocumentText exporter is still in development. For up to date +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 TaskJuggler export, Freemind export, OpenDocumentText export, Exporting +@node TaskJuggler export, Freemind export, OpenDocument Text export, Exporting @section TaskJuggler export @cindex TaskJuggler export @cindex Project management @@ -15673,7 +16275,7 @@ with links transformation to Org syntax. @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual chapter about publishing. @item -@i{Jambunathan K} contributed the OpenDocumentText exporter. +@i{Jambunathan K} contributed the @acronym{ODT} exporter. @item @i{Sebastien Vauban} reported many issues with LaTeX and BEAMER export and enabled source code highlighling in Gnus.