The Plotutils Package - pic2plot Introduction

Go to the first, previous, next, last section, table of contents.

## 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 Raymond's tutorial on the GNU implementation, and some sample pic macros contributed by 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 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 PNM format, pseudo-GIF format, or Fig format (which is editable with the `xfig` drawing editor) may be obtained similarly. You would use the options ``-T pnm'`, ``-T gif'`, 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 by default 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 section Text string format and escape sequences.

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.

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 tip 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 measured 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 PNM, pseudo-GIF, 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.

Go to the first, previous, next, last section, table of contents.