1PIC(1) General Commands Manual PIC(1)
2
6 pic - compile pictures for troff or TeX
7
9 pic [ -nvCSU ] [ filename ... ]
10 pic -t [ -cvzCSU ] [ filename ... ]
11
13 This manual page describes the GNU version of pic, which is part of the
14 groff document formatting system. pic compiles descriptions of pic‐
15 tures embedded within troff or TeX input files into commands that are
16 understood by TeX or troff. Each picture starts with a line beginning
17 with .PS and ends with a line beginning with .PE. Anything outside of
18 .PS and .PE is passed through without change.
19 It is the user's responsibility to provide appropriate definitions of
21 the PS and PE macros. When the macro package being used does not sup‐
22 ply such definitions (for example, old versions of -ms), appropriate
23 definitions can be obtained with -mpic: these will center each picture.
24
26 Options that do not take arguments may be grouped behind a single -.
27 The special option -- can be used to mark the end of the options. A
28 filename of - refers to the standard input.
29 -C Recognize .PS and .PE even when followed by a character other
31 than space or newline.
32 -S Safer mode; do not execute sh commands. This can be useful when
34 operating on untrustworthy input. (enabled by default)
35 -U Unsafe mode; revert the default option -S.
37 -n Don't use the groff extensions to the troff drawing commands.
39 You should use this if you are using a postprocessor that
40 doesn't support these extensions. The extensions are described
41 in groff_out(5). The -n option also causes pic not to use zero-
42 length lines to draw dots in troff mode.
43 -t TeX mode.
45 -c Be more compatible with tpic. Implies -t. Lines beginning with
47 \ are not passed through transparently. Lines beginning with .
48 are passed through with the initial . changed to \. A line
49 beginning with .ps is given special treatment: it takes an
50 optional integer argument specifying the line thickness (pen
51 size) in milliinches; a missing argument restores the previous
52 line thickness; the default line thickness is 8 milliinches.
53 The line thickness thus specified takes effect only when a non-
54 negative line thickness has not been specified by use of the
55 thickness attribute or by setting the linethick variable.
56 -v Print the version number.
58 -z In TeX mode draw dots using zero-length lines.
60 The following options supported by other versions of pic are ignored:
62 -D Draw all lines using the \D escape sequence. pic always does
64 this.
65 -T dev Generate output for the troff device dev. This is unnecessary
67 because the troff output generated by pic is device-independent.
68
70 This section describes only the differences between GNU pic and the
71 original version of pic. Many of these differences also apply to newer
72 versions of Unix pic. A complete documentation is available in the
73 file
74 /usr/share/doc/groff/1.18.1.4/pic.ms
76 TeX mode
78 TeX mode is enabled by the -t option. In TeX mode, pic will define a
79 vbox called \graph for each picture. You must yourself print that vbox
80 using, for example, the command
81 \centerline{\box\graph}
83 Actually, since the vbox has a height of zero this will produce
85 slightly more vertical space above the picture than below it;
86 \centerline{\raise 1em\box\graph}
88 would avoid this.
90 You must use a TeX driver that supports the tpic specials, version 2.
92 Lines beginning with \ are passed through transparently; a % is added
94 to the end of the line to avoid unwanted spaces. You can safely use
95 this feature to change fonts or to change the value of \baselineskip.
96 Anything else may well produce undesirable results; use at your own
97 risk. Lines beginning with a period are not given any special treat‐
98 ment.
99 Commands
101 for variable = expr1 to expr2 [by [*]expr3] do X body X
102 Set variable to expr1. While the value of variable is less than
103 or equal to expr2, do body and increment variable by expr3; if
104 by is not given, increment variable by 1. If expr3 is prefixed
105 by * then variable will instead be multiplied by expr3. X can
106 be any character not occurring in body.
107 if expr then X if-true X [else Y if-false Y]
109 Evaluate expr; if it is non-zero then do if-true, otherwise do
110 if-false. X can be any character not occurring in if-true. Y
111 can be any character not occurring in if-false.
112 print arg...
114 Concatenate the arguments and print as a line on stderr. Each
115 arg must be an expression, a position, or text. This is useful
116 for debugging.
117 command arg...
119 Concatenate the arguments and pass them through as a line to
120 troff or TeX. Each arg must be an expression, a position, or
121 text. This has a similar effect to a line beginning with . or
122 \, but allows the values of variables to be passed through.
123 sh X command X
125 Pass command to a shell. X can be any character not occurring
126 in command.
127 copy "filename"
129 Include filename at this point in the file.
130 copy ["filename"] thru X body X [until "word"]
132 copy ["filename"] thru macro [until "word"]
133 This construct does body once for each line of filename; the
134 line is split into blank-delimited words, and occurrences of $i
135 in body, for i between 1 and 9, are replaced by the i-th word of
136 the line. If filename is not given, lines are taken from the
137 current input up to .PE. If an until clause is specified, lines
138 will be read only until a line the first word of which is word;
139 that line will then be discarded. X can be any character not
140 occurring in body. For example,
141 .PS
143 copy thru % circle at ($1,$2) % until "END"
144 1 2
145 3 4
146 5 6
147 END
148 box
149 .PE
150 is equivalent to
152 .PS
154 circle at (1,2)
155 circle at (3,4)
156 circle at (5,6)
157 box
158 .PE
159 The commands to be performed for each line can also be taken
161 from a macro defined earlier by giving the name of the macro as
162 the argument to thru.
163 reset
165 reset variable1[,] variable2 ...
166 Reset pre-defined variables variable1, variable2 ... to their
167 default values. If no arguments are given, reset all pre-
168 defined variables to their default values. Note that assigning
169 a value to scale also causes all pre-defined variables that con‐
170 trol dimensions to be reset to their default values times the
171 new value of scale.
172 plot expr ["text"]
174 This is a text object which is constructed by using text as a
175 format string for sprintf with an argument of expr. If text is
176 omitted a format string of "%g" is used. Attributes can be
177 specified in the same way as for a normal text object. Be very
178 careful that you specify an appropriate format string; pic does
179 only very limited checking of the string. This is deprecated in
180 favour of sprintf.
181 variable := expr
183 This is similar to = except variable must already be defined,
184 and expr will be assigned to variable without creating a vari‐
185 able local to the current block. (By contrast, = defines the
186 variable in the current block if it is not already defined
187 there, and then changes the value in the current block only.)
188 For example, the following:
189 .PS
191 x = 3
192 y = 3
193 [
194 x := 5
195 y = 5
196 ]
197 print x " " y
198 .PE
199 prints 5 3.
201 Arguments of the form
203 X anything X
205 are also allowed to be of the form
207 { anything }
209 In this case anything can contain balanced occurrences of { and }.
211 Strings may contain X or imbalanced occurrences of { and }.
212 Expressions
214 The syntax for expressions has been significantly extended:
215 x ^ y (exponentiation)
217 sin(x)
218 cos(x)
219 atan2(y, x)
220 log(x) (base 10)
221 exp(x) (base 10, ie 10^x)
222 sqrt(x)
223 int(x)
224 rand() (return a random number between 0 and 1)
225 rand(x) (return a random number between 1 and x; deprecated)
226 srand(x) (set the random number seed)
227 max(e1, e2)
228 min(e1, e2)
229 !e
230 e1 && e2
231 e1 || e2
232 e1 == e2
233 e1 != e2
234 e1 >= e2
235 e1 > e2
236 e1 <= e2
237 e1 < e2
238 "str1" == "str2"
239 "str1" != "str2"
240 String comparison expressions must be parenthesised in some contexts to
242 avoid ambiguity.
243 Other Changes
245 A bare expression, expr, is acceptable as an attribute; it is equiva‐
246 lent to dir expr, where dir is the current direction. For example
247 line 2i
249 means draw a line 2 inches long in the current direction. The `i' (or
251 `I') character is ignored; to use another measurement unit, set the
252 scale variable to an appropriate value.
253 The maximum width and height of the picture are taken from the vari‐
255 ables maxpswid and maxpsht. Initially these have values 8.5 and 11.
256 Scientific notation is allowed for numbers. For example
258 x = 5e-2
259 Text attributes can be compounded. For example,
261 "foo" above ljust
262 is legal.
263 There is no limit to the depth to which blocks can be examined. For
265 example,
266 [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
267 circle at last [].A.B.C
268 is acceptable.
269 Arcs now have compass points determined by the circle of which the arc
271 is a part.
272 Circles and arcs can be dotted or dashed. In TeX mode splines can be
274 dotted or dashed.
275 Boxes can have rounded corners. The rad attribute specifies the radius
277 of the quarter-circles at each corner. If no rad or diam attribute is
278 given, a radius of boxrad is used. Initially, boxrad has a value of 0.
279 A box with rounded corners can be dotted or dashed.
280 The .PS line can have a second argument specifying a maximum height for
282 the picture. If the width of zero is specified the width will be
283 ignored in computing the scaling factor for the picture. Note that GNU
284 pic will always scale a picture by the same amount vertically as well
285 as horizontally. This is different from the DWB 2.0 pic which may
286 scale a picture by a different amount vertically than horizontally if a
287 height is specified.
288 Each text object has an invisible box associated with it. The compass
290 points of a text object are determined by this box. The implicit
291 motion associated with the object is also determined by this box. The
292 dimensions of this box are taken from the width and height attributes;
293 if the width attribute is not supplied then the width will be taken to
294 be textwid; if the height attribute is not supplied then the height
295 will be taken to be the number of text strings associated with the
296 object times textht. Initially textwid and textht have a value of 0.
297 In (almost all) places where a quoted text string can be used, an
299 expression of the form
300 sprintf("format", arg,...)
302 can also be used; this will produce the arguments formatted according
304 to format, which should be a string as described in printf(3) appropri‐
305 ate for the number of arguments supplied.
306 The thickness of the lines used to draw objects is controlled by the
308 linethick variable. This gives the thickness of lines in points. A
309 negative value means use the default thickness: in TeX output mode,
310 this means use a thickness of 8 milliinches; in TeX output mode with
311 the -c option, this means use the line thickness specified by .ps
312 lines; in troff output mode, this means use a thickness proportional to
313 the pointsize. A zero value means draw the thinnest possible line sup‐
314 ported by the output device. Initially it has a value of -1. There is
315 also a thick[ness] attribute. For example,
316 circle thickness 1.5
318 would draw a circle using a line with a thickness of 1.5 points. The
320 thickness of lines is not affected by the value of the scale variable,
321 nor by the width or height given in the .PS line.
322 Boxes (including boxes with rounded corners), circles and ellipses can
324 be filled by giving them an attribute of fill[ed]. This takes an
325 optional argument of an expression with a value between 0 and 1; 0 will
326 fill it with white, 1 with black, values in between with a proportion‐
327 ally gray shade. A value greater than 1 can also be used: this means
328 fill with the shade of gray that is currently being used for text and
329 lines. Normally this will be black, but output devices may provide a
330 mechanism for changing this. Without an argument, then the value of
331 the variable fillval will be used. Initially this has a value of 0.5.
332 The invisible attribute does not affect the filling of objects. Any
333 text associated with a filled object will be added after the object has
334 been filled, so that the text will not be obscured by the filling.
335 Three additional modifiers are available to specify colored objects:
337 outline[d] sets the color of the outline, shaded the fill color, and
338 colo[u]r[ed] sets both. All three keywords expect a suffix specifying
339 the color, for example
340 circle shaded "green" outline "black"
342 Currently, color support isn't available in TeX mode. Predefined color
344 names for groff are in the device macro files, for example ps.tmac;
345 additional colors can be defined with the .defcolor request (see the
346 manual page of troff(1) for more details).
347 pic assumes that at the beginning of a picture both glyph and fill
349 color are set to the default value.
350 Arrow heads will be drawn as solid triangles if the variable arrowhead
352 is non-zero and either TeX mode is enabled or the -n option has not
353 been given. Initially arrowhead has a value of 1. Note that solid
354 arrow heads are always filled with the current outline color.
355 The troff output of pic is device-independent. The -T option is there‐
357 fore redundant. All numbers are taken to be in inches; numbers are
358 never interpreted to be in troff machine units.
359 Objects can have an aligned attribute. This will only work if the
361 postprocessor is grops. Any text associated with an object having the
362 aligned attribute will be rotated about the center of the object so
363 that it is aligned in the direction from the start point to the end
364 point of the object. Note that this attribute will have no effect for
365 objects whose start and end points are coincident.
366 In places where nth is allowed `expr'th is also allowed. Note that 'th
368 is a single token: no space is allowed between the ' and the th. For
369 example,
370 for i = 1 to 4 do {
372 line from `i'th box.nw to `i+1'th box.se
373 }
374
376 To obtain a stand-alone picture from a pic file, enclose your pic code
377 with .PS and .PE requests; roff configuration commands may be added at
378 the beginning of the file, but no roff text.
379 It is necessary to feed this file into groff without adding any page
381 information, so you must check which .PS and .PE requests are actually
382 called. For example, the mm macro package adds a page number, which is
383 very annoying. At the moment, calling standard groff without any macro
384 package works. Alternatively, you can define your own requests, e.g.
385 to do nothing:
386 .de PS
388 ..
389 .de PE
390 ..
391 groff itself does not provide direct conversion into other graphics
393 file formats. But there are lots of possibilities if you first trans‐
394 form your picture into PostScript® format using the groff option -Tps.
395 Since this ps-file lacks BoundingBox information it is not very useful
396 by itself, but it may be fed into other conversion programs, usually
397 named ps2other or pstoother or the like. Moreover, the PostScript
398 interpreter ghostscript (gs) has built-in graphics conversion devices
399 that are called with the option
400 gs -sDEVICE=<devname>
402 Call
404 gs --help
405 for a list of the available devices.
407 As the Encapsulated PostScript File Format EPS is getting more and more
409 important, and the conversion wasn't regarded trivial in the past you
410 might be interested to know that there is a conversion tool named
411 ps2eps which does the right job. It is much better than the tool
412 ps2epsi packaged with gs.
413 For bitmapped graphic formats, you should use pstopnm; the resulting
415 (intermediate) PNM file can be then converted to virtually any graphics
416 format using the tools of the netpbm package .
417
419 /usr/share/groff/1.18.1.4/tmac/pic.tmac
420 Example definitions of the PS and PE macros.
421
423 troff(1), groff_out(5), tex(1), gs(1), ps2eps(1), pstopnm(1),
424 ps2epsi(1), pnm(5)
425 Tpic: Pic for TeX
427 Brian W. Kernighan, PIC — A Graphics Language for Typesetting (User
429 Manual). AT&T Bell Laboratories, Computing Science Technical Report
430 No. 116 <http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz> (revised May,
431 1991).
432 ps2eps is available from CTAN mirrors, e.g.
434 <ftp://ftp.dante.de/tex-archive/support/ps2eps/>
435 W. Richard Stevens - Turning PIC Into HTML
437 <http://www.kohala.com/start/troff/pic2html.html>
438 W. Richard Stevens - Examples of picMacros
440 <http://www.kohala.com/start/troff/pic.examples.ps>
441
443 Input characters that are invalid for groff (ie those with ASCII code
444 0, or 013 octal, or between 015 and 037 octal, or between 0200 and 0237
445 octal) are rejected even in TeX mode.
446 The interpretation of fillval is incompatible with the pic in 10th edi‐
448 tion Unix, which interprets 0 as black and 1 as white.
449 PostScript® is a registered trademark of Adobe Systems Incorporation.
451Groff Version 1.18.1.4 20 September 2002 PIC(1)