From: Thomas Dye Date: Sat, 29 Sep 2012 18:48:30 +0000 (-1000) Subject: Documentation for Dot source code blocks in Org mode X-Git-Tag: release_7.9.3~95^2~2^2~3 X-Git-Url: http://orgmode.org/w/?p=worg.git;a=commitdiff_plain;h=5ae77fe70eb1d9c2f39f69a269da1e41c691e5dd Documentation for Dot source code blocks in Org mode --- diff --git a/org-contrib/babel/languages/images/test-dot.png b/org-contrib/babel/languages/images/test-dot.png new file mode 100644 index 0000000..7999f73 Binary files /dev/null and b/org-contrib/babel/languages/images/test-dot.png differ diff --git a/org-contrib/babel/languages/ob-doc-dot.org b/org-contrib/babel/languages/ob-doc-dot.org new file mode 100644 index 0000000..ffff15e --- /dev/null +++ b/org-contrib/babel/languages/ob-doc-dot.org @@ -0,0 +1,146 @@ +#+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 +#+STARTUP: align fold nodlcheck hidestars oddeven lognotestate hideblocks +#+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@) +#+TAGS: Write(w) Update(u) Fix(f) Check(c) noexport(n) +#+TITLE: Dot Source Code Blocks in Org Mode +#+AUTHOR: Thomas S. Dye +#+EMAIL: tsd[at]tsdye[dot]com +#+LANGUAGE: en +#+STYLE: +#+LINK_UP: ../languages.html +#+LINK_HOME: http://orgmode.org/worg/ +#+EXPORT_EXCLUDE_TAGS: noexport + +#+name: banner +#+begin_html +
+

+ Org Mode support for Dot +

+

+ + + +

+
+#+end_html + +* Template Checklist [7/12] :noexport: + - [X] Revise #+TITLE: + - [X] Indicate #+AUTHOR: + - [X] Add #+EMAIL: + - [X] Revise banner source block [3/3] + - [X] Add link to a useful language web site + - [X] Replace "Language" with language name + - [X] Find a suitable graphic and use it to link to the language + web site + - [X] Write an [[Introduction]] + - [X] Describe [[Requirements%20and%20Setup][Requirements and Setup]] + - [X] Replace "Language" with language name in [[Org%20Mode%20Features%20for%20Language%20Source%20Code%20Blocks][Org Mode Features for Language Source Code Blocks]] + - [ ] Describe [[Header%20Arguments][Header Arguments]] + - [ ] Describe support for [[Sessions]] + - [ ] Describe [[Result%20Types][Result Types]] + - [ ] Describe [[Other]] differences from supported languages + - [ ] Provide brief [[Examples%20of%20Use][Examples of Use]] +* Introduction +=Dot= is one of six layout programs in the =Graphviz= open source +graph visualization software, created at AT&T. The =Graphviz= layout +programs take simple text graph descriptions and make useful diagrams +in a variety of formats. =Dot= source code blocks call the =dot= +layout program by default, but can be configured to call any of the +other five =Graphviz= layout programs. + +Graph visualization has applications in many technical domains, where +it is often used to explore large data sets. A typical use in =Org +mode= chains the =dot= source code block to a source code block in +another language that is responsible for converting a data table into +source code for one of the =Graphviz= layout languages. + +* Requirements and Setup +=Graphviz= is distributed on an open source basis under [[http://www.eclipse.org/legal/eplfaq.php][The Eclipse +Public License]]. [[http://www.graphviz.org/Download..php][Executable packages]] from AT&T are available for +Linux, Solaris, Windows, and Mac. + +You can configure Org mode to execute =dot= source code blocks by +adding a line to =org-babel-load-languages=: + +#+BEGIN_SRC emacs-lisp + (org-babel-do-load-languages + 'org-babel-load-languages + '((dot . t))) ; this line activates dot +#+END_SRC + +* Org Mode Features for =Dot= Source Code Blocks +** Header Arguments +=Dot= source code blocks produce graphics files. The default value for +the =:results= header argument is "file" and for the =:exports= header +argument it is "results". + +There are two =dot= specific header arguments that can be used to + tailor the command line. They are: + - =:cmd= :: this header argument can be used to change the layout + program from the default "dot". [[http://www.graphviz.org/Home.php][Sensible values]] + are "neato", "fdp", "sfdp", "twopi", and "circo". + - =:cmdline= :: the default sets the =dot= flag =-T= to the + extension of the output file in order to indicate + the output format. =Graphviz= recognizes three + dozen [[http://www.graphviz.org/content/output-formats][output formats]]. [[http://www.graphviz.org/content/command-line-invocation][Other flags]] that can be set + with =:cmdline= control default graph, node, and + edge attributes, among other functionality. + +The =:file= header argument is required for =dot= source code blocks. + +** Sessions +=Dot= does not support sessions. +** Result Types +=Dot= source code blocks produce graphic files, so the default value +"file" is the only sensible type of result. + +** Other +=Dot= source code blocks currently do not evaluate variables. + +* Examples of Use +A typical use of a =dot= source code block is to produce a graph +visualization of a data set. In this example, the following input +table + +#+name: dot-eg-table +| a | Hello | +| b | World! | + +is passed to a source code block that is responsible for producing +valid =dot= code + +#+name: make-dot +#+BEGIN_SRC emacs-lisp :var table=dot-eg-table :results output :exports none + (mapcar #'(lambda (x) + (princ (format "%s [label =\"%s\", shape = \"box\"];\n" + (first x) (second x)))) table) + (princ (format "%s -- %s;\n" (first (first table)) (first (second table)))) +#+END_SRC + +#+BEGIN_EXAMPLE +,#+name: make-dot +,#+BEGIN_SRC emacs-lisp :var table=dot-eg-table :results output :exports none + (mapcar #'(lambda (x) + (princ (format "%s [label =\"%s\", shape = \"box\"];\n" + (first x) (second x)))) table) + (princ (format "%s -- %s;\n" (first (first table)) (first (second table)))) +,#+END_SRC +#+END_EXAMPLE + +and this is chained to a =dot= source code block that wraps the input +in a =graph{}= command to produce the following graphic output + +#+BEGIN_SRC dot :file images/test-dot.png :var input=make-dot :exports results +graph { + $input +} +#+END_SRC + +#+RESULTS: +[[file:images/test-dot.png]] + +An example of chaining source code blocks to produce a =dot= graph is +provided by Schulte et al. in [[http://www.jstatsoft.org/v46/i03][A Multi-Language Computing Environment +for Literate Programming and Reproducible Research]].