pic.man revision 267654
1130389Sle.ig 2190507SlulfCopyright (C) 1989-2000, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. 3190507Slulf 4130389SlePermission is granted to make and distribute verbatim copies of 5130389Slethis manual provided the copyright notice and this permission notice 6130389Sleare preserved on all copies. 7130389Sle 8130389SlePermission is granted to copy and distribute modified versions of this 9130389Slemanual under the conditions for verbatim copying, provided that the 10130389Sleentire resulting derived work is distributed under the terms of a 11130389Slepermission notice identical to this one. 12130389Sle 13130389SlePermission is granted to copy and distribute translations of this 14130389Slemanual into another language, under the above conditions for modified 15130389Sleversions, except that this permission notice may be included in 16130389Sletranslations approved by the Free Software Foundation instead of in 17130389Slethe original English. 18130389Sle.. 19130389Sle. 20130389Sle. 21130389Sle.\" Like TP, but if specified indent is more than half 22130389Sle.\" the current line-length - indent, use the default indent. 23130389Sle.de Tp 24130389Sle.ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP 25130389Sle.el .TP "\\$1" 26130389Sle.. 27130389Sle. 28130389Sle.ie t \{\ 29130389Sle. ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 30130389Sle. ds lx L\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\*(tx 31130389Sle.\} 32130389Sle.el \{\ 33130389Sle. ds tx TeX 34130389Sle. ds lx LaTeX 35130389Sle.\} 36130389Sle. 37130389Sle.ie \n(.g .ds ic \/ 38130389Sle.el .ds ic \^ 39190507Slulf. 40190507Slulf.\" The BSD man macros can't handle " in arguments to font change macros, 41190507Slulf.\" so use \(ts instead of ". 42190507Slulf.tr \(ts" 43190507Slulf. 44190507Slulf. 45130389Sle.TH @G@PIC @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@" 46130389Sle. 47130389Sle. 48130389Sle.SH NAME 49130389Sle. 50130389Sle@g@pic \- compile pictures for troff or TeX 51130389Sle. 52130389Sle. 53130389Sle.SH SYNOPSIS 54190507Slulf. 55130389Sle.B @g@pic 56130389Sle[ 57130389Sle.B \-nvCSU 58130389Sle] 59130389Sle[ 60130389Sle.I filename 61130389Sle\&.\|.\|.\& 62130389Sle] 63130389Sle.br 64130389Sle.B @g@pic 65130389Sle.B \-t 66130389Sle[ 67130389Sle.B \-cvzCSU 68130389Sle] 69130389Sle[ 70130389Sle.I filename 71130389Sle\&.\|.\|.\& 72130389Sle] 73130389Sle. 74130389Sle. 75190507Slulf.SH DESCRIPTION 76190507Slulf. 77190507SlulfThis manual page describes the GNU version of 78130389Sle.BR pic , 79130389Slewhich is part of the groff document formatting system. 80130389Sle.B pic 81130389Slecompiles descriptions of pictures embedded within 82190507Slulf.B troff 83190507Slulfor \*(tx input files into commands that are understood by \*(tx or 84190507Slulf.BR troff . 85130389SleEach picture starts with a line beginning with 86130389Sle.B .PS 87130389Sleand ends with a line beginning with 88130389Sle.BR .PE . 89190507SlulfAnything outside of 90197767Slulf.B .PS 91149555Sleand 92130389Sle.B .PE 93130389Sleis passed through without change. 94130389Sle.LP 95130389SleIt is the user's responsibility to provide appropriate definitions of the 96130389Sle.B PS 97130389Sleand 98130389Sle.B PE 99130389Slemacros. 100190507SlulfWhen the macro package being used does not supply such definitions 101130389Sle(for example, old versions of \-ms), 102130389Sleappropriate definitions can be obtained with 103130389Sle.BR \-mpic : 104190507SlulfThese will center each picture. 105190507Slulf. 106149555Sle. 107130389Sle.SH OPTIONS 108130389Sle. 109130389SleOptions that do not take arguments may be grouped behind a single 110149555Sle.BR \- . 111130389SleThe special option 112190507Slulf.B \-\^\- 113190507Slulfcan be used to mark the end of the options. 114190507SlulfA filename of 115190507Slulf.B \- 116190507Slulfrefers to the standard input. 117190507Slulf. 118190507Slulf.TP 119190507Slulf.B \-C 120190507SlulfRecognize 121190507Slulf.B .PS 122190507Slulfand 123149555Sle.B .PE 124190507Slulfeven when followed by a character other than space or newline. 125149555Sle. 126190507Slulf.TP 127190507Slulf.B \-S 128190507SlulfSafer mode; do not execute 129190507Slulf.B sh 130190507Slulfcommands. 131190507SlulfThis can be useful when operating on untrustworthy input. 132190507Slulf(enabled by default) 133190507Slulf. 134190507Slulf.TP 135190507Slulf.B \-U 136190507SlulfUnsafe mode; revert the default option 137190507Slulf.BR \-S . 138190507Slulf. 139190507Slulf.TP 140190507Slulf.B \-n 141190507SlulfDon't use the groff extensions to the troff drawing commands. 142190507SlulfYou should use this if you are using a postprocessor that doesn't support 143190507Slulfthese extensions. 144190507SlulfThe extensions are described in 145190507Slulf.BR groff_out (@MAN5EXT@). 146190507SlulfThe 147190507Slulf.B \-n 148190507Slulfoption also causes 149190507Slulf.B pic 150190507Slulfnot to use zero-length lines to draw dots in troff mode. 151190507Slulf. 152190507Slulf.TP 153190507Slulf.B \-t 154190507Slulf\*(tx mode. 155190507Slulf. 156190507Slulf.TP 157190507Slulf.B \-c 158190507SlulfBe more compatible with 159135966Sle.BR tpic . 160149555SleImplies 161130389Sle.BR \-t . 162130389SleLines beginning with 163190507Slulf.B \e 164130389Sleare not passed through transparently. 165130389SleLines beginning with 166130389Sle.B . 167149555Sleare passed through with the initial 168130389Sle.B . 169130389Slechanged to 170130389Sle.BR \e . 171149555SleA line beginning with 172149555Sle.B .ps 173130389Sleis given special treatment: 174149555Sleit takes an optional integer argument specifying 175130389Slethe line thickness (pen size) in milliinches; 176130389Slea missing argument restores the previous line thickness; 177130389Slethe default line thickness is 8 milliinches. 178130389SleThe line thickness thus specified takes effect only 179190507Slulfwhen a non-negative line thickness has not been 180130389Slespecified by use of the 181149555Sle.B thickness 182149555Sleattribute or by setting the 183149555Sle.B linethick 184130389Slevariable. 185130389Sle. 186190507Slulf.TP 187149555Sle.B \-v 188190507SlulfPrint the version number. 189130389Sle. 190190507Slulf.TP 191130389Sle.B \-z 192190507SlulfIn \*(tx mode draw dots using zero-length lines. 193190507Slulf. 194190507Slulf.LP 195190507SlulfThe following options supported by other versions of 196190507Slulf.B pic 197190507Slulfare ignored: 198190507Slulf. 199190507Slulf.TP 200190507Slulf.B \-D 201190507SlulfDraw all lines using the \eD escape sequence. 202190507Slulf.B pic 203190507Slulfalways does this. 204190507Slulf. 205190507Slulf.TP 206190507Slulf.BI \-T \ dev 207190507SlulfGenerate output for the 208190507Slulf.B troff 209190507Slulfdevice 210190507Slulf.IR dev . 211190507SlulfThis is unnecessary because the 212190507Slulf.B troff 213130389Sleoutput generated by 214190507Slulf.B pic 215190507Slulfis device-independent. 216190507Slulf. 217190507Slulf. 218190507Slulf.SH USAGE 219190507Slulf. 220130389SleThis section describes only the differences between GNU 221130389Sle.B pic 222130389Sleand the original version of 223130389Sle.BR pic . 224130389SleMany of these differences also apply to newer versions of Unix 225130389Sle.BR pic . 226130389SleA complete documentation is available in the file 227190507Slulf.LP 228130389Sle.RS 229130389Sle.B @DOCDIR@/pic.ms 230149555Sle.RE 231190507Slulf. 232135966Sle.SS \*(tx mode 233190507Slulf. 234190507Slulf\*(tx mode is enabled by the 235190507Slulf.B \-t 236135966Sleoption. 237190507SlulfIn \*(tx mode, 238190507Slulf.B pic 239190507Slulfwill define a vbox called 240135966Sle.B \egraph 241149555Slefor each picture. 242190507SlulfUse the 243190507Slulf.B figname 244190507Slulfcommand to change the name of the vbox. 245190507SlulfYou must yourself print that vbox using, for example, the command 246190507Slulf.RS 247190507Slulf.LP 248190507Slulf.B 249190507Slulf\ecenterline{\ebox\egraph} 250190507Slulf.RE 251190507Slulf.LP 252190507SlulfActually, since the vbox has a height of zero (it is defined with 253190507Slulf\evtop) this will produce slightly more vertical space above the 254135966Slepicture than below it; 255190507Slulf.RS 256190507Slulf.LP 257190507Slulf.B 258190507Slulf\ecenterline{\eraise 1em\ebox\egraph} 259190507Slulf.RE 260190507Slulf.LP 261149555Slewould avoid this. 262135966Sle.LP 263135966SleTo make the vbox having a positive height and a depth of zero 264149555Sle(as used e.g.\& by \*(lx's 265190507Slulf.BR \%graphics.sty ), 266130389Sledefine the following macro in your document: 267190507Slulf.RS 268130389Sle.LP 269190507Slulf.B \edef\egpicbox#1{% 270130389Sle.br 271190507Slulf.B " \evbox{\eunvbox\ecsname #1\eendcsname\ekern 0pt}}" 272190507Slulf.RE 273190507Slulf.LP 274190507SlulfNow you can simply say 275190507Slulf.B \egpicbox{graph} 276190507Slulfinstead of \ebox\egraph. 277190507Slulf.LP 278190507SlulfYou must use a \*(tx driver that supports the 279130389Sle.B tpic 280190507Slulfspecials, version 2. 281190507Slulf.LP 282197767SlulfLines beginning with 283197767Slulf.B \e 284190507Slulfare passed through transparently; a 285190507Slulf.B % 286130389Sleis added to the end of the line to avoid unwanted spaces. 287190507SlulfYou can safely use this feature to change fonts or to 288135966Slechange the value of 289135966Sle.BR \ebaselineskip . 290190507SlulfAnything else may well produce undesirable results; use at your own risk. 291135966SleLines beginning with a period are not given any special treatment. 292190507Slulf. 293135966Sle.SS Commands 294190507Slulf. 295190507Slulf.TP 296135966Sle\fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\fR \fBto\fR \fIexpr2\fR \ 297135966Sle[\fBby\fR [\fB*\fR]\fIexpr3\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR 298135966SleSet 299190507Slulf.I variable 300190507Slulfto 301135966Sle.IR expr1 . 302135966SleWhile the value of 303190507Slulf.I variable 304190507Slulfis less than or equal to 305130389Sle.IR expr2 , 306190507Slulfdo 307190507Slulf.I body 308190507Slulfand increment 309190507Slulf.I variable 310130389Sleby 311190507Slulf.IR expr3 ; 312190507Slulfif 313190507Slulf.B by 314130389Sleis not given, increment 315190507Slulf.I variable 316190507Slulfby 1. 317190507SlulfIf 318190507Slulf.I expr3 319130389Sleis prefixed by 320190507Slulf.B * 321190507Slulfthen 322130389Sle.I variable 323190507Slulfwill instead be multiplied by 324190507Slulf.IR expr3 . 325130389SleThe value of 326130389Sle.I expr3 327190507Slulfcan be negative for the additive case; 328190507Slulf.I variable 329190507Slulfis then tested whether it is greater than or equal to 330190507Slulf.IR expr2 . 331190507SlulfFor the multiplicative case, 332190507Slulf.I expr3 333130389Slemust be greater than zero. 334190507SlulfIf the constraints aren't met, the loop isn't executed. 335190507Slulf.I X 336190507Slulfcan be any character not occurring in 337190507Slulf.IR body . 338190507Slulf. 339190507Slulf.TP 340190507Slulf\fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \ 341190507Slulf[\fBelse\fR \fIY\fR \fIif-false\fR \fIY\fR] 342143130SleEvaluate 343190507Slulf.IR expr ; 344190507Slulfif it is non-zero then do 345143130Sle.IR if-true , 346190507Slulfotherwise do 347130389Sle.IR if-false . 348130389Sle.I X 349190507Slulfcan be any character not occurring in 350190507Slulf.IR if-true . 351130389Sle.I Y 352190507Slulfcan be any character not occurring in 353130389Sle.IR if-false . 354130389Sle. 355190507Slulf.TP 356190507Slulf\fBprint\fR \fIarg\fR\|.\|.\|. 357130389SleConcatenate the arguments and print as a line on stderr. 358190507SlulfEach 359130389Sle.I arg 360190507Slulfmust be an expression, a position, or text. 361190507SlulfThis is useful for debugging. 362190507Slulf. 363190507Slulf.TP 364190507Slulf\fBcommand\fR \fIarg\fR\|.\|.\|. 365190507SlulfConcatenate the arguments 366190507Slulfand pass them through as a line to troff or \*(tx. 367190507SlulfEach 368190507Slulf.I arg 369190507Slulfmust be an expression, a position, or text. 370190507SlulfThis has a similar effect to a line beginning with 371190507Slulf.B .\& 372190507Slulfor 373190507Slulf.BR \e , 374190507Slulfbut allows the values of variables to be passed through. 375190507SlulfFor example, 376190507Slulf.RS 377190507Slulf.IP 378130389Sle.ft B 379130389Sle.nf 380190507Slulf\&.PS 381190507Slulfx = 14 382130389Slecommand ".ds string x is " x "." 383130389Sle\&.PE 384190507Slulf\e*[string] 385190507Slulf.ft 386130389Sle.fi 387190507Slulf.RE 388130389Sle.IP 389prints 390.RS 391.IP 392.B x is 14. 393.RE 394. 395.TP 396\fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR 397Pass 398.I command 399to a shell. 400.I X 401can be any character not occurring in 402.IR command . 403. 404.TP 405\fBcopy\fR \fB"\fIfilename\fB"\fR 406Include 407.I filename 408at 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] 417This construct does 418.I body 419once for each line of 420.IR filename ; 421the line is split into blank-delimited words, 422and occurrences of 423.BI $ i 424in 425.IR body , 426for 427.I i 428between 1 and 9, 429are replaced by the 430.IR i -th 431word of the line. 432If 433.I filename 434is not given, lines are taken from the current input up to 435.BR .PE . 436If an 437.B until 438clause is specified, 439lines will be read only until a line the first word of which is 440.IR word ; 441that line will then be discarded. 442.I X 443can be any character not occurring in 444.IR body . 445For example, 446.RS 447.IP 448.ft B 449.nf 450\&.PS 451copy thru % circle at ($1,$2) % until "END" 4521 2 4533 4 4545 6 455END 456box 457\&.PE 458.ft 459.fi 460.RE 461.IP 462is equivalent to 463.RS 464.IP 465.ft B 466.nf 467\&.PS 468circle at (1,2) 469circle at (3,4) 470circle at (5,6) 471box 472\&.PE 473.ft 474.fi 475.RE 476.IP 477The commands to be performed for each line can also be taken 478from a macro defined earlier by giving the name of the macro 479as 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 .\^.\^. 488Reset pre-defined variables 489.IR variable1 , 490.I variable2 491\&.\^.\^. to their default values. 492If no arguments are given, reset all pre-defined variables 493to their default values. 494Note that assigning a value to 495.B scale 496also causes all pre-defined variables that control dimensions 497to 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] 501This is a text object which is constructed by using 502.I text 503as a format string for sprintf 504with an argument of 505.IR expr . 506If 507.I text 508is omitted a format string of 509.B "\(ts%g\(ts" 510is used. 511Attributes can be specified in the same way as for a normal text 512object. 513Be very careful that you specify an appropriate format string; 514.B pic 515does only very limited checking of the string. 516This is deprecated in favour of 517.BR sprintf . 518. 519.TP 520.IB variable\ := \ expr 521This is similar to 522.B = 523except 524.I variable 525must already be defined, 526and 527.I expr 528will be assigned to 529.I variable 530without creating a variable local to the current block. 531(By contrast, 532.B = 533defines the variable in the current block if it is not already defined there, 534and then changes the value in the current block only.) 535For example, the following: 536.RS 537.IP 538.ft B 539.nf 540\&.PS 541x = 3 542y = 3 543[ 544 x := 5 545 y = 5 546] 547print x " " y 548\&.PE 549.ft 550.fi 551.RE 552.IP 553prints 554.RS 555.IP 556.B 5 3 557.RE 558. 559.LP 560Arguments of the form 561.IP 562.I X anything X 563.LP 564are also allowed to be of the form 565.IP 566.BI {\ anything\ } 567.LP 568In this case 569.I anything 570can contain balanced occurrences of 571.B { 572and 573.BR } . 574Strings may contain 575.I X 576or imbalanced occurrences of 577.B { 578and 579.BR } . 580. 581.SS Expressions 582. 583The 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 ; 613deprecated) 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 646String comparison expressions must be parenthesised in some contexts 647to avoid ambiguity. 648. 649.SS Other Changes 650. 651A bare expression, 652.IR expr , 653is acceptable as an attribute; 654it is equivalent to 655.IR dir\ expr , 656where 657.I dir 658is the current direction. 659For example 660.LP 661.RS 662.B line 2i 663.RE 664.LP 665means draw a line 2\ inches long in the current direction. 666The `i' (or `I') character is ignored; to use another measurement unit, 667set the 668.I scale 669variable to an appropriate value. 670. 671.LP 672The maximum width and height of the picture are taken from the variables 673.B maxpswid 674and 675.BR maxpsht . 676Initially these have values 8.5 and 11. 677. 678.LP 679Scientific notation is allowed for numbers. 680For example 681.RS 682.LP 683.B 684x = 5e\-2 685.RE 686. 687.LP 688Text attributes can be compounded. 689For example, 690.RS 691.LP 692.B 693"foo" above ljust 694.RE 695.LP 696is valid. 697. 698.LP 699There is no limit to the depth to which blocks can be examined. 700For example, 701.RS 702.LP 703.B 704[A: [B: [C: box ]]] with .A.B.C.sw at 1,2 705.br 706.B 707circle at last [\^].A.B.C 708.RE 709.LP 710is acceptable. 711. 712.LP 713Arcs now have compass points 714determined by the circle of which the arc is a part. 715. 716.LP 717Circles, ellipses, and arcs can be dotted or dashed. 718In \*(tx mode splines can be dotted or dashed also. 719. 720.LP 721Boxes can have rounded corners. 722The 723.B rad 724attribute specifies the radius of the quarter-circles at each corner. 725If no 726.B rad 727or 728.B diam 729attribute is given, a radius of 730.B boxrad 731is used. 732Initially, 733.B boxrad 734has a value of\ 0. 735A box with rounded corners can be dotted or dashed. 736. 737.LP 738The 739.B .PS 740line can have a second argument specifying a maximum height for 741the picture. 742If the width of zero is specified the width will be ignored in computing 743the scaling factor for the picture. 744Note that GNU 745.B pic 746will always scale a picture by the same amount vertically as well as 747horizontally. 748This is different from the 749.SM DWB 7502.0 751.B pic 752which may scale a picture by a different amount vertically than 753horizontally if a height is specified. 754. 755.LP 756Each text object has an invisible box associated with it. 757The compass points of a text object are determined by this box. 758The implicit motion associated with the object is also determined 759by this box. 760The dimensions of this box are taken from the width and height attributes; 761if the width attribute is not supplied then the width will be taken to be 762.BR textwid ; 763if the height attribute is not supplied then the height will be taken to be 764the number of text strings associated with the object 765times 766.BR textht . 767Initially 768.B textwid 769and 770.B textht 771have a value of 0. 772. 773.LP 774In (almost all) places where a quoted text string can be used, 775an expression of the form 776.IP 777.BI sprintf(\(ts format \(ts,\ arg ,\fR.\|.\|.\fB) 778.LP 779can also be used; 780this will produce the arguments formatted according to 781.IR format , 782which should be a string as described in 783.BR printf (3) 784appropriate for the number of arguments supplied. 785. 786.LP 787The thickness of the lines used to draw objects is controlled by the 788.B linethick 789variable. 790This gives the thickness of lines in points. 791A negative value means use the default thickness: 792in \*(tx output mode, this means use a thickness of 8 milliinches; 793in \*(tx output mode with the 794.B -c 795option, this means use the line thickness specified by 796.B .ps 797lines; 798in troff output mode, this means use a thickness proportional 799to the pointsize. 800A zero value means draw the thinnest possible line supported by 801the output device. 802Initially it has a value of -1. 803There is also a 804.BR thick [ ness ] 805attribute. 806For example, 807.RS 808.LP 809.B circle thickness 1.5 810.RE 811.LP 812would draw a circle using a line with a thickness of 1.5 points. 813The thickness of lines is not affected by the 814value of the 815.B scale 816variable, nor by the width or height given in the 817.B .PS 818line. 819. 820.LP 821Boxes (including boxes with rounded corners), 822circles and ellipses can be filled by giving them an attribute of 823.BR fill [ ed ]. 824This takes an optional argument of an expression with a value between 8250 and 1; 0 will fill it with white, 1 with black, values in between 826with a proportionally gray shade. 827A value greater than 1 can also be used: 828this means fill with the 829shade of gray that is currently being used for text and lines. 830Normally this will be black, but output devices may provide 831a mechanism for changing this. 832Without an argument, then the value of the variable 833.B fillval 834will be used. 835Initially this has a value of 0.5. 836The invisible attribute does not affect the filling of objects. 837Any text associated with a filled object will be added after the 838object has been filled, so that the text will not be obscured 839by the filling. 840. 841.LP 842Three additional modifiers are available to specify colored objects: 843.BR outline [ d ] 844sets the color of the outline, 845.B shaded 846the fill color, and 847.B colo\fR[\fPu\fR]\fPr\fR[\fPed\fR] 848sets both. 849All 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 855Currently, color support isn't available in \*(tx mode. 856Predefined color names for 857.B groff 858are in the device macro files, for example 859.BR ps.tmac ; 860additional colors can be defined with the 861.B .defcolor 862request (see the manual page of 863.BR @g@troff (@MAN1EXT@) 864for more details). 865.LP 866To 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. 869Example: 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 881The picture is then available in the box 882.BR \efoobar . 883.LP 884.B pic 885assumes that at the beginning of a picture both glyph and fill color are 886set to the default value. 887. 888.LP 889Arrow heads will be drawn as solid triangles if the variable 890.B arrowhead 891is non-zero and either \*(tx mode is enabled or the 892.B \-n 893option has not been given. 894Initially 895.B arrowhead 896has a value of\ 1. 897Note that solid arrow heads are always filled with the current outline 898color. 899. 900.LP 901The troff output of 902.B pic 903is device-independent. 904The 905.B \-T 906option is therefore redundant. 907All numbers are taken to be in inches; numbers are never interpreted 908to be in troff machine units. 909. 910.LP 911Objects can have an 912.B aligned 913attribute. 914This will only work if the postprocessor is 915.BR grops . 916Any text associated with an object having the 917.B aligned 918attribute will be rotated about the center of the object 919so that it is aligned in the direction from the start point 920to the end point of the object. 921Note that this attribute will have no effect for objects whose start and 922end points are coincident. 923. 924.LP 925In places where 926.IB n th 927is allowed 928.BI ` expr 'th 929is also allowed. 930Note that 931.B 'th 932is a single token: no space is allowed between the 933.B ' 934and the 935.BR th . 936For example, 937.IP 938.ft B 939.nf 940for 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. 949To obtain a stand-alone picture from a 950.B pic 951file, enclose your 952.B pic 953code with 954.B .PS 955and 956.B .PE 957requests; 958.B roff 959configuration commands may be added at the beginning of the file, but no 960.B roff 961text. 962. 963.LP 964It is necessary to feed this file into 965.B groff 966without adding any page information, so you must check which 967.B .PS 968and 969.B .PE 970requests are actually called. 971For example, the mm macro package adds a page number, which is very 972annoying. 973At the moment, calling standard 974.B groff 975without any macro package works. 976Alternatively, 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 991itself does not provide direct conversion into other graphics file 992formats. 993But there are lots of possibilities if you first transform your picture 994into PostScript\*R format using the 995.B groff 996option 997.BR -Tps . 998Since this 999.IR ps -file 1000lacks BoundingBox information it is not very useful by itself, but it 1001may be fed into other conversion programs, usually named 1002.BI ps2 other 1003or 1004.BI psto other 1005or the like. 1006Moreover, the PostScript interpreter 1007.B ghostscript 1008.RB ( gs ) 1009has built-in graphics conversion devices that are called with the option 1010.LP 1011.RS 1012.BI "gs -sDEVICE=" <devname> 1013.RE 1014.LP 1015Call 1016.LP 1017.RS 1018.B gs --help 1019.RE 1020.LP 1021for a list of the available devices. 1022. 1023.LP 1024As the Encapsulated PostScript File Format 1025.B EPS 1026is getting more and more important, and the conversion wasn't regarded 1027trivial in the past you might be interested to know that there is a 1028conversion tool named 1029.B ps2eps 1030which does the right job. 1031It is much better than the tool 1032.B ps2epsi 1033packaged with 1034.BR gs . 1035.LP 1036For bitmapped graphic formats, you should use 1037.BR pstopnm ; 1038the resulting (intermediate) 1039.B PNM 1040file can be then converted to virtually any graphics format using the tools 1041of the 1042.B netpbm 1043package . 1044. 1045. 1046.SH FILES 1047. 1048.Tp \w'\fB@MACRODIR@/pic.tmac'u+3n 1049.B 1050@MACRODIR@/pic.tmac 1051Example definitions of the 1052.B PS 1053and 1054.B PE 1055macros. 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 1069Tpic: Pic for \*(tx 1070.LP 1071Brian W. Kernighan, 1072PIC \(em A Graphics Language for Typesetting (User Manual). 1073AT&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 1078is available from CTAN mirrors, e.g. 1079.br 1080<ftp://ftp.dante.de/tex-archive/support/ps2eps/> 1081.LP 1082W. Richard Stevens - Turning PIC Into HTML 1083.br 1084<http://www.kohala.com/start/troff/pic2html.html> 1085.LP 1086W. Richard Stevens - Examples of picMacros 1087.br 1088<http://www.kohala.com/start/troff/pic.examples.ps> 1089. 1090. 1091.SH BUGS 1092. 1093Input characters that are invalid for 1094.B groff 1095(i.e., those with 1096.SM ASCII 1097code 0, or 013 octal, or between 015 and 037 octal, or between 0200 and 0237 1098octal) are rejected even in \*(tx mode. 1099.LP 1100The interpretation of 1101.B fillval 1102is incompatible with the pic in 10th edition Unix, 1103which interprets 0 as black and 1 as white. 1104.LP 1105PostScript\*R is a registered trademark of Adobe Systems Incorporation. 1106. 1107.\" Local Variables: 1108.\" mode: nroff 1109.\" End: 1110