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

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