org.texi: Add advanced configuration for export
This commit is contained in:
parent
f9555eef69
commit
209e071246
191
doc/org.texi
191
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
|
||||
|
|
Loading…
Reference in New Issue