org-contrib/org-exp-blocks.org

   1 #+TITLE:     org-exp-blocks.el --- pre-process blocks when exporting org files
   2 #+OPTIONS:   ^:{} author:nil toc:2
   3 #+STARTUP: odd
   4
   5 * General
   6
   7 =org-exp-blocks= can be used to pre-process blocks when exporting org
   8 files.  An extensible framework for block exportation is provided, as
   9 well as block exporters for [[http://ditaa.sourceforge.net/][ditaa]], [[http://www.graphviz.org/][dot]], comments.
  10
  11 Note: the ability to evaluate [[http://www.r-project.org/][R]] blocks with org-exp-blocks has been
  12 removed. Please use [[file:babel/index.org][org-babel]] for this purpose.
  13
  14 * How to use it
  15
  16 *** Quick Examples
  17
  18 To use =org-exp-blocks= first [[* Loading it][load it]] as described below.  Then try
  19 one of the following.
  20
  21 ***** ditaa
  22
  23 [[http://ditaa.sourceforge.net/][ditaa]] is a tool for converting ASCII images into actual images.  I
  24 believe ditaa is distributed with newer versions of org-mode.  To make
  25 sure that you have ditaa installed check the value of
  26 `org-ditaa-jar-path', it should point to a =ditaa.jar= file.  Once
  27 ditaa is installed and the `org-ditaa-jar-path' variable is set
  28 appropriately copy the following block in an org-mode file
  29
  30 : #+begin_ditaa blue.png -r -S
  31 : +---------+
  32 : | cBLU    |
  33 : |         |
  34 : |    +----+
  35 : |    |cPNK|
  36 : |    |    |
  37 : +----+----+
  38 : #+end_ditaa
  39
  40 Then export that file to HTML or LaTeX.  You should see an image like
  41 the following appear in the exported file.
  42
  43 [[file:../images/org-exp-blocks/blue.png]]
  44
  45
  46 ***** dot
  47
  48 dot is a language for representing structural information as diagrams
  49 of abstract graphs and networks.  It is part of [[http://www.graphviz.org/][Graphviz]].  To try out
  50 =org-exp-blocks= dot export install the =dot= shell command on your
  51 system, copy the following into an org-mode file
  52
  53 : #+begin_dot dot.png -Tpng
  54 : digraph data_relationships {
  55 :   "org-mode"
  56 :   "org-exp-blocks"
  57 :   "dot"
  58 :   "ditaa"
  59 :   "HTML" [shape=Mrecord, label="{HTML|publish on the web\l}"]
  60 :   "LaTeX" [shape=Mrecord, label="{LaTeX|publish in PDF\l}"]
  61 :   "org-mode" -> "org-exp-blocks"
  62 :   "dot" -> "org-mode"
  63 :   "ditaa" -> "org-mode"
  64 :   "org-exp-blocks" -> "HTML"
  65 :   "org-exp-blocks" -> LaTeX
  66 : }
  67 : #+end_dot
  68
  69 Then export that file to HTML or LaTeX.  You should see an image like
  70 the following appear in the exported file.
  71
  72 [[file:../images/org-exp-blocks/dot.png]]
  73
  74
  75 *** Loading it (No surprises here)
  76 The easiest way is by
  77
  78         M-x customize-apropos org-modules
  79
  80 Check the line for exp-blocks.  This will cause it to be loaded every
  81 time you start org-mode.
  82
  83 You'll still have to load it manually the first time.
  84
  85 Of course, you can also just try it out by loading it manually.
  86
  87 If you prefer to manually customize your emacs then make sure that the
  88 path to org's contrib directory is in your load-path and add the
  89 following to your =.emacs=.
  90
  91 : (require 'org-exp-blocks)
  92
  93
  94 *** Adding new source-code types
  95 =org-exp-blocks= is extensible.  If you would like to add a new block
  96 type code to =org-exp-blocks= you may do so by defining an export
  97 function for that block which will be called by
  98 `org-export-blocks-preprocess'.  Then add the block name, and the name
  99 of the function to the `org-export-blocks' variable.
 100
 101 If you add a new block type, and get it working please share your
 102 changes with the mailing list or post them [[additional-block-types][here]].
 103
 104 * Credits
 105
 106 =org-exp-blocks= was developed by Eric Schulte with much-appreciated
 107 help from Carsten Dominik.
 108
 109 * Additional Block Types
 110 #<<additional-block-types>>
 111
 112 *** Asymptote
 113
 114 Asymptote is a "powerful descriptive vector graphics language for
 115 technical drawing".  For more information see
 116 [[http://asymptote.sourceforge.net/]].
 117
 118 **** Installation
 119
 120 The following can be used to add asymptote support to
 121 =org-exp-blocks=.
 122
 123 #+begin_src emacs-lisp
 124 (setq org-export-blocks
 125       (cons '(asy org-export-blocks-format-asy) org-export-blocks))
 126
 127 (defun org-export-blocks-format-asy (body &rest headers)
 128   "Pass block BODY to the asy utility creating an image.
 129 Specify the path at which the image should be saved as the first
 130 element of headers, any additional elements of headers will be
 131 passed to the asy utility as command line arguments. The default
 132 output format is pdf, but you can specify any format supported by
 133 Imagemagick convert program with '-f outformat'."
 134   (message "asy-formatting...")
 135   (let* ((out-file (if headers (car headers)))
 136          (format (or (and (string-match ".+\\.\\(.+\\)" out-file)
 137                           (match-string 1 out-file))
 138                      "pdf"))
 139          (args (if (cdr headers) (mapconcat 'identity (cdr headers) " ")))
 140          (data-file (make-temp-file "org-asy")))
 141     (setq body (if (string-match "^\\([^:\\|:[^ ]\\)" body)
 142                    body
 143                  (mapconcat (lambda (x) (substring x (if (> (length x) 1) 2 1)))
 144                             (org-split-string body "\n")
 145                             "\n")))
 146     (cond
 147      ((or htmlp latexp)
 148       (with-temp-file data-file (insert body))
 149       (message (concat "asy -globalwrite -f " format " -o " out-file " " args " " data-file))
 150       (shell-command (concat "asy -globalwrite -f " format " -o " out-file " " args " " data-file))
 151       (format "\n[[file:%s]]\n" out-file))
 152      (t (concat
 153          "\n#+BEGIN_EXAMPLE\n"
 154          body (if (string-match "\n$" body) "" "\n")
 155          "#+END_EXAMPLE\n")))))
 156 #+end_src
 157
 158 **** Example
 159 Here is a simple asymptote block :
 160
 161 : #+begin_asy out.png
 162 : import graph;
 163 :
 164 : size(0,4cm);
 165 :
 166 : real f(real t) {return 1+cos(t);}
 167 :
 168 : path g=polargraph(f,0,2pi,operator ..)--cycle;
 169 : filldraw(g,pink);
 170 :
 171 : xaxis("$x$",above=true);
 172 : yaxis("$y$",above=true);
 173 :
 174 : dot("$(a,0)$",(1,0),N);
 175 : dot("$(2a,0)$",(2,0),N+E);
 176 : #+end_asy
 177
 178 The output should be [[file:../images/org-exp-blocks/cardioid.png]]
 179
 180 **** Credit
 181 Thanks to Nicolas Goaziou for adding support for asymptote.
 182
 183 *** Dot with EPS
 184 While dot is capable of generating pdf images directly the results are
 185 more pleasing when =dot= is used to generate an eps file and
 186 =epstopdf= is used to generate the actual pdf.
 187
 188 The following block type takes the name of a file, and generates both
 189 and EPS and a PDF file at that base name.
 190
 191 **** Installation
 192 The following can be used to add =dot-and-eps= block support to
 193 =org-exp-blocks=.
 194
 195 #+begin_src emacs-lisp
 196 (defun org-export-blocks-format-dot-and-eps (body &rest headers)
 197   "Pass block BODY to the dot graphing utility creating an eps
 198 file which is then processed by eps to create a pdf.  Specify the
 199 path at which the final pdf image should be created as the first
 200 element of headers, any additional elements of headers will be
 201 passed to the dot utility as command line arguments.
 202
 203 #+begin_dot_and_eps duh
 204 digraph test {
 205 a -> { b c d e };
 206 e -> { f g h i };
 207 };
 208 #+end_dot"
 209   (message "dot-and-eps-formatting...")
 210   (let ((out-file (if headers (car headers)))
 211         (args (if (cdr headers) (mapconcat 'identity (cdr headers) " ")))
 212         (data-file (make-temp-file "org-dot")))
 213     (cond
 214      ((or htmlp latexp docbookp)
 215       (with-temp-file data-file (insert body))
 216       (shell-command (message (concat "dot -Teps " data-file " " args " -o " out-file ".eps")))
 217       (shell-command (message (concat "epstopdf " out-file ".eps")))
 218       (format "\n[[file:%s.pdf]]\n" out-file))
 219      (t (concat
 220          "\n#+BEGIN_EXAMPLE\n"
 221          body (if (string-match "\n$" body) "" "\n")
 222          "#+END_EXAMPLE\n")))))
 223
 224 (org-export-blocks-add-block '(dot-and-eps org-export-blocks-format-dot-and-eps nil))
 225 #+end_src
 226
 227 **** Example
 228 Here is an example =dot-and-eps= block
 229
 230 : #+begin_dot-and-eps out-w-eps
 231 : digraph test {
 232 : a -> { b c d e };
 233 : e -> { f g h i };
 234 : };
 235 : #+end_dot-and-eps
 236
 237 **** Credit
 238 Thanks to Russell Adams for noticing this need, and supplying the
 239 command lines.
 240