org.texi: Add advanced configuration for export

doc/org.texi

@@ -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 isn’t 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