DocBook export: Installed the new DocBook exporter by Baoqiu Cui

This commit is contained in:
Carsten Dominik 2009-03-30 07:17:09 +02:00
parent daafaf09d8
commit 13b2f06ba4
6 changed files with 1558 additions and 49 deletions

View File

@ -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

View File

@ -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
simple version of an Org file. HTML export allows you to publish a
notes file on the web, while the XOXO format provides a solid base for
exchange with a broad range of other applications. La@TeX{} export lets
you use Org mode and its structured editing functions to easily create
La@TeX{} files. 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.
printing and sharing of notes, ASCII export produces a readable and simple
version of an Org file. HTML export allows you to publish a notes file on
the web, while the XOXO format provides a solid base for exchange with a
broad range of other applications. La@TeX{} export lets you use Org mode and
its structured editing functions to easily create La@TeX{} files. DocBook
export makes it possible to convert Org files to many other formats using
DocBook tools. 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).
@ -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
has rules how to prepare text for rich export. This section summarizes the
markup rule used in an Org mode buffer.
export targets like HTML, La@TeX{}, or DocBook allow much richer formatting,
Org mode has rules how to prepare text for rich export. This section
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
described below in the sections for the individual exporters.
you need to include literal HTML, La@TeX{}, or DocBook code, use the special
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
exported document. Org does this, if a link to an image files does not have
a description part, for example @code{[[./img/a.jpg]]}. If you wish to
define a caption for the image and maybe a label for internal cross
Some backends (HTML, LaTeX, and DocBook) allow to directly include images
into the exported document. Org does this, if a link to an image files does
not have a description part, for example @code{[[./img/a.jpg]]}. If you wish
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
@section Docbook export
@cindex Docbook export
@node DocBook export, XOXO export, LaTeX and PDF export, Exporting
@section 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.
@kindex C-c C-e v
Export as DocBook file, process to PDF, then open the resulting PDF file.
@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.

View File

@ -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.

1317
lisp/org-docbook.el Normal file

File diff suppressed because it is too large Load Diff

View File

@ -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)
(org-export-docbook-preprocess parameters))
(require 'org-docbook nil)
(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))
(eq backend 'docbook))
(when (and textareap (eq backend 'html))
;; 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"
code
"]]>\n</programlisting>\n"))
(concat "\n#+BEGIN_DOCBOOK\n"
rtn
"\n#+END_DOCBOOK\n\n")
)
(setq rtn (org-export-number-lines rtn 'docbook 0 0 num cont rpllbl fmt))
(concat "\n#+BEGIN_DOCBOOK\n"
(org-add-props (concat "<programlisting><![CDATA["
rtn
"]]>\n</programlisting>\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)

View File

@ -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-remember org-table org-timer)))
org-exp org-id org-export-latex org-docbook.el
org-publish org-remember org-table org-timer)))
;;;###autoload
(defun org-reload (&optional uncompiled)