1PIC(1) General Commands Manual PIC(1)
2
6 pic - compile pictures for troff or TeX
7
9 pic [-nvCSU] [file ...]
10 pic -t [-cvzCSU] [file ...]
12
14 This manual page describes the GNU version of pic, which is part of the
15 groff document formatting system. pic compiles descriptions of pic‐
16 tures embedded within troff or TeX input files into commands that are
17 understood by TeX or troff. Each picture starts with a line beginning
18 with .PS and ends with a line beginning with .PE. Anything outside of
19 .PS and .PE is passed through without change.
20 It is the user's responsibility to provide appropriate definitions of
22 the PS and PE macros. When the macro package being used does not sup‐
23 ply such definitions (for example, old versions of -ms), appropriate
24 definitions can be obtained with -mpic: These will center each picture.
25
27 Options that do not take arguments may be grouped behind a single -.
28 The special option -- can be used to mark the end of the options. A
29 filename of - refers to the standard input.
30 -C Recognize .PS and .PE even when followed by a character other
32 than space or newline.
33 -S Safer mode; do not execute sh commands. This can be useful when
35 operating on untrustworthy input (enabled by default).
36 -U Unsafe mode; revert the default option -S.
38 -n Don't use the groff extensions to the troff drawing commands.
40 You should use this if you are using a postprocessor that
41 doesn't support these extensions. The extensions are described
42 in groff_out(5). The -n option also causes pic not to use zero-
43 length lines to draw dots in troff mode.
44 -t TeX mode.
46 -c Be more compatible with tpic. Implies -t. Lines beginning with
48 \ are not passed through transparently. Lines beginning with .
49 are passed through with the initial . changed to \. A line be‐
50 ginning with .ps is given special treatment: it takes an op‐
51 tional integer argument specifying the line thickness (pen size)
52 in milliinches; a missing argument restores the previous line
53 thickness; the default line thickness is 8 milliinches. The
54 line thickness thus specified takes effect only when a non-nega‐
55 tive line thickness has not been specified by use of the thick‐
56 ness attribute or by setting the linethick variable.
57 -v Print the version number.
59 -z In TeX mode draw dots using zero-length lines.
61 The following options supported by other versions of pic are ignored:
63 -D Draw all lines using the \D escape sequence. pic always does
65 this.
66 -T dev Generate output for the troff device dev. This is unnecessary
68 because the troff output generated by pic is device-independent.
69
71 This section describes only the differences between GNU pic and the
72 original version of pic. Many of these differences also apply to newer
73 versions of Unix pic. A complete documentation is available in the
74 file
75 /usr/share/doc/groff/pic.ms
77 TeX mode
79 TeX mode is enabled by the -t option. In TeX mode, pic will define a
80 vbox called \graph for each picture. Use the figname command to change
81 the name of the vbox. You must yourself print that vbox using, for ex‐
82 ample, the command
83 \centerline{\box\graph}
85 Actually, since the vbox has a height of zero (it is defined with
87 \vtop) this will produce slightly more vertical space above the picture
88 than below it;
89 \centerline{\raise 1em\box\graph}
91 would avoid this.
93 To make the vbox having a positive height and a depth of zero (as used
95 e.g. by LaTeX's graphics.sty), define the following macro in your docu‐
96 ment:
97 \def\gpicbox#1{%
99 \vbox{\unvbox\csname #1\endcsname\kern 0pt}}
100 Now you can simply say \gpicbox{graph} instead of \box\graph.
102 You must use a TeX driver that supports the tpic specials, version 2.
104 Lines beginning with \ are passed through transparently; a % is added
106 to the end of the line to avoid unwanted spaces. You can safely use
107 this feature to change fonts or to change the value of \baselineskip.
108 Anything else may well produce undesirable results; use at your own
109 risk. Lines beginning with a period are not given any special treat‐
110 ment.
111 Commands
113 for variable = expr1 to expr2 [by [*]expr3] do X body X
114 Set variable to expr1. While the value of variable is less than
115 or equal to expr2, do body and increment variable by expr3; if
116 by is not given, increment variable by 1. If expr3 is prefixed
117 by * then variable will instead be multiplied by expr3. The
118 value of expr3 can be negative for the additive case; variable
119 is then tested whether it is greater than or equal to expr2.
120 For the multiplicative case, expr3 must be greater than zero.
121 If the constraints aren't met, the loop isn't executed. X can
122 be any character not occurring in body.
123 if expr then X if-true X [else Y if-false Y]
125 Evaluate expr; if it is non-zero then do if-true, otherwise do
126 if-false. X can be any character not occurring in if-true. Y
127 can be any character not occurring in if-false.
128 print arg...
130 Concatenate the arguments and print as a line on stderr. Each
131 arg must be an expression, a position, or text. This is useful
132 for debugging.
133 command arg...
135 Concatenate the arguments and pass them through as a line to
136 troff or TeX. Each arg must be an expression, a position, or
137 text. This has a similar effect to a line beginning with . or
138 \, but allows the values of variables to be passed through. For
139 example,
140 .PS
142 x = 14
143 command ".ds string x is " x "."
144 .PE
145 \*[string]
146 prints
148 x is 14.
150 sh X command X
152 Pass command to a shell. X can be any character not occurring
153 in command.
154 copy "filename"
156 Include filename at this point in the file.
157 copy ["filename"] thru X body X [until "word"]
159 copy ["filename"] thru macro [until "word"]
160 This construct does body once for each line of filename; the
161 line is split into blank-delimited words, and occurrences of $i
162 in body, for i between 1 and 9, are replaced by the i-th word of
163 the line. If filename is not given, lines are taken from the
164 current input up to .PE. If an until clause is specified, lines
165 will be read only until a line the first word of which is word;
166 that line will then be discarded. X can be any character not
167 occurring in body. For example,
168 .PS
170 copy thru % circle at ($1,$2) % until "END"
171 1 2
172 3 4
173 5 6
174 END
175 box
176 .PE
177 is equivalent to
179 .PS
181 circle at (1,2)
182 circle at (3,4)
183 circle at (5,6)
184 box
185 .PE
186 The commands to be performed for each line can also be taken
188 from a macro defined earlier by giving the name of the macro as
189 the argument to thru.
190 reset
192 reset variable1[,] variable2 ...
193 Reset pre-defined variables variable1, variable2 ... to their
194 default values. If no arguments are given, reset all pre-de‐
195 fined variables to their default values. Note that assigning a
196 value to scale also causes all pre-defined variables that con‐
197 trol dimensions to be reset to their default values times the
198 new value of scale.
199 plot expr ["text"]
201 This is a text object which is constructed by using text as a
202 format string for sprintf with an argument of expr. If text is
203 omitted a format string of "%g" is used. Attributes can be
204 specified in the same way as for a normal text object. Be very
205 careful that you specify an appropriate format string; pic does
206 only very limited checking of the string. This is deprecated in
207 favour of sprintf.
208 variable := expr
210 This is similar to = except variable must already be defined,
211 and expr will be assigned to variable without creating a vari‐
212 able local to the current block. (By contrast, = defines the
213 variable in the current block if it is not already defined
214 there, and then changes the value in the current block only.)
215 For example, the following:
216 .PS
218 x = 3
219 y = 3
220 [
221 x := 5
222 y = 5
223 ]
224 print x " " y
225 .PE
226 prints
228 5 3
230 Arguments of the form
232 X anything X
234 are also allowed to be of the form
236 { anything }
238 In this case anything can contain balanced occurrences of { and }.
240 Strings may contain X or imbalanced occurrences of { and }.
241 Expressions
243 The syntax for expressions has been significantly extended:
244 x ^ y (exponentiation)
246 sin(x)
247 cos(x)
248 atan2(y, x)
249 log(x) (base 10)
250 exp(x) (base 10, i.e. 10^x)
251 sqrt(x)
252 int(x)
253 rand() (return a random number between 0 and 1)
254 rand(x) (return a random number between 1 and x; deprecated)
255 srand(x) (set the random number seed)
256 max(e1, e2)
257 min(e1, e2)
258 !e
259 e1 && e2
260 e1 || e2
261 e1 == e2
262 e1 != e2
263 e1 >= e2
264 e1 > e2
265 e1 <= e2
266 e1 < e2
267 "str1" == "str2"
268 "str1" != "str2"
269 String comparison expressions must be parenthesised in some contexts to
271 avoid ambiguity.
272 Other Changes
274 A bare expression, expr, is acceptable as an attribute; it is equiva‐
275 lent to dir expr, where dir is the current direction. For example
276 line 2i
278 means draw a line 2 inches long in the current direction. The ‘i’ (or
280 ‘I’) character is ignored; to use another measurement unit, set the
281 scale variable to an appropriate value.
282 The maximum width and height of the picture are taken from the vari‐
284 ables maxpswid and maxpsht. Initially these have values 8.5 and 11.
285 Scientific notation is allowed for numbers. For example
287 x = 5e-2
289 Text attributes can be compounded. For example,
291 "foo" above ljust
293 is valid.
295 There is no limit to the depth to which blocks can be examined. For
297 example,
298 [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
300 circle at last [].A.B.C
301 is acceptable.
303 Arcs now have compass points determined by the circle of which the arc
305 is a part.
306 Circles, ellipses, and arcs can be dotted or dashed. In TeX mode
308 splines can be dotted or dashed also.
309 Boxes can have rounded corners. The rad attribute specifies the radius
311 of the quarter-circles at each corner. If no rad or diam attribute is
312 given, a radius of boxrad is used. Initially, boxrad has a value of 0.
313 A box with rounded corners can be dotted or dashed.
314 Boxes can have slanted sides. This effectively changes the shape of a
316 box from a rectangle to an arbitrary parallelogram. The xslanted and
317 yslanted attributes specify the x and y offset of the box's upper right
318 corner from its default position.
319 The .PS line can have a second argument specifying a maximum height for
321 the picture. If the width of zero is specified the width will be ig‐
322 nored in computing the scaling factor for the picture. Note that GNU
323 pic will always scale a picture by the same amount vertically as well
324 as horizontally. This is different from the DWB 2.0 pic which may
325 scale a picture by a different amount vertically than horizontally if a
326 height is specified.
327 Each text object has an invisible box associated with it. The compass
329 points of a text object are determined by this box. The implicit mo‐
330 tion associated with the object is also determined by this box. The
331 dimensions of this box are taken from the width and height attributes;
332 if the width attribute is not supplied then the width will be taken to
333 be textwid; if the height attribute is not supplied then the height
334 will be taken to be the number of text strings associated with the ob‐
335 ject times textht. Initially textwid and textht have a value of 0.
336 In (almost all) places where a quoted text string can be used, an ex‐
338 pression of the form
339 sprintf("format", arg,...)
341 can also be used; this will produce the arguments formatted according
343 to format, which should be a string as described in printf(3) appropri‐
344 ate for the number of arguments supplied.
345 The thickness of the lines used to draw objects is controlled by the
347 linethick variable. This gives the thickness of lines in points. A
348 negative value means use the default thickness: in TeX output mode,
349 this means use a thickness of 8 milliinches; in TeX output mode with
350 the -c option, this means use the line thickness specified by .ps
351 lines; in troff output mode, this means use a thickness proportional to
352 the pointsize. A zero value means draw the thinnest possible line sup‐
353 ported by the output device. Initially it has a value of -1. There is
354 also a thick[ness] attribute. For example,
355 circle thickness 1.5
357 would draw a circle using a line with a thickness of 1.5 points. The
359 thickness of lines is not affected by the value of the scale variable,
360 nor by the width or height given in the .PS line.
361 Boxes (including boxes with rounded corners or slanted sides), circles
363 and ellipses can be filled by giving them an attribute of fill[ed].
364 This takes an optional argument of an expression with a value between 0
365 and 1; 0 will fill it with white, 1 with black, values in between with
366 a proportionally gray shade. A value greater than 1 can also be used:
367 this means fill with the shade of gray that is currently being used for
368 text and lines. Normally this will be black, but output devices may
369 provide a mechanism for changing this. Without an argument, then the
370 value of the variable fillval will be used. Initially this has a value
371 of 0.5. The invisible attribute does not affect the filling of ob‐
372 jects. Any text associated with a filled object will be added after
373 the object has been filled, so that the text will not be obscured by
374 the filling.
375 Three additional modifiers are available to specify colored objects:
377 outline[d] sets the color of the outline, shaded the fill color, and
378 colo[u]r[ed] sets both. All three keywords expect a suffix specifying
379 the color, for example
380 circle shaded "green" outline "black"
382 Currently, color support isn't available in TeX mode. Predefined color
384 names for groff are in the device macro files, for example ps.tmac; ad‐
385 ditional colors can be defined with the .defcolor request (see the man‐
386 ual page of troff(1) for more details).
387 To change the name of the vbox in TeX mode, set the pseudo-variable
389 figname (which is actually a specially parsed command) within a pic‐
390 ture. Example:
391 .PS
393 figname = foobar;
394 ...
395 .PE
396 The picture is then available in the box \foobar.
398 pic assumes that at the beginning of a picture both glyph and fill
400 color are set to the default value.
401 Arrow heads will be drawn as solid triangles if the variable arrowhead
403 is non-zero and either TeX mode is enabled or the -n option has not
404 been given. Initially arrowhead has a value of 1. Note that solid ar‐
405 row heads are always filled with the current outline color.
406 The troff output of pic is device-independent. The -T option is there‐
408 fore redundant. All numbers are taken to be in inches; numbers are
409 never interpreted to be in troff machine units.
410 Objects can have an aligned attribute. This will only work if the
412 postprocessor is grops, or gropdf. Any text associated with an object
413 having the aligned attribute will be rotated about the center of the
414 object so that it is aligned in the direction from the start point to
415 the end point of the object. Note that this attribute will have no ef‐
416 fect for objects whose start and end points are coincident.
417 In places where nth is allowed ‘expr’th is also allowed. Note that ’th
419 is a single token: no space is allowed between the ’ and the th. For
420 example,
421 for i = 1 to 4 do {
423 line from ‘i’th box.nw to ‘i+1’th box.se
424 }
425
427 To obtain a stand-alone picture from a pic file, enclose your pic code
428 with .PS and .PE requests; roff configuration commands may be added at
429 the beginning of the file, but no roff text.
430 It is necessary to feed this file into groff without adding any page
432 information, so you must check which .PS and .PE requests are actually
433 called. For example, the mm macro package adds a page number, which is
434 very annoying. At the moment, calling standard groff without any macro
435 package works. Alternatively, you can define your own requests, e.g.
436 to do nothing:
437 .de PS
439 ..
440 .de PE
441 ..
442 groff itself does not provide direct conversion into other graphics
444 file formats. But there are lots of possibilities if you first trans‐
445 form your picture into PostScript® format using the groff option -Tps.
446 Since this ps-file lacks BoundingBox information it is not very useful
447 by itself, but it may be fed into other conversion programs, usually
448 named ps2other or pstoother or the like. Moreover, the PostScript in‐
449 terpreter ghostscript (gs) has built-in graphics conversion devices
450 that are called with the option
451 gs -sDEVICE=<devname>
453 Call
455 gs --help
457 for a list of the available devices.
459 An alternative may be to use the -Tpdf option to convert your picture
461 directly into PDF format. The MediaBox of the file produced can be
462 controlled by passing a -P-p papersize to groff.
463 As the Encapsulated PostScript File Format EPS is getting more and more
465 important, and the conversion wasn't regarded trivial in the past you
466 might be interested to know that there is a conversion tool named
467 ps2eps which does the right job. It is much better than the tool
468 ps2epsi packaged with gs.
469 For bitmapped graphic formats, you should use pstopnm; the resulting
471 (intermediate) PNM file can be then converted to virtually any graphics
472 format using the tools of the netpbm package.
473
475 /usr/share/groff/1.22.4/tmac/pic.tmac
476 Example definitions of the PS and PE macros.
477
479 troff(1), groff_out(5), tex(1), gs(1), ps2eps(1), pstopnm(1),
480 ps2epsi(1), pnm(5)
481 Eric S. Raymond, Making Pictures With GNU PIC.
483 /usr/share/doc/groff/pic.ps (this file, together with its source file,
484 pic.ms, is part of the groff documentation)
485 Tpic: Pic for TeX
487 Brian W. Kernighan, PIC — A Graphics Language for Typesetting (User
489 Manual) ⟨http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz⟩. AT&T Bell Lab‐
490 oratories, Computing Science Technical Report No. 116 (revised May,
491 1991).
492 ps2eps is available from CTAN mirrors, e.g. ⟨ftp://ftp.dante.de/
494 tex-archive/support/ps2eps/⟩
495 W. Richard Stevens, Turning PIC into HTML ⟨http://www.kohala.com/start/
497 troff/pic2html.html⟩
498 W. Richard Stevens, Examples of pic Macros ⟨http://www.kohala.com/
500 start/troff/pic.examples.ps⟩
501
503 Input characters that are invalid for groff (i.e., those with ASCII
504 code 0, or 013 octal, or between 015 and 037 octal, or between 0200 and
505 0237 octal) are rejected even in TeX mode.
506 The interpretation of fillval is incompatible with the pic in 10th edi‐
508 tion Unix, which interprets 0 as black and 1 as white.
509 PostScript® is a registered trademark of Adobe Systems Incorporation.
511groff 1.22.4 19 January 2023 PIC(1)