diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/pic.ms | 3287 |
1 files changed, 3287 insertions, 0 deletions
diff --git a/doc/pic.ms b/doc/pic.ms new file mode 100644 index 0000000..51c710f --- /dev/null +++ b/doc/pic.ms @@ -0,0 +1,3287 @@ +.\" Copyright (C) 2006-2020 Free Software Foundation, Inc. +.\" Written by Eric S. Raymond <esr@thyrsus.com> +.\" +.\" This file is part of groff. +.\" +.\" groff is free software; you can redistribute it and/or modify it under +.\" the terms of the GNU General Public License as published by the Free +.\" Software Foundation, either version 3 of the License, or +.\" (at your option) any later version. +.\" +.\" groff is distributed in the hope that it will be useful, but WITHOUT ANY +.\" WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. If not, see <http://www.gnu.org/licenses/>. +.\" +.\" For tolerably obvious reason, this needs to be processed through PIC. +.\" It also needs to be processed through TBL and EQN. Use "groff -p -e -t". +.\" There is no hope that this will ever look right under nroff. +.\" +.\" Comments beginning with %% are cut lines so portions of this +.\" document can be automatically extracted. %%TUTORIAL%% begins the +.\" tutorial part; %%REFERENCE%% the reference part. %%POSTLUDE%% the +.\" bibliography and end matter after the reference part. +.\" +.\" This document was written for free use and redistribution by +.\" Eric S. Raymond <esr@thyrsus.com> in August 1995. It has been put +.\" under the GPL in March 2006. +.\" +. +. +.\" Set a proper TeX and LaTeX +.ie t \{\ +. ds tx T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X\" +. ds lx L\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\*(tx\" +.\} +.el \{\ +. ds tx TeX\" +. ds lx LaTeX\" +.\} +. +.\" Centered caption for figure. Assumes previous .KS +.de CE +. ce 1 +Figure \\n[H1]-\\$1 +. sp 1 +. KE +.. +. +.\" Definitions end here +. +. +.TL +Making Pictures With GNU PIC +.AU +Eric S. Raymond +.AI +\[la]\fIesr@snark.thyrsus.com\fP\[ra] +.AB +The \fBpic\fP language is a \fBtroff\fP extension that makes it easy +to create and alter box-and-arrow diagrams of the kind frequently used +in technical papers and textbooks. +This paper is both an introduction to and reference for \fIgpic\/\fP(1), +the implementation distributed by the Free Software Foundation for use +with \fIgroff\/\fP(1). +It also catalogs other implementations and explains the differences +among them. +.AE +.\"%%TUTORIAL%% +. +. +.NH 1 +Introduction to PIC +. +.NH 2 +Why PIC? +.PP +The \fBpic\fP language provides an easy way to write procedural +box-and-arrow diagrams to be included in \fBtroff\fP documents. +The language is sufficiently flexible to be quite useful for state +charts, Petri-net diagrams, flow charts, simple circuit schematics, +jumper layouts, and other kinds of illustration involving repetitive +uses of simple geometric forms and splines. +Because these descriptions are procedural and object-based, they are +both compact and easy to modify. +.PP +The phrase \[lq]GNU pic\[rq] may refer to either of two \fBpic\fP +implementations distributed by the Free Software Foundation and +intended to accept the same input language. +The \fIgpic\/\fP(1) implementation is for use with the \fIgroff\/\fP(1) +implementation of \fBtroff\fP. +The \fIpic2plot\/\fP(1) implementation runs standalone and is part of +the \fBplotutils\fR package. +Because both implementations are widely available in source form for +free, they are good bets for writing very portable documentation. +. +.NH 2 +PIC Versions +.PP +The original 1984 pre-\fIditroff\/\fP(1) version of \fBpic\fP is long +obsolete. +The rewritten 1991 version is still available as part of the +Documenter's Work Bench module of System V. +.PP +Where differences between Documenter's Work Bench (1991) \fBpic\fP and GNU +\fBpic\fP need to be described, original \fBpic\fP is referred to as +\[lq]DWB pic\[rq]. +Details on the history of the program are given at the end of this +document. +.PP +The \fBpic2plot\fR program does not require the rest of the +\fIgroff\/\fP(1) toolchain to render graphics. +It can display \fBpic\fR diagrams in an X\~window, or generate output +plots in a large number of other formats. +These formats include: PNG, PBM, PGM, PPM, GIF, SVG, Adobe Illustrator +format, idraw-editable Postscript, the WebCGM format for Web-based +vector graphics, the format used by the \fBxfig\fP drawing editor, the +Hewlett-Packard PCL\~5 printer language, the Hewlett-Packard Graphics +Language (by default, HP-GL/2), the ReGIS (remote graphics instruction +set) format developed by DEC, Tektronix format, and device-independent +GNU graphics metafile format. +.PP +In this document, \fIgpic\/\fP(1) and \fIpic2plot\/\fP(1) extensions are +marked as such. +. +. +.NH 1 +Invoking PIC +.PP +Every \fBpic\fP description is a little program describing drawing +actions. +The \fB[gtn]roff\fP-dependent versions compile the program by +\fIpic\/\fP(1) into \fIgtroff\/\fP(1) macros; the \fIpic2plot\/\fP(1) +implementation uses a plotting library to draw the picture directly. +Programs that process or display +\fIgtroff\/\fP(1) output need not know or care that parts of the image +began life as \fBpic\fP descriptions. +.PP +The \fIpic\/\fP(1) program tries to translate anything between \fB.PS\fP +and \fB.PE\fP markers, and passes through everything else. +The normal definitions of \fB.PS\fP and \fB.PE\fP in the \fIms\fP macro +package and elsewhere have also the side-effect of centering the +\fBpic\fP output on the page. +. +.KS +.NH 2 +PIC Error Messages +.PP +If you make a mistake in \fBpic\fP input such that the program cannot +interpret what you mean, +\fIgpic\/\fP(1) issues a diagnostic message in the format prescribed by +the GNU Coding Standards. +. +A typical error message looks like +. +. +.ds FAM C +.DS +pic:\fIfile\fP:\fInnn\fP: syntax error before \[aq]\fItoken\fP\[aq] +pic:\fIfile\fP:\fInnn\fP: giving up on this picture +.DE +.ds FAM T +. +. +.LP +where +.I file +is the name of the file being processed, +.I nnn +is a line number within that file, +and +.I token +is a symbol in the \fBpic\fP language +(often a keyword) +near +(usually just after) +the error location. +.KE +. +. +.NH 1 +Basic PIC Concepts +.PP +Pictures are described procedurally, as collections of objects +connected by motions. +Normally, \fBpic\fP tries to string together objects left-to-right in +the sequence they are described, joining them at visually natural +points. +Here is an example illustrating the flow of data in \fBpic\fP +processing: +.KS +.PS +ellipse "document"; +arrow; +box width 0.6 "\fIgpic\/\fP(1)" +arrow; +box width 1.1 "\fIgtbl\/\fP(1) or \fIgeqn\/\fP(1)" "(optional)" dashed; +arrow; +box width 0.6 "\fIgtroff\/\fP(1)"; +arrow; +ellipse "PostScript" +.PE +.CE "1: Flow of \fBpic\fP data" +.PP +This was produced from the following \fBpic\fP program: +.KS +.DS +.ps -1 +.vs -1 +.CW +\&.PS +ellipse "document"; +arrow; +box width 0.6 "\efIgpic\e/\efP(1)" +arrow; +box width 1.1 "\efIgtbl\e/\efP(1) or \efIgeqn\e/\efP(1)" "(optional)" dashed; +arrow; +box width 0.6 "\efIgtroff\e/\efP(1)"; +arrow; +ellipse "PostScript" +\&.PE +.DE +.R +.KE +.LP +This little program illustrates several \fBpic\fP basics. +Firstly, we see how to invoke three object types; ellipses, arrows, and +boxes. +We see how to declare text lines to go within an object (and that text +can have font changes in it). +We see how to change the line style of an object from solid (the +default) to dashed. +And we see that a box can be made wider than its default size to +accommodate more text (we'll discuss this facility in detail in the next +section). +.PP +We also get to see \fBpic\fP's simple syntax. +Statements are ended by newlines or semicolons. +String quotes are required around all text arguments, whether or not +they contain spaces. +In general, the order of command arguments and modifiers like \[lq]width +1.2\[rq] or \[lq]dashed\[rq] doesn't matter, except that the order of +text arguments is significant. +.PP +Here are all but one of the basic \fBpic\fP objects at their default sizes: +.KS +.PS +box "box"; +move; +line "line" ""; +move; +arrow "arrow" ""; +move; +circle "circle"; +move; +ellipse "ellipse"; +move; +arc; down; move; "arc" +.PE +.CE "2: Basic \fBpic\fP objects" +.PP +The missing simple object type is a \fIspline\fP. +There is also a way to collect objects into \fIblock composites\fP which +allows you to treat the whole group as a single object (resembling a +box) for many purposes. +We'll describe both of these later on. +.PP +The box, ellipse, circle, and block composite objects are \fIclosed\/\fR; +lines, arrows, arcs and splines are \fIopen\fP. +This distinction is often important in explaining command modifiers. +.PP +Figure \n[H1]-2 was produced by the following \fBpic\fP program, +which introduces some more basic concepts: +.KS +.DS +.CW +\&.PS +box "box"; +move; +line "line" ""; +move; +arrow "arrow" ""; +move; +circle "circle"; +move; +ellipse "ellipse"; +move; +arc; down; move; "arc" +\&.PE +.DE +.ft R +.KE +.PP +The first thing to notice is the \fImove\fP command, which moves a +default distance (1/2 inch) in the current movement direction. +.PP +Secondly, see how we can also decorate lines and arrows with text. +The line and arrow commands each take two arguments here, specifying +text to go above and below the object. +If you wonder why one argument would not do, contemplate the output of +\fBarrow "ow!"\fP: +.KS +.PS +arrow "ow!" +.PE +.CE "3: Text centered on an arrow" +.PP +When a command takes one text string, \fBpic\fP tries to place it at +the object's geometric center. +As you add more strings, \fBpic\fP treats them as a vertical block to be +centered. +The program +.KS +.DS +.CW +line "1"; +line "1" "2"; +line "1" "2" "3"; +line "1" "2" "3" "4"; +line "1" "2" "3" "4" "5"; +.DE +.ft R +.KE +.LP +for example, gives you this: +.KS +.sp 2 +.PS +line "1"; +line "1" "2"; +line "1" "2" "3"; +line "1" "2" "3" "4"; +line "1" "2" "3" "4" "5"; +.PE +.sp 2 +.CE "4: Effects of multiple text arguments" +.PP +The last line of Figure 3-2's program, `\fBarc; down; move; +"arc"\fP', describing the captioned arc, introduces several new ideas. +Firstly, we see how to change the direction in which objects are +joined. +Had we written \fBarc; move; "arc"\fP, omitting \fBdown\fP the caption +would have been joined to the top of the arc, like this: +.KS +.PS +arc; move; "arc"; +.PE +.CE "5: Result of \fBarc; move; ""arc""\fP" +.PP +This is because drawing an arc changes the default direction to the +one its exit end points at. +To reinforce this point, consider: +.KS +.PS +arc cw; move; "arc"; +.PE +.CE "6: Result of \fBarc cw; move; ""arc""\fP" +.PP +All we've done differently here is specify \[lq]cw\[rq] for a clockwise arc +(\[lq]ccw\[rq] specifies counter-clockwise direction). +Observe how it changes the default direction to down, rather than up. +.PP +Another good way to see this via with the following program: +.KS +.DS +.CW +line; arc; arc cw; line +.DE +.ft R +.KE +.LP +which yields: +.KS +.PS +line; arc; arc cw; line; +.PE +.CE "7: Result of \fBline; arc; arc cw; line\fP" +.LP +Notice that we did not have to specify \[lq]up\[rq] for the second arc to be +joined to the end of the first. +.PP +Finally, observe that a string, alone, is treated as text to be +surrounded by an invisible box of a size either specified by width +and height attributes or by the defaults \fBtextwid\fR and +\fBtextht\fR. +Both are initially zero (because we don't know the default font size). +. +. +.NH 1 +Sizes and Spacing +.PP +Sizes are specified in inches. +If you don't like inches, it's possible to set a global style variable +\fBscale\fP that changes the unit. +Setting \fBscale = 2.54\fP effectively changes the internal unit to +centimeters (all other size variable values are scaled correspondingly). +. +.NH 2 +Default Sizes of Objects +.PP +Here are the default sizes for \fBpic\fP objects: +.TS H +center, tab(@), linesize(2); +lb | lb +l | l. +.sp 2p +Object@Default Size +.sp 2p +_ +.sp 2p +.TH +box@0.75" wide by 0.5" high +circle@0.5" diameter +ellipse@0.75" wide by 0.5" high +arc@0.5" radius +line@0.5" long +arrow@0.5" long +.sp 5p +_ +.TE +.PP +The simplest way to think about these defaults is that they make the +other basic objects fit snugly into a default-sized box. +.PP +\fIpic2plot\/\fP(1) does not necessarily emit a physical inch for +each virtual inch in its drawing coordinate system. +Instead, it draws on a canvas 8\~virtual inches by 8\~virtual inches +wide. +If its output page size is \[lq]letter\[rq], these virtual inches will +map to real ones. +Specifying a different page size (such as, say, \[lq]a4\[rq]) will scale +virtual inches so they are output as one eighth of the page width. +Also, \fIpic2plot\/\fP(1) centers all images by default, though the +\fB\-n\fP option can be used to prevent this. +. +.NH 2 +Objects Do Not Stretch! +.PP +Text is rendered in the current font with normal troff line spacing. +Boxes, circles, and ellipses do \fInot\fP automatically resize to fit +enclosed text. +Thus, if you say \fBbox "this text far too long for a default box"\fP +you'll get this: +.KS +.PS +box "this text is far too long for a default box" +.PE +.CE "1: Boxes do not automatically resize" +.LP +which is probably not the effect you want. +. +.NH 2 +Resizing Boxes +.PP +To change the box size, you can specify a box width with the \[lq]width\[rq] +modifier: +.KS +.PS +box width 3 "this text is far too long for a default box" +.PE +.CE "2: Result of \fBbox width 3 ""text far too long""\fP" +.PP +This modifier takes a dimension in inches. +There is also a \[lq]height\[rq] modifier that changes a box's height. +The \fBwidth\fP keyword may be abbreviated to \fBwid\fP; the +\fBheight\fP keyword to \fBht\fP. +. +.NH 2 +Resizing Other Object Types +.PP +To change the size of a circle, give it a \fBrad[ius]\fP or +\fBdiam[eter]\fP modifier; this changes the radius or diameter of the +circle, according to the numeric argument that follows. +.KS +.PS +{circle rad 0.1; move down 0.2 from last circle .s; "0.1"}; +move; circle rad 0.2 "0.2"; move; circle rad 0.3 "0.3"; +.PE +.CE "3: Circles with increasing radii" +.PP +The \fBmove\fP command can also take a dimension, which just tells +it how many inches to move in the current direction. +.PP +Ellipses are sized to fit in the rectangular box defined by their +axes, and can be resized with \fBwidth\fP and \fBheight\fP like boxes. +.PP +You can also change the radius of curvature of an arc with \fBrad[ius]\fP +(which specifies the radius of the circle of which the arc is a segment). +Larger values yield flatter arcs. +.KS +.PS +{arc rad 0.1; move down 0.3 from last arc .center; "0.1"}; +move; +{arc rad 0.2; move down 0.4 from last arc .center; "0.2"}; +move; +{arc rad 0.3; move down 0.5 from last arc .center; "0.3"}; +.PE +.CE "4: \fBarc rad\fP with increasing radii" +.PP +Observe that because an arc is defined as a quarter circle, increasing +the radius also increases the size of the arc's bounding box. +. +.NH 2 +The `same' Keyword +.PP +In place of a dimension specification, you can use the keyword +\fBsame\fR. +This gives the object the same size as the previous one +of its type. +As an example, the program +.KS +.DS +.CW +\&.PS +box; box wid 1 ht 1; box same; box +\&.PE +.R +.DE +.KE +.LP +gives you +.KS +.PS +box; box wid 1 ht 1; box same; box +.PE +.CE "5: The \fBsame\fP keyword" +. +. +.NH 1 +Generalized Lines and Splines +. +.NH 2 +Diagonal Lines +.PP +It is possible to specify diagonal lines or arrows by adding multiple \fBup\fP, +\fBdown\fP, \fBleft\fP, and \fBright\fP modifiers to the line object. +Any of these can have a multiplier. +To understand the effects, think of the drawing area as being gridded +with standard-sized boxes. +.KS +.PS +# Draw a demonstration up left arrow with grid box overlay +define gridarrow +{ + move right 0.5 + [ + {arrow up left $1;} + box wid 0.5 ht 0.5 dotted with .nw at last arrow .end; + for i = 2 to ($1 / 0.5) do { + box wid 0.5 ht 0.5 dotted with .sw at last box .se; + } + move down from last arrow .center; + [ + sprintf("\fBarrow up left %g\fP", $1) + ] + ] + move right 0.1 from last [] .e; +} +gridarrow(0.5); +gridarrow(1); +gridarrow(1.5); +gridarrow(2); +undef gridarrow +.PE +.CE "1: Diagonal arrows (dotted boxes show the implied 0.5-inch grid)" +. +.NH 2 +Multi-Segment Line Objects +.PP +A \[lq]line\[rq] or \[lq]arrow\[rq] object may actually be a path +consisting of any number of segments of varying lengths and directions. +To describe a path, connect several line or arrow commands with the +keyword \fBthen\fP. +.KS +.PS +define zigzag { $1 right 1 then down .5 left 1 then right 1 } +zigzag(line); +.PE +.CE "2: \fBline right 1 then down .5 left 1 then right 1\fP" +.PP +If a path starts with \fBthen\fP, the first segment is assumed to be into +the current direction, using the default length. +. +.NH 2 +Spline Objects +.PP +If you start a path with the \fBspline\fP keyword, the path vertices +are treated as control points for a spline curve fit. +.KS +.PS +[zigzag(spline);] +move down 0.2 from last [] .s; +"The spline curve..." +move right from last [] .e; +[ + zigzag(line dashed); + spline from start of last line right 1 then down .5 left 1 then right 1; + "1" at last spline .start + (-0.1, 0); + "2" at last spline .start + (1.1, 0); + "3" at last spline .end + (-1.1, 0); + "4" at last spline .end + (0.1, 0); +] +move down 0.2 from last [] .s; +"...with tangents displayed" +undef zigzag; +.PE +.CE "3: \fBspline right 1 then down .5 left 1 then right 1\fP" +.PP +You can describe many natural-looking but irregular curves this +way. +For example: +.KS +.PS +[spline right then up then left then down ->;] +move down 0.2 from last [] .s; +["\fBspline right then up then left then down ->;\fP"] +move right 3 from last [] .se; +"\fBspline left then up right then down right ->;\fP" +move up 0.2; +[spline left then up right then down right ->;] +.PE +.CE "4: Two more spline examples" +.LP +Note the arrow decorations. +Arrowheads can be applied naturally to any path-based object, line or +spline. +We'll see how in the next section. +. +. +.NH 1 +Decorating Objects +. +.NH 2 +Text Special Effects +.PP +All \fBpic\fP implementations support the following font-styling +escapes within text objects: +.IP "\efR, \ef1" \w'\efR,\~\ef3'u+2n +Set Roman style (the default) +.IP "\efI, \ef2" +Set Italic style +.IP "\efB, \ef3" +Set Bold style +.IP \efP +Revert to previous style; only works one level deep, does not stack. +.PP +In the \fBpic\fP implementations that are preprocessors for a +toolchain that include \fB[gtn]roff\fP, text objects may also contain +\fB[gtn]roff\fP vertical- and horizontal-motion escapes such as \eh or \ev. +Troff special glyphs are also available. +All \e-escapes will be passed through to the postprocessing stage and +have their normal effects. +The base font family is set by the \fB[gtn]roff\fP environment at the +time the picture is rendered. +.PP +\fBpic2plot\fP replaces \fB[gtn]roff\fP horizontal- and vertical-motion +escapes with \e-escapes of its own. +Troff special glyphs are not available, but in most back ends Latin-1 +special characters and a square-root radical will be. +See the \fBpic2plot\fP documentation for full details. +. +.NH 2 +Dashed Objects +.PP +We've already seen that the modifier \fBdashed\fP can change the line +style of an object from solid to dashed. +GNU \fBgpic\fP permits you to dot or dash ellipses, circles, and arcs +(and splines in \*[tx] mode only); some versions of DWB may only permit +dashing of lines and boxes. +It's possible to change the dash interval by specifying a +number after the modifier. +.PP +.KS +.PS +box dashed "default"; +move; +box dashed 0.05 "0.05"; +move; +box dashed 0.1 "0.1"; +move; +box dashed 0.15 "0.15"; +move; +box dashed 0.2 "0.2"; +.PE +.CE "1: Dashed objects" +. +.NH 2 +Dotted Objects +.PP +Another available qualifier is \fBdotted\fP. +GNU \fBgpic\fP permits you to dot or dash ellipses, circles, and arcs +(and splines in \*[tx] mode only); some versions of DWB may only permit +dashing of lines and boxes. +It too can be suffixed with a number to specify the interval between +dots: +.KS +.PS +box dotted "default"; +move; +box dotted 0.05 "0.05"; +move; +box dotted 0.1 "0.1"; +move; +box dotted 0.15 "0.15"; +move; +box dotted 0.2 "0.2"; +.PE +.CE "2: Dotted objects" +. +.NH 2 +Rounding Box Corners +.PP +It is also possible, in GNU \fBgpic\fP only, to modify a box so it has +rounded corners: +.KS +.PS +box rad 0.05 "rad 0.05"; +move; +box rad 0.1 "rad 0.1"; +move; +box rad 0.15 "rad 0.15"; +move; +box rad 0.2 "rad 0.2"; +move; +box rad 0.25 "rad 0.25"; +.PE +.CE "3: \fBbox rad\fP with increasing radius values" +.PP +Radius values higher than half the minimum box dimension are silently +truncated to that value. +. +.NH 2 +Slanted Boxes +.PP +GNU \fBgpic\fP supports slanted boxes: +.KS +.PS +box wid 1.2 xslanted 0.1 "xslanted 0.1"; +move; +box wid 1.2 yslanted -0.1 "yslanted -0.1"; +move; +box wid 1.2 xslanted -0.2 yslanted 0.1 "xslanted -0.2" "yslanted 0.1"; +.PE +.CE "4: Various slanted boxes." +.PP +The \fBxslanted\fP and \fByslanted\fP attributes specify the x and +y\~offset, respectively, of the box's upper right corner from its default +position. +. +.NH 2 +Arrowheads +.PP +Lines and arcs can be decorated as well. +Any line or arc (and any spline as well) can be decorated with +arrowheads by adding one or more as modifiers: +.KS +.PS +line <- -> +.PE +.CE "5: Double-headed line made with \fBline <- ->\fP" +.PP +In fact, the \fBarrow\fP command is just shorthand for \fBline ->\fP. +And there is a double-head modifier <->, so the figure above could have +been made with \fBline <->\fP. +.PP +Arrowheads have a \fBwidth\fP attribute, the distance across the rear; +and a \fBheight\fP attribute, the length of the arrowhead along the shaft. +.PP +Arrowhead style is controlled by the style variable \fBarrowhead\fP. +The DWB and GNU versions interpret it differently. +DWB defaults to open arrowheads and an \fBarrowhead\fP value of\~2; the +Kernighan paper says a value of\~7 makes solid arrowheads. +GNU \fBgpic\fP defaults to solid arrowheads and an \fBarrowhead\fP value +of\~1; a value of\~0 produces open arrowheads. +Note that solid arrowheads are always filled with the current outline +color. +. +.NH 2 +Line Thickness +.PP +It's also possible to change the line thickness of an object (this is +a GNU extension, DWB \fBpic\fP doesn't support it). +The default thickness of the lines used to draw objects is controlled by the +.B linethick +variable. +This gives the thickness of lines in points. +A negative value means use the default thickness: +in \*[tx] output mode, this means use a thickness of 8 milliinches; +in \*[tx] output mode with the +.B -c +option, this means use the line thickness specified by +.B .ps +lines; in troff output mode, this means use a thickness proportional +to the pointsize. +A zero value means draw the thinnest possible line supported by the +output device. +Initially it has a value of -1. +There is also a \fBthickness\fP attribute (which can be abbreviated to +\fBthick\fP). +For example, \fBcircle thickness 1.5\fP would draw a circle using a line +with a thickness of 1.5 points. +The thickness of lines is not affected by the value of the +.B scale +variable, nor by any width or height given in the +.B .PS +line. +. +.NH 2 +Invisible Objects +.PP +The modifier \fBinvis[ible]\fP makes an object entirely invisible. +This used to be useful for positioning text in an invisible object that +is properly joined to neighboring ones. +Newer DWB versions and GNU \fBpic\fP treat stand-alone text in exactly +this way. +. +.NH 2 +Filled Objects +.PP +It is possible to fill boxes, circles, and ellipses. +The modifier \fBfill[ed]\fP accomplishes this. +You can suffix it with a fill value; the default is given by the style +variable \fBfillval\fP. +.PP +DWB \fBpic\fP and \fBgpic\fP have opposite conventions for fill values +and different defaults. +DWB \fBfillval\fP defaults to 0.3 and smaller values are darker; GNU +\fBfillval\fP uses 0 for white and 1 for black. +.KS +.PS +circle fill; move; circle fill 0.4; move; circle fill 0.9; +.PE +.CE "6: \fBcircle fill; move; circle fill 0.4; move; circle fill 0.9;\fR" +.PP +GNU \fBgpic\fP makes some additional guarantees. +A fill value greater than 1 can also be used: this means fill with the +shade of gray that is currently being used for text and lines. +Normally this is black, but output devices may provide a mechanism for +changing this. +The invisible attribute does not affect the filling of objects. +Any text associated with a filled object is added after the object has +been filled, so that the text is not obscured by the filling. +. +.NH 2 +Colored Objects +.PP +As a GNU extension, three additional modifiers are available to specify +colored objects. +\fBoutline\fP sets the color of the outline, \fBshaded\fP the fill +color, and \fBcolor\fP sets both. +All three keywords expect a suffix specifying the color. +Example: +.KS +.PS +box color "yellow"; arrow color "cyan"; circle shaded "green" outline "black"; +.PE +.CE "7: \fBbox color ""yellow""; arrow color ""cyan""; \ +circle shaded ""green"" outline ""black"";\fR" +.PP +Alternative spellings are \fBcolour\fP, \fBcolored\fP, \fBcoloured\fP, +and \fBoutlined\fP. +.PP +Predefined color names for \fI[gtn]roff\/\fP-based \fBpic\fP +implementations are defined in the device macro files, for example +\f(CWps.tmac\fP; additional colors can be defined with the +\fB.defcolor\fP request (see the manual page of GNU \fItroff\/\fP(1) +for more details). +Currently, color support is not available at all in \*[tx] mode. +.PP +The \fIpic2plot\/\fP(1) carries with its own set of color names, +essentially those recognized by the X\~window system with \[lq]grey\[rq] +accepted as a variant of \[lq]gray\[rq]. +.PP +\fBpic\fP assumes that at the beginning of a picture both glyph and fill +color are set to the default value. +. +. +.NH 1 +More About Text Placement +.PP +By default, text is centered at the geometric center of the object it is +associated with. +The modifier \fBljust\fP causes the left end to be at the specified +point (which means that the text lies to the right of the specified +place!), the modifier \fBrjust\fP puts the right end at the place. +The modifiers \fBabove\fP and \fBbelow\fP center the text one half line +space in the given direction. +.PP +Text attributes can be combined: +.KS +.PS +[line up "ljust text" ljust;] +move 1.5; +[line up "rjust text" rjust;] +move; +[arrow 1 "ljust above" ljust above;] +move; +[arrow 1 "rjust below" rjust below;] +.PE +.CE "1: Text attributes" +.PP +What actually happens is that \fIn\fP text strings are centered in a box +that is \fBtextwid\fP wide by \fBtextht\fP high. +Both these variables are initially zero (that is \fBpic\fR's way of not +making assumptions about \fI[tg]roff\/\fP(1)'s default point size). +.PP +In GNU \fBgpic\fR, objects can have an +.B aligned +attribute. +This only works if the postprocessor is +\fBgrops\fP or \fBgropdf\fP. +Any text associated with an object having the +.B aligned +attribute is rotated about the center of the object +so that it is aligned in the direction from the start point +to the end point of the object. +Note that this attribute has no effect for objects whose start and +end points are coincident. +. +. +.NH 1 +More About Direction Changes +.PP +We've already seen how to change the direction in which objects are +composed from rightwards to downwards. +Here are some more illustrative examples: +.KS +.PS +down; +[ + "\fBright; box; arrow; circle; arrow; ellipse\fP"; + move 0.2; + [right; box; arrow; circle; arrow; ellipse;] +] +move down 0.3 from last [] .s; +[ + "\fBleft; box; arrow; circle; arrow; ellipse\fP" + move 0.2; + [left; box; arrow; circle; arrow; ellipse;] +] +# move down 0.3 from last [] .sw; +# To re-join this illustrations, delete everything from here down to +# the next #-comment, and uncomment the move line above +.PE +.CE "1: Effects of different motion directions (right and left)" +.KS +.PS +# To re-join this illustrations, delete everything down to here, then +# comment out the next `down' line. +# Don't forget to re-number the figures following! +down; +[ + "\fBdown; box; arrow; circle; arrow; ellipse;\fP" + move 0.2; + box; arrow; circle; arrow; ellipse; +] +move right 2 from last [] .e; +[ + up; box; arrow; circle; arrow; ellipse; + move 0.2; + "\fBup; box; arrow; circle; arrow; ellipse;\fP" +] +.PE +.CE "2: Effects of different motion directions (up and down)" +.PP +Something that may appear surprising happens if you change directions +in the obvious way: +.KS +.PS +box; arrow; circle; down; arrow; ellipse +.PE +.CE "3: \fBbox; arrow; circle; down; arrow; ellipse\fP" +.LP +You might have expected that program to yield this: +.KS +.PS +box; arrow; circle; move to last circle .s; down; arrow; ellipse +.PE +.CE "4: More intuitive?" +.LP +But, in fact, to get Figure \*[SN]3 you have to do this: +.KS +.DS +.CW +\&.PS +box; +arrow; +circle; +move to last circle .s; +down; +arrow; +ellipse +\&.PE +.R +.DE +.KE +.LP +Why is this? +Because the exit point for the current direction is already set when you +draw the object. +The second arrow in Figure \*[SN]2 dropped downwards from the circle's +attachment point for an +object to be joined to the right. +.PP +The meaning of the command \fBmove to last circle \&.s\fP should be +obvious. +In order to see how it generalizes, we'll need to go into detail on two +important topics; locations and object names. +. +. +.NH 1 +Naming Objects +.PP +The most natural way to name locations in \fBpic\fP is relative to +objects. +In order to do this, you have to be able to name +objects. +The \fBpic\fP language has rich facilities for this that try to emulate +the syntax of English. +. +.NH 2 +Naming Objects By Order Of Drawing +.PP +The simplest (and generally the most useful) way to name an object is +with a \fBlast\fP clause. +It needs to be followed by an object type name; \fBbox\fP, \fBcircle\fP, +\fBellipse\fP, \fBline\fP, \fBarrow\fP, \fBspline\fP, \fB""\fP, or +\fB[]\fP (the last type refers to a \fIcomposite object\fP which we'll +discuss later). +So, for example, the \fBlast circle\fP clause in the program attached to +Figure \*[SN]3 refers to the last circle drawn. +.PP +More generally, objects of a given type are implicitly numbered +(starting from\~1). +You can refer to (say) the third ellipse in the current picture with +\fB3rd ellipse\fP, or to the first box as \fB1st box\fP, or to the fifth +text string (which isn't an attribute to another object) as \fB5th +""\fP. +.PP +Objects are also numbered backwards by type from the last one. +You can say \fB2nd last box\fP to get the second-to-last box, or +\fB3rd last ellipse\fP to get the third-to-last ellipse. +.PP +In places where \fIn\/\fBth\fR is allowed, \fB`\fIexpr\/\fB'th\fR is +also allowed. +Note that +.B 'th +is a single token: no space is allowed between the +.B ' +and the \fBth\fP. +For example, +.IP +.KS +.DS +.CW +for i = 1 to 4 do { + line from `i'th box.nw to `i+1'th box.se +} +.DE +.R +.KE +. +.NH 2 +Naming Objects With Labels +.PP +You can also specify an object by referring to a label. +A label is a word (which must begin with a capital letter) followed by a +colon; you declare it by placing it immediately before the object +drawing command. +For example, the program +.KS +.DS +.CW +\&.PS +A: box "first" "object" +move; +B: ellipse "second" "object" +move; +arrow right at A .r; +\&.PE +.R +.DE +.KE +.LP +declares labels \fBA\fP and \fBB\fP for its first and second objects. +Here's what that looks like: +.KS +.PS +A: box "first" "object" +move; +B: ellipse "second" "object" +move; +arrow right at A .r; +.PE +.CE "1: Example of label use" +The \fBat\fP statement in the fourth line uses the label \fBA\fP (the +behavior of \fBat\fP is explained in the next section). +We'll see later on that labels are most useful for referring to block +composite objects. +.PP +Labels are not constants but variables (you can view colon as a sort +of assignment). +You can say something like \fBA: A + (1,0);\fP and the effect is to +reassign the label \fBA\fR to designate a position one inch to the right +of its old value. +. +. +.NH 1 +Describing locations +.PP +The location of points can be described in many different ways. +All these forms are interchangeable as for as the \fBpic\fP language +syntax is concerned; where you can use one, any of the others that would +make semantic sense are allowed. +.PP +The special label \fBHere\fR always refers to the current position. +. +.NH 2 +Absolute Coordinates +.PP +The simplest is absolute coordinates in inches; \fBpic\fP uses a +Cartesian system with (0,0) at the lower left corner of the virtual +drawing surface for each picture (that is, X\~increases to the right +and Y\~increases upwards). +An absolute location may always be written in the conventional form as +two comma-separated numbers surrounded by parentheses (and this is +recommended for clarity). +In contexts where it creates no ambiguity, the pair of X and +Y\~coordinates suffices without parentheses. +.PP +It is a good idea to avoid absolute coordinates, however. +They tend to make picture descriptions difficult to understand and +modify. +Instead, there are quite a number of ways to specify locations +relative to \fBpic\fP objects and previous locations. +.PP +Another possibility of surprise is the fact that \fBpic\fP crops the +picture to the smallest bounding box before writing it out. +For example, if you have a picture consisting of a small box with its +lower left corner at (2,2) and another small box with its upper right +corner at (5,5), the width and height of the image are both 3\~units and +not\~5. +To get the origin at (0,0) included, simply add an invisible object to +the picture, positioning the object's left corner at (0,0). +. +.NH 2 +Locations Relative to Objects +.PP +The symbol \fBHere\fP always refers to the position of the last object +drawn or the destination of the last \fBmove\fP. +.PP +Alone and unqualified, a \fBlast circle\fP or any other way of +specifying a closed-object or arc location refers as a position to the +geometric center of the object. +Unqualified, the name of a line or spline object refers to the position +of the object start. +.PP +Also, \fBpic\fP objects have quite a few named locations +associated with them. +One of these is the object center, which can be indicated (redundantly) +with the suffix \fB.center\fP (or just \fB.c\fP). +Thus, \fBlast circle \&.center\fP is equivalent to \fBlast +circle\fP. +.NH 3 +Locations Relative to Closed Objects +.PP +Every closed object (box, circle, ellipse, or block composite) also +has eight compass points associated with it; +.KS +.PS +define dot {circle fill rad 0.02 at $1} + +define compass { [ + ME: $1; + dot(ME.c); "\fB .c\fP" at ME .c ljust; + dot(ME.n); "\fB.n\fP" at ME .n above + dot(ME.ne); "\fB .ne\fP" at ME .ne above + dot(ME.e); "\fB .e\fP" at ME .e ljust + dot(ME.se); "\fB .se\fP" at ME .se below + dot(ME.s); "\fB.s\fP" at ME .s below + dot(ME.sw); "\fB.sw \fP" at ME .sw below + dot(ME.w); "\fB.w \fP" at ME .w rjust + dot(ME.nw); "\fB.nw \fP" at ME .nw above +] } +compass(box wid 1.5 ht 1); +move right from last [] .e; +compass(circle diam 1); +move right from last [] .e; +compass(ellipse wid 1.5 ht 1); +.PE +.CE "1: Compass points" +.LP +these are the locations where eight compass rays from the geometric center +would intersect the figure. +So when we say \fBlast circle \&.s\fP we are referring to the south +compass point of the last circle drawn. +The explanation of Figure 8-3's program is now complete. +.PP +(In case you dislike compass points, the names \fB.top\fP, +\&\fB.bottom\fP, \fB.left\fP and \fB.right\fP are synonyms for \fB.n\fP, +\&\fB.s\fP, \fB.e\fP, and \fB.w\fP respectively; they can even be +abbreviated to \fB.t\fP, \fB.b\fP, \fB.l\fP and \fB.r\fP). +.PP +The names \fBcenter\fP, \fBtop\fP, \fBbottom\fP, \fBleft\fP, \fBright\fP, +\fBnorth\fP, \fBsouth\fP, \fBeast\fP, and \fBwest\fP can also be used +(without the leading dot) in a prefix form marked by \fBof\fP; thus, +\fBcenter of last circle\fP and \fBtop of 2nd last ellipse\fP are both +valid object references. +Finally, the names \fBleft\fP and \fBright\fP can be prefixed with +\fBupper\fP and \fBlower\fP which both have the obvious meaning. +.PP +Arc objects also have compass points; they are the compass points of +the implied circle. +.PP +Non-closed objects (line, arrow, or spline) have compass points too, but +the locations of them are completely arbitrary. +In particular, different \fBpic\fP implementations return different +locations. +.NH 3 +Locations Relative to Open Objects +.PP +Every open object (line, arrow, arc, or spline) has three named +points: \fB.start\fP, \fB.center\fP (or \fB.c\fP), and \fB.end\fP. +They can also be used without leading dots in the \fBof\fP prefix form. +The center of an arc is the center of its circle, but the center of +a line, path, or spline is halfway between its endpoints. +.KS +.PS +define critical { + [ ME: $1; + dot(ME.c); "\fB.center\fP" rjust at ME.center + (-0.1, 0.1) + dot(ME.start); "\fB.start\fP" rjust at ME.start + (-0.1, 0.1) + dot(ME.end); "\fB.end\fP" rjust at ME.end + (-0.1, 0.1) + ] +} +critical(line up right 1); +move right 1 from last [] .e; +critical(arc rad 0.5 cw); +move down 0.5 from 2nd last [] .s; +critical(line right 1 then down .5 left 1 then right 1); +move right 1 from last [] .e; +critical(spline right 1 then up right then left then left 1); +.PE +.CE "2: Special points on open objects" +.PP +. +.NH 2 +Ways of Composing Positions +.PP +Once you have two positions to work with, there are several ways to +combine them to specify new positions. +.NH 3 +Vector Sums and Displacements +.PP +Positions may be added or subtracted to yield a new position (to be +more precise, you can only add a position and an expression pair; the +latter must be on the right side of the addition or subtraction sign). +The result is the conventional vector sum or difference of coordinates. +For example, \fBlast box \&.ne + (0.1, 0)\fP is a valid position. +This example illustrates a common use, to define a position slightly +offset from a named one (say, for captioning purposes). +.NH 3 +Interpolation Between Positions +.PP +A position may be interpolated between any two positions. +The syntax is `\fIfraction\fP \fBof the way between\fP \fIposition1\fP +\fBand\fP \fIposition2\fP'. +For example, you can say \fB1/3 of the way between Here and last ellipse +\&.ne\fP. +The fraction may be in numerator/denominator form or may be an ordinary +number (values are \fInot\fP restricted to [0,1]). +As an alternative to this verbose syntax, you can say `\fIfraction\fP +\fB<\,\fP\fIposition1\fP \fB,\fP \fIposition2\/\fP\fB>\fP'; thus, the +example could also be written as \fB1/3 <Here, last ellipse>\fP. +.KS +.PS +arrow up right; +P: 1/3 of the way between last arrow .start and last arrow .end; +dot(P); move right 0.1; "P"; +.PE +.CE "3: \fBP: 1/3 of the way between last arrow .start and last arrow .end\fP" +.PP +This facility can be used, for example, to draw double connections. +.KS +.PS +A: box "yin"; move; +B: box "yang"; +arrow right at 1/4 <A.e,A.ne>; +arrow left at 1/4 <B.w,B.sw>; +.PE +.CE "4: Doubled arrows" +.LP +You can get Figure \n[H1]-4 from the following program: +.KS +.DS +.CW +\&.PS +A: box "yin"; move; +B: box "yang"; +arrow right at 1/4 <A.e,A.ne>; +arrow left at 1/4 <B.w,B.sw>; +\&.PE +.R +.DE +.KE +.LP +Note the use of the short form for interpolating points. +.NH 3 +Projections of Points +.PP +Given two positions \fIp\fP and \fIq\fP, the position +\fB(\,\fP\fIp\fP\fB,\fP \fIq\fP\fB)\fP has the X\~coordinate of \fIp\fP +and the Y coordinate of \fIq\fP. +This can be helpful in placing an object at one of the corners of the +virtual box defined by two other objects. +.KS +.PS +box invis wid 2 height 1; +dot(last box .ne); "\fB(B,A)\fP is here" ljust at last circle + (0.1, 0.1); +dot(last box .se); "B" ljust at last circle + (0.1, -0.1) +dot(last box .sw); "\fB(A,B)\fP is here" rjust at last circle + (-0.1, -0.1); +dot(last box .nw); "A" ljust at last circle + (-0.1, 0.1) +.PE +.CE "5: Using (\fIx\fP, \fIy\fP) composition" +. +.NH 2 +Using Locations +.PP +There are four ways to use locations; \fBat\fP, \fBfrom\fP, \fBto\fP, +and \fBwith\fP. +All four are object modifiers; that is, you use them as suffixes to a +drawing command. +.PP +The \fBat\fP modifier says to draw a closed object or arc with its +center at the following location, or to draw a line/spline/arrow +starting at the following location. +.PP +The \fBto\fP modifier can be used alone to specify a move destination. +The \fBfrom\fP modifier can be used alone in the same way as \fBat\fP. +.PP +The \fBfrom\fP and \fBto\fP modifiers can be used with a \fBline\fR or +\fBarc\fR command to specify start and end points of the object. +In conjunction with named locations, this offers a very flexible +mechanism for connecting objects. +For example, the following program +.KS +.DS +.CW +\&.PS +box "from" +move 0.75; +ellipse "to" +arc cw from 1/3 of the way \e + between last box .n and last box .ne to last ellipse .n; +\&.PE +.R +.DE +.KE +.LP +yields: +.KS +.PS +box "from" +move 0.75; +ellipse "to" +arc cw from 1/3 of the way \ + between last box .n and last box .ne to last ellipse .n; +.PE +.CE "6: A tricky connection specified with English-like syntax" +.PP +The \fBwith\fP modifier allows you to identify a named attachment +point of an object (or a position within the object) with another point. +This is very useful for connecting objects in a natural way. +For an example, consider these two programs: +.KS +.PS +[ + [ + box wid 0.5 ht 0.5; + box wid 0.75 ht 0.75; + ] + move 0.1 down 0.3 from last [] .s; + "\fBbox wid 0.5 ht 0.5; box wid 0.75 ht 0.75\fP" +] +move from last [].e 1.5 +[ + [ + box wid 0.5 ht 0.5; + box wid 0.75 ht 0.75 with .sw at last box .se; + ] + move 0.1 down 0.3 from last [] .s; + box invisible "\fBbox wid 0.5 ht 0.5;\fP" \ + "\fBbox wid 0.75 ht 0.75 with .sw at last box .se;\fP" +] +.PE +.CE "7: Using the \fBwith\fP modifier for attachments" +. +.NH 2 +The `chop' Modifier +.PP +When drawing lines between circles that don't intersect them at a +compass point, it is useful to be able to shorten a line by the radius +of the circle at either or both ends. +Consider the following program: +.KS +.DS +.CW +\&.PS +circle "x" +circle "y" at 1st circle - (0.4, 0.6) +circle "z" at 1st circle + (0.4, -0.6) +arrow from 1st circle to 2nd circle chop +arrow from 2nd circle to 3rd circle chop +arrow from 3rd circle to 1st circle chop +\&.PE +.DE +.R +.KE +.LP +It yields the following: +.KS +.PS +circle "x" +circle "y" at 1st circle - (0.4, 0.6) +circle "z" at 1st circle + (0.4, -0.6) +arrow from 1st circle to 2nd circle chop +arrow from 2nd circle to 3rd circle chop +arrow from 3rd circle to 1st circle chop +.PE +.CE "8: The \fBchop\fR modifier" +.LP +Notice that the \fBchop\fR attribute moves arrowheads rather than +stepping on them. +By default, the \fBchop\fR modifier shortens both ends of the line by +\fBcirclerad\fR. +By suffixing it with a number you can change the amount of chopping. +.PP +If you say \fBline \&.\|.\|.\& chop \fIr1\fP chop \fIr2\fP\fR with +\fIr1\fP and \fIr2\fP both numbers, you can vary the amount of chopping +at both ends. +You can use this in combination with trigonometric functions to write +code that deals with more complex intersections. +. +. +.NH 1 +Object Groups +.PP +There are two different ways to group objects in \fBpic\fP; \fIbrace +grouping\fP and \fIblock composites\fP. +. +.NH 2 +Brace Grouping +.PP +The simpler method is simply to group a set of objects within curly +bracket or brace characters. +On exit from this grouping, the current position and direction are +restored to their value when the opening brace was encountered. +. +.NH 2 +Block Composites +.PP +A block composite object is created a series of commands enclosed by +square brackets. +The composite can be treated for most purposes like a single closed +object, with the size and shape of its bounding box. +Here is an example. +The program fragment +.KS +.DS +.CW +A: [ + circle; + line up 1 at last circle .n; + line down 1 at last circle .s; + line right 1 at last circle .e; + line left 1 at last circle .w; + box dashed with .nw at last circle .se + (0.2, -0.2); + Caption: center of last box; +] +.R +.DE +.KE +.LP +yields the block in figure \n[H1]-1, which we show both with and +without its attachment points. +The block's location becomes the value of \fBA\fP. +.KS +.PS +define junction { + circle; + line up 1 at last circle .n; + line down 1 at last circle .s; + line right 1 at last circle .e; + line left 1 at last circle .w; + box dashed with .nw at last circle .se + (0.2, -0.2); + Caption: center of last box; +} +[junction();] +move; +compass([junction()]); +.PE +.CE "1: A sample composite object" +.LP +To refer to one of the composite's attachment points, you can say +(for example) \fBA \&.s\fP. +For purposes of object naming, composites are a class. +You could write \fBlast [] \&.s\fP as an equivalent reference, usable +anywhere a location is needed. +This construction is very important for putting together large, +multi-part diagrams. +.PP +Blocks are also a variable-scoping mechanism, like a \fIgroff\/\fP(1) +environment. +All variable assignments done inside a block are undone at the end of it. +To get at values within a block, write a name of the block followed by a +dot, followed by the label you want. +For example, we could refer the center of the box in the above composite as +\fBlast [] \&.Caption\fP or \fBA.Caption\fP. +.PP +This kind of reference to a label can be used in any way any other +location can be. +For example, if we added \fB"Hi!" at A.Caption\fP +the result would look like this: +.KS +.PS +A: [junction();] +"Hi!" at A.Caption; +.PE +.CE "2: Adding a caption using interior labeling" +.PP +You can also use interior labels in either part of a \fBwith\fR +modifier. +This means that the example composite could be placed relative to its +caption box by a command containing \fBwith A.Caption at\fP. +.PP +Note that both width and height of the block composite object are always +positive: +.KS +.PS +[ + [ + box wid -0.5 ht 0.5 + box wid 0.75 ht 0.75 + ] + move 0.1 down 0.3 from last [].s + "\fBbox wid -0.5 ht 0.5; box wid 0.75 ht 0.75\fP" +] +move from last [].e 2 +[ + [ + [ box wid -0.5 ht 0.5 ] + box wid 0.75 ht 0.75 + ] + move 0.1 down 0.3 from last [].s + "\fB[box wid -0.5 ht 0.5]; box wid 0.75 ht 0.75\fP" +] +.PE +.CE "3: Composite block objects always have positive width and height" +.PP +Blocks may be nested. +This means you can use block attachment points to build up complex +diagrams hierarchically, from the inside out. +Note that \fBlast\fP and the other sequential naming mechanisms +don't look inside blocks, so if you have a program that looks +like +.KS +.DS +.CW +\&.PS +P: [box "foo"; ellipse "bar"]; +Q: [ + [box "baz"; ellipse "quxx"] + "random text"; + ] +arrow from 2nd last []; +\&.PE +.R +.DE +.KE +.LP +the arrow in the last line is attached to object \fBP\fP, not +object \fBQ\fP. +.PP +In DWB \fBpic\fP, only references one level deep into enclosed blocks +were permitted. +GNU \fBgpic\fP removes this restriction. +.PP +The combination of block variable scoping, assignability of labels and +the macro facility that we'll describe later on can be used to +simulate functions with local variables (just wrap the macro body in +block braces). +. +. +.NH 1 +Style Variables +.PP +There are a number of global style variables in \fBpic\fR that can be used to +change its overall behavior. +We've mentioned several of them in previous sections. +They're all described here. +For each variable, the default is given. +.TS H +center, tab(@), linesize(2); +lb | lb | lb +l | n | l. +.sp 2p +Style Variable@Default@What It Does +.sp 2p +_ +.sp 2p +.TH +boxht@0.5@Default height of a box +boxwid@0.75@Default width of a box +lineht@0.5@Default length of vertical line +linewid@0.75@Default length of horizontal line +linethick@-1@Default line thickness +arcrad @0.25@Default radius of an arc +circlerad@0.25@Default radius of a circle +ellipseht@0.5@Default height of an ellipse +ellipsewid@0.75@Default width of an ellipse +moveht@0.5@Default length of vertical move +movewid@0.75@Default length of horizontal move +textht@0@Default height of box enclosing a text object +textwid@0@Default width of box enclosing a text object +arrowht@0.1@Length of arrowhead along shaft +arrowwid@0.05@Width of rear of arrowhead +arrowhead@1@Enable/disable arrowhead filling +dashwid@0.05@Interval for dashed lines +maxpswid@8.5@Maximum width of picture +maxpsht@11@Maximum height of picture +scale@1@Unit scale factor +fillval@0.5@Default fill value +.sp 5p +_ +.TE +Any of these variables can be set with a simple assignment statement. +For example: +.KS +.PS +[boxht=1; boxwid=0.3; movewid=0.2; box; move; box; move; box; move; box;] +.PE +.CE "1: \fBboxht=1; boxwid=0.3; movewid=0.2; box; move; box; move; box; move; box;\fP" +.PP +In GNU \fBpic\fR, setting the \fBscale\fR variable re-scales all +size-related state variables so that their values remain equivalent in +the new units. +.PP +The command \fBreset\fP resets all style variables to their defaults. +You can give it a list of variable names as arguments (optionally +separated by commas), in which case it resets only those. +.PP +State variables retain their values across pictures until reset. +. +. +.NH 1 +Expressions, Variables, and Assignment +.PP +A number is a valid expression, of course (all numbers are stored +internally as floating-point). +Decimal-point notation is acceptable; +in GNU \fBgpic\fR, scientific notation in C's `e' format (like +\f(CW5e-2\fP) is accepted. +.PP +Anywhere a number is expected, the language also accepts a +variable. +Variables may be the built-in style variable described in the last +section, or new variables created by assignment. +.PP +DWB \fBpic\fP supports only the ordinary assignment via \fB=\fP, which +defines the variable (on the left side of the equal sign) in the current +block if it is not already defined there, and then changes the value (on +the right side) in the current block. +The variable is not visible outside of the block. +This is similar to the C\~programming language where a variable within a +block shadows a variable with the same name outside of the block. +.PP +GNU \fBgpic\fP supports an alternate form of assignment using \fB:=\fP. +The variable must already be defined, and the value is assigned to +that variable without creating a variable local to the current block. +For example, this +.KS +.DS +.CW +x=5 +y=5 +[ + x:=3 + y=3 +] +print x " " y +.DE +.KE +.LP +prints \fB3 5\fP. +.PP +You can use the height, width, radius, and x and y coordinates of any +object or corner in expressions. +If \fBA\fP is an object label or name, all the following are valid: +.KS +.DS +.CW +A.x # x coordinate of the center of A +A.ne.y # y coordinate of the northeast corner of A +A.wid # the width of A +A.ht # and its height +2nd last circle.rad # the radius of the 2nd last circle +.R +.DE +.KE +.LP +Note the second expression, showing how to extract a corner coordinate. +.PP +Basic arithmetic resembling those of C operators are available; \fB+\fP, +\fB*\fP, \fB-\fP, \fB/\fP, and \fB%\fP. +So is \fB^\fP for exponentiation. +Grouping is permitted in the usual way using parentheses. +GNU \fBgpic\fP allows logical operators to appear in expressions; +\fB!\&\fP (logical negation, not factorial), \fB&&\fP, \fB|\||\fP, +\fB==\fP, \fB!=\fP, \fB>=\fP, \fB<=\fP, \fB<\fP, \fB>\fP. +.PP +Various built-in functions are supported: \fBsin(\fIx\fB)\fR, +\fBcos(\fIx\fB)\fR, \fBlog(\fIx\fB)\fR, \fBexp(\fIx\fB)\fR, +\fBsqrt(\fIx\fB)\fR, \fBmax(\fIx\fB,\fIy\fB)\fR, +\fBatan2(\fIx\fB,\fIy\fB)\fR, \fBmin(\fIx\fB,\fIy\fB)\fR, +\fBint(\fIx\fB)\fR, \fBrand()\fP, and \fBsrand()\fP. +Both \fBexp\fP and \fBlog\fP are +base\~10; \fBint\fP does integer truncation; \fBrand()\fP returns a +random number in [0-1), and \fBsrand()\fP sets the seed for +a new sequence of pseudo-random numbers to be returned by \fBrand()\fP +(\fBsrand()\fP is a GNU extension). +.PP +GNU \fBgpic\fP also documents a one-argument form or rand, +\fBrand(\fIx\fB)\fR, which returns a random number between 1 and +\fIx\fP, but this is deprecated and may be removed in a future +version. +.PP +The function \fBsprintf()\fP behaves like a C \fIsprintf\/\fP(3) +function that only takes %%, %e, %E, %f, %g, and %G conversion +specifications. +. +. +.NH 1 +Macros +.PP +You can define macros in \fBpic\fP, with up to 32 arguments (up to 16 +on EBCDIC platforms). +This is useful for diagrams with repetitive parts. +In conjunction with the scope rules for block composites, it effectively +gives you the ability to write functions. +.PP +The syntax is +.DS +.CW +\fBdefine\fP \fIname\fP \fB{\fP \fIreplacement text \fB}\fP +.R +.DE +.LP +This defines \fIname\fR as a macro to be replaced by the replacement +text (not including the braces). +The macro may be called as +.DS +.CW +\fIname\fB(\fIarg1, arg2, \|.\|.\|.\& argn\fB)\fR +.R +.DE +.LP +The arguments (if any) are substituted for tokens \fB$1\fP, \fB$2\fP +\&.\|.\|.\& \fB$n\fP +appearing in the replacement text. +.PP +As an example of macro use, consider this: +.KS +.DS +.CW +.ps -1 +.vs -1 +\&.PS +# Plot a single jumper in a box, $1 is the on-off state. +define jumper { [ + shrinkfactor = 0.8; + Outer: box invis wid 0.45 ht 1; + + # Count on end ] to reset these + boxwid = Outer.wid * shrinkfactor / 2; + boxht = Outer.ht * shrinkfactor / 2; + + box fill (!$1) with .s at center of Outer; + box fill ($1) with .n at center of Outer; +] } + +# Plot a block of six jumpers. +define jumperblock { + jumper($1); + jumper($2); + jumper($3); + jumper($4); + jumper($5); + jumper($6); + + jwidth = last [].Outer.wid; + jheight = last [].Outer.ht; + + box with .nw at 6th last [].nw wid 6*jwidth ht jheight; + + # Use {} to avoid changing position from last box draw. + # This is necessary so move in any direction works as expected + {"Jumpers in state $1$2$3$4$5$6" at last box .s + (0,-0.2);} +} + +# Sample macro invocations. +jumperblock(1,1,0,0,1,0); +move; +jumperblock(1,0,1,0,1,1); +\&.PE +.ps +.vs +.R +.DE +.KE +.LP +It yields the following: +.KS +.PS +# Plot a single jumper in a box, $1 is the on-off state. +define jumper { [ + shrinkfactor = 0.8; + Outer: box invis wid 0.45 ht 1; + + # Count on end ] to reset these + boxwid = Outer.wid * shrinkfactor / 2; + boxht = Outer.ht * shrinkfactor / 2; + + box fill (!$1) with .s at center of Outer; + box fill ($1) with .n at center of Outer; +] } + +# Plot a block of six jumpers +define jumperblock { + jumper($1); + jumper($2); + jumper($3); + jumper($4); + jumper($5); + jumper($6); + + jwidth = last [].Outer.wid; + jheight = last [].Outer.ht; + + box with .nw at 6th last [].nw wid 6*jwidth ht jheight; + + # Use {} to avoid changing position from last box draw. + # This is necessary so move in any direction works as expected + {"Jumpers in state $1$2$3$4$5$6" at last box .s + (0,-0.2);} +} + +# Sample macro invocations +jumperblock(1,1,0,0,1,0); +move 0.25; +jumperblock(1,0,1,0,1,1); +.PE +.CE "1: Sample use of a macro" +.LP +This macro example illustrates how you can combine [], brace grouping, +and variable assignment to write true functions. +.PP +One detail the example above does not illustrate is the fact that +macro argument parsing is not token-oriented. +If you call \fBjumper(\~1\~)\fP, the value of $1 is \fB"\~1\~"\fP. +You could even call \fBjumper(big\~string)\fP to give $1 the value +\fB"big\~string"\fP. +.PP +If you want to pass in a coordinate pair, you can avoid getting +tripped up by the comma by wrapping the pair in parentheses. +.PP +Macros persist through pictures. +To undefine a macro, say \fBundef\fP \fIname\fR; for example, +.DS +\f(CWundef jumper\fP +\f(CWundef jumperblock\fP +.DE +.LP +would undefine the two macros in the jumper block example. +. +. +.NH 1 +Import/Export Commands +.PP +Commands that import or export data between \fBpic\fR and its +environment are described here. +. +.NH 2 +File and Table Insertion +.PP +The statement +.DS +\f(CWcopy\fP \fIfilename\fR +.DE +.LP +inserts the contents of \fIfilename\fR in the \fBpic\fP input stream. +Any \fB.PS\fP/\fB.PE\fP pair in the file is ignored. +You can use this to include pre-generated images. +.PP +A variant of this statement replicates the \fBcopy thru\fP feature of +\fIgrap\/\fP(1). +The call +.DS +\f(CWcopy\fP \fIfilename\fR \f(CWthru\fP \fImacro\fP +.DE +.LP +calls \fImacro\fP (which may be either a name or replacement text) +on the arguments obtained by breaking each line of the file into +blank-separated fields. +The macro may have up to 9\~arguments. +The replacement text may be delimited by braces or by a pair of +instances of any character not appearing in the rest of the text. +.PP +If you write +.DS +\f(CWcopy\fP \f(CWthru\fP \fImacro\fP +.DE +.LP +omitting the filename, lines to be parsed are taken from the input +source up to the next \fB.PE\fP. +.PP +In either of the last two \fBcopy\fP commands, GNU \fBgpic\fP permits a +trailing `\fBuntil\fP \fIword\/\fP' clause to be added which terminates +the copy when the first word matches the argument (the default +behavior is therefore equivalent to \fBuntil \&.PE\fP). +.PP +Accordingly, the command +.RS +.KS +.IP +.CW +.nf +\&.PS +copy thru % circle at ($1,$2) % until "END" +1 2 +3 4 +5 6 +END +box +\&.PE +.R +.fi +.KE +.RE +.LP +is equivalent to +.RS +.KS +.IP +.CW +.nf +\&.PS +circle at (1,2) +circle at (3,4) +circle at (5,6) +box +\&.PE +.R +.fi +.KE +.RE +. +.NH 2 +Debug Messages +.PP +The command \fBprint\fR accepts any number of arguments, concatenates +their output forms, and writes the result to standard error. +Each argument must be an expression, a position, or a text string. +. +.NH 2 +Escape to Post-Processor +.PP +If you write +.DS +\fBcommand\fR \fIarg\fR\|.\|.\|. +.DE +.LP +\fBpic\fP concatenates the arguments and pass them through as a line +to troff or \*[tx]. +Each +.I arg +must be an expression, a position, or text. +This has a similar effect to a line beginning with +.B . +or +\fB\e\fR\|, +but allows the values of variables to be passed through. +.LP +For example, +.KS +.DS +.CW +.nf +\&.PS +x = 14 +command ".ds string x is " x "." +\&.PE +\e*[string] +.DE +.R +.KE +.LP +prints +.DS +.CW +x is 14. +.R +.DE +. +.NH 2 +Executing Shell Commands +.PP +The command +.DS +\f(CWsh\fP \f(CW{\fP \fIanything.\|.\|.\fP \f(CW}\fP +.DE +.LP +macro-expands the text in braces, then executes it as a shell command. +This could be used to generate images or data tables for later +inclusion. +The delimiters shown as {} here may also be two copies of any one +character not present in the shell command text. +In either case, the body may contain balanced {} pairs. +Strings in the body may contain balanced or unbalanced braces in any +case. +. +. +.NH 1 +Control-flow constructs +.PP +The \fBpic\fP language provides conditionals and looping. +For example, +.KS +.DS +.CW +pi = atan2(0,-1); +for i = 0 to 2 * pi by 0.1 do { + "-" at (i/2, 0); + "." at (i/2, sin(i)/2); + ":" at (i/2, cos(i)/2); +} +.R +.DE +.KE +.LP +which yields this: +.KS +.PS +pi = atan2(0,-1); +for i = 0 to 2 * pi by 0.1 do { + "-" at (i/2, 0); + "." at (i/2, sin(i)/2); + ":" at (i/2, cos(i)/2); +} +.PE +.CE "1: Plotting with a \fBfor\fP loop" +.LP +The syntax of the \fBfor\fP statement is: +.DS +\fBfor\fR \fIvariable\fR \fB=\fR \fIexpr1\/\fR \fBto\fR \fIexpr2\/\fR \ +[\fBby\fR [\fB*\fR]\fIexpr3\/\fR] \fBdo\fR \fIX\fR \fIbody\fR \fIX\fR +.DE +The semantics are as follows: Set +.I variable +to \fIexpr1\fR. +While the value of +.I variable +is less than or equal to +\fIexpr2\fR, +do +.I body +and increment +.I variable +by +\fIexpr3\fR; +if +.B by +is not given, increment +.I variable +by\~1. +If +.I expr3 +is prefixed by\~\c +.B * +then +.I variable +is multiplied instead by +\fIexpr3\fR. +The value of +.I expr3 +can be negative for the additive case; +.I variable +is then tested whether it is greater than or equal to +\fIexpr2\fR. +For the multiplicative case, +.I expr3 +must be greater than zero. +If the constraints aren't met, the loop isn't executed. +.I X +can be any character not occurring in +\fIbody\fR; or the two \fIX\/\fPs may be paired braces (as in the +\fBsh\fR command). +.PP +The syntax of the \fBif\fP statement is as follows: +.DS +\fBif\fR \fIexpr\fR \fBthen\fR \fIX\fR \fIif-true\fR \fIX\fR \ +[\fBelse\fR \fIY\fR \fIif-false\fR \fIY\/\fR] +.DE +Its semantics are as follows: Evaluate +\fIexpr\fR; +if it is non-zero then do +\fIif-true\fR, +otherwise do +\fIif-false\fR. +.I X +can be any character not occurring in +\fIif-true\fR. +.I Y +can be any character not occurring in +\fIif-false\fR. +.PP +Eithe or both of the +.I X +or +.I Y +pairs may instead be balanced pairs of +braces ({ and\~}) as in the \fBsh\fR command. +In either case, the \fIif-true\fR may contain balanced pairs of braces. +None of these delimiters are seen inside strings. +.PP +All the usual relational operators my be used in conditional expressions; +\fB!\&\fP (logical negation, not factorial), \fB&&\fP, \fB|\||\fP, \fB==\fP, +\fB!=\fP, \fB>=\fP, \fB<=\fP, \fB<\fP, \fB>\fP. +.PP +String comparison is also supported using \fB==\fP and \fB!=\fP. +String comparisons may need to be parenthesized to avoid syntactic +ambiguities. +. +. +.NH 1 +Interface To [gt]roff +.PP +The output of \fBpic\fP is \fB[gt]roff\fP drawing commands. +The GNU \fIgpic\/\fP(1) command warns that it relies on drawing +extensions present in \fIgroff\/\fP(1) that are not present in +\fItroff\/\fP(1). +. +.NH 2 +Scaling Arguments +.PP +The DWB \fIpic\/\fP(1) program accepts one or two arguments to +\&\fB.PS\fP, which is interpreted as a width and height in inches to +which the results of \fIpic\/\fP(1) should be scaled (width and height +scale independently). +If there is only one argument, it is interpreted as a width to scale the +picture to, and height is scaled by the same proportion. +.PP +GNU \fBgpic\fP is less general; it accepts a single width to scale +to, or a zero width and a maximum height to scale to. +With two non-zero arguments, it scales to the maximum height. +. +.NH 2 +How Scaling is Handled +.PP +When \fBpic\fP processes a picture description on input, it passes +\fB.PS\fP, \fB.PE\fP, and \fB.PF\fP through to the postprocessor. +The \fB.PS\fP gets decorated with two numeric arguments which are the X +and Y\~dimensions of the picture in inches. +The post-processor can use these to reserve space for the picture and +center it. +.PP +The GNU incarnation of the \fBms\fP macro package, for example, includes +the following definitions: +.KS +.DS +.ps -1 +.vs -1 +.CW +\&.de PS +\&.br +\&.sp \e\en[DD]u +\&.ie \e\en[.$]<2 .@error bad arguments to PS (not preprocessed with pic?) +\&.el \e{\e +\&. ds@need (u;\e\e$1)+1v +\&. in +(u;\e\en[.l]-\e\en[.i]-\e\e$2/2>?0) +\&.\e} +\&.. +\&.de PE +\&.par@reset +\&.sp \e\en[DD]u+.5m +\&.. +.R +.DE +.ps +.vs +.KE +.LP +Equivalent definitions of these and of \fB.PF\fP are supplied by GNU +\fIpic\/\fP(1) if you use the \-mpic option; this should make it usable +with macro pages other than \fIms\/\fR(1). +.PP +If \fB.PF\fP is used instead of \fB.PE\fP, the \fBtroff\fP position is +restored to what it was at the picture start (Kernighan notes that +the\~F stands for \[lq]flyback\[rq]). +.PP +The invocation +.DS +\&\fB.PS <\,\fP\fIfile\fP +.DE +.LP +causes the contents of \fIfile\fP to replace the \fB.PS\fP line. +This feature is deprecated; use `\fBcopy\fP \fIfile\fR' instead. +. +.NH 2 +PIC and [gt]roff commands +.PP +By default, input lines that begin with a period are passed to the +postprocessor, embedded at the corresponding point in the output. +Messing with horizontal or vertical spacing is an obvious recipe for +bugs, but point size and font changes are usually safe. +.PP +Point sizes and font changes are also safe within text strings, as +long as they are undone before the end of string. +.PP +The enablement of output line filling by \fB[gt]roff\fP is preserved +across pictures. +. +.NH 2 +PIC and EQN +.PP +The Kernighan paper notes that there is a subtle problem with +complicated equations inside \fBpic\fR pictures; they come out wrong if +\fIeqn\/\fP(1) has to leave extra vertical space for the equation. +If your equation involves more than subscripts and superscripts, you +must add to the beginning of each equation the extra information +\fBspace\~0\fP. +He gives the following example: +.KS +.DS +.CW +arrow +box "$space 0 {H( omega )} over {1 - H( omega )}$" +arrow +.R +.DE +.KE +.EQ +delim @@ +.EN +.KS +.PS +arrow +box "@space 0 {H( omega )} over {1 - H( omega )}@" +arrow +.PE +.CE "1: Equations within pictures" +. +.NH 2 +Absolute Positioning of Pictures +.PP +A \fBpic\fP picture is positioned vertically by troff at the current +position. +The topmost position possible on a page is not the paper edge +but a position which is one baseline lower so that the first row of glyphs +is visible. +To make a picture really start at the paper edge you have to make the +baseline-to-baseline distance zero, this is, you must set the vertical +spacing to\~0 (using \fB.vs\fP) before starting the picture. +. +. +.NH 1 +Interface to TeX +.PP +.PP +\*[tx] mode is enabled by the +.B \-t +option. +In \*[tx] mode, pic defines a vbox called +.B \egraph +for each picture; the name can be changed with the pseudo-variable +.B figname +(which is actually a specially parsed command). +You must yourself print that vbox using, for example, the command +.RS +.LP +.CW +\ecenterline{\ebox\egraph} +.RE +.LP +Actually, since the vbox has a height of zero (it is defined with \evtop) +this produces slightly more vertical space above the picture than +below it; +.RS +.LP +.CW +\ecenterline{\eraise 1em\ebox\egraph} +.RE +.LP +would avoid this. +.PP +To make the vbox having a positive height and a depth of zero (as used +e.g.\& by \*(lx's \f(CW\%graphics.sty\fP), define the following macro in +your document: +.KS +.DS +.CW +\edef\egpicbox#1{% + \evbox{\eunvbox\ecsname #1\eendcsname\ekern 0pt}} +.R +.DE +.KE +.LP +Now you can simply say +.B \egpicbox{graph} +instead of \ebox\egraph. +.PP +You must use a \*[tx] driver that supports the +.B tpic +specials, version\~2. +.PP +Lines beginning with +.B \e +are passed through transparently; a +.B % +is added to the end of the line to avoid unwanted spaces. +You can safely use this feature to change fonts or to +change the value of \fB\ebaselineskip\fP. +Anything else may well produce undesirable results; use at your own risk. +Lines beginning with a period are not given any special treatment. +.PP +The \*[tx] mode of \fIpic\/\fP(1) does \fInot\fP translate \fBtroff\fP +font and size changes included in text strings! +.PP +Here an example how to use \fBfigname\fP. +.KS +.DS +.CW +\&.PS +figname = foo; +\&... +\&.PE + +\&.PS +figname = bar; +\&... +\&.PE + +\ecenterline{\ebox\efoo \ehss \ebox\ebar} +.DE +.R +.KE +.LP +Use this feature sparsingly and only if really needed: +A different name means a new box register in \*[tx], and the maximum number +of box registers is only 256. +Also be careful not to use a predefined \*[tx] or \*[lx] macro name as +an argument to \fBfigname\fP since this inevitably causes an error. +. +. +.NH 1 +Obsolete Commands +.PP +GNU \fIgpic\/\fP(1) has a command +.DS +\fBplot\fR \fIexpr\fR [\fB"\fItext\fB"\fR] +.DE +This is a text object which is constructed by using +.I text +as a format string for sprintf +with an argument of +\fIexpr\fP. +If +.I text +is omitted a format string of \fB"%g"\fP is used. +Attributes can be specified in the same way as for a normal text +object. +Be very careful that you specify an appropriate format string; +\fBpic\fP does only very limited checking of the string. +This is deprecated in favour of +\fBsprintf\fP. +. +. +.NH 1 +Some Larger Examples +.PP +Here are a few larger examples, with complete source code. +One of our earlier examples is generated in an instructive way using a +for loop: +.KS +.DS +.ps -1 +.vs -1 +.CW +\&.PS +# Draw a demonstration up left arrow with grid box overlay +define gridarrow +{ + move right 0.1 + [ + {arrow up left $1;} + box wid 0.5 ht 0.5 dotted with .nw at last arrow .end; + for i = 2 to ($1 / 0.5) do + { + box wid 0.5 ht 0.5 dotted with .sw at last box .se; + } + move down from last arrow .center; + [ + sprintf("\efBarrow up left %g\efP", $1) + ] + ] + move right 0.1 from last [] .e; +} +gridarrow(0.5); +gridarrow(1); +gridarrow(1.5); +gridarrow(2); +undef gridarrow +\&.PE +.R +.DE +.ps +.vs +.KE +.KS +.PS +# Draw a demonstration up left arrow with grid box overlay +define gridarrow +{ + move right 0.5 + [ + {arrow up left $1;} + box wid 0.5 ht 0.5 dotted with .nw at last arrow .end; + for i = 2 to ($1 / 0.5) do { + box wid 0.5 ht 0.5 dotted with .sw at last box .se; + } + move down from last arrow .center; + [ + sprintf("\fBarrow up left %g\fP", $1) + ] + ] + move right 0.1 from last [] .e; +} +gridarrow(0.5); +gridarrow(1); +gridarrow(1.5); +gridarrow(2); +undef gridarrow +.PE +.CE "1: Diagonal arrows (dotted boxes show the implied 0.5-inch grid)" +.PP +Here's an example concocted to demonstrate layout of a large, +multiple-part pattern: +.KS +.DS +.ps -1 +.vs -1 +.CW +\&.PS +define filter {box ht 0.25 rad 0.125} +lineht = 0.25; +Top: [ + right; + box "\efBms\efR" "sources"; + move; + box "\efBHTML\efR" "sources"; + move; + box "\efBlinuxdoc-sgml\efP" "sources" wid 1.5; + move; + box "\efBTexinfo\efP" "sources"; + + line down from 1st box .s lineht; + A: line down; + line down from 2nd box .s; filter "\efBhtml2ms\efP"; + B: line down; + line down from 3rd box .s; filter "\efBformat\efP"; + C: line down; + line down from 4th box .s; filter "\efBtexi2roff\efP"; + D: line down; +] +move down 1 from last [] .s; +Anchor: box wid 1 ht 0.75 "\efBms\efR" "intermediate" "form"; +arrow from Top.A.end to Anchor.nw; +arrow from Top.B.end to 1/3 of the way between Anchor.nw and Anchor.ne; +arrow from Top.C.end to 2/3 of the way between Anchor.nw and Anchor.ne; +arrow from Top.D.end to Anchor.ne +{ + # PostScript column + move to Anchor .sw; + line down left then down ->; + filter "\efBpic\efP"; + arrow; + filter "\efBeqn\efP"; + arrow; + filter "\efBtbl\efP"; + arrow; + filter "\efBgroff\efP"; + arrow; + box "PostScript"; + + # HTML column + move to Anchor .se; + line down right then down ->; + A: filter dotted "\efBpic2img\efP"; + arrow; + B: filter dotted "\efBeqn2html\efP"; + arrow; + C: filter dotted "\efBtbl2html\efP"; + arrow; + filter "\efBms2html\efP"; + arrow; + box "HTML"; + + # Nonexistence caption + box dashed wid 1 at B + (2,0) "These tools" "don't yet exist"; + line chop 0 chop 0.1 dashed from last box .nw to A.e ->; + line chop 0 chop 0.1 dashed from last box .w to B.e ->; + line chop 0 chop 0.1 dashed from last box .sw to C.e ->; +} +\&.PE +.R +.DE +.ps +.vs +.KE +.KS +.PS +define filter {box ht 0.25 rad 0.125} +lineht = 0.25; +Top: [ + right; + box "\fBms\fR" "sources"; + move; + box "\fBHTML\fR" "sources"; + move; + box "\fBlinuxdoc-sgml\fP" "sources" wid 1.5; + move; + box "\fBTexinfo\fP" "sources"; + + line down from 1st box .s lineht; + A: line down; + line down from 2nd box .s; filter "\fBhtml2ms\fP"; + B: line down; + line down from 3rd box .s; filter "\fBformat\fP"; + C: line down; + line down from 4th box .s; filter "\fBtexi2roff\fP"; + D: line down; +] +move down 1 from last [] .s; +Anchor: box wid 1 ht 0.75 "\fBms\fR" "intermediate" "form"; +arrow from Top.A.end to Anchor.nw; +arrow from Top.B.end to 1/3 of the way between Anchor.nw and Anchor.ne; +arrow from Top.C.end to 2/3 of the way between Anchor.nw and Anchor.ne; +arrow from Top.D.end to Anchor.ne +{ + # PostScript column + move to Anchor .sw; + line down left then down ->; + filter "\fBpic\fP"; + arrow; + filter "\fBeqn\fP"; + arrow; + filter "\fBtbl\fP"; + arrow; + filter "\fBgroff\fP"; + arrow; + box "PostScript"; + + # HTML column + move to Anchor .se; + line down right then down ->; + A: filter dotted "\fBpic2img\fP"; + arrow; + B: filter dotted "\fBeqn2html\fP"; + arrow; + C: filter dotted "\fBtbl2html\fP"; + arrow; + filter "\fBms2html\fP"; + arrow; + box "HTML"; + + # Nonexistence caption + box dashed wid 1 at B + (2,0) "These tools" "don't yet exist"; + line chop 0 chop 0.1 dashed from last box .nw to A.e ->; + line chop 0 chop 0.1 dashed from last box .w to B.e ->; + line chop 0 chop 0.1 dashed from last box .sw to C.e ->; +} +.PE +.CE "2: Hypothetical production flow for dual-mode publishing" +.PP +.KS +.PS +# a three-dimensional block +# +# tblock(<width>, <height>, <text>) + +define tblock { [ + box ht $2 wid $1 \ + color "gold" outlined "black" \ + xslanted 0 yslanted 0 \ + $3; + box ht .1 wid $1 \ + color "yellow" outlined "black" \ + xslanted .1 yslanted 0 \ + with .sw at last box .nw; + box ht $2 wid .1 \ + color "goldenrod" outlined "black" \ + xslanted 0 yslanted .1 \ + with .nw at 2nd last box .ne; +] } + +tblock(1, .5, "Master" "1"); +move -.1 +tblock(.5, 1, "Slave"); +.PE +.CE "3: Three-dimensional Boxes" +.PP +Here the source code for figure \n[H1]-3: +.KS +.DS +.CW +\&.PS +# a three-dimensional block +# +# tblock(<width>, <height>, <text>) + +define tblock { [ + box ht $2 wid $1 \e + color "gold" outlined "black" \e + xslanted 0 yslanted 0 \e + $3; + box ht .1 wid $1 \e + color "yellow" outlined "black" \e + xslanted .1 yslanted 0 \e + with .sw at last box .nw; + box ht $2 wid .1 \e + color "goldenrod" outlined "black" \e + xslanted 0 yslanted .1 \e + with .nw at 2nd last box .ne; +] } + +tblock(1, .5, "Master" "1"); +move -.1 +tblock(.5, 1, "Slave"); +\&.PE +.DE +.ft R +.KE +. +. +. +.NH 1 +PIC Reference +.PP +This is an annotated grammar of \fBpic\fP. +. +.NH 2 +Lexical Items +.PP +In general, \fBpic\fP is a free-format, token-oriented language that +ignores whitespace outside strings. +But certain lines and constructs are specially interpreted at the +lexical level: +.PP +A comment begins with \fB#\fP and continues to \fB\en\fP (comments may +also follow text in a line). +A line beginning with a period or backslash may be interpreted as text +to be passed through to the post-processor, depending on command-line +options. +An end-of-line backslash is interpreted as a request to continue the +line; the backslash and following newline are ignored. +.PP +.RS +Here are the grammar terminals: +.IP \s[-1]INT\s[0] +A positive integer. +.IP \s[-1]NUMBER\s[0] +A floating point numeric constant. +May contain a decimal point or be expressed in scientific notation in +the style of \fIprintf\/\fP(3)'s %e escape. +A trailing `i' or `I' (indicating the unit `inch') is ignored. +.IP \s[-1]TEXT\s[0] +A string enclosed in double quotes. +A double quote within \s[-1]TEXT\s[0] must be preceded by a backslash. +Instead of \s[-1]TEXT\s[0] you can use +.DS +.CW +sprintf ( TEXT [, <expr> ...] ) +.R +.DE +.IP +except after the `until' and `last' keywords, and after all ordinal +keywords (`th' and friends). +.IP \s[-1]VARIABLE\s[0] +A string starting with a character from the set [a-z], optionally +followed by one or more characters of the set [a-zA-Z0-9_]. +(Values of variables are preserved across pictures.) +.IP \s[-1]LABEL\s[0] +A string starting with a character from the set [A-Z], optionally +followed by one or more characters of the set [a-zA-Z0-9_]. +.IP \s[-1]COMMAND-LINE\s[0] +A line starting with a command character (`.' in groff mode, `\e' in +\*[tx] mode). +.IP \s[-1]BALANCED-TEXT\s[0] +A string either enclosed by `{' and `}' or with \fIX\fP and \fIX\fP, +where \fIX\fP doesn't occur in the string. +.IP \s[-1]BALANCED-BODY\s[0] +Delimiters as in \s[-1]BALANCED-TEXT\s[0]; the body is interpreted as +`\fB\[la]command\[ra].\|.\|.\fP'. +.IP \s[-1]FILENAME\s[0] +The name of a file. +This has the same semantics as \s[-1]TEXT\s[0]. +.IP \s[-1]MACRONAME\s[0] +Either \s[-1]VARIABLE\s[0] or \s[-1]LABEL\s[0]. +.RE +. +.NH 2 +Semi-Formal Grammar +.PP +Tokens not enclosed in \[la]\|\[ra] are literals, except: +.IP 1. +\fB\en\fP is a newline. +.IP 2. +Three dots is a suffix meaning `replace with 0 or more repetitions +of the preceding element(s). +.IP 3. +An enclosure in square brackets has its usual meaning of `this clause is +optional'. +.IP 4. +Square-bracket-enclosed portions within tokens are optional. +Thus, `h\^[eigh]\^t' matches either `height' or `ht'. +.LP +If one of these special tokens has to be referred to literally, it is +surrounded with single quotes. +.PP +The top-level \fBpic\fP object is a picture. +.DS +.CW +<picture> ::= + .PS [NUMBER [NUMBER]]\en + <statement> ... + .PE \en +.R +.DE +.PP +The arguments, if present, represent the width and height of the picture, +causing \fBpic\fR to attempt to scale it to the given dimensions in +inches. +In no case, however, the X and Y\~dimensions of the picture exceed the +values of the style variables \fBmaxpswid\fP and \fBmaxpsheight\fP +(which default to the normal 8.5\^i by 11\^i page size). +.PP +If the ending `.PE' is replaced by `.PF', the page vertical position is +restored to its value at the time `.PS' was encountered. +Another alternate form of invocation is `.PS\~<\s[-1]FILENAME\s[0]', +which replaces the `.PS' line with a file to be interpreted by \fBpic\fR +(but this feature is deprecated). +.PP +The `.PS', `.PE', and `.PF' macros to perform centering and scaling are +normally supplied by the post-processor. +.PP +In the following, either `|' or a new line starts an alternative. +.DS +.CW +<statement> ::= + <command> ; + <command> \en +.R +.DE +.DS +.CW +<command> ::= + <primitive> [<attribute>] + LABEL : [;] <command> + LABEL : [;] <command> [<position>] + { <command> ... } + VARIABLE [:] = <any-expr> + figname = MACRONAME + up | down | left | right + COMMAND-LINE + command <print-arg> ... + print <print-arg> ... + sh BALANCED-TEXT + copy FILENAME + copy [FILENAME] thru MACRONAME [until TEXT] + copy [FILENAME] thru BALANCED-BODY [until TEXT] + for VARIABLE = <expr> to <expr> [by [*] <expr>] do BALANCED-BODY + if <any-expr> then BALANCED-BODY [else BALANCED-BODY] + reset [VARIABLE [[,] VARIABLE ...]] +.R +.DE +.DS +.CW +<print-arg> ::= + TEXT + <expr> + <position> +.R +.DE +.PP +The current position and direction are saved on entry to a + `{\~.\|.\|.\~}' construction and restored on exit from it. +.PP +Note that in `if' constructions, newlines can only occur in +\s[-1]BALANCED-BODY\s[0]. +This means that +.DS +.CW +if +{ ... } +else +{ ... } +.R +.DE +.PP +fails. +You have to use the braces on the same line as the keywords: +.DS +.CW +if { +\&... +} else { +\&... +} +.R +.DE +.PP +This restriction doesn't hold for the body after the `do' in a `for' +construction. +.PP +At the beginning of each picture, `figname' is reset to the vbox name +`graph'; this command has only a meaning in \*[tx] mode. +While the grammar rules allow digits and the underscore in the value of +`figname', \*[tx] normally accepts uppercase and lowercase letters only +as box names (you have to use `\ecsname' if you really need to +circumvent this limitation). +.DS +.CW +<any-expr> ::= + <expr> + <text-expr> + <any-expr> <logical-op> <any-expr> + ! <any-expr> +.R +.DE +.DS +.CW +<logical-op> ::= + == | != | && | '||' +.R +.DE +.DS +.CW +<text-expr> ::= + TEXT == TEXT + TEXT != TEXT +.R +.DE +.PP +Logical operators are handled specially by \fBpic\fP since they can +deal with text strings also. +\fBpic\fP uses \%\fIstrcmp\/\fP(3) to test for equality of strings; an +empty string is considered as `false' for `&&' and `|\||'. +.DS +.CW +<primitive> ::= + box \fR# closed object \[em] rectangle\fP + circle \fR# closed object \[em] circle\fP + ellipse \fR# closed object \[em] ellipse\fP + arc \fR# open object \[em] quarter-circle\fP + line \fR# open object \[em] line\fP + arrow \fR# open object \[em] line with arrowhead\fP + spline \fR# open object \[em] spline curve\fP + move + TEXT TEXT ... \fR# text within invisible box\fP + plot <expr> TEXT \fR# formatted text\fP + '[' <command> ... ']' +.R +.DE +.PP +Drawn objects within `[\~.\|.\|.\~]' are treated as a single composite +object with a rectangular shape (that of the bounding box of all the +elements). +Variable and label assignments within a block are local to the block. +Current direction of motion is restored to the value at start of block +upon exit. +Position is \fInot\fR restored (unlike `{\~}'); +instead, the current position becomes the exit position for the current +direction on the block's bounding box. +.DS +.CW +<attribute> ::= + h[eigh]t <expr> \fR# set height of closed figure\fP + wid[th] <expr> \fR# set width of closed figure\fP + rad[ius] <expr> \fR# set radius of circle/arc\fP + diam[eter] <expr> \fR# set diameter of circle/arc\fP + up [<expr>] \fR# move up\fP + down [<expr>] \fR# move down\fP + left [<expr>] \fR# move left\fP + right [<expr>] \fR# move right\fP + from <position> \fR# set from position of open figure\fP + to <position> \fR# set to position of open figure\fP + at <position> \fR# set center of open figure\fP + with <path> \fR# fix corner/named point at specified location\fP + with <position> \fR# fix position of object at specified location\fP + by <expr-pair> \fR# set object's attachment point\fP + then \fR# sequential segment composition\fP + dotted [<expr>] \fR# set dotted line style\fP + dashed [<expr>] \fR# set dashed line style\fP + thick[ness] <expr> \fR# set thickness of lines\fP + chop [<expr>] \fR# chop end(s) of segment\fP + '->' | '<-' | '<->' \fR# decorate with arrows\fP + invis[ible] \fR# make primitive invisible\fP + solid \fR# set solid line style\fP + fill[ed] [<expr>] \fR# fill closed figure with optional density\fP + xscaled <expr> \fR# slant box into x direction\fP + yscaled <expr> \fR# slant box into y direction\fP + colo[u]r[ed] TEXT \fR# set fill and outline color for figure\fP + outline[d] TEXT \fR# set outline color for figure\fP + shaded TEXT \fR# set fill color for figure\fP + same \fR# copy size of previous object\fP + cw | ccw \fR# set orientation of curves\fP + ljust | rjust \fR# adjust text horizontally\fP + above | below \fR# adjust text vertically\fP + aligned \fR# align parallel to object\fP + TEXT TEXT ... \fR# text within object\fP + <expr> \fR# motion in the current direction\fR +.R +.DE +.PP +Missing attributes are supplied from defaults; inappropriate ones are +silently ignored. +For lines, splines, and arcs, height and width refer to arrowhead size. +.PP +The `at' primitive sets the center of the current object. +The `with' attribute fixes the specified feature of the given object to +a specified location. +(Note that `with' is incorrectly described in the Kernighan paper.) +.PP +The `by' primitive is not documented in the tutorial portion of +the Kernighan paper, and should probably be considered unreliable. +.PP +The primitive `arrow' is a synonym for `line\~->'. +.PP +Text is normally an attribute of some object, in which case successive +strings are vertically stacked and centered on the object's center by +default. +Standalone text is treated as though placed in an invisible box. +.PP +A text item consists of a string or sprintf-expression, optionally +followed by positioning information. +Text (or strings specified with `sprintf') may contain font changes, +size changes, and local motions, provided those changes are undone +before the end of the current item. +Text may also contain \e-escapes denoting special characters. +The base font and specific set of escapes supported is implementation +dependent, but supported escapes always include the following: +.IP "\efR, \ef1" \w'\efR,\~\ef3'u+2n +Set Roman style (the default) +.IP "\efI, \ef2" +Set Italic style +.IP "\efB, \ef3" +Set Bold style +.IP \efP +Revert to previous style; only works one level deep, does not stack. +.PP +Color names are dependent on the \gBpic\fR implementation, but in +all modern versions color names recognized by the X\~window system are +supported. +.PP +A position is an (x,y) coordinate pair. +There are lots of different ways to specify positions: +.DS +.CW +<position> ::= + <position-not-place> + <place> + ( <position> ) +.R +.DE +.DS +.CW +<position-not-place> ::= + <expr-pair> + <position> + <expr-pair> + <position> - <expr-pair> + ( <position> , <position> ) + <expr> [of the way] between <position> and <position> + <expr> '<' <position> , <position> '>' +.R +.DE +.DS +.CW +<expr-pair> ::= + <expr> , <expr> + ( expr-pair ) +.R +.DE +.DS +.CW +<place> ::= + <label> + <label> <corner> + <corner> [of] <label> + Here +.R +.DE +.DS +.CW +<label> ::= + LABEL [. LABEL ...] + <nth-primitive> +.R +.DE +.DS +.CW +<corner> ::= + .n | .e | .w | .s + .ne | .se | .nw | .sw + .c[enter] | .start | .end + .t[op] | .b[ot[tom]] | .l[eft] | .r[ight] + left | right | <top-of> | <bottom-of> + <north-of> | <south-of> | <east-of> | <west-of> + <center-of> | <start-of> | <end-of> + upper left | lower left | upper right | lower right +.R +.DE +.DS +.CW +<\,\f(CIxxx\/\fP-of> ::= + \f(CIxxx\fP \fR# followed by `of'\fP +.R +.DE +.DS +.CW +<nth-primitive> ::= + <ordinal> <object-type> + [<ordinal>] last <object-type> +.R +.DE +.DS +.CW +<ordinal> ::= + INT th + INT st | INT nd | INT rd + ` <any-expr> 'th +.R +.DE +.DS +.CW +<object-type> ::= + box + circle + ellipse + arc + line + arrow + spline + '[]' + TEXT +.R +.DE +.PP +As Kernighan notes, \[lq]since barbarisms like \fB1th\fP and \fB3th\fP are +barbaric, synonyms like \fB1st\fP and \fB3rd\fP are accepted as well.\[rq] +Objects of a given type are numbered from 1 upwards in order of +declaration; the \fBlast\fP modifier counts backwards. +.PP +The \[lq]'th\[rq] form (which allows you to select a previous object with +an expression, as opposed to a numeric literal) is not documented in DWB's +\fIpic\/\fR(1). +.PP +The \[la]\,\fIxxx\/\fP-of\|\[ra] rule is special: The lexical parser checks whether +\fIxxx\fP is followed by the token `of' without eliminating it so that +the grammar parser can still see `of'. +Valid examples of specifying a place with corner and label are thus +.DS +.CW +A .n +\&.n of A +\&.n A +north of A +.R +.DE +.LP +while +.DS +.CW +north A +A north +.R +.DE +both cause a syntax error. +(DWB \fBpic\fP also allows the weird form `A\~north\~of'.) +.PP +Here the special rules for the `with' keyword using a path: +.DS +.CW +<path> ::= + <relative-path> + ( <relative-path> , <relative-path> ) +.R +.DE +.DS +.CW +<relative-path> ::= + <corner> + . LABEL [. LABEL ...] [<corner>] +.R +.DE +.PP +The following style variables control output: +.TS H +center tab(@), linesize(2); +lb | lb | lb +l | n | l. +.sp 2p +Style Variable@Default@What It Does +.sp 2p +_ +.sp 2p +.TH +boxht@0.5@Default height of a box +boxwid@0.75@Default width of a box +lineht@0.5@Default length of vertical line +linewid@0.75@Default length of horizontal line +arcrad @0.25@Default radius of an arc +circlerad@0.25@Default radius of a circle +ellipseht@0.5@Default height of an ellipse +ellipsewid@0.75@Default width of an ellipse +moveht@0.5@Default length of vertical move +movewid@0.75@Default length of horizontal move +textht@0@Default height of box enclosing a text object +textwid@0@Default width of box enclosing a text object +arrowht@0.1@Length of arrowhead along shaft +arrowwid@0.05@Width of rear of arrowhead +arrowhead@1@Enable/disable arrowhead filling +dashwid@0.05@Interval for dashed lines +maxpswid@8.5@Maximum width of picture +maxpsht@11@Maximum height of picture +scale@1@Unit scale factor +fillval@0.5@Default fill value +.sp 5p +_ +.TE +Any of these can be set by assignment, or reset using the \fBreset\fP +statement. +Style variables assigned within `[\~]' blocks are restored to their +beginning-of-block value on exit; top-level assignments persist across +pictures. +Dimensions are divided by \fBscale\fR on output. +.PP +All \fBpic\fP expressions are evaluated in floating point; units +are always inches (a trailing `i' or `I' is ignored). +Expressions have the following simple grammar, with semantics very +similar to C\~expressions: +.DS +.CW +<expr> ::= + VARIABLE + NUMBER + <place> <place-attribute> + <expr> <op> <expr> + - <expr> + ( <any-expr> ) + ! <expr> + <func1> ( <any-expr> ) + <func2> ( <any-expr> , <any-expr> ) + rand ( ) +.R +.DE +.DS +.CW +<place-attribute> + .x | .y | .h[eigh]t | .wid[th] | .rad +.R +.DE +.DS +.CW +<op> ::= + + | - | * | / | % | ^ | '<' | '>' | '<=' | '>=' +.R +.DE +.DS +.CW +<func1> ::= + sin | cos | log | exp | sqrt | int | rand | srand +.R +.DE +.DS +.CW +<func2> ::= + atan2 | max | min +.R +.DE +.LP +Both \fBexp\fP and \fBlog\fP are base 10; \fBint\fP does integer +truncation; and \fBrand()\fP returns a random number in [0-1). +.PP +There are \fBdefine\fP and \fBundef\fR statements which are not part +of the grammar (they behave as pre-processor macros to the language). +These may be used to define pseudo-functions. +.DS +.CW +\fBdefine\fP \fIname\fP \fB{\fP \fIreplacement-text\fP \fB}\fP +.R +.DE +.LP +This defines \fIname\fR as a macro to be replaced by the replacement +text (not including the braces). +The macro may be called as +.DS +.CW +\fIname\/\fB(\,\fIarg1, arg2, .\|.\|., argn\fB\/)\fR +.R +.DE +.LP +The arguments (if any) are substituted for tokens $1, $2 \&.\|.\|.\& $n +appearing in the replacement text. +To undefine a macro, say \fBundef\fP \fIname\fR, specifying the name to +be undefined. +.\"%%POSTLUDE%% +. +. +.NH 1 +History and Acknowledgements +.PP +Original \fBpic\fP was written to go with Joseph Ossanna's original +\fItroff\/\fP(1) by Brian Kernighan, and later re-written by Kernighan +with substantial enhancements (apparently as part of the evolution of +\fItroff\/\fP(1) into \fIditroff\/\fP(1) to generate +device-independent output). +.PP +The language had been inspired by some earlier graphics languages +including \fBideal\fP and \fBgrap\fP. +Kernighan credits Chris van Wyk (the designer of \fBideal\fP) with many +of the ideas that went into +\fBpic\fP. +.PP +.\" the original definitions of EQ and EN cause insertion of vertical +.\" space which is not appropriate here +.de EQ +.. +.de EN +.. +.EQ +delim $$ +.EN +The \fBpic\fP language was originally described by Brian Kernighan in +Bell Labs Computing Science Technical Report #116 (you can obtain a +PostScript copy of the revised version, [1], by sending a mail message to +\fInetlib@research.att.com\fP with a body of `send 116 from +research/cstr'). +There have been two revisions, in 1984 and 1991. +.PP +The document you are reading effectively subsumes Kernighan's +description; it was written to fill in lacun\[ae] in the exposition and +integrate in descriptions of the GNU \fIgpic\/\fP(1) and +\fIpic2plot\/\fP(1) features. +.PP +The GNU \fBgpic\fR implementation was written by James Clark +\[la]\,\fIjjc@jclark.com\/\fP\[ra]. +.PP +The GNU \fBpic2plot\fR implementation is based on James Clark's parser +code and maintained by Robert Maier, principal author of \fBplotutils\fP. +. +. +.NH 1 +Bibliography +.IP 1. +Kernighan, B. W. +\fBPIC \[em] A Graphics Language for Typesetting +(Revised User Manual)\fP. +Bell Labs Computing Science Technical Report #116, December 1991. +.IP 2. +Van Wyk, C. J. +\fBA high-level language for specifying pictures\fP. +\fIACM Transactions On Graphics\fP 1,2 (1982) 163-182. +. +.\" Local Variables: +.\" mode: nroff +.\" End: +.\" vim: filetype=groff: |