--- /dev/null
+.TH tcldot 3tcl "Tcl Extensions"
+
+.SH NAME
+
+tcldot \- graph manipulation in tcl
+
+.SH SYNOPSIS
+
+#!/usr/local/bin/tclsh
+.br
+package require \fBTcldot\fR
+
+.SH USAGE
+Requires the dynamic loading facilities of tcl7.6 or later.
+
+.SH INTRODUCTION
+
+.B tcldot
+is a tcl dynamically loaded extension that incorporates
+the directed graph facilities of
+.B dot(1),
+and the undirected graph facilities of
+.B neato(1),
+into tcl and provides a set of commands to control those
+facilities.
+.B tcldot
+converts
+.B dot
+and
+.B neato
+from batch processing tools to an interpreted and, if needed, interactive set
+of graph manipulation facilities.
+
+.SH COMMANDS
+
+.B tcldot
+initially adds only three commands to tcl, namely
+.B dotnew,
+.B dotread,
+and
+.B dotstring.
+These commands return a handle for the graph that has just been created
+and that handle can then be used as a command for further actions on the graph.
+
+All other "commands" are of the form:
+.IP
+.I handle
+.B <method>
+.I parameters
+.PP
+Many of the methods return further
+handles of graphs, nodes of edges, which are themselves registered as commands.
+
+The methods are described in detail below, but in summary:
+.PP
+Graph methods are:
+.IP
+.B "addedge, addnode, addsubgraph, countedges, countnodes, layout, listattributes, listedgeattributes, listnodeattributes, listedges, listnodes, listnodesrev, listsubgraphs, render, rendergd, queryattributes, queryedgeattributes, querynodeattributes, queryattributevalues, queryedgeattributevalues, querynodeattributevalues, setattributes, setedgeattributes, setnodeattributes, showname, write."
+.PP
+Node methods are:
+.IP
+.B "addedge, listattributes, listedges, listinedges, listoutedges, queryattributes, queryattributevalues, setattributes, showname."
+.PP
+Edge methods are:
+.IP
+.B "delete, listattributes, listnodes, queryattributes, queryattributevalues, setattributes, showname."
+
+.TP
+\fBdotnew\fR \fIgraphType ?attributeName attributeValue? ?...?\fR
+
+creates a new empty graph and returns its
+.I graphHandle.
+
+.I graphType
+can be any supported by
+.B dot(1)
+namely: "graph," "digraph," "graphstrict," or "digraphstrict."
+(In digraphs edges have a direction from tail to head. "Strict" graphs
+or digraphs collapse multiple edges between the same pair of
+nodes into a single edge.)
+
+Following the mandatory
+.I graphType
+parameter the
+.B dotnew
+command will accept an arbitrary number of attribute name/value pairs
+for the graph.
+Certain special graph attributes and permitted values are described in
+.B dot(1),
+but the programmer can arbitrarily invent and assign values
+to additional attributes beyond these.
+In
+.B dot
+the attribute name is separated from the value by an "=" character.
+In
+.B tcldot
+the "=" has been replaced by a " " (space) to be more consistent
+with
+.B tcl
+syntax.
+e.g.
+.nf
+
+ set g [dotnew digraph rankdir LR]
+
+.fi
+.TP
+\fBdotread\fR \fIfileHandle\fR
+
+reads in a dot-language description of a graph from a previously opened
+file identified by the
+.I fileHandle.
+The command returns the
+.I graphHandle
+of the newly read graph. e.g.
+.nf
+
+ set f [open test.dot r]
+ set g [dotread $f]
+
+.fi
+.TP
+\fBdotstring\fR \fIstring\fR
+
+reads in a dot-language description of a graph from a Tcl string;
+The command returns the
+.I graphHandle
+of the newly read graph. e.g.
+.nf
+
+ set g [dotread $dotsyntaxstring]
+
+.fi
+.TP
+\fIgraphHandle\fR \fBaddnode\fR \fI?nodeName? ?attributeName attributeValue? ?...?\fR
+
+creates a new node in the graph whose handle is
+.I graphHandle
+and returns its
+.I nodeHandle.
+The handle of a node is a string like: "node0" where the integer value is
+different for each node.
+There can be an arbitrary number of attribute name/value pairs
+for the node.
+Certain special node attributes and permitted values are described in
+.B dot(1),
+but the programmer can arbitrarily invent and assign values
+to additional attributes beyond these.
+e.g.
+.nf
+
+ set n [$g addnode "N" label "Top\\nNode" shape triangle eggs easyover]
+
+.fi
+A possible cause of confusion in
+.B tcldot
+is the distinction between handles, names, labels, and variables.
+The distinction is primarily in who owns them.
+Handles are owned by tcldot and are guaranteed to be unique within
+one interpreter session. Typically handles are assigned to variables,
+like "n" above, for manipulation within a tcl script.
+Variables are owned by the programmer.
+Names are owned by the application that is using the
+graph, typically names are important when reading in a graph from
+an external program or file. Labels are the text that is displayed with
+the node
+(or edge) when the graph is displayed, labels are meaningful to the
+reader of the graph. Only the handles and variables are essential to
+.B tcldot's
+ability to manipulate abstract graphs. If a name is not specified then
+it defaults to the string representation of the handle, if a label is
+not specified then it defaults to the name.
+
+.TP
+\fIgraphHandle\fR \fBaddedge\fR \fItailNode headNode ?attributeName attributeValue? ?...?\fR
+
+creates a new edge in the graph whose handle is
+.I graphHandle
+and returns its
+.B edgeHandle.
+.I tailNode
+and
+.I headNode
+can be specified either by their
+.I nodeHandle
+or by their
+.I nodeName.
+e.g.
+.nf
+
+ set n [$g addnode]
+ set m [$g addnode]
+ $g addedge $n $m label "NM"
+
+ $g addnode N
+ $g addnode M
+ $g addedge N M label "NM"
+
+.fi
+The argument is recognized as a handle if possible and so it is best
+to avoid names like "node6" for nodes. If there is potential for conflict then use
+.B findnode
+to translate explicitly from names to handles.
+e.g.
+.nf
+
+ $g addnode "node6"
+ $g addnode "node99"
+ $g addedge [$g findnode "node6"] [$g findnode "node99"]
+
+.fi
+There can be an arbitrary number of attribute name/value pairs
+for the edge.
+Certain special edge attributes and permitted values are described in
+.B dot(1),
+but the programmer can arbitrarily invent and assign values
+to additional attributes beyond these.
+
+.TP
+\fIgraphHandle\fR \fBaddsubgraph\fR \fI?graphName? ?attributeName attributeValue? ?...?\fR
+
+creates a new subgraph in the graph and returns its
+.I graphHandle.
+If the
+.I graphName
+is omitted then the name of the subgraph defaults to it's
+.I graphHandle.
+There can be an arbitrary number of attribute name/value pairs
+for the subgraph.
+Certain special graph attributes and permitted values are described in
+.B dot(1),
+but the programmer can arbitrarily invent and assign values
+to additional attributes beyond these.
+e.g.
+.nf
+
+ set sg [$g addsubgraph dinglefactor 6]
+
+.fi
+Clusters, as described in
+.B dot(1),
+are created by giving the subgraph a name that begins with the string:
+"cluster". Cluster can be labelled by using the \fIlabel\fR attibute.
+e.g.
+.nf
+
+ set cg [$g addsubgraph cluster_A label dongle dinglefactor 6]
+
+.fi
+.TP
+\fInodeHandle\fR \fBaddedge\fR \fIheadNode ?attributeName attributeValue? ?...?\fR
+
+creates a new edge from the tail node identified by tha
+.I nodeHandle
+to the
+.I headNode
+which can be specified either by
+.I nodeHandle
+or by
+.I nodeName
+(with preference to recognizing the argument as a handle).
+The graph in which this is drawn is the graph in which both nodes are
+members.
+There can be an arbitrary number of attribute name/value pairs
+for the edge.
+These edge attributes and permitted values are described in
+.B dot(1).
+e.g.
+.nf
+
+ [$g addnode] addedge [$g addnode] label "NM"
+
+.fi
+.TP
+\fIgraphHandle\fR \fBdelete\fR
+.TP
+\fInodeHandle\fR \fBdelete\fR
+.TP
+\fIedgeHandle\fR \fBdelete\fR
+
+Delete all data structures associated with the graph, node or edge
+from the internal storage of the interpreter. Deletion of a node also
+results in the the deletion of all subtending edges on that node.
+Deletion of a graph also results in the deletion of all nodes and
+subgraphs within that graph (and hence all edges too). The return from
+these delete commands is a null string.
+
+.TP
+\fIgraphHandle\fR \fBcountnodes\fR
+.TP
+\fIgraphHandle\fR \fBcountedges\fR
+
+Returns the number of nodes, or edges, in the graph.
+
+.TP
+\fIgraphHandle\fR \fBlistedges\fR
+.TP
+\fIgraphHandle\fR \fBlistnodes\fR
+.TP
+\fIgraphHandle\fR \fBlistnodesrev\fR
+.TP
+\fIgraphHandle\fR \fBlistsubgraphs\fR
+.TP
+\fInodeHandle\fR \fBlistedges\fR
+.TP
+\fInodeHandle\fR \fBlistinedges\fR
+.TP
+\fInodeHandle\fR \fBlistoutedges\fR
+.TP
+\fIedgeHandle\fR \fBlistnodes\fR
+
+Each return a list of handles of graphs, nodes or edges, as appropriate.
+
+.TP
+\fIgraphHandle\fR \fBfindnode\fR \fInodeName\fR
+.TP
+\fIgraphHandle\fR \fBfindedge\fR \fItailnodeName headNodeName\fR
+.TP
+\fInodeHandle\fR \fBfindedge\fR \fInodeName\fR
+
+Each return the handle of the item if found, or an error if none are found.
+For non-strict graphs when there are multiple edges between two nodes
+.B findedge
+will return an arbitrary edge from the set.
+
+.TP
+\fIgraphHandle\fR \fBshowname\fR
+.TP
+\fInodeHandle\fR \fBshowname\fR
+.TP
+\fIedgeHandle\fR \fBshowname\fR
+
+Each return the name of the item. Edge names are of the form:
+"a\->b" where "a" and "b" are the names of the nodes and the connector
+"\->" indicates the tail-to-head direction of the edge. In undirected
+graphs the connector "\-\-" is used.
+
+.TP
+\fIgraphHandle\fR \fBsetnodeattributes\fR \fIattributeName attributeValue ?...?\fR
+.TP
+\fIgraphHandle\fR \fBsetedgeattributes\fR \fIattributeName attributeValue ?...?\fR
+
+Set one or more default attribute name/values that are to apply to
+all nodes (edges) unless overridden by subgraphs or per-node
+(per-edge) attributes.
+
+.TP
+\fIgraphHandle\fR \fBlistnodeattributes\fR
+.TP
+\fIgraphHandle\fR \fBlistedgeattributes\fR
+
+Return a list of attribute names.
+
+.TP
+\fIgraphHandle\fR \fBquerynodeattributes\fR \fIattributeName ?...?\fR
+.TP
+\fIgraphHandle\fR \fBqueryedgeattributes\fR \fIattributeName ?...?\fR
+
+Return a list of default attribute value, one value for each of the
+attribute names provided with the command.
+
+.TP
+\fIgraphHandle\fR \fBquerynodeattributes\fR \fIattributeName ?...?\fR
+.TP
+\fIgraphHandle\fR \fBqueryedgeattributes\fR \fIattributeName ?...?\fR
+
+Return a list of pairs of attrinute name and default attribute value,
+one pair for each of the attribute names provided with the command.
+
+.TP
+\fIgraphHandle\fR \fBsetattributes\fR \fIattributeName attributeValue ?...?\fR
+.TP
+\fInodeHandle\fR \fBsetattributes\fR \fIattributeName attributeValue ?...?\fR
+.TP
+\fIedgeHandle\fR \fBsetattributes\fR \fIattributeName attributeValue ?...?\fR
+
+Set one or more attribute name/value pairs for a specific graph, node,
+or edge instance.
+
+.TP
+\fIgraphHandle\fR \fBlistattributes\fR
+.TP
+\fInodeHandle\fR \fBlistattributes\fR
+.TP
+\fIedgeHandle\fR \fBlistattributes\fR
+
+Return a list of attribute names (attribute values are provided by
+.B queryattribute
+
+.TP
+\fIgraphHandle\fR \fBqueryattributes\fR \fIattributeName ?...?\fR
+.TP
+\fInodeHandle\fR \fBqueryattributes\fR \fIattributeName ?...?\fR
+.TP
+\fIedgeHandle\fR \fBqueryattributes\fR \fIattributeName ?...?\fR
+
+Return a list of attribute value, one value for each of the
+attribute names provided with the command.
+
+.TP
+\fIgraphHandle\fR \fBqueryattributevalues\fR \fIattributeName ?...?\fR
+.TP
+\fInodeHandle\fR \fBqueryattributevalues\fR \fIattributeName ?...?\fR
+.TP
+\fIedgeHandle\fR \fBqueryattributevalues\fR \fIattributeName ?...?\fR
+
+Return a list of pairs or attribute name and attribute value,
+one value for each of the attribute names provided with the command.
+
+.TP
+\fIgraphHandle\fR \fBlayout ?dot|neato|circo|twopi|fdp|nop?\fR
+
+Annotate the graph with layout information. This commands takes an
+abstract graph add shape and position information to it according to
+the layout engine's rules of eye-pleasing graph layout. If the layout engine is
+unspecified then it defaults to \fBdot\fR for directed graphs, and \fBneato\fR otherwise.
+If the \fBnop\fR engine is specified then layout infomation from the input graph is used.
+The result of the layout is stored
+as additional attributes name/value pairs in the graph, node and edges.
+These attributes are intended to be interpreted by subsequent
+.I write
+or
+.I render
+commands.
+
+.TP
+\fIgraphHandle\fR \fBwrite\fR \fIfileHandle format ?dot|neato|circo|twopi|fdp|nop?\fR
+
+Write a graph to the open file represented by
+.I fileHandle
+in a specific
+.I format.
+Possible
+.I formats
+are: "ps" "mif" "hpgl" "plain" "dot" "gif" "ismap"
+If the layout hasn't been already done, then it will be done as part
+of this operation using the same rules for selecting the layout engine
+as for the layout command.
+
+.TP
+\fIgraphHandle\fR \fBrendergd\fR \fIgdHandle\fR
+
+Generates a rendering of a graph to a new
+or existing gifImage structure (see
+.B gdTcl(1)
+). Returns the
+.I gdHandle
+of the image.
+If the layout hasn't been already done, then it will be done as part
+of this operation using the same rules for selecting the layout engine
+as for the layout command.
+
+.TP
+\fIgraphHandle\fR \fBrender\fR \fI?canvas ?dot|neato|circo|twopi|fdp|nop??\fR
+
+If no \fIcanvas\fR argument is provided then \fBrender\fR
+returns a string of commands which, when evaluated, will render the
+graph to a
+.B Tk
+canvas whose
+.I canvasHandle
+is available in variable
+.B $c
+
+If a \fIcanvas\fR argument is provided then \fBrender\fR
+produces a set of commands for \fIcanvas\fR instead of $c.
+
+If the layout hasn't been already done, then it will be done as part
+of this operation using the same rules for selecting the layout engine
+as for the layout command.
+.nf
+
+ #!/usr/local/bin/wish
+ package require Tcldot
+ set c [canvas .c]
+ pack $c
+ set g [dotnew digraph rankdir LR]
+ $g setnodeattribute style filled color white
+ [$g addnode Hello] addedge [$g addnode World!]
+ $g layout
+ if {[info exists debug]} {
+ puts [$g render] ;# see what render produces
+ }
+ eval [$g render]
+
+.fi
+
+.B Render
+generates a series of canvas commands for each graph element, for example
+a node typically consist of two items on the canvas, one for the shape
+and the other for the label. The canvas items are automatically
+.I tagged
+(See
+.B canvas(n)
+) by the commands generated by render. The tags take one of two forms:
+text items are tagged with 0<handle> and
+shapes and lines are rendered with 1<handle>.
+
+The tagging can be used to recognize when a user wants to interact with
+a graph element using the mouse. See the script in
+.I examples/disp
+of the tcldot distribution for a demonstration of this facility.
+
+.SH BUGS
+
+Still batch-oriented. It would be nice if the layout was maintained incrementally.
+(The intent is to address this limitation in graphviz_2_0.)
+
+.SH AUTHOR
+
+John Ellson (ellson@graphviz.org)
+
+.SH ACKNOWLEDGEMENTS
+
+John Ousterhout, of course, for
+.B tcl
+and
+.B tk.
+Steven North and Eleftherios Koutsofios for
+.B dot.
+Karl Lehenbauer and Mark Diekhans of NeoSoft
+for the handles.c code which was derived from tclXhandles.c.
+Tom Boutell of the Quest Center at Cold Spring Harbor Labs for the gif drawing routines.
+Spencer Thomas of the University of Michigan for gdTcl.c.
+Dayatra Shands for coding much of the initial implementation of
+.B tcldot.
+
+.SH KEYWORDS
+
+graph, tcl, tk, dot, neato.
projects / graphviz / commitdiff