[Chapter 16] 16.3 Pic

16.3 Pic

Pic is a graphics language program that facilitates the drawing of simple flowcharts and diagrams. Pic offers dozens of ways to draw a picture, not only because of the many abbreviations it allows, but because pic tries to combine the language of geometry with English. For example, you can specify a line by its direction, magnitude, and starting point, yet you can often achieve the same effect by simply stating, "from there to there ."

Pic has the following command-line syntax:

/usr/ucb/pic [files ]

Full descriptions of primitive objects in pic can be ended by starting another line, or by the semicolon character (;). A single primitive description can be continued on the next line, however, by ending the first with a backslash character (\). Comments may be placed on lines beginning with the pound sign (#).

16.3.1 Pic Macros

`.PS` [`h` [`w` ]]	Start pic description. `h` and `w` , if specified, are the desired height and width of the picture; the full picture will be made to expand or contract to fill this space.
`.PS` < `file`	Read contents of `file` in place of current line.
.PE	End pic description.
.PF	End pic description and return to vertical position before matching `PS` .
.`xx`	Troff request (or macro) `xx` .

16.3.2 Declarations

At the beginning of a pic description, you may declare a new scale, and declare any number of variables. Pic assumes you want a 1-to-1 scale, where units are inches by default. You can declare a different scale, say 1 = one-n th of an inch, by declaring:

scale = 

n

Pic takes variable substitutions for numbers used in the description. Instead of:

line right 

n

you may use a lowercase character as a variable, for example a , by declaring at the top of the description:

a = 

n

You may then write:

line right a

16.3.3 Primitives

Pic recognizes several basic graphical objects, or primitives. These primitives are specified by the following keywords:

arc      circle    move
arrow    ellipse   spline
box      line      "

text

"

16.3.3.1 Syntax

Primitives may be followed by relevant options. Options are discussed later in this section.

arc [cw] [options ] ["text "]: A fraction of a circle (default is 1/4 of a circle). The cw option specifies a clockwise arc; default is counter-clockwise.
arrow [options ] ["text "]: Draw an arrow. Essentially the same as line -> .
box [options ] ["text "]: Draw a box.
circle [options ] ["text "]: Draw a circle.
ellipse [options ] ["text "]: Draw an ellipse.
line [options ] ["text "]: Draw a line.
move [options ] ["text "]: A move of position in the drawing. Essentially, an invisible line.
spline [options ] ["text "]: A line, with the feature that a then option results in a gradual (sloped) change in direction.
"text ": Text centered at current point.

16.3.4 Options

The options below are grouped by function. Note that at , with , and from specify points. Points may be expressed as Cartesian coordinates or with respect to previous objects.

right [n ]
left [n ]
up [n ]
down [n ]: The direction of the primitive; default is the direction in which the previous description had been heading. Create diagonal motion by using two directions on the option line. Each direction can be followed by a specified length n .
rad n
diam n: Create the primitive using radius or diameter n .
ht n
wid n: Create the primitive using height or width n . For an arrow, line, or spline, height and width refer to arrowhead size.
same: Create the primitive using the same dimensions specified for the most recent matching primitive.
at point: Center the primitive at point .
with . position at point: Designate the position of the primitive to be at point .
from point1 to point2: Draw the primitive from point1 to point2 .
->: Direct the arrowhead forward.
<-: Direct the arrowhead backward.
<->: Direct the arrowhead both ways.
chop n m: Chop off n from beginning of primitive, and m from end. With only one argument, the same value will be chopped from both ends.
dotted
dashed
invis: Draw the primitive using lines that are dotted, dashed, or invisible. (An invisible object still occupies space in the output.) Default is solid line.
then ...: Continue primitive in a new direction. Relevant only to lines, splines, moves, and arrows. Can be placed before or after any text.

16.3.5 Text

Text must be placed within quotes. To break the line, break into two (or more) sets of quotes. Text always appears centered within the object, unless given one of the following arguments:

ljust: Text appears flush left, vertically centered.
rjust: Text appears flush right, vertically centered.
above: Text appears above the center.
below: Text appears below the center.

16.3.6 Object Blocks

Several primitives can be combined to make a complex object (for example, an octagon). This complex object can be treated as a single object by declaring it as a block:

Object: [
     

description


      .
      .
      .
]

Brackets are used as delimiters. Note that the object is declared as a proper noun, hence should begin with a capital letter.

16.3.7 Macros

The same sequence of commands can be repeated by using macros. The syntax is:

define 

sequence

 %
      

description


          .
          .
          . 
      %

Here we used the percent sign (%) as the delimiter, but you can use any character that isn't in the description.

Macros can take variables, expressed in the definition as $1 through $9 . Invoke the macro with the syntax:



sequence

(

value1

,

value2

,

...

)

16.3.8 Positioning

In a pic description, the first action begins at (0,0) unless otherwise specified with coordinates. Thus, as objects are placed above and left of the first object, the point (0,0) moves down and right on the drawing.

All points are ultimately translated by the formatter into x- and y-coordinates. You may therefore refer to a specific point in the picture by incrementing or decrementing the coordinates. For example:

2nd ellipse - (3,1)

You may refer to the x- and y-coordinates of an object by placing .x or .y at the end. For example:

last box.x

refers to the x-coordinate of the most recent box drawn. You can refer to some of the object's physical attributes in a similar way:

.x: x-coordinate of object's center.
.y: y-coordinate of object's center.
.ht: Height of object.
.wid: Width of object.
.rad: Radius of object.

Unless otherwise positioned, each object begins at the point where the last object left off. However, if a command (or sequence of commands) is set off by curly braces ({ }), pic then returns to the position before the first brace.

16.3.8.1 Positioning Between Objects

To refer to a previous object, use proper names. This can be done two ways:

By referring to it by order. For example:
```
1st box 
3rd box 
last box 
2nd last box
```
By declaring it with a name, in initial caps, on its declaration line. For example:
```
Line1: line 1.5 right from last box.sw
```

To refer to a point between two objects, or between two points on the same object, you may write:



fraction



 of the way between



 first.position



 and 



second.position

or (abbreviated):



fraction



<



first.position



,



second.position



>

16.3.8.2 Corners

When you refer to a previous object, pic assumes you mean the object's center unless you specify a corner. To specify a corner, use either of these forms:



.



corner 



of 



object




object



.



corner

For example:



.sw of last box
last box.sw

Valid corners can be specified as any of the following:

n	North
s	South
e	East
w	West
ne	Northeast
nw	Northwest
se	Southeast
sw	Southwest
t	Top (same as `n` )
b	Bottom (same as `s` )
r	Right (same as `e` )
l	Left (same as `w` )
start	Point where drawing of object began
end	Point where drawing of object ended

You may also refer to the following parts of an object:

upper right        lower right 
upper left         lower left

16.3.9 Arithmetic Operators

Pic recognizes the operators below:

+	Addition.
-	Subtraction.
*	Multiplication.
/	Division
%	Modulus (remainder after division).

16.3.10 Default Values

The default dimensions of objects are controlled by various system variables. You can change these defaults by typing a description line of the form:



variable

 = 

value

Variable	Default	Variable	Default
arcrad	0.25	ellipsewid	0.75
arrowwid	0.05	linewid	0.5
arrowht	0.1	lineht	0.5
boxwid	0.75	movewid	0.5
boxht	0.5	moveht	0.5
circlerad	0.25	scale	1
dashwid	0.05	textht	0
ellipseht	0.5	textwid	0

16.3.11 A Pic Example

Input:

.PS
define smile %
a = $1
circle radius a at 0,0
arc cw radius a*.75 from a*.5,-a*.25 to -a*.5,-a*.25
"\(bu" at a*.33,a*.25
"\(bu" at a*-.33,a*.25
%
smile(.5)
.PE

Result: Figure 16.0