contrib/groff/src/preproc/pic/pic.man

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