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