PIC(1)

NAME
pic, tpic - troff and tex preprocessors for drawing pictures

SYNOPSIS
pic [ files ]

tpic [ files ]

DESCRIPTION
Pic is a troff(1) preprocessor for drawing figures on a typesetter. Pic code is contained between .PS and .PE lines:

        .PS optional-width optional-height
        element-list
        .PE

or in a file mentioned in a .PS line:

    .PS <file

If optional-width is present, the picture is made that many inches wide, regardless of any dimensions used internally. The height is scaled in the same proportion unless optional-height is present. If .PF is used instead of .PE, the typesetting position after printing is restored to what it was upon entry.

An element-list is a list of elements:
    	primitive  attribute-list
    	placename : element
    	placename : position
    	var = expr
    	direction
    	{ element-list }
    	[ element-list ]
    	for var = expr to expr by expr do { anything }
    	if expr then { anything } else { anything }
    	copy file,  copy thru macro,  copy file thru macro
    	sh { commandline }
    	print expr
    	reset optional var-list
    	troff-command

Elements are separated by newlines or semicolons; a long element may be continued by ending the line with a backslash. Comments are introduced by a # and terminated by a newline. Variable names begin with a lower case letter; place names begin with upper case. Place and variable names retain their values from one picture to the next.

After each primitive the current position moves in the current direction (up,down, left,right (default)) by the size of the primitive. The current position and direction are saved upon entry to a {...} block and restored upon exit. Elements within a block enclosed in [...] are treated as a unit; the dimensions are determined by the extreme points of the contained objects. Names, variables, and direction of motion within a block are local to that block.

Troff-command is any line that begins with a period. Such a line is assumed to make sense in the context where it appears; generally, this means only size and font changes.

The primitive objects are:
    	box  circle  ellipse  arc  line  arrow  spline  move  text-list
is a synonym for

An attribute-list is a sequence of zero or more attributes; each attribute consists of a keyword, perhaps followed by a value.
    	h(eigh)t expr	wid(th) expr
    	rad(ius) expr	diam(eter) expr
    	up opt-expr	down opt-expr
    	right opt-expr	left opt-expr
    	from position	to position
    	at position	with corner
    	by expr, expr	then
    	dotted opt-expr	dashed opt-expr
    	chop opt-expr	->  <-  <->
    	invis	same
    	fill opt-expr
    	text-list	expr
Missing attributes and values are filled in from defaults. Not all attributes make sense for all primitives; irrelevant ones are silently ignored. The attribute causes the geometrical center to be put at the specified place; causes the position on the object to be put at the specified place. For lines, splines and arcs, and refer to arrowhead size. A bare expr implies motion in the current direction.

Text is normally an attribute of some primitive; by default it is placed at the geometrical center of the object. Stand-alone text is also permitted. A text list is a list of text items:
      text-item:
    	"..." positioning ...
    	sprintf("format", expr, ...) positioning ...
      positioning:
    	center  ljust  rjust  above  below
If there are multiple text items for some primitive, they are arranged vertically and centered except as qualified. Positioning requests apply to each item independently. Text items may contain troff commands for size and font changes, local motions, etc., but make sure that these are balanced so that the entering state is restored before exiting.

A position is ultimately an x,y coordinate pair, but it may be specified in other ways.
      position:
    	expr, expr
    	place ± expr, expr
    	place ± ( expr, expr )
    	( position, position )	x from one, y the other
    	expr [of the way] between position and position
    	expr < position , position >
    	( position )

      place:
    	placename optional-corner
    	corner of placename
    	nth primitive optional-corner
    	corner of nth primitive
    	Here
An optional-corner is one of the eight compass points or the center or the start or end of a primitive.
      optional-corner:
    	.n  .e  .w  .s  .ne  .se  .nw  .sw  .c  .start  .end
      corner:
    	top  bot  left  right  start  end
Each object in a picture has an ordinal number; nth refers to this.
      nth:
    	nth,     nth last

The built-in variables and their default values are:
    	boxwid 0.75	boxht 0.5
    	circlerad 0.25	arcrad 0.25
    	ellipsewid 0.75	ellipseht 0.5
    	linewid 0.5	lineht 0.5
    	movewid 0.5	moveht 0.5
    	textwid 0	textht 0
    	arrowwid 0.05	arrowht 0.1
    	dashwid 0.1	arrowhead 2
    	scale 1
These may be changed at any time, and the new values remain in force from picture to picture until changed again or reset by a statement. Variables changed within [ and ] revert to their previous value upon exit from the block. Dimensions are divided by scale during output.

Expressions in pic are evaluated in floating point. All numbers representing dimensions are taken to be in inches.
      expr:
    	expr op expr
    	- expr
    	! expr
    	( expr )
    	variable
    	number
    	place .x  place .y  place .ht  place .wid  place .rad
    	sin(expr)  cos(expr)  atan2(expr,expr)  log(expr)  exp(expr)
    	sqrt(expr)  max(expr,expr)  min(expr,expr)  int(expr)  rand()
      op:
    	+  -  *  /  %  <  <=  >  >=  ==  !=  &&  ||

The define and undef statements are not part of the grammar.
    	define name { replacement text }
    	undef name
Occurrences of $1, $2, etc., in the replacement text will be replaced by the corresponding arguments if name is invoked as
    	name(arg1, arg2, ...)
Non-existent arguments are replaced by null strings. Replacement text may contain newlines. The undef statement removes the definition of a macro.

Tpic is a tex(1) preprocessor that accepts pic language. It produces Tex commands that define a box called \graph, which contains the picture. The box may be output this way:

    \centerline{\box\graph}

EXAMPLES
    arrow "input" above; box "process"; arrow "output" above
    move
    A: ellipse
       circle rad .1 with .w at A.e
       circle rad .05 at 0.5 <A.c, A.ne>
       circle rad .065 at 0.5 <A.c, A.ne>
       spline from last circle.nw left .25 then left .05 down .05
       arc from A.c to A.se rad 0.5
       for i = 1 to 10 do { line from A.s+.025*i,.01*i down i/50 }

SOURCE
/usr/local/plan9/src/cmd/pic

SEE ALSO
grap(1), doctype(1), troff(1)
B. W. Kernighan, ``PIC—a Graphics Language for Typesetting'', Unix Research System Programmer's Manual, Tenth Edition, Volume 2