man/pre-pic.1.in

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