From: erg <devnull@localhost>
Date: Thu, 15 Jul 2010 16:06:45 +0000 (+0000)
Subject: Add smyrna manual to cvs
X-Git-Tag: LAST_LIBGRAPH~32^2~1275
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=8334cfea8886b204db11e516b9d97d353e3902ab;p=graphviz

Add smyrna manual to cvs
---

diff --git a/doc/Makefile.am b/doc/Makefile.am
index bf6392933..277c551bb 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -4,7 +4,7 @@
 # SUBDIRS = dot neato lefty dotty info
 SUBDIRS = info schema
 
-pdf = dotguide.pdf dottyguide.pdf leftyguide.pdf neatoguide.pdf libguide/libguide.pdf
+pdf = dotguide.pdf dottyguide.pdf leftyguide.pdf neatoguide.pdf libguide/libguide.pdf smyrna/smyrna.pdf
 html = build.html FAQ.html index.html winbuild.html pspdf.png char.html Gdtclft2.2.5.example.png todo.html
 txt = Dot.ref latex_suggestions.txt fontfaq.txt addingLayout.txt
 
diff --git a/doc/dotguide/graphdraw.bib b/doc/dotguide/graphdraw.bib
index 39a77d536..d2b40109d 100644
--- a/doc/dotguide/graphdraw.bib
+++ b/doc/dotguide/graphdraw.bib
@@ -237,7 +237,7 @@
 	publisher = "World Scientific"}
 
 @techreport {kn:dotguide,
-	author = "Eleftherios Koutsofios and Stephen C. North",
+	author = "Emden R. Gansner and Eleftherios Koutsofios and Stephen C. North",
 	title = "{Drawing graphs with dot}",
 	institution="AT\&T Bell Laboratories",
 	address="Murray Hill, NJ",
@@ -371,4 +371,12 @@
 	publisher="Addison-Wesley",
 	isbn="0-201-54275-7"
 	}
+@article{topfish,
+  author =   {E. R. Gansner and Y. Koren and S. North},
+  title =    {Topological fisheye views for visualizing large graphs},
+  journal =      {IEEE Transactions on Visualization and Computer Graphics},
+  year =     {2005},
+  volume =   {11},
+  pages =    {457-468}
+}
 
