pic2plot Programpic2plot 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.
pic2plot command-line options
The pic2plot program translates files in the pic language, which
is used for creating box-and-arrow diagrams of the kind frequently found
in technical papers and textbooks, to other graphics formats. The
output format or display type is specified with the `-T' option.
The possible output formats are the same ten formats that are supported
by the GNU graph and plot programs.
Input file names may be specified anywhere on the command line. That is, the relative order of file names and command-line options does not matter. If no file names are specified, or the file name `-' is specified, the standard input is read. The output file is written to standard output, unless the `-T X' option is specified. In that case the output is displayed in one or more windows on an X Window System display, and there is no output file.
The full set of command-line options is listed below. There are three sorts of option:
pic2plot, i.e., relevant only if no
display type or output format is specified with the `-T' option.
Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.
The following are general options.
idraw-editable Postscript, the format used by the xfig
drawing editor, the Hewlett--Packard PCL 5 printer language, the
Hewlett--Packard Graphics Language (by default, HP-GL/2), Tektronix
format, and device-independent GNU graphics metafile format.
libplot.
This option may produce slightly better-looking dashed and dotted lines.
However, it will come at a price: if an editable output file is produced
(i.e., an output file in Illustrator, Postscript or Fig format),
it will be difficulty to modify its dashed and dotted lines with a
drawing editor.
pic2plot -T pnm,
pic2plot -T gif, pic2plot -T pcl, pic2plot -T hpgl,
pic2plot -T tek, and raw pic2plot, for all of which
"HersheySerif" is the default.) Set the font used for text to
font_name. Font names are case-insensitive. If the specified
font is not available, the default font will be used. Which fonts are
available depends on which `-T' option is used. For a list of all
fonts, see section Available text fonts. The plotfont utility will produce a
character map of any available font. See section The plotfont Utility.
libplot graphics library should be used. This is
usually 1/850 times the size of the display, although if `-T X',
`-T pnm', or -T gif is specified, it is zero. By
convention, a zero-thickness line is the thinnest line that can be
drawn. This is the case in all output formats. Note, however, that the
drawing editors idraw and xfig treat zero-thickness lines
as invisible.
pic2plot -T hpgl does not support drawing lines with other than a
default thickness if the environment variable HPGL_VERSION is set
to a value less than "2" (the default).
pic2plot -T X,
pic2plot -T pnm, and pic2plot -T gif. An unrecognized
name sets the color to the default. For information on what names are
recognized, see section Specifying Colors by Name. The environment variable
BG_COLOR can equally well be used to specify the background
color.
If the `-T gif' option is used, a transparent pseudo-GIF may be
produced by setting the TRANSPARENT_COLOR environment variable to
the name of the background color. See section Environment variables.
pic2plot -T X,
pic2plot -T pnm, and pic2plot -T gif, for which the
graphics display size can be expressed in terms of pixels. The
environment variable BITMAPSIZE can equally well be used to
specify the size.
The graphics display used by pic2plot -T X is an X window;
i.e., one window for each figure. If you choose a rectangular
(non-square) window size, the fonts in each figure will be scaled
anisotropically, i.e., by different factors in the horizontal and
vertical direction. This requires an X11R6 display. Any font that
cannot be scaled in this way will be replaced by a default scalable
font, such as the Hershey vector font "HersheySerif".
For backward compatibility, the X resource Xplot.geometry,
which can be set by the user, may be used to set the window size,
instead of `--bitmap-size' or BITMAPSIZE.
MAX_LINE_LENGTH
can also be used to specify the maximum line length. This option has no
effect on raw pic2plot, since it draws polylines in real time and
has no buffer limitations.
pic2plot -T
ai, pic2plot -T ps, pic2plot -T fig, pic2plot -T
pcl, and pic2plot -T hpgl. "letter" means an 8.5in by
11in page. Any ISO page size in the range "a0"..."a4" or ANSI
page size in the range "a"..."e" may be specified ("letter" is an
alias for "a" and "tabloid" is an alias for "b"). "legal",
"ledger", and "b5" are recognized page sizes also. The environment
variable PAGESIZE can equally well be used to specify the page
size.
For pic2plot -T ai and pic2plot -T ps, the graphics
display within which each figure is drawn will be a square region
centered on the specified page, occupying its full width (with allowance
being made for margins). For pic2plot -T fig, it will be a
square region of the same size, located in the upper left corner of an
xfig display. For pic2plot -T pcl and pic2plot -T
hpgl, the graphics display will be a square region of the same size,
but may be positioned differently. Fine control its positioning on the
page can be accomplished by setting certain environment variables
(see section Environment variables).
The following option is relevant only to raw pic2plot, i.e.,
relevant only if no display type or output format is specified with the
`-T' option. In this case pic2plot outputs a graphics
metafile, which may be translated to other formats by invoking
plot.
META_PORTABLE to "yes".
The following options request information.
pic2plot -T X, pic2plot -T ai, pic2plot
-T ps, and pic2plot -T fig each support the 35 standard
Postscript fonts. pic2plot -T ai, pic2plot -T pcl, and
pic2plot -T hpgl support the 45 standard PCL 5 fonts, and
pic2plot -T pcl and pic2plot -T hpgl support a number of
Hewlett--Packard vector fonts. All of the preceding, together with
pic2plot -T pnm, pic2plot -T gif, and pic2plot
-T tek, support a set of 22 Hershey vector fonts. Raw pic2plot
in principle supports any of these fonts, since its output must be
translated to other formats with plot. The plotfont
utility will produce a character map of any available font.
See section The plotfont Utility.
pic2plot and the plotting utilities
package, and exit.
The behavior of pic2plot is affected by several environment
variables. We have already mentioned the environment variables
BITMAPSIZE, PAGESIZE, BG_COLOR, and
MAX_LINE_LENGTH. They serve as backups for the options
`--bitmap-size', `--page-size', `--bg-color', and
`--max-line-length'. The remaining environment variables are
specific to individual output formats.
pic2plot -T X, which pops up a window on an X Window
System display for each figure, checks the DISPLAY environment
variable. The value of this variable determines the display on which
the windows will be popped up.
pic2plot -T pnm, which produces output in Portable Anymap
(PBM/PGM/PPM) format, is affected by the PNM_PORTABLE environment
variable. If its value is "yes", the output file will be in the
portable (human readable) version of PBM, PGM, or PPM format, rather
than the default (binary) version.
pic2plot -T gif, which produces output in pseudo-GIF format, is
affected by two environment variables. If the value of the
INTERLACE variable is "yes", the pseudo-GIF output file will be
in interlaced format. Also, if the value of the
TRANSPARENT_COLOR environment variable is the name of a color
that appears in the output file, that color will be treated as
transparent by most applications that read GIF files. For information
on what color names are recognized, see section Specifying Colors by Name.
pic2plot -T pcl, which produces PCL 5 output for
Hewlett--Packard printers and plotters, is affected by several
environment variables. The position of the graphics display on the page
can be adjusted by setting the PCL_XOFFSET and PCL_YOFFSET
environment variables, which may be specified in centimeters,
millimeters, or inches. For example, an offset could be specified as
"2cm" or "1.2in". Also, the display can be rotated 90 degrees
counterclockwise on the page by setting the PCL_ROTATE
environment variable to "yes". Besides "no" and "yes", recognized
values for this variable are "0", "90", "180", and "270". "no"
and "yes" are equivalent to "0" and "90", respectively.
The variable PCL_ASSIGN_COLORS is also recognized. It should be
set to "yes" when producing PCL 5 output for a color printer or
other color device. This will ensure accurate color reproduction by
giving the output device complete freedom in assigning colors,
internally, to its "logical pens". If it is "no" then the device will
use a fixed set of colored pens, and will emulate other colors by
shading. The default is "no" because monochrome PCL 5 devices,
which are much more common than colored ones, must use shading to
emulate color.
pic2plot -T hpgl, which produces Hewlett--Packard Graphics
Language output, is also affected by several environment variables. The
most important is HPGL_VERSION, which may be set to "1", "1.5",
or "2" (the default). "1" means that the output should be
generic HP-GL, "1.5" means that the output should be suitable for
the HP7550A graphics plotter and the HP758x, HP7595A and HP7596A
drafting plotters (HP-GL with some HP-GL/2 extensions), and "2"
means that the output should be modern HP-GL/2. If the version is
"1" or "1.5" then the only available fonts will be vector fonts, and
all lines will be drawn with a default thickness (the `-W' option
will not work). Additionally, if the version is "1" then the
filling of arbitrary curves with solid color will not be supported
(circles and rectangles aligned with the coordinate axes may be filled,
though).
The position of the pic2plot -T hpgl graphics display on the page
can be adjusted by setting the HPGL_XOFFSET and
HPGL_YOFFSET environment variables, which may be specified in
centimeters, millimeters, or inches. For example, an offset could be
specified as "2cm" or "1.2in". Also, the display can be rotated 90
degrees counterclockwise on the page by setting the HPGL_ROTATE
environment variable to "yes". Besides "no" and "yes", recognized
values for this variable are "0", "90", "180", and "270". "no"
and "yes" are equivalent to "0" and "90", respectively. "180" and
"270" are supported only if HPGL_VERSION is "2" (the
default).
Opaque filling and the drawing of visible white lines are
supported only if HPGL_VERSION is "2" (the default) and the
environment variable HPGL_OPAQUE_MODE is "yes" (the default).
If the value is "no" then opaque filling will not be used, and white
lines (if any), which are normally drawn with pen #0, will not
be drawn. This feature is to accommodate older HP-GL/2 devices.
HP-GL/2 pen plotters, for example, do not support opacity or the use
of pen #0 to draw visible white lines. Some older HP-GL/2 devices
reportedly malfunction if asked to draw opaque objects.
By default, pic2plot -T hpgl will draw with a fixed set of
pens. Which pens are present may be specified by setting the
HPGL_PENS environment variable. If HPGL_VERSION is
"1", the default value of HPGL_PENS is "1=black"; if
HPGL_VERSION is "1.5" or "2", the default value of
HPGL_PENS is
"1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan". The format
should be self-explanatory. By setting HPGL_PENS, you may
specify a color for any pen in the range #1...#31. For information
on what color names are recognized, see section Specifying Colors by Name. Pen #1
must always be present, though it need not be black. Any other pen in
the range #1...#31 may be omitted.
If HPGL_VERSION is "2" then pic2plot -T hpgl will also be
affected by the environment variable HPGL_ASSIGN_COLORS. If
the value of this variable is "yes", then plot -T hpgl will not
be restricted to the palette specified in HPGL_PENS: it will
assign colors to "logical pens" in the range #1...#31, as
needed. The default value is "no" because other than color LaserJet
printers and DesignJet plotters, not many HP-GL/2 devices allow the
assignment of colors to logical pens.
pic2plot -T tek, which produces output for a Tektronix terminal
or emulator, checks the TERM environment variable. If the
value of TERM is "xterm", "xterms", or "kterm", it is taken
as a sign that the current application is running in an X Window
System VT100 terminal emulator: an xterm. Before drawing
graphics, pic2plot -T tek will emit an escape sequence that
causes the terminal emulator's auxiliary Tektronix window, which is
normally hidden, to pop up. After the graphics are drawn, an escape
sequence that returns control to the original VT100 window will be
emitted. The Tektronix window will remain on the screen.
If the value of TERM is "kermit", "ansi.sys", "ansissys",
"ansi.sysk", or "ansisysk", it is taken as a sign that the current
application is running in the VT100 terminal emulator provided by the
MS-DOS version of kermit. Before drawing graphics,
pic2plot -T tek will emit an escape sequence that switches the
terminal emulator to Tektronix mode. Also, some of the Tektronix
control codes emitted by pic2plot -T tek will be
kermit-specific. There will be a limited amount of color
support, which is not normally the case (the 16 ansi.sys colors
will be supported). After drawing graphics, pic2plot -T tek will
emit an escape sequence that returns the emulator to VT100 mode. The
key sequence `ALT minus' can be employed manually within
kermit to switch between the two modes.
Go to the first, previous, next, last section, table of contents.