SysIII/usr/src/man/docs/graf_over

.ds :? P\s-1WB\s+1/Graphics Overview
.PH "''''"
.OH "'\s9\f2\*(:?\fP''\\\\nP\s0'"
.EH "'\s9\\\\nP''\f2\*(:?\^\fP\s0'"
.na
.bd S B 3
.EQ
delim $$
.EN
.TL 49582-063 39382-900
PWB/Graphics Overview
.AU "A. R. Feuer" ARF PY 3782 7016 2F-202
.TM 79-3782-1
.MT 4
.sp
.sp 3
.H 1 INTRODUCTION
PWB/Graphics, or just
.I graphics,
is the name given to a growing collection
of numerical and graphical commands available
as part of the Programmer's Workbench [1].
In its initial release,
.I graphics
includes commands to construct and edit
numerical data plots and hierarchy charts.
This memorandum will help you get started using
.I graphics
and show you where to find more information.
The examples below assume that you are familiar with
the \s-1UNIX\s+1\*(Tm Shell [1].
.H 1 "BASIC CONCEPTS"
The basic approach taken in
.I graphics
is to generate a drawing by describing it
rather than by drafting it.
Any drawing is seen as having two fundamental
attributes:
its underlying logic and its visual layout. 
The layout encompasses one representation
of the logic.
For example, consider the attributes of a drawing that
consists of a plot of the function
$y = x sup 2$ for $x$ between 0 and 10.
The logic of the plot is the description as just
given, viz. $y = x sup 2 , 0 <= x <= 10$.
The layout consists of an x-y grid,
axes labeled perhaps 0 to 10 and 0 to 100,
and lines drawn connecting the x-y pairs
0,0 to 1,1 to 2,4 and so on.
.P
The way to generate a picture in
.I graphics
is
.DS  1 1
gather data | transform the data | generate a layout | display the layout.
.DE
To generate the specific plot of $y = x sup 2 , 0 <= x <= 10$
and display it on a Tektronix\(rg display terminal
would be:
.DS 1 1
.tr ~"
.B "gas \-s0,t10 | af ~x^2~ | plot | td"
.DE
.VL 1i .5i
.LI \fBgas\fR
generates sequences of numbers,
in this case \fBs\fRtarting at 0
and \fBt\fRerminating at 10.
.LI \fBaf\fR
performs general arithmetic transformations.
.LI \fBplot\fR
builds x-y plots.
.LI \fBtd\fR
displays drawings on Tektronix terminals.
.LE 1
The resulting drawing is shown in Figure 1.
.P
The layout generated by a \fIgraphics\fR program may not always
be precisely what is wanted.
There are two ways to influence the layout.
Each drawing program accepts options to direct
certain layout features.
For instance,
in the previous example
we may have wanted the x-axis labels to
indicate each of the numbers plotted and
we might not have wanted any y-axis labels at all.
To achieve this the \fIplot\fR command would be changed to:
.DS 1 1
.B "plot \-xi1,ya"
.DE
producing the drawing of Figure 2.
.P
The output from any drawing command can also be
affected by editing it directly at a display terminal using the
graphical editor, \fIged\fR.
To edit a drawing really means to edit the computer
representation of the drawing.
In the case of
.I graphics
the representation is called a graphical primitive string,
or \s-1GPS\s+1.
All of the drawing commands (e.g., \fIplot\fR\|) write \s-1GPS\s+1 and all of the
device filters (e.g., \fItd\fR\^) read \s-1GPS\s+1.
\fIGed\fR allows you to manipulate \s-1GPS\s+1 at a display terminal
by interacting with the drawing the \s-1GPS\s+1 describes.
.SK 1
.P
\s-1GPS\s+1 describes graphical objects drawn within
a Cartesian plane 65,534 units on each axis.
The plane, known as the \fIuniverse\fR,
is partitioned into 25 equal sized square regions.
Multi-drawing displays can be produced
by placing drawings into adjacent regions
and then displaying each region.
.H 1 "GETTING STARTED"
To access the
.I graphics
commands when logged in on a \s-1PWB/UNIX\s+1 system type
.B graphics.
Your \fIShell\fR variable \fB\s-1PATH\s+1\fR will be altered
to include the
.I graphics
commands and the \fIShell\fR
primary prompt will be changed to \fB^\fR.
Any command accessible before typing
.B graphics
will still be accessible;
.I graphics
only adds commands, it doesn't take any away.
Once in
.I graphics,
you can find out about any of the
.I graphics
commands using \fIwhatis\fR.
Typing \fBwhatis\fR by itself on a command line
will generate a list of all the commands in
.I graphics
along with instructions on how to find out
more about any of them.
.P
All of the \fIgraphics\fR commands accept the same
command line format:
.VL 2.1i .5i
.LI "A command is:"
a \fIcommand-name\fR followed by \fIargument\fR(s).
.LI "A \fIcommand-name\fR is:"
the name of any of the \fIgraphics\fR commands.
.LI "An \fIargument\fR is:"
a \fIfile-name\fR or an \fIoption-string\fR.
.LI "A \fIfile-name\fR is:
any file name not beginning with \fB\-\fR,
or a \fB\-\fR by itself to reference the standard input.
.LI "An \fIoption-string\fR is:"
a \fB\-\fR followed by \fIoption\fR(s).
.LI "An\ \fIoption\fR\ is:"
letter(s) followed by an optional value.
Options may be separated by commas.
.LE
.P
You will get the best results with
.I graphics
commands if you use a display terminal.
\fIPlot\fR\|(1) filters can be used in conjunction
with \fIgtop\fR (see \fIgutil\fR(1)) to get somewhat degraded
drawings on Versatec printers and Dasi-type terminals.
And since \s-1GPS\s+1 can be stored in a file,
it can be created from any terminal for later displaying
on a graphical device.
.P
To remove the
.I graphics
commands from your
.B \s-1PATH\s+1
.I Shell
variable type \fB\s-1EOT\s+1\fR (control-d on most terminals).
To logoff \s-1UNIX\s+1 from
.I graphics
type \fBquit\fR.
.sp
.H 1 "EXAMPLES OF WHAT YOU CAN DO"
.H 2 "Numerical Manipulation and Plotting"
\fIStat\fR\|(1) describes a collection of numerical commands.
All of these commands operate on vectors.
A vector is a text file that contains
numbers separated by delimiters,
where a delimiter is anything that is not
a number.
For example,
.DS 1
1 2 3 4 5, and
arf tty47 Mar 5 09:52
.DE
are both vectors.
(The latter being the vector: 47 5 9 52.)
.sp 2
Here is an easy way to generate a Celsius-Fahrenheit
conversion table using \fIgas\fR to generate
the vector of Celsius values:
.DS 1 1
.B "gas \-s0,t100,i10 | af ~C,9/5*C+32~"
.DE
.SK
The output is:
.DS 1
0.0         	32          
10          	50          
20          	68          
30          	86          
40          	104         
50          	122         
60          	140         
70          	158         
80          	176         
90          	194         
100         	212         
.DE
This is what is going on:
.VL 2i .5i
.LI "\fBgas \-s0,t100,i10\fR"
We have seen \fIgas\fR in an earlier example.
In this case the sequence \fBs\fRtarts at
0, \fBt\fRerminates at 100, and the
\fBi\fRncrement between successive elements
is 10.
.LI "\fBaf ~C,9/5*C+32~\fR"
We have also seen \fIaf\fR.
Arguments to \fIaf\fR are expressions.
Operands in an expression are either constants
or filenames.
If a filename is given that does not exist in the
current directory it is taken as the name for the
standard input.
In this example \fBC\fR references the standard
input.
The output is a vector with odd
elements coming from the standard input
and even elements being a function of
the preceding odd element.
.LE
.sp 2
Here is an example that illustrates the use of
vector titles and multiline plots:
.DS 1
.B "gas | title \-v~first ten integers~ >N"
.B "root N >RN"
.B "root \-r3 N >R3N"
.B "root \-r1.5 N >R1.5N"
.B "plot \-FN,g N R1.5N RN R3N | td"
.DE
The resulting plot is shown in Figure 3.
.P
.VL 2i .5i
.LI "\fBtitle \-v~\fIname\fR~ "
\fITitle\fR associates a \fIname\fR with a vector.
In this case, \fBfirst ten integers\fR is associated with
the vector output by \fIgas\fR.
The vector is stored in file \fBN\fR.
.LI "\fBroot \-r\fIn\fP"
\fIRoot\fR outputs the \fIn\fR\|th root of each element on the input.
If \fB\-r\fIn\fR is not given then the square root is output.
Also, if the input is a titled vector the title will be transformed to
reflect the root function.
.LI "\fBplot \-F\fIX\fB,g \fIY(s)\fR"
This command generates a multiline plot with
\fIY(s)\fR plotted versus \fIX\fR.
The \fBg\fR option causes tick marks to appear instead
of grid lines.
.LE
.sp 2
The next example generates a histogram of random numbers.
.DS 1
.B "rand \-n100 | title \-v~100 random numbers~ | qsort | bucket | hist | td"
.DE
The output is shown in Figure 4.
.SK 1
.P
.VL 2i .5i
.LI "\fBrand \-n100\fR"
\fIRand\fR outputs random numbers using \fIrand\fR(3C).
In this case 100 numbers are output in the range 0 to 1.
.LI "\fBqsort\fR"
\fIQsort\fR sorts the elements of a vector in ascending order.
.LI "\fBbucket\fR"
\fIBucket\fR breaks the range of a vector into intervals
and counts how many elements from the vector fall into
each interval.
The output is a vector with odd elements being the interval
boundaries and even elements being the counts.
.LI "\fBhist\fR"
\fIHist\fR builds a histogram based on interval
boundaries and counts.
.LE 1
.H 2 "Drawings Built from Boxes"
There is a large class of drawings composed from
boxes and text.
Examples are structure charts, configuration drawings, and
flow diagrams.
In \fIgraphics\fR the general procedure to construct such
box drawings is the same as that for numerical plotting.
Namely gather and transform the data, build and display the layout.
.P
As an example, consider hierarchy charts.
The command line
.DS 1 1
.B "dtoc | vtoc | td"
.DE
outputs the drawing shown in Figure 5.
.P
\fIDtoc\fR outputs a table of contents that describes a
directory structure (Figure 5a).
The fields from left to right are
level number, directory name, and the number of
ordinary readable files contained in the directory.
\fIVtoc\fR reads a (textual) table of contents and
outputs a visual table of contents, or hierarchy chart.
Input to \fIvtoc\fR consists of
a sequence of entries, each describing a box to be drawn.
An entry consists of
a level number, an optional style field,
a text string to be placed in the box, and
a mark field to appear above the top right hand corner
of the box.
.H 1 "WHERE TO GO FROM HERE"
The best way to learn about
.I graphics
is to log onto a \s-1PWB/UNIX\s+1 system and
use it.
Tutorials exist for \fIstat\fR(1) and \fIged\fR(1).
[2] contains administrative information for \fIgraphics\fR.
Reference information can be found
in the \s-1PWB/UNIX\s+1 User's Manual under the
following manual pages:
.DS 1
\fIged\fR(1), the graphical editor;
\fIgps\fR(5), a description of a graphical primitive string;
\fIgraphics\fR(1), the entry point for \fIgraphics\fR;
\fIgutil\fR(1), a collection of utility commands;
\fIstat\fR(1), numerical manipulation and plotting commands;
\fItek4000\fR(1), a collection of commands to manipulate Tektronix 4000 series terminals; and
\fItoc\fR(1), routines to build tables of contents.
.DE
.H 1 "REFERENCES"
.RL
.LI
.I "PWB/UNIX User's Manual"
\*-Release 2.0.,
Bell Laboratories, 1979.
.LI
R. L. Chen and D. E. Pinkston,
.I "Administrative Information for PWB/Graphics,"
Bell Laboratories Memorandum, 1979.
.LE
.sp
.I "January 1980"
.SK