diff --git a/doc/smyrna/Makefile b/doc/smyrna/Makefile
new file mode 100644
index 000000000..4253b6318
--- /dev/null
+++ b/doc/smyrna/Makefile
@@ -0,0 +1,38 @@
+GRAPHFILES =  \
+  figures/2D.png \
+  figures/3D.png \
+  figures/attr1.png \
+  figures/attr2.png \
+  figures/attr3.png \
+  figures/attr4.png \
+  figures/center.png \
+  figures/details.png \
+  figures/fisheye.png \
+  figures/general.png \
+  figures/graph.png \
+  figures/gvpr.png \
+  figures/labels.png \
+  figures/magnifier.png \
+  figures/no_fisheye.png \
+  figures/nodelist.png \
+  figures/pan.png \
+  figures/smyrna.png \
+  figures/topfish.png \
+  figures/zoomin.png \
+  figures/zoomout.png
+
+TEXFILES = smyrna.tex attributes.tex controls.tex gui.tex \
+  intro.tex using.tex
+
+smyrna.pdf : smyrna.tex smyrna.bbl $(GRAPHFILES)
+	pdflatex smyrna.tex
+	@if grep "Label(s) may have changed" smyrna.log; then pdflatex smyrna.tex; fi
+
+smyrna.bbl : smyrna.tex ../dotguide/graphdraw.bib smyrna.aux
+	bibtex smyrna
+
+smyrna.aux : smyrna.tex $(GRAPHFILES)
+	pdflatex smyrna
+
+clean: 
+	rm -rf *.pdf *.log *.aux *.bbl *.blg *.log *.toc
diff --git a/doc/smyrna/attributes.tex b/doc/smyrna/attributes.tex
new file mode 100644
index 000000000..1c356636b
--- /dev/null
+++ b/doc/smyrna/attributes.tex
@@ -0,0 +1,129 @@
+\section{\smyrna\ Attributes}
+\label{sec:attribs}
+
+This section describes the various attributes used to control
+how \smyrna\ works. Unless otherwise noted, 
+all attributes belong to the root graph.
+
+ The following table lists the principal
+attributes used by \smyrna.\\
+\begin{center}
+{\footnotesize
+\begin{tabular}[t]{|l|p{2.5in}|l|} \hline
+{\bf Name} & {\bf Description} & {\bf Default} \\ \hline
+bgcolor & Background color & white (\#ffffff) \\
+bordercolor & Border color & \#38eb29 \\
+bordervisible & Draw graph border (boolean) & 1 \\ 
+gridcolor & Grid color & \#6033d8 \\ 
+gridsize & Grid size & 30 \\ 
+gridvisible & Draw grid (boolean) & 0 \\
+defaultlinewidth & Default line width  & 1 \\ 
+selectednodecolor & Color of selected nodes & \#8ce61d \\ 
+selectededgecolor & Color of selected edges & \#ffc0cb \\
+usermode & Advanced mode (boolean) & 1 \\
+drawnodes & Draw nodes (boolean) & 1 \\
+drawedges & Draw edges (boolean) & 1 \\
+drawlabels & Show node labels (boolean) & 1 \\
+defaultnodealpha & Overall alpha scale for all nodes. This 
+value is multiplied by a node's alpha value. & 0.8 \\
+defaultedgealpha & Overall alpha scale for all edges & 0.5 \\
+defaultnodeshape & OpenGL dots (0); spheres (1); custom (2) & 0 \\ 
+labelglutfont & Glut font id to use to render labels & 0 \\
+nodelabelcolor & node label color & \#8ce61d \\
+edgelabelcolor & edge label color & \#8ce61d \\
+nodelabelattribute & Node attribute used as node label & name \\
+edgelabelattribute & Edge attribute used as edge label & name \\
+labelwithdegree & Labels of high-degree nodes with 
+rendered before the ones with lower degree (boolean) & 0 \\
+labelnumberofnodes & Maximum number of node labels to be 
+rendered & 45 \\
+shownodelabels & Show node labels (boolean) & 1 \\
+showedgelabels & Show edge labels (boolean) & 1 \\
+colortheme & Color theme id for edges with no 
+color attribute. If unset, color is based on edge length; if
+set, edgecolorattribute is used & 1 \\
+defaultnodecolor & Default node color & blue \\
+defaultedgecolor & Color of edges with no color attribute. Active only when 
+colortheme attribute is set to "-1" & purple \\
+edgecolorattribute & Set this attribute when you need a 
+different value other than edge length to calculate color themes for edges & \\
+nodesize & Overall node size scale & 50 \\ 
+nodesselectable & Enable visual selection tools for nodes & 1 \\
+edgesselectable & Enable visual selection tools for edges & 1 \\ \hline
+\end{tabular}
+}
+\end{center}
+Most of these attributes are self-explanatory. 
+
+\subsection{usermode}
+What does this attribute do?
+
+\subsection{fonts}
+Explain font ids
+
+\subsection{colors}
+Explain color theme ids, default node and edge colors
+and edgecolorattribute
+
+\subsection{labels}
+name as pseudo-attribute \\
+labelwithdegree labelnumberofnodes
+
+\subsection{alpha values}
+Explain defaultedgealpha defaultnodealpha
+
+\subsection{Node shapes}
+The node shape attribute determines the look, flexibility and performance associated
+with how nodes are displayed. If {\tt defaultnodeshape} is set to 0, \smyrna\ uses
+OpenGL dots. This gives the best performance, but does not allow variations in size.
+A value of 1 causes \smyrna\ to use spherical node shapes. For large graphs, this will
+cause some slowdown when panning and zooming. On the other hand, one can set the
+size of each node individually via a node's {\tt size} attribute.
+Finally, if 2 is used, \smyrna\ will draw nothing.
+
+\newpage
+This table lists the attributes used by \smyrna
+in the topological fisheye mode.\\
+{\footnotesize
+\begin{tabular}[t]{|l|p{3.0in}|l|} \hline
+{\bf Name} & {\bf Description} & {\bf Default} \\ \hline
+topologicalfisheyefinenodes & Number of the fine nodes in topological fisheye view & 50 \\ 
+topologicalfisheyecoarseningfactor & Coarsening factor of topological fisheye & 2.5 \\ 
+topologicalfisheyedistortionfactor & Distortion Factor & 1 \\
+topologicalfisheyeanimate & Animate transitions (boolean) & 1 \\
+topologicalfisheyelabelfinenodes & Show fine node labels & 1 \\
+topologicalfisheyecolornodes & Color nodes (boolean) & 1 \\ 
+topologicalfisheyelabelfocus & Show focus node labels (boolean) & 1 \\
+topologicalfisheyefinestcolor & Color of fine nodes & red \\ 
+topologicalfisheyecoarsestcolor & Color of coarse nodes & green \\ \hline
+\end{tabular}
+}
+
+The following attributes affect the magnifying glass widget.\\
+{\footnotesize
+\begin{tabular}[t]{|l|p{3.0in}|l|} \hline
+{\bf Name} & {\bf Description} & {\bf Default} \\ \hline
+defaultfisheyemagnifierradius & Radius of magnifier glass & 350 \\ 
+defaultfisheyemagnifierdistort & Distortion value of magnifying glass & 5 \\ \hline
+\end{tabular}
+}
+
+The larger the distortion, the larger the magnification factor.
+
+\subsection{Node and Edge Attributes}
+At present, it is assumed that the input graph has been laid out. In particular,
+each node should have a {\tt pos} attribute specifying 2 or 3 real numbers giving the
+x and y and, if applicable, z coordinates of the node. {\bf edge pos}
+If an edge does not possess a {\tt pos} attribute, the edge will be drawn as a line segment
+connect its end vertices.
+
+If a node or edge has a {\tt color} attribute, that will be used as its color.
+Similarly, a node may have a {\tt color} attribute, which will affect the node's size if
+{\tt defaultnodeshape == 1}.
+
+\smyrna\ also checks for a {\tt \_draw\_} attribute
+for nodes, edges and graphs. This is assumed to be a valid xdot string describing how to 
+render the object. If the graph has a {\tt \_draw\_} attribute, this will be drawn first to serve
+as a background for the node and edges of the graph.
+
+
diff --git a/doc/smyrna/controls.tex b/doc/smyrna/controls.tex
new file mode 100644
index 000000000..92e545529
--- /dev/null
+++ b/doc/smyrna/controls.tex
@@ -0,0 +1,410 @@
+\section{\smyrna\ Controls}
+\label{sec:controls}
+
+In this section, we describe the various controls making up 
+the \smyrna\ interface. Figure~\ref{fig:main} shows an example of
+the main \smyrna\ display.
+
+\begin{figure}[ht] 
+\begin{center}
+\includegraphics[scale=.3]{figures/smyrna.png}
+\caption{\small Typical \smyrna\ view.}
+\label{fig:main} 
+\end{center}
+\end{figure}
+
+
+Across the top of the main window, there is a fairly standard menu bar. 
+The {\tt File} pull-down menus offers the choices {\bf Open}, {\bf Save},
+{\bf Save As} and {\bf Quit}. These should be self-explanatory.
+The {\tt View} menu allows you to make the console window a subwindow of the
+main \smyrna\ window. 
+\begin{comment}
+ As open and hide are mutually exclusive, this menu should
+be made dynamic, or the control should be done as a toggle.
+\end{comment}
+The {\tt Help} menu provides access to information about using \smyrna\ {\bf but at
+present does nothing}.
+The {\tt Select} menu provides shortcuts for selecting and unselecting large parts
+of the the graph, such as all nodes.
+
+The {\tt Edit} menu consists of the three items: {\bf Smyrna Settings}, {\bf Attributes},
+and {\bf Node List}. The first activates the \smyrna\ Settings Widget described in
+Section~\ref{sec:settings}. The second is identical, except it guarantees that that
+widget is on the Attributes tab (Section~\ref{sec:attr}). 
+The last instantiates the Node List widget, which is
+considered in Section~\ref{sec:nodelist}.
+
+On the right of the menu bar are controls for handling the loaded graphs.
+The currently active graph is shown. The names of all available graphs are provided in the
+associated pull-down menu. To switch between graphs, the user can pick another graph from
+the menu, then click on the {\tt Activate} button. Alternatively, clicking on the {\tt Remove}
+button closes the graph. {\bf This doesn't appear to work.}
+
+The top buttons along the left of the main window serve as simple controls for
+certain common actions. 
+\begin{description}
+\item[\includegraphics{figures/center.png}]
+The top button is used to re-center the display. 
+\item[\includegraphics{figures/zoomin.png} \includegraphics{figures/zoomout.png}]
+The next two buttons allow you to zoom in and
+out. 
+\item[\includegraphics{figures/details.png}]
+The fourth top button is yet another shortcut for opening the 
+Attributes tab (Section~\ref{sec:attr}) in the Setting widget.
+\end{description}
+
+The bottom buttons are used to toggle between states in \smyrna.
+\begin{description}
+\item[E  N]
+The top two, E and N, determine whether edges and nodes are selected when doing
+an area selection. Programmatic selection or single selection by mouse still works even
+if these are unset.
+\item[\includegraphics{figures/2D.png} \includegraphics{figures/3D.png}]
+The buttons toggle between 2D and 3D display modes. 
+If the {\tt pos} attributes of the nodes has only two coordinates, the
+z value is taken to be 0, and the graph appears in the XY plane.
+\item[\includegraphics{figures/fisheye.png} \includegraphics{figures/no_fisheye.png}]
+The fish buttons toggle between the normal and topological fisheye views (Section~\ref{sec:topfish}).
+\item[\includegraphics{figures/pan.png}]
+The last button unselects all selected objects. 
+\begin{comment}
+This makes me feel this button should be at the top.
+\end{comment}
+\end{description}
+
+\subsection{\smyrna\ Settings Widget}
+\label{sec:settings}
+This is the main control panel for controlling the display parameters in
+\smyrna. It also provides two tabs for interacting with the graph: a high-level
+interface for dealing with graph attributes, and a general-purpose interface
+for applying \gvpr\ on the graph. We discuss each tab individually in
+the following subsections.
+
+Note that is necessary to click on the {\tt Apply} button to cause the changes to
+take effect. 
+\begin{comment}
+Why not make each change immediate?
+\end{comment}
+
+\subsubsection{General Settings}
+\label{sec:general}
+The General Settings tab is shown in Figure~\ref{fig:general}.
+It provides control control over the default color schemes, and whether
+or not nodes and edges are drawn or can be selected.
+Clicking on one of the colors brings up a color selection widget that allows
+you to modify the color.
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.5]{figures/general.png}
+\caption{\small The General Settings tab.}
+\label{fig:general}
+\end{center}
+\end{figure}
+\begin{description}
+\item[Background Color] 
+Specifies the background color of the window.
+\item[Border Color] 
+Specifies the border color.
+If enabled, \smyrna\ draws a rectangle about the graph to indicate its limits.
+This attribute specifies what color is used.
+\item[Grid Color] specifies the color of grid points.
+If enabled, \smyrna\ draws an array of grid points behind the graph.
+\item[Default Node Color] gives the color used to draw nodes, unless specified explicitly
+in the input graph.
+\item[Default Edge Color] gives the color used to draw edges, unless specified explicitly
+in the input graph or a color theme is selected.
+\item[Selected Node Color] specifies the color used for selected nodes.
+\item[Selected Edge Color] specifies the color used for selected edges.
+\end{description}
+
+This tab also provides check boxes to enable or disable various properties.
+These can be used to turn off the drawing of nodes, edges, the border or the grid.
+In addition, the ability to select nodes or edges using the GUI can be disabled.
+
+\smyrna\ provides a collection of color themes which can be selected using the {\tt Color Theme}
+menu. This specifies a color theme used to color edges with no color attribute. Edge color
+calculations are based on an edge's {\em len} attribute. A different edge attribute can
+be specified using the {\tt Edge Attr. for Color} text box. 
+\begin{comment}
+This doesn't appear to be
+implemented yet? Also, how does one turn of the color themes, so that the default edge color
+is used?
+\end{comment}
+
+The {\tt Show Edges} menu can be used to determine when edges are drawn. Normally, an edge
+is drawn if any part of it appears within the view windows. Sometimes, for clarity or efficiency,
+it is better to only draw those edges with at least one node with the view.
+
+\subsubsection{Labels}
+\label{subsubsec:labels}
+The Labels tab is shown in Figure~\ref{fig:labels}.
+This tab provides control over labels used in \smyrna.
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.5]{figures/labels.png}
+\caption{\small The Labels tab.}
+\label{fig:labels}
+\end{center}
+\end{figure}
+The {\tt Font} menu can be used to set the face and standard size of the OpenGL font used to
+display text labels.
+The {\tt Default Node Label Color} and {\tt Default Edge Label Color} items can be used to
+specify which colors are used for node and edge labels, respectively.
+
+The user can tailor what attribute is used as the label for nodes and edges. This is done via
+the {\tt Node Label Attribute} and {\tt Edge Label Attribute} text boxes. For example,
+a graph representing Internet communication may benefit from using a node attribute such
+as {\it IPaddress} or {\it hostname}. Note that,
+by default, the label comes from the pseudo-attribute {\it name}. For nodes, this is the
+name of the node; for edges, the name is constructed from the names of its head and tail nodes.
+\begin{comment}
+I wonder if label may be a better and more
+appropriate default attribute to use, since if the graph has been processed, the label will be
+node name. Also, when are labels shown? 
+\end{comment}
+
+Labels are shown when an object is selected. In addition, if the Show Node Labels box is checked,
+labels are displayed for all nodes whenever one zooms in close enough. Close enough is determined
+by the Labeling Level widget. The smaller the number, the sooner labels appear as you zoom in.
+ 
+\subsubsection{Graph}
+The Graph tab is shown in Figure~\ref{fig:graph}.
+With this tab, the user can affect more technical aspects of the graph view.
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.5]{figures/graph.png}
+\caption{\small The Graph tab.}
+\label{fig:graph}
+\end{center}
+\end{figure}
+The {\tt Node Shape} menu allows the user to specify how nodes are drawn.
+\begin{description}
+\item[OpenGL dots] Nodes are drawn as filled circles as efficiently as possible. All nodes
+will have the same size.
+\item[Spherical] Nodes are drawn using OpenGL spheres. The advantage over OpenGL dots is that
+each node can have its own size specified by the size attribute. The disadvantage is that it is not
+as efficient.
+\item[Custom] At present, the choice is not implemented.
+\end{description}
+
+This tab provides three sliders. The {\tt Node Alpha} and {\tt Edge Alpha} 
+sliders control the transparency of nodes and edges. Set to 1.0, the object is opaque;
+set to 0, the object is invisible. A typical use would be to set the edge alpha to a small
+value rather than to turn off edge drawing entirely. The edges would still be visible, but
+would obscure the drawing as much. 
+These values are multiplied with any alpha valued supplied with an edge's or node's color.
+The {\tt Node Size} slider can be used to uniformly
+scale the node size. Note that the node sliders have no effect for custom nodes.
+
+The {\tt Advanced Mode} and {\tt Anti-aliasing} check boxes toggle the advanced user mode 
+\begin{comment}
+ What does this mean?
+\end{comment}
+and the use of anti-aliasing.
+
+
+\subsubsection{Magnifier Settings}
+The Magnifiers tab is shown in Figure~\ref{fig:magnifier}.
+This controls the magnifying glass parameters.
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.5]{figures/magnifier.png}
+\caption{\small The Magnifiers tab.}
+\label{fig:magnifier}
+\end{center}
+\end{figure}
+The radius of the fisheye magnifier is specified using the {\tt Radius} field.
+The {\tt Distortion} field allows you control the distortion in the lens. Larger distortion
+causes greater magnification.
+\begin{comment}
+What do the width, height and Zoom X fields do, and why are their boxes so different in size?
+\end{comment}
+
+
+\subsubsection{Topfish Settings}
+The Topfish tab is shown in Figure~\ref{fig:topfish}.
+This allows you to specify the parameters associated with a topological fisheye view of the
+graph as discussed in Section~\ref{sec:topfish}.
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.5]{figures/topfish.png}
+\caption{\small The Topfish tab.}
+\label{fig:topfish}
+\end{center}
+\end{figure}
+The {\tt \# Of Fine Nodes} field allows the user to set the number of the fine nodes 
+The {Fine Node Label Attribute} indicates what node attribute is used to label fine nodes.
+The {\tt Coarsening factor} and {\tt Distortion Factor} fields control some technical
+parameters of the view; refer to the paper for more details.
+
+There are six check boxes.
+\begin{description}
+\item[Dist 2 Limit] Distance to limit value of the algorithm  {\bf What does this mean?}
+\item[Animate] Toggles whether animation is used to handle the transition from an old focus to
+a new focus. Although more expensive, animation helps to preserve the mental map of the graph.
+\item[Label Fine Nodes] Indicates whether fine nodes are labeled.
+\item[Color nodes]  {\bf What does this do?}
+\item[Label Coarse Nodes] {\bf What does this do?}
+\item[Label Focus] Indicates whether the focus node is labeled. The focus node label is
+displayed prominently whether or not the labeling of fine nodes is enabled.
+\end{description}
+
+The two {\tt Color extremes} widgets allow you to set the colors used for the finest
+and coarsest nodes. Colors of intermediate nodes are interpolated between these two colors.
+
+\subsubsection{Applying \gvpr}
+\label{sec:gvprtab}
+The Script tab is shown in Figure~\ref{fig:gvpr}.
+This is the main control for using \gvpr\ scripts to manipulate the active graph
+as discussed in Section~\ref{sec:gvpr}.
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.5]{figures/gvpr.png}
+\caption{\small The \gvpr\ tab.}
+\label{fig:gvpr}
+\end{center}
+\end{figure}
+The top text window can be used to enter and edit a \gvpr\ script. By then clicking on 
+the {\tt Run gvpr} button, the script is run on the active graph. As usual, to update
+smyrna's data structures, you will need to click the {\tt Apply} (or {\tt OK}) button,
+and then click on the main \smyrna\ window to cause the the display to be refreshed. 
+\begin{comment}
+Can this be avoided?
+\end{comment}
+
+By default, any changes are done directly to the active graph. Often, this is appropriate.
+During exploratory data analysis, though, the user may wish to keep the original graph unaltered
+in order to return to it later. Rather than trying to undo any changes made, it is simpler to
+mark the {\tt Clone Current Graph} checkbox. In this case, a clone of the original graph is made.
+Then, the \gvpr\ is applied to the cloned graph, which then becomes the new active graph. The
+original graph can be retrieved using the {\tt Active Graph} menu at the top of the main
+\smyrna\ window. The obvious drawbacks to this mode are that there is the extra time needed to
+clone the graph, and the extra memory use for each copy.
+
+A \gvpr\ script accepts arguments, which are available via the {\tt ARGV[]} array. Normally, these
+would be provided on the command line. Here, the user can use the middle {\tt Arguments} text
+window to supply these.
+
+In addition to manipulating a graph, a \gvpr\ script can also perform I/O to a {\tt stdout} stream. 
+This output appears
+in the console window, which is labeled {\tt Output}. The console window opened as part of the
+main \smyrna\ window using the {\tt View} menu is another view of the same stream.  
+
+Finally, the {\tt Load} and {\tt Save} buttons support the re-use of \gvpr\ scripts.
+Specifically, the {\tt Load} button can be used to read in a file, whose contents are stored 
+in the \gvpr\ script text window, overwriting any previously stored script. Conversely, the
+{\tt Save} button can be used to write the contents of the script text window into a file
+for later use.
+
+\subsubsection{Setting Attributes}
+\label{sec:attr}
+Manipulating attributes is a common task when using \smyrna. Any such operations can be done
+using \gvpr. However, it seems reasonable to support this activity with a simpler interface.
+The purpose of the Attribute tab is to provide this interface, though it should be noted that
+the actual work is done using \gvpr.
+
+Figure~\ref{fig:attr1} shows the initial state when the Attributes tab is opened.
+Note that the caption indicates that some collection of nodes and edges has been selected.
+	\begin{figure}[ht]
+	\begin{center}
+	\includegraphics[scale=.5]{figures/attr1.png}
+\caption{\small The Attribute tab.}
+\label{fig:attr1}
+\end{center}
+\end{figure}
+To start, use the radio buttons to specify what type of 
+graph object you wish to work with. Then type in the attribute's name in the
+{\tt Attribute Name} field. As you type, the tab interface changes dynamically in
+response to your typing,
+giving feedback concerning what it knows about available attributes. If what you have
+typed is the prefix of a known attribute, all attributes with that prefix will appear
+in a list below. In Figure~\ref{fig:attr2}, the character 's' causes the various
+known node attributes starting with 's' to be shown.
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.5]{figures/attr2.png}
+\caption{\small Typing in the Attribute tab.}
+\label{fig:attr2}
+\end{center}
+\end{figure}
+
+\begin{description}
+\item[Searching and modifying attributes]
+If the current text fully matches a known attribute,
+the background color of the {\tt Attribute Name} field will appear in green. 
+In the example shown in Figure~\ref{fig:attr3}, the shape attribute has been
+recognized and the default value is shown. 
+In addition, you will see two additional buttons: {\tt Apply} and {\tt Search}.
+
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.5]{figures/attr3.png}
+\caption{\small A recognized attribute.}
+\label{fig:attr3}
+\end{center}
+\end{figure}
+
+The {\tt Apply} button is used to replace the attribute values of selected objects of the 
+specified object type. In our example, we have chosen the {\tt shape} attribute, 
+and have specified a value of {\tt box} in Value field. If we then click the {\tt Apply},
+\smyrna\ will set the shape value of all selected nodes to the given value.
+
+The {\tt Search} button is used to select objects of the specified object type based on
+attribute values specified by regular expressions.
+For example, suppose that you have a network graph with IP addresses 
+attached to each node. You can type {\tt IP} in the attribute name box, {\tt 10.*} in the
+value box, and click on the {\tt Search} button. 
+This will select all nodes whose IP address begins with {\tt 10.}. Regular expression
+matching is, obviously, based on the regular expressions supported in \gvpr.
+
+\item[Adding new attributes]
+If, as you type, the attribute name is not currently set in the graph for the specified object type,
+the Attribute Name field will be red and
+a button with a plus sign ('+') will appear, as in Figure~\ref{fig:attr4}.
+You can then type in a value into the {\tt Default Value} field, click on the '+' button and
+the appropriate attribute will be created with the given default value, and all objects
+of the given type that value for the attribute.
+Here, we have specified a default
+value of "yes" in the Default Value field. If we now click on the '+' button on the right,
+\smyrna\ will create this new node attribute.
+
+\end{description}
+
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.5]{figures/attr4.png}
+\caption{\small An unknown attribute.}
+\label{fig:attr4}
+\end{center}
+\end{figure}
+
+\subsection{The Node List Widget}
+\label{sec:nodelist}
+It is often useful to be able to focus on certain nodes, and look at some of their associated attributes. 
+This can be done using \gvpr (\ref{sec:gvprtab}), but this type of query is important enough that \smyrna\
+provides the special-purpose Node List widget. This is opened by using the {\tt Edit} menu.
+Figure~\ref{fig:nodelist} shows a typical view of the widget. It lists all of the currently selected nodes.
+Selection could have been down by clicking on the nodes, sweeping out a region, or via \gvpr.
+\begin{figure}[ht]
+\begin{center}
+\includegraphics[scale=.35]{figures/nodelist.png}
+\caption{\small The Node List widget.}
+\label{fig:nodelist}
+\end{center}
+\end{figure}
+The list always gives the names of the selected nodes. You can specify additional attributes to be
+displayed by setting the graph's {\tt datacolumns} attribute, which is a comma-separated list of the
+desired attribute names. Thus, in the example shown, the graph has {\tt datacolumns="category,customer"}.
+To select new columns, just run \gvpr. For example, to switch the current two columns and add the
+{\tt tier} attribute, you would run the \gvpr\ script
+\begin{verbatim}
+BEG_G{datacolumns="customer,category,tier"}
+\end{verbatim}
+Note that, at present, you will need to close and then re-open the Node List widget to get the new columns.
+
+The widget provides four buttons that can sometimes be useful in this context. The subgraph may be
+interesting enough that you wish to view it off-line. By clicking the {\tt Save} button, you can save
+the nodes as a separate graph. The {\tt Save with Edges} button, the graph saved with the selected nodes
+and all edges in the original graph between two selected nodes. The {\tt Hide All} button will make all of 
+the selected nodes invisible; the {\tt Hide All} button makes them all visible.
diff --git a/doc/smyrna/figures/2D.png b/doc/smyrna/figures/2D.png
new file mode 100644
index 000000000..b47da0a75
Binary files /dev/null and b/doc/smyrna/figures/2D.png differ
diff --git a/doc/smyrna/figures/3D.png b/doc/smyrna/figures/3D.png
new file mode 100644
index 000000000..01413e893
Binary files /dev/null and b/doc/smyrna/figures/3D.png differ
diff --git a/doc/smyrna/figures/attr1.png b/doc/smyrna/figures/attr1.png
new file mode 100644
index 000000000..5bc914096
Binary files /dev/null and b/doc/smyrna/figures/attr1.png differ
diff --git a/doc/smyrna/figures/attr2.png b/doc/smyrna/figures/attr2.png
new file mode 100644
index 000000000..2e822a6e3
Binary files /dev/null and b/doc/smyrna/figures/attr2.png differ
diff --git a/doc/smyrna/figures/attr3.png b/doc/smyrna/figures/attr3.png
new file mode 100644
index 000000000..d5d6edbd3
Binary files /dev/null and b/doc/smyrna/figures/attr3.png differ
diff --git a/doc/smyrna/figures/attr4.png b/doc/smyrna/figures/attr4.png
new file mode 100644
index 000000000..6ac1dd67e
Binary files /dev/null and b/doc/smyrna/figures/attr4.png differ
diff --git a/doc/smyrna/figures/center.png b/doc/smyrna/figures/center.png
new file mode 100644
index 000000000..508101473
Binary files /dev/null and b/doc/smyrna/figures/center.png differ
diff --git a/doc/smyrna/figures/details.png b/doc/smyrna/figures/details.png
new file mode 100644
index 000000000..0a7b8af96
Binary files /dev/null and b/doc/smyrna/figures/details.png differ
diff --git a/doc/smyrna/figures/fisheye.png b/doc/smyrna/figures/fisheye.png
new file mode 100644
index 000000000..5031c9996
Binary files /dev/null and b/doc/smyrna/figures/fisheye.png differ
diff --git a/doc/smyrna/figures/general.png b/doc/smyrna/figures/general.png
new file mode 100644
index 000000000..c9e903742
Binary files /dev/null and b/doc/smyrna/figures/general.png differ
diff --git a/doc/smyrna/figures/graph.png b/doc/smyrna/figures/graph.png
new file mode 100644
index 000000000..ddb9faa7b
Binary files /dev/null and b/doc/smyrna/figures/graph.png differ
diff --git a/doc/smyrna/figures/gvpr.png b/doc/smyrna/figures/gvpr.png
new file mode 100644
index 000000000..67d8e6a9e
Binary files /dev/null and b/doc/smyrna/figures/gvpr.png differ
diff --git a/doc/smyrna/figures/labels.png b/doc/smyrna/figures/labels.png
new file mode 100644
index 000000000..065724538
Binary files /dev/null and b/doc/smyrna/figures/labels.png differ
diff --git a/doc/smyrna/figures/magnifier.png b/doc/smyrna/figures/magnifier.png
new file mode 100644
index 000000000..3dd5aee32
Binary files /dev/null and b/doc/smyrna/figures/magnifier.png differ
diff --git a/doc/smyrna/figures/no_fisheye.png b/doc/smyrna/figures/no_fisheye.png
new file mode 100644
index 000000000..82daa49b2
Binary files /dev/null and b/doc/smyrna/figures/no_fisheye.png differ
diff --git a/doc/smyrna/figures/nodelist.png b/doc/smyrna/figures/nodelist.png
new file mode 100644
index 000000000..9ee7b1987
Binary files /dev/null and b/doc/smyrna/figures/nodelist.png differ
diff --git a/doc/smyrna/figures/pan.png b/doc/smyrna/figures/pan.png
new file mode 100644
index 000000000..d0870c540
Binary files /dev/null and b/doc/smyrna/figures/pan.png differ
diff --git a/doc/smyrna/figures/smyrna.png b/doc/smyrna/figures/smyrna.png
new file mode 100644
index 000000000..eb9ea7aa8
Binary files /dev/null and b/doc/smyrna/figures/smyrna.png differ
diff --git a/doc/smyrna/figures/topfish.png b/doc/smyrna/figures/topfish.png
new file mode 100644
index 000000000..2fee4c0b3
Binary files /dev/null and b/doc/smyrna/figures/topfish.png differ
diff --git a/doc/smyrna/figures/zoomin.png b/doc/smyrna/figures/zoomin.png
new file mode 100644
index 000000000..847b1eba5
Binary files /dev/null and b/doc/smyrna/figures/zoomin.png differ
diff --git a/doc/smyrna/figures/zoomout.png b/doc/smyrna/figures/zoomout.png
new file mode 100644
index 000000000..643328e16
Binary files /dev/null and b/doc/smyrna/figures/zoomout.png differ
diff --git a/doc/smyrna/gui.tex b/doc/smyrna/gui.tex
new file mode 100644
index 000000000..47e00c0fd
--- /dev/null
+++ b/doc/smyrna/gui.tex
@@ -0,0 +1,8 @@
+\section{Modifying the \smyrna\ GUI}
+\label{sec:gui}
+
+Explain attrs.txt and attr\_widgets.dot
+and  mouse\_actions.txt
+
+Note template.dot
+
diff --git a/doc/smyrna/intro.tex b/doc/smyrna/intro.tex
new file mode 100644
index 000000000..48478b384
--- /dev/null
+++ b/doc/smyrna/intro.tex
@@ -0,0 +1,111 @@
+\section{Introduction}
+\label{sec:intro}
+
+\smyrna\ is an application for viewing graphs. It allows the user
+to open a window on a graph; navigate around the graph using pan
+and zoom; and select nodes and edges with the mouse. The GUI provides various simple
+mechanisms for changing the view of the graph and querying information about nodes and edges. 
+In addition, \smyrna\
+allows the user to perform sophisticated querying and
+manipulation of graphs.
+
+Although it works with graphs of any size, \smyrna\ was 
+designed to handle large graphs, on the order of 100,000 nodes
+and edges. It uses the OpenGL library which allows it to take advantage 
+of modern video cards' graphics rendering features. 
+
+\subsection{File Format} 
+\label{sec:files}
+Currently, \smyrna\ supports only the Graphviz \DOT\ language.
+Please refer to 
+\begin{center}
+\url{http://www.graphviz.org/Documentation.php} 
+\end{center}
+to get more information about the \DOT\ language of Graphviz and
+the related attributes.
+
+\smyrna\ assumes the input graph has position information
+for all nodes. This is supplied by the {\tt pos} attribute, whose
+format is two or three numbers separated by comma. Thus, for a
+node {\tt start}, one might have
+\begin{center}
+{\tt start [pos="23.5,288"]}
+\end{center}
+If a graph is laid out using one of the Graphviz graph drawing programs,
+the position information is attached in this manner. For example, running the
+command
+\begin{center}
+{\tt sfdp -o outgraph.gv ingraph.gv}
+\end{center}
+will lay out the graph described in {\tt ingraph.gv} and create the file
+{\tt outgraph.gv}, which can be used as input to \smyrna.
+
+All \smyrna\ settings are stored as graph attributes.
+For example, you can change the background color by setting the
+{\tt bgcolor} attribute of the graph. Or the size of a 
+node can be altered by changing its {\tt size} attribute. 
+These attributes can be modified through the \smyrna\ GUI, 
+using the built-in scripting (cf.~\ref{sec:gvpr}),
+or by simply changing the graph file itself. 
+
+Normally in \smyrna, nodes are represented by filled disks, which
+can vary in size and color. For smaller graphs, \smyrna\ 
+can render the more complex shapes and styles available in Graphviz.
+This requires the nodes and edges in the graph to have the necessary
+{\it xdot} attributes to describe the rendering. This can be achieved
+by running the Graphviz layout with the {\tt -Txdot} flag, e.g.
+\begin{center}
+{\tt sfdp -Txdot -o outgraph.gv ingraph.gv}
+\end{center}
+For more information about {\it xdot} attributes and their formats,
+see
+\begin{center}
+\url{http://www.graphviz.org/doc/info/output.html#d:xdot }
+\end{center}
+
+\subsection{Visualization Modes} 
+\label{sec:vizmodes}
+{\it Smyrna} has three display modes:
+2D, 3D and topological fisheye. 
+In 2D mode, the graph is displayed in the plane. Navigation is
+limited to panning and zooming. Any third coordinate in a
+node's {\tt pos} attribute is ignored.
+In 3D mode, the graph is displayed using 3D graphics, allowing the
+user to rotate about the graph in addition to panning and zooming.
+Any node whose {\tt pos} attribute does not have a third coordinate
+will be placed in the xy plane.
+
+The topological fisheye mode~\cite{topfish} presents a 
+distorted, fisheye view of the
+graph, in which the areas of the graph near to one or more focus nodes
+are shown accurately, while the areas of the graph away from the foci
+become more ``compressed'' the further they are from the foci.
+For large graphs, this allows the user to see areas of interest clearly
+and in detail, while eliding detail away from the foci.
+Unlike ordinary fisheye techniques, in which
+the distortion is done geometrically, with remote nodes being
+drawn on top of each other, 
+topological fisheye is a specialized type of semantic zoom in which
+remote nodes are combined into meta-nodes with induced edges, thereby
+maintaining the graph's topology in a coarsened form.
+
+\subsection{Querying, Filtering and Modifying Graphs}   
+Beyond the simple viewing and navigating around a graph, \smyrna\
+also provides machinery for querying properties of the graph, modifying
+the graph and creating new graphs. The main engine for this is \gvpr,
+a scripting language specifically designed to edit graphs. By using 
+\gvpr, you can do almost anything related to graphs, from counting 
+the number of nodes with an attribute matching a given regular expression to
+fairly complex graph algorithms.
+
+One can use \gvpr\ to read and write files. In particular, \gvpr\ scripts
+can write to {\tt stdout}. This is implemented in \smyrna\ but a console
+window, which is part of the \gvpr\ control tab (Section~\ref{sec:gvprtab}).
+
+When \gvpr\ changes the structure or attributes of the active graph,
+these changes are reflected in \smyrna. Conversely, nodes and edges
+that are selected have an attribute {\tt selected=1}, which \gvpr\
+can use to provide actions on selected nodes and edges.
+
+The use of \gvpr\ is discussed in more detail in Section~\ref{sec:gvpr}.
+
diff --git a/doc/smyrna/smyrna.pdf b/doc/smyrna/smyrna.pdf
new file mode 100644
index 000000000..f56d99327
Binary files /dev/null and b/doc/smyrna/smyrna.pdf differ
diff --git a/doc/smyrna/smyrna.tex b/doc/smyrna/smyrna.tex
new file mode 100644
index 000000000..c3c62530e
--- /dev/null
+++ b/doc/smyrna/smyrna.tex
@@ -0,0 +1,38 @@
+\documentclass[11pt]{article}
+\usepackage{graphicx}
+\usepackage{times}
+\usepackage{verbatim}
+\usepackage{url}
+\pagestyle{myheadings}
+\addtolength{\topmargin}{-0.75in}
+
+\author{Arif Bilgin and Emden R. Gansner}
+
+\def\smyrna{{\it smyrna}}
+\def\gvpr{{\it gvpr}}
+\def\DOT{{\it DOT}}
+\renewcommand{\date}{\today}
+\newcommand{\mymark}{{\it smyrna} User's Manual, \date \hfil }
+\markboth{\mymark}{\mymark}
+
+\begin{document}
+\bibliographystyle{alpha}
+\title{Viewing graphs with \smyrna}
+\maketitle
+\newpage
+\tableofcontents
+
+\newpage
+\input{intro}
+\input{using}
+\input{controls}
+\input{attributes}
+
+\appendix
+\clearpage
+\input{gui} 
+
+\bibliography{../dotguide/graphdraw}
+
+\end{document}
+
diff --git a/doc/smyrna/using.tex b/doc/smyrna/using.tex
new file mode 100644
index 000000000..5a79ef70a
--- /dev/null
+++ b/doc/smyrna/using.tex
@@ -0,0 +1,153 @@
+\section{Using \smyrna} \label{sec:using}
+
+One starts \smyrna\ as with any program, either using a command interpreter to
+execute it or double-clicking on its icon. From the command line, 
+it accepts a single argument giving the
+file name of a graph to be viewed.
+
+This will open a main window for \smyrna\ similar to 
+that shown in Figure~\ref{fig:main0}.
+\begin{figure}[ht] 
+\begin{center}
+\includegraphics[scale=.3]{figures/smyrna.png}
+\caption{\small Typical \smyrna\ view.}
+\label{fig:main0} 
+\end{center}
+\end{figure}
+The window has a fairly typical layout. There is a menu bar across the top,
+with some additional widgets on the right side of it. There is a control bar
+of buttons down the left side. The remainder of the window is the display area.
+
+\subsection{Opening a graph}
+If no file name is given on the command line, one can use 
+{\tt File->Open} to open a graph file. This can also be used
+read in additional graphs. When a new graph is read in, it is made
+the {\it active} graph, and the previous graph is added to the
+list of open graphs. One can make an open graph the new active
+graph by using the {\tt Active Graph} menu at the top right
+of the main window, picking the desired
+graph, and then clicking on the {\tt Activate} button.
+
+Being able to switch back and forth between open graphs can be
+useful when analyzing graphs. However, due to resource consumption,
+one should avoid having too many open graphs. You can close a
+graph the same way that you activate it, except clicking on the
+{\tt Remove} button rather than {\tt Activate}. 
+
+\subsection{Navigation}
+To zoom in and out on a graph, you use the scroll wheel or ball
+on the mouse. Or you can use the plus and minus magnifying glasses
+\includegraphics{figures/zoomin.png} \includegraphics{figures/zoomout.png}
+on the left-hand icon bar.
+
+To pan, click and hold down the left mouse button, and move the
+mouse. Releasing the mouse stops the panning.
+
+Sometimes during navigation, you may find yourself in some obscure corner
+of the graph, or you've lost the graph entirely. By clicking on the top
+button
+\includegraphics{figures/center.png}
+on the left icon bar, the view is reset so that the graph is 
+centered in the window, and just large enough
+to fill it. 
+
+\subsection{Selection}
+{\it Smyrna} has a notion of selected nodes and edges. 
+To pick a single node or edge, right click on it. The color will
+change to indicate the selection; in addition, an
+attribute of the object may be displayed. You can use the Labels
+tab (Section~\ref{subsubsec:labels}) to specify which attribute you wish to see.
+If right clicked a second time, the object is unselected.
+Multiple objects can be selected.
+
+One can also select multiple items by holding down the right mouse
+button and sweeping out a region. One can do this multiple times;
+the selected set is the union of all selections.
+What is selected is determined by the E and N buttons on the control bar, which
+activate the selection of edges and nodes respectively. Initially, only nodes
+can be selected.
+\begin{comment}
+\bf Can one unselect multiple nodes, but not all?
+\end{comment}
+
+The button
+\includegraphics{figures/pan.png}
+at the bottom of the control bar can be used to unselect everything.
+\begin{comment}
+Do we still want cluster selection? What does that do?
+Should one be able to unselect by sweeping?
+\end{comment}
+
+Choosing {\tt Edit->Node List} opens the Node List widget (Section~\ref{sec:nodelist}),
+which provides a text view of the selected nodes. It also provides the opportunity
+to save the selected nodes as a subgraph.
+
+\subsection{3D in \smyrna}
+\label{sec:3D}
+To move from a 2D to a 3D view, click the button \includegraphics{figures/3D.png}
+found in the control bar. Pan and zoom are achieved the same way they are in 2D.
+For rotation in 3D, hold down the left shift key, then click and hold 
+down the left mouse button, and move the mouse.
+Returning back to 2D is done by clicking the control bar button
+\includegraphics{figures/2D.png}.
+
+\subsection{Graphical Node and Edge Attributes}
+To display more information about the graph, especially attributes
+that may be associated with nodes or edges, one can use various
+display attributes. The principal such attribute is color, stored
+as the {\tt color} attribute in a node or edge. The attribute can
+be set already when the graph is read in, or it can be attached
+using the Attribute tab or the Script tab of Settings widget.
+If the color is not explicitly set, \smyrna\ provides default values
+which can be set using the General tab of the Settings widget.
+
+For cluttered drawings, it can sometimes help to play down parts of the graph.
+\smyrna\ allows you turn off the drawing of either nodes are edges. There 
+are check boxes for this also on the General tab.
+You can also reach a middle ground by having the edges or nodes drawn, but making
+them more transparent. To do this, one uses the Node Alpha and Edge Alpha sliders
+on the Graph tab.
+
+The Graph tab also provides a Node Size slider. With this, you can uniformly
+increase or decrease the size of the nodes. If Node Shape is set to Spherical,
+you can set the size attribute of nodes to get a variation in node sizes. 
+The attribute is used as a scale factor, so a size less than 1 will cause a node
+to shrink relative to other nodes while a size greater than 1 will enlarge the node.
+
+For large graphs, lack of screen space means you usually want to see nodes drawn as small disks.
+This holds if Node Shape is set to either OpenGL dots or Spherical. The former is quicker to draw,
+but at present does not allow varying sizes among nodes. (The Custom shape is not implemented.)
+For smaller graphs with xdot attributes attached, \smyrna\ will use the xdot information to
+draw the nodes and edges.  
+
+\subsubsection {Defining and setting attributes}
+Attributes can be defined and set in \smyrna\ using either the Attributes tab or \gvpr\ via the
+Script tab. For setting atttributes, the former works on the set of selected nodes. 
+
+\subsection{General Graph Manipulation}
+\label{sec:gvpr}
+There are controls in \smyrna\ for the most common operations such as navigation, selection
+by mouse and simple attribute queries. For more complex selection criteria, and general
+analysis and manipulation of graphs, \smyrna\ is integrated with the \gvpr\ graph processor. 
+The main interface to \gvpr\ is provided by the Script tab (Section~\ref{sec:gvprtab}), though
+\smyrna\ also uses \gvpr\ for various internal operations.
+
+To use \gvpr, you write a script in the \gvpr\ language, which is then applied against an input 
+graph. With the language, you can specify operations to be performed when the graph is first scanned;
+operations to be performed when each node or edge is visited; and operations to be performed after
+all node and edge processing has been done. Node and edge statements can have a boolean guard; with
+this, the action is only performed if the guard is true.
+As a simple example, the script
+\begin{verbatim}
+N[color=="blue"]{selected="1"}
+\end{verbatim}
+causes \gvpr\ to mark all blue nodes as selected.
+
+Though \gvpr\ is primarily designed for working with graphs, it incorporates the C language
+expression model, and provides many general-purpose C-like functions such as {\tt printf} and file I/O,
+string manipulation functions, and associative arrays. A more complete discussion of the use of
+\gvpr\ is outside of the scope of this document. The reader is refered to the \gvpr\ man page for
+further information. 
+
+\subsection{Topological Fisheye Views}
+\label{sec:topfish}