4.1 What pic2plot is used for

The pic2plot program takes one or more files in the pic language, and either displays the figures that they contain on an X Window System display, or produces an output file containing the figures. Many graphics file formats are supported.

The pic language is a `little language' that was developed at Bell Laboratories for creating box-and-arrow diagrams of the kind frequently found in technical papers and textbooks. A directory containing documentation on the pic language is distributed along with the plotting utilities. On most systems it is installed as /usr/share/pic2plot or /usr/local/share/pic2plot. The directory includes Brian Kernighan's original technical report on the language, Eric S. Raymond's tutorial on the GNU implementation, and some sample pic macros contributed by the late W. Richard Stevens.

The pic language was originally designed to work with the troff document formatter. In that context it is read by a translator called pic, or its GNU counterpart gpic. Since extensive documentation on pic and gpic is available, this section simply gives an example of an input file, and mentions some extra features supported by pic2plot.

A pic file contains one or more figures, each of the box-and-arrow type. Each figure is begun by a line reading .PS, and ended by a line reading .PE. Lines that are not contained in a .PS....PE pair are ignored. Each figure is built from geometrical objects, such as rectangular boxes, circles, ellipses, quarter circles (“arcs”), polygonal lines, and splines. Arcs, polygonal lines, and spline may be equipped with arrowheads. Any object may be labeled with one or more lines of text.

Objects are usually positioned not by specifying their positions in absolute coordinates, but rather by specifying their positions relative to other, previously drawn objects. The following figure is an example.

     .PS
     box "START"; arrow; circle dashed filled; arrow
     circle diam 2 thickness 3 "This is a" "big, thick" "circle" dashed; up
     arrow from top of last circle; ellipse "loopback" dashed
     arrow dotted from left of last ellipse to top of last box
     arc cw radius 1/2 from top of last ellipse; arrow
     box "END"
     .PE

If you put this example in a file and run ‘pic2plot -T X’ on the file, a window containing the figure will be popped up on your X display. Similarly, if you run ‘pic2plot -T ps’ on the file, a Postscript file containing the figure will be written to standard output. The Postscript file may be edited with the idraw drawing editor. Other graphics formats such as PNG format, PNM format, pseudo-GIF format, SVG format, WebCGM format, or Fig format (which is editable with the xfig drawing editor) may be obtained similarly. You would use the options ‘-T png’, ‘-T pnm’, ‘-T gif’, samp -T svg, ‘-T cgm’, and ‘-T fig’, respectively.

The above example illustrates some of the features of the pic language. By default, successive objects are drawn so as to touch each other. The drawing proceeds in a certain direction, which at startup is left-to-right. The ‘up’ command changes this direction to bottom-to-top, so that the next object (the arrow extending from the top of the big circle) will point upward rather than to the right.

Objects have sizes and other attributes, which may be set globally, or specified on a per-object basis. For example, the diameter of a circle may be specified, or the radius of an arc. An arc may be oriented clockwise rather than counterclockwise by specifying the ‘cw’ attribute. The line style of most objects may be altered by specifying the ‘dashed’ or ‘dotted’ attribute. Also, any object may be labeled, by specifying one or more text strings as attributes. A text string may contain escape sequences that shift the font, append subscripts or superscripts, or include non-ASCII characters and mathematical symbols. See Text String Format.

Most sizes and positions are expressed in terms of `virtual inches'. The use of virtual inches is peculiar to pic2plot. The graphics display used by pic2plot, i.e., its drawing region, is defined to be a square, 8 virtual inches wide and 8 virtual inches high. If the page size for the output file is the "letter" size, which is the default for Postscript output, virtual inches will the same as real inches. But a different page size may be specified; for example, by using the ‘--page-size a4’ option. If so, a virtual inch will simply equal one-eighth of the width of the graphics display. On A4 paper, the graphics display is a square of size 19.81cm.

By default, each figure is centered in the graphics display. You may turn off centering, so that you can use absolute coordinates, by using the ‘-n’ option. For example, a figure consisting only of the object ‘arrow from (8,8) to (4,4)’ will be positioned in the absence of centering so that the head of the arrow is at the center of the display. Its tail will be at the upper right corner.

The thickness of lines is not specified in terms of virtual inches. For compatibility with gpic, it is specified in terms of virtual points. The example above, which specifies the ‘thickness’ attribute of one of the objects, illustrates this. There are 72 virtual points per virtual inch.

If there is more than one figure to be displayed, they will appear in different X windows, or on successive pages of the output file. Some output formats (such as PNG, PNM, pseudo-GIF, SVG, Illustrator, and Fig) support only a single page of graphics. If any of those output formats is chosen, only the first figure will appear in the output file. Currently, pic2plot cannot produce animated pseudo-GIFs.

The preceding survey does not do justice to the pic language, which is actually a full-featured programming language, with support for variables, looping constructs, etc. Its advanced features make the drawing of large, repetitive diagrams quite easy.