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