diff --git a/doc/org.texi b/doc/org.texi index 60ea12ae7..f5cb8389a 100644 --- a/doc/org.texi +++ b/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