man/pre-pic.1.in

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