Function: org-export-define-backend

org-export-define-backend is a byte-compiled function defined in ox.el.gz.

Signature

(org-export-define-backend BACKEND TRANSCODERS &rest BODY)

Documentation

Define a new backend BACKEND.

TRANSCODERS is an alist between object or element types and functions handling them.

These functions should return a string without any trailing space, or nil. They must accept three arguments: the object or element itself, its contents or nil when it isn't recursive and the property list used as a communication channel.

Contents, when not nil, are stripped from any global indentation
(although the relative one is preserved). They also always end
with a single newline character.

If, for a given type, no function is found, that element or object type will simply be ignored, along with any blank line or white space at its end. The same will happen if the function returns the nil value. If that function returns the empty string, the type will be ignored, but the blank lines or white spaces will be kept.

In addition to element and object types, one function can be associated to the template (or inner-template) symbol and another one to the plain-text symbol.

The former returns the final transcoded string, and can be used to add a preamble and a postamble to document's body. It must accept two arguments: the transcoded string and the property list containing export options. A function associated to template will not be applied if export has option "body-only". A function associated to inner-template is always applied.

The latter, when defined, is to be called on every text not recognized as an element or an object. It must accept two arguments: the text string and the information channel. It is an appropriate place to protect special chars relative to the backend.

BODY can start with pre-defined keyword arguments. The following keywords are understood:

  :filters-alist

    Alist between filters and function, or list of functions,
    specific to the backend. See org-export-filters-alist for
    a list of all allowed filters. Filters defined here
    shouldn't make a backend test, as it may prevent backends
    derived from this one to behave properly.

  :menu-entry

    Menu entry for the export dispatcher. It should be a list
    like:

      (KEY DESCRIPTION-OR-ORDINAL ACTION-OR-MENU)

    where :

      KEY is a free character selecting the backend.

      DESCRIPTION-OR-ORDINAL is either a string or a number.

      If it is a string, is will be used to name the backend in
      its menu entry. If it is a number, the following menu will
      be displayed as a sub-menu of the backend with the same
      KEY. Also, the number will be used to determine in which
      order such sub-menus will appear (lowest first).

      ACTION-OR-MENU is either a function or an alist.

      If it is an action, it will be called with four
      arguments (booleans): ASYNC, SUBTREEP, VISIBLE-ONLY and
      BODY-ONLY. See org-export-as for further explanations on
      some of them.

      If it is an alist, associations should follow the
      pattern:

        (KEY DESCRIPTION ACTION)

      where KEY, DESCRIPTION and ACTION are described above.

    Valid values include:

      (?m "My Special Backend" my-special-export-function)

      or

       (?l "Export to LaTeX"
           ((?p "As PDF file" org-latex-export-to-pdf)
            (?o "As PDF file and open"
                (lambda (a s v b)
                  (if a (org-latex-export-to-pdf t s v b)
                    (org-open-file
                     (org-latex-export-to-pdf nil s v b)))))))

      or the following, which will be added to the previous
      sub-menu,

       (?l 1
          ((?B "As TEX buffer (Beamer)" org-beamer-export-as-latex)
           (?P "As PDF file (Beamer)" org-beamer-export-to-pdf)))

  :options-alist

    Alist between backend specific properties introduced in
    communication channel and how their value are acquired. See
    org-export-options-alist for more information about
    structure of the values.

Source Code

;; Defined in /usr/src/emacs/lisp/org/ox.el.gz
(defun org-export-define-backend (backend transcoders &rest body)
  "Define a new backend BACKEND.

TRANSCODERS is an alist between object or element types and
functions handling them.

These functions should return a string without any trailing
space, or nil.  They must accept three arguments: the object or
element itself, its contents or nil when it isn't recursive and
the property list used as a communication channel.

Contents, when not nil, are stripped from any global indentation
\(although the relative one is preserved).  They also always end
with a single newline character.

If, for a given type, no function is found, that element or
object type will simply be ignored, along with any blank line or
white space at its end.  The same will happen if the function
returns the nil value.  If that function returns the empty
string, the type will be ignored, but the blank lines or white
spaces will be kept.

In addition to element and object types, one function can be
associated to the `template' (or `inner-template') symbol and
another one to the `plain-text' symbol.

The former returns the final transcoded string, and can be used
to add a preamble and a postamble to document's body.  It must
accept two arguments: the transcoded string and the property list
containing export options.  A function associated to `template'
will not be applied if export has option \"body-only\".
A function associated to `inner-template' is always applied.

The latter, when defined, is to be called on every text not
recognized as an element or an object.  It must accept two
arguments: the text string and the information channel.  It is an
appropriate place to protect special chars relative to the
backend.

BODY can start with pre-defined keyword arguments.  The following
keywords are understood:

  :filters-alist

    Alist between filters and function, or list of functions,
    specific to the backend.  See `org-export-filters-alist' for
    a list of all allowed filters.  Filters defined here
    shouldn't make a backend test, as it may prevent backends
    derived from this one to behave properly.

  :menu-entry

    Menu entry for the export dispatcher.  It should be a list
    like:

      (KEY DESCRIPTION-OR-ORDINAL ACTION-OR-MENU)

    where :

      KEY is a free character selecting the backend.

      DESCRIPTION-OR-ORDINAL is either a string or a number.

      If it is a string, is will be used to name the backend in
      its menu entry.  If it is a number, the following menu will
      be displayed as a sub-menu of the backend with the same
      KEY.  Also, the number will be used to determine in which
      order such sub-menus will appear (lowest first).

      ACTION-OR-MENU is either a function or an alist.

      If it is an action, it will be called with four
      arguments (booleans): ASYNC, SUBTREEP, VISIBLE-ONLY and
      BODY-ONLY.  See `org-export-as' for further explanations on
      some of them.

      If it is an alist, associations should follow the
      pattern:

        (KEY DESCRIPTION ACTION)

      where KEY, DESCRIPTION and ACTION are described above.

    Valid values include:

      (?m \"My Special Backend\" my-special-export-function)

      or

       (?l \"Export to LaTeX\"
           ((?p \"As PDF file\" org-latex-export-to-pdf)
            (?o \"As PDF file and open\"
                (lambda (a s v b)
                  (if a (org-latex-export-to-pdf t s v b)
                    (org-open-file
                     (org-latex-export-to-pdf nil s v b)))))))

      or the following, which will be added to the previous
      sub-menu,

       (?l 1
          ((?B \"As TEX buffer (Beamer)\" org-beamer-export-as-latex)
           (?P \"As PDF file (Beamer)\" org-beamer-export-to-pdf)))

  :options-alist

    Alist between backend specific properties introduced in
    communication channel and how their value are acquired.  See
    `org-export-options-alist' for more information about
    structure of the values."
  (declare (indent 1))
  (let (filters menu-entry options)
    (while (keywordp (car body))
      (let ((keyword (pop body)))
	(pcase keyword
	  (:filters-alist (setq filters (pop body)))
	  (:menu-entry (setq menu-entry (pop body)))
	  (:options-alist (setq options (pop body)))
	  (_ (error "Unknown keyword: %s" keyword)))))
    (org-export-register-backend
     (org-export-create-backend :name backend
				:transcoders transcoders
				:options options
				:filters filters
				:menu menu-entry))))