Debian Codegraph @

upstream/debian-unstable/man1/pic.1

raw
1 .TH \%pic 1 "2026-04-22" "groff 1.24.1"
2 .SH Name
3 \%pic \- compile pictures for
4 .I troff
5 or TeX
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright 1989-2025 Free Software Foundation, Inc.
13 .\"
14 .\" Permission is granted to make and distribute verbatim copies of this
15 .\" manual provided the copyright notice and this permission notice are
16 .\" preserved on all copies.
17 .\"
18 .\" Permission is granted to copy and distribute modified versions of
19 .\" this manual under the conditions for verbatim copying, provided that
20 .\" the entire resulting derived work is distributed under the terms of
21 .\" a permission notice identical to this one.
22 .\"
23 .\" Permission is granted to copy and distribute translations of this
24 .\" manual into another language, under the above conditions for
25 .\" modified versions, except that this permission notice may be
26 .\" included in translations approved by the Free Software Foundation
27 .\" instead of in the original English.
28 .
29 .
30 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
31 .do nr *groff_pic_1_man_C \n[.cp]
32 .cp 0
33 .
34 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
35 .nr do-fallback 0
36 .if !\n(.f .nr do-fallback 1 \" mandoc
37 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
38 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
39 .if \n[do-fallback] \{\
40 . de MR
41 . ie \\n(.$=1 \
42 . I \%\\$1
43 . el \
44 . IR \%\\$1 (\\$2)\\$3
45 . .
46 .\}
47 .rr do-fallback
48 .
49 .
50 .\" ====================================================================
51 .\" Definitions
52 .\" ====================================================================
53 .
54 .ie t \{\
55 . ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
56 . ds lx L\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\*[tx]
57 .\}
58 .el \{\
59 . ds tx TeX
60 . ds lx LaTeX
61 .\}
62 .
63 .ie \n(.g .ds ic \/
64 .el .ds ic \^
65 .
66 .
67 .\" ====================================================================
68 .SH Synopsis
69 .\" ====================================================================
70 .
71 .SY \%pic
72 .RB [ \-CnSU ]
73 .RI [ file\~ .\|.\|.]
74 .YS
75 .
76 .
77 .P
78 .SY \%pic
79 .B \-t
80 .RB [ \-cCSUz ]
81 .RI [ file\~ .\|.\|.]
82 .YS
83 .
84 .
85 .P
86 .SY \%pic
87 .B \-\-help
88 .YS
89 .
90 .
91 .P
92 .SY \%pic
93 .B \-v
94 .YS
95 .
96 .SY \%pic
97 .B \%\-\-version
98 .YS
99 .
100 .
101 .\" ====================================================================
102 .SH Description
103 .\" ====================================================================
104 .
105 The GNU implementation of
106 .I pic \" generic
107 is part of the
108 .MR groff 1
109 document formatting system.
110 .
111 .I \%pic
112 is a
113 .MR \%troff 1
114 preprocessor that translates descriptions of diagrammatic pictures
115 embedded in
116 .MR roff 7
117 or \*[tx] input into the language understood by \*[tx] or
118 .IR \%troff .
119 .
120 It copies each
121 .IR file 's
122 contents to the standard output stream,
123 translating each
124 .I picture
125 between lines starting with
126 .B .PS
127 and any of
128 .BR .PE ,
129 .BR .PF ,
130 or
131 .BR .PY .
132 .
133 End a
134 .I \%pic
135 picture with
136 .B .PE
137 to leave the drawing position at the bottom of the picture,
138 and with
139 .B .PF
140 or
141 .B .PY
142 to leave it at the top.
143 .
144 Normally,
145 .I \%pic
146 is not executed directly by the user,
147 but invoked by specifying the
148 .B \-p
149 option to
150 .MR groff 1 .
151 .
152 If no
153 .I file
154 operands are present,
155 or if
156 .I file
157 is
158 .RB \[lq] \- \[rq],
159 .I \%pic
160 reads the standard input stream.
161 .
162 .
163 .P
164 It is the user's responsibility to provide appropriate definitions
165 of the
166 .BR PS ,
167 .BR PE ,
168 and one or both of the
169 .B PF
170 and
171 .B PY
172 macros.
173 .
174 When a macro package does not supply these,
175 obtain simple definitions with the
176 .I groff
177 option
178 .BR \-mpic ;
179 these horizontally center each picture.
180 .
181 .
182 .P
183 GNU
184 .I pic \" GNU
185 supports
186 .B PY
187 as a synonym of
188 .B PF
189 to work around a name space collision with the
190 .I mm
191 macro package,
192 which defines
193 .B PF
194 as a page footer management macro.
195 .
196 Use
197 .B PF
198 preferentially unless a similar problem faces your document.
199 .
200 .
201 .\" ====================================================================
202 .SH Options
203 .\" ====================================================================
204 .
205 .B \-\-help
206 displays a usage message,
207 while
208 .B \-v
209 and
210 .B \%\-\-version
211 show version information;
212 all exit afterward.
213 .
214 .
215 .TP
216 .B \-c
217 Be more compatible with
218 .IR tpic ;
219 implies
220 .BR \-t .
221 .
222 Lines beginning with
223 .B \[rs]
224 are not passed through transparently.
225 .
226 Lines beginning with
227 .B .\&
228 are passed through with the initial
229 .B .\&
230 changed to
231 .BR \[rs] .
232 .
233 GNU
234 .I pic \" GNU
235 gives a line beginning with
236 .B .ps
237 special treatment:
238 it takes an optional integer argument specifying the line thickness
239 (pen size)
240 in milliinches,
241 a missing argument restores the previous line thickness,
242 and the default line thickness is 8\~milliinches.
243 .
244 The line thickness thus specified takes effect only when a
245 non-negative line thickness has not been specified by use of the
246 .B \%thickness
247 attribute or by setting the
248 .B \%linethick
249 variable.
250 .
251 .
252 .TP
253 .B \-C
254 Recognize
255 .BR .PS ,
256 .BR .PE ,
257 .BR .PF ,
258 and
259 .B .PY
260 even when followed by a character other than space or newline.
261 .
262 .
263 .TP
264 .B \-n
265 Don't use
266 .I groff
267 extensions to the
268 .I troff \" generic
269 drawing commands.
270 .
271 Specify this option if a postprocessor you're using doesn't support
272 these extensions,
273 described in
274 .MR groff_out 5 .
275 .
276 This option also causes
277 .I \%pic
278 not to use zero-length lines to draw dots in
279 .I troff \" generic
280 mode.
281 .
282 .
283 .TP
284 .B \-S
285 Enable safer mode and ignore any subsequent
286 .B \-U
287 option.
288 .
289 In
290 .I "safer mode,"
291 .I \%pic
292 ignores
293 .B sh
294 commands,
295 which can be useful when operating on untrustworthy input.
296 .
297 .I \%pic
298 operates in safer mode by default.
299 .
300 .
301 .TP
302 .B \-t
303 Produce \*[tx] output.
304 .
305 .
306 .TP
307 .B \-U
308 Operate in
309 .I unsafe mode;
310 .B sh
311 commands are interpreted.
312 .
313 .
314 .TP
315 .B \-z
316 In \*[tx] mode,
317 draw dots using zero-length lines.
318 .
319 .
320 .P
321 The following options supported by other versions of
322 .I pic \" generic
323 are ignored.
324 .
325 .
326 .TP 8n \" "-T dev" + 2n
327 .B \-D
328 Draw all lines using the \[rs]D escape sequence.
329 GNU
330 .I pic \" GNU
331 always does this.
332 .
333 .
334 .TP
335 .BI \-T\~ dev
336 Generate output for the
337 .I troff \" generic
338 device
339 .IR dev .
340 .
341 This option is unnecessary in GNU
342 .I pic \" GNU
343 because the
344 .I troff \" generic
345 it generates is device-independent.
346 .
347 .
348 .\" ====================================================================
349 .SH Usage
350 .\" ====================================================================
351 .
352 This section primarily discusses the differences between GNU
353 .I pic \" GNU
354 and the Eighth Edition Unix version of AT&T
355 .I pic \" AT&T
356 (1985).
357 .
358 Many of these differences also apply to later versions of AT&T
359 .IR pic .
360 .
361 .
362 .\" ====================================================================
363 .SS "\*[tx] mode"
364 .\" ====================================================================
365 .
366 \*[tx]-compatible output is produced when the
367 .B \-t
368 option is specified.
369 .
370 You must use a \*[tx] driver that supports
371 .I tpic
372 version 2 specials.
373 .
374 .RI ( tpic
375 was a fork of AT&T
376 .I pic \" AT&T
377 by Tim Morgan of the University of California at Irvine that diverged
378 from its source around 1984.
379 .
380 It is best known today for lending its name to a group of
381 .B \[rs]special
382 commands it produced for \*[tx].)
383 .\" http://ftp.cs.stanford.edu/tex/texhax/texhax90.019
384 .
385 .
386 .P
387 Lines beginning with
388 .B \[rs]
389 are passed through unaltered except for a
390 .B %
391 suffix to avoid unwanted spaces.
392 .
393 Use this feature to change fonts or the value of
394 .BR \[rs]baselineskip .
395 .
396 Other applications may produce undesirable results;
397 use at your own risk.
398 .
399 By default,
400 lines beginning with a dot are not treated specially\[em]but see the
401 .B \-c
402 option.
403 .
404 .
405 .P
406 In \*[tx] mode,
407 .I \%pic
408 defines a vbox called
409 .B \[rs]graph
410 for each picture.
411 .
412 Use GNU
413 .IR pic 's \" GNU
414 .B figname
415 command to change the name of the vbox.
416 .
417 You must print that vbox yourself using the command
418 .
419 .RS
420 .EX
421 \[rs]centerline{\[rs]box\[rs]graph}
422 .EE
423 .RE
424 .
425 for instance.
426 .
427 Since the vbox has a height of zero\[em]it is defined with
428 .BR \[rs]vtop \[em]\c
429 this produces slightly more vertical space above the picture than
430 below it;
431 .
432 .RS
433 .EX
434 \[rs]centerline{\[rs]raise 1em\[rs]box\[rs]graph}
435 .EE
436 .RE
437 .
438 would avoid this.
439 .
440 To give the vbox a positive height and a depth of zero
441 (as used by \*[lx]'s
442 .IR \%graphics.sty ,
443 for example),
444 define the following macro in your document.
445 .
446 .RS
447 .EX
448 \[rs]def\[rs]gpicbox#1{%
449 \[rs]vbox{\[rs]unvbox\[rs]csname #1\[rs]endcsname\[rs]kern 0pt}}
450 .EE
451 .RE
452 .
453 You can then simply say
454 .B \[rs]gpicbox{graph}
455 instead of
456 .BR \[rs]box\[rs]graph .
457 .
458 .
459 .\" ====================================================================
460 .SS Commands
461 .\" ====================================================================
462 .
463 Several commands new to GNU
464 .I pic \" GNU
465 accept delimiters,
466 shown in their synopses as braces
467 .BR "{ }" .
468 .
469 Nesting of braces is supported.
470 .
471 Any other characters
472 (except a space,
473 tab,
474 or newline)
475 .\" XXX even crazy control characters, ugh--src/preproc/pic/lex.cpp:1266
476 may be used as alternative delimiters,
477 in which case the members of a given pair must be identical.
478 .
479 GNU
480 .I pic \" GNU
481 recognizes double-quoted strings within delimiters of either kind;
482 such strings may contain the delimiter character or unbalanced braces.
483 .
484 .
485 .TP
486 \fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\fR \fBto\fR \fIexpr2\fR \
487 [\fBby\fR [\fB*\fR]\,\fIexpr3\/\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR
488 Set
489 .I variable
490 to
491 .IR expr1 .
492 .
493 While the value of
494 .I variable
495 is less than or equal to
496 .IR expr2 ,
497 do
498 .I body
499 and increment
500 .I variable
501 by
502 .IR expr3 ;
503 if
504 .B by
505 is not given,
506 increment
507 .I variable
508 by 1.
509 .
510 .I expr3
511 can be negative,
512 in which case
513 .I variable
514 is then tested whether it is greater than or equal to
515 .IR expr2 .
516 .
517 A
518 .B *
519 prefix on
520 .I variable
521 multiplies it by
522 .I expr3
523 (which must be greater than zero)
524 at each iteration rather than incrementing it.
525 .
526 If the range constraint on
527 .I expr3
528 isn't met,
529 the loop does not execute.
530 .
531 .I X
532 can be any character not in
533 .IR body .
534 .
535 .TP
536 \fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \
537 [\fBelse\fR \fIY\fR \fIif-false\fR \fIY\fR]
538 Evaluate
539 .IR expr ;
540 if it is non-zero then do
541 .IR if-true ,
542 otherwise do
543 .IR if-false .
544 .
545 .I X
546 can be any character not in
547 .IR if-true .
548 .
549 .I Y
550 can be any character not in
551 .IR if-false .
552 .
553 .TP
554 .BI print\~ arg\c
555 \~.\|.\|.
556 Catenate and write arguments to the standard error stream followed by a
557 newline.
558 .
559 Each
560 .I arg
561 must be an expression,
562 a position,
563 or text.
564 .
565 This feature is useful for debugging.
566 .
567 .TP
568 .BI command\~ arg\c
569 \~.\|.\|.
570 .\" Move right margin to indentation since we must indent more later.
571 .RS
572 Catenate arguments
573 and pass them as a line to
574 .I troff \" generic
575 or \*[tx].
576 .
577 Each
578 .I arg
579 must be an expression,
580 a position,
581 or text.
582 .
583 .B command
584 allows the values of
585 .I pic
586 variables to be passed to the formatter.
587 .
588 Thus,
589 .
590 .RS
591 .EX
592 \&.PS
593 x = 14
594 command ".ds string x is " x "."
595 \&.PE
596 \[rs]*[string]
597 .EE
598 .RE
599 .
600 produces
601 .
602 .RS
603 .EX
604 x is 14.
605 .EE
606 .RE
607 when formatted with
608 .IR troff . \" generic
609 .RE
610 .
611 .
612 .TP
613 \fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR
614 Pass
615 .I command
616 to a shell via
617 .MR system 3 .
618 .
619 Ignored if
620 .B \-U
621 option not specified.
622 .
623 .
624 .TP
625 \fBcopy\fR \fB"\,\fIfilename\/\fB"\fR
626 Include
627 .I filename
628 at this point in the file.
629 .
630 .
631 .TP
632 .BR copy\~ [ \[dq]\c
633 .IB filename \[dq]\c
634 .RB ]\~ thru\~\c
635 .IR "X body X" \~\c \" space in roman: we must use 2-font macro with \c
636 .RB [ until\~ \[dq]\c
637 .IB word \[dq]\c
638 ]
639 .TQ
640 .BR copy\~ [ \[dq]\c
641 .IB filename \[dq]\c
642 .RB ]\~ thru\~\c
643 .IR macro \~\c \" space roman because we must use 2-font macro with \c
644 .RB [ until\~ \[dq]\c
645 .IB word \[dq]\c
646 ]
647 .\" Move right margin to indentation since we must indent more later.
648 .RS
649 This construct does
650 .I body
651 once for each line of
652 .IR filename ;
653 the line is split into blank-delimited words,
654 and occurrences of
655 .BI $ i
656 in
657 .IR body ,
658 for
659 .I i
660 between 1 and 9,
661 are replaced by the
662 .IR i -th
663 word of the line.
664 .
665 If
666 .I filename
667 is not given,
668 lines are taken from the current input up to
669 .BR .PE .
670 .
671 If an
672 .B until
673 clause is specified,
674 GNU
675 .I pic \" GNU
676 reads lines only until encountering one beginning with
677 .IR word ;
678 which it then discards.
679 .
680 .I X
681 can be any character not in
682 .IR body .
683 .
684 For example,
685 .
686 .RS \" now move further
687 .EX
688 \&.PS
689 copy thru % circle at ($1,$2) % until "END"
690 1 2
691 3 4
692 5 6
693 END
694 box
695 \&.PE
696 .EE
697 .RE
698 .
699 and
700 .
701 .RS
702 .EX
703 \&.PS
704 circle at (1,2)
705 circle at (3,4)
706 circle at (5,6)
707 box
708 \&.PE
709 .EE
710 .RE
711 .
712 are equivalent.
713 .
714 The commands to be performed for each line can also be taken from a
715 macro defined earlier by giving the name of the macro as the argument to
716 .BR thru .
717 .
718 The argument after
719 .B thru
720 is looked up as a macro name first;
721 if not defined,
722 its first character is interpreted as a delimiter.
723 .RE
724 .
725 .
726 .TP
727 .B reset
728 .TQ
729 .BI reset\~ pvar1\c
730 .RB [ , ]\~\c
731 .IR pvar2 \~.\|.\|.
732 Reset predefined variables
733 .IR pvar1 ,
734 .I pvar2
735 \&.\|.\|.\& to their default values;
736 if no arguments are given,
737 reset all predefined variables to their default values.
738 .
739 Variable names may be separated by commas,
740 spaces,
741 or both.
742 .
743 Assigning a value to
744 .B scale
745 also causes all predefined variables that control dimensions to be reset
746 to their default values times the new value of
747 .BR scale .
748 .
749 .
750 .TP
751 .BI plot\~ expr\~\c
752 .RI [\[dq] text \[dq]]
753 Create a text object by using
754 .I text
755 as a format string for
756 .MR sprintf 3
757 with an argument of
758 .IR expr .
759 .
760 If
761 .I text
762 is omitted,
763 .B \[dq]%g\[dq]
764 is implied.
765 .
766 Attributes can be specified in the same way as for a normal text object.
767 .
768 .I Caution:
769 be very careful that you specify an appropriate format string in
770 .I text;
771 .IR \%pic 's
772 validation of it is limited.
773 .
774 .B plot
775 is deprecated in favour of
776 .BR sprintf .
777 .
778 .TP
779 .IB var \~:=\~ expr
780 .RS
781 Update an existing variable.
782 .
783 .I var
784 must already be defined,
785 and
786 .I expr
787 is assigned to
788 .I var
789 without creating a variable local to the current block.
790 .
791 (By contrast,
792 .B =
793 defines
794 .I var
795 in the current block if it is not already defined there,
796 and then changes the value in the current block only.)
797 .
798 For example,
799 .
800 .RS
801 .EX
802 .B .PS
803 .B x = 3
804 .B y = 3
805 .B [
806 .B x := 5
807 .B y = 5
808 .B ]
809 .B print x " " y
810 .B .PE
811 .EE
812 .RE
813 .
814 writes
815 .
816 .RS
817 .EX
818 5 3
819 .EE
820 .RE
821 .
822 to the standard error stream.
823 .RE
824 .
825 .
826 .\" ====================================================================
827 .SS Expressions
828 .\" ====================================================================
829 .
830 The syntax for expressions has been significantly extended.
831 .
832 .
833 .P
834 .IB x\ \[ha]\ y
835 (exponentiation)
836 .br
837 .BI sin( x )
838 .br
839 .BI cos( x )
840 .br
841 .BI atan2( y , \ x )
842 .br
843 .BI log( x )
844 (base 10)
845 .br
846 .BI exp( x )
847 (base 10, i.e.\&
848 .ie t 10\v'-.4m'\fIx\*(ic\fR\v'.4m')
849 .el 10\[ha]\fIx\fR)
850 .br
851 .BI sqrt( x )
852 .br
853 .BI int( x )
854 .br
855 .B rand()
856 (return a random number between 0 and 1)
857 .br
858 .BI rand( x )
859 (return a random number between 1 and
860 .IR x ;
861 deprecated)
862 .br
863 .BI srand( x )
864 (set the random number seed)
865 .br
866 .BI max( e1 , \ e2 )
867 .br
868 .BI min( e1 , \ e2 )
869 .br
870 .BI ! e
871 .br
872 \fIe1\fB && \fIe2\fR
873 .br
874 \fIe1\fB || \fIe2\fR
875 .br
876 \fIe1\fB == \fIe2\fR
877 .br
878 \fIe1\fB != \fIe2\fR
879 .br
880 \fIe1\fB >= \fIe2\fR
881 .br
882 \fIe1\fB > \fIe2\fR
883 .br
884 \fIe1\fB <= \fIe2\fR
885 .br
886 \fIe1\fB < \fIe2\fR
887 .br
888 \fB"\,\fIstr1\*(ic\fB" == "\,\fIstr2\*(ic\fB"\fR
889 .br
890 \fB"\,\fIstr1\*(ic\fB" != "\,\fIstr2\*(ic\fB"\fR
891 .br
892 .
893 .
894 .LP
895 String comparison expressions must be parenthesised in some contexts
896 to avoid ambiguity.
897 .
898 .
899 .\" ====================================================================
900 .SS "Other changes"
901 .\" ====================================================================
902 .
903 A bare expression,
904 .IR expr ,
905 is acceptable as an attribute;
906 it is equivalent to
907 .RI \[lq] "dir expr" \[rq],
908 where
909 .I dir
910 is the current direction.
911 .
912 For example,
913 .RB \[lq] "line 2i" \[rq]
914 draws a line 2\~inches long in the current direction.
915 .
916 The \[oq]i\[cq]
917 (or \[oq]I\[cq])
918 character is ignored;
919 to use another measurement unit,
920 set the
921 .B scale
922 variable to an appropriate value.
923 .
924 .
925 .P
926 The maximum width and height of the picture are taken from the variables
927 .B maxpswid
928 and
929 .BR maxpsht .
930 .
931 Initially,
932 these have values 8.5 and 11,
933 respectively.
934 .
935 .
936 .P
937 Scientific notation is allowed for numbers,
938 as with
939 .RB \[lq] "x = 5e\-2" \[rq].
940 .
941 .
942 .P
943 Text attributes can be compounded.
944 .
945 For example,
946 .RB \[lq]\^ "\[dq]foo\[dq] above ljust" \^\[rq]
947 is valid.
948 .
949 .
950 .P
951 There is no limit to the depth to which blocks can be nested.
952 .
953 For example,
954 .
955 .RS
956 .EX
957 [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
958 circle at last [].A.B.C
959 .EE
960 .RE
961 .
962 is acceptable.
963 .
964 .
965 .P
966 Arcs have compass points determined by the circle of which the arc is a
967 part.
968 .
969 .
970 .P
971 Circles,
972 ellipses,
973 and arcs can be dotted or dashed.
974 .
975 In \*[tx] mode,
976 splines can be dotted or dashed as well.
977 .
978 .
979 .P
980 Boxes can have rounded corners.
981 .
982 The
983 .B rad
984 attribute specifies the radius of the quarter-circles at each corner.
985 If no
986 .B rad
987 or
988 .B diam
989 attribute is given,
990 a radius of
991 .B boxrad
992 is used.
993 .
994 Initially,
995 .B boxrad
996 has a value of\~0.
997 .
998 A box with rounded corners can be dotted or dashed.
999 .
1000 .
1001 .br
1002 .ne 3v
1003 .P
1004 Boxes can have slanted sides,
1005 generalizing them from rectangles to parallelograms.
1006 .
1007 The
1008 .B \%xslanted
1009 and
1010 .B \%yslanted
1011 attributes specify the
1012 .I x
1013 and
1014 .I y
1015 offsets of the box's upper right corner from its default position.
1016 .
1017 .
1018 .P
1019 The
1020 .B .PS
1021 line accepts a second argument specifying a maximum height for the
1022 picture.
1023 .
1024 If a width of zero is specified,
1025 it is ignored when computing the scaling factor for the picture.
1026 .
1027 GNU
1028 .I pic \" GNU
1029 always scales a picture by the same amount vertically and horizontally.
1030 .
1031 This differs from DWB 2.0
1032 .IR pic , \" foreign
1033 which may change the picture's aspect ratio if a height is specified.
1034 .
1035 .
1036 .P
1037 Each text object has an associated invisible box that determines its
1038 compass points and implicit motion.
1039 .
1040 The dimensions of the box are taken from its width and height
1041 attributes.
1042 .
1043 If the width attribute is not supplied,
1044 the value of
1045 .B textwid
1046 is assumed.
1047 .
1048 If the height attribute is not supplied,
1049 the height defaults to the number of text strings associated with
1050 the object times
1051 .BR textht .
1052 .
1053 Initially,
1054 .B textwid
1055 and
1056 .B textht
1057 have values of\~0.
1058 .
1059 .
1060 .P
1061 In
1062 (almost all)
1063 .\" XXX: So what _are_ the exceptions?
1064 places where a quoted text string can be used,
1065 an expression of the form
1066 .
1067 .
1068 .IP
1069 .BI sprintf(\[dq] format \[dq],\~ arg ,\fR\~.\|.\|.\fB)
1070 .
1071 .
1072 .P
1073 can be used instead;
1074 it transforms its arguments per
1075 .IR format ,
1076 which should be a string as described in
1077 .MR printf 3 ,
1078 and appropriate to the quantity of arguments supplied.
1079 .
1080 GNU
1081 .I pic
1082 supports only the conversion specifiers
1083 .BR e ,
1084 .BR E ,
1085 .BR f ,
1086 .BR g ,
1087 .BR G ,
1088 and
1089 .BR % ,
1090 modifiers
1091 .RB \[lq] # \[rq],
1092 .RB \[lq] \- \[rq],
1093 .RB \[lq] + \[rq],
1094 and \[lq]\~\[rq] [space]),
1095 a minimum field width,
1096 and an optional precision.
1097 .
1098 .
1099 .P
1100 The thickness of the lines used to draw objects is controlled by the
1101 .B linethick
1102 variable,
1103 which is measured in points.
1104 .
1105 A negative value indicates the default thickness.
1106 .
1107 In \*[tx] output mode when the
1108 .B \-c
1109 option is not given,
1110 this means 8 milliinches.
1111 .
1112 In
1113 .I troff
1114 and \*[tx]
1115 .B \-c
1116 output modes,
1117 the default thickness corresponds to the type size.
1118 .
1119 (Thus,
1120 if the type size is 10 points,
1121 a line is 10 points thick.)
1122 .
1123 A
1124 .B linethick
1125 value of zero draws the thinnest possible line supported by the output
1126 device.
1127 .
1128 Initially,
1129 .B linethick
1130 has a value of \-1.
1131 .
1132 A
1133 .BR thick [ ness ]
1134 attribute is also available.
1135 .
1136 For example,
1137 .RB \[lq] "circle thickness 1.5" \[rq]
1138 draws a circle with a line thickness of 1.5 points.
1139 .
1140 The thickness of lines is not affected by the
1141 value of the
1142 .B scale
1143 variable,
1144 nor by the width or height given in the
1145 .B .PS
1146 line.
1147 .
1148 .
1149 .P
1150 Boxes
1151 (including boxes with rounded corners or slanted sides),
1152 circles,
1153 and ellipses can be filled by giving them an attribute of
1154 .BR fill [ ed ],
1155 which takes an optional expression argument with a value between
1156 0 and 1;
1157 0 fills it with white,
1158 1 with black,
1159 and values in between with a proportionally gray shade.
1160 .
1161 A value greater than 1 is interpreted as the shade of gray that is
1162 being used for text and lines.
1163 .
1164 Normally this is black,
1165 but output devices may provide a mechanism for changing this.
1166 .
1167 Without an argument,
1168 the value of the variable
1169 .B \%fillval
1170 is used.
1171 .
1172 Initially,
1173 .B \%fillval
1174 has a value of 0.5.
1175 .
1176 The
1177 .B \%invisible
1178 attribute does not affect the filling of objects.
1179 .
1180 Text associated with a filled object is added after the object is
1181 filled,
1182 so that the text is not obscured by the filling.
1183 .
1184 .
1185 .P
1186 Additional modifiers are available to draw colored objects:
1187 .BR \%outline [ d ]
1188 sets the color of the outline,
1189 .B shaded
1190 the fill color,
1191 and
1192 .BR colo [ u ] r [ ed ]
1193 sets both.
1194 .
1195 All expect a subsequent string argument specifying the color.
1196 .
1197 .RS
1198 .EX
1199 circle shaded \[dq]green\[dq] outline \[dq]black\[dq]
1200 .EE
1201 .RE
1202 .
1203 Color is not yet supported in \*[tx] mode.
1204 .
1205 Device macro files like
1206 .I ps.tmac
1207 declare color names;
1208 you can define additional ones with the
1209 .B \%defcolor
1210 request
1211 (see
1212 .MR groff 7 ).
1213 .
1214 .I \%pic
1215 assumes at the beginning of each picture that the stroke and fill colors
1216 are set to the device defaults.
1217 .
1218 .
1219 .P
1220 To change the name of the vbox in \*[tx] mode,
1221 set the pseudo-variable
1222 .B \%figname
1223 (which is actually a specially parsed command)
1224 within a picture.
1225 .
1226 For example,
1227 .RS
1228 .EX
1229 \&.PS
1230 figname = foobar;
1231 circle "dig here";
1232 \&.PE
1233 .EE
1234 .RE
1235 .
1236 makes the picture available in the box
1237 .BR \[rs]foobar .
1238 .
1239 .
1240 .P
1241 Arrow heads are drawn as solid triangles if the variable
1242 .B \%arrowhead
1243 is non-zero and either \*[tx] mode is enabled or the
1244 .B \-n
1245 option is not used.
1246 .
1247 Initially,
1248 .B \%arrowhead
1249 has a value of\~1.
1250 .
1251 Solid arrow heads are always filled with the current outline (stroke)
1252 color.
1253 .
1254 .
1255 .P
1256 The
1257 .I troff
1258 output of
1259 .I \%pic
1260 is device-independent.
1261 .
1262 The
1263 .B \-T
1264 option is therefore redundant.
1265 .
1266 Except where noted,
1267 all measurements and dimensions use inches implicitly;
1268 they are never interpreted as
1269 .I troff
1270 basic units.
1271 .
1272 .
1273 .P
1274 Objects can have an
1275 .B \%aligned
1276 attribute,
1277 but it is supported only by the
1278 .MR grops 1
1279 and
1280 .MR gropdf 1
1281 output drivers.
1282 .
1283 Any text associated with an
1284 .B \%aligned
1285 object is rotated about the object's center
1286 such that it is oriented along a line connecting the start and end
1287 points of the object.
1288 .
1289 .B \%aligned
1290 has no effect on objects whose start and end points are coincident.
1291 .
1292 .
1293 .P
1294 In places where
1295 .IB n th
1296 is allowed,
1297 .BI \[ga] expr \[aq]th
1298 is also allowed.
1299 .
1300 .RB \[lq] \[aq]th \[rq]
1301 is a single token:
1302 no space is allowed between the apostrophe and the
1303 .RB \[lq] th \[rq].
1304 .
1305 Consider the following example.
1306 .
1307 .
1308 .IP
1309 .EX
1310 for i = 1 to 4 do {
1311 box
1312 move right 0.5
1313 }
1314 for i = 1 to 3 do {
1315 arrow from \[ga]i\[aq]th box.ne to \[ga]i+1\[aq]th box.sw
1316 }
1317 .EE
1318 .
1319 .
1320 .P
1321 Arbitrary polygons can be drawn using the
1322 .B polygon
1323 keyword followed by a series of
1324 .IR n \-1
1325 line segments,
1326 where
1327 .I n
1328 is the number of edges of the polygon.
1329 .
1330 This allows
1331 GNU
1332 .I troff \" GNU
1333 to interpret the line segments as a complete object such that the
1334 .B \%filled
1335 and
1336 .B \%shaded
1337 attributes may be used.
1338 .
1339 The last user-specified line segment determines the polygon's
1340 final drawing position and direction.
1341 .
1342 For example,
1343 draw and fill a triangle
1344 with the following.
1345 .
1346 .
1347 .RS
1348 .P
1349 .EX
1350 polygon up 1 then right 1 down 0.5 fill 0.5
1351 .EE
1352 .RE
1353 .
1354 .
1355 .P
1356 Two reference point suffixes permit the positioning
1357 of drawing elements relative to a polygon.
1358 .
1359 .RB \[lq] .vertex
1360 .IR expr \[rq]
1361 locates the vertices,
1362 and
1363 .RB \[lq] .midpoint
1364 .IR expr \[rq]
1365 for locating the midpoints of edges.
1366 .
1367 GNU
1368 .B pic
1369 numbers vertices and midpoints in drawing order starting from
1370 .B 1 .
1371 .
1372 You can abbreviate
1373 .B \%.vertex
1374 as
1375 .B .v
1376 or
1377 .BR .ver ,
1378 and
1379 .B \%.midpoint
1380 as
1381 .BR .mid .
1382 .
1383 .
1384 .P
1385 For example,
1386 .IP
1387 .EX
1388 arrow down
1389 polygon up 0.5 right 1 \[rs]
1390 then down 0.5 right 1 \[rs]
1391 then down 0.5 left 1 \[rs]
1392 with .v2 at last line.end
1393 arrow down from last polygon.v4
1394 .EE
1395 .
1396 .
1397 .P
1398 creates and correctly places a flowchart decision diamond.
1399 .
1400 .
1401 .P
1402 .B \%.center
1403 .RB ( .c )
1404 is also available,
1405 but compass points do not work as expected
1406 and should not be used with polygons.
1407 .
1408 .
1409 .\" ====================================================================
1410 .SS "Converting \f[I]pic\f[] to other image formats"
1411 .\" ====================================================================
1412 .
1413 To create a stand-alone graphics file from a
1414 .I \%pic
1415 file,
1416 first compose the picture.
1417 .
1418 Bracket your
1419 .I pic \" language
1420 code with
1421 .B .PS
1422 and
1423 .B .PE
1424 tokens.
1425 .
1426 .I groff
1427 requests that don't produce formatted output may precede
1428 .BR .PS ,
1429 but format no text,
1430 not even any injected by a macro package,
1431 which may include a page number even on the first page,
1432 as
1433 .I mm
1434 does by default.
1435 .
1436 Consider writing a \[lq]raw\[rq]
1437 .I roff
1438 document that uses no macro package.
1439 .
1440 .
1441 .P
1442 Next,
1443 convert
1444 the
1445 .IR roff / pic
1446 input into the desired format.
1447 .
1448 .I groff
1449 distributes a simple utility,
1450 .MR pic2graph 1 ,
1451 for this purpose.
1452 .
1453 Other possibilities exist,
1454 particularly if you first transform your picture into PostScript format
1455 with
1456 .RB \[lq] "groff \-T ps" \[rq].
1457 .
1458 However,
1459 such a PostScript file lacks bounding box information;
1460 .I roff
1461 formatters produce page-sized output.
1462 .
1463 Several tools with names beginning \[lq]psto\[rq] or \[lq]ps2\[rq] exist
1464 that can infer the bounding box and perform a format conversion.
1465 .
1466 One of these is
1467 the PostScript interpreter Ghostscript
1468 .RI ( gs (1)),
1469 which exposes format converters via its
1470 .B \%\-sDEVICE=
1471 option.
1472 .
1473 .RB \[lq] "gs \-\-help" \[rq]
1474 lists available devices.
1475 .
1476 .
1477 .P
1478 Alternatively,
1479 produce a PDF with
1480 .RB \[lq] "groff \-T pdf" \[rq];
1481 .MR gropdf 1 's
1482 .B \-p
1483 option sets the MediaBox of the file.
1484 .
1485 .
1486 .P
1487 The Encapsulated PostScript File (EPS) format is still sometimes seen.
1488 .
1489 The aforementioned Ghostscript offers
1490 .MR ps2epsi 1 ,
1491 and a standalone package and command
1492 .MR ps2eps 1
1493 is also available.
1494 .
1495 .
1496 .br
1497 .ne 2v
1498 .P
1499 For raster image formats,
1500 use
1501 .MR pstopnm 1 ;
1502 the resulting
1503 .MR pnm 5
1504 file can be then converted to virtually any image format using the
1505 .I netpbm
1506 tools.
1507 .
1508 .
1509 .P
1510 GNU
1511 .I plotutils
1512 offers a
1513 .MR pic2plot 1
1514 utility for converting
1515 .I pic
1516 input to a wide variety of other image formats,
1517 including SVG.
1518 .
1519 .
1520 .\" ====================================================================
1521 .SH "Exit status"
1522 .\" ====================================================================
1523 .
1524 .I \%pic
1525 exits with
1526 .RB status\~ 0
1527 on successful operation,
1528 .RB status\~ 2
1529 if the program cannot interpret its command-line arguments,
1530 and
1531 .RB status\~ 1
1532 if it encounters an error during operation.
1533 .
1534 .
1535 .\" ====================================================================
1536 .SH Files
1537 .\" ====================================================================
1538 .
1539 .TP
1540 .I /usr/\:\%share/\:\%groff/\:\%1.24.1/\:\%tmac/pic.tmac
1541 offers simple definitions of the
1542 .BR PS ,
1543 .BR PE ,
1544 .BR PF ,
1545 and
1546 .B PY
1547 macros.
1548 .
1549 Load it with the
1550 .B mso
1551 request
1552 when eschewing a full-service macro package,
1553 or using one that doesn't supply its own definitions for them.
1554 .
1555 .
1556 .\" ====================================================================
1557 .SH Caveats
1558 .\" ====================================================================
1559 .
1560 The spacing of dots and dashes in broken lines
1561 scales with other graphics,
1562 and is configurable.
1563 .
1564 For example,
1565 .
1566 .
1567 .RS
1568 .P
1569 .EX
1570 line from 0,0 to 100,0 dotted 5
1571 .EE
1572 .RE
1573 .
1574 .
1575 .P
1576 spaces the dots in a dotted line 5 units apart.
1577 .
1578 The spacing of dashes can be set the same way.
1579 .
1580 The
1581 .B \%dashwid
1582 variable sets the length of dashes.
1583 .
1584 .
1585 .\" ====================================================================
1586 .SH Bugs
1587 .\" ====================================================================
1588 .
1589 Characters that are invalid as input to GNU
1590 .I troff \" GNU
1591 (see the
1592 .I groff
1593 Texinfo manual or
1594 .MR groff_char 7
1595 for a list)
1596 are rejected even in \*[tx] mode.
1597 .
1598 .
1599 .P
1600 Research Tenth Edition Unix
1601 .IR pic 's \" AT&T
1602 .B \%fillval
1603 interprets
1604 0 as black and 1 as white,
1605 incompatibly with GNU
1606 .IR pic .
1607 .
1608 .
1609 .\" ====================================================================
1610 .SH "See also"
1611 .\" ====================================================================
1612 .
1613 .TP
1614 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/\:pic\:.ps.gz
1615 \[lq]Making Pictures with GNU pic\[rq],
1616 by
1617 .MT esr@\:thyrsus\:.com
1618 Eric S.\& Raymond
1619 .ME .
1620 .
1621 This file,
1622 together with its source,
1623 .IR pic.ms ,
1624 is part of the
1625 .I groff
1626 distribution.
1627 .
1628 .
1629 .br
1630 .ne 2v
1631 .P
1632 \[lq]PIC\[em]A Graphics Language for Typesetting: User Manual\[rq],
1633 by Brian W.\& Kernighan,
1634 1984
1635 (revised 1991),
1636 AT&T Bell Laboratories Computing Science Technical Report No.\& 116
1637 .
1638 .
1639 .P
1640 .I ps2eps
1641 is available from CTAN mirrors, e.g.,
1642 .UR ftp://\:ftp\:.dante\:.de/\:tex\-archive/\:support/\:ps2eps/
1643 .UE .
1644 .
1645 .
1646 .LP
1647 W.\& Richard Stevens,
1648 .UR http://\:www\:.kohala\:.com/\:start/\:troff/\:pic2html\:.html
1649 .I Turning PIC into HTML
1650 .UE
1651 .
1652 .
1653 .LP
1654 W.\& Richard Stevens,
1655 .UR http://\:www\:.kohala\:.com/\:start/\:troff/\:pic\:.examples\:.ps
1656 .IR "Examples of " pic " Macros"
1657 .UE
1658 .
1659 .
1660 .P
1661 .MR \%troff 1 ,
1662 .MR groff_out 5 ,
1663 .MR tex 1 ,
1664 .MR gs 1 ,
1665 .MR ps2eps 1 ,
1666 .MR pstopnm 1 ,
1667 .MR ps2epsi 1 ,
1668 .MR pnm 5
1669 .
1670 .
1671 .\" Clean up.
1672 .rm tx
1673 .rm lx
1674 .rm ic
1675 .
1676 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1677 .cp \n[*groff_pic_1_man_C]
1678 .do rr *groff_pic_1_man_C
1679 .
1680 .
1681 .\" Local Variables:
1682 .\" fill-column: 72
1683 .\" mode: nroff
1684 .\" End:
1685 .\" vim: set filetype=groff textwidth=72: