From 11af1b167881eefcb01ca46ee8e4387312934ce7 Mon Sep 17 00:00:00 2001
From: Jambunathan K <kjambunathan@gmail.com>
Date: Wed, 7 Dec 2011 00:08:54 +0530
Subject: [PATCH] org.texi: Refine ODT section

---
 doc/org.texi | 92 +++++++++++++++++++---------------------------------
 1 file changed, 34 insertions(+), 58 deletions(-)

diff --git a/doc/org.texi b/doc/org.texi
index d22a41b9e..5d1c01f6e 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -10854,78 +10854,54 @@ the preferred format.
 @cindex styles, custom
 @cindex template, custom
 
-@subsubheading Overriding the default styles
+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 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:
+@subsubsection Applying custom styles - The Easy way
 
 @enumerate
-@item A @file{styles.xml} file
+@item
+Create a sample @file{example.org} file with the below settings and export it
+to @acronym{ODT} format.
 
-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
+@example
+#+OPTIONS: H:10 num:t
+@end example
 
 @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
+Open the above @file{example.odt} using LibreOffice.  Use the @file{Stylist}
+to locate the target styles - these typically have @samp{Org} prefix - and
+modify those to your taste.  Save the modified file either as an OpenDocument
+Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file.
 
+@item
 @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.
 
-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
+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
 
 @example
-#+ODT_STYLES_FILE: "/path/to/styles.xml"
+#+ODT_STYLES_FILE: "/path/to/example.ott"
 @end example
 
-or
+@end enumerate
 
-@example
-#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
-@end example
+@subsubsection Using Third-party Styles and Templates
+
+You can use third-party styles and templates for customizing your output.
+This will produce the desired output only if the template provides all
+style-names that the @samp{ODT} exporter relies on.  Unless this condition is
+met, the output is going to be less than satisfactory.  So it is highly
+recommended that you only work with templates that are directly derived from
+the factory settings.
 
 @node Links in @acronym{ODT} export, Tables in @acronym{ODT} export, Applying Custom Styles, OpenDocument Text export
 @subsection Links in @acronym{ODT} export