The dottex package∗

Lars Kotthoff
lars@larsko.org
August 22, 2007

1 Introduction
This package allows you to include dot and neato graphs in your LATEX documents.
The dot/neato code is extracted from the document and written to .dot/.neato
files. Then, if shell escape is used, the graph files are automatically processed and
converted to PostScript files, which will then be included. If shell escape isn’t
used, the user will have to manually convert the files.
Shell escape is available in the web2c TEX compiler, it allows the execution of
shell code during the compilation of a TEX document. It’s disabled by default,
you’ll have to edit your configuration files or give the -shell-escape option to
latex. A check is performed whether shell escape really works, so you might get
warnings that the .dot/.neato files need to be converted manually although you
enabled shell escape.

2 Requirements
To use dottex, you’ll need the graphicx, keyval and moreverb packages, ps2pdf
if you want to use the pdf option, and of course, dot / neato of the Graphviz
package. All the binaries need to be in your PATH, i.e. you should be able to call
them without specifying the absolute path to the binary.

3 Usage
To load the package, simply \usepackage{dottex} in your document preamble.
Options that can be passed to the package are

[hshell i] Use shell escape to automatically generate the graphs from the dot
source files. This is the default. Normally, you don’t need to specify it.

[hnoshell i] Don’t use shell escape, graphs must be generated manually.

[hmiktex i] We’re using mikTeX.

[hpdf i] PDF output, generate .pdf files of the graphs out of .ps.

1
 The following environments can be used to include graphs:
dotpic Within this environment, you can specify arbitrary dot code, for example
a -> b;
b -> a;.
The digraph preamble and the surrounding braces are inserted automatically.
neatopic Within this environment, you can specify arbitrary neato code, for example
a -- b;
b -- a;.
The graph preamble and the surrounding braces are inserted automatically.
For both environments, you may specify width or height of the picture using
[width=hwidthi] or [height=hheighti] as in the includegraphics command.

4 Acknowledgements
Thanks to Klaus Storch for several suggestions to improve the Miktex compati-
bility.

5 Implementation
5.1 Initialization
1 \newif\ifShellEscape
2 \newif\ifmiktex \miktexfalse
3 \newif\ifpdf \pdffalse
4
5 \DeclareOption{shell}{\ShellEscapetrue}
6 \DeclareOption{noshell}{\ShellEscapefalse}
7 \DeclareOption{miktex}{\global\miktextrue}
8 \DeclareOption{pdf}{\pdftrue}
9
10 \ExecuteOptions{shell}
11 \ProcessOptions\relax
12 %% test if shell escape really works
13 \ifShellEscape
14 \def\tmpfile{/tmp/w18-test-\the\year\the\month\the\day\the\time}
15 \ifmiktex
16 \def\tmpfile{w18-test-\the\year\the\month\the\day\the\time}
17 \immediate\write18{echo t > "\tmpfile"}
18 \else
19 \immediate\write18{touch \tmpfile}
20 \fi
21 \ifmiktex
22 \IfFileExists{\tmpfile.}{\ShellEscapetrue}{\ShellEscapefalse}
23 \immediate\write18{del "\tmpfile"}
24 \else
25 \IfFileExists{\tmpfile}{\ShellEscapetrue}{\ShellEscapefalse}
26 \immediate\write18{rm -f \tmpfile}
27 \fi
28 \fi
29
∗ This document corresponds to dottex v0.6, dated 2007/08/22.

2
30 \ifShellEscape
31 \PackageInfo{dottex}
32 {Automatically converting dot/neato files}
33 \else
34 \PackageWarningNoLine{dottex}
35 {Shell escape not enabled.\MessageBreak
36 You’ll need to convert the graphs yourself.}
37 \fi
38 \newcounter{fignum}
5.2 .dot/.neato write out
39 \def\figname{\jobname-dottex-fig\thefignum}
40
41 \def\dotverbatimwrite#1{%
42 \def\BeforeStream
43 {\message{Opening Dot stream=\figname.dot}%
44 \immediate\write\verbatim@out{\string digraph\space G\space {/*}*/}
45 }
46 \@bsphack
47 \immediate\openout \verbatim@out #1
48 \BeforeStream%
49 \let\do\@makeother\dospecials
50 \catcode‘\^^M\active
51 \def\verbatim@processline{%
52 \immediate\write\verbatim@out
53 {\the\verbatim@line}}%
54 \verbatim@start}
55 \def\enddotverbatimwrite{%
56 \immediate\write\verbatim@out{/*{*/}}
57 \immediate\closeout\verbatim@out
58 \@esphack}
59
60 \def\neatoverbatimwrite#1{%
61 \def\BeforeStream
62 {\message{Opening Neato stream=\figname.neato}%
63 \immediate\write\verbatim@out{\string graph\space G\space {/*}*/}
64 }
65 \@bsphack
66 \immediate\openout \verbatim@out #1
67 \BeforeStream%
68 \let\do\@makeother\dospecials
69 \catcode‘\^^M\active
70 \def\verbatim@processline{%
71 \immediate\write\verbatim@out
72 {\the\verbatim@line}}%
73 \verbatim@start}
74 \def\endneatoverbatimwrite{%
75 \immediate\write\verbatim@out{/*{*/}}
76 \immediate\closeout\verbatim@out
77 \@esphack}
The spurious braces (commented out in the .dot/.neato file) are necessary
because LATEX gets confused with only one brace.
5.3 Environment definition

