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

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