pic is rarely your first choice as a drawing tool. With pic you can draw lines and a limited variety of shapesno color, no shadingbut you can create a complex and detailed picture, if you're willing to work at it. pic was developed before
everyone had personal computers with sophisticated, mouse-based drawing packages. Today, troff users with graphics terminals can use mouse-based programs such as xcip. These programs provide many of the capabilitiesexcept for colorof the
sophisticated packages, and they don't require a knowledge of pic. xcip produces pic code, whichand here's the pointyou can edit if you know pic.
pic is no substitute for a sophisticated drawing tool. It doesn't have color. It provides shading only inside boxes, circles, and ellipses. It doesn't even let you draw a randomly wiggly line.
troff recognizes pic code by its opening and closing macros: .PS and .PE. ms includes a .PF macro for picture flyback. This macro restores you to your last position on the page (vertically and horizontally) before the picturewhere you were before
you invoked pic. This feature is rarely used; some pic users surround their pic code with display macros and specify no-fill mode. For example,
.box ht 1 wid 1.25
This might look like overkill, but mm likes it.
The .PS macro also can be used to do the following:
.PS < filename
Sources in a pic file; imports an external file called filename and allows it to be processed as if filename were part of your text file.
.PS wid ht
Enables you to specify the width or the heightor bothof the final picture
CAUTION: If you have a space after the .PS and no measurements, your figure will be enlarged proportionally so that its width is the current width (line length) of your pages.
To insert comments in pic code, begin a line with #.
Whatever you do, don't include any spacing requests.sp, .ls, .vs, .SP, and .Pinside your pic code. pic does its own spacing, and it gets really annoyed if you interfere. Use the move command instead.
Each line of text is enclosed in its own set of quotation marks.
pic attempts to center your text, both vertically and horizontally, which isn't helpful if you want to label a line. For example,
line right 1i "line"
comes out looking like
Fortunately, pic recognizes the words above and below, so you can position your text so that it is more readable. If you have two lines of text, pic puts one above the line and one below it. For example,
line right 1i "over" "under"
pic doesn't object if you want to specify the font and point size for your text, so long as you keep the specifications inside the quotation marks. For example,
line right 1i "\f(HB\s12over" "under\fP\s0"
NOTE: To right or left justify text, use rjust or ljust.
The preceding examples are troff escape sequences and are discussed further in Chapter 21, "Basic Formatting with troff/nroff."
pic is especially suited for charts and flow diagrams. Consider the following code:
box; line; box
move right li
box; arrow; box
NOTE: When you write pic code, you specify one command per line, or you can separate commands with semicolons. Long lines require the continuation symbol (\).
As you can see from the code and the figure, arrow is a synonym for line.
The following commands are useful as well:
Draws an arrowhead at the end of the arrow. It doesn't necess-arily point to the right.
Draws an arrowhead at the beginning of the arrow. It doesn't necessarily point to the left.
Draws arrowheads on both ends of the arrow.
TIP: To draw a line with an arrow at both ends, use line <-> or arrow <->. This might seem obvious, but for seven years I drew two-headed arrows using the arrow command twicedrawing a
right-pointing arrow over a left-pointing arrowbecause nobody told me about <->.
Suppose that you want Box 2 directly under Box 1. Consider the following code:
box "Box 1"
box "Box 2"
The problem with this code is that pic moves half an inch from wherever it left off drawing the first box, which in this case is the middle of the box top. To place Box 2 correctly, you have to move down another one-half inch and to the left:
box "Box 1"
move left .375i
move down .75i
box "Box 2"
This is a nuisance, to say the least, because in a complicated drawing you quickly lose track of where pic begins and ends each element of the drawing. You can use reference points with pic so that you know where each element of your drawing will be
placed. They are discussed in the next section.
The position notation words and the compass points enable you to specify positions like these:
line from upper right of 2nd last box to upper left of last box
arrow from 1st circle.e to 2nd circle.w
box at end of last line
move left 1i from start of last box
line from Box.c to Box.s
move down 1i from bottom of 2nd last ellipse
NOTE: You can use terms like upper left and lower right, but not top left and lower bottom.
Now you have several ways of specifying the two boxes shown in Figure 25.1. You could write
box "Box 1"
move to last box.s down .5
box "Box 2"
or you could write
box "Box 1"
move to bottom of last box down .5
box "Box 2"
If you want to avoid the wordiness of bottom of last box, you can label your construct
B1: box "Box 1"
Labels must begin with a capital letter.
Using labels enables you to specify the two boxes as follows:
B1:box "Box 1"
B2:box with .c down 1i from B1.c "Box 2"
TIP: If you reference objects by their centers, you don't have to worry about where pic starts a new object or in which direction the new object is drawn.
These notationsleft, right, .ne, .sw, and so onassume that you can tell left from right and east from west. If you are directionally challenged like me, you should allow extra debugging time for your pics. I've tried sticking scraps of paper
labelled left/west and right/east on the sides of my monitor. It helps a little.
pic comes to your rescue with a solution. It understands Cartesian coordinates, as shown in Figure 25.3.
Again, the unit is inches. The important thing to remember is that your first object starts at 0,0. In other words, the coordinates are relative. There is no specific location on a page or in a drawing that is always 0,0. It depends on where you start.
Cartesian coordinates enable you to specify the two boxes shown in Figure 25.1 as
box at 0,0 "Box 1"
box at 0,-1 "Box 2"
You'll probably find this easier.
pic also has an invis command. At first glance, it doesn't seem very useful. How often do you expect to draw a page full of invisible boxes? The real advantage of invis is in placing text. Consider Figure 25.4.
pic also recognizes trigonometric and other mathematical functions:
the arctangent of e1, e2
cosine of e (e must be in radians)
integer part (by truncation)
logarithm base 10 of e
maximum of e1 and e2
minimum of e1 and e2
random number between 1 and n
sine of e (e must be in radians)
square root of e
These functions must be followed by an expression in parentheses. In the case of atan2, max, and min, two expressions must follow. rand is followed by empty parentheses and produces a random number between 0 and 1.
Lines and shapes don't have to be solid. You can draw dotted and dashed objects. Consider the following code.
move to B1.n up .05 right .05
B2: box dashed
move to B2.n up .05 right .05
B3: box dotted
pic variables include several that specify the default size of pic objects. Table 25.1 lists these variables and their default values.
Table 25.1. Default values of pic variables.
arrowwid and arriowht refer to the arrowhead. The arrowhead variable specifies the fill style of the arrowhead.
It's easy to change the value of a variable. For example,
boxht = .75; boxwid = .5
Remember: The default unit for pic is inches.
There are other ways of controlling the size of a picture. You can specify a height or a widthor bothon the .PS line. Usually it's better to specify only the width. If you specify both dimensions, your picture may be distorted.
NOTE: For some reason, you must specify the width first. For example, .PS 2 4 produces a picture 2 inches wide and 4 inches long. This is the opposite of the order in which you specify the dimensions of a
box or ellipse. The width and height you specify refer to the whole picture.
You can also set the variable scale. By default, scale is set at 100 or 1, depending on your version of pic. (You can test this by scaling a drawing to 1.5. If you get an error message or a garbled result, use 150.) All the dimensions in a pic drawing
are divided by the scaling factor. Therefore, if the scale is normally 1 and you set it to 4, your 1-inch lines will be a quarter-inch long. For example,
scale = 2
box ht 2i wid 2i
This code produces a box scaled down to half the size of its specifications, that is, a 1- inch square.
CAUTION: Text is not scaled. If your text needs resizing, you must do it with \s, and it's usually a matter of trial and error to find out what will fit in your scaled figure.
You can define any sequence of objects or moves as a block, which you can manipulate almost as if it were a simple box. You need to name the block. The name must begin with an uppercase letter. Although pic places no specific restrictions on the length
of the name, shorter is better.
Object blocks are useful when you are placing text.
You can also position an object block easily, as in
C1: circle rad .125
arc rad .04
arc rad .08
arc rad .12
arc rad .16
arc rad .20
arc rad .24
arc rad .28
arc rad .32
arc rad .36
arc rad .40
arc rad .44
arc rad .48
] with .s at C1.n
If you want to reuse an object, you can put it in a file by itself and use the copy function:
You can also define a pic macro. Don't confuse pic macros with troff macros. In the broadest sense, a macro is a short way of referring to a complex process. In other words, a pic macro is just a collection of pic commands that have been given a name.
Unlike object blocks, which merely give you a convenient way of referring to positions in and around the object, macros can be used to draw objects. The first three lines of the following code sequence enable you to draw the defined object by invoking
its name, as shown in the last line.
To create a macro, use the word define followed by a name for your macro and a delimeter. Next come all your pic instructions and finally, another delimeter. In the first example, I used % for delimeters. In the second example, I used curly braces.
There is no default. The choice is yours.
Macros can have up to nine arguments, specified $1 through $9. For example, you can define a square and supply the dimensions as arguments when you invoke the macro, as shown in the first three lines of the following code. The last line produces the 1/2
inches square shown in Figure 25.6.
When you're dealing with pic, you aren't troubleshootingyou're debugging. It's much easier to do this as you code. Draw the first element of your picture. Before you print it, send the file through pic to see whether any error messages are
generated. If your file contains only pic, you can do this:
If your file contains text, just use your normal troff command line. However, instead of sending the file to a printer, redirect your output to /dev/null. See Chapter 28, "Tools for Writers," for more information on directing output to
pic tries to help you pinpoint your errors with messages similar to the following:
pic: syntax error near line 26
>>> linr <<< left 1i
Occasionally, pic tells you that it has reduced the size of your picture. This is almost always because you've made a mistake. Most often, you've left out a decimal point, and pic is trying to fit a line 1625 inches longyou meant 1.625
incheson an 8.5-inch page. When this happens, your picture naturally is mangled out of all recognition.
Usually, your debugging involves the placement of objects and the placement or size of text.
pic is a troff preprocessor for drawing lines, arrows, boxes, circles, ellipses, arcs, and splines. Output tends to vary from system to system, so be prepared to spend some time debugging. pic is well worth the trouble if you frequently include simple
graphics in text files. It is especially useful for organization charts, flow charts, state diagrams, and the like.