org-contrib/babel/languages/ob-doc-eukleides.org

   1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:{} -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
   2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate hideblocks
   3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
   4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) noexport(n)
   5 #+TITLE:      Eukleides Source Code Blocks in Org Mode
   6 #+AUTHOR:     Luis Anaya
   7 #+EMAIL:      papoanaya[at]hotmail[dot]com
   8 #+LANGUAGE:   en
   9 #+STYLE:      <style type="text/css">#outline-container-introduction{ clear:both; }</style>
  10 #+LINK_UP:    ../languages.html
  11 #+LINK_HOME:  http://orgmode.org/worg/
  12
  13 #+begin_html
  14   <div id="subtitle" style="float: center; text-align: center;">
  15   <p>
  16   Org-babel support for
  17   <a href="http://www.eukleides.org/">Eukleides</a>
  18   </p>
  19   <p>
  20   <a href="http://www.eukleides.org/">
  21   <img src="http://www.eukleides.org/img/perdigal.png" width=200/>
  22   </a>
  23   </p>
  24   </div>
  25 #+end_html
  26 * Introduction
  27 org-babel-eukleides allows =eukleides= code to be executed directly from
  28 within embedded code blocks in =Org mode= documents. These code blocks
  29 can draw pictures that are generated from =eukleides=
  30 and can include output as embedded graphics when the document is
  31 exported.
  32
  33 The following provides instructions and some examples of =eukleides=
  34 usage. Since babel is simply allowing native code to run inside of
  35 =Org mode=, all =eukleides= documentation is applicable and valid. [fn:1]
  36
  37 * Requirements and Setup
  38 To get =eukleides= up and running, you need =eukleides= to be available in
  39 your system. You *will* need a program to convert Encapsulated
  40 Postscript (EPS) files into PNG. Strings to convert files using =sam2p=
  41 or =pnmtopng= are supported, but other types of converters like
  42 ImageMagick can be used.
  43
  44 There are two strings being passed, the first one is the original file
  45 name and the second one is the converted one.
  46
  47 As of =Org mode= 7.01, babel support is included and there is no need to load it via
  48 .emacs. All you have to do is enable specific language support with
  49 the following in .emacs:
  50
  51 #+begin_example
  52 ;; active Babel languages
  53 (org-babel-do-load-languages
  54  'org-babel-load-languages
  55  '((eukleides . t)))
  56 ;; add additional languages with '((language . t)))
  57 #+end_example
  58
  59 or
  60
  61 #+begin_example
  62 ;; set up babel support
  63 (require 'org-install)
  64 (require 'ob-eukleides)
  65 ;; add additional languages with (require 'ob-language)
  66 #+end_example
  67
  68 To run =eukleides= and produce a resultant image (or to produce any result
  69 from babel code blocks), simply move one's cursor anywhere in the code
  70 block and press =C-c C-c= (Ctrl+C followed by Ctrl+C) and type "yes"
  71 in the minibuffer when asked about executing the code.
  72
  73 * Babel Header Arguments
  74 Babel block headers are used to pass various arguments to control the
  75 results of the executed code. The complete list of header arguments
  76 is covered in the =Org mode= manual; for now, some options frequently used for
  77 =eukleides= are:
  78 - =:exports {code, results, both, none}=
  79   - When the code is run and the document exported (e.g. to HTML or
  80     \LaTeX PDF), what should appear? Just the code block itself? Only
  81     the produced output (in this case a plot of some sort)? Both the
  82     code and the accompanying results? Or nothing?
  83 - =:file foo.{png,eps}=
  84   - This option specifies where the resulting output should be put. This
  85     option is *required*. Only EPS and PNG files are supported; PNG only
  86     supported with a conversion script.
  87
  88 * Quick =Eukleides= Overview
  89 As stated earlier, the full =eukleides= documentation can and should be
  90 consulted as the official reference, but it might be helpful to lay
  91 out some common syntax here as a quick reference. Any of the commands
  92 typed in =code= font below should be assumed to reside in a babel
  93 code block (between =#+begin_src eukleides= and =#+end_src=).
  94
  95 ** Basic Use
  96 *** Defining Shapes
  97 =Eukleides= is a programming language that contain a complete set of logic
  98 constructs, but its main purpose is to generate pictures, commonly
  99 seen in geometry texts. This is for the most part a two part process:
 100
 101   1. Defining the Shapes
 102   2. Drawing them.
 103
 104 Let's go through this example:
 105
 106 #+begin_example
 107 #+begin_src eukleides :file test.eps
 108 O = point (2,2)
 109 C = circle(O,2)
 110 draw
 111   O plus
 112   C
 113 end
 114 #+end_src
 115 #+end_example
 116
 117 There are two shapes being drawn in this example:
 118   1.  A point in position 2,2. It is shaped as a cross
 119   2.  A circle centered in 2,2 with a diameter of 2.
 120
 121 Upon the execution of this block using =C-c C-c= the file name will be
 122 stated in =#+RESULTS:= containing the resultant picture.
 123
 124 *** Data Processing
 125
 126 As mentioned, =eukleides= is a complete programming language, but
 127 support for results is not available from =Org mode= at this time
 128 being that its primary function is to draw pictures. But the following
 129 can be used to write text or other items to a file as part of the
 130 execution of an =eukleides= script.
 131
 132 #+begin_example
 133
 134 #+begin_src eukleides :file /dev/null
 135 write "myfile.txt"
 136 print "Hello"
 137 print 1,2,3
 138 release
 139 #+end_src
 140
 141 #+RESULTS:
 142 [[file:/dev/null]]
 143
 144 #+end_example
 145
 146 In this example the a file named "myfile.txt" containing "Hello" and
 147 1,2,3 is written.
 148
 149 ** Named Procedures and Tables
 150 Named procedures and tables are not supported at this moment. [fn:2]
 151
 152 * Footnotes
 153 [fn:1] =Eukleides= manual downloads are located at [[eukleides.org]]
 154
 155 [fn:2] =Eukleides= is able to support text results and variable
 156 processing, but it is not available in this release of the Babel
 157 plugin. The code will be enhanced in the future.
 158
 159