From: Emden Gansner Date: Thu, 28 Feb 2013 16:29:24 +0000 (-0500) Subject: Update libguide to reflect use of cgraph; store original as oldlibguide.pdf. X-Git-Tag: LAST_LIBGRAPH~32^2~220^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=8d25fce41c17dabdfa22cbe68c4bb72a3545b1bf;p=graphviz Update libguide to reflect use of cgraph; store original as oldlibguide.pdf. --- diff --git a/doc/libguide/Makefile b/doc/libguide/Makefile index c1a1c2658..6971e317b 100644 --- a/doc/libguide/Makefile +++ b/doc/libguide/Makefile @@ -9,8 +9,11 @@ all : libguide.pdf # libguide.bbl -libguide.pdf : libguide.ps - ps2pdf libguide.ps libguide.pdf +libguide.pdf : libguide.tex + $(PTEX) libguide + bibtex libguide + $(PTEX) libguide + @if grep "Label(s) may have changed" libguide.log; then $(PTEX) libguide; fi libguide.ps : libguide.dvi @if grep "Label(s) may have changed" libguide.log; then $(TEX) libguide.tex; fi diff --git a/doc/libguide/basic.tex b/doc/libguide/basic.tex index 532bcdbd9..1246bfa1a 100644 --- a/doc/libguide/basic.tex +++ b/doc/libguide/basic.tex @@ -37,17 +37,13 @@ Section~\ref{sec:gvc}. \subsection{Creating the graph} The first step in drawing a graph is to create it. To use the \gviz\ layout software, the graph must be created using the \graph\ library. -Before any other function in \graph\ is called, an application must -call the library initialization function {\tt aginit}. This -function is called by {\tt gvContext} and {\tt gvParseArgs}, -so if either of these is used, -no additional call to {\tt aginit} is necessary.\footnote{See -Section~\ref{sec:layout_info} for a description of occasions when -the more general function {\tt aginitlib} should be called first.} -Also, it is safe to make multiple calls to {\tt aginit}. We can create a graph in one of two main ways, using {\tt agread} or {\tt agopen}. The former function takes a {\tt FILE*} pointer to a file open for reading. +\begin{verbatim} + FILE* fp; + Agraph_t* G = agread(fp, 0); +\end{verbatim} It is assumed the file contains the description of graphs using the \DOT\ language. The {\tt agread} function parses one graph at a time, returning a pointer to an attributed graph generated from the input, @@ -58,28 +54,21 @@ the \DOT\ representation of the graph is stored in memory at {\tt char* cp}, the \begin{verbatim} Agraph_t* G = agmemread(cp); \end{verbatim} -can be used to parse the representation. The {\tt agread} function relies on the +can be used to parse the representation. By default, the {\tt agread} function relies on the standard {\tt FILE} structure and {\tt fgets} function of the stdio library. You -can supply your own text reading function {\tt mygets} coupled with a compatible -source of text {\tt fp} -to read a graph using +can supply your own data source {\tt dp} coupled with your own discipline {\tt disc} +for reading the data to read a graph using \begin{verbatim} - Agraph_t* G = agread_usergets((FILE*)fp, mygets); + Agraph_t* G = agread(dp, &disc); \end{verbatim} -{\bf N.B.} If you use a Windows binary distribution of \gviz\, it is possible that -the {\tt FILE} structure used during the build of \gviz\ is different from the one -used in your compilation system. In this case, a call to {\tt agread} will not work, -and you will need to either use {\tt agread\_usergets}, -supplying your version of {\tt fgets}, -or {\tt agmemread}. - +Further details on using {\tt agread} and disciplines can be found in the \graph\ library manual. The alternative technique is to call {\tt agopen}. \begin{verbatim} - Agraph_t* G = agopen(name, type); + Agraph_t* G = agopen(name, type, &disc); \end{verbatim} The first argument is a {\tt char*} giving the name of the graph; -the second argument is an {\tt int} value describing the type of graph +the second argument is an {\tt Agdesc\_t} value describing the type of graph to be created. A graph can be directed or undirected. In addition, a graph can be strict, i.e., have at most one edge between any pair of nodes, or non-strict, allowing an arbitrary number of edges @@ -92,24 +81,26 @@ The return value is a new graph, with no nodes or edges. \centering \begin{tabular}{|l|l|} \hline Graph Type & Graph \\ \hline -AGRAPH & Non-strict, undirected graph \\ -AGRAPHSTRICT & Strict, undirected graph \\ -AGDIGRAPH & Non-strict, directed graph \\ -AGDIGRAPHSTRICT & Strict, directed graph \\ \hline +Agundirected & Non-strict, undirected graph \\ +Agstrictundirected & Strict, undirected graph \\ +Agdirected & Non-strict, directed graph \\ +Agstrictdirected & Strict, directed graph \\ \hline \end{tabular} \caption{Graph types} \label{table:types} \end{table*} -So, to open a graph name {\tt "network"} that is directed but not strict, one would use +So, to open a graph named {\tt "network"} that is directed but not strict, one would use \begin{verbatim} - Agraph_t* G = agopen("network", AGDIGRAPH); + Agraph_t* G = agopen("network", Agdirected, 0); \end{verbatim} +The third argument is a pointer to a discipline of functions used for reading, memory, etc. +If the value of 0 or NULL is used, the library uses a default discipline. Nodes and edges are created by the functions {\tt agnode} and {\tt agedge}, respectively. \begin{verbatim} - Agnode_t *agnode(Agraph_t*, char*); - Agedge_t *agedge(Agraph_t*, Agnode_t*, Agnode_t*); + Agnode_t *agnode(Agraph_t*, char*, int); + Agedge_t *agedge(Agraph_t*, Agnode_t*, Agnode_t*, char*, int); \end{verbatim} The first argument is the graph containing the node or edge. Note that if this is a subgraph, the node or edge will also belong to @@ -117,11 +108,14 @@ all containing graphs. The second argument to {\tt agnode} is the node's name. This is a key for the node within the graph. If {\tt agnode} is called twice with the same name, the second invocation will not create a new node but simply return a pointer to the previously -created node with the given name. +created node with the given name. The third argument specifies whether or not +a node of the given name should be created if it does not already exist. Edges are created using {\tt agedge} by passing in the edge's two nodes. If the graph is not strict, additional calls to {\tt agedge} with the same arguments will create additional edges between the two nodes. +The string argument allows you to supply a further name to distinguish between +edges with the same head and tail. If the graph is strict, extra calls will simply return the already existing edge. For directed graphs, the first and @@ -129,15 +123,17 @@ second node arguments are taken to be the tail and head nodes, respectively. For undirected graph, they still play this role for the functions {\tt agfstout} and {\tt agfstin}, but when checking if an edge exists with {\tt agedge} or {\tt agfindedge}, the order is -irrelevant. +irrelevant. As with {\tt agnode}, the final argument specifies whether or not +the edge should be created if it does not yet exist. As suggested above, a graph can also contain subgraphs. These are created using {\tt agsubg}: \begin{verbatim} - Agraph_t *agsubg(Agraph_t*, char*); + Agraph_t *agsubg(Agraph_t*, char*, int); \end{verbatim} The first argument is the immediate parent graph; the second argument -is the name of the subgraph. +is the name of the subgraph; the final argument indicates if the subgraph should +be created. Subgraphs play three roles in \gviz. First, a subgraph can be used to represent graph structure, indicating that @@ -205,12 +201,11 @@ default in both cases. Setting attributes is a bit more complex. Before attaching an attribute to a graph component, the code must first set up the default case. This -is accomplished by a call to {\tt agraphattr}, {\tt agnodeattr} or -{\tt agedgeattr} for graph, node or edge attributes, respectively. -The types of the 3 functions are identical. They all take a graph and +is accomplished by a call to {\tt agattr}. +It takes a graph, an object type ({\tt AGRAPH, AGNODE, AGEDGE}), and two strings as arguments, and return a representation of the attribute. The first string gives the name of the attribute; the second supplies -the default value, which must not be {\tt NULL}. +the default value. The graph must be the root graph. Once the attribute has been initialized, the attribute can be set for @@ -227,7 +222,7 @@ For example, the call sets the color of node {\tt np} to {\tt "blue"}. The attribute value must not be {\tt NULL}. -For simplicity, the \graph library provides the function +For simplicity, the \graph\ library provides the function \begin{verbatim} agsafeset(void*, char*, char*, char*) \end{verbatim} @@ -271,15 +266,17 @@ In order to expedite the reading and writing of attributes for large graphs, \gviz\ provides a lower-level mechanism for manipulating attributes which can avoid hashing a string. Attributes have a representation of type \verb+Agsym_t+. This is basically the -value returned by the initialization functions {\tt agraphattr}, etc. -It can also be obtained by a call to {\tt agfindattr}, which takes +value returned by the initialization function {\tt agattr}. (Passing {\tt NULL} +as the default value will cause {\tt agattr} to return the \verb+Agsym_t+ if +it exists, and {\tt NULL} otherwise.) +An attribute can also be obtained by a call to {\tt agattrsym}, which takes a graph component and an attribute name. If the attribute has been defined, the function returns a pointer to the corresponding \verb+Agsym_t+ value. This can be used to directly access the corresponding attribute value, using the functions {\tt agxget} and {\tt agxset}. These are identical to {\tt agget} and {\tt agset}, respectively, except that instead of taking the attribute name as the second argument, they use -the {\tt index} field of the \verb+Agsym_t+ value to extract the attribute +the \verb+Agsym_t+ value to access the attribute value from an array. Due to the nature of the implementation of attributes in \gviz, an application @@ -288,9 +285,10 @@ attributes before creating nodes and edges. The drawing algorithms in \gviz\ use a large collection of attributes, giving the application a great deal of control over the appearance of the -drawing. For more detailed information on what the attributes mean, the -reader should consult the manual {\bf Drawing graphs with \dot}. +drawing. For more detailed and complete information on what the attributes mean, the +reader should consult the page \url{http://www.graphviz.org/content/attrs}. +Here, we consider some of the more commonly used attributes. We can divide the attributes into those that affect the placement of nodes, edges and clusters in the layout and those, such as color, which do not. diff --git a/doc/libguide/codegen.tex b/doc/libguide/codegen.tex index 2c4a3bc9a..99e9de86b 100644 --- a/doc/libguide/codegen.tex +++ b/doc/libguide/codegen.tex @@ -252,9 +252,8 @@ relevant to input and GUIs. \begin{description} \item[{\tt common}] This points to various information valid throughout the duration -of the application using \gviz. In particular, {\tt common->user} -gives the user name associated to the related {\tt GVC\_t} value -(see Section~\ref{sec:gvc}), and {\tt common->info} contains \gviz\ version +of the application using \gviz. In particular, +the {\tt common->info} contains \gviz\ version information, as described in Section~\ref{sec:info}. \item[{\tt output\_file}] The {\tt FILE*} value for an open stream on diff --git a/doc/libguide/drivers.tex b/doc/libguide/drivers.tex index 778be4a62..06d2dfc45 100644 --- a/doc/libguide/drivers.tex +++ b/doc/libguide/drivers.tex @@ -22,25 +22,11 @@ with only one graph at a time. In addition, if {\tt gvLayout()} was invoked for a graph and \gvc, then {\tt gvFreeLayout()} should be called before using {\tt gvLayout()} again, even on the same graph. -An instance of a \gvc\ can be created by a call to -\begin{verbatim} - extern GVC_t *gvNEWcontext(char **info, char *user); -\end{verbatim} -The first argument is an array of three character pointers -providing version information; see Section~\ref{sec:info} below for a -description of this data. The second argument is a string giving a -name for the user. If desired, the application can call the library -function {\tt gvUsername()} to obtain this value. These strings -are stored in the \gvc\ and used in various messages and comments. - -For convenience, the \gviz\ library provides a simple way to -create a context: +Normally, one creates a \gvc\ by a call to: \begin{verbatim} extern GVC_t *gvContext(); \end{verbatim} which is what we have used in the examples shown here. -This uses version information created when \gviz\ was built, plus -the value returned by {\tt gvUsername()}. One can initialize a \gvc\ to record a list of graphs, layout algorithms and renderers. To do this, the application should @@ -91,24 +77,18 @@ and layout algorithm to the \gvc, as would be done by {\tt gvParseArgs}, and then invokes {\tt gvLayoutJobs}. A similar remark holds for {\tt gvRender} and {\tt gvRenderJobs}. -\subsection{Application-specific data} +\subsection{Version-specific data} \label{sec:info} -It is sometimes useful to supply version information. -For example, some renderers in \gviz\ the library version used -to create the output file. To do this, they rely on -the application providing an array +When the \gvc\ is created, it stores version and build date information +that can be used by renderers to identify which version of \gviz\ produced +the output. It is also what is printed when a layout program is given the {\tt -V} +flag. This information is stored as an array of three {\tt char*}, giving the +name, version number and build date, respectively. +These can be accessed via the functions: \begin{verbatim} - extern char* Info[3]; -\end{verbatim} -giving the desired version information. -The three strings should be the name of the application, the version -of the application, and a build date. For example, \dot\ might provide -\begin{verbatim} - char *Info[] = { - "dot", /* Program */ - "1.8.10", /* Version */ - "16 Dec 2006" /* Build Date */ - }; +extern char **gvcInfo(GVC_t*); +extern char *gvcVersion(GVC_t*); +extern char *gvcBuildDate(GVC_t*); \end{verbatim} diff --git a/doc/libguide/layouts.tex b/doc/libguide/layouts.tex index ae681559c..d3e8331e7 100644 --- a/doc/libguide/layouts.tex +++ b/doc/libguide/layouts.tex @@ -238,6 +238,26 @@ route the edges. In \fdp, because it is necessary to keep clusters separate, the removal of overlaps is (usually) obligatory. +\subsection{\sfdp} +\label{sec:sfdp} + +The \sfdp\ layout is similar to \fdp\, except it uses a refined multilevel +approach that enables it to handle very large graphs. The algorithm is +due to Hu\cite{sfdp}. + +Unlike \fdp, \sfdp\ does not support cluster subgraphs. It also +does not model edge lengths or weights. + +\begin{verbatim} + initialize + position + adjust + splines +\end{verbatim} + +The layout scheme is fairly simple: initialization; layout; node overlap removal; and a call to +route the edges. + \subsection{\twopi} \label{sec:twopi} diff --git a/doc/libguide/libguide.pdf b/doc/libguide/libguide.pdf index 444d02249..360c51db8 100644 Binary files a/doc/libguide/libguide.pdf and b/doc/libguide/libguide.pdf differ diff --git a/doc/libguide/libguide.tex b/doc/libguide/libguide.tex index 35f5a3b16..d8f851670 100644 --- a/doc/libguide/libguide.tex +++ b/doc/libguide/libguide.tex @@ -1,6 +1,7 @@ \documentclass[11pt]{article} %\usepackage{graphicx} \usepackage{times} +\usepackage{url} %\addtolength{\oddsidemargin}{-0.5in} %\addtolength{\evensidemargin}{-0.5in} @@ -18,23 +19,25 @@ \def\DOT{{\it DOT}} \def\neato{{\it neato}} \def\fdp{{\it fdp}} +\def\sfdp{{\it sfdp}} \def\twopi{{\it twopi}} \def\circo{{\it circo}} \def\gviz{{\it Graphviz}} -\def\graph{{\tt graph}} +\def\graph{{\tt cgraph}} \def\agraph{{\tt libagraph}} \def\pack{{\tt pack}} \def\gvc{{\tt GVC\_t}} -\newcommand{\lastedited}{16 August 2006} +\newcommand{\lastedited}{17 February 2013} \date{\today} -\newcommand{\mymark}{\gviz{} Drawing Library Manual, \today \hfil } +\newcommand{\mymark}{\gviz{} Library Manual, \today \hfil } \markboth{\mymark}{\mymark} \begin{document} \bibliographystyle{alpha} \author{Emden R. Gansner} -\title{Drawing graphs with \gviz} +\title{Using \gviz as a Library \\ +(cgraph version)} \maketitle \newpage diff --git a/doc/libguide/samples.tex b/doc/libguide/samples.tex index da4e7fcc2..258d31533 100644 --- a/doc/libguide/samples.tex +++ b/doc/libguide/samples.tex @@ -6,14 +6,13 @@ using the {\tt plain} format. An application can replace the call to {\tt gvRender} with its own function for rendering the graph, using the layout information encoded in the graph structure (cf. Section~\ref{sec:layout_info}). -\pagebreak[4] \begin{verbatim} #include int main(int argc, char **argv) { GVC_t *gvc; - graph_t *g; + Agraph_t *g; FILE *fp; gvc = gvContext(); @@ -22,7 +21,7 @@ int main(int argc, char **argv) fp = fopen(argv[1], "r"); else fp = stdin; - g = agread(fp); + g = agread(fp, 0); gvLayout(gvc, g, "dot"); @@ -35,6 +34,7 @@ int main(int argc, char **argv) return (gvFreeContext(gvc)); } \end{verbatim} +\newpage \section{A sample program: {\tt dot.c}} \label{sec:dot} @@ -50,7 +50,7 @@ minor details. int main(int argc, char **argv) { - graph_t *g, *prev = NULL; + Agraph_t *g, *prev = NULL; GVC_t *gvc; gvc = gvContext(); @@ -69,6 +69,7 @@ int main(int argc, char **argv) } \end{verbatim} +\newpage \section{A sample program: {\tt demo.c}} \label{sec:demo} @@ -93,10 +94,10 @@ int main(int argc, char **argv) gvParseArgs(gvc, argc, argv); /* Create a simple digraph */ - g = agopen("g", AGDIGRAPH); - n = agnode(g, "n"); - m = agnode(g, "m"); - e = agedge(g, n, m); + g = agopen("g", Agdirected); + n = agnode(g, "n", 1); + m = agnode(g, "m", 1); + e = agedge(g, n, m, 0, 1); /* Set an attribute - in this case one that affects the visible rendering */ agsafeset(n, "color", "red", ""); diff --git a/doc/libguide/unconnect.tex b/doc/libguide/unconnect.tex index f475499b9..077643c45 100644 --- a/doc/libguide/unconnect.tex +++ b/doc/libguide/unconnect.tex @@ -21,9 +21,9 @@ basic layout algorithms given an input graph {\tt g} and a \gvc\ value {\tt gvc}. \begin{verbatim} - graph_t *sg; + Agraph_t *sg; FILE *fp; - graph_t** cc; + Agraph_t** cc; int i, ncc; cc = ccomps(g, &ncc, (char*)0); diff --git a/doc/oldlibguide.pdf b/doc/oldlibguide.pdf new file mode 100644 index 000000000..444d02249 Binary files /dev/null and b/doc/oldlibguide.pdf differ