Debian Codegraph @

upstream/debian-trixie/man1/pic.1

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