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.20.1/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. Use the figname command to change
80 the name of the vbox. You must yourself print that vbox using, for
81 example, the command
82 \centerline{\box\graph}
84 Actually, since the vbox has a height of zero (it is defined with
86 \vtop) this will produce slightly more vertical space above the picture
87 than below it;
88 \centerline{\raise 1em\box\graph}
90 would avoid this.
92 To make the vbox having a positive height and a depth of zero (as used
94 e.g. by LaTeX's graphics.sty), define the following macro in your docu‐
95 ment:
96 \def\gpicbox#1{%
98 \vbox{\unvbox\csname #1\endcsname\kern 0pt}}
99 Now you can simply say \gpicbox{graph} instead of \box\graph.
101 You must use a TeX driver that supports the tpic specials, version 2.
103 Lines beginning with \ are passed through transparently; a % is added
105 to the end of the line to avoid unwanted spaces. You can safely use
106 this feature to change fonts or to change the value of \baselineskip.
107 Anything else may well produce undesirable results; use at your own
108 risk. Lines beginning with a period are not given any special treat‐
109 ment.
110 Commands
112 for variable = expr1 to expr2 [by [*]expr3] do X body X
113 Set variable to expr1. While the value of variable is less than
114 or equal to expr2, do body and increment variable by expr3; if
115 by is not given, increment variable by 1. If expr3 is prefixed
116 by * then variable will instead be multiplied by expr3. The
117 value of expr3 can be negative for the additive case; variable
118 is then tested whether it is greater than or equal to expr2.
119 For the multiplicative case, expr3 must be greater than zero.
120 If the constraints aren't met, the loop isn't executed. X can
121 be any character not occurring in body.
122 if expr then X if-true X [else Y if-false Y]
124 Evaluate expr; if it is non-zero then do if-true, otherwise do
125 if-false. X can be any character not occurring in if-true. Y
126 can be any character not occurring in if-false.
127 print arg...
129 Concatenate the arguments and print as a line on stderr. Each
130 arg must be an expression, a position, or text. This is useful
131 for debugging.
132 command arg...
134 Concatenate the arguments and pass them through as a line to
135 troff or TeX. Each arg must be an expression, a position, or
136 text. This has a similar effect to a line beginning with . or
137 \, but allows the values of variables to be passed through. For
138 example,
139 .PS
141 x = 14
142 command ".ds string x is " x "."
143 .PE
144 \*[string]
145 prints
147 x is 14.
149 sh X command X
151 Pass command to a shell. X can be any character not occurring
152 in command.
153 copy "filename"
155 Include filename at this point in the file.
156 copy ["filename"] thru X body X [until "word"]
158 copy ["filename"] thru macro [until "word"]
159 This construct does body once for each line of filename; the
160 line is split into blank-delimited words, and occurrences of $i
161 in body, for i between 1 and 9, are replaced by the i-th word of
162 the line. If filename is not given, lines are taken from the
163 current input up to .PE. If an until clause is specified, lines
164 will be read only until a line the first word of which is word;
165 that line will then be discarded. X can be any character not
166 occurring in body. For example,
167 .PS
169 copy thru % circle at ($1,$2) % until "END"
170 1 2
171 3 4
172 5 6
173 END
174 box
175 .PE
176 is equivalent to
178 .PS
180 circle at (1,2)
181 circle at (3,4)
182 circle at (5,6)
183 box
184 .PE
185 The commands to be performed for each line can also be taken
187 from a macro defined earlier by giving the name of the macro as
188 the argument to thru.
189 reset
191 reset variable1[,] variable2 ...
192 Reset pre-defined variables variable1, variable2 ... to their
193 default values. If no arguments are given, reset all pre-
194 defined variables to their default values. Note that assigning
195 a value to scale also causes all pre-defined variables that con‐
196 trol dimensions to be reset to their default values times the
197 new value of scale.
198 plot expr ["text"]
200 This is a text object which is constructed by using text as a
201 format string for sprintf with an argument of expr. If text is
202 omitted a format string of "%g" is used. Attributes can be
203 specified in the same way as for a normal text object. Be very
204 careful that you specify an appropriate format string; pic does
205 only very limited checking of the string. This is deprecated in
206 favour of sprintf.
207 variable := expr
209 This is similar to = except variable must already be defined,
210 and expr will be assigned to variable without creating a vari‐
211 able local to the current block. (By contrast, = defines the
212 variable in the current block if it is not already defined
213 there, and then changes the value in the current block only.)
214 For example, the following:
215 .PS
217 x = 3
218 y = 3
219 [
220 x := 5
221 y = 5
222 ]
223 print x " " y
224 .PE
225 prints
227 5 3
229 Arguments of the form
231 X anything X
233 are also allowed to be of the form
235 { anything }
237 In this case anything can contain balanced occurrences of { and }.
239 Strings may contain X or imbalanced occurrences of { and }.
240 Expressions
242 The syntax for expressions has been significantly extended:
243 x ^ y (exponentiation)
245 sin(x)
246 cos(x)
247 atan2(y, x)
248 log(x) (base 10)
249 exp(x) (base 10, ie 10^x)
250 sqrt(x)
251 int(x)
252 rand() (return a random number between 0 and 1)
253 rand(x) (return a random number between 1 and x; deprecated)
254 srand(x) (set the random number seed)
255 max(e1, e2)
256 min(e1, e2)
257 !e
258 e1 && e2
259 e1 || e2
260 e1 == e2
261 e1 != e2
262 e1 >= e2
263 e1 > e2
264 e1 <= e2
265 e1 < e2
266 "str1" == "str2"
267 "str1" != "str2"
268 String comparison expressions must be parenthesised in some contexts to
270 avoid ambiguity.
271 Other Changes
273 A bare expression, expr, is acceptable as an attribute; it is equiva‐
274 lent to dir expr, where dir is the current direction. For example
275 line 2i
277 means draw a line 2 inches long in the current direction. The `i' (or
279 `I') character is ignored; to use another measurement unit, set the
280 scale variable to an appropriate value.
281 The maximum width and height of the picture are taken from the vari‐
283 ables maxpswid and maxpsht. Initially these have values 8.5 and 11.
284 Scientific notation is allowed for numbers. For example
286 x = 5e-2
288 Text attributes can be compounded. For example,
290 "foo" above ljust
292 is valid.
294 There is no limit to the depth to which blocks can be examined. For
296 example,
297 [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
299 circle at last [].A.B.C
300 is acceptable.
302 Arcs now have compass points determined by the circle of which the arc
304 is a part.
305 Circles, ellipses, and arcs can be dotted or dashed. In TeX mode
307 splines can be dotted or dashed also.
308 Boxes can have rounded corners. The rad attribute specifies the radius
310 of the quarter-circles at each corner. If no rad or diam attribute is
311 given, a radius of boxrad is used. Initially, boxrad has a value of 0.
312 A box with rounded corners can be dotted or dashed.
313 Boxes can have slanted sides. This effectively changes the shape of a
315 box from a rectangle to an arbitrary parallelogram. The xslanted and
316 yslanted attributes specify the x and y offset of the box's upper right
317 corner from its default position.
318 The .PS line can have a second argument specifying a maximum height for
320 the picture. If the width of zero is specified the width will be
321 ignored in computing the scaling factor for the picture. Note that GNU
322 pic will always scale a picture by the same amount vertically as well
323 as horizontally. This is different from the DWB 2.0 pic which may
324 scale a picture by a different amount vertically than horizontally if a
325 height is specified.
326 Each text object has an invisible box associated with it. The compass
328 points of a text object are determined by this box. The implicit
329 motion associated with the object is also determined by this box. The
330 dimensions of this box are taken from the width and height attributes;
331 if the width attribute is not supplied then the width will be taken to
332 be textwid; if the height attribute is not supplied then the height
333 will be taken to be the number of text strings associated with the
334 object times textht. Initially textwid and textht have a value of 0.
335 In (almost all) places where a quoted text string can be used, an
337 expression of the form
338 sprintf("format", arg,...)
340 can also be used; this will produce the arguments formatted according
342 to format, which should be a string as described in printf(3) appropri‐
343 ate for the number of arguments supplied.
344 The thickness of the lines used to draw objects is controlled by the
346 linethick variable. This gives the thickness of lines in points. A
347 negative value means use the default thickness: in TeX output mode,
348 this means use a thickness of 8 milliinches; in TeX output mode with
349 the -c option, this means use the line thickness specified by .ps
350 lines; in troff output mode, this means use a thickness proportional to
351 the pointsize. A zero value means draw the thinnest possible line sup‐
352 ported by the output device. Initially it has a value of -1. There is
353 also a thick[ness] attribute. For example,
354 circle thickness 1.5
356 would draw a circle using a line with a thickness of 1.5 points. The
358 thickness of lines is not affected by the value of the scale variable,
359 nor by the width or height given in the .PS line.
360 Boxes (including boxes with rounded corners or slanted sides), circles
362 and ellipses can be filled by giving them an attribute of fill[ed].
363 This takes an optional argument of an expression with a value between 0
364 and 1; 0 will fill it with white, 1 with black, values in between with
365 a proportionally gray shade. A value greater than 1 can also be used:
366 this means fill with the shade of gray that is currently being used for
367 text and lines. Normally this will be black, but output devices may
368 provide a mechanism for changing this. Without an argument, then the
369 value of the variable fillval will be used. Initially this has a value
370 of 0.5. The invisible attribute does not affect the filling of
371 objects. Any text associated with a filled object will be added after
372 the object has been filled, so that the text will not be obscured by
373 the filling.
374 Three additional modifiers are available to specify colored objects:
376 outline[d] sets the color of the outline, shaded the fill color, and
377 colo[u]r[ed] sets both. All three keywords expect a suffix specifying
378 the color, for example
379 circle shaded "green" outline "black"
381 Currently, color support isn't available in TeX mode. Predefined color
383 names for groff are in the device macro files, for example ps.tmac;
384 additional colors can be defined with the .defcolor request (see the
385 manual page of troff(1) for more details).
386 To change the name of the vbox in TeX mode, set the pseudo-variable
388 figname (which is actually a specially parsed command) within a pic‐
389 ture. Example:
390 .PS
392 figname = foobar;
393 ...
394 .PE
395 The picture is then available in the box \foobar.
397 pic assumes that at the beginning of a picture both glyph and fill
399 color are set to the default value.
400 Arrow heads will be drawn as solid triangles if the variable arrowhead
402 is non-zero and either TeX mode is enabled or the -n option has not
403 been given. Initially arrowhead has a value of 1. Note that solid
404 arrow heads are always filled with the current outline color.
405 The troff output of pic is device-independent. The -T option is there‐
407 fore redundant. All numbers are taken to be in inches; numbers are
408 never interpreted to be in troff machine units.
409 Objects can have an aligned attribute. This will only work if the
411 postprocessor is grops. Any text associated with an object having the
412 aligned attribute will be rotated about the center of the object so
413 that it is aligned in the direction from the start point to the end
414 point of the object. Note that this attribute will have no effect for
415 objects whose start and end points are coincident.
416 In places where nth is allowed `expr'th is also allowed. Note that 'th
418 is a single token: no space is allowed between the ' and the th. For
419 example,
420 for i = 1 to 4 do {
422 line from `i'th box.nw to `i+1'th box.se
423 }
424
426 To obtain a stand-alone picture from a pic file, enclose your pic code
427 with .PS and .PE requests; roff configuration commands may be added at
428 the beginning of the file, but no roff text.
429 It is necessary to feed this file into groff without adding any page
431 information, so you must check which .PS and .PE requests are actually
432 called. For example, the mm macro package adds a page number, which is
433 very annoying. At the moment, calling standard groff without any macro
434 package works. Alternatively, you can define your own requests, e.g.
435 to do nothing:
436 .de PS
438 ..
439 .de PE
440 ..
441 groff itself does not provide direct conversion into other graphics
443 file formats. But there are lots of possibilities if you first trans‐
444 form your picture into PostScript® format using the groff option -Tps.
445 Since this ps-file lacks BoundingBox information it is not very useful
446 by itself, but it may be fed into other conversion programs, usually
447 named ps2other or pstoother or the like. Moreover, the PostScript
448 interpreter ghostscript (gs) has built-in graphics conversion devices
449 that are called with the option
450 gs -sDEVICE=<devname>
452 Call
454 gs --help
456 for a list of the available devices.
458 As the Encapsulated PostScript File Format EPS is getting more and more
460 important, and the conversion wasn't regarded trivial in the past you
461 might be interested to know that there is a conversion tool named
462 ps2eps which does the right job. It is much better than the tool
463 ps2epsi packaged with gs.
464 For bitmapped graphic formats, you should use pstopnm; the resulting
466 (intermediate) PNM file can be then converted to virtually any graphics
467 format using the tools of the netpbm package .
468
470 /usr/share/groff/1.20.1/tmac/pic.tmac
471 Example definitions of the PS and PE macros.
472
474 troff(1), groff_out(5), tex(1), gs(1), ps2eps(1), pstopnm(1),
475 ps2epsi(1), pnm(5)
476 Tpic: Pic for TeX
478 Brian W. Kernighan, PIC — A Graphics Language for Typesetting (User
480 Manual). AT&T Bell Laboratories, Computing Science Technical Report
481 No. 116 <http://cm.bell-labs.com/cm/cs/cstr/116.ps.gz> (revised May,
482 1991).
483 ps2eps is available from CTAN mirrors, e.g.
485 <ftp://ftp.dante.de/tex-archive/support/ps2eps/>
486 W. Richard Stevens - Turning PIC Into HTML
488 <http://www.kohala.com/start/troff/pic2html.html>
489 W. Richard Stevens - Examples of picMacros
491 <http://www.kohala.com/start/troff/pic.examples.ps>
492
494 Input characters that are invalid for groff (i.e., those with ASCII
495 code 0, or 013 octal, or between 015 and 037 octal, or between 0200 and
496 0237 octal) are rejected even in TeX mode.
497 The interpretation of fillval is incompatible with the pic in 10th edi‐
499 tion Unix, which interprets 0 as black and 1 as white.
500 PostScript® is a registered trademark of Adobe Systems Incorporation.
502Groff Version 1.20.1 9 January 2009 PIC(1)