\documentstyle[texdraw]{article}
%
% manual.tex - user's manual for GraphTeX
% $Id: manual.tex,v 1.4 1994/02/03 03:03:16 pliam Exp $
%

%
% margins
%
\addtolength{\oddsidemargin}{-0.8125in} % Set up for 1 inch margins
\addtolength{\textwidth}{1.6875in}      % in 10pt LaTeX styles
\addtolength{\topmargin}{-0.8125in}
\addtolength{\textheight}{1.375in}
%
% various logos
%
\newcommand{\gtlogo}{Graph-$\!$\TeX}
\def\XY{\leavevmode\hbox{X\kern-.3em\lower.4ex\hbox{Y\kern-.15em}}}
\newcommand{\xypic}{\XY\,-pic}
\newcommand{\txdrw}{\TeX draw}
%
% subsectioning (drop the section stuff)
%
\renewcommand{\thesubsection}{\arabic{subsection}}
\renewcommand{\thesubsubsection}{\arabic{subsection}.\arabic{subsubsection}}
%
% math help
%
\newcommand{\mmtt}[1]{\mbox{{\tt #1}}} % math-mode \tt
\newcommand{\adj}{\mathop{adj}\nolimits}
\newcommand{\bul}{$\bullet$}
\input{dihed.tex}
%
% BNF stuff
%
\newcommand{\bnf}[1]{$\langle \text{#1} \rangle$}
\newcommand{\ra}{$\rightarrow$}
\newcommand{\pipe}{$|$}
\newcommand{\emp}{$\varepsilon$}

\begin{document}
%
% title
%
\begin{minipage}[t]{2.5in}
\begin{center}
$\dihedral{a}{b}$
\end{center}
\end{minipage} \ \begin{minipage}[t]{3.5in}
{\Large 
\begin{center}
{\huge \gtlogo\ User's Manual} \\
John Pliam\footnotemark \\
Version 1.0$\beta$, \today \\
\end{center}
}
\end{minipage}
\footnotetext[1]{Your special friend: pliam@ima.umn.edu}

\vspace{.5in}
\subsection{Introduction}

If you are anal retentive like me, there are certain things you expect to
see in a graph: smoothly curved edges, spade-like arrowheads which
follow the curve of the edge, \TeX\ labels, etc.  \gtlogo\ tries to meet 
these expectations by performing tedious calculations from high school 
trigonometry.

\gtlogo\ is actually a {\em Perl}\, library ({\tt graphtex.pl}) along with
a preprocessor
({\tt gt}) which can be used to generate {\em \txdrw}\ commands producing 
graphs and related diagrams inside a \TeX\ document.  A graph can be 
``typeset'' by writing {\tt .gt} source file which resembles a matrix 
environment
\footnote{This idea is an outright plagiarism of \xypic, a GNU-protected 
package which is great for commutative diagrams, but which seemed inadequate 
for my graphs.  \gtlogo\ even started life as a set of macros for \xypic.}.

If your graph can be drawn with all its vertices lying on a rectilinear 
grid, you needn't be aware of the Perl interface aside from carrying out 
the
$$
\mmtt{.gt} \rightarrow \mmtt{.tex}
$$
preprocessing.
On the other hand, some graphs, such as the Peterson graph, are not 
naturally drawn with their vertices on any rectilinear grid.  A simple Perl
script including both the position and adjacency information, can produce
desired {\tt .tex} file (see \S \ref{sec:lib} below).

\subsection{Installation}

First, get the latest compressed tar file via anonymous ftp from {\tt
ima.umn.edu}.  It is in the directory {\tt /pub/graphtex}.  In order for 
\gtlogo\ to work, you need to have the following packages installed: 
\TeX, Perl, \txdrw, and dvips (any {\tt .dvi} to {\tt .ps} program which 
respects \verb|\special| for postscript insertion).  Attend to definitions 
{\tt PERLLIB}, {\tt PERLEXEC} and {\tt BINDER} in the {\tt Makefile}, and type
$$
\mmtt{make install}
$$

\subsection{Using the Preprocessor, {\tt gt}}

\subsubsection{A Simple Example}

The graph
$$
\input{examp1.tex}
$$
was typeset by the following \TeX\ commands:
\begin{verbatim}
The graph
$$
\input{examp1.tex}
$$
was typeset by ...
\end{verbatim}
The file {\tt examp1.tex} was automatically generated by the command line
$$
\mmtt{gt examp1.gt}
$$
where the extension ``{\tt .gt}'' is optional.  The ultimate source file,
{\tt examp1.gt} looks like this:
\input{examp1.texinput}
Notice that all commands and comments resemble \TeX\ input even though they 
are processed by a Perl script.  The array-like environment defines both
the position of vertices and the adjacency structure of the graph.  The
vertices lie on a rectilinear grid whose spacing is \verb|\versep| (10 mm
by default).  The edges must be defined in the cell corresponding to the
vertex from which they emanate.  The destination of an edge is usually 
defined by a string of relative displacement characters $\{ \mmtt{l},
\mmtt{r},\mmtt{u},\mmtt{d} \}$ (short for {\em left}, {\em right}, {\em
up}, {\em down}) preceding the edge commands: {\tt to},
{\tt edge}.

\subsubsection{Command Summary}

Below is a table of graphics commands recognized by \gtlogo.  Notice that
the vertices are enlarged, and the edges are shown along with vertices
to indicate their relative positions.
$$
\input{table.tex}
$$
Additionally, objects can have labels (\S \ref{sec:label}), edges can curve
(\S \ref{sec:curve}), and most drawing attributes can be changed with
commands \verb|\gtset{}{}| and \verb|\gtsetglb{}{}| (\S \ref{sec:attrib}).

\subsubsection{Labels}
\label{sec:label}

Edge and vertex labels also resemble the corresponding \TeX\ 
commands, but they are more flexible.  Consider the following variant of
{\tt examp1.gt}.

\begin{minipage}[t]{2.0in}
$$
\input{examp2.tex}
$$
\vspace{1em}
\end{minipage} \begin{minipage}[t]{4.0in}
\input{examp2.texinput}
\end{minipage}

Though the text offset is defined by the variable \verb|\txtoff| the angle
is defined by the sequence of characters from set
$\{$ \verb|<|, \verb|>|, \verb|^|, \verb|v|, \verb|_| $\}$.
For example, \verb|\ver^^>{\hat{g}}| will produce a vertex labeled by a 
``$\hat{g}$''.  The label starts at a point \verb|\txtoff| away from the 
vertex and at an angle of $\tan^{-1}(2)$, and ``grows'' in that direction.
$$
\input{ghat.tex}
$$

Edge labels can only have an ``up'' or ``down'' orientation defined by a
single character in the set 
\hbox{$\{$ \verb|^|, \verb|_| $\}$}.  
The actual position of the edge label is a function of the relative position 
of the source and destination vertices along with prescribed orientation.  
In other words, ``up'' may mean ``down.''  The emphasis here is on symmetry;
If you get one label right and stick with its orientation, you'll probably 
get all the orientations right.  The next graph has all its labels outside:

\begin{minipage}[t]{2.0in}
$$
\input{hex1.tex}
$$
\vspace{1em}
\end{minipage} \begin{minipage}[t]{4.0in}
\input{hex1.texinput}
\end{minipage}

\noindent
The following graph has all its labels inside, and is derived from the
previous by changing \verb|^| to \verb|_|.

\begin{minipage}[t]{2.0in}
$$
\input{hex2.tex}
$$
\vspace{1em}
\end{minipage} \begin{minipage}[t]{4.0in}
\input{hex2.texinput}
\end{minipage}

\subsubsection{Loops and Curved Edges}
\label{sec:curve}

\gtlogo\ allows for loops and Bezier curved edges as in the following graph.

\begin{minipage}[t]{2.0in}
$$
\input{curv.tex}
$$
\vspace{1em}
\end{minipage} \begin{minipage}[t]{4.0in}
\input{curv.texinput}
\end{minipage}

\noindent
The orientation of a loop is similar to that of a vertex label.  A
sequence of characters in the set
\hbox{$\{$ \verb|<|, \verb|>|, \verb|^|, \verb|v|, \verb|_| $\}$}
specifies the looping direction.  The specification of an edge's bend is 
similar to that of its label.  A single character in the set
\hbox{$\{ \mmtt{+}, \mmtt{-} \}$},
along with the relative position of the endpoints, determines the bending
direction.

\subsubsection{Changing the Attributes}
\label{sec:attrib}

Consider the graph

\begin{minipage}[t]{2.0in}
$$
\input{local.tex}
$$
\vspace{1em}
\end{minipage} \begin{minipage}[t]{4.0in}
\input{local.texinput}
\end{minipage}
\vspace{1em}

\noindent
where it was necessary to locally change the variables \verb|\edgmu| and
\verb|\labelmu|, which are the parameters defining how far to move along 
the Bezier curve before drawing the arrowhead and label, respectively.
This was accomplished with the command \verb|\gtset{}{}| which changes a
variable only within the \verb|&|'s (i.e. within the current {\em cell}\,).
To change an attribute globally, the \verb|\gtsetglb{}{}| command can be
used before any other command.  This is particularly useful when the 
picture as a whole has a different style than the typical graph.  For 
example, the following exact sequence redefines \verb|\versep|, 
\verb|\verrad|, \verb|\edgmu|, and \verb|\bezfact|.
$$
\input{diag.tex}
$$
\input{diag.texinput}
The following graph is drawn in a style common in Automata Theory.
\vspace{1em}
$$
\input{auto.tex}
$$
\input{auto.texinput}

\noindent
For a complete list of \gtlogo\ variables see \S \ref{sec:var}.

\subsubsection{Absolute Form of Edge Commands}
\label{sec:absolut}

So far we have only shown the relative form of the edge commands, e.g.
\verb|\rruto|.  However the destination of an edge can be defined
in an absolute way by referring explicitly to its name inside \verb|<|
and \verb|>|.  When using {\tt gt}, all vertices are given names of the 
form
$$
\mmtt{grid}x,y
$$
where $x$ and $y$ are column and row integers, respectively, starting from
\verb|grid0,0| at the upper lefthand corner of the array environment.   So 
for example, the following graph

\begin{minipage}[t]{2.0in}
$$
\input{absolut.tex}
$$
\vspace{1em}
\end{minipage} \begin{minipage}[t]{4.0in}
\begin{verbatim}
\ver \to<grid1,2> & \ver \\
\ver & \ver \\
\ver & \ver \to<grid1,1>
\end{verbatim}
\end{minipage}

\noindent
could have just as easily been created from the commands below.
\begin{verbatim}
\ver \rddto & \ver \\
\ver & \ver \\
\ver & \ver \uto
\end{verbatim}

\subsection{Using The Perl Library}
\label{sec:lib}

In this section we describe the Perl library {\tt graphtex.pl} which can be
used to generate graphs whose vertex spacing is not rectilinear.  Consider
the Peterson graph below:
$$
\input{pete.tex}
$$
Since the graph possesses symmetries (i.e. it's automorphism group contains
the dihedral group $D_5$), it is didactic to draw the graph with it's 
vertices lying on circles with an angular spacing of $2\pi/5$ radians.  A 
placement of the vertices on a grid cannot express the symmetries.  For this 
reason, \gtlogo\ was built up from a library of Perl functions to facilitate 
the drawing of graphs with arbitrary vertex positions and adjacency.

To write a Perl script to generate \txdrw\ commands for a graph, the
following steps must be taken:
\begin{list}{}{}
\item[\bul] Require {\tt graphtex.pl}.
\item[\bul] Define the vertex positions in the associative array \verb|%posit|.
\item[\bul] Define the adjacency structure in the associative array
            \verb|%connect|.
\item[\bul] Open the file handle {\tt OUT}.
\item[\bul] Call \verb|&parse|.
\end{list}

\noindent
In order to define a graph, a name must be assigned to each vertex, such as
{\tt in1},...,{\tt in5},{\tt out1},...,{\tt out5} for the Peterson graph.
Then the position and adjacency information is attached to the name via 
the associative arrays\footnote{
Associative arrays in Perl allow array values to be indexed by 
{\em strings} (as opposed to the more common {\em integer} indices).
}
\verb|%posit| and \verb|%connect|.  A \verb|%posit| value is a string
consisting of the $x$ and $y$ coordinates separated by white space.  A
\verb|%connect| value is a string consisting of \gtlogo\ commands as if
they were in any cell of a {\tt .gt} file.  Of course in a \verb|%connect|
array, the absolute form of the edge commands (see \S \ref{sec:absolut})
is the most useful.  As an example we list the entire Perl script {\tt 
peterson}:
\input{peterson.texinput}

\subsection{Reference Guide}
\label{sec:ref}

In this section we provide a pedantic description of the \gtlogo\ variables
and commands.

\subsubsection{Variables}
\label{sec:var}

Certain variables define the attributes of graph drawing, such as edge
curvature.  \gtlogo\ treats the sequence of commands appearing between the 
{\tt \&}'s as a subroutine call in the sense that changes in attributes
(effected by the \verb|\gtset{}{}| command)
have scope limited to objects emanating from the current vertex.  Of course
global definitions can be declared using the \verb|\gtsetglb{}{}| command.

The following table gives the \gtlogo\ variables, their defaults, and their
meanings.

\begin{center}
\begin{tabular}{lll}
\verb|\drawdim| & mm & drawing dimension \\
\verb|\linewd| & 0.3 & line width \\
\verb|\txtrefh| & {\em null string} & override horizontal text reference 
                                      parameter (L, C, R) \\
\verb|\txtrefv| & {\em null string} & override vertical text reference 
                                      command (T, C, B) \\
\verb|\vertstr| & 1.0 &  vertical stretch \\
\verb|\arrowwd| & 2.0 &  arrowhead width \\
\verb|\arrowln| & 2.0 &  arrowhead length \\
\verb|\arrowdp| & 1.0 &  arrowhead depth (length where wings meet) \\
\verb|\verrad| & 0.75 &  vertex radius \\
\verb|\versep| & 10 &  vertex separation \\
\verb|\txtoff| & 2.0 &  text offset \\
\verb|\bezfact| & 0.75 &  Bezier curve stretch factor \\
\verb|\edgmu| & 0.5 &  how far to move along edge before arrow \\
\verb|\labelmu| & 0.5 &  how far to move along edge before label \\
\verb|\loopln| & 10 &  dimensions of rectangle enclosing loop \\
\verb|\loopwd| & 15 &  \hspace{1in}" \\
\verb|\loopmu| & 0.18 &  how far to move along loop before arrow \\
\verb|\llabelmu| & 0.5 &  how far to move along loop before label \\
\verb|\stubrat| & 0.5 & fraction of \verb|\versep| to draw \verb|\stub| or 
                        \verb|\from| \\
\verb|\inverrat| & 0.75 &  ratio of inner to outer radius for \verb|\dblver| \\
\verb|\boxwd| & 1.5 &  width of a \verb|\box| \\
\verb|\boxht| & 1.5 &  height of a \verb|\box| \\

\end{tabular}
\end{center}

\subsubsection{Command Syntax}
The following is a stylized BNF of the syntax of a {\tt .gt} file:

\begin{center}
\begin{tabular}{rcl}
%
% gt file
%
\bnf{gt file} & \ra & \bnf{global decl.} \bnf{gt environment} \\
%
% global decl.
%
\bnf{global decl.} & \ra & \emp \\
 & \pipe & \verb|\gtsetglb{| \bnf{variable ident.} \verb|}{| 
   \bnf{PERL EXPR.} \verb|}| \bnf{global decl.} \\
\bnf{variable ident.} & \ra & \verb|\| \bnf{STRING} \\
%
% environment
%
\bnf{gt environment} & \ra & \bnf{line} \verb|\\| \bnf{line list} \\
\bnf{line list} & \ra & \emp\ \pipe\ \bnf{line} \verb|\\| \bnf{line list}\\
%
% line
%
\bnf{line} & \ra & \bnf{cell} \verb|&| \bnf{cell list} \\
\bnf{cell list} & \ra & \emp\ \pipe\ \bnf{cell} \verb|&| \bnf{cell list}\\
\end{tabular}
\end{center}

Below is the BNF of the syntax of a \bnf{cell}.  These can of course occur
between \&'s in a {\tt .gt} file, or inside the \verb|%connect| array of a 
Perl script.

\begin{center}
\begin{tabular}{rcl}
%
% cell
%
\bnf{cell} & \ra & \bnf{command} \bnf{command list} \\
\bnf{command list} & \ra & \emp\ \pipe\ \bnf{command} \bnf{command list}\\
%
% command
%
\bnf{command} & \ra & \bnf{local decl.} \\
& \pipe\ & \bnf{math expr} \\
& \pipe\ & \bnf{vertex} \\
& \pipe\ & \bnf{edge} \\
& \pipe\ & \bnf{stub} \\
& \pipe\ & \bnf{box} \\
%
% local decl.
%
\bnf{local decl.} & \ra & \verb|\gtset{| \bnf{variable ident.} \verb|}{| 
                          \bnf{PERL EXPR.} \verb|}| \\
%
% math expr
%
\bnf{math expr} & \ra & \bnf{STRING} \\
%
% vertex
%
\bnf{vertex} & \ra & \bnf{vertex type} \bnf{ver. label} \\
\bnf{vertex type} & \ra & \verb|\ver| \pipe\ \verb|\dblver| \pipe\
                          \verb|\solver| \\
\bnf{ver. label} & \ra & \emp\ \pipe\ \bnf{ver. orientation} \verb|{|
                         \bnf{math expr} \verb|}| \\
\bnf{ver. orientation} & $\in$ & $\{$ \verb|<|, \verb|>|, \verb|^|, \verb|v|,
                                 \verb|_| $\}^*$ \\
%
% edge
%
\bnf{edge} & \ra & \bnf{relative edge} \bnf{edge options} \\
 & \pipe & \bnf{absolute edge} \bnf{edge options} \\
\bnf{relative edge} & \ra & \verb|\| \bnf{displacement} \bnf{edge type} \\
\bnf{absolute edge} & \ra & \verb|\| \bnf{edge type} \verb|<| \bnf{STRING}
    \verb|>| \\
\bnf{edge type} & \ra & {\tt to} \pipe\ {\tt edg} \pipe {\tt stick} \\
\bnf{displacement} & $\in$ & $\{ \mmtt{l}, \mmtt{r}, \mmtt{u}, \mmtt{d}
                             \}^*$ \\
%
% edge options
%
\bnf{edge options} & \ra & \bnf{bend} \bnf{edge label} \\
\bnf{bend} & \ra & \emp\ \pipe\ \verb|(+)| \pipe\ \verb|(-)| \\
\bnf{edge label} & \ra & \emp\ \pipe\ \bnf{edge orientation} \verb|{|
                         \bnf{math expr} \verb|}| \\
\bnf{edge orientation} & \ra & \verb|^| \pipe\ \verb|_| \\
%
% stub
%
\bnf{stub} & \ra & \verb|\| \bnf{displacement} \bnf{stub type} \\
\bnf{stub type} & \ra & \verb|stub| \pipe\ \verb|from| \\
%
% box
%
\bnf{box} & \ra & \verb|\box| \\

\end{tabular}
\end{center}

\end{document}
