pic/pic.man

   1 .ig \"-*- nroff -*-
   2 Copyright (C) 1989-1995 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 .\" Like TP, but if specified indent is more than half
  20 .\" the current line-length - indent, use the default indent.
  21 .de Tp
  22 .ie \\n(.$=0:((0\\$1)*2u>(\\n(.lu-\\n(.iu)) .TP
  23 .el .TP "\\$1"
  24 ..
  25 .ie t .ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
  26 .el .ds tx TeX
  27 .ie \n(.g .ds ic \/
  28 .el .ds ic \^
  29 .\" The BSD man macros can't handle " in arguments to font change macros,
  30 .\" so use \(ts instead of ".
  31 .tr \(ts"
  32 .TH @G@PIC @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
  33 .SH NAME
  34 @g@pic \- compile pictures for troff or TeX
  35 .SH SYNOPSIS
  36 .B @g@pic
  37 [
  38 .B \-nvC
  39 ]
  40 [
  41 .I filename
  42 \&.\|.\|.
  43 ]
  44 .br
  45 .B @g@pic
  46 .B \-t
  47 [
  48 .B \-cvzC
  49 ]
  50 [
  51 .I filename
  52 \&.\|.\|.
  53 ]
  54 .SH DESCRIPTION
  55 .LP
  56 This manual page describes the GNU version of
  57 .BR pic ,
  58 which is part of the groff document formatting system.
  59 .B pic
  60 compiles descriptions of pictures embedded within
  61 .B troff
  62 or \*(tx input files into commands that are understood by \*(tx or
  63 .BR troff .
  64 Each picture starts with a line beginning with
  65 .B .PS
  66 and ends with a line beginning with
  67 .BR .PE .
  68 Anything outside of
  69 .B .PS
  70 and
  71 .B .PE
  72 is passed through without change.
  73 .LP
  74 It is the user's responsibility to provide appropriate definitions of the
  75 .B PS
  76 and
  77 .B PE
  78 macros.
  79 When the macro package being used does not supply such definitions
  80 (for example, old versions of \-ms),
  81 appropriate definitions can be obtained with
  82 .BR \-mpic :
  83 these will center each picture.
  84 .SH OPTIONS
  85 .LP
  86 Options that do not take arguments may be grouped behind a single
  87 .BR \- .
  88 The special option
  89 .B \-\^\-
  90 can be used to mark the end of the options.
  91 A filename of
  92 .B \-
  93 refers to the standard input.
  94 .TP
  95 .B \-C
  96 Recognize
  97 .B .PS
  98 and
  99 .B .PE
 100 even when followed by a character other than space or newline.
 101 .TP
 102 .B \-S
 103 Safer mode; do not execute
 104 .B sh
 105 commands.
 106 This can be useful when operating on untrustworthy input.
 107 .TP
 108 .B \-n
 109 Don't use the groff extensions to the troff drawing commands.
 110 You should use this if you are using a postprocessor that doesn't support
 111 these extensions.
 112 The extensions are described in
 113 .BR groff_out (@MAN5EXT@).
 114 The
 115 .B \-n
 116 option also causes pic
 117 not to use zero-length lines to draw dots in troff mode.
 118 .TP
 119 .B \-t
 120 \*(tx mode.
 121 .TP
 122 .B \-c
 123 Be more compatible with
 124 .BR tpic .
 125 Implies
 126 .BR \-t .
 127 Lines beginning with
 128 .B \e
 129 are not passed through transparently.
 130 Lines beginning with
 131 .B .
 132 are passed through with the initial
 133 .B .
 134 changed to
 135 .BR \e .
 136 A line beginning with
 137 .B .ps
 138 is given special treatment:
 139 it takes an optional integer argument specifying
 140 the line thickness (pen size) in milliinches;
 141 a missing argument restores the previous line thickness;
 142 the default line thickness is 8 milliinches.
 143 The line thickness thus specified takes effect only
 144 when a non-negative line thickness has not been
 145 specified by use of the
 146 .B thickness
 147 attribute or by setting the
 148 .B linethick
 149 variable.
 150 .TP
 151 .B \-v
 152 Print the version number.
 153 .TP
 154 .B \-z
 155 In \*(tx mode draw dots using zero-length lines.
 156 .LP
 157 The following options supported by other versions of
 158 .B pic
 159 are ignored:
 160 .TP
 161 .B \-D
 162 Draw all lines using the \eD escape sequence.
 163 .B pic
 164 always does this.
 165 .TP
 166 .BI \-T \ dev
 167 Generate output for the
 168 .B troff
 169 device
 170 .IR dev .
 171 This is unnecessary because the
 172 .B troff
 173 output generated by
 174 .B pic
 175 is device-independent.
 176 .SH USAGE
 177 This section describes only the differences between GNU pic and the original
 178 version of pic.
 179 Many of these differences also apply to newer versions of Unix pic.
 180 .SS \*(tx mode
 181 .LP
 182 \*(tx mode is enabled by the
 183 .B \-t
 184 option.
 185 In \*(tx mode, pic will define a vbox called
 186 .B \egraph
 187 for each picture.
 188 You must yourself print that vbox using, for example, the command
 189 .RS
 190 .LP
 191 .B
 192 \ecenterline{\ebox\egraph}
 193 .RE
 194 .LP
 195 Actually, since the vbox has a height of zero this will produce
 196 slightly more vertical space above the picture than below it;
 197 .RS
 198 .LP
 199 .B
 200 \ecenterline{\eraise 1em\ebox\egraph}
 201 .RE
 202 .LP
 203 would avoid this.
 204 .LP
 205 You must use a \*(tx driver that supports the
 206 .B tpic
 207 specials, version 2.
 208 .LP
 209 Lines beginning with
 210 .B \e
 211 are passed through transparently; a
 212 .B %
 213 is added to the end of the line to avoid unwanted spaces.
 214 You can safely use this feature to change fonts or to
 215 change the value of
 216 .BR \ebaselineskip .
 217 Anything else may well produce undesirable results; use at your own risk.
 218 Lines beginning with a period are not given any special treatment.
 219 .SS Commands
 220 .TP
 221 \fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\fR \fBto\fR \fIexpr2\fR \
 222 [\fBby\fR [\fB*\fR]\fIexpr3\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR
 223 Set
 224 .I variable
 225 to
 226 .IR expr1 .
 227 While the value of
 228 .I variable
 229 is less than or equal to
 230 .IR expr2 ,
 231 do
 232 .I body
 233 and increment
 234 .I variable
 235 by
 236 .IR expr3 ;
 237 if
 238 .B by
 239 is not given, increment
 240 .I variable
 241 by 1.
 242 If
 243 .I expr3
 244 is prefixed by
 245 .B *
 246 then
 247 .I variable
 248 will instead be multiplied by
 249 .IR expr3 .
 250 .I X
 251 can be any character not occurring in
 252 .IR body .
 253 .TP
 254 \fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \
 255 [\fBelse\fR \fIY\fR \fIif-false\fR \fIY\fR]
 256 Evaluate
 257 .IR expr ;
 258 if it is non-zero then do
 259 .IR if-true ,
 260 otherwise do
 261 .IR if-false .
 262 .I X
 263 can be any character not occurring in
 264 .IR if-true .
 265 .I Y
 266 can be any character not occurring in
 267 .IR if-false .
 268 .TP
 269 \fBprint\fR \fIarg\fR\|.\|.\|.
 270 Concatenate the arguments and print as a line on stderr.
 271 Each
 272 .I arg
 273 must be an expression, a position, or text.
 274 This is useful for debugging.
 275 .TP
 276 \fBcommand\fR \fIarg\fR\|.\|.\|.
 277 Concatenate the arguments
 278 and pass them through as a line to troff or\*(tx.
 279 Each
 280 .I arg
 281 must be an expression, a position, or text.
 282 This has a similar effect to a line beginning with
 283 .B .
 284 or
 285 .BR \e ,
 286 but allows the values of variables to be passed through.
 287 .TP
 288 \fBsh\fR \fIX\fR \fIcommand\fR \fIX\fR
 289 Pass
 290 .I command
 291 to a shell.
 292 .I X
 293 can be any character not occurring in
 294 .IR command .
 295 .TP
 296 \fBcopy\fR \fB"\fIfilename\fB"\fR
 297 Include
 298 .I filename
 299 at this point in the file.
 300 .TP
 301 \fBcopy\fR [\fB"\fIfilename\fB"\fR] \fBthru\fR \fIX\fR \fIbody\fR \fIX\fR \
 302 [\fBuntil\fR \fB"\fIword\*(ic\fB"\fR]
 303 .ns
 304 .TP
 305 \fBcopy\fR [\fB"\fIfilename\fB"\fR] \fBthru\fR \fImacro\fR \
 306 [\fBuntil\fR \fB"\fIword\*(ic\fB"\fR]
 307 This construct does
 308 .I body
 309 once for each line of
 310 .IR filename ;
 311 the line is split into blank-delimited words,
 312 and occurrences of
 313 .BI $ i
 314 in
 315 .IR body ,
 316 for
 317 .I i
 318 between 1 and 9,
 319 are replaced by the
 320 .IR i -th
 321 word of the line.
 322 If
 323 .I filename
 324 is not given, lines are taken from the current input up to
 325 .BR .PE .
 326 If an
 327 .B until
 328 clause is specified,
 329 lines will be read only until a line the first word of which is
 330 .IR word ;
 331 that line will then be discarded.
 332 .I X
 333 can be any character not occurring in
 334 .IR body .
 335 For example,
 336 .RS
 337 .IP
 338 .ft B
 339 .nf
 340 \&.PS
 341 copy thru % circle at ($1,$2) % until "END"
 342 1 2
 343 3 4
 344 5 6
 345 END
 346 box
 347 \&.PE
 348 .ft
 349 .fi
 350 .RE
 351 .IP
 352 is equivalent to
 353 .RS
 354 .IP
 355 .ft B
 356 .nf
 357 \&.PS
 358 circle at (1,2)
 359 circle at (3,4)
 360 circle at (5,6)
 361 box
 362 \&.PE
 363 .ft
 364 .fi
 365 .RE
 366 .IP
 367 The commands to be performed for each line can also be taken
 368 from a macro defined earlier by giving the name of the macro
 369 as the argument to
 370 .BR thru .
 371 .LP
 372 .B reset
 373 .br
 374 .ns
 375 .TP
 376 \fBreset\fI variable1\fB,\fI variable2 .\^.\^.
 377 Reset pre-defined variables
 378 .IR variable1 ,
 379 .I variable2
 380 \&.\^.\^. to their default values.
 381 If no arguments are given, reset all pre-defined variables
 382 to their default values.
 383 Note that assigning a value to
 384 .B scale
 385 also causes all pre-defined variables that control dimensions
 386 to be reset to their default values times the new value of scale.
 387 .TP
 388 \fBplot\fR \fIexpr\fR [\fB"\fItext\*(ic\fB"\fR]
 389 This is a text object which is constructed by using
 390 .I text
 391 as a format string for sprintf
 392 with an argument of
 393 .IR expr .
 394 If
 395 .I text
 396 is omitted a format string of
 397 .B "\(ts%g\(ts"
 398 is used.
 399 Attributes can be specified in the same way as for a normal text
 400 object.
 401 Be very careful that you specify an appropriate format string;
 402 pic does only very limited checking of the string.
 403 This is deprecated in favour of
 404 .BR sprintf .
 405 .TP
 406 .IB variable := expr
 407 This is similar to
 408 .B =
 409 except
 410 .I variable
 411 must already be defined,
 412 and the value of
 413 .I variable
 414 will be changed only in the innermost block in which it is defined.
 415 (By contrast,
 416 .B =
 417 defines the variable in the current block if it is not already defined there,
 418 and then changes the value in the current block.)
 419 .LP
 420 Arguments of the form
 421 .IP
 422 .IR X\  anything\  X
 423 .LP
 424 are also allowed to be of the form
 425 .IP
 426 .BI {\  anything\  }
 427 .LP
 428 In this case
 429 .I anything
 430 can contain balanced occurrences of
 431 .B {
 432 and
 433 .BR } .
 434 Strings may contain
 435 .I X
 436 or imbalanced occurrences of
 437 .B {
 438 and
 439 .BR } .
 440 .SS Expressions
 441 The syntax for expressions has been significantly extended:
 442 .LP
 443 .IB  x\  ^\  y
 444 (exponentiation)
 445 .br
 446 .BI sin( x )
 447 .br
 448 .BI cos( x )
 449 .br
 450 .BI atan2( y , \ x )
 451 .br
 452 .BI log( x )
 453 (base 10)
 454 .br
 455 .BI exp( x )
 456 (base 10, ie 10\v'-.4m'\fIx\*(ic\fR\v'.4m')
 457 .br
 458 .BI sqrt( x )
 459 .br
 460 .BI int( x )
 461 .br
 462 .B rand()
 463 (return a random number between 0 and 1)
 464 .br
 465 .BI rand( x )
 466 (return a random number between 1 and
 467 .IR x ;
 468 deprecated)
 469 .br
 470 .BI max( e1 , \ e2 )
 471 .br
 472 .BI min( e1 , \ e2 )
 473 .br
 474 .BI ! e
 475 .br
 476 \fIe1\fB && \fIe2\fR
 477 .br
 478 \fIe1\fB || \fIe2\fR
 479 .br
 480 \fIe1\fB == \fIe2\fR
 481 .br
 482 \fIe1\fB != \fIe2\fR
 483 .br
 484 \fIe1\fB >= \fIe2\fR
 485 .br
 486 \fIe1\fB > \fIe2\fR
 487 .br
 488 \fIe1\fB <= \fIe2\fR
 489 .br
 490 \fIe1\fB < \fIe2\fR
 491 .br
 492 \fB"\fIstr1\*(ic\fB" == "\fIstr2\*(ic\fB"\fR
 493 .br
 494 \fB"\fIstr1\*(ic\fB" != "\fIstr2\*(ic\fB"\fR
 495 .br
 496 .LP
 497 String comparison expressions must be parenthesised in some contexts
 498 to avoid ambiguity.
 499 .SS Other Changes
 500 .LP
 501 A bare expression,
 502 .IR expr ,
 503 is acceptable as an attribute;
 504 it is equivalent to
 505 .IR dir\ expr ,
 506 where
 507 .I dir
 508 is the current direction.
 509 For example
 510 .IP
 511 .B line 2i
 512 .LP
 513 means draw a line 2 inches long in the current direction.
 514 .LP
 515 The maximum width and height of the picture are taken from the variables
 516 .B maxpswid
 517 and
 518 .BR maxpsht .
 519 Initially these have values 8.5 and 11.
 520 .LP
 521 Scientific notation is allowed for numbers.
 522 For example
 523 .RS
 524 .B
 525 x = 5e\-2
 526 .RE
 527 .LP
 528 Text attributes can be compounded.
 529 For example,
 530 .RS
 531 .B
 532 "foo" above ljust
 533 .RE
 534 is legal.
 535 .LP
 536 There is no limit to the depth to which blocks can be examined.
 537 For example,
 538 .RS
 539 .B
 540 [A: [B: [C: box ]]] with .A.B.C.sw at 1,2
 541 .br
 542 .B
 543 circle at last [\^].A.B.C
 544 .RE
 545 is acceptable.
 546 .LP
 547 Arcs now have compass points
 548 determined by the circle of which the arc is a part.
 549 .LP
 550 Circles and arcs can be dotted or dashed.
 551 In \*(tx mode splines can be dotted or dashed.
 552 .LP
 553 Boxes can have rounded corners.
 554 The
 555 .B rad
 556 attribute specifies the radius of the quarter-circles at each corner.
 557 If no
 558 .B rad
 559 or
 560 .B diam
 561 attribute is given, a radius of
 562 .B boxrad
 563 is used.
 564 Initially,
 565 .B boxrad
 566 has a value of 0.
 567 A box with rounded corners can be dotted or dashed.
 568 .LP
 569 The
 570 .B .PS
 571 line can have a second argument specifying a maximum height for
 572 the picture.
 573 If the width of zero is specified the width will be ignored in computing
 574 the scaling factor for the picture.
 575 Note that GNU pic will always scale a picture by the same amount
 576 vertically as horizontally.
 577 This is different from the
 578 .SM DWB
 579 2.0 pic which may scale a picture by a
 580 different amount vertically than horizontally if a height is
 581 specified.
 582 .LP
 583 Each text object has an invisible box associated with it.
 584 The compass points of a text object are determined by this box.
 585 The implicit motion associated with the object is also determined
 586 by this box.
 587 The dimensions of this box are taken from the width and height attributes;
 588 if the width attribute is not supplied then the width will be taken to be
 589 .BR textwid ;
 590 if the height attribute is not supplied then the height will be taken to be
 591 the number of text strings associated with the object
 592 times
 593 .BR textht .
 594 Initially
 595 .B textwid
 596 and
 597 .B textht
 598 have a value of 0.
 599 .LP
 600 In places where a quoted text string can be used,
 601 an expression of the form
 602 .IP
 603 .BI sprintf(\(ts format \(ts,\  arg ,\fR.\|.\|.\fB)
 604 .LP
 605 can also be used;
 606 this will produce the arguments formatted according to
 607 .IR format ,
 608 which should be a string as described in
 609 .BR printf (3)
 610 appropriate for the number of arguments supplied,
 611 using only the
 612 .BR e ,
 613 .BR f ,
 614 .B g
 615 or
 616 .B %
 617 format characters.
 618 .LP
 619 The thickness of the lines used to draw objects is controlled by the
 620 .B linethick
 621 variable.
 622 This gives the thickness of lines in points.
 623 A negative value means use the default thickness:
 624 in \*(tx output mode, this means use a thickness of 8 milliinches;
 625 in \*(tx output mode with the
 626 .B -c
 627 option, this means use the line thickness specified by
 628 .B .ps
 629 lines;
 630 in troff output mode, this means use a thickness proportional
 631 to the pointsize.
 632 A zero value means draw the thinnest possible line supported by
 633 the output device.
 634 Initially it has a value of -1.
 635 There is also a
 636 .BR thick [ ness ]
 637 attribute.
 638 For example,
 639 .RS
 640 .LP
 641 .B circle thickness 1.5
 642 .RE
 643 .LP
 644 would draw a circle using a line with a thickness of 1.5 points.
 645 The thickness of lines is not affected by the
 646 value of the
 647 .B scale
 648 variable, nor by the width or height given in the
 649 .B .PS
 650 line.
 651 .LP
 652 Boxes (including boxes with rounded corners),
 653 circles and ellipses can be filled by giving then an attribute of
 654 .BR fill [ ed ].
 655 This takes an optional argument of an expression with a value between
 656 0 and 1; 0 will fill it with white, 1 with black, values in between
 657 with a proportionally gray shade.
 658 A value greater than 1 can also be used:
 659 this means fill with the
 660 shade of gray that is currently being used for text and lines.
 661 Normally this will be black, but output devices may provide
 662 a mechanism for changing this.
 663 Without an argument, then the value of the variable
 664 .B fillval
 665 will be used.
 666 Initially this has a value of 0.5.
 667 The invisible attribute does not affect the filling of objects.
 668 Any text associated with a filled object will be added after the
 669 object has been filled, so that the text will not be obscured
 670 by the filling.
 671 .LP
 672 Arrow heads will be drawn as solid triangles if the variable
 673 .B arrowhead
 674 is non-zero and either \*(tx mode is enabled or
 675 the
 676 .B \-x
 677 option has been given.
 678 Initially
 679 .B arrowhead
 680 has a value of 1.
 681 .LP
 682 The troff output of pic is device-independent.
 683 The
 684 .B \-T
 685 option is therefore redundant.
 686 All numbers are taken to be in inches; numbers are never interpreted
 687 to be in troff machine units.
 688 .LP
 689 Objects can have an
 690 .B aligned
 691 attribute.
 692 This will only work when the postprocessor is
 693 .BR grops .
 694 Any text associated with an object having the
 695 .B aligned
 696 attribute will be rotated about the center of the object
 697 so that it is aligned in the direction from the start point
 698 to the end point of the object.
 699 Note that this attribute will have no effect for objects whose start and
 700 end points are coincident.
 701 .LP
 702 In places where
 703 .IB n th
 704 is allowed
 705 .BI ` expr 'th
 706 is also allowed.
 707 Note that
 708 .B 'th
 709 is a single token: no space is allowed between the
 710 .B '
 711 and the
 712 .BR th .
 713 For example,
 714 .IP
 715 .B
 716 .nf
 717 for i = 1 to 4 do {
 718    line from `i'th box.nw to `i+1'th box.se
 719 }
 720 .fi
 721 .SH FILES
 722 .Tp \w'\fB@MACRODIR@/tmac.pic'u+3n
 723 .B
 724 @MACRODIR@/tmac.pic
 725 Example definitions of the
 726 .B PS
 727 and
 728 .B PE
 729 macros.
 730 .SH "SEE ALSO"
 731 .BR @g@troff (@MAN1EXT@),
 732 .BR groff_out (@MAN5EXT@),
 733 .BR tex (1)
 734 .br
 735 Tpic: Pic for \*(tx
 736 .br
 737 AT&T Bell Laboratories, Computing Science Technical Report No.\ 116,
 738 PIC \(em A Graphics Language for Typesetting.
 739 (This can be obtained by sending a mail message to netlib@research.att.com
 740 with a body of `send\ 116\ from\ research/cstr'.)
 741 .SH BUGS
 742 .LP
 743 Input characters that are illegal for
 744 .B groff
 745 (ie those with
 746 .SM ASCII
 747 code 0 or between 013 and 037 octal or between 0200 and 0237 octal)
 748 are rejected even in \*(tx mode.
 749 .LP
 750 The interpretation of
 751 .B fillval
 752 is incompatible with the pic in 10th edition Unix,
 753 which interprets 0 as black and 1 as white.