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