aboutsummaryrefslogtreecommitdiff
path: root/man/man1/pic.1
blob: 685de68fca396de6e1def74ac45c995e2567a4f2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
.TH PIC 1
.de PS	\" start picture
.	\" $1 is height, $2 is width, both in inches
.if \\$1>0 .sp .35
.ie \\$1>0 .nr $1 \\$1
.el .nr $1 0
.in (\\n(.lu-\\$2)/2u
.ne \\$1
..
.de PE	\" end of picture
.in
.if \\n($1>0 .sp .65
..
.SH NAME
pic, tpic \- troff and tex preprocessors for drawing pictures
.SH SYNOPSIS
.B pic
[
.I files
]
.PP
.B tpic
[
.I files
]
.SH DESCRIPTION
.I Pic
is a
.IR troff (1)
preprocessor for drawing figures on a typesetter.
.I Pic
code is contained between
.B .PS
and
.B .PE
lines:
.IP
.EX
\&.PS \f2optional-width\fP \f2optional-height\fP
\f2element-list\fP
\&.PE
.EE
.LP
or in a file mentioned in a
.B .PS
line:
.IP
.BI .PS " " < file
.LP
If
.IR 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
.IR optional-height
is present.
If
.B .PF
is used instead of
.BR .PE ,
the typesetting position after printing is restored to what it was
upon entry.
.PP
An
.IR element-list
is a list of elements:
.EX
	\f2primitive  attribute-list\fP
	\f2placename\fP : \f2element\fP
	\f2placename\fP : \f2position\fP
	\f2var\fP = \f2expr\fP
	\f2direction\fP
	{ \f2element-list\fP }
	[ \f2element-list\fP ]
	for \f2var\fP = \f2expr\fP to \f2expr\fP by \f2expr\fP do { \f2anything\fP }
	if \f2expr\fP then { \f2anything\fP } else { \f2anything\fP }
	copy \f2file,\fP  copy thru \f2macro,\fP  copy \f2file\fP thru \fPmacro\fP
	sh { \f2commandline\fP }
	print \f2expr\fP
	reset \f2optional var-list\fP
	\f2troff-command\fP
.EE
.PP
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
.BI #
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.
.PP
After each primitive
the current position moves in the current direction
.RB ( up , down ,
.BR left , right
(default)) by the size of the primitive.
The current position and direction are saved upon entry
to a
.BR { ... }
block and restored upon exit.
Elements within a block enclosed in
.BR [ ... ]
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.
.PP
.IR 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.
.PP
The
.I primitive
objects are:
.br
.EX
	box  circle  ellipse  arc  line  arrow  spline  move  \f2text-list\fP
.EE
.L arrow
is a synonym for
.LR "line ->" .
.PP
An
.IR attribute-list
is a sequence of zero or more attributes;
each attribute consists of a keyword, perhaps followed by a value.
.EX
.ta .5i 2.5i
	h(eigh)t \f2expr\fP	wid(th) \f2expr\fP
	rad(ius) \f2expr\fP	diam(eter) \f2expr\fP
	up \f2opt-expr\fP	down \f2opt-expr\fP
	right \f2opt-expr\fP	left \f2opt-expr\fP
	from \f2position\fP	to \f2position\fP
	at \f2position\fP	with \f2corner\fP
	by \f2expr, expr\fP	then
	dotted \f2opt-expr\fP	dashed \f2opt-expr\fP
	chop \f2opt-expr\fP	->  <-  <->
	invis	same
	fill \f2opt-expr\fP
	\f2text-list\fP	\f2expr\fP
.EE
Missing attributes and values are filled in from defaults.
Not all attributes make sense for all primitives;
irrelevant ones are silently ignored.
The attribute
.L at
causes the geometrical center to be put at the specified place;
.L with
causes the position on the object to be put at the specified place.
For lines, splines and arcs,
.L height
and
.L width
refer to arrowhead size.
A bare
.I expr
implies motion in the current direction.
.PP
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:
.EX
\f2  text-item\fP:
	"..." \f2positioning ...\fP
	sprintf("\f2format\fP", \f2expr\fP, \f2...\fP) \f2positioning ...\fP
\f2  positioning\fP:
	center  ljust  rjust  above  below
.EE
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
.I 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.
.PP
A position is ultimately an
.I x,y
coordinate pair, but it may be specified in other ways.
.EX
\f2  position\fP:
	\f2expr, expr\fP
	\f2place\fP ± \f2expr, expr\fP
	\f2place\fP ± ( \f2expr, expr\fP )
	( \f2position\fP,\f2 position\fP )	\f2x\fP\fR from one, \f2y\fP\fR the other\fP
	\f2expr\fP [\fLof the way\fP] between \f2position\fP and \f2position\fP
	\f2expr\fP < \f2position\fP , \f2position\fP >
	( \f2position\fP )
.EE
.PP
.EX
\f2  place\fP:
	\f2placename\fP \f2optional-corner\fP
	\f2corner\fP of \f2placename\fP
	\f2nth\fP \f2primitive\fP \f2optional-corner\fP
	\f2corner\fP of \f2nth\fP \f2primitive\fP
	Here
.EE
An
.IR optional-corner
is one of the eight compass points
or the center or the start or end of a primitive.
.EX
\f2  optional-corner\fP:
	.n  .e  .w  .s  .ne  .se  .nw  .sw  .c  .start  .end
\f2  corner\fP:
	top  bot  left  right  start  end
.EE
Each object in a picture has an ordinal number;
.IR nth
refers to this.
.EX
\f2  nth\fP:
	\f2n\fPth\f2,     n\fPth last
.EE
.PP
The built-in variables and their default values are:
.EX
.ta .5i 2.5i
	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
.EE
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
.L reset
statement.
Variables changed within
.B [
and
.B ]
revert to their previous value upon exit from the block.
Dimensions are divided by
.B scale
during output.
.PP
Expressions in
.I pic
are evaluated in floating point.
All numbers representing dimensions are taken to be in inches.
.EX
\f2  expr\fP:
	\f2expr\fP \f2op\fP \f2expr\fP
	- \f2expr\fP
	! \f2expr\fP
	( \f2expr\fP )
	variable
	number
	\f2place\fP .x  \f2place\fP .y  \f2place\fP .ht  \f2place\fP .wid  \f2place\fP .rad
	sin(\f2expr\fP)  cos(\f2expr\fP)  atan2(\f2expr,expr\fP)  log(\f2expr\fP)  exp(\f2expr\fP)
	sqrt(\f2expr\fP)  max(\f2expr,expr\fP)  min(\f2expr,expr\fP)  int(\f2expr\fP)  rand()
\f2  op\fP:
	+  -  *  /  %  <  <=  >  >=  ==  !=  &&  ||
.EE
.PP
The
.B define
and
.B undef
statements are not part of the grammar.
.EX
	define \f2name\fP { \f2replacement text\fP }
	undef \f2name\fP
.EE
Occurrences of
.BR $1 ,
.BR $2 ,
etc.,
in the replacement text
will be replaced by the corresponding arguments if
.I name
is invoked as
.EX
	\f2name\fP(\f2arg1\fP, \f2arg2\fP, ...)
.EE
Non-existent arguments are replaced by null strings.
Replacement text
may contain newlines.
The
.B undef
statement removes the definition of a macro.
.PP
.I Tpic
is a
.IR tex (1)
preprocessor that accepts
.IR pic
language.
It produces Tex commands that define a box called
.BR \egraph ,
which contains the picture.
The box may be output this way:
.IP
.L
\ecenterline{\ebox\egraph}
.SH EXAMPLES
.EX
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 } 
.EE
.PP
.PS
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 } 
.PE
.SH SOURCE
.B /sys/src/cmd/pic
.SH "SEE ALSO"
.IR grap (1), 
.IR doctype (1),
.IR troff (1)
.br
B. W. Kernighan,
``PIC\(ema Graphics Language for Typesetting'',
.I
Unix Research System Programmer's Manual,
Tenth Edition, Volume 2