Penguin
Recent Changes
Annotated edit history of gpic(1) version 4 showing authors affecting page license. View with all changes included.
Rev Author # Line
1 perry 1 PIC
2 !!!PIC
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 USAGE
8 CONVERSION
9 FILES
10 SEE ALSO
11 BUGS
12 ----
13 !!NAME
14
15
16 pic - compile pictures for troff or TeX
17 !!SYNOPSIS
18
19
20 __pic__ [[ __-nvCSU__ ] [[ ''filename'' ... ]__
21 pic -t__ [[ __-cvzCSU__ ] [[ ''filename'' ...
22 ]
23 !!DESCRIPTION
24
25
26 This manual page describes the GNU version of __pic__,
27 which is part of the groff document formatting system.
28 __pic__ compiles descriptions of pictures embedded within
29 __troff__ or TEX input files into commands that are
30 understood by TEX or __troff__. Each picture starts with
31 a line beginning with __.PS__ and ends with a line
32 beginning with __.PE__. Anything outside of __.PS__
33 and __.PE__ is passed through without
34 change.
35
36
37 It is the user's responsibility to provide appropriate
38 definitions of the __PS__ and __PE__ macros. When the
39 macro package being used does not supply such definitions
40 (for example, old versions of -ms), appropriate definitions
41 can be obtained with __-mpic__: these will center each
42 picture.
43 !!OPTIONS
44
45
46 Options that do not take arguments may be grouped behind a
47 single __-__. The special option __--__ can be used to
48 mark the end of the options. A filename of __-__ refers
49 to the standard input.
50
51
52 __-C__
53
54
55 Recognize __.PS__ and __.PE__ even when followed by a
56 character other than space or newline.
57
58
59 __-S__
60
61
62 Safer mode; do not execute __sh__ commands. This can be
63 useful when operating on untrustworthy input. (enabled by
64 default)
65
66
67 __-U__
68
69
70 Unsafe mode; revert the default option
71 __-S__.
72
73
74 __-n__
75
76
77 Don't use the groff extensions to the troff drawing
78 commands. You should use this if you are using a
79 postprocessor that doesn't support these extensions. The
80 extensions are described in groff_out(5). The
81 __-n__ option also causes __pic__ not to use
82 zero-length lines to draw dots in troff mode.
83
84
85 __-t__
86
87
88 TEX mode.
89
90
91 __-c__
92
93
94 Be more compatible with __tpic__. Implies __-t__.
95 Lines beginning with __\__ are not passed through
96 transparently. Lines beginning with __.__ are passed
97 through with the initial __.__ changed to __\__. A
98 line beginning with __.ps__ is given special treatment:
99 it takes an optional integer argument specifying the line
100 thickness (pen size) in milliinches; a missing argument
101 restores the previous line thickness; the default line
102 thickness is 8 milliinches. The line thickness thus
103 specified takes effect only when a non-negative line
104 thickness has not been specified by use of the
105 __thickness__ attribute or by setting the
106 __linethick__ variable.
107
108
109 __-v__
110
111
112 Print the version number.
113
114
115 __-z__
116
117
118 In TEX mode draw dots using zero-length lines.
119
120
121 The following options supported by other versions of
122 __pic__ are ignored:
123
124
125 __-D__
126
127
128 Draw all lines using the D escape sequence. __pic__
129 always does this.
130
131
132 __-T__ ''dev''
133
134
135 Generate output for the __troff__ device ''dev''. This
136 is unnecessary because the __troff__ output generated by
137 __pic__ is device-independent.
138 !!USAGE
139
140
141 This section describes only the differences between GNU
142 __pic__ and the original version of __pic__. Many of
143 these differences also apply to newer versions of Unix
144 __pic__.
145
146
147 __TEX mode__
148
149
150 TEX mode is enabled by the __-t__ option. In TEX mode,
151 __pic__ will define a vbox called __graph__ for each
152 picture. You must yourself print that vbox using, for
153 example, the command
154
155
156 __centerline{boxgraph}__
157
158
159 Actually, since the vbox has a height of zero this will
160 produce slightly more vertical space above the picture than
161 below it;
162
163
164 __centerline{raise 1emboxgraph}__
165
166
167 would avoid this.
168
169
170 You must use a TEX driver that supports the __tpic__
171 specials, version 2.
172
173
174 Lines beginning with __\__ are passed through
175 transparently; a __%__ is added to the end of the line to
176 avoid unwanted spaces. You can safely use this feature to
177 change fonts or to change the value of __baselineskip__.
178 Anything else may well produce undesirable results; use at
179 your own risk. Lines beginning with a period are not given
180 any special treatment.
181
182
183 __Commands__
184
185
186 __for__ ''variable'' __=__ ''expr1'' __to__
187 ''expr2'' [[__by__ [[__*__]''expr3''] __do__
188 ''X body X''
189
190
191 Set ''variable'' to ''expr1''. While the value of
192 ''variable'' is less than or equal to ''expr2'', do
193 ''body'' and increment ''variable'' by ''expr3'';
194 if __by__ is not given, increment ''variable'' by 1.
195 If ''expr3'' is prefixed by __*__ then ''variable''
196 will instead be multiplied by ''expr3''. ''X'' can be
197 any character not occurring in ''body''.
198
199
200 __if__ ''expr'' __then__ ''X if-true X''
201 [[__else__ ''Y if-false Y'']
202
203
204 Evaluate ''expr''; if it is non-zero then do
205 ''if-true'', otherwise do ''if-false''. ''X'' can
206 be any character not occurring in ''if-true''. ''Y''
207 can be any character not occurring in
208 ''if-false''.
209
210
211 __print__ ''arg''...
212
213
214 Concatenate the arguments and print as a line on stderr.
215 Each ''arg'' must be an expression, a position, or text.
216 This is useful for debugging.
217
218
219 __command__ ''arg''...
220
221
222 Concatenate the arguments and pass them through as a line to
223 troff orTEX. Each ''arg'' must be an expression, a
224 position, or text. This has a similar effect to a line
225 beginning with __.__ or __\__, but allows the values
226 of variables to be passed through.
227
228
229 __sh__ ''X command X''
230
231
232 Pass ''command'' to a shell. ''X'' can be any
233 character not occurring in ''command''.
234
235
236 __copy __''filename''____
237
238
239 Include ''filename'' at this point in the
240 file.
241
242
243 __copy__ [[____''filename''____]
244 __thru__ ''X body X'' [[__until
245 __''word''____]
246
247
248 __copy__ [[____''filename''____]
249 __thru__ ''macro'' [[__until
250 __''word''____]
251
252
253 This construct does ''body'' once for each line of
254 ''filename''; the line is split into blank-delimited
255 words, and occurrences of __$__''i'' in ''body'',
256 for ''i'' between 1 and 9, are replaced by the
257 ''i''-th word of the line. If ''filename'' is not
258 given, lines are taken from the current input up to
259 __.PE__. If an __until__ clause is specified, lines
260 will be read only until a line the first word of which is
261 ''word''; that line will then be discarded. ''X'' can
262 be any character not occurring in ''body''. For
263 example,
264
265
266 __.PS
267 copy thru % circle at ($1,$2) % until
268 __
269
270
271 is equivalent to
272
273
274 __.PS
275 circle at (1,2)
276 circle at (3,4)
277 circle at (5,6)
278 box
279 .PE
280 __
281
282
283 The commands to be performed for each line can also be taken
284 from a macro defined earlier by giving the name of the macro
285 as the argument to __thru__.
286
287
288 __reset__
289
290
291 __reset__ ''variable1''__,__ ''variable2
292 ...''
293
294
295 Reset pre-defined variables ''variable1'',
296 ''variable2'' ... to their default values. If no
297 arguments are given, reset all pre-defined variables to
298 their default values. Note that assigning a value to
299 __scale__ also causes all pre-defined variables that
300 control dimensions to be reset to their default values times
301 the new value of scale.
302
303
304 __plot__ ''expr''
305 [[____''text''____]
306
307
308 This is a text object which is constructed by using
309 ''text'' as a format string for sprintf with an argument
310 of ''expr''. If ''text'' is omitted a format string of
311 ____ is used. Attributes can be specified
312 in the same way as for a normal text object. Be very careful
313 that you specify an appropriate format string; __pic__
314 does only very limited checking of the string. This is
315 deprecated in favour of __sprintf__.
316
317
318 ''variable''__:=__''expr''
319
320
321 This is similar to __=__ except ''variable'' must
322 already be defined, and the value of ''variable'' will be
323 changed only in the innermost block in which it is defined.
324 (By contrast, __=__ defines the variable in the current
325 block if it is not already defined there, and then changes
326 the value in the current block.)
327
328
329 Arguments of the form
330
331
332 ''X'' anything ''X''
333
334
335 are also allowed to be of the form
336
337
338 __{__ ''anything'' __}__
339
340
341 In this case ''anything'' can contain balanced
342 occurrences of __{__ and __}__. Strings may contain
343 ''X'' or imbalanced occurrences of __{__ and
344 __}__.
345
346
347 __Expressions__
348
349
350 The syntax for expressions has been significantly
351 extended:
352
353
354 ''x'' __^__ ''y'' (exponentiation)__
355 sin(__''x''__)
356 cos(__''x''__)
357 atan2(__''y''__,__ ''x''__)
358 log(__''x''__)__ (base 10)__
359 exp(__''x''__)__ (base 10, ie 10''x'')__
360 sqrt(__''x''__)
361 int(__''x''__)
362 rand()__ (return a random number between 0 and 1)__
363 rand(__''x''__)__ (return a random number between 1
364 and ''x''; deprecated)__
365 srand(__''x''__)__ (set the random number
366 seed)__
367 max(__''e1''__,__ ''e2''__)
368 min(__''e1''__,__ ''e2''__)
369 !__''e
370 e1'' ____ ''e2
371 e1'' __||__ ''e2
372 e1'' __==__ ''e2
373 e1'' __!=__ ''e2
374 e1'' ____ ''e2
375 e1'' ____ ''e2
376 e1'' ____ ''e2
377 e1'' ____ ''e2''__
378 ''str1''__
379 __''str2''____
380 __''str1''__
381 __''str2''____
382
383
384 String comparison expressions must be parenthesised in some
385 contexts to avoid ambiguity.
386
387
388 __Other Changes__
389
390
391 A bare expression, ''expr'', is acceptable as an
392 attribute; it is equivalent to ''dir expr'', where
393 ''dir'' is the current direction. For
394 example
395
396
397 __line 2i__
398
399
400 means draw a line 2 inches long in the current
401 direction.
402
403
404 The maximum width and height of the picture are taken from
405 the variables __maxpswid__ and __maxpsht__. Initially
406 these have values 8.5 and 11.
407
408
409 Scientific notation is allowed for numbers. For
410 example
411
412
413 __x = 5e-2__
414
415
416 Text attributes can be compounded. For example,
417
418
419 ____
420
421
422 is legal.
423
424
425 There is no limit to the depth to which blocks can be
426 examined. For example,
427
428
429 __[[A: [[B: [[C: box ]]] with .A.B.C.sw at 1,2
430 circle at last [[].A.B.C__
431
432
433 is acceptable.
434
435
436 Arcs now have compass points determined by the circle of
437 which the arc is a part.
438
439
440 Circles and arcs can be dotted or dashed. In TEX mode
441 splines can be dotted or dashed.
442
443
444 Boxes can have rounded corners. The __rad__ attribute
445 specifies the radius of the quarter-circles at each corner.
446 If no __rad__ or __diam__ attribute is given, a radius
447 of __boxrad__ is used. Initially, __boxrad__ has a
448 value of 0. A box with rounded corners can be dotted or
449 dashed.
450
451
452 The __.PS__ line can have a second argument specifying a
453 maximum height for the picture. If the width of zero is
454 specified the width will be ignored in computing the scaling
455 factor for the picture. Note that GNU __pic__ will always
456 scale a picture by the same amount vertically as
457 horizontally. This is different from the DWB
458 2.0 __pic__ which may scale a picture by a different
459 amount vertically than horizontally if a height is
460 specified.
461
462
463 Each text object has an invisible box associated with it.
464 The compass points of a text object are determined by this
465 box. The implicit motion associated with the object is also
466 determined by this box. The dimensions of this box are taken
467 from the width and height attributes; if the width attribute
468 is not supplied then the width will be taken to be
469 __textwid__; if the height attribute is not supplied then
470 the height will be taken to be the number of text strings
471 associated with the object times __textht__. Initially
472 __textwid__ and __textht__ have a value of
473 0.
474
475
476 In places where a quoted text string can be used, an
477 expression of the form
478
479
480 __sprintf(__''format''____
481 ''arg''__,__...__)__
482
483
484 can also be used; this will produce the arguments formatted
485 according to ''format'', which should be a string as
486 described in printf(3) appropriate for the number of
487 arguments supplied, using only the __e__, __f__,
488 __g__ or __%__ format characters.
489
490
491 The thickness of the lines used to draw objects is
492 controlled by the __linethick__ variable. This gives the
493 thickness of lines in points. A negative value means use the
494 default thickness: in TEX output mode, this means use a
495 thickness of 8 milliinches; in TEX output mode with the
496 __-c__ option, this means use the line thickness
497 specified by __.ps__ lines; in troff output mode, this
498 means use a thickness proportional to the pointsize. A zero
499 value means draw the thinnest possible line supported by the
500 output device. Initially it has a value of -1. There is also
501 a __thick__[[__ness__] attribute. For
502 example,
503
504
505 __circle thickness 1.5__
506
507
508 would draw a circle using a line with a thickness of 1.5
509 points. The thickness of lines is not affected by the value
510 of the __scale__ variable, nor by the width or height
511 given in the __.PS__ line.
512
513
514 Boxes (including boxes with rounded corners), circles and
515 ellipses can be filled by giving then an attribute of
516 __fill__[[__ed__]. This takes an optional argument of
517 an expression with a value between 0 and 1; 0 will fill it
518 with white, 1 with black, values in between with a
519 proportionally gray shade. A value greater than 1 can also
520 be used: this means fill with the shade of gray that is
521 currently being used for text and lines. Normally this will
522 be black, but output devices may provide a mechanism for
523 changing this. Without an argument, then the value of the
524 variable __fillval__ will be used. Initially this has a
525 value of 0.5. The invisible attribute does not affect the
526 filling of objects. Any text associated with a filled object
527 will be added after the object has been filled, so that the
528 text will not be obscured by the filling.
529
530
531 Arrow heads will be drawn as solid triangles if the variable
532 __arrowhead__ is non-zero and either TEX mode is enabled
533 or the __-x__ option has been given. Initially
534 __arrowhead__ has a value of 1.
535
536
537 The troff output of __pic__ is device-independent. The
538 __-T__ option is therefore redundant. All numbers are
539 taken to be in inches; numbers are never interpreted to be
540 in troff machine units.
541
542
543 Objects can have an __aligned__ attribute. This will only
544 work when the postprocessor is __grops__. Any text
545 associated with an object having the __aligned__
546 attribute will be rotated about the center of the object so
547 that it is aligned in the direction from the start point to
548 the end point of the object. Note that this attribute will
549 have no effect for objects whose start and end points are
550 coincident.
551
552
553 In places where ''n''__th__ is allowed
554 __`__''expr''__'th__ is also allowed. Note that
555 __'th__ is a single token: no space is allowed between
556 the __'__ and the __th__. For example,
557
558
559 __for i = 1 to 4 do {
560 __ line from `i'th box.nw to `i+1'th box.se
561 }
562 !!CONVERSION
563
564
565 To obtain a stand-alone picture from a __pic__ file,
566 enclose your __pic__ code with __.PS__ and __.PE__
567 requests; __roff__ configuration commands may be added at
568 the beginning of the file, but no __roff__
569 text.
570
571
572 It is necessary to feed this file into __groff__ without
573 adding any page information, so you must check which
574 __.PS__ and __.PE__ requests are actually called. For
575 example, the mm macro package adds a page number, which is
576 very annoying. At the moment, calling standard __groff__
577 without any macro package works. Alternatively, you can
578 define your own requests, e.g. to do nothing:
579
580
581 __.de PS
582 ..
583 .de PE
584 ..
585 __
586
587
588 __groff__ itself does not provide direct conversion into
589 other graphics file formats. But there are lots of
590 possibilities if you first transform your picture into
591 !PostScript format using the __groff__ option __-Tps__.
592 Since this ''ps''-file lacks !BoundingBox information it
593 is not very useful by itself, but it may be fed into other
594 conversion programs, usually named __ps2__''other'' or
595 __psto__''other'' or the like. Moreover, the
596 !PostScript interpreter __ghostscript__ (__gs__) has
597 built-in graphics conversion devices that are called with
598 the option
599
600
601 __gs -sDEVICE=__''''
602
603
604 Call
605
606
607 __gs --help__
608
609
610 for a list of the available devices.
611
612
613 As the Encapsulated !PostScript File Format __EPS__ is
614 getting more and more important, and the conversion wasn't
615 regarded trivial in the past you might be interested to know
616 that there is a conversion tool named __ps2eps__ which
617 does the right job. It is much better than the tool
618 __ps2epsi__ packaged with __gs__.
619
620
621 For bitmapped graphic formats, you should use
622 __pstopnm__; the resulting (intermediate) __PNM__ file
623 can be then converted to virtually any graphics format using
624 the tools of the __netpbm__ package .
625 !!FILES
626
627
628 __/usr/share/groff/1.17.2/tmac/pic.tmac__
629
630
631 Example definitions of the __PS__ and __PE__
632 macros.
633 !!SEE ALSO
634
635
636 troff(1), groff_out(5), tex(1),
637 gs(1), ps2eps(1), pstopnm(1),
638 ps2epsi(1), pnm(5)
639
640
641 Tpic: Pic for TEX
642
643
644 Brian W. Kernighan, PIC -- A Graphics Language for
645 Typesetting (User Manual). AT
646
647
648 __ps2eps__ is available from CTAN mirrors, e.g.
649
650
651 W. Richard Stevens - Turning PIC Into HTML
652
653
654 W. Richard Stevens - Examples of picMacros
655 !!BUGS
656
657
658 Input characters that are illegal for __groff__ (ie those
659 with ASCII code 0 or between 013 and 037
660 octal or between 0200 and 0237 octal) are rejected even in
661 TEX mode.
662
663
664 The interpretation of __fillval__ is incompatible with
665 the pic in 10th edition Unix, which interprets 0 as black
666 and 1 as white.
667
668
669 !PostScript is a registered trademark of Adobe Systems
670 Incorporation.
671 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.