DocBook export: Installed the new DocBook exporter by Baoqiu Cui

Makefile

@@ -72,6 +72,7 @@ LISPF      = 	org.el			\
 	     	org-compat.el		\
 		org-exp.el		\
 		org-export-latex.el	\
+		org-docbook.el		\
 		org-faces.el		\
 		org-footnote.el		\
 		org-gnus.el		\
@@ -323,6 +324,7 @@ lisp/org-colview-xemacs.elc:      lisp/org.el
 lisp/org-compat.elc:       lisp/org-macs.el
 lisp/org-exp.elc:          lisp/org.el lisp/org-agenda.el
 lisp/org-export-latex.elc: lisp/org.el lisp/org-exp.el
+lisp/org-docbook.elc:      lisp/org.el lisp/org-exp.el
 lisp/org-faces.elc:        lisp/org-macs.el lisp/org-compat.el
 lisp/org-footnotes.elc:    lisp/org-macs.el lisp/org-compat.el
 lisp/org-gnus.elc:         lisp/org.el

doc/org.texi

@@ -296,7 +296,7 @@ Exporting
 * ASCII export::                Exporting to plain ASCII
 * HTML export::                 Exporting to HTML
 * LaTeX and PDF export::        Exporting to LaTeX, and processing to PDF
-* Docbook export::              Exporting to Docbook
+* DocBook export::              Exporting to DocBook
 * XOXO export::                 Exporting to XOXO
 * iCalendar export::            Exporting in iCalendar format
 
@@ -337,6 +337,15 @@ LaTeX and PDF export
 * Tables in LaTeX export::      Options for exporting tables to LaTeX
 * Images in LaTeX export::      How to insert figures into LaTeX output
 
+DocBook export
+
+* DocBook export commands::     How to invoke DocBook export
+* Quoting DocBook code::        Incorporating DocBook code in Org files
+* Recursive sections::          Recursive sections in DocBook
+* Tables in DocBook export::    Tables are exported as HTML tables
+* Images in DocBook export::    How to insert figures into DocBook output
+* Special characters::          How to handle special characters
+
 Publishing
 
 * Configuration::               Defining projects
@@ -7743,15 +7752,16 @@ is normal.
 @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
+printing and sharing of notes, ASCII export produces a readable and simple
-simple version of an Org file.  HTML export allows you to publish a
+version of an Org file.  HTML export allows you to publish a notes file on
-notes file on the web, while the XOXO format provides a solid base for
+the web, while the XOXO format provides a solid base for exchange with a
-exchange with a broad range of other applications. La@TeX{} export lets
+broad range of other applications. La@TeX{} export lets you use Org mode and
-you use Org mode and its structured editing functions to easily create
+its structured editing functions to easily create La@TeX{} files.  DocBook
-La@TeX{} files.  To incorporate entries with associated times like
+export makes it possible to convert Org files to many other formats using
-deadlines or appointments into a desktop calendar program like iCal,
+DocBook tools.  To incorporate entries with associated times like deadlines
-Org mode can also produce extracts in the iCalendar format.  Currently
+or appointments into a desktop calendar program like iCal, Org mode can also
-Org mode only supports export, not import of these different formats.
+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).
@@ -7764,7 +7774,7 @@ enabled (default in Emacs 23).
 * ASCII export::                Exporting to plain ASCII
 * HTML export::                 Exporting to HTML
 * LaTeX and PDF export::        Exporting to LaTeX, and processing to PDF
-* Docbook export::              Exporting to Docbook
+* DocBook export::              Exporting to DocBook
 * XOXO export::                 Exporting to XOXO
 * iCalendar export::            Exporting in iCalendar format
 @end menu
@@ -7772,11 +7782,11 @@ enabled (default in Emacs 23).
 @node Markup rules, Selective export, Exporting, Exporting
 @section Markup rules
 
-When exporting Org mode documents,  the exporter tries to reflect the
+When exporting Org mode documents, the exporter tries to reflect the
 structure of the document as accurately as possible in the back-end.  Since
