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