filter-markup.org 11 KB


<p>
Copyright (C) 2013  Charles C. Berry
</p>

<p>
This program is free software: you can redistribute it and/or modify
</p>
<p>
it under the terms of the GNU General Public License as published by
</p>
<p>
the Free Software Foundation, either version 3 of the License, or
</p>
<p>
(at your option) any later version.
</p>

<p>
This program is distributed in the hope that it will be useful,
</p>
<p>
but WITHOUT ANY WARRANTY; without even the implied warranty of
</p>
<p>
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
</p>
<p>
GNU General Public License for more details.
</p>

<p>
For a copy of the GNU General Public License, see
</p>
<p>
<http://www.gnu.org/licenses/>.
</p>


Filters in the Exporter

The exporter in ox.el has more than 50 elements that can be filtered. Developers can write filters for new backends, and users can write filters to customize output to their individual needs.

Understanding Elements and Filters

Figuring out how to craft a filter to customize output requires detailed knowledge of what the elements are and how they are rendered by a backend. It can be fairly difficult to sort this out and keep it all in mind by just reading the code.

One way to understand an element and the markup applied to it by an export backend is to write a filter that will mark the element.

For example, the function


 (defun ox-mrkup-filter-bold
    (text back-end info)
    "Markup TEXT as <bold>TEXT</bold>. Ignore BACK-END and INFO."
    (format "<bold>%s</bold>" text))

will show a bold element inside the tags <bold> and </bold>.

Using that filter with the latex backend will render

This text should be in BOLD.

as

 This text should be in \textbf{BOLD}.

A Complete Set of Filter Functions

Here is a complete set of filter functions to provide markup tags.

(defun ox-mrkup-filter-body (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-bold (text back-end info) "Markup TEXT as TEXT. Ignore BACK-END and INFO." (format "%s" text)) (defun ox-mrkup-filter-babel-call (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-center-block (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-clock (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-code (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-comment (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-comment-block (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-diary-sexp (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-drawer (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-dynamic-block (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-entity (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-example-block (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-export-block (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-export-snippet (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-final-output (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-fixed-width (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-footnote-definition (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-footnote-reference (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-headline (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-horizontal-rule (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-inline-babel-call (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-inline-src-block (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-inlinetask (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-italic (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-item (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-keyword (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-latex-environment (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-latex-fragment (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-line-break (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-link (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-node-property (text back-end info) (format "%s" text)) ;; dont (defun ox-mrkup-filter-options ...) (defun ox-mrkup-filter-paragraph (text back-end info) (format "%s" text)) ;; dont (defun ox-mrkup-filter-parse-tree ...) (defun ox-mrkup-filter-plain-list (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-plain-text (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-planning (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-property-drawer (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-quote-block (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-radio-target (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-section (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-special-block (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-src-block (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-statistics-cookie (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-strike-through (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-subscript (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-superscript (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-table (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-table-cell (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-table-row (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-target (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-timestamp (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-underline (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-verbatim (text back-end info) (format "%s" text)) (defun ox-mrkup-filter-verse-block (text back-end info) (format "%s" text))

A LaTeX Backend Example

Here is a derived backend that will use those tags. This backend takes ~latex~ as its parent, but other backends could be used as well. It is called latex2 and can be used like this:

M-: (org-export-to-buffer 'latex2 "latex-buffer-marked")

or

M-: (org-export-to-file 'latex2 "latex-file-marked.tex")

For many purposes only a subset of these might be needed. So the code could be edited to leave only those filters that are wanted.

(require 'ox-latex) (org-export-define-derived-backend 'latex2 'latex :filters-alist '((:filter-body . ox-mrkup-filter-body) (:filter-bold . ox-mrkup-filter-bold) (:filter-babel-call . ox-mrkup-filter-babel-call) (:filter-center-block . ox-mrkup-filter-center-block) (:filter-clock . ox-mrkup-filter-clock) (:filter-code . ox-mrkup-filter-code) (:filter-comment . ox-mrkup-filter-comment) (:filter-comment-block . ox-mrkup-filter-comment-block) (:filter-diary-sexp . ox-mrkup-filter-diary-sexp) (:filter-drawer . ox-mrkup-filter-drawer) (:filter-dynamic-block . ox-mrkup-filter-dynamic-block) (:filter-entity . ox-mrkup-filter-entity) (:filter-example-block . ox-mrkup-filter-example-block) (:filter-export-block . ox-mrkup-filter-export-block) (:filter-export-snippet . ox-mrkup-filter-export-snippet) (:filter-final-output . ox-mrkup-filter-final-output) (:filter-fixed-width . ox-mrkup-filter-fixed-width) (:filter-footnote-definition . ox-mrkup-filter-footnote-definition) (:filter-footnote-reference . ox-mrkup-filter-footnote-reference) (:filter-headline . ox-mrkup-filter-headline) (:filter-horizontal-rule . ox-mrkup-filter-horizontal-rule) (:filter-inline-babel-call . ox-mrkup-filter-inline-babel-call) (:filter-inline-src-block . ox-mrkup-filter-inline-src-block) (:filter-inlinetask . ox-mrkup-filter-inlinetask) (:filter-italic . ox-mrkup-filter-italic) (:filter-item . ox-mrkup-filter-item) (:filter-keyword . ox-mrkup-filter-keyword) (:filter-latex-environment . ox-mrkup-filter-latex-environment) (:filter-latex-fragment . ox-mrkup-filter-latex-fragment) (:filter-line-break . ox-mrkup-filter-line-break) (:filter-link . ox-mrkup-filter-link) (:filter-node-property . ox-mrkup-filter-node-property) ;; omit filter with different args ;; (:filter-options . ox-mrkup-filter-options) (:filter-paragraph . ox-mrkup-filter-paragraph) ;; omit filter with different args ;; (:filter-parse-tree . ox-mrkup-filter-parse-tree) (:filter-plain-list . ox-mrkup-filter-plain-list) (:filter-plain-text . ox-mrkup-filter-plain-text) (:filter-planning . ox-mrkup-filter-planning) (:filter-property-drawer . ox-mrkup-filter-property-drawer) (:filter-quote-block . ox-mrkup-filter-quote-block) (:filter-radio-target . ox-mrkup-filter-radio-target) (:filter-section . ox-mrkup-filter-section) (:filter-special-block . ox-mrkup-filter-special-block) (:filter-src-block . ox-mrkup-filter-src-block) (:filter-statistics-cookie . ox-mrkup-filter-statistics-cookie) (:filter-strike-through . ox-mrkup-filter-strike-through) (:filter-subscript . ox-mrkup-filter-subscript) (:filter-superscript . ox-mrkup-filter-superscript) (:filter-table . ox-mrkup-filter-table) (:filter-table-cell . ox-mrkup-filter-table-cell) (:filter-table-row . ox-mrkup-filter-table-row) (:filter-target . ox-mrkup-filter-target) (:filter-timestamp . ox-mrkup-filter-timestamp) (:filter-underline . ox-mrkup-filter-underline) (:filter-verbatim . ox-mrkup-filter-verbatim) (:filter-verse-block . ox-mrkup-filter-verse-block)))


Options for Adding Filters

Users can add filter functions to the lists in ~org-export-filters-alist~ and subsequent exports will apply those functions accordingly.

Alternatively, writing a derived backend in which the ~:filters-alist~ contains an entry such as:

 (:filter-bold . ox-mrkup-filter-bold)

will result in bold elements being filterd through that function.

The advantage of using a derived backend to experiment with filters is that org-export-filters-alist is not filled with functions that will need to be removed once the experiments have ended.