-export targets like HTML or La@TeX{} allow much richer formatting, Org mode
+export targets like HTML, La@TeX{}, or DocBook allow much richer formatting,
-has rules how to prepare text for rich export.  This section summarizes the
+Org mode has rules how to prepare text for rich export.  This section
-markup rule used in an Org mode buffer.
+summarizes the markup rule used in an Org mode buffer.
 
 @menu
 * Document title::              How the document title is determined
@@ -7860,8 +7870,8 @@ the table of contents entirely by configuring the variable
 
 Org mode normally exports the text before the first headline, and even uses
 the first line as the document title.  The text will be fully marked up.  If
-you need to include literal HTML or La@TeX{} code, use the special constructs
+you need to include literal HTML, La@TeX{}, or DocBook code, use the special
-described below in the sections for the individual exporters.
+constructs described below in the sections for the individual exporters.
 
 @vindex org-export-skip-text-before-1st-heading
 Some people like to use the space before the first headline for setup and
@@ -8078,10 +8088,10 @@ a caption and a label for cross references:
 @subheading Inlined Images
 @cindex inlined images, markup rules
 
-Some backends (HTML and LaTeX) allow to directly include images into the
+Some backends (HTML, LaTeX, and DocBook) allow to directly include images
-exported document.  Org does this, if a link to an image files does not have
+into the exported document.  Org does this, if a link to an image files does
-a description part, for example @code{[[./img/a.jpg]]}.  If you wish to
+not have a description part, for example @code{[[./img/a.jpg]]}.  If you wish
-define a caption for the image and maybe a label for internal cross
+to define a caption for the image and maybe a label for internal cross
 references, you can use (before, but close to the link)
 
 @example
@@ -8709,7 +8719,7 @@ You can choose default values for these options by customizing the variable
 @code{org-infojs-options}.  If you always want to apply the script to your
 pages, configure the variable @code{org-export-html-use-infojs}.
 
-@node LaTeX and PDF export, Docbook export, HTML export, Exporting
+@node LaTeX and PDF export, DocBook export, HTML export, Exporting
 @section LaTeX and PDF export
 @cindex LaTeX export
 @cindex PDF export
@@ -8874,25 +8884,193 @@ pdflatex (@file{png}, @file{jpg}, and @file{pdf} files).  If you process your
 files in a different way, you may need to customize the variable
 @code{org-export-latex-inline-image-extensions}.
 
-@node Docbook export, XOXO export, LaTeX and PDF export, Exporting
+@node DocBook export, XOXO export, LaTeX and PDF export, Exporting
-@section Docbook export
+@section DocBook export
-@cindex Docbook export
+@cindex DocBook export
+@cindex PDF export
 
-The Docbook exporter was contributed to Org by Baoqiu Cui.
+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
+formats, including PDF, HTML, man pages, etc, using many available DocBook
+tools and stylesheets.
 
+Currently DocBook exporter only supports DocBook V5.0.
+
+@menu
+* DocBook export commands::     How to invoke DocBook export
+* Quoting DocBook code::        Incorporating DocBook code in Org files
+* Recursive sections::          Recursive sections in DocBook
+* Tables in DocBook export::    Tables are exported as HTML tables
+* Images in DocBook export::    How to insert figures into DocBook output
+* Special characters::          How to handle special characters
+@end menu
+
+@node DocBook export commands, Quoting DocBook code, DocBook export, DocBook export
+@subsection DocBook export commands
+
+@cindex region, active
+@cindex active region
+@cindex transient-mark-mode
 @table @kbd
 @kindex C-c C-e D
 @item C-c C-e D
-Export as Docbook file @file{myfile.xml}.
+Export as DocBook file.  For an Org file @file{myfile.org}, the DocBook XML
+file will be @file{myfile.xml}.  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 as, or inherits, an @code{EXPORT_FILE_NAME}
+property, that name will be used for the export.
 @kindex C-c C-e V
 @item C-c C-e V
-Export as Docbook file and launch a viewer.
+Export as DocBook file, process to PDF, then open the resulting PDF file.
-@kindex C-c C-e v
+
+@vindex org-export-docbook-xslt-proc-command
+@vindex org-export-docbook-xsl-fo-proc-command
+Note that, in order to produce PDF output based on exported DocBook file, you
+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}.
+
+@kindex C-c C-e v D
 @item C-c C-e v D
 Export only the visible part of the document.
 @end table
 
