From 5ae77fe70eb1d9c2f39f69a269da1e41c691e5dd Mon Sep 17 00:00:00 2001 From: Thomas Dye Date: Sat, 29 Sep 2012 08:48:30 -1000 Subject: [PATCH] Documentation for Dot source code blocks in Org mode --- org-contrib/babel/languages/images/test-dot.png | Bin 0 -> 2022 bytes org-contrib/babel/languages/ob-doc-dot.org | 146 +++++++++++++++++++++++ 2 files changed, 146 insertions(+), 0 deletions(-) create mode 100644 org-contrib/babel/languages/images/test-dot.png create mode 100644 org-contrib/babel/languages/ob-doc-dot.org 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 0000000000000000000000000000000000000000..7999f739dd5178257f525566e2b6cdc4e2f0418e GIT binary patch literal 2022 zcma)72{hZ;8vj3IdzPxDsL%yf6+@6Hm8#K5VwqM|5jv5h_j577ZGuLr}52%sKC!Gjq*?H6On1|2(u$G z1oQU|w(4ktd3_FHN5P2V4a7cUnf>aD1Shntv*FI)bN$ifrK^5GM!Tx7U9!5sEjiYP z9WohsUxK`vY36H30_o{l7xn`X2qYMyD-B9#1+Q&wN}RineR~ek9Y$xfkt_CJzNxqV z>K58qT}C}?qUF@F_@#a32Sc$#Wy6T5^{M6! zL3&Go9h;nf zfq7m09PbdIyLYcJd8;?i68I&OOX1l(EGA!z0DUwvGOF(W^k9;cBh)%~^Wv@ung{3- z?$ool;^k!^-RJSQBOV?e=J?mGt&YHGLo5hv3xoZmT^gQdIl6u7iaJq4Q5M*zP5e5j z6)p)3YD<+%r(3H$Yi!g5TCYibDk^e=vx7qyC7aLh^$lgwQaACyj|ju+e6%s(RO6## zR&`(}i&EX#)P$kc)p4Vs7O#6lXh8eSj47CulXDQPe7u&JWjYYG+(pz8-H`s9fP4Vw zazbcjWo7kl6d?+UbaQv7dSOv0PB!Q;4u>0WPVU@6V_$c2@>9v|1lh*C#61ZO4P`JG z3Tk_JQP6i6>?Heaavnnr5t|X@RLRPGV`Jl8u&-V=8>)PN43kk%u)BPy($jP*o;i#w zE-LDC>~P_n$?vjG(UB&UUblX#lj!?+_-Wi&&tbMpDJtfV`1mi7`L`>KWnk7ektUuS z4!P+iyOEj}8(XtxHK5u|B9Y!B{oocst>#CjZmT#DyROFujx#SsVmnJ={{xDD{nXzp z=+9B)pwv2=F%~xZF*9phKwd_GD%&t?nL{{5SNHnQy}UJF=~mt3_5UwvYG22EV)=CM z%-mc&^K2!|A?cGWz&uOww}-=vP+_}&i@v(CHZY&KFiJCeLZ?!xOs0K~@_y{Zpp6J+ ztU*Xx7^n3LVr)s1S14+kouXZf3On@Q+Imx>8Oj1q29qJnz&1c{i$;?*33d zJ-p-i^z^h>CA9aBGU{H2A~G%Q7~t*e%jI$zdJV5k?mW-eV{dFUBOiQOo;{s=i$EtU z4jeb{bUZGEjx-ke>*XIPygFyS_XJatc>k#lTZUYaegmOsK#6GgYWM`(Dj%DDR#>>&B zT7$C*s;a8@^H%UJ0Sz&yOtoIsey6$TyB7TAQ!ap0KmZ6xNJ`>NUIY|nWmv(UCU?Xu zE9?*};787++8($aemRQn{z0TG7K?>1iVO4epT$pSohT!emOg4_bMAHld-RAwsix2EBBZ6nt2&&|r08;;Emxhisw2o}5e=`gVBY zPjW#Ta*K1rVBqC!0#NEzc|-MQw{TjyJYc6!qSNUV3MCk_wlW`(!Md=vc&^fWeeqo< z+Spp!8K3x{7Hp>`{>0~FfQpI=zl!T;ElzH6`ZM4z)fmPj8tr0STy0BB3zLa4yk&Z~ zXH&9zNk3_QdG?xQh3c{);aiOc6;i9zrw6I-aZep`XprC1eoZ`53|v?kZwb4tZ0is= z-dtd7S-O*NwTwRsz|*$$>Fyr4Z3^+s!IS=#OZxpx{x(#PU( zZjS~rO^G$n!|41N5zX*!RaI4sS#outline-container-introduction{ clear:both; } +#+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]]. -- 1.7.2.5