src/preproc/pic/pic.1.man

   1 .TH @G@PIC @MAN1EXT@ "@MDATE@" "groff @VERSION@"
   2 .SH NAME
   3 @g@pic \- compile pictures for troff or TeX
   4 .
   5 .
   6 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
   7 .do nr pic_C \n[.C]
   8 .cp 0
   9 .
  10 .
  11 .\" ====================================================================
  12 .\" Legal Terms
  13 .\" ====================================================================
  14 .\"
  15 .\" Copyright (C) 1989-2018 Free Software Foundation, Inc.
  16 .\"
  17 .\" Permission is granted to make and distribute verbatim copies of this
  18 .\" manual provided the copyright notice and this permission notice are
  19 .\" preserved on all copies.
  20 .\"
  21 .\" Permission is granted to copy and distribute modified versions of
  22 .\" this manual under the conditions for verbatim copying, provided that
  23 .\" the entire resulting derived work is distributed under the terms of
  24 .\" a permission notice identical to this one.
  25 .\"
  26 .\" Permission is granted to copy and distribute translations of this
  27 .\" manual into another language, under the above conditions for
  28 .\" modified versions, except that this permission notice may be
  29 .\" included in translations approved by the Free Software Foundation
  30 .\" instead of in the original English.
  31 .
  32 .
  33 .\" ====================================================================
  34 .\" Definitions
  35 .\" ====================================================================
  36 .
  37 .ie t \{\
  38 .  ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
  39 .  ds lx L\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\*(tx
  40 .\}
  41 .el \{\
  42 .  ds tx TeX
  43 .  ds lx LaTeX
  44 .\}
  45 .
  46 .ie \n(.g .ds ic \/
  47 .el       .ds ic \^
  48 .
  49 .\" The BSD man macros can't handle " in arguments to font change macros,
  50 .\" so use \(ts instead of ".
  51 .tr \(ts"\""
  52 .
  53 .
  54 .\" ====================================================================
  55 .SH SYNOPSIS
  56 .\" ====================================================================
  57 .
  58 .SY @g@pic
  59 .OP \-nvCSU
  60 .RI [ file
  61 \&.\|.\|.\&]
  62 .YS
  63 .
  64 .SY @g@pic
  65 .B \-t
  66 .OP \-cvzCSU
  67 .RI [ file
  68 \&.\|.\|.\&]
  69 .YS
  70 .
  71 .
  72 .\" ====================================================================
  73 .SH DESCRIPTION
  74 .\" ====================================================================
  75 .
  76 This manual page describes the GNU version of
  77 .BR pic ,
  78 which is part of the groff document formatting system.
  79 .
  80 .B pic
  81 compiles descriptions of pictures embedded within
  82 .B troff
  83 or \*(tx input files into commands that are understood by \*(tx or
  84 .BR troff .
  85 .
  86 Each picture starts with a line beginning with
  87 .B .PS
  88 and ends with a line beginning with
  89 .BR .PE .
  90 .
  91 Anything outside of
  92 .B .PS
  93 and
  94 .B .PE
  95 is passed through without change.
  96 .
  97 .
  98 .LP
  99 It is the user's responsibility to provide appropriate definitions
 100 of the
 101 .B PS
 102 and
 103 .B PE
 104 macros.
 105 .
 106 When the macro package being used does not supply such definitions
 107 (for example, old versions of \-ms), appropriate definitions can be
 108 obtained with
 109 .BR \-mpic :
 110 .
 111 These will center each picture.
 112 .
 113 .
 114 .\" ====================================================================
 115 .SH OPTIONS
 116 .\" ====================================================================
 117 .
 118 Options that do not take arguments may be grouped behind a single
 119 .BR \- .
 120 .
 121 The special option
 122 .B \-\^\-
 123 can be used to mark the end of the options.
 124 .
 125 A filename of
 126 .B \-
 127 refers to the standard input.
 128 .
 129 .TP
 130 .B \-C
 131 Recognize
 132 .B .PS
 133 and
 134 .B .PE
 135 even when followed by a character other than space or newline.
 136 .
 137 .TP
 138 .B \-S
 139 Safer mode; do not execute
 140 .B sh
 141 commands.
 142 .
 143 This can be useful when operating on untrustworthy input (enabled by
 144 default).
 145 .
 146 .TP
 147 .B \-U
 148 Unsafe mode; revert the default option
 149 .BR \-S .
 150 .
 151 .TP
 152 .B \-n
 153 Don't use the groff extensions to the troff drawing commands.
 154 .
 155 You should use this if you are using a postprocessor that doesn't
 156 support these extensions.
 157 .
 158 The extensions are described in
 159 .BR groff_out (@MAN5EXT@).
 160 .
 161 The
 162 .B \-n
 163 option also causes
 164 .B pic
 165 not to use zero-length lines to draw dots in troff mode.
 166 .
 167 .TP
 168 .B \-t
 169 \*(tx mode.
 170 .
 171 .TP
 172 .B \-c
 173 Be more compatible with
 174 .BR tpic .
 175 .
 176 Implies
 177 .BR \-t .
 178 Lines beginning with
 179 .B \e
 180 are not passed through transparently.
 181 .
 182 Lines beginning with
 183 .B .
 184 are passed through with the initial
 185 .B .
 186 changed to
 187 .BR \e .
 188 .
 189 A line beginning with
 190 .B .ps
 191 is given special treatment:
 192 it takes an optional integer argument specifying
 193 the line thickness (pen size) in milliinches;
 194 a missing argument restores the previous line thickness;
 195 the default line thickness is 8 milliinches.
 196 .
 197 The line thickness thus specified takes effect only when a
 198 non-negative line thickness has not been specified by use of the
 199 .B thickness
 200 attribute or by setting the
 201 .B linethick
 202 variable.
 203 .
 204 .TP
 205 .B \-v
 206 Print the version number.
 207 .
 208 .TP
 209 .B \-z
 210 In \*(tx mode draw dots using zero-length lines.
 211 .
 212 .
 213 .LP
 214 The following options supported by other versions of
 215 .B pic
 216 are ignored:
 217 .
 218 .TP
 219 .B \-D
 220 Draw all lines using the \eD escape sequence.
 221 .B pic
 222 always does this.
 223 .
 224 .TP
 225 .BI \-T \ dev
 226 Generate output for the
 227 .B troff
 228 device
 229 .IR dev .
 230 .
 231 This is unnecessary because the
 232 .B troff
 233 output generated by
 234 .B pic
 235 is device-independent.
 236 .
 237 .
 238 .\" ====================================================================
 239 .SH USAGE
 240 .\" ====================================================================
 241 .
 242 This section describes only the differences between GNU
 243 .B pic
 244 and the original version of
 245 .BR pic .
 246 .
 247 Many of these differences also apply to newer versions of Unix
 248 .BR pic .
 249 .
 250 A complete documentation is available in the file
 251 .
 252 .
 253 .LP
 254 .RS
 255 .I @DOCDIR@/pic.ms
 256 .RE
 257 .
 258 .
 259 .\" ====================================================================
 260 .SS \*(tx mode
 261 .\" ====================================================================
 262 .
 263 \*(tx mode is enabled by the
 264 .B \-t
 265 option.
 266 .
 267 In \*(tx mode,
 268 .B pic
 269 will define a vbox called
 270 .B \egraph
 271 for each picture.
 272 .
 273 Use the
 274 .B figname
 275 command to change the name of the vbox.
 276 .
 277 You must yourself print that vbox using, for example, the command
 278 .
 279 .
 280 .RS
 281 .LP
 282 .B
 283 \ecenterline{\ebox\egraph}
 284 .RE
 285 .
 286 .
 287 .LP
 288 Actually, since the vbox has a height of zero (it is defined with
 289 \evtop) this will produce slightly more vertical space above the
 290 picture than below it;
 291 .RS
 292 .LP
 293 .B
 294 \ecenterline{\eraise 1em\ebox\egraph}
 295 .RE
 296 .LP
 297 would avoid this.
 298 .
 299 .
 300 .LP
 301 To make the vbox having a positive height and a depth of zero
 302 (as used e.g.\& by \*[lx]'s
 303 .BR \%graphics.sty ),
 304 define the following macro in your document:
 305 .RS
 306 .LP
 307 .B \edef\egpicbox#1{%
 308 .br
 309 .B "   \evbox{\eunvbox\ecsname #1\eendcsname\ekern 0pt}}"
 310 .RE
 311 .LP
 312 Now you can simply say
 313 .B \egpicbox{graph}
 314 instead of \ebox\egraph.
 315 .
 316 .
 317 .LP
 318 You must use a \*(tx driver that supports the
 319 .B tpic
 320 specials, version 2.
 321 .
 322 .
 323 .LP
 324 Lines beginning with
 325 .B \e
 326 are passed through transparently; a
 327 .B %
 328 is added to the end of the line to avoid unwanted spaces.
 329 .
 330 You can safely use this feature to change fonts or to
 331 change the value of
 332 .BR \ebaselineskip .
 333 .
 334 Anything else may well produce undesirable results; use at your own risk.
 335 .
 336 Lines beginning with a period are not given any special treatment.
 337 .
 338 .
 339 .\" ====================================================================
 340 .SS Commands
 341 .\" ====================================================================
 342 .
 343 .TP
 344 \fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\fR \fBto\fR \fIexpr2\fR \
 345 [\fBby\fR [\fB*\fR]\,\fIexpr3\/\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR
 346 Set
 347 .I variable
 348 to
 349 .IR expr1 .
 350 .
 351 While the value of
 352 .I variable
 353 is less than or equal to
 354 .IR expr2 ,
 355 do
 356 .I body
 357 and increment
 358 .I variable
 359 by
 360 .IR expr3 ;
 361 if
 362 .B by
 363 is not given, increment
 364 .I variable
 365 by 1.
 366 .
 367 If
 368 .I expr3
 369 is prefixed by
 370 .B *
 371 then
 372 .I variable
 373 will instead be multiplied by
 374 .IR expr3 .
 375 .
 376 The value of
 377 .I expr3
 378 can be negative for the additive case;
 379 .I variable
 380 is then tested whether it is greater than or equal to
 381 .IR expr2 .
 382 .
 383 For the multiplicative case,
 384 .I expr3
 385 must be greater than zero.
 386 .
 387 If the constraints aren't met, the loop isn't executed.
 388 .
 389 .I X
 390 can be any character not occurring in
 391 .IR body .
 392 .
 393 .TP
 394 \fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \
 395 [\fBelse\fR \fIY\fR \fIif-false\fR \fIY\fR]
 396 Evaluate
 397 .IR expr ;
 398 if it is non-zero then do
 399 .IR if-true ,
 400 otherwise do
 401 .IR if-false .
 402 .
 403 .I X
 404 can be any character not occurring in
 405 .IR if-true .
 406 .
 407 .I Y
 408 can be any character not occurring in
 409 .IR if-false .
 410 .
 411 .TP
 412 \fBprint\fR \fIarg\fR\|.\|.\|.
 413 Concatenate the arguments and print as a line on stderr.
 414 .
 415 Each
 416 .I arg
 417 must be an expression, a position, or text.
 418 .
 419 This is useful for debugging.
 420 .
 421 .TP
 422 \fBcommand\fR \fIarg\fR\|.\|.\|.
 423 Concatenate the arguments
 424 and pass them through as a line to troff or \*(tx.
 425 .
 426 Each
 427 .I arg
 428 must be an expression, a position, or text.
 429 .
 430 This has a similar effect to a line beginning with
 431 .B .\&
 432 or
 433 .BR \e ,
 434 but allows the values of variables to be passed through.
 435 .
 436 For example,
 437 .RS
 438 .IP
 439 .ft B
 440 .nf
 441 \&.PS
 442 x = 14
 443 command ".ds string x is " x "."
 444 \&.PE
 445 \e*[string]
 446 .ft
 447 .fi
 448 .RE
 449 .IP
 450 prints
 451 .RS
 452 .IP
 453 .B x is 14.
 454 .RE
 455 .
 456 .TP
 457 \fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR
 458 Pass
 459 .I command
 460 to a shell.
 461 .
 462 .I X
 463 can be any character not occurring in
 464 .IR command .
 465 .
 466 .TP
 467 \fBcopy\fR \fB"\,\fIfilename\/\fB"\fR
 468 Include
 469 .I filename
 470 at this point in the file.
 471 .
 472 .TP
 473 \fBcopy\fR [\fB"\,\fIfilename\/\fB"\fR] \fBthru\fR \fIX\fR \fIbody\fR \fIX\fR \
 474 [\fBuntil\fR \fB"\,\fIword\*(ic\fB"\fR]
 475 .ns
 476 .TP
 477 \fBcopy\fR [\fB"\,\fIfilename\/\fB"\fR] \fBthru\fR \fImacro\fR \
 478 [\fBuntil\fR \fB"\,\fIword\*(ic\fB"\fR]
 479 This construct does
 480 .I body
 481 once for each line of
 482 .IR filename ;
 483 the line is split into blank-delimited words,
 484 and occurrences of
 485 .BI $ i
 486 in
 487 .IR body ,
 488 for
 489 .I i
 490 between 1 and 9,
 491 are replaced by the
 492 .IR i -th
 493 word of the line.
 494 .
 495 If
 496 .I filename
 497 is not given, lines are taken from the current input up to
 498 .BR .PE .
 499 .
 500 If an
 501 .B until
 502 clause is specified,
 503 lines will be read only until a line the first word of which is
 504 .IR word ;
 505 that line will then be discarded.
 506 .
 507 .I X
 508 can be any character not occurring in
 509 .IR body .
 510 .
 511 For example,
 512 .RS
 513 .IP
 514 .ft B
 515 .nf
 516 \&.PS
 517 copy thru % circle at ($1,$2) % until "END"
 518 1 2
 519 3 4
 520 5 6
 521 END
 522 box
 523 \&.PE
 524 .ft
 525 .fi
 526 .RE
 527 .IP
 528 is equivalent to
 529 .RS
 530 .IP
 531 .ft B
 532 .nf
 533 \&.PS
 534 circle at (1,2)
 535 circle at (3,4)
 536 circle at (5,6)
 537 box
 538 \&.PE
 539 .ft
 540 .fi
 541 .RE
 542 .
 543 .IP
 544 The commands to be performed for each line can also be taken
 545 from a macro defined earlier by giving the name of the macro
 546 as the argument to
 547 .BR thru .
 548 .
 549 .
 550 .LP
 551 .B reset
 552 .br
 553 .ns
 554 .TP
 555 \fBreset\fI variable1\/\fR[\fB,\fR]\fI variable2 .\^.\^.
 556 Reset pre-defined variables
 557 .IR variable1 ,
 558 .I variable2
 559 \&.\^.\^.\& to their default values.
 560 .
 561 If no arguments are given, reset all pre-defined variables to their
 562 default values.
 563 .
 564 Note that assigning a value to
 565 .B scale
 566 also causes all pre-defined variables that control dimensions to be
 567 reset to their default values times the new value of scale.
 568 .
 569 .TP
 570 \fBplot\fR \fIexpr\fR [\fB"\,\fItext\*(ic\fB"\fR]
 571 This is a text object which is constructed by using
 572 .I text
 573 as a format string for sprintf
 574 with an argument of
 575 .IR expr .
 576 .
 577 If
 578 .I text
 579 is omitted a format string of
 580 .B "\(ts%g\(ts"
 581 is used.
 582 .
 583 Attributes can be specified in the same way as for a normal text
 584 object.
 585 Be very careful that you specify an appropriate format string;
 586 .B pic
 587 does only very limited checking of the string.
 588 This is deprecated in favour of
 589 .BR sprintf .
 590 .
 591 .TP
 592 .IB variable\  := \ expr
 593 This is similar to
 594 .B =
 595 except
 596 .I variable
 597 must already be defined,
 598 and
 599 .I expr
 600 will be assigned to
 601 .I variable
 602 without creating a variable local to the current block.
 603 .
 604 (By contrast,
 605 .B =
 606 defines the variable in the current block if it is not already defined
 607 there, and then changes the value in the current block only.)
 608 .
 609 For example, the following:
 610 .RS
 611 .IP
 612 .ft B
 613 .nf
 614 \&.PS
 615 x = 3
 616 y = 3
 617 [
 618   x := 5
 619   y = 5
 620 ]
 621 print x " " y
 622 \&.PE
 623 .ft
 624 .fi
 625 .RE
 626 .IP
 627 prints
 628 .RS
 629 .IP
 630 .B 5 3
 631 .RE
 632 .
 633 .
 634 .LP
 635 Arguments of the form
 636 .IP
 637 .I X anything X
 638 .LP
 639 are also allowed to be of the form
 640 .IP
 641 .BI {\  anything\  }
 642 .
 643 .
 644 .LP
 645 In this case
 646 .I anything
 647 can contain balanced occurrences of
 648 .B {
 649 and
 650 .BR } .
 651 Strings may contain
 652 .I X
 653 or imbalanced occurrences of
 654 .B {
 655 and
 656 .BR } .
 657 .
 658 .
 659 .\" ====================================================================
 660 .SS Expressions
 661 .\" ====================================================================
 662 .
 663 The syntax for expressions has been significantly extended:
 664 .
 665 .
 666 .LP
 667 .IB  x\  ^\  y
 668 (exponentiation)
 669 .br
 670 .BI sin( x )
 671 .br
 672 .BI cos( x )
 673 .br
 674 .BI atan2( y , \ x )
 675 .br
 676 .BI log( x )
 677 (base 10)
 678 .br
 679 .BI exp( x )
 680 (base 10, i.e.\&
 681 .ie t 10\v'-.4m'\fIx\*(ic\fR\v'.4m')
 682 .el   10^\fIx\fR)
 683 .br
 684 .BI sqrt( x )
 685 .br
 686 .BI int( x )
 687 .br
 688 .B rand()
 689 (return a random number between 0 and 1)
 690 .br
 691 .BI rand( x )
 692 (return a random number between 1 and
 693 .IR x ;
 694 deprecated)
 695 .br
 696 .BI srand( x )
 697 (set the random number seed)
 698 .br
 699 .BI max( e1 , \ e2 )
 700 .br
 701 .BI min( e1 , \ e2 )
 702 .br
 703 .BI ! e
 704 .br
 705 \fIe1\fB && \fIe2\fR
 706 .br
 707 \fIe1\fB || \fIe2\fR
 708 .br
 709 \fIe1\fB == \fIe2\fR
 710 .br
 711 \fIe1\fB != \fIe2\fR
 712 .br
 713 \fIe1\fB >= \fIe2\fR
 714 .br
 715 \fIe1\fB > \fIe2\fR
 716 .br
 717 \fIe1\fB <= \fIe2\fR
 718 .br
 719 \fIe1\fB < \fIe2\fR
 720 .br
 721 \fB"\,\fIstr1\*(ic\fB" == "\,\fIstr2\*(ic\fB"\fR
 722 .br
 723 \fB"\,\fIstr1\*(ic\fB" != "\,\fIstr2\*(ic\fB"\fR
 724 .br
 725 .
 726 .
 727 .LP
 728 String comparison expressions must be parenthesised in some contexts
 729 to avoid ambiguity.
 730 .
 731 .
 732 .\" ====================================================================
 733 .SS Other Changes
 734 .\" ====================================================================
 735 .
 736 A bare expression,
 737 .IR expr ,
 738 is acceptable as an attribute;
 739 it is equivalent to
 740 .IR dir\ expr ,
 741 where
 742 .I dir
 743 is the current direction.
 744 .
 745 For example
 746 .LP
 747 .RS
 748 .B line 2i
 749 .RE
 750 .LP
 751 means draw a line 2\ inches long in the current direction.
 752 .
 753 The \[oq]i\[cq] (or \[oq]I\[cq]) character is ignored; to use another
 754 measurement unit, set the
 755 .I scale
 756 variable to an appropriate value.
 757 .
 758 .
 759 .LP
 760 The maximum width and height of the picture are taken from the variables
 761 .B maxpswid
 762 and
 763 .BR maxpsht .
 764 .
 765 Initially these have values 8.5 and 11.
 766 .
 767 .
 768 .LP
 769 Scientific notation is allowed for numbers.
 770 For example
 771 .RS
 772 .LP
 773 .B
 774 x = 5e\-2
 775 .RE
 776 .
 777 .
 778 .LP
 779 Text attributes can be compounded.
 780 .
 781 For example,
 782 .RS
 783 .LP
 784 .B
 785 "foo" above ljust
 786 .RE
 787 .LP
 788 is valid.
 789 .
 790 .
 791 .LP
 792 There is no limit to the depth to which blocks can be examined.
 793 .
 794 For example,
 795 .RS
 796 .LP
 797 .B
 798 [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
 799 .br
 800 .B
 801 circle at last [\^].A.B.C
 802 .RE
 803 .LP
 804 is acceptable.
 805 .
 806 .
 807 .LP
 808 Arcs now have compass points determined by the circle of which the arc
 809 is a part.
 810 .
 811 .
 812 .LP
 813 Circles, ellipses, and arcs can be dotted or dashed.
 814 .
 815 In \*(tx mode splines can be dotted or dashed also.
 816 .
 817 .
 818 .LP
 819 Boxes can have rounded corners.
 820 .
 821 The
 822 .B rad
 823 attribute specifies the radius of the quarter-circles at each corner.
 824 If no
 825 .B rad
 826 or
 827 .B diam
 828 attribute is given, a radius of
 829 .B boxrad
 830 is used.
 831 .
 832 Initially,
 833 .B boxrad
 834 has a value of\ 0.
 835 .
 836 A box with rounded corners can be dotted or dashed.
 837 .
 838 .
 839 .LP
 840 Boxes can have slanted sides.
 841 .
 842 This effectively changes the shape of a box from a rectangle to an
 843 arbitrary parallelogram.
 844 .
 845 The
 846 .B xslanted
 847 and
 848 .B yslanted
 849 attributes specify the x and y\~offset of the box's upper right
 850 corner from its default position.
 851 .
 852 .
 853 .LP
 854 The
 855 .B .PS
 856 line can have a second argument specifying a maximum height for
 857 the picture.
 858 .
 859 If the width of zero is specified the width will be ignored in computing
 860 the scaling factor for the picture.
 861 .
 862 Note that GNU
 863 .B pic
 864 will always scale a picture by the same amount vertically as well as
 865 horizontally.
 866 .
 867 This is different from the DWB
 868 2.0
 869 .B pic
 870 which may scale a picture by a different amount vertically than
 871 horizontally if a height is specified.
 872 .
 873 .
 874 .LP
 875 Each text object has an invisible box associated with it.
 876 .
 877 The compass points of a text object are determined by this box.
 878 .
 879 The implicit motion associated with the object is also determined
 880 by this box.
 881 .
 882 The dimensions of this box are taken from the width and height attributes;
 883 if the width attribute is not supplied then the width will be taken to be
 884 .BR textwid ;
 885 if the height attribute is not supplied then the height will be taken to be
 886 the number of text strings associated with the object
 887 times
 888 .BR textht .
 889 .
 890 Initially
 891 .B textwid
 892 and
 893 .B textht
 894 have a value of 0.
 895 .
 896 .
 897 .LP
 898 In (almost all) places where a quoted text string can be used,
 899 an expression of the form
 900 .IP
 901 .BI sprintf(\(ts format \(ts,\  arg ,\fR.\|.\|.\fB)
 902 .LP
 903 can also be used;
 904 this will produce the arguments formatted according to
 905 .IR format ,
 906 which should be a string as described in
 907 .BR printf (3)
 908 appropriate for the number of arguments supplied.
 909 .
 910 .
 911 .LP
 912 The thickness of the lines used to draw objects is controlled by the
 913 .B linethick
 914 variable.
 915 .
 916 This gives the thickness of lines in points.
 917 .
 918 A negative value means use the default thickness:
 919 in \*(tx output mode, this means use a thickness of 8 milliinches;
 920 in \*(tx output mode with the
 921 .B \-c
 922 option, this means use the line thickness specified by
 923 .B .ps
 924 lines;
 925 in troff output mode, this means use a thickness proportional
 926 to the pointsize.
 927 .
 928 A zero value means draw the thinnest possible line supported by
 929 the output device.
 930 .
 931 Initially it has a value of \-1.
 932 .
 933 There is also a
 934 .BR thick [ ness ]
 935 attribute.
 936 .
 937 For example,
 938 .RS
 939 .LP
 940 .B circle thickness 1.5
 941 .RE
 942 .LP
 943 would draw a circle using a line with a thickness of 1.5 points.
 944 .
 945 The thickness of lines is not affected by the
 946 value of the
 947 .B scale
 948 variable, nor by the width or height given in the
 949 .B .PS
 950 line.
 951 .
 952 .
 953 .LP
 954 Boxes (including boxes with rounded corners or slanted sides),
 955 circles and ellipses can be filled by giving them an attribute of
 956 .BR fill [ ed ].
 957 .
 958 This takes an optional argument of an expression with a value between
 959 0 and 1; 0 will fill it with white, 1 with black, values in between
 960 with a proportionally gray shade.
 961 .
 962 A value greater than 1 can also be used:
 963 this means fill with the
 964 shade of gray that is currently being used for text and lines.
 965 .
 966 Normally this will be black, but output devices may provide
 967 a mechanism for changing this.
 968 .
 969 Without an argument, then the value of the variable
 970 .B fillval
 971 will be used.
 972 .
 973 Initially this has a value of 0.5.
 974 .
 975 The invisible attribute does not affect the filling of objects.
 976 .
 977 Any text associated with a filled object will be added after the
 978 object has been filled, so that the text will not be obscured
 979 by the filling.
 980 .
 981 .
 982 .LP
 983 Three additional modifiers are available to specify colored objects:
 984 .BR outline [ d ]
 985 sets the color of the outline,
 986 .B shaded
 987 the fill color, and
 988 .B colo\fR[\fPu\fR]\fPr\fR[\fPed\fR]
 989 sets both.
 990 .
 991 All three keywords expect a suffix specifying the color, for example
 992 .RS
 993 .LP
 994 .B circle shaded """green""" outline """black"""
 995 .RE
 996 .
 997 .
 998 .LP
 999 Currently, color support isn't available in \*(tx mode.
1000 .
1001 Predefined color names for
1002 .B groff
1003 are in the device macro files, for example
1004 .BR ps.tmac ;
1005 additional colors can be defined with the
1006 .B .defcolor
1007 request (see the manual page of
1008 .BR @g@troff (@MAN1EXT@)
1009 for more details).
1010 .
1011 .
1012 .LP
1013 To change the name of the vbox in \*(tx mode, set the pseudo-variable
1014 .B figname
1015 (which is actually a specially parsed command) within a picture.
1016 .
1017 Example:
1018 .RS
1019 .LP
1020 .B .PS
1021 .br
1022 .B figname = foobar;
1023 .br
1024 .B ...
1025 .br
1026 .B .PE
1027 .RE
1028 .
1029 .
1030 .LP
1031 The picture is then available in the box
1032 .BR \efoobar .
1033 .
1034 .
1035 .LP
1036 .B pic
1037 assumes that at the beginning of a picture both glyph and fill color are
1038 set to the default value.
1039 .
1040 .
1041 .LP
1042 Arrow heads will be drawn as solid triangles if the variable
1043 .B arrowhead
1044 is non-zero and either \*(tx mode is enabled or the
1045 .B \-n
1046 option has not been given.
1047 .
1048 Initially
1049 .B arrowhead
1050 has a value of\ 1.
1051 .
1052 Note that solid arrow heads are always filled with the current outline
1053 color.
1054 .
1055 .
1056 .LP
1057 The troff output of
1058 .B pic
1059 is device-independent.
1060 .
1061 The
1062 .B \-T
1063 option is therefore redundant.
1064 .
1065 All numbers are taken to be in inches; numbers are never interpreted
1066 to be in troff machine units.
1067 .
1068 .
1069 .LP
1070 Objects can have an
1071 .B aligned
1072 attribute.
1073 .
1074 This will only work if the postprocessor is
1075 .BR grops ,
1076 or
1077 .BR gropdf .
1078 .
1079 Any text associated with an object having the
1080 .B aligned
1081 attribute will be rotated about the center of the object
1082 so that it is aligned in the direction from the start point
1083 to the end point of the object.
1084 .
1085 Note that this attribute will have no effect for objects whose start
1086 and end points are coincident.
1087 .
1088 .
1089 .LP
1090 In places where
1091 .IB n th
1092 is allowed
1093 .BI \[oq] expr \[cq]th
1094 is also allowed.
1095 .
1096 Note that
1097 .B \[cq]th
1098 is a single token: no space is allowed between the
1099 .B \[cq]
1100 and the
1101 .BR th .
1102 .
1103 For example,
1104 .IP
1105 .ft B
1106 .nf
1107 for i = 1 to 4 do {
1108    line from \[oq]i\[cq]th box.nw to \[oq]i+1\[cq]th box.se
1109 }
1110 .ft
1111 .fi
1112 .
1113 .
1114 .\" ====================================================================
1115 .SH CONVERSION
1116 .\" ====================================================================
1117 .
1118 To obtain a stand-alone picture from a
1119 .B pic
1120 file, enclose your
1121 .B pic
1122 code with
1123 .B .PS
1124 and
1125 .B .PE
1126 requests;
1127 .B roff
1128 configuration commands may be added at the beginning of the file, but no
1129 .B roff
1130 text.
1131 .
1132 .
1133 .LP
1134 It is necessary to feed this file into
1135 .B groff
1136 without adding any page information, so you must check which
1137 .B .PS
1138 and
1139 .B .PE
1140 requests are actually called.
1141 .
1142 For example, the mm macro package adds a page number, which is very
1143 annoying.
1144 .
1145 At the moment, calling standard
1146 .B groff
1147 without any macro package works.
1148 .
1149 Alternatively, you can define your own requests, e.g.\& to do nothing:
1150 .LP
1151 .RS
1152 .nf
1153 .ft B
1154 \&.de PS
1155 \&..
1156 \&.de PE
1157 \&..
1158 .ft
1159 .fi
1160 .RE
1161 .
1162 .
1163 .LP
1164 .B groff
1165 itself does not provide direct conversion into other graphics file
1166 formats.
1167 .
1168 But there are lots of possibilities if you first transform your
1169 picture into PostScript\*R format using the
1170 .B groff
1171 option
1172 .BR \-Tps .
1173 .
1174 Since this
1175 .IR ps -file
1176 lacks BoundingBox information it is not very useful by itself, but it
1177 may be fed into other conversion programs, usually named
1178 .BI ps2 other
1179 or
1180 .BI psto other
1181 or the like.
1182 .
1183 Moreover, the PostScript interpreter
1184 .B ghostscript
1185 .RB ( gs )
1186 has built-in graphics conversion devices that are called with the option
1187 .LP
1188 .RS
1189 .BI "gs \-sDEVICE=" <devname>
1190 .RE
1191 .LP
1192 Call
1193 .LP
1194 .RS
1195 .B gs \-\-help
1196 .RE
1197 .LP
1198 for a list of the available devices.
1199 .
1200 .
1201 .LP
1202 An alternative may be to use the
1203 .B \-Tpdf
1204 option to convert your picture directly into
1205 .B PDF
1206 format.
1207 .
1208 The MediaBox of the file produced can be controlled by passing a
1209 .B \-P\-p
1210 papersize to groff.
1211 .
1212 .
1213 .LP
1214 As the Encapsulated PostScript File Format
1215 .B EPS
1216 is getting more and more important, and the conversion wasn't
1217 regarded trivial in the past you might be interested to know that
1218 there is a conversion tool named
1219 .B ps2eps
1220 which does the right job.
1221 .
1222 It is much better than the tool
1223 .B ps2epsi
1224 packaged with
1225 .BR gs .
1226 .
1227 .
1228 .LP
1229 For bitmapped graphic formats, you should use
1230 .BR pstopnm ;
1231 the resulting (intermediate)
1232 .B PNM
1233 file can be then converted to virtually any graphics format using the
1234 tools of the
1235 .B netpbm
1236 package.
1237 .
1238 .
1239 .\" ====================================================================
1240 .SH FILES
1241 .\" ====================================================================
1242 .
1243 .TP
1244 .I @MACRODIR@/pic.tmac
1245 Example definitions of the
1246 .B PS
1247 and
1248 .B PE
1249 macros.
1250 .
1251 .
1252 .\" ====================================================================
1253 .SH "SEE ALSO"
1254 .\" ====================================================================
1255 .
1256 .BR @g@troff (@MAN1EXT@),
1257 .BR groff_out (@MAN5EXT@),
1258 .BR tex (1),
1259 .BR gs (1),
1260 .BR ps2eps (1),
1261 .BR pstopnm (1),
1262 .BR ps2epsi (1),
1263 .BR pnm (5)
1264 .
1265 .
1266 .LP
1267 Eric S.\& Raymond,
1268 .I Making Pictures With GNU PIC.
1269 .br
1270 .I @DOCDIR@/pic.ps
1271 (this file, together with its source file, pic.ms, is part
1272 of the groff documentation)
1273 .
1274 .
1275 .LP
1276 Tpic: Pic for \*(tx
1277 .LP
1278 Brian W.\& Kernighan,
1279 .UR http://\:cm.bell\-labs.com/\:cm/\:cs/\:cstr/\:116.ps.gz
1280 .I PIC \(em A Graphics Language for Typesetting (User Manual)
1281 .UE .
1282 AT&T Bell Laboratories, Computing Science Technical Report No.\ 116
1283 (revised May, 1991).
1284 .
1285 .
1286 .LP
1287 .B ps2eps
1288 is available from CTAN mirrors, e.g.\&
1289 .UR ftp://\:ftp.dante.de/\:tex\-archive/\:support/\:ps2eps/
1290 .UE
1291 .
1292 .
1293 .LP
1294 W.\& Richard Stevens,
1295 .UR http://\:www.kohala.com/\:start/\:troff/\:pic2html.html
1296 .I Turning PIC into HTML
1297 .UE
1298 .
1299 .
1300 .LP
1301 W.\& Richard Stevens,
1302 .UR http://\:www.kohala.com/\:start/\:troff/\:pic.examples.ps
1303 .IR "Examples of " pic " Macros"
1304 .UE
1305 .
1306 .
1307 .\" ====================================================================
1308 .SH BUGS
1309 .\" ====================================================================
1310 .
1311 Input characters that are invalid for
1312 .B groff
1313 (i.e., those with ASCII code 0,
1314 or 013 octal, or between 015 and 037 octal, or between 0200 and 0237
1315 octal) are rejected even in \*(tx mode.
1316 .
1317 .
1318 .LP
1319 The interpretation of
1320 .B fillval
1321 is incompatible with the pic in 10th edition Unix,
1322 which interprets 0 as black and 1 as white.
1323 .
1324 .
1325 .LP
1326 PostScript\*R is a registered trademark of Adobe Systems Incorporation.
1327 .
1328 .
1329 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
1330 .cp \n[pic_C]
1331 .
1332 .
1333 .\" Local Variables:
1334 .\" mode: nroff
1335 .\" End:
1336 .\" vim: set filetype=groff: