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