org.texi: Add advanced configuration for export

This commit is contained in:
Nicolas Goaziou 2013-04-14 17:01:26 +02:00
parent f9555eef69
commit 209e071246
1 changed files with 185 additions and 6 deletions

View File

@ -538,7 +538,7 @@ Presentation and sorting
* Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time
* Sorting agenda items:: The order of things
* Filtering/limiting agenda items:: Dynamically narrow the agenda
* Filtering/limiting agenda items:: Dynamically narrow the agenda
Custom agenda views
@ -583,12 +583,13 @@ Exporting
* Export formats:: Available export formats
* Export settings:: Generic export settings
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
* Beamer export:: Turning the file into a presentation
* Beamer export:: Exporting as a Beamer presentation
* HTML export:: Exporting to HTML
* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF
* Markdown export:: Exporting to Markdown
* OpenDocument Text export:: Exporting to OpenDocument Text
* iCalendar export:: Exporting to iCalendar
* Advanced configuration:: Fine-tuning the export output
HTML export
@ -608,7 +609,7 @@ HTML export
* @LaTeX{}/PDF export commands::
* Header and sectioning:: Setting up the export file structure
* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code
* @LaTeX{} specific attributes:: Controlling @LaTeX{} output
* @LaTeX{} specific attributes:: Controlling @LaTeX{} output
OpenDocument Text export
@ -8247,7 +8248,7 @@ associated with the item.
* Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time
* Sorting agenda items:: The order of things
* Filtering/limiting agenda items:: Dynamically narrow the agenda
* Filtering/limiting agenda items:: Dynamically narrow the agenda
@end menu
@node Categories, Time-of-day specifications, Presentation and sorting, Presentation and sorting
@ -10304,6 +10305,7 @@ powerful way of quickly editing tables and lists in HTML, @LaTeX{},
* Markdown export:: Exporting to Markdown
* OpenDocument Text export:: Exporting to OpenDocument Text
* iCalendar export:: Exporting to iCalendar
* Advanced configuration:: Fine-tuning the export output
@end menu
@node The Export Dispatcher, Export formats, Exporting, Exporting
@ -11332,7 +11334,7 @@ nested footnotes, footnotes in tables and footnotes in items' description.
* @LaTeX{}/PDF export commands::
* Header and sectioning:: Setting up the export file structure
* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code
* @LaTeX{} specific attributes:: Controlling @LaTeX{} output
* @LaTeX{} specific attributes:: Controlling @LaTeX{} output
@end menu
@node @LaTeX{}/PDF export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export
@ -12561,7 +12563,7 @@ will take care of updating the @code{rng-schema-locating-files} for you.
@c end opendocument
@node iCalendar export, , OpenDocument Text export, Exporting
@node iCalendar export, Advanced configuration, OpenDocument Text export, Exporting
@section iCalendar export
@cindex iCalendar export
@ -12630,6 +12632,183 @@ and the description from the body (limited to
How this calendar is best read and updated, depends on the application
you are using. The FAQ covers this issue.
@node Advanced configuration, , iCalendar export, Exporting
@section Advanced configuration
@subheading Hooks
@vindex org-export-before-processing-hook
@vindex org-export-before-parsing-hook
Two hooks are run during the first steps of the export process. The first
one, @var{org-export-before-processing-hook} is called before expanding
macros, Babel code and include keywords in the buffer. The second one,
@var{org-export-before-parsing-hook}, as its name suggests, happens just
before parsing the buffer. Their main use is for heavy duties, that is
duties involving structural modifications of the document. For example, one
may want to remove every headline in the buffer during export. The following
code can achieve this:
@example
(defun my-headline-removal (backend)
"Remove all headlines in the current buffer.
BACKEND is the export back-end being used, as a symbol."
(org-map-entries
(lambda () (delete-region (point) (progn (forward-line) (point))))))
(add-hook 'org-export-before-parsing-hook 'my-headline-removal)
@end example
Note that functions used in these hooks require a mandatory argument,
a symbol representing the back-end used.
@subheading Filters
@cindex Filters, exporting
Filters are lists of functions applied on a specific part of the output from
a given back-end. More explicitly, each time a back-end transforms an Org
object or element into another language, all functions within a given filter
type are called in turn on the string produced. The string returned by the
last function will be the one used in the final output.
There are filters sets for each type of element or object, for plain text,
for the parse tree, for the export options and for the final output. They
are all named after the same scheme: @code{org-export-filter-TYPE-functions},
where @code{TYPE} is the type targeted by the filter. Valid types are:
@itemize @minus
@item bold
@item babel-call
@item center-block
@item clock
@item code
@item comment
@item comment-block
@item diary-sexp
@item drawer
@item dynamic-block
@item entity
@item example-block
@item export-block
@item export-snippet
@item final-output
@item fixed-width
@item footnote-definition
@item footnote-reference
@item headline
@item horizontal-rule
@item inline-babel-call
@item inline-src-block
@item inlinetask
@item italic
@item item
@item keyword
@item latex-environment
@item latex-fragment
@item line-break
@item link
@item node-property
@item options
@item paragraph
@item parse-tree
@item plain-list
@item plain-text
@item planning
@item property-drawer
@item quote-block
@item quote-section
@item radio-target
@item section
@item special-block
@item src-block
@item statistics-cookie
@item strike-through
@item subscript
@item superscript
@item table
@item table-cell
@item table-row
@item target
@item timestamp
@item underline
@item verbatim
@item verse-block
@end itemize
For example, the following snippet allows me to use non-breaking spaces in
the Org buffer and get them translated into @LaTeX{} without using the
@code{\nbsp} macro (where @code{_} stands for the non-breaking space):
@example
(defun my-latex-filter-nobreaks (text backend info)
"Ensure \" \" are properly handled in LaTeX export."
(when (org-export-derived-backend-p backend 'latex)
(replace-regexp-in-string " " "~" text)))
(add-to-list 'org-export-filter-plain-text-functions
'my-latex-filter-nobreaks)
@end example
Three arguments must be provided to a fiter: the code being changed, the
back-end used, and some information about the export process. You can safely
ignore the third argument for most purposes. Note the use of
@code{org-export-derived-backend-p}, which ensures that the filter will only
be applied when using @code{latex} back-end or any other back-end derived
from it (e.g., @code{beamer}).
@subheading Extending an existing back-end
This is obviously the most powerful customization, since the changes happen
at the parser level. Indeed, some export back-ends are built as extensions
of other ones (e.g. Markdown back-end an extension of HTML back-end).
Extending a back-end means that if an element type is not transcoded by the
new back-end, it will be handled by the original one. Hence you can extend
specific parts of a back-end without too much work.
As an example, imagine we want the @code{ascii} back-end to display the
language used in a source block, when it is available, but only when some
attribute is non-nil, like the following:
@example
#+ATTR_ASCII: :language t
@end example
Because that back-end is lacking in that area, we are going to create a new
back-end, @code{my-ascii} that will do the job.
@example
(defun my-ascii-src-block (src-block contents info)
"Transcode a SRC-BLOCK element from Org to ASCII.
CONTENTS is nil. INFO is a plist used as a communication
channel."
(if (not (org-export-read-attribute :attr_ascii src-block :language))
(org-export-with-backend 'ascii src-block contents info)
(concat
(format ",--[ %s ]--\n%s`----"
(org-element-property :language src-block)
(replace-regexp-in-string
"^" "| "
(org-element-normalize-string
(org-export-format-code-default src-block info)))))))
(org-export-define-derived-backend 'my-ascii 'ascii
:translate-alist '((src-block . my-ascii-src-block)))
@end example
The @code{my-ascii-src-block} function looks at the attribute above the
element. If it isnt true, it gives hand to the @code{ascii} back-end.
Otherwise, it creates a box around the code, leaving room for the language.
A new back-end is then created. It only changes its behaviour when
translating @code{src-block} type element. Now, all it takes to use the new
back-end is calling the following from an Org buffer:
@example
(org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
@end example
It is obviously possible to write an interactive function for this, install
it in the export dispatcher menu, and so on.
@node Publishing, Working With Source Code, Exporting, Top
@chapter Publishing
@cindex publishing