exporters/filter-markup.org

   1 #+TITLE:       Marking Up Elements to be Exported
   2 #+DESCRIPTION: Dummy Filters for Orgmode Exporter
   3 #+AUTHOR: Charles C. Berry
   4 #+DATE: 2013-02-05
   5
   6 #+BEGIN_COMMENT
   7
   8 Copyright (C) 2013  Charles C. Berry
   9
  10 This program is free software: you can redistribute it and/or modify
  11 it under the terms of the GNU General Public License as published by
  12 the Free Software Foundation, either version 3 of the License, or
  13 (at your option) any later version.
  14
  15 This program is distributed in the hope that it will be useful,
  16 but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 GNU General Public License for more details.
  19
  20 For a copy of the GNU General Public License, see
  21 <http://www.gnu.org/licenses/>.
  22
  23 #+END_COMMENT
  24
  25 * Filters in the Exporter
  26 The exporter in =ox.el= has more than 50 elements that can be
  27 filtered. Developers can write filters for new backends, and users can
  28 write filters to customize output to their individual needs.
  29
  30 * Understanding Elements and Filters
  31 Figuring out how to craft a filter to customize output requires
  32 detailed knowledge of what the elements are and how they are rendered
  33 by a backend. It can be fairly difficult to sort this out and keep it
  34 all in mind by just reading the code.
  35
  36 One way to understand an element and the markup applied to it by an
  37 export backend is to write a filter that will mark the element.
  38
  39 For example, the function
  40
  41 #+BEGIN_SRC emacs-lisp
  42  (defun ox-mrkup-filter-bold
  43     (text back-end info)
  44     "Markup TEXT as <bold>TEXT</bold>. Ignore BACK-END and INFO."
  45     (format "<bold>%s</bold>" text))
  46 #+END_SRC
  47
  48 will show a bold element inside the tags ~<bold>~ and ~</bold>~.
  49
  50 Using that filter with the latex backend will render
  51
  52 #+begin_src org
  53   This text should be in *BOLD*.
  54 #+end_src
  55
  56 as
  57
  58 :  This text should be in <bold>\textbf{BOLD}</bold>.
  59
  60 * A Complete Set of Filter Functions
  61 Here is a complete set of filter functions to provide markup tags.
  62
  63 #+begin_src emacs-lisp
  64 (defun ox-mrkup-filter-body
  65   (text back-end info)
  66   (format "<body>%s</body>" text))
  67 (defun ox-mrkup-filter-bold
  68   (text back-end info)
  69   "Markup TEXT as <bold>TEXT</bold>. Ignore BACK-END and INFO."
  70   (format "<bold>%s</bold>" text))
  71 (defun ox-mrkup-filter-babel-call
  72   (text back-end info)
  73   (format "<bbl>%s</bbl>" text))
  74 (defun ox-mrkup-filter-center-block
  75   (text back-end info)
  76   (format "<cnt>%s</cnt>" text))
  77 (defun ox-mrkup-filter-clock
  78   (text back-end info)
  79   (format "<clck>%s</clck>" text))
  80 (defun ox-mrkup-filter-code
  81   (text back-end info)
  82   (format "<code>%s</code>" text))
  83 (defun ox-mrkup-filter-comment
  84   (text back-end info)
  85   (format "<cmmn>%s</cmmn>" text))
  86 (defun ox-mrkup-filter-comment-block
  87   (text back-end info)
  88   (format "<cmm>%s</cmm>" text))
  89 (defun ox-mrkup-filter-diary-sexp
  90   (text back-end info)
  91   (format "<dry>%s</dry>" text))
  92 (defun ox-mrkup-filter-drawer
  93   (text back-end info)
  94   (format "<drwr>%s</drwr>" text))
  95 (defun ox-mrkup-filter-dynamic-block
  96   (text back-end info)
  97   (format "<dyn>%s</dyn>" text))
  98 (defun ox-mrkup-filter-entity
  99   (text back-end info)
 100   (format "<entt>%s</entt>" text))
 101 (defun ox-mrkup-filter-example-block
 102   (text back-end info)
 103   (format "<exm>%s</exm>" text))
 104 (defun ox-mrkup-filter-export-block
 105   (text back-end info)
 106   (format "<exprt-b>%s</exprt-b>" text))
 107 (defun ox-mrkup-filter-export-snippet
 108   (text back-end info)
 109   (format "<exprt-s>%s</exprt-s>" text))
 110 (defun ox-mrkup-filter-final-output
 111   (text back-end info)
 112   (format "<fnl>%s</fnl>" text))
 113 (defun ox-mrkup-filter-fixed-width
 114   (text back-end info)
 115   (format "<fxd>%s</fxd>" text))
 116 (defun ox-mrkup-filter-footnote-definition
 117   (text back-end info)
 118   (format "<ftnt-d>%s</ftnt-d>" text))
 119 (defun ox-mrkup-filter-footnote-reference
 120   (text back-end info)
 121   (format "<ftnt-r>%s</ftnt-r>" text))
 122 (defun ox-mrkup-filter-headline
 123   (text back-end info)
 124   (format "<hdln>%s</hdln>" text))
 125 (defun ox-mrkup-filter-horizontal-rule
 126   (text back-end info)
 127   (format "<hrz>%s</hrz>" text))
 128 (defun ox-mrkup-filter-inline-babel-call
 129   (text back-end info)
 130   (format "<inln-b>%s</inln-b>" text))
 131 (defun ox-mrkup-filter-inline-src-block
 132   (text back-end info)
 133   (format "<inln-s>%s</inln-s>" text))
 134 (defun ox-mrkup-filter-inlinetask
 135   (text back-end info)
 136   (format "<inln>%s</inln>" text))
 137 (defun ox-mrkup-filter-italic
 138   (text back-end info)
 139   (format "<itlc>%s</itlc>" text))
 140 (defun ox-mrkup-filter-item
 141   (text back-end info)
 142   (format "<item>%s</item>" text))
 143 (defun ox-mrkup-filter-keyword
 144   (text back-end info)
 145   (format "<kywr>%s</kywr>" text))
 146 (defun ox-mrkup-filter-latex-environment
 147   (text back-end info)
 148   (format "<ltx-n>%s</ltx-n>" text))
 149 (defun ox-mrkup-filter-latex-fragment
 150   (text back-end info)
 151   (format "<ltx-f>%s</ltx-f>" text))
 152 (defun ox-mrkup-filter-line-break
 153   (text back-end info)
 154   (format "<ln-b>%s</ln-b>" text))
 155 (defun ox-mrkup-filter-link
 156   (text back-end info)
 157   (format "<link>%s</link>" text))
 158 (defun ox-mrkup-filter-node-property
 159   (text back-end info)
 160   (format "<nd-p>%s</nd-p>" text))
 161 ;; dont (defun ox-mrkup-filter-options ...)
 162 (defun ox-mrkup-filter-paragraph
 163   (text back-end info)
 164   (format "<prgr>%s</prgr>" text))
 165 ;; dont (defun ox-mrkup-filter-parse-tree ...)
 166 (defun ox-mrkup-filter-plain-list
 167   (text back-end info)
 168   (format "<pln-l>%s</pln-l>" text))
 169 (defun ox-mrkup-filter-plain-text
 170   (text back-end info)
 171   (format "<pln-t>%s</pln-t>" text))
 172 (defun ox-mrkup-filter-planning
 173   (text back-end info)
 174   (format "<plnn>%s</plnn>" text))
 175 (defun ox-mrkup-filter-property-drawer
 176   (text back-end info)
 177   (format "<prp>%s</prp>" text))
 178 (defun ox-mrkup-filter-quote-block
 179   (text back-end info)
 180   (format "<qt-b>%s</qt-b>" text))
 181 (defun ox-mrkup-filter-radio-target
 182   (text back-end info)
 183   (format "<rd-t>%s</rd-t>" text))
 184 (defun ox-mrkup-filter-section
 185   (text back-end info)
 186   (format "<sctn>%s</sctn>" text))
 187 (defun ox-mrkup-filter-special-block
 188   (text back-end info)
 189   (format "<spc>%s</spc>" text))
 190 (defun ox-mrkup-filter-src-block
 191   (text back-end info)
 192   (format "<src>%s</src>" text))
 193 (defun ox-mrkup-filter-statistics-cookie
 194   (text back-end info)
 195   (format "<stt>%s</stt>" text))
 196 (defun ox-mrkup-filter-strike-through
 197   (text back-end info)
 198   (format "<str>%s</str>" text))
 199 (defun ox-mrkup-filter-subscript
 200   (text back-end info)
 201   (format "<sbsc>%s</sbsc>" text))
 202 (defun ox-mrkup-filter-superscript
 203   (text back-end info)
 204   (format "<sprs>%s</sprs>" text))
 205 (defun ox-mrkup-filter-table
 206   (text back-end info)
 207   (format "<tabl>%s</tabl>" text))
 208 (defun ox-mrkup-filter-table-cell
 209   (text back-end info)
 210   (format "<tbl-c>%s</tbl-c>" text))
 211 (defun ox-mrkup-filter-table-row
 212   (text back-end info)
 213   (format "<tbl-r>%s</tbl-r>" text))
 214 (defun ox-mrkup-filter-target
 215   (text back-end info)
 216   (format "<trgt>%s</trgt>" text))
 217 (defun ox-mrkup-filter-timestamp
 218   (text back-end info)
 219   (format "<tmst>%s</tmst>" text))
 220 (defun ox-mrkup-filter-underline
 221   (text back-end info)
 222   (format "<undr>%s</undr>" text))
 223 (defun ox-mrkup-filter-verbatim
 224   (text back-end info)
 225   (format "<vrbt>%s</vrbt>" text))
 226 (defun ox-mrkup-filter-verse-block
 227   (text back-end info)
 228   (format "<vrs>%s</vrs>" text))
 229 #+end_src
 230
 231 * A LaTeX Backend Example
 232 Here is a derived backend that will use those tags. This backend takes
 233 ~latex~ as its parent, but other backends could be used as well.
 234 It is called ~latex2~ and can be used like this:
 235
 236 : M-: (org-export-to-buffer 'latex2 "latex-buffer-marked")
 237
 238 or
 239
 240 : M-: (org-export-to-file 'latex2 "latex-file-marked.tex")
 241
 242
 243 For many purposes only a subset of these might be needed. So the code
 244 could be edited to leave only those filters that are wanted.
 245
 246 #+begin_src emacs-lisp
 247 (require 'ox-latex)
 248 (org-export-define-derived-backend 'latex2 'latex
 249   :filters-alist
 250   '((:filter-body . ox-mrkup-filter-body)
 251     (:filter-bold . ox-mrkup-filter-bold)
 252     (:filter-babel-call . ox-mrkup-filter-babel-call)
 253     (:filter-center-block . ox-mrkup-filter-center-block)
 254     (:filter-clock . ox-mrkup-filter-clock)
 255     (:filter-code . ox-mrkup-filter-code)
 256     (:filter-comment . ox-mrkup-filter-comment)
 257     (:filter-comment-block . ox-mrkup-filter-comment-block)
 258     (:filter-diary-sexp . ox-mrkup-filter-diary-sexp)
 259     (:filter-drawer . ox-mrkup-filter-drawer)
 260     (:filter-dynamic-block . ox-mrkup-filter-dynamic-block)
 261     (:filter-entity . ox-mrkup-filter-entity)
 262     (:filter-example-block . ox-mrkup-filter-example-block)
 263     (:filter-export-block . ox-mrkup-filter-export-block)
 264     (:filter-export-snippet . ox-mrkup-filter-export-snippet)
 265     (:filter-final-output . ox-mrkup-filter-final-output)
 266     (:filter-fixed-width . ox-mrkup-filter-fixed-width)
 267     (:filter-footnote-definition . ox-mrkup-filter-footnote-definition)
 268     (:filter-footnote-reference . ox-mrkup-filter-footnote-reference)
 269     (:filter-headline . ox-mrkup-filter-headline)
 270     (:filter-horizontal-rule . ox-mrkup-filter-horizontal-rule)
 271     (:filter-inline-babel-call . ox-mrkup-filter-inline-babel-call)
 272     (:filter-inline-src-block . ox-mrkup-filter-inline-src-block)
 273     (:filter-inlinetask . ox-mrkup-filter-inlinetask)
 274     (:filter-italic . ox-mrkup-filter-italic)
 275     (:filter-item . ox-mrkup-filter-item)
 276     (:filter-keyword . ox-mrkup-filter-keyword)
 277     (:filter-latex-environment . ox-mrkup-filter-latex-environment)
 278     (:filter-latex-fragment . ox-mrkup-filter-latex-fragment)
 279     (:filter-line-break . ox-mrkup-filter-line-break)
 280     (:filter-link . ox-mrkup-filter-link)
 281     (:filter-node-property . ox-mrkup-filter-node-property)
 282     ;;   omit filter with different args
 283     ;;   (:filter-options . ox-mrkup-filter-options)
 284     (:filter-paragraph . ox-mrkup-filter-paragraph)
 285     ;;   omit filter with different args
 286     ;;   (:filter-parse-tree . ox-mrkup-filter-parse-tree)
 287     (:filter-plain-list . ox-mrkup-filter-plain-list)
 288     (:filter-plain-text . ox-mrkup-filter-plain-text)
 289     (:filter-planning . ox-mrkup-filter-planning)
 290     (:filter-property-drawer . ox-mrkup-filter-property-drawer)
 291     (:filter-quote-block . ox-mrkup-filter-quote-block)
 292     (:filter-radio-target . ox-mrkup-filter-radio-target)
 293     (:filter-section . ox-mrkup-filter-section)
 294     (:filter-special-block . ox-mrkup-filter-special-block)
 295     (:filter-src-block . ox-mrkup-filter-src-block)
 296     (:filter-statistics-cookie . ox-mrkup-filter-statistics-cookie)
 297     (:filter-strike-through . ox-mrkup-filter-strike-through)
 298     (:filter-subscript . ox-mrkup-filter-subscript)
 299     (:filter-superscript . ox-mrkup-filter-superscript)
 300     (:filter-table . ox-mrkup-filter-table)
 301     (:filter-table-cell . ox-mrkup-filter-table-cell)
 302     (:filter-table-row . ox-mrkup-filter-table-row)
 303     (:filter-target . ox-mrkup-filter-target)
 304     (:filter-timestamp . ox-mrkup-filter-timestamp)
 305     (:filter-underline . ox-mrkup-filter-underline)
 306     (:filter-verbatim . ox-mrkup-filter-verbatim)
 307     (:filter-verse-block . ox-mrkup-filter-verse-block)))
 308 #+END_SRC
 309
 310 * Options for Adding Filters
 311 Users can add filter functions to the lists in ~org-export-filters-alist~
 312 and subsequent exports will apply those functions accordingly.
 313
 314 Alternatively, writing a derived backend in which the ~:filters-alist~
 315 contains an entry such as:
 316
 317 :  (:filter-bold . ox-mrkup-filter-bold)
 318
 319 will result in bold elements being filterd through that function.
 320
 321 The advantage of using a derived backend to experiment with filters is
 322 that ~org-export-filters-alist~ is not filled with functions that will
 323 need to be removed once the experiments have ended.
 324
 325