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
arrow
is a synonym for
line ->.
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
at
causes the geometrical center to be put at the specified place;
with
causes the position on the object to be put at the specified place.
For lines, splines and arcs,
height
and
width
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
reset
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:
- ecenterline{\box\graph}