\chapter{Conventions}
\markboth{Conventions}{}

\section{User assumption}
\markright{User assumption}

You, the user of \program{WD-pic}, are assumed to know the \program{pic} language well. If not, please refer to a user's manual of the \program{pic} program~\cite{bk:pic}.

\section{Notational conventions}
\markright{Notational conventions}

The following text conventions are used in the manual:

\begin{itemize}

\item \textrm{Times Roman} is used for normal
text.

\item \textit{Times Italics} is used for emphasis and new
terms in normal text.

\item \textbf{Times Bold} is used for section names.

\item \textsf{Helvetica} is used for program names and
file names except in command lines.

\item \textsf{\textit{Helvetica Oblique}} is used
for widget and key name variables.

\item \textsf{\textbf{Helvetica Bold}} is used for
widget and key name constants.

\item \texttt{Courier} is used for internal representation
contents.

\item \texttt{\textit{Courier Oblique}} is used
for variables of \program{pic} internal representation syntax.

\item \texttt{\textbf{Courier Bold}} is used for
constants of \program{pic} internal representation syntax.

\item {\cmss Computer Modern Sans Serif} is used for
command code and use case names.

\item {\cmssi Computer Modern Sans Serif
Italics} is used for variables of command syntax.

\item {\cmssbx Computer Modern Sans Serif
Bold} is used for constants of command syntax.

\item \textless\widvar{A} + \widvar{B}\textgreater is used to specify
the simultaneous combination of key \widvar{A} and key \widvar{B}.

\item \widvar{MenuA}$\rightarrow$\widvar{MenuItemB} is used to specify
the menu item \widvar{MenuItemB} in the menu \widvar{MenuA}.

\end{itemize}

\section{Terms}
\markright{Terms}

The following terms are used throughout the manual:

\begin{itemize}
\item \program{WD-pic} --- the name of the program.

\item user --- the person who uses \program{WD-pic}, addressed by ``you''.

\item \program{pic} primitive --- abbreviate as ``primitive'', defined by the \program{pic} grammar, \eg\ \token{box}, \token{line}, \token{arrow}, \token{circle}, \token{ellipse}, \token{arc}, \token{spline}, and \token{move}. 

\item \program{pic} object --- abbreviate as ``object'', a \program{pic} primitive together with its attributes. 

\item \program{pic} token --- abbreviate as ``token'', a smallest semantically meaningful syntactic unit in the \program{pic} language, \eg\ \token{box}, \token{line}, \token{arrow}, \token{circle}, \token{ellipse}, \token{arc}, \token{spline}, \token{move}, \token{up}, \token{down}, \token{left}, \token{right}, \token{;}, \token{:}, \widquote, and variable identifiers. 

\item attribute --- used to give more information about a primitive, consisting of a keyword, perhaps followed by a value, \eg
\begin{center}
\begin{tabular}{ll}
\token{h(eigh)t} \picvar{expr},		& \token{wid(th)} \picvar{expr}, \\ 
\token{rad(ius)} \picvar{expr},		& \token{diam(eter)} \picvar{expr}, \\
\token{up} \picvar{opt-expr},		& \token{down} \picvar{opt-expr}, \\
\token{right} \picvar{opt-expr},	& \token{left} \picvar{opt-expr}, \\
\token{from} \picvar{position},		& \token{to} \picvar{position}, \\
\token{at} \picvar{position},		& \token{with} \picvar{corner}, \\
\token{by} \picvar{expr},		& \token{then}, \\
\token{dotted} \picvar{opt-expr},	& \token{dashed} \picvar{opt-expr}, \\
\token{chop} \picvar{opt-expr},		& \token{-> <- <->}, \\
\token{invis},				& \token{solid}, \\
\token{fill} \picvar{opt-expr},		& \token{same}, \\
\picvar{text-list},			& \picvar{expr}.
\end{tabular}
\end{center}

In these attributes, the parenthesized text describes an optional full spelling of the containing token.

\item internal representation --- abbreviate as ``IR'', the text file containing the \program{pic} code corresponding to the picture drawn on the canvas.

\item session --- an invocation of \program{WD-pic}.

\item edit window --- abbreviate as ``EW'', the window used to view and edit the IR.

\item external editor --- your preferred text editor, not part of \program{WD-pic}, indicated to your operating system by setting a shell variable, \eg\ \cmmd{setenv EDITOR vi}.

\item canvas --- used for displaying the picture corresponding to the IR.

\item palette --- used for causing input to the IR, made up of the \wid{box}, \wid{circle}, \wid{ellipse}, \wid{line}, \wid{arrow}, \wid{spline}, \wid{arc}, \wid{;}, \widquote, \wid{Constructs}, \wid{Copy}, \wid{Macros}, \wid{Label}, and \wid{Variables} buttons, and an attribute area, whose content changes to provide the attributes for the object that was most recently inserted.   