3
 78 \define@key{pic}{width}{\def\dotwidth{#1}}
79 \define@key{pic}{height}{\def\dotheight{#1}}
80 \newenvironment{dotpic}[1][]{\stepcounter{fignum}%
81 \let\dotwidth\undefined
82 \let\dotheight\undefined
83 \setkeys{pic}{#1}
84 \xdef\dotCutFile{\figname.dot}
85 \dotverbatimwrite{\dotCutFile}}
86 {\enddotverbatimwrite%
87 \dotgraphicsinclude}
88
89 \newenvironment{neatopic}[1][]{\stepcounter{fignum}%
90 \let\dotwidth\undefined
91 \let\dotheight\undefined
92 \setkeys{pic}{#1}
93 \xdef\neatoCutFile{\figname.neato}
94 \neatoverbatimwrite{\neatoCutFile}}
95 {\endneatoverbatimwrite%
96 \neatographicsinclude}

5.4 .dot/.neato file processing

97 \long\gdef\dotgraphicsprocess{%
98 \ifShellEscape
99 \IfFileExists{\figname.dot}{%
100 \immediate\write18{dot -Tps2 -o \figname.ps \figname.dot}
101 \IfFileExists{\figname.ps}{%
102 \ifpdf
103 \immediate\write18{ps2pdf \figname.ps \figname.pdf}
104 \IfFileExists{\figname.pdf}{%
105 \PackageInfo{dottex}
106 {\figname.dot converted}}
107 {\PackageWarningNoLine{dottex}
108 {Conversion of \figname.dot failed.}}
109 \else
110 \PackageInfo{dottex}
111 {\figname.dot converted}
112 \fi}
113 {\PackageWarningNoLine{dottex}
114 {Conversion of \figname.dot failed.}}}{}
115 \fi}
116
117 \long\gdef\neatographicsprocess{%
118 \ifShellEscape
119 \IfFileExists{\figname.neato}{%
120 \immediate\write18{neato -Tps2 -o \figname.ps \figname.neato}
121 \IfFileExists{\figname.ps}{%
122 \ifpdf
123 \immediate\write18{ps2pdf \figname.ps \figname.pdf}
124 \IfFileExists{\figname.pdf}{%
125 \PackageInfo{dottex}
126 {\figname.dot converted}}
127 {\PackageWarningNoLine{dottex}
128 {Conversion of \figname.dot failed.}}
129 \else

4
130 \PackageInfo{dottex}
131 {\figname.neato converted}
132 \fi}
133 {\PackageWarningNoLine{dottex}
134 {Conversion of \figname.neato failed.}}}{}
135 \fi}

5.5 Graph inclusion

136 \long\gdef\dotgraphicsinclude{\dotgraphicsprocess%
137 \ifpdf
138 \IfFileExists{\figname.pdf}{%
139 \ifx\dotwidth\undefined
140 \ifx\dotheight\undefined
141 \includegraphics{\figname}
142 \else
143 \includegraphics[height=\dotheight]{\figname}
144 \fi
145 \else
146 \ifx\dotheight\undefined
147 \includegraphics[width=\dotwidth]{\figname}
148 \else
149 \includegraphics[width=\dotwidth,height=\dotheight]{\figname}
150 \fi
151 \fi
152 }
153 {\PackageWarningNoLine{dottex}
154 {Please convert \figname.dot manually}}
155 \else
156 \IfFileExists{\figname.ps}{%
157 \ifx\dotwidth\undefined
158 \ifx\dotheight\undefined
159 \includegraphics{\figname}
160 \else
161 \includegraphics[height=\dotheight]{\figname}
162 \fi
163 \else
164 \ifx\dotheight\undefined
165 \includegraphics[width=\dotwidth]{\figname}
166 \else
167 \includegraphics[width=\dotwidth,height=\dotheight]{\figname}
168 \fi
169 \fi
170 }
171 {\PackageWarningNoLine{dottex}
172 {Please convert \figname.dot manually}}
173 \fi
174 }
175
176 \long\gdef\neatographicsinclude{\neatographicsprocess%
177 \ifpdf
178 \IfFileExists{\figname.pdf}{%
179 \ifx\dotwidth\undefined
180 \ifx\dotheight\undefined
181 \includegraphics{\figname}

5
182 \else
183 \includegraphics[height=\dotheight]{\figname}
184 \fi
185 \else
186 \ifx\dotheight\undefined
187 \includegraphics[width=\dotwidth]{\figname}
188 \else
189 \includegraphics[width=\dotwidth,height=\dotheight]{\figname}
190 \fi
191 \fi
192 }
193 {\PackageWarningNoLine{dottex}
194 {Please convert \figname.neato manually}}
195 \else
196 \IfFileExists{\figname.ps}{%
197 \ifx\dotwidth\undefined
198 \ifx\dotheight\undefined
199 \includegraphics{\figname}
200 \else
201 \includegraphics[height=\dotheight]{\figname}
202 \fi
203 \else
204 \ifx\dotheight\undefined
205 \includegraphics[width=\dotwidth]{\figname}
206 \else
207 \includegraphics[width=\dotwidth,height=\dotheight]{\figname}
208 \fi
209 \fi
210 }
211 {\PackageWarningNoLine{dottex}
212 {Please convert \figname.neato manually}}
213 \fi
214 }