0da535382316492bbc0d3e3221551c1221928895
[worg.git] / 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