\item menu bar --- used for operating and adjusting current session, made up of the \wid{File}, \wid{Edit}, \wid{Tools}, and \wid{Help} menus.

\item menu item --- a unit of a menu.

\item tool bar --- shortcuts to some menu items, made up of the \wid{New}, \wid{Open}, \wid{Save}, \wid{Copy}, \wid{Paste}, \wid{Undo}, \wid{Redo}, \wid{Grid}, and \wid{Help} buttons. 

\item screen layout --- made up of a menu bar, a tool bar, a palette, a canvas and an EW, as shown in Figure~\ref{fig:screen}.

\item left mouse click --- abbreviate as ``LMC'', a left mouse click.

\item right mouse click --- abbreviate as ``RMC'', a right mouse click.

\item double click --- two LMCs not more than 1 second apart.

\item current insertion point --- abbreviate as ``CIP'', the point in the IR in which the next object will be inserted, indicated by the cursor on the canvas and the cursor in the EW; normally, it is after the last inserted object.

\item the picture corresponding to an IR --- the picture generated by \program{pic} when it interprets the entire IR from start to end, regardless of where in the IR the CIP is.  

\item current file name --- a name for the file into which a \usecase{Save} would cause writing of the entire IR.

\item basic interpretation cycle --- abbreviate as ``BIC'', the process starts with inputting into the IR, and ends with the picture on the canvas being redrawn. For example, following sequenced steps illustrate a BIC:  
\begin{enumerate}
 \item LMC a \program{pic} token on the palette.
 \item The token is added to the IR. 
 \item The picture on the canvas is redrawn.
\end{enumerate}

\item pop-up menu --- a menu that is opened by a RMC on the canvas.  

\item grid --- a network of horizontal and vertical lines that provide 
coordinates for locating points on the canvas; a grid is determined by 
\widvar{Center}, \widvar{dX}, and \widvar{dY} values, where 
\widvar{Center} is the origin; \widvar{dX} is the distance between any two 
adjacent horizontal lines; \widvar{dY} is the distance of any two adjacent 
vertical lines.

\item grid point --- a point in a grid at which a horizontal line and a vertical line cross.

\item gravity --- used to control the restriction of positioning points; it has no effect on the IR.

\item gravity tightness radius --- abbreviate as ``tightness radius'', the radius of the area around a grid point or an object corner around which gravity is effective.

\item approximate point --- the point on the canvas that you LMCed.

\item indicated point --- the point corresponding to an approximate point that is finally indicated by \program{WD-pic} by use of gravity and inserted into the IR.

\item type \picvar{xxx} --- type \picvar{xxx} from the keyboard without concern for the location of the cursor; \picvar{xxx} is added to the IR at the CIP and is shown also in the EW.

\item type \picvar{xxx} into the EW --- make sure the cursor is in the EW; type \picvar{xxx} from the keyboard; \picvar{xxx} is added to the EW at the CIP.

\item type \picvar{xxx} into the external editor --- make sure the cursor is in the external editor, type \picvar{xxx} from the keyboard; \picvar{xxx} is added to the to-be-edited file, which is taken as the IR after you save and quit the external editor. 

\item type \picvar{xxx} into the \widvar{yyy}\ field of \widvar{zzz}\ dialog --- make sure the cursor is in the \widvar{yyy} field of \widvar{zzz} dialog; type \picvar{xxx} from the keyboard; \widvar{xxx} is added to the \widvar{yyy} field of \widvar{zzz} dialog.

\end{itemize}

\section{Abbreviations}
\markright{Abbreviations}

\begin{itemize}
\item BIC --- \textbf{B}asic \textbf{I}nterpretation \textbf{C}ycle
\item CIP --- \textbf{C}urrent \textbf{I}nsertion \textbf{P}oint
\item EW --- \textbf{E}dit \textbf{W}indow
\item GUI --- \textbf{G}raphic \textbf{U}ser \textbf{I}nterface
\item IR --- \textbf{I}nternal \textbf{R}epresentation
\item LMC --- \textbf{L}eft \textbf{M}ouse \textbf{C}lick
\item RMC --- \textbf{R}ight \textbf{M}ouse \textbf{C}lick
\item WD --- \textbf{W}YSIWYG \textbf{D}irect-manipulation 
\item WYSIWYG --- \textbf{W}hat \textbf{Y}ou \textbf{S}ee \textbf{I}s \textbf{W}hat \textbf{Y}ou \textbf{G}et
\end{itemize}

\section{Basic user interface goals}
\markright{Basic user interface goals}

