[Orgmode] Re: [PATCH] Re: Custom docbook stylesheets.

[Baoqiu Cui]

Hi Carsten,

Carsten Dominik <address@hidden> writes:

> Dear Baoqiu,
>
> thanks for the patch, I applied it.  Can you please also make a patch
> for the documentation - I think #+XSLT must be mentioned in the export
> chapter....
>
> And an entry for the Changes.org file would indeed be nice, can you
> write that as well?

Thanks for applying the previous patch.  Attached below please find the
2nd patch that mainly covers the documentation changes, which include

  1. Some changes in org.texi to cover `#+XSLT'.
  2. An entry in Changes.org about the incompatible change.
  3. A small change in org-exp.el to include `#+XSLT' in
     org-get-current-options().

Hope I did not miss anything important.  Free feel to change the wording
or add anything that you'd like to add.

diff --git a/ORGWEBPAGE/Changes.org b/ORGWEBPAGE/Changes.org
index b7352b3..eab265b 100644
--- a/ORGWEBPAGE/Changes.org
+++ b/ORGWEBPAGE/Changes.org
@@ -14,6 +14,47 @@
  :CUSTOM_ID: v6.36
  :END:
 
+** Incompatible Changes
+
+*** Customizable variable changes for DocBook exporter
+
+To make it more flexible for users to provide DocBook exporter
+related commands, we start to use format-spec to format the
+commands in this release.  If you use DocBook exporter and use it
+to export Org files to PDF and/or FO format, the settings of the
+following two customizable variables need to be changed:
+
+1. =org-export-docbook-xslt-proc-command=
+2. =org-export-docbook-xsl-fo-proc-command=
+
+Instead of using =%s= in the format control string for all
+arguments, now we use /three/ different format spec characters:
+
+1. =%i=: input file argument
+2. =%o=: output file argument
+3. =%s=: XSLT stylesheet argument
+
+For example, if you set =org-export-docbook-xslt-proc-command= to
+
+: java com.icl.saxon.StyleSheet -o %s %s /path/to/docbook.xsl
+
+in the past, now you need to change it to
+
+: java com.icl.saxon.StyleSheet -o %o %i %s
+
+and set a new customizable variable called
+=org-export-docbook-xslt-stylesheet= to =/path/to/docbook.xsl=.
+
+Please check the documentation of these two variables for more
+details and other examples.
+
+Along with the introduction of variable
+=org-export-docbook-xslt-stylesheet=, we also added a new
+in-buffer setting called =#+XSLT:=.  You can use this setting to
+specify the XSLT stylesheet that you want to use on a per-file
+basis.  This setting overrides
+=org-export-docbook-xslt-stylesheet=.
+
 ** Details
 *** Inline display of linked images
 
diff --git a/doc/org.texi b/doc/org.texi
index d2b7904..7b6afd7 100644
--- a/doc/org.texi
+++ b/doc/org.texi
@@ -9020,6 +9020,7 @@ Insert template with export options, see example below.
 #+LATEX_HEADER: extra line(s) for the LaTeX header, like address@hidden@}
 #+EXPORT_SELECT_TAGS:   Tags that select a tree for export
 #+EXPORT_EXCLUDE_TAGS:  Tags that exclude a tree from export
+#+XSLT:        the XSLT stylesheet used by DocBook exporter to generate FO file
 @end example
 
 @noindent
@@ -9860,7 +9861,7 @@ For more information, see the documentation on Worg.
 @section DocBook export
 @cindex DocBook export
 @cindex PDF export
address@hidden Cui, Baoqui
address@hidden Cui, Baoqiu
 
 Org contains a DocBook exporter written by Baoqiu Cui.  Once an Org file is
 exported to DocBook format, it can be further processed to produce other
@@ -9907,6 +9908,15 @@ need to have XSLT processor and XSL-FO processor 
software installed on your
 system.  Check variables @code{org-export-docbook-xslt-proc-command} and
 @code{org-export-docbook-xsl-fo-proc-command}.
 
address@hidden org-export-docbook-xslt-stylesheet
+The stylesheet argument (`%s') in variable
address@hidden is in general replaced by the
+value of variable @code{org-export-docbook-xslt-stylesheet}, which is
+expected to be set by the user.  You can also tell DocBook exporter which
+stylesheet to use on a per-file basis by adding an in-buffer setting
+`#+XSLT:' to the Org file.  The setting of `#+XSLT:' overrides
address@hidden
+
 @kindex C-c C-e v D
 @item C-c C-e v D
 Export only the visible part of the document.
@@ -11001,8 +11011,8 @@ keys.  The corresponding variable is 
@code{org-tag-alist}.
 @item #+TBLFM:
 This line contains the formulas for the table directly above the line.
 @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,
address@hidden #+OPTIONS:, #+BIND:
address@hidden #+DESCRIPTION:, #+KEYWORDS:
address@hidden #+OPTIONS:, #+BIND:, #+XSLT:,
address@hidden #+DESCRIPTION:, #+KEYWORDS:,
 @itemx #+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,
 @itemx #+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:
 These lines provide settings for exporting files.  For more details see
diff --git a/lisp/org-exp.el b/lisp/org-exp.el
index 068f9c5..a4f9ac3 100644
--- a/lisp/org-exp.el
+++ b/lisp/org-exp.el
@@ -2574,6 +2574,7 @@ Does include HTML export options as well as TODO and 
CATEGORY stuff."
 #+EXPORT_EXCLUDE_TAGS: %s
 #+LINK_UP:   %s
 #+LINK_HOME: %s
+#+XSLT: 
 #+CATEGORY:  %s
 #+SEQ_TODO:  %s
 #+TYP_TODO:  %s

Thanks,

-- 
Baoqiu