-@node XOXO export, iCalendar export, Docbook export, Exporting
+@node Quoting DocBook code, Recursive sections, DocBook export commands, DocBook export
+@subsection Quoting DocBook code
+
+You can quote DocBook code in Org files and copy it verbatim into exported
+DocBook file with the following constructs:
+
+@example
+#+DOCBOOK: Literal DocBook code for export
+@end example
+
+@noindent or
+@cindex #+BEGIN_DOCBOOK
+
+@example
+#+BEGIN_DOCBOOK
+All lines between these markers are exported by DocBook exporter
+literally.
+#+END_DOCBOOK
+@end example
+
+For example, you can use the following lines to include a DocBook warning
+admonition.  As what this warning says, you should pay attention to the
+document context when quoting DocBook code in Org files.  You may make
+exported DocBook XML file invalid if not quoting DocBook code correctly.
+
+@example
+#+BEGIN_DOCBOOK
+<warning>
+  <para>You should know what you are doing when quoting DocBook XML code
+  in your Org file.  Invalid DocBook XML file may be generated by
+  DocBook exporter if you are not careful!</para>
+</warning>
+#+END_DOCBOOK
+@end example
+
+@node Recursive sections, Tables in DocBook export, Quoting DocBook code, DocBook export
+@subsection Recursive sections
+@cindex DocBook recursive sections
+
+DocBook exporter exports Org files as articles using the @code{article}
+element in DocBook.  Recursive sections, i.e. @code{section} elements, are
+used in exported articles.  Top level headlines in Org files are exported as
+top level sections, and lower level headlines are exported as nested
+sections.  The entire structure of Org files will be exported completely, no
+matter how many nested levels of headlines there are.
+
+Using recursive sections makes it easy to port and reuse exported DocBook
+code in other DocBook document types like @code{book} or @code{set}.
+
+@node Tables in DocBook export, Images in DocBook export, Recursive sections, DocBook export
+@subsection Tables in DocBook export
+@cindex tables, in DocBook export
+
+Tables in Org files are exported as HTML tables, which are supported since
+DocBook V4.3.
+
+If a table does not have a caption, an informal table is generated using the
+@code{informaltable} element; otherwise, a formal table will be generated
+using the @code{table} element.
+
+@node Images in DocBook export, Special characters, Tables in DocBook export, DocBook export
+@subsection Images in DocBook export
+@cindex images, inline in DocBook
+@cindex inlining images in DocBook
+
+Images that are linked to without a description part in the link, like
+@samp{[[file:img.jpg]]} or @samp{[[./img.jpg]]}, will be exported to DocBook
+using @code{mediaobject} elements.  Each @code{mediaobject} element contains
+an @code{imageobject} that wraps an @code{imagedata} element.  If you have
+specified a caption for an image as described in @ref{Markup rules}, a
+@code{caption} element will be added in @code{mediaobject}.  If a label is
+also specified, it will be exported as an @code{xml:id} attribute of the
+@code{mediaobject} element.
+
+@vindex org-export-docbook-default-image-attributes
+Image attributes supported by the @code{imagedata} element, like @code{align}
+or @code{width}, can be specified in two ways: you can either customize
+variable @code{org-export-docbook-default-image-attributes} or use the
+@code{#+ATTR_DOCBOOK:} line.  Attributes sepcified in variable
+@code{org-export-docbook-default-image-attributes} are applied to all inline
+images in the Org file to be exported (unless they are overwritten by image
+attributes specified in @code{#+ATTR_DOCBOOK:} lines).
+
+The @code{#+ATTR_DOCBOOK:} line can be used to specify additional image
+attributes or overwrite default image attributes for individual images.  If
+the same attribute appears in both the @code{#+ATTR_DOCBOOK:} line and
+variable @code{org-export-docbook-default-image-attributes}, the former
+overwrites the latter.  Here is an example about how image attributes can be
+set:
+
+@example
+#+CAPTION:    The logo of Org-mode
+#+LABEL:      unicorn-svg
+#+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
+[[./img/org-mode-unicorn.svg]]
+@end example
+
+@vindex org-export-docbook-inline-image-extensions
+By default, DocBook exporter recognizes the following image file types:
+@file{jpeg}, @file{jpg}, @file{png}, @file{gif}, and @file{svg}.  You can
+customize variable @code{org-export-docbook-inline-image-extensions} to add
+more types to this list as long as DocBook supports them.
+
+@node Special characters,  , Images in DocBook export, DocBook export
+@subsection Special characters in DocBook export
+@cindex Special characters in DocBook export
+
+@vindex org-export-docbook-doctype
+@vindex org-html-entities
+Special characters that are written in TeX-like syntax, such as @code{\alpha}
+@code{\Gamma}, and @code{\Zeta}, are supported by DocBook exporter.  These
+characters are rewritten to XML entities, like @code{&alpha;},
+@code{&Gamma;}, and @code{&Zeta;}, based on the list saved in variable
+@code{org-html-entities}.  As long as the generated DocBook file includes the
+corresponding entities, these special characters are recognized.
+
+You can customize variable @code{org-export-docbook-doctype} to include the
+entities you need.  For example, you can set variable
+@code{org-export-docbook-doctype} to the following value to recognize all
+special characters included in XHTML entities:
+
+@example
+"<!DOCTYPE article [
+<!ENTITY % xhtml1-symbol PUBLIC
+\"-//W3C//ENTITIES Symbol for HTML//EN//XML\"
+\"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\"
+>
+%xhtml1-symbol;
+]>
+"
+@end example
+
+@node XOXO export, iCalendar export, DocBook export, Exporting
 @section XOXO export
 @cindex XOXO export
 
@@ -10939,6 +11117,8 @@ calculations and improved XEmacs compatibility, in particular by porting
 @item
 @i{Sacha Chua} suggested to copy some linking code from Planner.
 @item
+@i{Baoqiu Cui} contributed the DocBook exporter.
+@item
 @i{Eddward DeVilla} proposed and tested checkbox statistics.  He also
 came up with the idea of properties, and that there should be an API for
 them.

lisp/ChangeLog

@@ -1,3 +1,11 @@
+2009-03-30  Carsten Dominik  <carsten.dominik@gmail.com>
+
+	* org-docbook.el (org-id-find-id-file): Add function declaration.
+
+	* org.el (org-require-autoloaded-modules): Add org-docbook.el.
+
+	* org-docbook.el: New file.
+
 2009-03-28  Carsten Dominik  <carsten.dominik@gmail.com>
 
 	* org.el (org-reftex-citation): New command.

lisp/org-exp.el

@@ -1171,7 +1171,8 @@ value of `org-export-run-in-background'."
 \[p] export as LaTeX and process to PDF
 \[d] export as LaTeX, process to PDF, and open the resulting PDF document
 
-\[D] export as Docbook             [V] export and view Docbook file
+\[D] export as DocBook
+\[V] export as DocBook, process to PDF, and open the resulting PDF document
 
 \[x] export as XOXO
 
@@ -1191,7 +1192,7 @@ value of `org-export-run-in-background'."
 	    (?R org-export-region-as-html nil)
 	    (?x org-export-as-xoxo t)
 	    (?D org-export-as-docbook t)
-	    (?V org-export-as-docbook-and-open t)
+	    (?V org-export-as-docbook-pdf-and-open t)
 	    (?l org-export-as-latex t)
 	    (?p org-export-as-pdf t)
 	    (?d org-export-as-pdf-and-open t)
@@ -1705,11 +1706,11 @@ on this string to produce the exported version."
       ;; HTML-specific preprocessing
       (when htmlp
 	(org-export-html-preprocess parameters))
-
+      
       ;; DocBook-specific preprocessing
       (when docbookp
-	(require 'org-export-docbook nil)
+	(require 'org-docbook nil)
-        (org-export-docbook-preprocess parameters))
+	(org-export-docbook-preprocess parameters))
 
       ;; Remove or replace comments
       (org-export-handle-comments (plist-get parameters :comments))
@@ -1998,7 +1999,7 @@ from the buffer."
 (defun org-export-select-backend-specific-text (backend)
   (let ((formatters
 	 '((docbook "DOCBOOK" "BEGIN_DOCBOOK" "END_DOCBOOK")
-           (html "HTML" "BEGIN_HTML" "END_HTML")
+	   (html "HTML" "BEGIN_HTML" "END_HTML")
 	   (ascii "ASCII" "BEGIN_ASCII" "END_ASCII")
 	   (latex "LaTeX" "BEGIN_LaTeX" "END_LaTeX")))
 	(case-fold-search t)
@@ -2493,8 +2494,7 @@ Numbering lines works for all three major backends (html, latex, and ascii)."
 		   (org-count-lines code))
 	    fmt (if (string-match "-l[ \t]+\"\\([^\"\n]+\\)\"" opts)
 		    (match-string 1 opts)))
-      (when (or (and textareap (eq backend 'html))
+      (when (and textareap (eq backend 'html))
-                (eq backend 'docbook))
 	;; we cannot use numbering or highlighting.
 	(setq num nil cont nil lang nil))
       (if keepp (setq rpllbl 'keep))
@@ -2511,13 +2511,13 @@ Numbering lines works for all three major backends (html, latex, and ascii)."
       ;; Now backend-specific coding
       (cond
        ((eq backend 'docbook)
-        (setq rtn (concat "<programlisting><![CDATA[\n"
+	(setq rtn (org-export-number-lines rtn 'docbook 0 0 num cont rpllbl fmt))
-                          code
+	(concat "\n#+BEGIN_DOCBOOK\n"
-                          "]]>\n</programlisting>\n"))
+		(org-add-props (concat "<programlisting><![CDATA["
-        (concat "\n#+BEGIN_DOCBOOK\n"
+				       rtn
-                rtn
+				       "]]>\n</programlisting>\n")
-                "\n#+END_DOCBOOK\n\n")
+		    '(org-protected t))
-        )
+		"#+END_DOCBOOK\n"))
        ((eq backend 'html)
 	;; We are exporting to HTML
 	(when lang
@@ -2607,6 +2607,7 @@ Numbering lines works for all three major backends (html, latex, and ascii)."
 					 fmt))
 	     ((eq backend 'ascii) fmt)
 	     ((eq backend 'latex) fmt)
+	     ((eq backend 'docbook) fmt)
 	     (t "")))
 	   (label-format (or label-format org-coderef-label-format))
 	   (label-pre (if (string-match "%s" label-format)
@@ -3091,10 +3092,10 @@ continue to use it.  The prefix arg ARG is passed through to the exporting
 command."
   (interactive
    (list (progn
-	   (message "Export visible: [a]SCII  [h]tml  [b]rowse HTML [H/R]uffer with HTML  [x]OXO  [ ]keep buffer")
+	   (message "Export visible: [a]SCII  [h]tml  [b]rowse HTML [H/R]uffer with HTML  [D]ocBook  [x]OXO  [ ]keep buffer")
 	   (read-char-exclusive))
 	 current-prefix-arg))
-  (if (not (member type '(?a ?\C-a ?b ?\C-b ?h ?x ?\ )))
+  (if (not (member type '(?a ?\C-a ?b ?\C-b ?h ?D ?x ?\ )))
       (error "Invalid export key"))
   (let* ((binding (cdr (assoc type
 			      '((?a . org-export-as-ascii)
@@ -3104,6 +3105,7 @@ command."
 				(?h . org-export-as-html)
 				(?H . org-export-as-html-to-buffer)
 				(?R . org-export-region-as-html)
+				(?D . org-export-as-docbook)
 				(?x . org-export-as-xoxo)))))
 	 (keepp (equal type ?\ ))
 	 (file buffer-file-name)

lisp/org.el

@@ -14596,8 +14596,8 @@ With optional NODE, go directly to that node."
   (interactive)
   (mapc 'require
 	'(org-agenda org-archive org-attach org-clock org-colview
-		     org-exp org-id org-export-latex org-publish
+		     org-exp org-id org-export-latex org-docbook.el
-		     org-remember org-table org-timer)))
+		     org-publish org-remember org-table org-timer)))
 
 ;;;###autoload
 (defun org-reload (&optional uncompiled)