Compared to the \program{pic} program, the major advantage of \program{WD-pic} is its GUI. This GUI gives you the benefits of WYSIWYG and direction manipulation. Some other basic goals of the user interface of \program{WD-pic} are the following:

\begin{itemize} 
\item All styles of input, \ie\ by mouse or by keyboard, are fully interchangeable, without the need to inform the application where its next input is coming from.

\item There is no need to move the mouse to the canvas or the EW except to explicitly and directly identify a point or an object; therefore, the mouse movement is minimized. 

\item The internal representation should be as much as possible what a human would write in the \program{pic} language to achieve the picture shown on the canvas.

\item When inputting text that is expected and that has a definite end, there is no need to move the mouse to a text window and to confirm at the end. 
\end{itemize}

\section{First sample redone}
\markright{First sample redone}

As mentioned in Section 1.2, there are always alternative ways to draw the same picture. Besides using the palette as described in Section 1.2, you can also type the whole IR given in Figure~\ref{fig:flowcode} into the EW or with an external editor.  

The following sequenced steps illustrate another way to draw Figure~\ref{fig:flowdiagram} strictly from the keyboard: 

\begin{enumerate}
\item Type \wid{e l l i p s e}. The \code{ellipse} token is added to the IR at the CIP. After you enter a blank, an ellipse with default size is added at the CIP on the canvas.
\item Type \widquote\ to start inputting text or you can LMC the \widquote\ button on the palette. In either case, \codequote\ is added to the IR at the CIP. 
\item Type \wid{d o c u m e n t}. \code{document} is added to the IR at the CIP.
\item End the text input by typing \widquote\ from the keyboard. After \codequote\ is added to the IR, the ellipse object is redrawn with text ``document'' in its center on the canvas.
\item Press the \wid{Enter} key to finish inputting the ellipse object. A new line is started in the IR.
\item Type \wid{a r r o w}. \code{arrow} is added to the IR at the CIP. After the \wid{Enter} key is pressed, an arrow with default size is added at the CIP on the canvas.
\item Type \wid{b o x}\ \textvisiblespace\ \widquote\ \wid{p i c}\ \widquote. \code{box} \codequote\code{pic}\codequote\ is added to the IR at the CIP. After the \wid{Enter} key is pressed, a box with ``pic'' at the center is added at the CIP on the canvas.
\item Type \wid{a r r o w}. \code{arrow} is added to the IR at the CIP. After the \wid{Enter} key is pressed, an arrow with default size is added at the CIP on the canvas.
\item Type \wid{b o x}\ \textvisiblespace\ \widquote\ \wid{t r o f f} \widquote. \code{box} \codequote\code{troff}\codequote\ is added to the IR at the CIP. After the \wid{Enter} key is pressed, a box with ``troff'' at the center is added at the CIP on the canvas.
\item Type \wid{a r r o w}. \code{arrow} is added to the IR at the CIP. After the \wid{Enter} key is pressed, an arrow with default size is added at the CIP on the canvas.
\item Type \wid{e l l i p s e} \textvisiblespace\ \widquote\ \wid{t y p e s e t t e r} \widquote. \code{ellipse}\ \codequote\code{typesetter}\codequote\ is added to the IR at the CIP. After the \wid{Enter} key is pressed, an ellipse with ``typesetter'' at the center is added at the CIP on the canvas.
\end{enumerate}

If you see the text in red in the EW after inputting \wid{;} or \wid{Enter} key, you have made a syntax error. Check your input in the EW, and correct it. If you see the text in red in the EW before inputting \wid{;} or \wid{Enter} key, the text could be right. \program{WD-pic} marks it red because the sentence is not completed.

At this point, you should see the picture of Figure~\ref{fig:flowdiagram} drawn on the canvas while the \program{pic} code of Figure~\ref{fig:flowcode} is in the EW, as illustrated in Figure~\ref{fig:firstsample}. 

In the following sections, you will learn how to change the attributes of the objects and how to draw an object at a desired position.

\section{Using grid \& gravity}
\markright{Using grid \& gravity}

There are cases in which a specific position is desired. For instance, 
after 
having given an \token{at}, \token{from}, or \token{to} token, you would then need to specify a position. A position could be a (\emph{x, y}) coordinate pair, or may be specified in other ways. For example, you might want to draw the diagram shown in Figure 2.1.

\begin{figure}
\begin{center}
\parbox{2.8in}{
\begin{center}
\epsfig{figure=example.eps}
\end{center}
\caption{An example diagram}
}
\parbox{3.2in}{
\vspace{.78in}
\code{Box1: box} \\
\code{box at Box1.c + (boxwid, boxht)}
\vspace{.4in}
\caption{\program{pic} code of Figure 2.1}
}
\end{center}
\end{figure}

This diagram can be generated from the \program{pic} code shown in Figure 2.2.

