src/preproc/pic/pic.man

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