1 '\" pet -- preprocess: pic(1), eqn(1), tbl(1)
3 .\"@ There is no hope that this will ever look right under nroff.
4 .\"@ Comments beginning with %% are cut lines so portions of this
5 .\"@ document can be automatically extracted. %%TUTORIAL%% begins the
6 .\"@ tutorial part; %%REFERENCE%% the reference part. %%POSTLUDE%% the
7 .\"@ bibliography and end matter after the reference part.
9 .\" Copyright (c) 2014 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
11 .\" Copyright (C) 2006, 2007, 2008
12 .\" Free Software Foundation, Inc.
13 .\" Written by Eric S. Raymond <esr@thyrsus.com>
15 .\" This document was written for free use and redistribution by
16 .\" Eric S. Raymond <esr@thyrsus.com> in August 1995. It has been put
17 .\" under the GPL in March 2006.
19 .\" This is free software; you can redistribute it and/or modify it under
20 .\" the terms of the GNU General Public License as published by the Free
21 .\" Software Foundation; either version 2, or (at your option) any later
24 .\" This is distributed in the hope that it will be useful, but WITHOUT ANY
25 .\" WARRANTY; without even the implied warranty of MERCHANTABILITY or
26 .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
29 .\" You should have received a copy of the GNU General Public License along
30 .\" with groff; see the file COPYING. If not, write to the Free Software
31 .\" Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA.
34 .\" Set a proper TeX and LaTeX
36 . ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\"
37 . ds lx L\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\*(tx\"
44 .\" Centered caption for figure. Assumes previous .KS
52 .\" Definitions end here
56 Making Pictures With GNU PIC
60 \[la]\fIesr@snark.thyrsus.com\fP\[ra]
62 The \fBpic\fP language is a \fBtroff\fP extension that makes it easy
63 to create and alter box-and-arrow diagrams of the kind frequently used
64 in technical papers and textbooks. This paper is both an introduction
65 to and reference for \fIgpic\/\fP(1), the implementation distributed by
66 the Free Software Foundation for use with \fIgroff\/\fP(1). It also
67 catalogs other implementations and explains the differences among them.
78 The \fBpic\fP language provides an easy way to write procedural
79 box-and-arrow diagrams to be included in \fBtroff\fP documents. The
80 language is sufficiently flexible to be quite useful for state charts,
81 Petri-net diagrams, flow charts, simple circuit schematics, jumper
82 layouts, and other kinds of illustration involving repetitive uses of
83 simple geometric forms and splines. Because these descriptions are
84 procedural and object-based, they are both compact and easy to modify.
86 The phrase \[lq]GNU pic\[rq] may refer to either of two \fBpic\fP
87 implementations distributed by the Free Software Foundation and
88 intended to accept the same input language. The \fIgpic\/\fP(1)
89 implementation is for use with the \fIgroff\/\fP(1) implementation of
90 \fBtroff\fP. The \fIpic2plot\/\fP(1) implementation runs standalone
91 and is part of the \fBplotutils\fR package. Because both
92 implementations are widely available in source form for free, they are
93 good bets for writing very portable documentation.
98 The original 1984 pre-\fIditroff\/\fP(1) version of \fBpic\fP is long
99 obsolete. The rewritten 1991 version is still available as part of
100 the Documenter's Work Bench module of System V.
102 Where differences between Documenter's Work Bench (1991) \fBpic\fP and GNU
103 \fBpic\fP need to be described, original \fBpic\fP is referred to as
104 \[lq]DWB pic\[rq]. Details on the history of the program are given at the
105 end of this document.
107 The \fBpic2plot\fR program does not require the rest of the
108 \fIgroff\/\fP(1) toolchain to render graphics. It can display
109 \fBpic\fR diagrams in a X\~window, or generate output plots in a large
110 number of other formats. These formats include: PNG, PBM, PGM, PPM, GIF,
111 SVG, Adobe Illustrator format, idraw-editable Postscript, the WebCGM
112 format for Web-based vector graphics, the format used by the \fBxfig\fP
113 drawing editor, the Hewlett-Packard PCL\~5 printer language, the
114 Hewlett-Packard Graphics Language (by default, HP-GL/2), the ReGIS
115 (remote graphics instruction set) format developed by DEC, Tektronix
116 format, and device-independent GNU graphics metafile format.
118 In this document, \fIgpic\/\fP(1) and \fIpic2plot\/\fP(1) extensions are
125 Every \fBpic\fP description is a little program describing drawing
126 actions. The \fB[gtn]roff\fP-dependent versions compile the program
127 by \fIpic\/\fP(1) into \fIgtroff\/\fP(1) macros; the
128 \fIpic2plot\/\fP(1) implementation uses a plotting library to draw the
129 picture directly. Programs that process or display
130 \fIgtroff\/\fP(1) output need not know or care that parts of the image
131 began life as \fBpic\fP descriptions.
133 The \fIpic\/\fP(1) program tries to translate anything between \fB.PS\fP
134 and \fB.PE\fP markers, and passes through everything else. The normal
135 definitions of \fB.PS\fP and \fB.PE\fP in the \fIms\fP macro package
136 and elsewhere have also the side-effect of centering the \fBpic\fP output
142 If you make a \fBpic\fP syntax error, \fIgpic\/\fP(1) issues an
143 error message in the standard \fIgcc\/\fP(1)-like syntax. A typical
144 error message looks like this,
148 pic:pic.ms:<nnn>: parse error before `<token>'
149 pic:pic.ms:<nnn>: giving up on this picture
154 where \[la]nnn\[ra] is a line number, and \[la]token\[ra] is a token near (usually
155 just after) the error location.
161 Pictures are described procedurally, as collections of objects
162 connected by motions. Normally, \fBpic\fP tries to string together
163 objects left-to-right in the sequence they are described, joining them
164 at visually natural points. Here is an example illustrating the
165 flow of data in \fBpic\fP processing:
170 box width 0.6 "\fIgpic\/\fP(1)"
172 box width 1.1 "\fIgtbl\/\fP(1) or \fIgeqn\/\fP(1)" "(optional)" dashed;
174 box width 0.6 "\fIgtroff\/\fP(1)";
178 .CE "1: Flow of \fBpic\fP data"
180 This was produced from the following \fBpic\fP program:
189 box width 0.6 "\efIpic\e/\efP(1)"
191 box width 1.1 "\efIgtbl\e/\efP(1) or \efIgeqn\e/\efP(1)" "(optional)" dashed;
193 box width 0.6 "\efIgtroff\e/\efP(1)";
201 This little program illustrates several \fBpic\fP basics. Firstly, we
202 see how to invoke three object types; ellipses, arrows, and boxes. We
203 see how to declare text lines to go within an object (and that text
204 can have font changes in it). We see how to change the line style of
205 an object from solid to dashed. And we see that a box can be made
206 wider than its default size to accommodate more text (we'll discuss
207 this facility in detail in the next section).
209 We also get to see \fBpic\fP's simple syntax. Statements are ended by
210 newlines or semicolons. String quotes are required around all text
211 arguments, whether or not they contain spaces. In general, the order
212 of command arguments and modifiers like \[lq]width 1.2\[rq] or
213 \[lq]dashed\[rq] doesn't matter, except that the order of text arguments
216 Here are all but one of the basic \fBpic\fP objects at their default sizes:
229 arc; down; move; "arc"
231 .CE "2: Basic \fBpic\fP objects"
233 The missing simple object type is a \fIspline\fP. There is also a way
234 to collect objects into \fIblock composites\fP which allows you to
235 treat the whole group as a single object (resembling a box) for many
236 purposes. We'll describe both of these later on.
238 The box, ellipse, circle, and block composite objects are \fIclosed\/\fR;
239 lines, arrows, arcs and splines are \fIopen\fP. This distinction
240 is often important in explaining command modifiers.
242 Figure \n[H1]-2 was produced by the following \fBpic\fP program,
243 which introduces some more basic concepts:
258 arc; down; move; "arc"
264 The first thing to notice is the \fImove\fP command, which moves a
265 default distance (1/2 inch) in the current movement direction.
267 Secondly, see how we can also decorate lines and arrows with text.
268 The line and arrow commands each take two arguments here, specifying
269 text to go above and below the object. If you wonder why one argument
270 would not do, contemplate the output of \fBarrow "ow!"\fP:
275 .CE "3: Text centered on an arrow"
277 When a command takes one text string, \fBpic\fP tries to place it at
278 the object's geometric center. As you add more strings, \fBpic\fP
279 treats them as a vertical block to be centered. The program
286 line "1" "2" "3" "4";
287 line "1" "2" "3" "4" "5";
292 for example, gives you this:
299 line "1" "2" "3" "4";
300 line "1" "2" "3" "4" "5";
303 .CE "4: Effects of multiple text arguments"
305 The last line of Figure 3.2's program, `\fBarc; down; move;
306 "arc"\fP', describing the captioned arc, introduces several new ideas.
307 Firstly, we see how to change the direction in which objects are
308 joined. Had we written \fBarc; move; "arc"\fP,
309 omitting \fBdown\fP the caption would have been joined to the top
310 of the arc, like this:
315 .CE "5: Result of \fBarc; move; \"arc\"\fP"
317 This is because drawing an arc changes the default direction to the
318 one its exit end points at. To reinforce this point, consider:
323 .CE "6: Result of \fBarc cw; move; \"arc\"\fP"
325 All we've done differently here is specify \[lq]cw\[rq] for a clockwise arc
326 (\[lq]ccw\[rq] specifies counter-clockwise direction).
327 Observe how it changes the default direction to down, rather than up.
329 Another good way to see this via with the following program:
333 line; arc; arc cw; line
341 line; arc; arc cw; line;
343 .CE "7: Result of \fBline; arc; arc cw; line\fP"
345 Notice that we did not have to specify \[lq]up\[rq] for the second arc to be
346 joined to the end of the first.
348 Finally, observe that a string, alone, is treated as text to be
349 surrounded by an invisible box of a size either specified by width
350 and height attributes or by the defaults \fBtextwid\fR and
351 \fBtextht\fR. Both are initially zero (because we don't know the
358 Sizes are specified in inches. If you don't like inches, it's
359 possible to set a global style variable \fBscale\fP that changes the
360 unit. Setting \fBscale = 2.54\fP effectively changes the internal
361 unit to centimeters (all other size variable values are scaled
365 Default Sizes of Objects
367 Here are the default sizes for \fBpic\fP objects:
369 center, tab(@), linesize(2);
378 box@0.75" wide by 0.5" high
380 ellipse@0.75" wide by 0.5" high
388 The simplest way to think about these defaults is that they make the
389 other basic objects fit snugly into a default-sized box.
391 \fIpic2plot\/\fP(1) does not necessarily emit a physical inch for
392 each virtual inch in its drawing coordinate system. Instead, it draws
393 on a canvas 8\~virtual inches by 8\~virtual inches wide. If its
394 output page size is \[lq]letter\[rq], these virtual inches will map to
395 real ones. Specifying a different page size (such as, say,
396 \[lq]a4\[rq]) will scale virtual inches so they are output as one
397 eighth of the page width. Also, \fIpic2plot\/\fP(1) centers all
398 images by default, though the \fB\-n\fP option can be used to prevent
402 Objects Do Not Stretch!
404 Text is rendered in the current font with normal troff line spacing.
405 Boxes, circles, and ellipses do \fInot\fP automatically resize to fit
406 enclosed text. Thus, if you say \fBbox "this text far too long for a
407 default box"\fP you'll get this:
410 box "this text is far too long for a default box"
412 .CE "1: Boxes do not automatically resize"
414 which is probably not the effect you want.
419 To change the box size, you can specify a box width with the \[lq]width\[rq]
423 box width 3 "this text is far too long for a default box"
425 .CE "2: Result of \fBbox width 3 \"text far too long\"\fP"
427 This modifier takes a dimension in inches. There is also a \[lq]height\[rq]
428 modifier that changes a box's height. The \fBwidth\fP keyword may
429 be abbreviated to \fBwid\fP; the \fBheight\fP keyword to \fBht\fP.
432 Resizing Other Object Types
434 To change the size of a circle, give it a \fBrad[ius]\fP or
435 \fBdiam[eter]\fP modifier; this changes the radius or diameter of the
436 circle, according to the numeric argument that follows.
439 {circle rad 0.1; move down 0.2 from last circle .s; "0.1"};
440 move; circle rad 0.2 "0.2"; move; circle rad 0.3 "0.3";
442 .CE "3: Circles with increasing radii"
444 The \fBmove\fP command can also take a dimension, which just tells
445 it how many inches to move in the current direction.
447 Ellipses are sized to fit in the rectangular box defined by their
448 axes, and can be resized with \fBwidth\fP and \fBheight\fP like boxes.
450 You can also change the radius of curvature of an arc with \fBrad[ius]\fP
451 (which specifies the radius of the circle of which the arc is a segment).
452 Larger values yield flatter arcs.
455 {arc rad 0.1; move down 0.3 from last arc .center; "0.1"};
457 {arc rad 0.2; move down 0.4 from last arc .center; "0.2"};
459 {arc rad 0.3; move down 0.5 from last arc .center; "0.3"};
461 .CE "4: \fBarc rad\fP with increasing radii"
463 Observe that because an arc is defined as a quarter circle, increasing
464 the radius also increases the size of the arc's bounding box.
469 In place of a dimension specification, you can use the keyword
470 \fBsame\fR. This gives the object the same size as the previous one
471 of its type. As an example, the program
476 box; box wid 1 ht 1; box same; box
485 box; box wid 1 ht 1; box same; box
487 .CE "5: The \fBsame\fP keyword"
491 Generalized Lines and Splines
496 It is possible to specify diagonal lines or arrows by adding multiple \fBup\fP,
497 \fBdown\fP, \fBleft\fP, and \fBright\fP modifiers to the line object.
498 Any of these can have a multiplier. To understand the effects, think
499 of the drawing area as being gridded with standard-sized boxes.
502 # Draw a demonstration up left arrow with grid box overlay
508 box wid 0.5 ht 0.5 dotted with .nw at last arrow .end;
509 for i = 2 to ($1 / 0.5) do {
510 box wid 0.5 ht 0.5 dotted with .sw at last box .se;
512 move down from last arrow .center;
514 if ( $1 == boxht ) then {
517 sprintf("\fBarrow up left %g\fP", $1)
521 move right 0.1 from last [] .e;
529 .CE "1: Diagonal arrows (dotted boxes show the implied 0.5-inch grid)"
532 Multi-Segment Line Objects
534 A \[lq]line\[rq] or \[lq]arrow\[rq] object may actually be a path
535 consisting of any number of segments of varying lengths and directions.
536 To describe a path, connect several line or arrow commands with the
540 define zigzag { $1 right 1 then down .5 left 1 then right 1 }
543 .CE "2: \fBline right 1 then down .5 left 1 then right 1\fP"
545 If a path starts with \fBthen\fP, the first segment is assumed to be into
546 the current direction, using the default length.
551 If you start a path with the \fBspline\fP keyword, the path vertices
552 are treated as control points for a spline curve fit.
556 move down 0.2 from last [] .s;
557 "The spline curve..."
558 move right from last [] .e;
561 spline from start of last line right 1 then down .5 left 1 then right 1;
562 "1" at last spline .start + (-0.1, 0);
563 "2" at last spline .start + (1.1, 0);
564 "3" at last spline .end + (-1.1, 0);
565 "4" at last spline .end + (0.1, 0);
567 move down 0.2 from last [] .s;
568 "...with tangents displayed"
571 .CE "3: \fBspline right 1 then down .5 left 1 then right 1\fP"
573 You can describe many natural-looking but irregular curves this
577 [spline right then up then left then down ->;]
578 move down 0.2 from last [] .s;
579 ["\fBspline right then up then left then down ->;\fP"]
580 move right 3 from last [] .se;
581 "\fBspline left then up right then down right ->;\fP"
583 [spline left then up right then down right ->;]
585 .CE "4: Two more spline examples"
587 Note the arrow decorations. Arrowheads can be applied naturally to
588 any path-based object, line or spline. We'll see how in the next
598 All \fBpic\fP implementations support the following font-styling
599 escapes within text objects:
601 Set Roman style (the default)
606 .IP "\efP\ \ \ \ \ \ "
607 Revert to previous style; only works one level deep, does not stack.
609 In the \fBpic\fP implementations that are preprocessors for a
610 toolchain that include \fB[gtn]roff\fP, text objects may also contain
611 \fB[gtn]roff\fP vertical- and horizontal-motion escapes such as \eh or \ev.
612 Troff special glyphs are also available. All \e-escapes will be
613 passed through to the postprocessing stage and have their normal
614 effects. The base font family is set by the \fB[gtn]roff\fP
615 environment at the time the picture is rendered.
617 \fBpic2plot\fP replaces \fB[gtn]roff\fP horizontal- and vertical-motion
618 escapes with \e-escapes of its own. Troff special glyphs are not
619 available, but in most back ends Latin-1 special characters and a
620 square-root radical will be. See the \fBpic2plot\fP documentation for
626 We've already seen that the modifier \fBdashed\fP can change the line
627 style of an object from solid to dashed. GNU \fBgpic\fP permits you to
628 dot or dash ellipses, circles, and arcs (and splines in \*[tx] mode
629 only); some versions of DWB may only permit dashing of lines and
630 boxes. It's possible to change the dash interval by specifying a
631 number after the modifier.
635 box dashed "default";
637 box dashed 0.05 "0.05";
639 box dashed 0.1 "0.1";
641 box dashed 0.15 "0.15";
643 box dashed 0.2 "0.2";
645 .CE "1: Dashed objects"
650 Another available qualifier is \fBdotted\fP. GNU \fBgpic\fP permits
651 you to dot or dash ellipses, circles, and arcs (and splines in \*[tx]
652 mode only); some versions of DWB may only permit dashing of lines and
653 boxes. It too can be suffixed with a number to specify the interval
657 box dotted "default";
659 box dotted 0.05 "0.05";
661 box dotted 0.1 "0.1";
663 box dotted 0.15 "0.15";
665 box dotted 0.2 "0.2";
667 .CE "2: Dotted objects"
672 It is also possible, in GNU \fBgpic\fP only, to modify a box so it has
676 box rad 0.05 "rad 0.05";
678 box rad 0.1 "rad 0.1";
680 box rad 0.15 "rad 0.15";
682 box rad 0.2 "rad 0.2";
684 box rad 0.25 "rad 0.25";
686 .CE "3: \fBbox rad\fP with increasing radius values"
688 Radius values higher than half the minimum box dimension are silently
689 truncated to that value.
694 GNU \fBgpic\fP supports slanted boxes:
697 box wid 1.2 xslanted 0.1 "xslanted 0.1";
699 box wid 1.2 yslanted -0.1 "yslanted -0.1";
701 box wid 1.2 xslanted -0.2 yslanted 0.1 "xslanted -0.2" "yslanted 0.1";
703 .CE "4: Various slanted boxes."
705 The \fBxslanted\fP and \fByslanted\fP attributes specify the x and
706 y\~offset, respectively, of the box's upper right corner from its default
712 Lines and arcs can be decorated as well. Any line or arc (and any
713 spline as well) can be decorated with arrowheads by adding one or more
719 .CE "5: Double-headed line made with \fBline <- ->\fP"
721 In fact, the \fBarrow\fP command is just shorthand for \fBline ->\fP. And
722 there is a double-head modifier <->, so the figure above could have been made
725 Arrowheads have a \fBwidth\fP attribute, the distance across the rear;
726 and a \fBheight\fP attribute, the length of the arrowhead along the shaft.
728 Arrowhead style is controlled by the style variable \fBarrowhead\fP.
729 The DWB and GNU versions interpret it differently. DWB defaults to
730 open arrowheads and an \fBarrowhead\fP value of\~2; the Kernighan
731 paper says a value of\~7 makes solid arrowheads. GNU \fBgpic\fP
732 defaults to solid arrowheads and an \fBarrowhead\fP value of\~1; a
733 value of\~0 produces open arrowheads. Note that solid arrowheads are
734 always filled with the current outline color.
739 It's also possible to change the line thickness of an object (this is
740 a GNU extension, DWB \fBpic\fP doesn't support it).
741 The default thickness of the lines used to draw objects is controlled by the
744 This gives the thickness of lines in points.
745 A negative value means use the default thickness:
746 in \*[tx] output mode, this means use a thickness of 8 milliinches;
747 in \*[tx] output mode with the
749 option, this means use the line thickness specified by
751 lines; in troff output mode, this means use a thickness proportional
752 to the pointsize. A zero value means draw the thinnest possible line
753 supported by the output device. Initially it has a value of -1.
754 There is also a \fBthickness\fP attribute (which can be abbreviated to
755 \fBthick\fP). For example, \fBcircle thickness 1.5\fP would draw a
756 circle using a line with a thickness of 1.5 points. The thickness of
757 lines is not affected by the value of the
759 variable, nor by any width or height given in the
766 The modifier \fBinvis[ible]\fP makes an object entirely invisible. This
767 used to be useful for positioning text in an invisible object that is
768 properly joined to neighboring ones. Newer DWB versions and GNU
769 \fBpic\fP treat stand-alone text in exactly this way.
774 It is possible to fill boxes, circles, and ellipses. The
775 modifier \fBfill[ed]\fP accomplishes this. You can suffix it with a fill
776 value; the default is given by the style variable \fBfillval\fP.
778 DWB \fBpic\fP and \fBgpic\fP have opposite conventions for fill values
779 and different defaults. DWB \fBfillval\fP defaults to 0.3 and smaller
780 values are darker; GNU \fBfillval\fP uses 0 for white and 1 for black.
783 circle fill; move; circle fill 0.4; move; circle fill 0.9;
785 .CE "6: \fBcircle fill; move; circle fill 0.4; move; circle fill 0.9;\fR"
787 GNU \fBgpic\fP makes some additional guarantees. A fill value greater
788 than 1 can also be used: this means fill with the shade of gray that
789 is currently being used for text and lines. Normally this is
790 black, but output devices may provide a mechanism for changing this.
791 The invisible attribute does not affect the filling of objects. Any
792 text associated with a filled object is added after the object
793 has been filled, so that the text is not obscured by the filling.
795 The closed-object modifier \fBsolid\fP is equivalent to \fBfill\fP
796 with the darkest fill value (DWB \fBpic\fP had this capability but
797 mentioned it only in a reference section).
802 As a GNU extension, three additional modifiers are available to specify
803 colored objects. \fBoutline\fP sets the color of the outline, \fBshaded\fP
804 the fill color, and \fBcolor\fP sets both. All three keywords expect a
805 suffix specifying the color. Example:
808 box color "yellow"; arrow color "cyan"; circle shaded "green" outline "black";
810 .CE "7: \fBbox color ""yellow""; arrow color ""cyan""; \
811 circle shaded ""green"" outline ""black"";\fR"
813 Alternative spellings are \fBcolour\fP, \fBcolored\fP, \fBcoloured\fP,
816 Predefined color names for \fI[gtn]roff\/\fP-based \fBpic\fP
817 implementations are defined in the device macro files, for example
818 \f(CWps.tmac\fP; additional colors can be defined with the
819 \fB.defcolor\fP request (see the manual page of GNU \fItroff\/\fP(1)
820 for more details). Currently, color support is not available at all
823 The \fIpic2plot\/\fP(1) carries with its own set of color names,
824 essentially those recognized by the X\~window system with \[lq]grey\[rq]
825 accepted as a variant of \[lq]gray\[rq].
827 \fBpic\fP assumes that at the beginning of a picture both glyph and fill
828 color are set to the default value.
832 More About Text Placement
834 By default, text is centered at the geometric center of the object it is
835 associated with. The modifier \fBljust\fP causes the left end to be
836 at the specified point (which means that the text lies to the right of
837 the specified place!), the modifier \fBrjust\fP puts the right end at
838 the place. The modifiers \fBabove\fP and \fBbelow\fP center the text
839 one half line space in the given direction.
841 Text attributes can be combined:
844 [line up "ljust text" ljust;]
846 [line up "rjust text" rjust;]
848 [arrow 1 "ljust above" ljust above;]
850 [arrow 1 "rjust below" rjust below;]
852 .CE "1: Text attributes"
854 What actually happens is that \fIn\fP text strings are centered in a box
855 that is \fBtextwid\fP wide by \fBtextht\fP high. Both these variables
856 are initially zero (that is \fBpic\fR's way of not making assumptions
857 about \fI[tg]roff\/\fP(1)'s default point size).
859 In GNU \fBgpic\fR, objects can have an
862 This only works if the postprocessor is
864 Any text associated with an object having the
866 attribute is rotated about the center of the object
867 so that it is aligned in the direction from the start point
868 to the end point of the object.
869 Note that this attribute has no effect for objects whose start and
870 end points are coincident.
874 More About Direction Changes
876 We've already seen how to change the direction in which objects are
877 composed from rightwards to downwards. Here are some more
878 illustrative examples:
883 "\fBright; box; arrow; circle; arrow; ellipse\fP";
885 [right; box; arrow; circle; arrow; ellipse;]
887 move down 0.3 from last [] .s;
889 "\fBleft; box; arrow; circle; arrow; ellipse\fP"
891 [left; box; arrow; circle; arrow; ellipse;]
893 # move down 0.3 from last [] .sw;
894 # To re-join this illustrations, delete everything from here down to
895 # the next #-comment, and uncomment the move line above
897 .CE "1: Effects of different motion directions (right and left)"
900 # To re-join this illustrations, delete everything down to here, then
901 # comment out the next `down' line.
902 # Don't forget to re-number the figures following!
905 "\fBdown; box; arrow; circle; arrow; ellipse;\fP"
907 box; arrow; circle; arrow; ellipse;
909 move right 2 from last [] .e;
911 up; box; arrow; circle; arrow; ellipse;
913 "\fBup; box; arrow; circle; arrow; ellipse;\fP"
916 .CE "2: Effects of different motion directions (up and down)"
918 Something that may appear surprising happens if you change directions
922 box; arrow; circle; down; arrow; ellipse
924 .CE "3: \fBbox; arrow; circle; down; arrow; ellipse\fP"
926 You might have expected that program to yield this:
929 box; arrow; circle; move to last circle .s; down; arrow; ellipse
931 .CE "4: More intuitive?"
933 But, in fact, to get Figure \*[SN]3 you have to do this:
941 move to last circle .s;
950 Why is this? Because the exit point for the current direction is
951 already set when you draw the object. The second arrow in Figure
952 \*[SN]2 dropped downwards from the circle's attachment point for an
953 object to be joined to the right.
955 The meaning of the command \fBmove to last circle .s\fP should be obvious.
956 In order to see how it generalizes, we'll need to go into detail on two
957 important topics; locations and object names.
963 The most natural way to name locations in \fBpic\fP is relative to
964 objects. In order to do this, you have to be able you have to be able
965 to name objects. The \fBpic\fP language has rich facilities for this
966 that try to emulate the syntax of English.
969 Naming Objects By Order Of Drawing
971 The simplest (and generally the most useful) way to name an object is
972 with a \fBlast\fP clause. It needs to be followed by an object type
973 name; \fBbox\fP, \fBcircle\fP, \fBellipse\fP, \fBline\fP, \fBarrow\fP,
974 \fBspline\fP, \fB""\fP, or \fB[]\fP (the last type refers to a \fIcomposite
975 object\fP which we'll discuss later). So, for example, the \fBlast
976 circle\fP clause in the program attached to Figure \*[SN]3 refers to the
979 More generally, objects of a given type are implicitly numbered
980 (starting from\~1). You can refer to (say) the third ellipse in the
981 current picture with \fB3rd ellipse\fP, or to the first box as \fB1st
982 box\fP, or to the fifth text string (which isn't an attribute to another
983 object) as \fB5th ""\fP.
985 Objects are also numbered backwards by type from the last one.
986 You can say \fB2nd last box\fP to get the second-to-last box, or
987 \fB3rd last ellipse\fP to get the third-to-last ellipse.
989 In places where \fIn\/\fBth\fR is allowed, \fB`\fIexpr\/\fB'th\fR is
990 also allowed. Note that
992 is a single token: no space is allowed between the
1001 line from `i'th box.nw to `i+1'th box.se
1008 Naming Objects With Labels
1010 You can also specify an object by referring to a label. A label is a
1011 word (which must begin with a capital letter) followed by a colon;
1012 you declare it by placing it immediately before the object drawing command.
1013 For example, the program
1018 A: box "first" "object"
1020 B: ellipse "second" "object"
1022 arrow right at A .r;
1028 declares labels \fBA\fP and \fBB\fP for its first and second objects.
1029 Here's what that looks like:
1032 A: box "first" "object"
1034 B: ellipse "second" "object"
1036 arrow right at A .r;
1038 .CE "1: Example of label use"
1039 The \fBat\fP statement in the fourth line uses the label \fBA\fP (the
1040 behavior of \fBat\fP is explained in the next section). We'll
1041 see later on that labels are most useful for referring to block composite
1044 Labels are not constants but variables (you can view colon as a sort
1045 of assignment). You can say something like \fBA: A + (1,0);\fP
1046 and the effect is to reassign the label \fBA\fR to designate a
1047 position one inch to the right of its old value.
1051 Describing locations
1053 The location of points can be described in many different ways. All these
1054 forms are interchangeable as for as the \fBpic\fP language syntax is
1055 concerned; where you can use one, any of the others that would make
1056 semantic sense are allowed.
1058 The special label \fBHere\fR always refers to the current position.
1061 Absolute Coordinates
1063 The simplest is absolute coordinates in inches; \fBpic\fP uses a
1064 Cartesian system with (0,0) at the lower left corner of the virtual
1065 drawing surface for each picture (that is, X\~increases to the right
1066 and Y\~increases upwards). An absolute location may always be written in the
1067 conventional form as two comma-separated numbers surrounded by
1068 parentheses (and this is recommended for clarity). In contexts where
1069 it creates no ambiguity, the pair of X and Y\~coordinates suffices
1070 without parentheses.
1072 It is a good idea to avoid absolute coordinates, however. They tend
1073 to make picture descriptions difficult to understand and modify.
1074 Instead, there are quite a number of ways to specify locations
1075 relative to \fBpic\fP objects and previous locations.
1077 Another possibility of surprise is the fact that \fBpic\fP crops the
1078 picture to the smallest bounding box before writing it out. For
1079 example, if you have a picture consisting of a small box with its lower
1080 left corner at (2,2) and another small box with its upper right corner
1081 at (5,5), the width and height of the image are both 3\~units and
1082 not\~5. To get the origin at (0,0) included, simply add an invisible
1083 object to the picture, positioning the object's left corner at (0,0).
1086 Locations Relative to Objects
1088 The symbol \fBHere\fP always refers to the position of the last object
1089 drawn or the destination of the last \fBmove\fP.
1091 Alone and unqualified, a \fBlast circle\fP or any other way of
1092 specifying a closed-object or arc location refers as a position to the
1093 geometric center of the object. Unqualified, the name of a line or
1094 spline object refers to the position of the object start.
1096 Also, \fBpic\fP objects have quite a few named locations
1097 associated with them. One of these is the object center, which can be
1098 indicated (redundantly) with the suffix \fB.center\fP (or just \fB.c\fP).
1099 Thus, \fBlast circle \&.center\fP is equivalent to \fBlast
1102 Locations Relative to Closed Objects
1104 Every closed object (box, circle, ellipse, or block composite) also
1105 has eight compass points associated with it;
1108 define dot {circle fill rad 0.02 at $1}
1112 dot(ME.c); "\fB .c\fP" at ME .c ljust;
1113 dot(ME.n); "\fB.n\fP" at ME .n above
1114 dot(ME.ne); "\fB .ne\fP" at ME .ne above
1115 dot(ME.e); "\fB .e\fP" at ME .e ljust
1116 dot(ME.se); "\fB .se\fP" at ME .se below
1117 dot(ME.s); "\fB.s\fP" at ME .s below
1118 dot(ME.sw); "\fB.sw \fP" at ME .sw below
1119 dot(ME.w); "\fB.w \fP" at ME .w rjust
1120 dot(ME.nw); "\fB.nw \fP" at ME .nw above
1122 compass(box wid 1.5 ht 1);
1123 move right from last [] .e;
1124 compass(circle diam 1);
1125 move right from last [] .e;
1126 compass(ellipse wid 1.5 ht 1);
1128 .CE "1: Compass points"
1130 these are the locations where eight compass rays from the geometric center
1131 would intersect the figure. So when we say \fBlast circle .s\fP we are
1132 referring to the south compass point of the last circle drawn. The
1133 explanation of Figure 7.3's program is now complete.
1135 (In case you dislike compass points, the names \fB.top\fP,
1136 \&\fB.bottom\fP, \fB.left\fP and \fB.right\fP are synonyms for \fB.n\fP,
1137 \&\fB.s\fP, \fB.e\fP, and \fB.w\fP respectively; they can even be
1138 abbreviated to \fB.t\fP, \fB.b\fP, \fB.l\fP and \fB.r\fP).
1140 The names \fBcenter\fP, \fBtop\fP, \fBbottom\fP, \fBleft\fP, \fBright\fP,
1141 \fBnorth\fP, \fBsouth\fP, \fBeast\fP, and \fBwest\fP can also be used
1142 (without the leading dot) in a prefix form marked by \fBof\fP; thus,
1143 \fBcenter of last circle\fP and \fBtop of 2nd last ellipse\fP are both
1144 valid object references. Finally, the names \fBleft\fP and \fBright\fP
1145 can be prefixed with \fBupper\fP and \fBlower\fP which both have the
1148 Arc objects also have compass points; they are the compass points of
1151 Non-closed objects (line, arrow, or spline) have compass points too, but
1152 the locations of them are completely arbitrary. In particular, different
1153 \fBpic\fP implementations return different locations.
1155 Locations Relative to Open Objects
1157 Every open object (line, arrow, arc, or spline) has three named
1158 points: \fB.start\fP, \fB.center\fP (or \fB.c\fP), and \fB.end\fP. They
1159 can also be used without leading dots in the \fBof\fP prefix form.
1160 The center of an arc is the center of its circle, but the center of
1161 a line, path, or spline is halfway between its endpoints.
1166 dot(ME.c); "\fB.center\fP" rjust at ME.center + (-0.1, 0.1)
1167 dot(ME.start); "\fB.start\fP" rjust at ME.start + (-0.1, 0.1)
1168 dot(ME.end); "\fB.end\fP" rjust at ME.end + (-0.1, 0.1)
1171 critical(line up right 1);
1172 move right 1 from last [] .e;
1173 critical(arc rad 0.5 cw);
1174 move down 0.5 from 2nd last [] .s;
1175 critical(line right 1 then down .5 left 1 then right 1);
1176 move right 1 from last [] .e;
1177 critical(spline right 1 then up right then left then left 1);
1179 .CE "2: Special points on open objects"
1183 Ways of Composing Positions
1185 Once you have two positions to work with, there are several ways to
1186 combine them to specify new positions.
1188 Vector Sums and Displacements
1190 Positions may be added or subtracted to yield a new position (to be
1191 more precise, you can only add a position and an expression pair; the
1192 latter must be on the right side of the addition or subtraction sign).
1193 The result is the conventional vector sum or difference of coordinates.
1194 For example, \fBlast box .ne + (0.1, 0)\fP is a valid position. This
1195 example illustrates a common use, to define a position slightly offset
1196 from a named one (say, for captioning purposes).
1198 Interpolation Between Positions
1200 A position may be interpolated between any two positions. The syntax
1201 is `\fIfraction\fP \fBof the way between\fP \fIposition1\fP \fBand\fP
1202 \fIposition2\fP'. For example, you can say \fB1/3 of the way between
1203 here and last ellipse .ne\fP. The fraction may be in
1204 numerator/denominator form or may be an ordinary number (values are
1205 \fInot\fP restricted to [0,1]). As an alternative to this verbose
1206 syntax, you can say `\fIfraction\fP \fB<\,\fP\fIposition1\fP \fB,\fP
1207 \fIposition2\/\fP\fB>\fP'; thus, the example could also be written as
1208 \fB1/3 <here, last ellipse>\fP.
1212 P: 1/3 of the way between last arrow .start and last arrow .end;
1213 dot(P); move right 0.1; "P";
1215 .CE "3: \fBP: 1/3 of the way between last arrow .start and last arrow .end\fP"
1217 This facility can be used, for example, to draw double connections.
1222 arrow right at 1/4 <A.e,A.ne>;
1223 arrow left at 1/4 <B.w,B.sw>;
1225 .CE "4: Doubled arrows"
1227 You can get Figure \n[H1]-4 from the following program:
1234 arrow right at 1/4 <A.e,A.ne>;
1235 arrow left at 1/4 <B.w,B.sw>;
1241 Note the use of the short form for interpolating points.
1243 Projections of Points
1245 Given two positions \fIp\fP and \fIq\fP, the position
1246 \fB(\,\fP\fIp\fP\fB,\fP \fIq\fP\fB)\fP has the X\~coordinate of \fIp\fP
1247 and the Y coordinate of \fIq\fP. This can be helpful in placing an
1248 object at one of the corners of the virtual box defined by two other
1252 box invis wid 2 height 1;
1253 dot(last box .ne); "\fB(B,A)\fP is here" ljust at last circle + (0.1, 0.1);
1254 dot(last box .se); "B" ljust at last circle + (0.1, -0.1)
1255 dot(last box .sw); "\fB(A,B)\fP is here" rjust at last circle + (-0.1, -0.1);
1256 dot(last box .nw); "A" ljust at last circle + (-0.1, 0.1)
1258 .CE "5: Using (\fIx\fP, \fIy\fP) composition"
1263 There are four ways to use locations; \fBat\fP, \fBfrom\fP, \fBto\fP,
1264 and \fBwith\fP. All four are object modifiers; that is, you use them
1265 as suffixes to a drawing command.
1267 The \fBat\fP modifier says to draw a closed object or arc with its
1268 center at the following location, or to draw a line/spline/arrow
1269 starting at the following location.
1271 The \fBto\fP modifier can be used alone to specify a move destination.
1272 The \fBfrom\fP modifier can be used alone in the same way as \fBat\fP.
1274 The \fBfrom\fP and \fBto\fP modifiers can be used with a \fBline\fR or
1275 \fBarc\fR command to specify start and end points of the object. In
1276 conjunction with named locations, this offers a very flexible
1277 mechanism for connecting objects. For example, the following program
1285 arc cw from 1/3 of the way \e
1286 between last box .n and last box .ne to last ellipse .n;
1298 arc cw from 1/3 of the way \
1299 between last box .n and last box .ne to last ellipse .n;
1301 .CE "6: A tricky connection specified with English-like syntax"
1303 The \fBwith\fP modifier allows you to identify a named attachment
1304 point of an object (or a position within the object) with another point.
1305 This is very useful for connecting objects in a natural way. For an
1306 example, consider these two programs:
1312 box wid 0.75 ht 0.75;
1314 move down 0.3 from last [] .s 0.1;
1315 "\fBbox wid 0.5 ht 0.5; box wid 0.75 ht 0.75\fP"
1317 move from last [].e 1.5
1321 box wid 0.75 ht 0.75 with .sw at last box .se;
1323 move down 0.3 from last [] .s 0.1;
1324 box invisible "\fBbox wid 0.5 ht 0.5;\fP" \
1325 "\fBbox wid 0.75 ht 0.75 with .sw at last box .se;\fP"
1328 .CE "7: Using the \fBwith\fP modifier for attachments"
1333 When drawing lines between circles that don't intersect them at a
1334 compass point, it is useful to be able to shorten a line by the radius
1335 of the circle at either or both ends. Consider the following program:
1341 circle "y" at 1st circle - (0.4, 0.6)
1342 circle "z" at 1st circle + (0.4, -0.6)
1343 arrow from 1st circle to 2nd circle chop
1344 arrow from 2nd circle to 3rd circle chop
1345 arrow from 3rd circle to 1st circle chop
1351 It yields the following:
1355 circle "y" at 1st circle - (0.4, 0.6)
1356 circle "z" at 1st circle + (0.4, -0.6)
1357 arrow from 1st circle to 2nd circle chop
1358 arrow from 2nd circle to 3rd circle chop
1359 arrow from 3rd circle to 1st circle chop
1361 .CE "8: The \fBchop\fR modifier"
1363 Notice that the \fBchop\fR attribute moves arrowheads rather than
1364 stepping on them. By default, the \fBchop\fR modifier shortens both
1365 ends of the line by \fBcirclerad\fR. By suffixing it with a number
1366 you can change the amount of chopping.
1368 If you say \fBline .\|.\|.\& chop \fIr1\fP chop \fIr2\fP\fR with \fIr1\fP
1369 and \fIr2\fP both numbers, you can vary the amount of chopping at both
1370 ends. You can use this in combination with trigonometric functions
1371 to write code that deals with more complex intersections.
1377 There are two different ways to group objects in \fBpic\fP; \fIbrace
1378 grouping\fP and \fIblock composites\fP.
1383 The simpler method is simply to group a set of objects within curly
1384 bracket or brace characters. On exit from this grouping, the current
1385 position and direction are restored to their value when the opening
1386 brace was encountered.
1391 A block composite object is created a series of commands enclosed by
1392 square brackets. The composite can be treated for most purposes like
1393 a single closed object, with the size and shape of its bounding box.
1394 Here is an example. The program fragment
1400 line up 1 at last circle .n;
1401 line down 1 at last circle .s;
1402 line right 1 at last circle .e;
1403 line left 1 at last circle .w;
1404 box dashed with .nw at last circle .se + (0.2, -0.2);
1405 Caption: center of last box;
1411 yields the block in figure \n[H1]-1, which we show both with and
1412 without its attachment points. The block's location becomes the
1418 line up 1 at last circle .n;
1419 line down 1 at last circle .s;
1420 line right 1 at last circle .e;
1421 line left 1 at last circle .w;
1422 box dashed with .nw at last circle .se + (0.2, -0.2);
1423 Caption: center of last box;
1427 compass([junction()]);
1429 .CE "1: A sample composite object"
1431 To refer to one of the composite's attachment points, you can say
1432 (for example) \fBA .s\fP. For purposes of object naming, composites
1433 are a class. You could write \fBlast [] .s\fP as an equivalent
1434 reference, usable anywhere a location is needed. This construction is
1435 very important for putting together large, multi-part diagrams.
1437 Blocks are also a variable-scoping mechanism, like a \fIgroff\/\fP(1)
1438 environment. All variable assignments done inside a block are undone
1439 at the end of it. To get at values within a block, write a name of
1440 the block followed by a dot, followed by the label you
1441 want. For example, we could refer the the center of the box in the
1442 above composite as \fBlast [] .Caption\fP or \fBA.Caption\fP.
1444 This kind of reference to a label can be used in any way any other
1445 location can be. For example, if we added \fB"Hi!" at A.Caption\fP
1446 the result would look like this:
1452 .CE "2: Adding a caption using interior labeling"
1454 You can also use interior labels in either part of a \fBwith\fR
1455 modifier. This means that the example composite could be placed
1456 relative to its caption box by a command containing \fBwith A.Caption
1459 Note that both width and height of the block composite object are always
1466 box wid 0.75 ht 0.75
1468 move down 0.3 from last [].s 0.1
1469 "\fBbox wid -0.5 ht 0.5; box wid 0.75 ht 0.75\fP"
1471 move from last [].e 2
1474 [ box wid -0.5 ht 0.5 ]
1475 box wid 0.75 ht 0.75
1477 move down 0.3 from last [].s 0.1
1478 "\fB[box wid -0.5 ht 0.5]; box wid 0.75 ht 0.75\fP"
1481 .CE "3: Composite block objects always have positive width and height"
1483 Blocks may be nested. This means you can use block attachment points
1484 to build up complex diagrams hierarchically, from the inside out.
1485 Note that \fBlast\fP and the other sequential naming mechanisms
1486 don't look inside blocks, so if you have a program that looks
1492 P: [box "foo"; ellipse "bar"];
1494 [box "baz"; ellipse "quxx"]
1497 arrow from 2nd last [];
1503 the arrow in the last line is attached to object \fBP\fP, not
1506 In DWB \fBpic\fP, only references one level deep into enclosed blocks
1507 were permitted. GNU \fBgpic\fP removes this restriction.
1509 The combination of block variable scoping, assignability of labels and
1510 the macro facility that we'll describe later on can be used to
1511 simulate functions with local variables (just wrap the macro body in
1518 There are a number of global style variables in \fBpic\fR that can be used to
1519 change its overall behavior. We've mentioned several of them in
1520 previous sections. They're all described here. For each variable,
1521 the default is given.
1523 center, tab(@), linesize(2);
1527 Style Variable@Default@What It Does
1532 boxht@0.5@Default height of a box
1533 boxwid@0.75@Default width of a box
1534 lineht@0.5@Default length of vertical line
1535 linewid@0.75@Default length of horizontal line
1536 linethick@-1@Default line thickness
1537 arcrad @0.25@Default radius of an arc
1538 circlerad@0.25@Default radius of a circle
1539 ellipseht@0.5@Default height of an ellipse
1540 ellipsewid@0.75@Default width of an ellipse
1541 moveht@0.5@Default length of vertical move
1542 movewid@0.75@Default length of horizontal move
1543 textht@0@Default height of box enclosing a text object
1544 textwid@0@Default width of box enclosing a text object
1545 arrowht@0.1@Length of arrowhead along shaft
1546 arrowwid@0.05@Width of rear of arrowhead
1547 arrowhead@1@Enable/disable arrowhead filling
1548 dashwid@0.05@Interval for dashed lines
1549 maxpswid@8.5@Maximum width of picture
1550 maxpsht@11@Maximum height of picture
1551 scale@1@Unit scale factor
1552 fillval@0.5@Default fill value
1556 Any of these variables can be set with a simple assignment statement.
1560 [boxht=1; boxwid=0.3; movewid=0.2; box; move; box; move; box; move; box;]
1562 .CE "1: \fBboxht=1; boxwid=0.3; movewid=0.2; box; move; box; move; box; move; box;\fP"
1564 In GNU \fBpic\fR, setting the \fBscale\fR variable re-scales all
1565 size-related state variables so that their values remain equivalent in
1568 The command \fBreset\fP resets all style variables to their defaults.
1569 You can give it a list of variable names as arguments (optionally
1570 separated by commas), in which case it resets only those.
1572 State variables retain their values across pictures until reset.
1576 Expressions, Variables, and Assignment
1578 A number is a valid expression, of course (all numbers are stored
1579 internally as floating-point). Decimal-point notation is acceptable;
1580 in GNU \fBgpic\fR, scientific notation in C's `e' format (like
1581 \f(CW5e-2\fP) is accepted.
1583 Anywhere a number is expected, the language also accepts a
1584 variable. Variables may be the built-in style variable described in
1585 the last section, or new variables created by assignment.
1587 DWB \fBpic\fP supports only the ordinary assignment via \fB=\fP, which
1588 defines the variable (on the left side of the equal sign) in the current
1589 block if it is not already defined there, and then changes the value (on
1590 the right side) in the current block. The variable is not visible outside
1591 of the block. This is similar to the C\~programming language where a
1592 variable within a block shadows a variable with the same name outside of
1595 GNU \fBgpic\fP supports an alternate form of assignment using \fB:=\fP.
1596 The variable must already be defined, and the value is assigned to
1597 that variable without creating a variable local to the current block.
1614 You can use the height, width, radius, and x and y coordinates of any
1615 object or corner in expressions. If \fBA\fP is an object label or name,
1616 all the following are valid:
1620 A.x # x coordinate of the center of A
1621 A.ne.y # y coordinate of the northeast corner of A
1622 A.wid # the width of A
1623 A.ht # and its height
1624 2nd last circle.rad # the radius of the 2nd last circle
1629 Note the second expression, showing how to extract a corner coordinate.
1631 Basic arithmetic resembling those of C operators are available; \fB+\fP,
1632 \fB*\fP, \fB-\fP, \fB/\fP, and \fB%\fP. So is \fB^\fP for exponentiation.
1633 Grouping is permitted in the usual way using parentheses. GNU \fBgpic\fP
1634 allows logical operators to appear in expressions; \fB!\&\fP (logical
1635 negation, not factorial), \fB&&\fP, \fB|\||\fP, \fB==\fP, \fB!=\fP,
1636 \fB>=\fP, \fB<=\fP, \fB<\fP, \fB>\fP.
1638 Various built-in functions are supported: \fBsin(\fIx\fB)\fR,
1639 \fBcos(\fIx\fB)\fR, \fBlog(\fIx\fB)\fR, \fBexp(\fIx\fB)\fR,
1640 \fBsqrt(\fIx\fB)\fR, \fBmax(\fIx\fB,\fIy\fB)\fR,
1641 \fBatan2(\fIx\fB,\fIy\fB)\fR, \fBmin(\fIx\fB,\fIy\fB)\fR,
1642 \fBint(\fIx\fB)\fR, \fBrand()\fP, and \fBsrand()\fP.
1643 Both \fBexp\fP and \fBlog\fP are
1644 base\~10; \fBint\fP does integer truncation; \fBrand()\fP returns a
1645 random number in [0-1), and \fBsrand()\fP sets the seed for
1646 a new sequence of pseudo-random numbers to be returned by \fBrand()\fP
1647 (\fBsrand()\fP is a GNU extension).
1649 GNU \fBgpic\fP also documents a one-argument form or rand,
1650 \fBrand(\fIx\fB)\fR, which returns a random number between 1 and
1651 \fIx\fP, but this is deprecated and may be removed in a future
1654 The function \fBsprintf()\fP behaves like a C \fIsprintf\/\fP(3)
1655 function that only takes %, %e, %f, and %g format strings.
1661 You can define macros in \fBpic\fP, with up to 32 arguments (up to 16
1662 on EBCDIC platforms). This is useful for diagrams with
1663 repetitive parts. In conjunction with the scope rules for block
1664 composites, it effectively gives you the ability to write functions.
1669 \fBdefine\fP \fIname\fP \fB{\fP \fIreplacement text \fB}\fP
1673 This defines \fIname\fR as a macro to be replaced by the replacement
1674 text (not including the braces). The macro may be called as
1677 \fIname\fB(\fIarg1, arg2, \|.\|.\|.\& argn\fB)\fR
1681 The arguments (if any) are substituted for tokens \fB$1\fP, \fB$2\fP
1682 \&.\|.\|.\& \fB$n\fP
1683 appearing in the replacement text.
1685 As an example of macro use, consider this:
1692 # Plot a single jumper in a box, $1 is the on-off state.
1695 Outer: box invis wid 0.45 ht 1;
1697 # Count on end ] to reset these
1698 boxwid = Outer.wid * shrinkfactor / 2;
1699 boxht = Outer.ht * shrinkfactor / 2;
1701 box fill (!$1) with .s at center of Outer;
1702 box fill ($1) with .n at center of Outer;
1705 # Plot a block of six jumpers.
1706 define jumperblock {
1714 jwidth = last [].Outer.wid;
1715 jheight = last [].Outer.ht;
1717 box with .nw at 6th last [].nw wid 6*jwidth ht jheight;
1719 # Use {} to avoid changing position from last box draw.
1720 # This is necessary so move in any direction works as expected
1721 {"Jumpers in state $1$2$3$4$5$6" at last box .s + (0,-0.2);}
1724 # Sample macro invocations.
1725 jumperblock(1,1,0,0,1,0);
1727 jumperblock(1,0,1,0,1,1);
1735 It yields the following:
1738 # Plot a single jumper in a box, $1 is the on-off state.
1741 Outer: box invis wid 0.45 ht 1;
1743 # Count on end ] to reset these
1744 boxwid = Outer.wid * shrinkfactor / 2;
1745 boxht = Outer.ht * shrinkfactor / 2;
1747 box fill (!$1) with .s at center of Outer;
1748 box fill ($1) with .n at center of Outer;
1751 # Plot a block of six jumpers
1752 define jumperblock {
1760 jwidth = last [].Outer.wid;
1761 jheight = last [].Outer.ht;
1763 box with .nw at 6th last [].nw wid 6*jwidth ht jheight;
1765 # Use {} to avoid changing position from last box draw.
1766 # This is necessary so move in any direction works as expected
1767 {"Jumpers in state $1$2$3$4$5$6" at last box .s + (0,-0.2);}
1770 # Sample macro invocations
1771 jumperblock(1,1,0,0,1,0);
1773 jumperblock(1,0,1,0,1,1);
1775 .CE "1: Sample use of a macro"
1777 This macro example illustrates how you can combine [], brace grouping,
1778 and variable assignment to write true functions.
1780 One detail the example above does not illustrate is the fact that
1781 macro argument parsing is not token-oriented. If you call
1782 \fBjumper(\ 1\ )\fP, the value of $1 is \fB"\ 1\ "\fP. You could
1783 even call \fBjumper(big\ string)\fP to give $1 the value
1784 \fB"big\ string"\fP.
1786 If you want to pass in a coordinate pair, you can avoid getting
1787 tripped up by the comma by wrapping the pair in parentheses.
1789 Macros persist through pictures. To undefine a macro, say \fBundef\fP
1790 \fIname\fR; for example,
1792 \f(CWundef jumper\fP
1793 \f(CWundef jumperblock\fP
1796 would undefine the two macros in the jumper block example.
1800 Import/Export Commands
1802 Commands that import or export data between \fBpic\fR and its
1803 environment are described here.
1806 File and Table Insertion
1810 \f(CWcopy\fP \fIfilename\fR
1813 inserts the contents of \fIfilename\fR in the \fBpic\fP input stream.
1814 Any \fB.PS\fP/\fB.PE\fP pair in the file is ignored. You
1815 can use this to include pre-generated images.
1817 A variant of this statement replicates the \fBcopy thru\fP feature of
1818 \fIgrap\/\fP(1). The call
1820 \f(CWcopy\fP \fIfilename\fR \f(CWthru\fP \fImacro\fP
1823 calls \fImacro\fP (which may be either a name or replacement text)
1824 on the arguments obtained by breaking each line of the file into
1825 blank-separated fields. The macro may have up to 9\~arguments. The
1826 replacement text may be delimited by braces or by a pair of instances
1827 of any character not appearing in the rest of the text.
1831 \f(CWcopy\fP \f(CWthru\fP \fImacro\fP
1834 omitting the filename, lines to be parsed are taken from the input
1835 source up to the next \fB.PE\fP.
1837 In either of the last two \fBcopy\fP commands, GNU \fBgpic\fP permits a
1838 trailing `\fBuntil\fP \fIword\/\fP' clause to be added which terminates
1839 the copy when the first word matches the argument (the default
1840 behavior is therefore equivalent to \fBuntil .PE\fP).
1842 Accordingly, the command
1849 copy thru % circle at ($1,$2) % until "END"
1881 The command \fBprint\fR accepts any number of arguments, concatenates
1882 their output forms, and writes the result to standard error. Each
1883 argument must be an expression, a position, or a text string.
1886 Escape to Post-Processor
1890 \fBcommand\fR \fIarg\fR\|.\|.\|.
1893 \fBpic\fP concatenates the arguments and pass them through as a line
1894 to troff or \*[tx]. Each
1896 must be an expression, a position, or text.
1897 This has a similar effect to a line beginning with
1901 but allows the values of variables to be passed through.
1910 command ".ds string x is " x "."
1925 Executing Shell Commands
1929 \f(CWsh\fP \f(CW{\fP \fIanything.\|.\|.\fP \f(CW}\fP
1932 macro-expands the text in braces, then executes it as a shell command.
1933 This could be used to generate images or data tables for later
1934 inclusion. The delimiters shown as {} here may also be two copies of
1935 any one character not present in the shell command text. In either
1936 case, the body may contain balanced {} pairs. Strings in the body
1937 may contain balanced or unbalanced braces in any case.
1941 Control-flow constructs
1943 The \fBpic\fP language provides conditionals and looping. For
1949 for i = 0 to 2 * pi by 0.1 do {
1951 "." at (i/2, sin(i)/2);
1952 ":" at (i/2, cos(i)/2);
1962 for i = 0 to 2 * pi by 0.1 do {
1964 "." at (i/2, sin(i)/2);
1965 ":" at (i/2, cos(i)/2);
1968 .CE "1: Plotting with a \fBfor\fP loop"
1970 The syntax of the \fBfor\fP statement is:
1972 \fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\/\fR \fBto\fR \fIexpr2\/\fR \
1973 [\fBby\fR [\fB*\fR]\fIexpr3\/\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR
1975 The semantics are as follows: Set
1980 is less than or equal to
1990 is not given, increment
1999 is multiplied instead by
2003 can be negative for the additive case;
2005 is then tested whether it is greater than or equal to
2007 For the multiplicative case,
2009 must be greater than zero.
2010 If the constraints aren't met, the loop isn't executed.
2012 can be any character not occurring in
2013 \fIbody\fR; or the two \fIX\/\fPs may be paired braces (as in the
2016 The syntax of the \fBif\fP statement is as follows:
2018 \fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \
2019 [\fBelse\fR \fIY\fR \fIif-false\fR \fIY\/\fR]
2021 Its semantics are as follows: Evaluate
2023 if it is non-zero then do
2028 can be any character not occurring in
2031 can be any character not occurring in
2034 Eithe or both of the
2038 pairs may instead be balanced pairs of
2039 braces ({ and\~}) as in the \fBsh\fR command. In either case, the
2040 \fIif-true\fR may contain balanced pairs of braces. None of these
2041 delimiters are seen inside strings.
2043 All the usual relational operators my be used in conditional expressions;
2044 \fB!\&\fP (logical negation, not factorial), \fB&&\fP, \fB|\||\fP, \fB==\fP,
2045 \fB!=\fP, \fB>=\fP, \fB<=\fP, \fB<\fP, \fB>\fP.
2047 String comparison is also supported using \fB==\fP and \fB!=\fP. String
2048 comparisons may need to be parenthesized to avoid syntactic
2053 Interface To [gt]roff
2055 The output of \fBpic\fP is \fB[gt]roff\fP drawing commands. The GNU
2056 \fIgpic\/\fP(1) command warns that it relies on drawing extensions
2057 present in \fIgroff\/\fP(1) that are not present in \fItroff\/\fP(1).
2062 The DWB \fIpic\/\fP(1) program accepts one or two arguments to
2063 \&\fB.PS\fP, which is interpreted as a width and height in inches to
2064 which the results of \fIpic\/\fP(1) should be scaled (width and height
2065 scale independently). If there is only one argument, it is
2066 interpreted as a width to scale the picture to, and height is
2067 scaled by the same proportion.
2069 GNU \fBgpic\fP is less general; it accepts a single width to scale
2070 to, or a zero width and a maximum height to scale to. With
2071 two non-zero arguments, it scales to the maximum height.
2074 How Scaling is Handled
2076 When \fBpic\fP processes a picture description on input, it passes
2077 \fB.PS\fP and \fB.PE\fP through to the postprocessor. The \fB.PS\fP
2078 gets decorated with two numeric arguments which are the X and
2079 Y\~dimensions of the picture in inches. The post-processor can use
2080 these to reserve space for the picture and center it.
2082 The GNU incarnation of the \fBms\fP macro package, for example, includes
2083 the following definitions:
2092 \&.ie \e\en[.$]<2 .@error bad arguments to PS (not preprocessed with pic?)
2094 \&. ds@need (u;\e\e$1)+1v
2095 \&. in +(u;\e\en[.l]-\e\en[.i]-\e\e$2/2>?0)
2100 \&.sp \e\en[DD]u+.5m
2108 Equivalent definition is supplied by GNU \fIpic\/\fP(1) if you use
2109 the \-mpic option; this should make it usable with macro pages other
2112 If \fB.PF\fP is used instead of \fB.PE\fP, the \fBtroff\fP position is
2113 restored to what it was at the picture start (Kernighan notes that
2114 the\~F stands for \[lq]flyback\[rq]).
2118 \&\fB.PS <\,\fP\fIfile\fP
2121 causes the contents of \fIfile\fP to replace the \fB.PS\fP line. This
2122 feature is deprecated; use `\fBcopy\fP \fIfile\fR' instead).
2125 PIC and [gt]roff commands
2127 By default, input lines that begin with a period are passed to the
2128 postprocessor, embedded at the corresponding point in the output.
2129 Messing with horizontal or vertical spacing is an obvious recipe for
2130 bugs, but point size and font changes are usually safe.
2132 Point sizes and font changes are also safe within text strings, as
2133 long as they are undone before the end of string.
2135 The state of \fB[gt]roff\fP's fill mode is preserved across pictures.
2140 The Kernighan paper notes that there is a subtle problem with
2141 complicated equations inside \fBpic\fR pictures; they come out wrong if
2142 \fIeqn\/\fP(1) has to leave extra vertical space for the equation.
2143 If your equation involves more than subscripts and superscripts, you
2144 must add to the beginning of each equation the extra information
2145 \fBspace\~0\fP. He gives the following example:
2150 box "$space 0 {H( omega )} over {1 - H( omega )}$"
2161 box "@space 0 {H( omega )} over {1 - H( omega )}@"
2164 .CE "1: Equations within pictures"
2167 Absolute Positioning of Pictures
2169 A \fBpic\fP picture is positioned vertically by troff at the current
2170 position. The topmost position possible on a page is not the paper edge
2171 but a position which is one baseline lower so that the first row of glyphs
2172 is visible. To make a picture really start at the paper edge you have
2173 to make the baseline-to-baseline distance zero, this is, you must set the
2174 vertical spacing to\~0 (using \fB.vs\fP) before starting the picture.
2181 \*[tx] mode is enabled by the
2184 In \*[tx] mode, pic defines a vbox called
2186 for each picture; the name can be changed with the pseudo-variable
2188 (which is actually a specially parsed command).
2189 You must yourself print that vbox using, for example, the command
2193 \ecenterline{\ebox\egraph}
2196 Actually, since the vbox has a height of zero (it is defined with \evtop)
2197 this produces slightly more vertical space above the picture than
2202 \ecenterline{\eraise 1em\ebox\egraph}
2207 To make the vbox having a positive height and a depth of zero (as used
2208 e.g.\& by \*(lx's \f(CW\%graphics.sty\fP), define the following macro in
2214 \evbox{\eunvbox\ecsname #1\eendcsname\ekern 0pt}}
2219 Now you can simply say
2221 instead of \ebox\egraph.
2223 You must use a \*[tx] driver that supports the
2225 specials, version\~2.
2227 Lines beginning with
2229 are passed through transparently; a
2231 is added to the end of the line to avoid unwanted spaces.
2232 You can safely use this feature to change fonts or to
2233 change the value of \fB\ebaselineskip\fP.
2234 Anything else may well produce undesirable results; use at your own risk.
2235 Lines beginning with a period are not given any special treatment.
2237 The \*[tx] mode of \fIpic\/\fP(1) does \fInot\fP translate \fBtroff\fP
2238 font and size changes included in text strings!
2240 Here an example how to use \fBfigname\fP.
2254 \ecenterline{\ebox\efoo \ehss \ebox\ebar}
2259 Use this feature sparsingly and only if really needed:
2260 A different name means a new box register in \*[tx], and the maximum number
2261 of box registers is only 256.
2262 Also be careful not to use a predefined \*[tx] or \*[lx] macro name as
2263 an argument to \fBfigname\fP since this inevitably causes an error.
2269 GNU \fIgpic\/\fP(1) has a command
2271 \fBplot\fR \fIexpr\fR [\fB"\fItext\fB"\fR]
2273 This is a text object which is constructed by using
2275 as a format string for sprintf
2280 is omitted a format string of \fB"%g"\fP is used.
2281 Attributes can be specified in the same way as for a normal text
2283 Be very careful that you specify an appropriate format string;
2284 \fBpic\fP does only very limited checking of the string.
2285 This is deprecated in favour of
2290 Some Larger Examples
2292 Here are a few larger examples, with complete source code.
2293 One of our earlier examples is generated in an instructive way using a
2301 # Draw a demonstration up left arrow with grid box overlay
2307 box wid 0.5 ht 0.5 dotted with .nw at last arrow .end;
2308 for i = 2 to ($1 / 0.5) do
2310 box wid 0.5 ht 0.5 dotted with .sw at last box .se;
2312 move down from last arrow .center;
2314 if ( $1 == boxht ) \e
2315 then { "\efBline up left\efP" } \e
2316 else { sprintf("\efBarrow up left %g\efP", $1) };
2319 move right 0.1 from last [] .e;
2334 # Draw a demonstration up left arrow with grid box overlay
2340 box wid 0.5 ht 0.5 dotted with .nw at last arrow .end;
2341 for i = 2 to ($1 / 0.5) do
2343 box wid 0.5 ht 0.5 dotted with .sw at last box .se;
2345 move down from last arrow .center;
2347 if ( $1 == boxht ) \
2348 then { "\fBline up left\fP" } \
2349 else { sprintf("\fBarrow up left %g\fP", $1) };
2352 move right 0.1 from last [] .e;
2360 .CE "1: Diagonal arrows (dotted boxes show the implied 0.5-inch grid)"
2362 Here's an example concocted to demonstrate layout of a large,
2363 multiple-part pattern:
2370 define filter {box ht 0.25 rad 0.125}
2374 box "\efBms\efR" "sources";
2376 box "\efBHTML\efR" "sources";
2378 box "\efBlinuxdoc-sgml\efP" "sources" wid 1.5;
2380 box "\efBTexinfo\efP" "sources";
2382 line down from 1st box .s lineht;
2384 line down from 2nd box .s; filter "\efBhtml2ms\efP";
2386 line down from 3rd box .s; filter "\efBformat\efP";
2388 line down from 4th box .s; filter "\efBtexi2roff\efP";
2391 move down 1 from last [] .s;
2392 Anchor: box wid 1 ht 0.75 "\efBms\efR" "intermediate" "form";
2393 arrow from Top.A.end to Anchor.nw;
2394 arrow from Top.B.end to 1/3 of the way between Anchor.nw and Anchor.ne;
2395 arrow from Top.C.end to 2/3 of the way between Anchor.nw and Anchor.ne;
2396 arrow from Top.D.end to Anchor.ne
2400 line down left then down ->;
2401 filter "\efBpic\efP";
2403 filter "\efBeqn\efP";
2405 filter "\efBtbl\efP";
2407 filter "\efBgroff\efP";
2413 line down right then down ->;
2414 A: filter dotted "\efBpic2img\efP";
2416 B: filter dotted "\efBeqn2html\efP";
2418 C: filter dotted "\efBtbl2html\efP";
2420 filter "\efBms2html\efP";
2424 # Nonexistence caption
2425 box dashed wid 1 at B + (2,0) "These tools" "don't yet exist";
2426 line chop 0 chop 0.1 dashed from last box .nw to A.e ->;
2427 line chop 0 chop 0.1 dashed from last box .w to B.e ->;
2428 line chop 0 chop 0.1 dashed from last box .sw to C.e ->;
2438 define filter {box ht 0.25 rad 0.125}
2442 box "\fBms\fR" "sources";
2444 box "\fBHTML\fR" "sources";
2446 box "\fBlinuxdoc-sgml\fP" "sources" wid 1.5;
2448 box "\fBTexinfo\fP" "sources";
2450 line down from 1st box .s lineht;
2452 line down from 2nd box .s; filter "\fBhtml2ms\fP";
2454 line down from 3rd box .s; filter "\fBformat\fP";
2456 line down from 4th box .s; filter "\fBtexi2roff\fP";
2459 move down 1 from last [] .s;
2460 Anchor: box wid 1 ht 0.75 "\fBms\fR" "intermediate" "form";
2461 arrow from Top.A.end to Anchor.nw;
2462 arrow from Top.B.end to 1/3 of the way between Anchor.nw and Anchor.ne;
2463 arrow from Top.C.end to 2/3 of the way between Anchor.nw and Anchor.ne;
2464 arrow from Top.D.end to Anchor.ne
2468 line down left then down ->;
2475 filter "\fBgroff\fP";
2481 line down right then down ->;
2482 A: filter dotted "\fBpic2img\fP";
2484 B: filter dotted "\fBeqn2html\fP";
2486 C: filter dotted "\fBtbl2html\fP";
2488 filter "\fBms2html\fP";
2492 # Nonexistence caption
2493 box dashed wid 1 at B + (2,0) "These tools" "don't yet exist";
2494 line chop 0 chop 0.1 dashed from last box .nw to A.e ->;
2495 line chop 0 chop 0.1 dashed from last box .w to B.e ->;
2496 line chop 0 chop 0.1 dashed from last box .sw to C.e ->;
2499 .CE "2: Hypothetical production flow for dual-mode publishing"
2503 # a three-dimensional block
2505 # tblock(<width>, <height>, <text>)
2509 color "gold" outlined "black" \
2510 xslanted 0 yslanted 0 \
2513 color "yellow" outlined "black" \
2514 xslanted .1 yslanted 0 \
2515 with .sw at last box .nw;
2517 color "goldenrod" outlined "black" \
2518 xslanted 0 yslanted .1 \
2519 with .nw at 2nd last box .ne;
2522 tblock(1, .5, "Master" "1");
2524 tblock(.5, 1, "Slave");
2526 .CE "3: Three-dimensional Boxes"
2528 Here the source code for figure \n[H1]-3:
2533 # a three-dimensional block
2535 # tblock(<width>, <height>, <text>)
2539 color "gold" outlined "black" \e
2540 xslanted 0 yslanted 0 \e
2543 color "yellow" outlined "black" \e
2544 xslanted .1 yslanted 0 \e
2545 with .sw at last box .nw;
2547 color "goldenrod" outlined "black" \e
2548 xslanted 0 yslanted .1 \e
2549 with .nw at 2nd last box .ne;
2552 tblock(1, .5, "Master" "1");
2554 tblock(.5, 1, "Slave");
2565 This is an annotated grammar of \fBpic\fP.
2570 In general, \fBpic\fP is a free-format, token-oriented language that
2571 ignores whitespace outside strings. But certain lines and contructs
2572 are specially interpreted at the lexical level:
2574 A comment begins with \fB#\fP and continues to \fB\en\fP (comments may
2575 also follow text in a line). A line beginning with a period or
2576 backslash may be interpreted as text to be passed through to the
2577 post-processor, depending on command-line options. An end-of-line
2578 backslash is interpreted as a request to continue the line; the
2579 backslash and following newline are ignored.
2582 Here are the grammar terminals:
2585 .IP \s[-1]NUMBER\s[0]
2586 A floating point numeric constant. May contain a decimal point or be
2587 expressed in scientific notation in the style of \fIprintf\/\fP(3)'s %e
2588 escape. A trailing `i' or `I' (indicating the unit `inch') is ignored.
2590 A string enclosed in double quotes. A double quote within \s[-1]TEXT\s[0]
2591 must be preceded by a backslash. Instead of \s[-1]TEXT\s[0] you can use
2594 sprintf ( TEXT [, <expr> ...] )
2598 except after the `until' and `last' keywords, and after all ordinal
2599 keywords (`th' and friends).
2600 .IP \s[-1]VARIABLE\s[0]
2601 A string starting with a character from the set [a-z], optionally
2602 followed by one or more characters of the set [a-zA-Z0-9_].
2603 (Values of variables are preserved across pictures.)
2604 .IP \s[-1]LABEL\s[0]
2605 A string starting with a character from the set [A-Z], optionally
2606 followed by one or more characters of the set [a-zA-Z0-9_].
2607 .IP \s[-1]COMMAND-LINE\s[0]
2608 A line starting with a command character (`.' in groff mode, `\e' in
2610 .IP \s[-1]BALANCED-TEXT\s[0]
2611 A string either enclosed by `{' and `}' or with \fIX\fP and \fIX\fP,
2612 where \fIX\fP doesn't occur in the string.
2613 .IP \s[-1]BALANCED-BODY\s[0]
2614 Delimiters as in \s[-1]BALANCED-TEXT\s[0]; the body is interpreted as
2615 `\fB\[la]command\[ra].\|.\|.\fP'.
2616 .IP \s[-1]FILENAME\s[0]
2617 The name of a file. This has the same semantics as \s[-1]TEXT\s[0].
2618 .IP \s[-1]MACRONAME\s[0]
2619 Either \s[-1]VARIABLE\s[0] or \s[-1]LABEL\s[0].
2625 Tokens not enclosed in \[la]\|\[ra] are literals, except:
2627 \fB\en\fP is a newline.
2629 Three dots is a suffix meaning `replace with 0 or more repetitions
2630 of the preceding element(s).
2632 An enclosure in square brackets has its usual meaning of `this clause is
2635 Square-bracket-enclosed portions within tokens are optional. Thus,
2636 `h\^[eigh]\^t' matches either `height' or `ht'.
2638 If one of these special tokens has to be referred to literally, it is
2639 surrounded with single quotes.
2641 The top-level \fBpic\fP object is a picture.
2645 .PS [NUMBER [NUMBER]]\en
2651 The arguments, if present, represent the width and height of the picture,
2652 causing \fBpic\fR to attempt to scale it to the given dimensions in
2653 inches. In no case, however, the X and Y\~dimensions of the
2654 picture exceed the values of the style variables \fBmaxpswid\fP and
2655 \fBmaxpsheight\fP (which default to the normal 8.5\^i by 11\^i page size).
2657 If the ending `.PE' is replaced by `.PF', the page vertical position is
2658 restored to its value at the time `.PS' was encountered. Another
2659 alternate form of invocation is `.PS\ <\s[-1]FILENAME\s[0]', which
2660 replaces the `.PS' line with a file to be interpreted by \fBpic\fR (but
2661 this feature is deprecated).
2663 The `.PS', `.PE', and `.PF' macros to perform centering and scaling are
2664 normally supplied by the post-processor.
2666 In the following, either `|' or a new line starts an alternative.
2677 <primitive> [<attribute>]
2678 LABEL : [;] <command>
2679 LABEL : [;] <command> [<position>]
2681 VARIABLE [:] = <any-expr>
2683 up | down | left | right
2685 command <print-arg> ...
2686 print <print-arg> ...
2689 copy [FILENAME] thru MACRONAME [until TEXT]
2690 copy [FILENAME] thru BALANCED-BODY [until TEXT]
2691 for VARIABLE = <expr> to <expr> [by [*] <expr>] do BALANCED-BODY
2692 if <any-expr> then BALANCED-BODY [else BALANCED-BODY]
2693 reset [VARIABLE [[,] VARIABLE ...]]
2705 The current position and direction are saved on entry to a `{\ .\|.\|.\ }'
2706 construction and restored on exit from it.
2708 Note that in `if' constructions, newlines can only occur in
2709 \s[-1]BALANCED-BODY\s[0]. This means that
2719 fails. You have to use the braces on the same line as the keywords:
2730 This restriction doesn't hold for the body after the `do' in a `for'
2733 At the beginning of each picture, `figname' is reset to the vbox name
2734 `graph'; this command has only a meaning in \*[tx] mode. While the grammar
2735 rules allow digits and the underscore in the value of `figname', \*[tx]
2736 normally accepts uppercase and lowercase letters only as box names
2737 (you have to use `\ecsname' if you really need to circumvent this
2744 <any-expr> <logical-op> <any-expr>
2762 Logical operators are handled specially by \fBpic\fP since they can
2763 deal with text strings also. \fBpic\fP uses \%\fIstrcmp\/\fP(3) to test
2764 for equality of strings; an empty string is considered as `false' for
2769 box \fR# closed object \[em] rectangle\fP
2770 circle \fR# closed object \[em] circle\fP
2771 ellipse \fR# closed object \[em] ellipse\fP
2772 arc \fR# open object \[em] quarter-circle\fP
2773 line \fR# open object \[em] line\fP
2774 arrow \fR# open object \[em] line with arrowhead\fP
2775 spline \fR# open object \[em] spline curve\fP
2777 TEXT TEXT ... \fR# text within invisible box\fP
2778 plot <expr> TEXT \fR# formatted text\fP
2779 '[' <command> ... ']'
2783 Drawn objects within `[\ .\|.\|.\ ]' are treated as a single composite
2784 object with a rectangular shape (that of the bounding box of all the
2785 elements). Variable and label assignments within a block are local to
2786 the block. Current direction of motion is restored to the value at start
2787 of block upon exit. Position is \fInot\fR restored (unlike `{\ }');
2788 instead, the current position becomes the exit position for the current
2789 direction on the block's bounding box.
2793 h[eigh]t <expr> \fR# set height of closed figure \fP
2794 wid[th] <expr> \fR# set width of closed figure \fP
2795 rad[ius] <expr> \fR# set radius of circle/arc \fP
2796 diam[eter] <expr> \fR# set diameter of circle/arc \fP
2797 up [<expr>] \fR# move up \fP
2798 down [<expr>] \fR# move down \fP
2799 left [<expr>] \fR# move left \fP
2800 right [<expr>] \fR# move right \fP
2801 from <position> \fR# set from position of open figure\fP
2802 to <position> \fR# set to position of open figure\fP
2803 at <position> \fR# set center of open figure\fP
2804 with <path> \fR# fix corner/named point at specified location\fP
2805 with <position> \fR# fix position of object at specified location\fP
2806 by <expr-pair> \fR# set object's attachment point\fP
2807 then \fR# sequential segment composition\fP
2808 dotted [<expr>] \fR# set dotted line style\fP
2809 dashed [<expr>] \fR# set dashed line style\fP
2810 thick[ness] <expr> \fR# set thickness of lines\fP
2811 chop [<expr>] \fR# chop end(s) of segment\fP
2812 '->' | '<-' | '<->' \fR# decorate with arrows\fP
2813 invis[ible] \fR# make primitive invisible\fP
2814 solid \fR# make closed figure solid\fP
2815 fill[ed] [<expr>] \fR# set fill density for figure\fP
2816 xscaled <expr> \fR# slant box into x direction\fP
2817 yscaled <expr> \fR# slant box into y direction\fP
2818 colo[u]r[ed] TEXT \fR# set fill and outline color for figure\fP
2819 outline[d] TEXT \fR# set outline color for figure\fP
2820 shaded TEXT \fR# set fill color for figure\fP
2821 same \fR# copy size of previous object\fP
2822 cw | ccw \fR# set orientation of curves\fP
2823 ljust | rjust \fR# adjust text horizontally\fP
2824 above | below \fR# adjust text vertically\fP
2825 aligned \fR# align parallel to object\fP
2826 TEXT TEXT ... \fR# text within object\fP
2827 <expr> \fR# motion in the current direction\fR
2831 Missing attributes are supplied from defaults; inappropriate ones are
2832 silently ignored. For lines, splines, and arcs, height and width
2833 refer to arrowhead size.
2835 The `at' primitive sets the center of the current object. The
2836 `with' attribute fixes the specified feature of the given object
2837 to a specified location. (Note that `with' is incorrectly described
2838 in the Kernighan paper.)
2840 The `by' primitive is not documented in the tutorial portion of
2841 the Kernighan paper, and should probably be considered unreliable.
2843 The primitive `arrow' is a synonym for `line\ ->'.
2845 Text is normally an attribute of some object, in which case successive
2846 strings are vertically stacked and centered on the object's center by
2847 default. Standalone text is treated as though placed in an invisible
2850 A text item consists of a string or sprintf-expression, optionally
2851 followed by positioning information. Text (or strings specified with
2852 `sprintf') may contain font changes, size changes, and local
2853 motions, provided those changes are undone before the end of the current
2854 item. Text may also contain \e-escapes denoting special characters.
2855 The base font and specific set of escapes supported is implementation
2856 dependent, but supported escapes always include the following:
2858 Set Roman style (the default)
2863 .IP "\efP\ \ \ \ \ \ "
2864 Revert to previous style; only works one level deep, does not stack.
2866 Color names are dependent on the \gBpic\fR implementation, but in
2867 all modern versions color names recognized by the X\~window system are
2870 A position is an (x,y) coordinate pair. There are lots of different
2871 ways to specify positions:
2875 <position-not-place>
2882 <position-not-place> ::=
2884 <position> + <expr-pair>
2885 <position> - <expr-pair>
2886 ( <position> , <position> )
2887 <expr> [of the way] between <position> and <position>
2888 <expr> '<' <position> , <position> '>'
2903 <corner> [of] <label>
2918 .ne | .se | .nw | .sw
2919 .c[enter] | .start | .end
2920 .t[op] | .b[ot[tom]] | .l[eft] | .r[ight]
2921 left | right | <top-of> | <bottom-of>
2922 <north-of> | <south-of> | <east-of> | <west-of>
2923 <center-of> | <start-of> | <end-of>
2924 upper left | lower left | upper right | lower right
2929 <\,\f(CIxxx\/\fP-of> ::=
2930 \f(CIxxx\fP \fR# followed by `of'\fP
2936 <ordinal> <object-type>
2937 [<ordinal>] last <object-type>
2944 INT st | INT nd | INT rd
2963 As Kernighan notes, \[lq]since barbarisms like \fB1th\fP and \fB3th\fP are
2964 barbaric, synonyms like \fB1st\fP and \fB3rd\fP are accepted as well.\[rq]
2965 Objects of a given type are numbered from 1 upwards in order of
2966 declaration; the \fBlast\fP modifier counts backwards.
2968 The \[lq]'th\[rq] form (which allows you to select a previous object with
2969 an expression, as opposed to a numeric literal) is not documented in DWB's
2972 The \[la]\,\fIxxx\/\fP-of\|\[ra] rule is special: The lexical parser checks whether
2973 \fIxxx\fP is followed by the token `of' without eliminating it so that
2974 the grammar parser can still see `of'. Valid examples of specifying a
2975 place with corner and label are thus
2992 both cause a syntax error. (DWB \fBpic\fP also allows the weird form
2995 Here the special rules for the `with' keyword using a path:
3000 ( <relative-path> , <relative-path> )
3007 . LABEL [. LABEL ...] [<corner>]
3011 The following style variables control output:
3013 center tab(@), linesize(2);
3017 Style Variable@Default@What It Does
3022 boxht@0.5@Default height of a box
3023 boxwid@0.75@Default height of a box
3024 lineht@0.5@Default length of vertical line
3025 linewid@0.75@Default length of horizontal line
3026 arcrad @0.25@Default radius of an arc
3027 circlerad@0.25@Default radius of a circle
3028 ellipseht@0.5@Default height of an ellipse
3029 ellipsewid@0.75@Default width of an ellipse
3030 moveht@0.5@Default length of vertical move
3031 movewid@0.75@Default length of horizontal move
3032 textht@0@Default height of box enclosing a text object
3033 textwid@0@Default width of box enclosing a text object
3034 arrowht@0.1@Length of arrowhead along shaft
3035 arrowwid@0.05@Width of rear of arrowhead
3036 arrowhead@1@Enable/disable arrowhead filling
3037 dashwid@0.05@Interval for dashed lines
3038 maxpswid@8.5@Maximum width of picture
3039 maxpsht@11@Maximum height of picture
3040 scale@1@Unit scale factor
3041 fillval@0.5@Default fill value
3045 Any of these can be set by assignment, or reset using the \fBreset\fP
3046 statement. Style variables assigned within `[\ ]' blocks are restored to
3047 their beginning-of-block value on exit; top-level assignments persist
3048 across pictures. Dimensions are divided by \fBscale\fR on output.
3050 All \fBpic\fP expressions are evaluated in floating point; units
3051 are always inches (a trailing `i' or `I' is ignored). Expressions have
3052 the following simple grammar, with semantics very similar to
3059 <place> <place-attribute>
3064 <func1> ( <any-expr> )
3065 <func2> ( <any-expr> , <any-expr> )
3072 .x | .y | .h[eigh]t | .wid[th] | .rad
3078 + | - | * | / | % | ^ | '<' | '>' | '<=' | '>='
3084 sin | cos | log | exp | sqrt | int | rand | srand
3094 Both \fBexp\fP and \fBlog\fP are base 10; \fBint\fP does integer
3095 truncation; and \fBrand()\fP returns a random number in [0-1).
3097 There are \fBdefine\fP and \fBundef\fR statements which are not part
3098 of the grammar (they behave as pre-processor macros to the language).
3099 These may be used to define pseudo-functions.
3102 \fBdefine\fP \fIname\fP \fB{\fP \fIreplacement-text\fP \fB}\fP
3106 This defines \fIname\fR as a macro to be replaced by the replacement
3107 text (not including the braces). The macro may be called as
3110 \fIname\/\fB(\,\fIarg1, arg2, .\|.\|., argn\fB\/)\fR
3114 The arguments (if any) are substituted for tokens $1, $2 .\|.\|.\& $n
3115 appearing in the replacement text. To undefine a macro, say \fBundef\fP
3116 \fIname\fR, specifying the name to be undefined.
3121 History and Acknowledgements
3123 Original \fBpic\fP was written to go with Joseph Ossanna's original
3124 \fItroff\/\fP(1) by Brian Kernighan, and later re-written by Kernighan
3125 with substantial enhancements (apparently as part of the evolution of
3126 \fItroff\/\fP(1) into \fIditroff\/\fP(1) to generate
3127 device-independent output).
3129 The language had been inspired by some earlier graphics languages
3130 including \fBideal\fP and \fBgrap\fP. Kernighan credits Chris van Wyk
3131 (the designer of \fBideal\fP) with many of the ideas that went into
3134 .\" the original definitions of EQ and EN cause insertion of vertical
3135 .\" space which is not appropriate here
3143 The \fBpic\fP language was originally described by Brian Kernighan in
3144 Bell Labs Computing Science Technical Report #116 (you can obtain a
3145 PostScript copy of the revised version, [1], by sending a mail message to
3146 \fInetlib@research.att.com\fP with a body of `send 116 from
3147 research/cstr'). There have been two revisions, in 1984 and 1991.
3149 The document you are reading effectively subsumes Kernighan's
3150 description; it was written to fill in lacun\[ae] in the exposition and
3151 integrate in descriptions of the GNU \fIgpic\/\fP(1) and
3152 \fIpic2plot\/\fP(1) features.
3154 The GNU \fBgpic\fR implementation was written by James Clark
3155 \[la]\,\fIjjc@jclark.com\/\fP\[ra]. It is currently maintained by Werner
3156 Lemberg \[la]\,\fIwl@gnu.org\/\fP\[ra].
3158 The GNU \fBpic2plot\fR implementation is based on James Clark's parser
3159 code and maintained by Robert Maier, principal author of \fBplotutils\fP.
3165 Kernighan, B. W. \fBPIC \[em] A Graphics Language for Typesetting
3166 (Revised User Manual)\fP. Bell Labs Computing Science Technical Report
3167 #116, December 1991.
3169 Van Wyk, C. J. \fBA high-level language for specifying pictures\fP.
3170 \fIACM Transactions On Graphics\fP 1,2 (1982) 163-182.