One way to draw Figure 2.1 and to get the IR shown in Figure 2.2 is to use the keyboard to enter the text of Figure 2.2 into the IR. Another way is by direct manipulation. 

Two key concepts of \program{WD-pic} are its grid and gravity. Their main purpose is to allow direct manipulation placement of objects while getting (\emph{x, y}) coordinates that would be written by a human user when using \program{pic} in the batch mode. Gravity is used to map the approximate point that you can achieve with a mouse to a corner of an existing object or to a grid point. When gravity is off, the point you have LMCed, whatever its coordinates are as a pair of real numbers, is taken as the indicated point.  

The following steps show one way of using grid and gravity to draw the 
diagram:
\begin{enumerate}
\item LMC the \wid{box} button. \code{box} is added to the IR at the CIP. A box with default size is drawn on the canvas according to the IR.
\item LMC the \wid{Label} button. Type \wid{B o x 1} and end the label input by typing \wid{:}. \code{Box1:} is added to the IR before \code{box}.
\item Select \menu{Tools}{Define Grid} from the menu bar. A \wid{Grid Definition} dialog with fields filled with default values, as illustrated in Figure~\ref{fig:griddef}, shows up.
 
\begin{figure}
\begin{center}
\epsfig{figure=griddef.eps,height=1.7in}
\end{center}
\caption{\wid{Grid Definition} Dialog}\label{fig:griddef}
\end{figure}

\item Type \code{Box1C} into the \wid{Name} field, \code{Box1.c} into the \wid{Center} field, \code{boxwid} into the \wid{dX} field, and \code{boxht} into the \wid{dY} field, as illustrated in Figure~\ref{fig:gridbox1c}.

\begin{figure}
\begin{center}
\epsfig{figure=gridbox1c.eps, height=1.7in}
\end{center}
\caption{Grid Box1C}\label{fig:gridbox1c}
\end{figure} 

\item LMC the \wid{Activate Now} button. A grid with name \code{Box1C}, center \code{Box1.c}, dX \code{boxwid}, and dY \code{boxht} is saved. The canvas is redrawn according to the current complete IR with the activated grid \code{Box1C} superimposed, as illustrated in Figure~\ref{fig:gridsampleI}.

\begin{figure}
\begin{center}
\epsfig{figure=sampleI.eps}
\end{center}
\caption{A sample of using grid \& gravity - I}\label{fig:gridsampleI}
\end{figure}

\item Select \menu{Tools}{Set Gravity} from the menu bar. A \wid{Gravity Settings} dialog with fields filled with default values, as illustrated in Figure~\ref{fig:gravityset}, shows up.

\begin{figure}
\begin{center}
\epsfig{figure=gravity.eps, height=3.0in}
\end{center}
\caption{\wid{Gravity Setting} Dialog}\label{fig:gravityset}
\end{figure}

\item Make sure that \wid{on} and \wid{medium} are selected, and \wid{gravitate to grid points} and \wid{gravitate to \program{pic} corners} are checked.
\item LMC the \wid{OK} button. 
\item LMC the \wid{box} button from the palette. \code{box} is added to the IR at the CIP. 
The canvas is redrawn from the current complete IR.
\item LMC the \wid{at} button from the palette. \code{at} is added to the IR at the CIP.
\item Move the mouse to the canvas, and LMC the grid point just northeast of the box's northeast corner in Figure~\ref{fig:gridsampleII}.
\item \code{Box1.c + (boxwid, boxht)} is added to the IR after the \code{at} at the CIP. 
The whole picture is redrawn with the second box at the expected position, as shown in Figure~\ref{fig:gridsampleIII}.
\end{enumerate}

\begin{figure}
\begin{center}
\parbox{3.1in}{
\begin{center}
\includegraphics{sampleII.eps}
\end{center}
\caption{\footnotesize A sample of using grid \& gravity - II}\label{fig:gridsampleII}
}
\parbox{3.1in}{
\begin{center}
\includegraphics{sampleIII.eps}
\end{center}
\caption{\footnotesize A sample of using grid \& gravity - III}\label{fig:gridsampleIII}
}
\end{center}
\end{figure}
\normalsize 
Grid and gravity are independent session concepts. They are used to help you work with the objects on the canvas by direct manipulation. Thus the grid appears on the canvas, but not in the IR. Details of grid and gravity setting are given in Sections 3.1.5 and 3.1.7.

\section{Organization of this manual}
\markright{Organization of this manual}

The rest of the manual is organized mainly based on use cases. Chapter 3 describes the basic use cases affecting both the session and the IR. Chapter 4 describes the advanced features of the program. What to do if you have trouble and tips on how to use the program better are given in Chapter 5. Chapter 6 gives the limitations of the current version of 
\program{WD-pic}.  
