path: root/macros/latex/contrib/graphviz/graphviz.dtx

% \iffalse meta-comment
%
% Copyright (C) 2003-2013 by Derek Rayside <drayside@uwaterloo.ca>
% --------------------------------------------------
% 
% This file may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.3 of this license
% or (at your option) any later version.  The latest version of this
% license is in:
%
%    http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX
% version 1999/12/01 or later.
%
% \fi
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{graphviz} 
%<package>   [2013/08/15 v0.94 .dtx graphviz file] 
%
%<*driver>
\documentclass{ltxdoc} 
\RequirePackage[psfrag]{graphviz} 
\RequirePackage{url}
\RequirePackage{calc}
\EnableCrossrefs
\CodelineIndex 
\RecordChanges 
\begin{document} 
  \DocInput{graphviz.dtx}
\end{document}
%</driver> \fi
%
% \CheckSum{0}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
%
%
% \changes{v0.1}{2003/11/24}{Initial version}
% \changes{v0.4}{2004/05/14}{converted to dtx format}
% \changes{v0.5}{2004/05/19}{renamed package to \textsf{dotla}}
% \changes{v0.7}{2005/12/29}{renamed package back to \textsf{graphviz}}
%
% \GetFileInfo{graphviz.sty}
%
% \DoNotIndex{\newcommand,\newenvironment}
% 
%
% \title{\vspace*{-0.5in}The \textsf{graphviz} package\thanks{This document
% corresponds to \textsf{graphviz}~\fileversion, dated \filedate.}}
% \author{Derek Rayside $\langle$\texttt{drayside@uwaterloo.ca}$\rangle$ \\
% with contributions from 
% Ralf Hemmecke $\langle$\texttt{ralf@hemmecke.de}$\rangle$  }
%
% \maketitle
% 
% \setlength{\parskip}{1ex}
% \setlength{\parindent}{0ex}
%
% \section{Introduction}
%
% \textsf{graphviz.sty} is a \LaTeX\ package for writing
% \textsf{graphviz/dot/neato} graphs inside of \LaTeX\ documents.
% \textsf{graphviz.sty} was inspired by a feature that Daniel Jackson added
% to his \textsf{tagger} text markup tool.
%
% \textsf{graphviz} is a freely available package for doing automated
% graph layout from AT\&T Research, distributed under the Common
% Public License (CPL).  
% \textsf{graphviz}
% includes the \textsf{dot} and \textsf{neato} programs, which read a textual
% description of a graph and produces a graphical rendering of it.
% Many different graphics formats, include PostScript, are supported.
%
% There are two main web pages for the \textsf{graphviz} project:
% 
% \begin{itemize}
%
%     \item  \url{http://www.graphviz.org}
%
%     \item  \url{http://www.research.att.com/sw/tools/graphviz/}
% 
% \end{itemize}
%
% \textsf{graphviz.sty} is provided as-is, with no warranty or claim to
% fitness for any purpose, use at your own risk, etc.
% \textsf{graphviz.sty} 
% is distributed under the \LaTeX\ Project Public License.
%
% \section{Example}
%
% Put this in your document:
%
%   \hspace*{2em}|\digraph[scale=0.5]{abc}{rankdir=LR; a->b->c;}|
% 
% Run these commands (only the first run needs \texttt{-shell-escape}):
%
%   \hspace*{2em}|latex -shell-escape main.tex| \\
%   \hspace*{2em}|latex main.tex|
%
%
% And here's what you get:
% 
% \vspace{1ex}
% 
%   \hspace*{2em}\digraph[scale=0.5]{abc}{rankdir=LR; a->b->c;}
%
% \vspace{1ex}
%
% 
% \newpage
% \section{Usage}
%
% \DescribeMacro{\digraph\oarg{i}\marg{n}\marg{g}}
% The |\digraph| (\textsf{dot}) and |\neatograph| (\textsf{neato}) 
% commands take three arguments:
% 
% \begin{enumerate}
% 
%     \item[\oarg{i}]  parameters to the |\includegraphics|
%     command that will include the PostScript file of the graph
%     [this is optional]: eg, `\texttt{scale=0.5}'
% 
%     \item[\marg{n}]  the name of the graph; a file \texttt{name.dot} 
%     is created,
%     and a file \texttt{name.ps} is expected to be produced from
%     \textsf{dot}: eg, `\texttt{MyGraph}' \\
%     \marg{n} has to be a valid file name and a valid identifier name.
% 
%     \item[\marg{g}]  the graph, specified in the \textsf{dot/graphviz} 
%     language:
%     \\ eg, `\texttt{rankdir=LR; a->b->c;}'
% 
% \end{enumerate}
% 
% \section{Options}
%
%
% \begin{macro}{singlefile}
% \changes{v0.6}{2005/12/03}{added singlefile option}
% \changes{v0.7}{2005/12/29}{now using gvpr instead of gawk to break out individual digraphs from master.graphviz}
% \changes{v0.94}{2013/08/15}{writing gvpr commands to separate script to be executed when master.graphviz is closed}
%
% \LaTeX\ has a small number of file handles (about 16 or so).  So if
% you can't have too many digraphs in your tex file before you run out
% of file handles.  The \texttt{singlefile} option is a work-around:
% it writes all of your digraphs to a single file
% (\texttt{tmpmaster.graphviz}), and then uses \textsf{gvpr} to split that 
% file into individual dot files for processing by \textsf{dot}.
%
% The \textsc{gvpr} commands are all written to a second file 
% (\texttt{tmpmaster.gvpr}), which
% is executed once the \texttt{tmpmaster.graphviz} file has been closed.
%
% \textsf{gvpr} does not seem to be packaged with the Windows version
% of \textsf{dot}.
% 
%    \begin{macrocode}
\newif\ifsinglefile
\DeclareOption{singlefile}{
    \singlefiletrue
    \AtBeginDocument{% open a new file handle
        \newwrite\masterdotfile%
        \immediate\openout\masterdotfile=\@tmpdir tmpmaster.graphviz%
        \newwrite\mastergvprfile%
        \immediate\openout\mastergvprfile=\@tmpdir tmpmaster.gvpr}
    \AtEndDocument{% close the file
        % close the dot file and the gvpr file
        \immediate\closeout\masterdotfile%
        \immediate\closeout\mastergvprfile%
        % execute the gvpr file
        \immediate\write18{gvpr -f \@tmpdir tmpmaster.gvpr \@tmpdir tmpmaster.graphviz}%
        }}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{psfrag}
% \changes{v0.8}{2005/12/30}{added psfrag option}
%
% The \texttt{psfrag} option uses the \textsf{psfrag} package to
% enable you to overlay \TeX\ fragments over included postscript
% files, such as those generated via the |\digraph| command.
%
% The \textsf{ladot} script from Brighten Godfrey uses Perl to extend
% the syntax of the graphviz language with \TeX\ fragments, and 
% \textsf{psfrag} to super-impose those fragments.  
%
% The \texttt{psfrag} option requires sed.
% \textsf{psfrag} seems to only work with \textsf{dvips}: ie, it is
% not compatible with \textsf{pdflatex} or \textsf{dvipdfm}.
% The PDF files produced by \LaTeX/\textsf{psfrag/ps2pdf} seem to view 
% ok with \textsf{Acrobat}, but not with \textsf{gv}.  
% Oddly, the PS files produced this way work in \textsf{gv}.
%
% Put this in your document:
%
%   \hspace*{2em}|\psfrag{x2}[cc][cc]{$x^2$}| \\
%   \hspace*{2em}|\digraph{xy}{rankdir=LR; x2->y;}|
% 
% And here's what you get:
% 
% \vspace{1ex}
% 
%   \hspace*{2em}\psfrag{x2}[cc][cc]{$x^2$} \digraph[scale=0.5]{xy}{rankdir=LR; x2->y;}
%
% \vspace{1ex}
%
% 
%
%    \begin{macrocode}
\newif\ifpsfrag
\DeclareOption{psfrag}{ \psfragtrue }
%    \end{macrocode}
% \end{macro}
%
%
%
% \begin{macro}{ps}
% \changes{v0.92}{2013/08/15}{added ps option (previously default behaviour)}
%
% Tell Graphviz to generate Postscript files as output.
% 
%    \begin{macrocode}
\newcommand{\@outext}{ps}
\newcommand{\@outextspace}{ps }
\DeclareOption{ps}{
    \renewcommand{\@outext}{ps}
    \renewcommand{\@outextspace}{ps }}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{pdf}
% \changes{v0.92}{2013/08/15}{added pdf option}
%
% Tell Graphviz to generate PDF files as output.
% 
%    \begin{macrocode}
\DeclareOption{pdf}{%
    \renewcommand{\@outext}{pdf}%
    \renewcommand{\@outextspace}{pdf }}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{tmpdir}
% \changes{v0.93}{2013/08/15}{added tmpdir option}
%
% Write all generated files in |./tmp/|
% 
%    \begin{macrocode}
\newcommand{\@tmpdir}{}
\DeclareOption{tmpdir}{%
    \immediate\write18{mkdir ./tmp/}%
    \renewcommand{\@tmpdir}{./tmp/}}
%    \end{macrocode}
% \end{macro}
%
%
%
% \paragraph{Set the default options}
%
%    \begin{macrocode}
\ExecuteOptions{ps}
\ProcessOptions\relax % LaTeX class guide says it is wise to relax
%    \end{macrocode}
%
%
%
% \StopEventually{\PrintChanges\PrintIndex}
%
% \section{Implementation}
%
% \subsection{Required Packages}
% This package requires \textsf{graphicx} to include PostScript
% renderings of graphs.
%    \begin{macrocode}
\RequirePackage{graphicx}
\ifpsfrag \RequirePackage{psfrag} \fi
%    \end{macrocode}
%
% \subsection{Command Implementation}
%
% \begin{macro}{\digraph}
% \changes{v0.2}{2003/12/24}{minor adjustments}
% \changes{v0.4}{2004/05/14}{new comments}
% \changes{v0.5}{2004/05/19}{added automatic invocation of dot}
% \changes{v0.6}{2005/12/03}{added singlefile option}
% \changes{v0.7}{2005/12/29}{added backslash-hyphen line breaks by Ralf Hemmecke}
% \changes{v0.7}{2005/12/29}{now using gvpr instead of gawk to break out individual digraphs from master.graphviz}
% \changes{v0.7}{2005/12/29}{removed redundant invocation of dot from digraph; only inputdigraph needs to invoke dot}
% \changes{v0.9}{2006/01/08}{refactored for control-M by Ralf Hemmecke}
% \changes{v0.91}{2013/04/25}{a bit of cleanup and modernization}
%
% This is the command the user uses for \textsf{dot}.
%
% It is very important that this command is not defined with 3
% parameters although it will be used with 3 parameters in the
% form |\digraph[OPTIONS]{FILENAME}{GRAPH}|.
% The reason is that the catcode for |^^M|
% must be changed \emph{before} \TeX\ 
% reads the GRAPH argument.
%
% The order of the command (first |\inputdigraph| then |\@digraph|)
% may look a bit odd, but it simplifies the code. In order to include
% the digraph, \LaTeX\ has to be run at least two times anyway. In the
% first run the file \textsf{dot} will be generated and only
% the second run the digraph will be included.
% 
%    \begin{macrocode}
\newcommand{\digraph}[2][scale=1]{
  \inputdigraph[#1]{#2}{dot}%       % Include the generated ps/pdf.
  \@digraph{digraph}{#2}%           % Generate the .dot file.
}
%    \end{macrocode}
% \end{macro}
%
%
% \begin{macro}{\neatograph}
% \changes{v0.9}{2006/01/11}{added support for neato}
%
% This is the command the user uses for \textsf{neato}. The syntax is
% the same as for |\digraph|.
%
%    \begin{macrocode}
\newcommand{\neatograph}[2][scale=1]{
  \inputdigraph[#1]{#2}{neato}%     % Include the generated ps/pdf.
  \@digraph{graph}{#2}%             % Generate the .dot file.
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@digraph}
% Internal implementation.
%
% The macro |\@digraph| prepares the actual output of the digraph to a
% file (which is done by |\@@digraph|) by a special treatment of the
% newline character. 
% Before entering |\@@digraph|, the input newline character (|^^M|)
% is made active, and redefined to expand to |^^J|.
% Note that |\@digraph| has a |\begingroup| that is closed in
% |\@@digraph|.
%
% The purpose of this is to preserve line breaks in the digraph.
%
%    \begin{macrocode}
\begingroup
  \catcode`\^^M=\active%
  \gdef\@digraph{\begingroup\catcode`\^^M=\active\def^^M{^^J}\@@digraph}%
\endgroup
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@digraph}
% Internal implementation.
%
% The parameters of the macro |\@@digraph| are the TYPE, FILENAME and GRAPH
% of the initial |\digraph[OPTIONS]{FILENAME}{GRAPH}|.
% Note that if |\@@digraph| is entered the |^^M| character is active.
% Thus every newline character (|^^M|) in the following macro is
% hidden through a |%| sign at the end of line.
%    \begin{macrocode}
\def\@@digraph#1#2#3{%
    \ifsinglefile% write the graph to the master file
        \expandafter\def\csname -\endcsname{\string\n}%
        \immediate\write\masterdotfile{#1 #2 {#3}}%
        \immediate\write\mastergvprfile{BEG_G { if ($.name == "#2") {writeG($G,"\@tmpdir#2.dot");} }}%
    \else% open a new file handle
        \newwrite\dotfile%
        \immediate\openout\dotfile=\@tmpdir#2.dot%
        \expandafter\def\csname -\endcsname{\string\n}%
        \immediate\write\dotfile{#1 #2 {#3}}%
        \immediate\closeout\dotfile%
    \fi%
% Here comes the closing \endgroup that closes the group opened in \@digraph.
    \endgroup}%
% Now ^^M is no longer active.
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\inputdigraph}
% \changes{v0.2}{2003/12/24}{minor adjustments}
% \changes{v0.8}{2005/12/30}{added psfrag support}
%
% This is usually only called by |\digraph|,
% but may be called by the user.
%
% The purpose is to include the ps/pdf rendering of the graph if
% it exists, or to give instructions on how to generate it.
%
%    \begin{macrocode}
\newcommand{\inputdigraph}[3][scale=1]{
    % execute dot or neato (nb: requires latex -shell-escape)
    \immediate\write18{#3 -T\@outextspace -o \@tmpdir#2.\@outextspace \@tmpdir#2.dot}
    \IfFileExists{\@tmpdir#2.\@outext}{ % the postscript/pdf exists: include it
            \ifpsfrag
                % per the ladot 2.2 source code, psfrag has a problem with
                % graphviz 2.2, and some sed hackery is necessary to work around
                \write18{sed -ibackup -e "s/xshow/pop show/g" \@tmpdir#2.ps}
            \fi
            \includegraphics[#1]{\@tmpdir#2.\@outext} 
        }
        % else: the postscript/pdf doesn't exist: tell the user how to create it
        { 
            \fbox{ \begin{tabular}{l}
                The file \texttt{#2.\@outext} hasn't been created from 
                \texttt{\@tmpdir#2.dot} yet. \\ 
                Run `\texttt{dot -T\@outextspace -o \@tmpdir#2.\@outextspace \@tmpdir#2.dot}' 
                to create it. \\
                Or invoke \LaTeX\ with the \texttt{-shell-escape} option
                to have this done automatically. \\
                \end{tabular}}
        }
}
%    \end{macrocode}
% \end{macro}
%
%
%
% \subsection{Process}
% 
% |\digraph| writes out a \textsf{dot} file, and then invokes
% \textsf{dot} on it.  
% 
% Note:  |\digraph| can only invoke \textsf{dot} if the \LaTeX\ was
% invoked with the \texttt{-shell-escape} option, to enable execution of
% external programs.  If you do not want to allow \LaTeX\ to execute
% external programs, then you will have to invoke \textsf{dot} yourself.
% \textsf{graphviz} will also need to execute \textsf{gvpr} if the 
% \texttt{singlefile} option has been selected, and \textsf{sed} if
% the \texttt{psfrag} option has been selected.
% 
% Here's a picture of the process (drawn with \textsf{dot},
% naturally). The picture shows the process using dvips, but pdflatex
% is now also supported with the pdf option.
%
% \begin{center}
% 
% \digraph[height=\textheight-2in]{process}{
%     /* PROGRAMS */
%     latex1 [label="latex -shell-escape x.tex", shape=hexagon, fontname=Courier];
%     latex2 [label="latex x.tex", shape=hexagon, fontname=Courier];
%     dvips [label="dvips -o x.ps x.dvi", shape=hexagon, fontname=Courier];
%     /* FILES */
%     xTex [label="x.tex", fontname=Helvetica, shape=ellipse];
%     xDvi [label="x.dvi", fontname=Helvetica, shape=ellipse];
%     xPS [label="x.ps", fontname=Helvetica, shape=ellipse];
%     subgraph cluster0 {
%         label="graphviz.sty magic";
%         dot [label="dot -Tps -o a.ps a.dot", shape=hexagon, fontname=Courier];
%         gvpr [label="gvpr master.graphviz", shape=hexagon, fontname=Courier];
%         aPS [label="a.ps", fontname=Helvetica, shape=ellipse];
%         sed [label="sed s/xshow/pop show/g a.ps", shape=hexagon, fontname=Courier];
%         aDot [label="a.dot", fontname=Helvetica, shape=ellipse];
%         master [label="master.graphviz", fontname=Helvetica, shape=ellipse];
%     };
%     /* COMMON EDGES */
%     xTex -> latex1;
%     xTex -> latex2;
%     latex2 -> xDvi;
%     xDvi -> dvips;
%     dvips -> xPS;
%     latex1 -> master [style=dotted, label=singlefile];
%     latex1 -> aDot [style=dotted, label="multiple files"];
%     master -> gvpr;
%     gvpr -> aDot;
%     aDot -> dot;
%     dot -> aPS;
%     aPS -> sed;
%     sed -> aPS;
%     aPS -> dvips;
%     aPS -> latex2;
% }
% \end{center}
%
% \newpage
%
%
%
% \Finale
\endinput