diff options
author | Jambunathan K <kjambunathan@gmail.com> | 2011-12-07 04:04:55 +0530 |
---|---|---|
committer | Bastien Guerry <bzg@altern.org> | 2011-12-10 18:13:30 +0100 |
commit | 69aa8884ed7319a28ff8f1ab9068497a1cc1bb5b (patch) | |
tree | c8da422df6b954f7a2cafa3995b80515251d4001 | |
parent | dc9e33b0a5462881a697c07c3ce3878770b95861 (diff) | |
download | org-mode-69aa8884ed7319a28ff8f1ab9068497a1cc1bb5b.tar.gz |
org.texi: Improve ODT section
-rw-r--r-- | doc/org.texi | 322 |
1 files changed, 191 insertions, 131 deletions
diff --git a/doc/org.texi b/doc/org.texi index bdc43f5..7b1fbbe 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -620,7 +620,6 @@ OpenDocument Text export * 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:: Math formatting in @acronym{ODT} export @@ -633,8 +632,9 @@ Advanced topics in @acronym{ODT} export * Exporting and Converting to Other formats:: * Configuring a converter:: * Using the converter:: +* Working with OpenDocument style files:: +* Working with raw OpenDocument XML:: * Customizing Tables in @acronym{ODT} export:: -* A note on the internals of @acronym{ODT} exporter:: Exporting and Converting to Other formats @@ -10775,7 +10775,6 @@ are compatible with LibreOffice 3.4. * 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:: @end menu @@ -10838,13 +10837,13 @@ the preferred format. @cindex styles, custom @cindex template, custom -The @acronym{ODT} exporter ships with a set of OpenDocument styles (@pxref{A -note on the internals of @acronym{ODT} exporter}) that ensure a -well-formatted output. These factory styles, however, may not cater to your -specific tastes. To customize the output, you can either modify the above -styles files directly or generate the required styles using an application -like LibreOffice. The latter method is suitable for both expert and -non-expert users alike and is described here. +The @acronym{ODT} exporter ships with a set of OpenDocument styles +(@pxref{Working with OpenDocument style files}) that ensure a well-formatted +output. These factory styles, however, may not cater to your specific +tastes. To customize the output, you can either modify the above styles +files directly or generate the required styles using an application like +LibreOffice. The latter method is suitable for both expert and non-expert +users alike and is described here. @subsubsection Applying custom styles - The Easy way @@ -10867,7 +10866,8 @@ Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file. @cindex #+ODT_STYLES_FILE @vindex org-export-odt-styles-file Customize the variable @code{org-export-odt-styles-file} and point it to the -newly created file. +newly created file. For additional configuration options +@xref{x-overriding-factory-styles,,Overriding factory styles}. If you would like to choose a style on per-file basis, you can use the @code{#+ODT_STYLES_FILE} option. A typical setting will look like @@ -10876,6 +10876,12 @@ If you would like to choose a style on per-file basis, you can use the #+ODT_STYLES_FILE: "/path/to/example.ott" @end example +or + +@example +#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png")) +@end example + @end enumerate @subsubsection Using Third-party Styles and Templates @@ -11093,7 +11099,7 @@ or [[./equation.odf]] @end example -@node Literal Examples in @acronym{ODT} export, Working with raw OpenDocument XML, Math formatting in @acronym{ODT} export, OpenDocument Text export +@node Literal Examples in @acronym{ODT} export, Advanced topics in @acronym{ODT} export, 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 @@ -11120,80 +11126,17 @@ their auto-generation altogether, you can do so by customizing the variable 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 -@@<text:span text:style-name="Highlight">This is a -highlighted text@@</text:span>. 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 -<style:style style:name="Highlight" style:family="text"> - <style:text-properties fo:background-color="#ff0000"/> -</style:style> -@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: <text:p text:style-name="PageBreak"/> -@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 -<style:style style:name="PageBreak" style:family="paragraph" - style:parent-style-name="Text_20_body"> - <style:paragraph-properties fo:break-before="page"/> -</style:style> -@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 -<text:p text:style-name="Text_20_body_20_bold"> -This paragraph is specially formatted and uses bold text. -</text:p> -#+END_ODT -@end example - -@end enumerate -@node Advanced topics in @acronym{ODT} export, , Working with raw OpenDocument XML, OpenDocument Text export +@node Advanced topics in @acronym{ODT} export, , Literal Examples in @acronym{ODT} export, OpenDocument Text export @subsection Advanced topics in @acronym{ODT} export @menu * Exporting and Converting to Other formats:: * Configuring a converter:: * Using the converter:: +* Working with OpenDocument style files:: +* Working with raw OpenDocument XML:: * 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 @@ -11268,7 +11211,7 @@ 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 +@node Using the converter, Working with OpenDocument style files, 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 @@ -11288,7 +11231,173 @@ 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 +@node Working with OpenDocument style files, Working with raw OpenDocument XML, Using the converter, Advanced topics in @acronym{ODT} export +@subsubsection Working with OpenDocument style files +@cindex styles, custom +@cindex template, custom + +@anchor{x-factory-styles} +@subsubheading Factory styles + +@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 +@anchor{x-orgodtstyles-xml} +@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 + +@anchor{x-orgodtcontenttemplate-xml} +@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{<office:text>}@dots{}@samp{</office:text>} 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{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>} +elements that control how various entities - Tables, Images, Equations etc - +are numbered. +@end enumerate +@end itemize + +@anchor{x-overriding-factory-styles} +@subsubheading Overriding factory styles +The following two variables control the location from which the @acronym{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. + +@itemize +@anchor{x-org-export-odt-styles-file} +@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 + +@anchor{x-org-export-odt-content-template-file} +@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 + +@node Working with raw OpenDocument XML, Customizing Tables in @acronym{ODT} export, Working with OpenDocument style files, Advanced topics in @acronym{ODT} export +@subsubsection 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 +@@<text:span text:style-name="Highlight">This is a +highlighted text@@</text:span>. But this is a +regular text. +@end example + +@strong{Hint:} To see the above example in action, edit your +@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a +custom @samp{Highlight} style as shown below. + +@example +<style:style style:name="Highlight" style:family="text"> + <style:text-properties fo:background-color="#ff0000"/> +</style:style> +@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: <text:p text:style-name="PageBreak"/> +@end example + +@strong{Hint:} To see the above example in action, edit your +@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a +custom @samp{PageBreak} style as shown below. + +@example +<style:style style:name="PageBreak" style:family="paragraph" + style:parent-style-name="Text_20_body"> + <style:paragraph-properties fo:break-before="page"/> +</style:style> +@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 +<text:p text:style-name="Text_20_body_20_bold"> +This paragraph is specially formatted and uses bold text. +</text:p> +#+END_ODT +@end example + +@end enumerate + +@node Customizing Tables in @acronym{ODT} export, , Working with raw OpenDocument XML, Advanced topics in @acronym{ODT} export @subsubsection Customizing Tables in @acronym{ODT} export @cindex tables, in ODT export @@ -11368,8 +11477,8 @@ following table. To create a table template with name @samp{Custom}, define the above styles in the @code{<office:automatic-styles>}...@code{</office:automatic-styles>} -element of the content template file (see docstring of variable -@code{org-export-odt-content-template-file}). +element of the content template file +(@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). @item Define a table style@footnote{See attributes - @code{table:template-name}, @@ -11416,55 +11525,6 @@ To do this, specify the table style created in step (2) as part of @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 - -@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 -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{<office:text>}@dots{}@samp{</office:text>} 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{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>} -elements that control how various entities - Tables, Images, Equations etc - -are numbered. -@end enumerate -@end itemize - @c end opendocument @node TaskJuggler export, Freemind export, OpenDocument Text export, Exporting |