org-latex filters

org-latex filters

[Shiyuan]

[-- Attachment #1: Type: text/plain, Size: 1612 bytes --]

Hi,
    I try to understand what the filter system is for and why the
transcoders itself doesn't suffice. So I take an example and want to see
how the filters are used in real exporter.  I look at ox-latex.el and try
to make sense of the filters

1. There are only two filters are used:

 :filters-alist '((:filter-options . org-latex-math-block-options-filter)
   (:filter-parse-tree . org-latex-math-block-tree-filter))

The purpose of org-latex-math-block-options-filter seems to be converting
whatever in the property list of :author, :date, :title  to strings of
latex commands(please correct me if I am wrong).  But what is the purpose
of org-latex-math-block-tree-filter? The org-latex--wrap-latex-math-block
is quite sophisticate and I don't get what it's doing.

-----------------------------------------------------
(defun org-latex-math-block-options-filter (info backend)
  (dolist (prop '(:author :date :title) info)
    (plist-put info prop
       (org-latex--wrap-latex-math-block (plist-get info prop) info))))
----------------------------------------------------
(defun org-latex-math-block-tree-filter (tree backend info)
  (org-latex--wrap-latex-math-block tree info))
----------------------------------------------------

2. For the filters of the form :filter-TYPE, there is also a transcoder for
processing the same TYPE. For example, for bold, there are :filter-bold,
but bold is also processed in the transcoder specified in the transcoder
alist when the backend is defined(by org-export-define-backend). When shall
we use a transcode and when shall we use a filter?

Thank you.

Shiyuan

[-- Attachment #2: Type: text/html, Size: 2151 bytes --]

Re: org-latex filters

[Nicolas Goaziou]

Hello,

Shiyuan <gshy2014@gmail.com> writes:

>     I try to understand what the filter system is for and why the
> transcoders itself doesn't suffice. So I take an example and want to see
> how the filters are used in real exporter.  I look at ox-latex.el and try
> to make sense of the filters
>
> 1. There are only two filters are used:
>
>  :filters-alist '((:filter-options . org-latex-math-block-options-filter)
>    (:filter-parse-tree . org-latex-math-block-tree-filter))
>
> The purpose of org-latex-math-block-options-filter seems to be converting
> whatever in the property list of :author, :date, :title  to strings of
> latex commands(please correct me if I am wrong).  But what is the purpose
> of org-latex-math-block-tree-filter?

The same as `org-latex-math-block-options-filter', but on the parse tree
itself.

> The org-latex--wrap-latex-math-block is quite sophisticate and I don't
> get what it's doing.

It merges contiguous math objects into a single one, and give it a new
type (i.e, a pseudo type), which requires its own translator. For
example:

  \(1\)\alpha$+1$

more or less becomes

  \(\beta\alpha+1\)

> 2. For the filters of the form :filter-TYPE, there is also a transcoder for
> processing the same TYPE. For example, for bold, there are :filter-bold,
> but bold is also processed in the transcoder specified in the transcoder
> alist when the backend is defined(by org-export-define-backend). When shall
> we use a transcode and when shall we use a filter?

A transcoder is mandatory. It transforms the parsed object into
a string. If there is no transcoder for a given type of object, all
objects of that type will be omitted from output.

A filter is applied on the output of the transcoder, for further
tweaking. Filters mainly target users, who do not have complete control
over transcoders (unless they create their own derived back-end).

There are also three special filters, which are not applied to the
output of a transcoder. Among them, two can be useful even for
a back-end developer: options filter and parse tree filter. For example,
they permit, as in "ox-latex.el" to introduce pseudo objects into the
parsed data.

You can also read "The Filter System" section in "ox.el".

HTH,

-- 
Nicolas Goaziou