Documentation for Dot source code blocks in Org mode
[worg.git] / org-contrib / babel / languages / ob-doc-dot.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:      Dot Source Code Blocks in Org Mode
6 #+AUTHOR:     Thomas S. Dye
7 #+EMAIL:      tsd[at]tsdye[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 #+EXPORT_EXCLUDE_TAGS: noexport
13
14 #+name: banner
15 #+begin_html
16   <div id="subtitle" style="float: center; text-align: center;">
17   <p>
18   Org Mode support for <a href="http://www.graphviz.org/">Dot</a>
19   </p>
20   <p>
21   <a href="http://language-site/">
22   <img src="http://www.graphviz.org/app.png"/>
23   </a>
24   </p>
25   </div>
26 #+end_html
27
28 * Template Checklist [7/12]                                        :noexport:
29   - [X] Revise #+TITLE:
30   - [X] Indicate #+AUTHOR:
31   - [X] Add #+EMAIL:
32   - [X] Revise banner source block [3/3]
33     - [X] Add link to a useful language web site
34     - [X] Replace "Language" with language name
35     - [X] Find a suitable graphic and use it to link to the language
36       web site
37   - [X] Write an [[Introduction]]
38   - [X] Describe [[Requirements%20and%20Setup][Requirements and Setup]]
39   - [X] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]]
40   - [ ] Describe [[Header%20Arguments][Header Arguments]]
41   - [ ] Describe support for [[Sessions]]
42   - [ ] Describe [[Result%20Types][Result Types]]
43   - [ ] Describe [[Other]] differences from supported languages
44   - [ ] Provide brief [[Examples%20of%20Use][Examples of Use]]
45 * Introduction
46 =Dot= is one of six layout programs in the =Graphviz= open source
47 graph visualization software, created at AT&T. The =Graphviz= layout
48 programs take simple text graph descriptions and make useful diagrams
49 in a variety of formats. =Dot= source code blocks call the =dot=
50 layout program by default, but can be configured to call any of the
51 other five =Graphviz= layout programs.
52
53 Graph visualization has applications in many technical domains, where
54 it is often used to explore large data sets. A typical use in =Org
55 mode= chains the =dot= source code block to a source code block in
56 another language that is responsible for converting a data table into
57 source code for one of the =Graphviz= layout languages.
58
59 * Requirements and Setup
60 =Graphviz= is distributed on an open source basis under [[http://www.eclipse.org/legal/eplfaq.php][The Eclipse
61 Public License]].  [[http://www.graphviz.org/Download..php][Executable packages]] from AT&T are available for
62 Linux, Solaris, Windows, and Mac.
63
64 You can configure Org mode to execute =dot= source code blocks by
65 adding a line to =org-babel-load-languages=:
66
67 #+BEGIN_SRC emacs-lisp
68     (org-babel-do-load-languages
69      'org-babel-load-languages
70      '((dot . t))) ; this line activates dot
71 #+END_SRC
72
73 * Org Mode Features for =Dot= Source Code Blocks
74 ** Header Arguments
75 =Dot= source code blocks produce graphics files. The default value for
76 the =:results= header argument is "file" and for the =:exports= header
77 argument it is "results".
78
79 There are two =dot= specific header arguments that can be used to
80                tailor the command line.  They are:
81    - =:cmd= :: this header argument can be used to change the layout
82                program from the default "dot".  [[http://www.graphviz.org/Home.php][Sensible values]]
83                are "neato", "fdp", "sfdp", "twopi", and "circo".
84    - =:cmdline= :: the default sets the =dot= flag =-T= to the
85                    extension of the output file in order to indicate
86                    the output format. =Graphviz= recognizes three
87                    dozen [[http://www.graphviz.org/content/output-formats][output formats]]. [[http://www.graphviz.org/content/command-line-invocation][Other flags]] that can be set
88                    with =:cmdline= control default graph, node, and
89                    edge attributes, among other functionality.
90
91 The =:file= header argument is required for =dot= source code blocks.
92
93 ** Sessions
94 =Dot= does not support sessions.
95 ** Result Types
96 =Dot= source code blocks produce graphic files, so the default value
97 "file" is the only sensible type of result.
98
99 ** Other
100 =Dot= source code blocks currently do not evaluate variables.
101
102 * Examples of Use
103 A typical use of a =dot= source code block is to produce a graph
104 visualization of a data set.  In this example, the following input
105 table 
106
107 #+name: dot-eg-table
108 | a | Hello  |
109 | b | World! |
110
111 is passed to a source code block that is responsible for producing
112 valid =dot= code 
113
114 #+name: make-dot
115 #+BEGIN_SRC emacs-lisp :var table=dot-eg-table :results output :exports none
116   (mapcar #'(lambda (x)
117               (princ (format "%s [label =\"%s\", shape = \"box\"];\n"
118                              (first x) (second x)))) table)
119               (princ (format "%s -- %s;\n" (first (first table)) (first (second table))))
120 #+END_SRC
121
122 #+BEGIN_EXAMPLE
123 ,#+name: make-dot
124 ,#+BEGIN_SRC emacs-lisp :var table=dot-eg-table :results output :exports none
125   (mapcar #'(lambda (x)
126               (princ (format "%s [label =\"%s\", shape = \"box\"];\n"
127                              (first x) (second x)))) table)
128               (princ (format "%s -- %s;\n" (first (first table)) (first (second table))))
129 ,#+END_SRC
130 #+END_EXAMPLE
131
132 and this is chained to a =dot= source code block that wraps the input
133 in a =graph{}= command to produce the following graphic output
134
135 #+BEGIN_SRC dot :file images/test-dot.png :var input=make-dot :exports results
136 graph {
137  $input
138 }
139 #+END_SRC
140
141 #+RESULTS:
142 [[file:images/test-dot.png]]
143
144 An example of chaining source code blocks to produce a =dot= graph is
145 provided by Schulte et al. in [[http://www.jstatsoft.org/v46/i03][A Multi-Language Computing Environment
146 for Literate Programming and Reproducible Research]].