This file documents version 2.2 of the GNU plotting utilities package, including GNU libplot 2.0 Copyright (C) 1989-1999 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. This is the documentation for version 2.2 of the GNU plotting utilities package, including GNU libplot 2.0. The package consists of programs and functions for data plotting and vector graphics. The GNU Plotting Utilities ************************** The GNU plotting utilities consist of eight command-line programs: the graphics programs `graph', `plot', `pic2plot', `tek2plot', and `plotfont', and the mathematical programs `spline', `ode', and `double'. Distributed with these programs is GNU `libplot', the library on which the graphics programs are based. `libplot' is a function library for device-independent two-dimensional vector graphics, including vector graphics animations under the X Window System. There are versions for both C and C++. The graphics programs and `libplot' can export vector graphics in the following ten formats. X If this output option is selected, there is no output file. Output is directed to a popped-up window on an X Window System display. PNM This is "portable anymap" format. There are three types of portable anymap: PBM (portable bitmap, for monochrome images), PGM (portable graymap), and PPM (portable pixmap, for colored images). The output file will be in whichever of these three formats is most appropriate. Portable anymaps may be viewed or edited with many applications, such as the free image display application `xv'. GIF This is pseudo-GIF format rather than true GIF format. Unlike GIF format it does not use LZW compression, so it does not transgress the Unisys LZW patent. However, files in pseudo-GIF format may be viewed or edited with any application that understands GIF format, such as `xv'. AI This is the format used by Adobe Illustrator. Files in this format may be edited with Adobe Illustrator (version 5, and more recent versions), or other applications. PS This is `idraw'-editable Postscript format. Files in this format may be sent to a Postscript printer, imported into another document, or edited with the free `idraw' drawing editor. See *Note idraw::. Fig This is a graphics format that may be displayed or edited with the free `xfig' drawing editor. See *Note xfig::. PCL 5 This is a powerful version of Hewlett-Packard's Printer Control Language. Files in this format may be sent to a LaserJet printer or compatible device (note that most inkjets do not support PCL 5). HP-GL This is Hewlett-Packard's Graphics Language. By default, the modern variant HP-GL/2 is produced. Files in HP-GL or HP-GL/2 format may be imported into a document or sent to a plotter. Tek This is the graphics format understood by Tektronix 4014 terminals and emulators, including the emulators built into the `xterm' terminal emulator program and the MS-DOS version of `kermit'. Metafile This is device-independent GNU graphics metafile format. The `plot' program can translate it to any of the preceding formats. Of the command-line graphics programs, the best known is `graph', which is an application for plotting two-dimensional scientific data. It reads one or more data files containing datasets, and outputs a plot. The above output formats are supported. The corresponding commands are `graph -T X', `graph -T pnm', `graph -T gif', `graph -T ai', `graph -T ps', `graph -T fig', `graph -T pcl', `graph -T hpgl', `graph -T tek', and `graph'. `graph' without a `-T' option (referred to as `raw `graph'') produces output in GNU metafile format. `graph' can read datasets in both ASCII and binary format, and datasets in the `table' format produced by the plotting program `gnuplot'. It produces a plot with or without axes and labels. You may specify labels and ranges for the axes, and the size and position of the plot on the display. The labels may contain subscripts and subscripts, Greek letters, and other special symbols; there is also support for Cyrillic script (i.e., Russian) and Japanese. You may specify the type of plotting symbol used for each dataset, and such parameters as the style and thickness of the line (if any) used to connect points in a dataset. The plotting of filled regions is supported, as is the drawing of error bars. `graph' provides full support for multiplotting. With a single invocation of `graph', you may produce a plot consisting of many sub-plots, either side by side or inset. Each sub-plot will have its own axes and data. `graph -T X', `graph -T tek', and raw `graph' have a feature that most plotting programs do not have. They can accept input from a pipe, and plot data points to the output in real time. For this to occur, the user must specify ranges for both axes, so that `graph' does not need to wait until the end of the input before determining them. The `plot' program is a so-called plot filter. It can translate GNU graphics metafiles (produced for example by raw `graph') into any supported output format. The corresponding commands are `plot -T X', `plot -T pnm', `plot -T gif', `plot -T ai', `plot -T ps', `plot -T fig', `plot -T pcl', `plot -T hpgl', `plot -T tek', and `plot'. The `plot' program is useful if you wish to produce output in several different formats while invoking `graph' only once. It is also useful if you wish to translate files in the traditional `plot(5)' format produced by, e.g., the non-GNU versions of `graph' provided with some operating systems. GNU metafile format is compatible with plot(5) format. The `pic2plot' program can translate from the pic language to any supported output format. The pic language, which was invented at Bell Laboratories, is used for creating box-and-arrow diagrams of the kind frequently found in technical papers and textbooks. The corresponding commands are `pic2plot -T X', `pic2plot -T pnm', `pic2plot -T gif', `pic2plot -T ai', `pic2plot -T ps', `pic2plot -T fig', `pic2plot -T pcl', `pic2plot -T hpgl', `pic2plot -T tek', and `pic2plot'. The `tek2plot' program can translate from Tektronix format to any supported output format. The corresponding commands are `tek2plot -T X', `tek2plot -T pnm', `tek2plot -T gif', `tek2plot -T ai', `tek2plot -T ps', `tek2plot -T fig', `tek2plot -T pcl', `tek2plot -T hpgl', and `tek2plot'. `tek2plot' is useful if you have an older application that produces drawings in Tektronix format. The `plotfont' program is a simple utility that displays a character map for any font that is available to `graph', `plot', `pic2plot', or `tek2plot'. The 35 standard Postscript fonts are available if the `-T X', `-T ai', `-T ps', or `-T fig' options are used. The 45 standard PCL 5 fonts (i.e., "LaserJet" fonts) are available if the `-T ai', `-T pcl' or `-T hpgl' options are used. In the latter two cases (`-T pcl' and `-T hpgl'), a number of Hewlett-Packard vector fonts are available as well. A set of 22 Hershey vector fonts, including Cyrillic fonts and a Japanese font, is always available. When producing output for an X Window System display, any of the graphics programs can use scalable X fonts. Of the command-line mathematical programs, `spline' does spline interpolation of scalar or vector-valued data. It normally uses either cubic spline interpolation or exponential splines in tension, but like `graph' it can function as a real-time filter under some circumstances. Besides splining datasets, it can construct curves, either open or closed, through arbitrarily chosen points in d-dimensional space. `ode' provides the ability to integrate an ordinary differential equation or a system of ordinary differential equations, when provided with an explicit expression for each equation. It supplements the plotting program `gnuplot', which can plot functions but not integrate ordinary differential equations. The final command-line mathematical program, `double', is a filter for converting, scaling and cutting binary or ASCII data streams. It is still under development and is not yet documented. The `libplot' function library is discussed at length elsewhere in this documentation. It gives C and C++ programs the ability to draw such objects as lines, open and closed polylines, arcs (both circular and elliptic), quadratic and cubic Bezier curves, circles and ellipses, points, marker symbols, and text strings. The filling of objects other than points, marker symbols, and text strings is supported (fill color, as well as pen color, can be set arbitrarily). Text strings can be drawn in any of a large number of fonts. The 35 standard Postscript fonts are supported by the X Window System, Illustrator, Postscript, and `xfig' drivers, and the 45 standard PCL 5 fonts are supported by the Illustrator, PCL 5 and HP-GL/2 drivers. The latter two also support a number of Hewlett-Packard vector fonts. All drivers, including the PNM, GIF, Tektronix and metafile drivers, support a set of 22 Hershey vector fonts. The support for drawing text strings is extensive. Text strings may include subscripts and superscripts, and may include characters chosen from more than one font in a typeface. Many non-alphanumeric characters may be included. The entire collection of over 1700 `Hershey glyphs' digitized by Allen V. Hershey at the U.S. Naval Surface Weapons Center, which includes many curious symbols, is built into `libplot'. Text strings in the so-called EUC-JP encoding (i.e., the Extended Unix Code for Japanese) can be also be drawn. Such strings may include both syllabic Japanese characters (Hiragana and Katakana) and ideographic Japanese characters (Kanji). A library of 603 Kanji, including 596 of the 2965 frequently used Level 1 Kanji, is built into `libplot'. The drawing editors `idraw' and `xfig' are not distributed along with the GNU plotting utilities. However, they are free software, and you may readily obtain them elsewhere (*note Auxiliary Software::.). The `graph' Application *********************** Each invocation of `graph' reads one or more datasets from files named on the command line or from standard input, and prepares a plot. There are many command-line options for adjusting the visual appearance of the plot. The following sections explain how to use the most frequently used options, by giving examples. Simple examples using `graph' ============================= By default, `graph' reads ASCII data from the files specified on the command line, or from standard input if no files are specified. The data are pairs of numbers, interpreted as the x and y coordinates of data points: 0.0 0.0 1.0 0.2 2.0 0.0 3.0 0.4 4.0 0.2 5.0 0.6 Data points do not need to be on different lines, nor do the x and y coordinates of a data point need to be on the same line. However, there should be no blank lines in the input if it is to be viewed as forming a single dataset. To plot such a dataset with `graph', you could do graph -T ps ascii_data_file > plot.ps or equivalently graph -T ps < ascii_data_file > plot.ps This will produce an encapsulated Postscript file `plot.ps', which you may include in another document, display on a screen, or send directly to a printer. (The `--page-size' option, or the `PAGESIZE' environment variable, specifies the size of the printed page. The default is "letter", i.e., 8.5in by 11in, but "a4" or other ISO or ANSI page sizes can be specified instead.) You may also do graph -T fig < ascii_data_file > plot.fig to produce a file `plot.fig' that you may edit with the the free `xfig' drawing editor, or graph -T ai < ascii_data_file > plot.ai to produce a file `plot.ai' that you may edit with Adobe Illustrator. If you do graph -T hpgl < ascii_data_file > plot.plt you will produce a file `plot.plt' in the Hewlett-Packard Graphics Language (HP-GL/2) that you may send to a Hewlett-Packard plotter. Similarly, you may use `graph -T pcl' to produce a file in PCL 5 format that may be printed on a LaserJet or other laser printer. You may use `graph -T X' to pop up a window on an X Window System display, and display the plot in it. For that, you would do graph -T X < ascii_data_file If you use `graph -T X', no output file will be produced; only a window. The window will vanish if you type `q' or click your mouse in it. You may also use `graph -T pnm' to produce a PNM file (a "portable anymap"), and `graph -T gif' to produce a pseudo-GIF file. If the free image display application `xv' is available on your system, you would use either of the two commands graph -T pnm < ascii_data_file | xv - graph -T gif < ascii_data_file | xv - to display the output file. Another thing you can do is use `graph -T tek' to display a plot on a device that can emulate a Tektronix 4014 graphics terminal. `xterm', the X Window System terminal emulator, can do this. Within an `xterm' window, you would do graph -T tek < ascii_data_file `xterm' normally emulates a VT100 terminal, but when this command is issued from within it, it will pop up a second window (a `Tektronix window') and draw the plot in it. The Japanese terminal emulator `kterm' should be able to do the same, provided that it is correctly installed. Another piece of software that can emulate a Tektronix 4014 terminal is the MS-DOS version of `kermit'. `graph' may behave differently depending on the environment in which it is invoked. We have already mentioned the `PAGESIZE' environment variable, which affects the operation of `graph -T ai', `graph -T ps', `graph -T fig', `graph -T pcl', and `graph -T hpgl'. Similarly, the `BITMAPSIZE' environment variable affects the operation of `graph -T X', `graph -T pnm', and `graph -T gif'. The `DISPLAY' environment variable affects the operation of `graph -T X', and the `TERM' environment variable affects the operation of `graph -T tek'. There are also several environment variables that affect the operation of `graph -T pcl' and `graph -T hpgl'. For a complete discussion of the effects of the environment on `graph', see *Note graph Environment::. The following remarks apply irrespective of which output format is specified. By default, successive points in the dataset are joined by solid line segments, which form a polygonal line or polyline that we call simply a `line'. You may choose the style of line (the `linemode') with the `-m' option: graph -T ps -m 2 < ascii_data_file > plot.ps Here `-m 2' indicates that linemode #2 should be used. If the dataset is rendered in monochrome, which is the default, the line can be drawn in one of five distinct styles. Linemodes #1 through #5 signify solid, dotted, dotdashed, shortdashed, and longdashed; thereafter the sequence repeats. If the `-C' option is used, the dataset will be rendered in color. For colored datasets, the line can be drawn in one of 25 distinct styles. Linemodes #1 through #5 signify red, green, blue, magenta, and cyan; all are solid. Linemodes #6 through #10 signify the same five colors, but dotted rather than solid. Linemodes #11 through #16 signify the same five colors, but dotdashed, and so forth. After linemode #25, the sequence repeats. Linemode #0, irrespective of whether the rendering is in monochrome or color, means that the line is not drawn. If you wish to _fill_ the polygon bounded by the line (i.e., shade it, or fill it with a solid color), you may use the `-q' option. For example, echo .1 .1 .1 .9 .9 .9 .9 .1 .1 .1 | graph -T ps -C -m 1 -q 0.3 > plot.ps will plot a square region with vertices (0.1,0.1), (0.1,0.9), (0.9,0.9), and (0.9,0.1). The repetition of the first vertex (0.1,0.1) at the end of the sequence of vertices ensures that the square will be closed: all four segments of its boundary will be drawn. The square will be drawn in red, since the colored version of linemode #1 is requested. The interior of the square will be filled with red to an intensity of 30%, as the `-q 0.3' option specifies. If the intensity were zero, the region would be filled with white, and if it were 1.0, the region would be filled with solid color. If the intensity were negative, the region would be unfilled, or transparent (the default). You may choose the thickness (`width') of the line, whether it is filled or not, by using the `-W' option. For example, `-W 0.01' specifies that the line should have a thickness equal to 0.01 times the size of the display. Also, you may put symbols at each data point along the line by doing, for example, graph -T ps -S 3 0.1 < ascii_data_file > plot.ps where the first argument 3 indicates which symbol to plot. The optional second argument 0.1 specifies the symbol size as a fraction of the size of the `plotting box': the square within which the plot is drawn. Symbol #1 is a dot, symbol #2 is a plus sign, symbol #3 is an asterisk, symbol #4 is a circle, symbol #5 is a cross, and so forth. (*Note Marker Symbols::.) Symbols 1 through 31 are the same for all display types, and the color of a symbol will be the same as the color of the line it is plotted along. Actually, you would probably not want to plot symbols at each point in the dataset unless you turn off the line joining the points. For this purpose, the `negative linemode' concept is useful. A line whose linemode is negative is not visible; however, any symbols plotted along it will have the color associated with the corresponding positive linemode. So, for example, graph -T ps -C -m -3 -S 4 < ascii_data_file > plot.ps will plot a blue circle at each data point. The circles will not be joined by line segments. By adding the optional second argument to the `-S' option, you may adjust the size of the circles. `graph' will automatically generate abscissa (i.e., x) values for you if you use the `-a' option. If this option is used, no abscissa values should be given in the data file. The data points will be taken to be regularly spaced along the abscissa. The two arguments following `-a' on the command line will be taken as the sampling interval and the abscissa value of the first data point. If they are absent, they default to 1.0 and 0.0 respectively. For example, the command echo 0 1 0 | graph -T ps -a > plot.ps produces exactly the same plot as echo 0 0 1 1 2 0 | graph -T ps > plot.ps `graph' will plot data with error bars, if the `-I e' option is specified. If it is, the dataset should consist of triples (x,y,error) rather than pairs (x,y). A vertical error bar of the appropriate length will be plotted at each data point. You may plot a symbol at each data point, along with the error bar, by using the `-S' option in the usual way. The symbol will be the same for each point in the dataset. You may use the `-a' option in conjunction with `-I e', if you wish. If you do, the dataset should contain no abscissa (i.e., x) values. By default the limits on the x and y axes, and the spacing between the labeled ticks on each axis, are computed automatically. You may wish to set them manually. You may accomplish this with the `-x' and `-y' options. echo 0 0 1 1 2 0 | graph -T ps -x -1 3 -y -1 2 > plot.ps will produce a plot in which the x axis extends from -1 to 3, and the y axis from -1 to 2. By default, `graph' tries to place about six numbered ticks on each axis. By including an optional third argument to either `-x' or `-y', you may manually set the spacing of these ticks, also. For example, using `-y -1 2 1' rather than `-y -1 2' will produce a y axis with labeled ticks at -1, 0, 1, and 2, rather than at the locations that `graph' would choose by default, which would be -1, -0.5, 0, 0.5, 1, 1.5, and 2. In general, if a third argument is present then labeled ticks will be placed at each of its integer multiples. To make an axis logarithmic, you may use the `-l' option. For example, echo 1 1 2 3 3 1 | graph -T ps -l x > plot.ps will produce a plot in which the x axis is logarithmic, but the y axis is linear. To make both axes logarithmic, you would use `-l x -l y'. By default, the upper and lower limits on a logarithmic axis are powers of ten, and there are tick marks at each power of ten and at its integer multiples. The tick marks at the powers of ten are labeled. If the axis spans more than five orders of magnitude, the tick marks at the integer multiples are omitted. If you have an unusually short logarithmic axis, you may need to increase the number of labeled ticks. To do this, you should specify a tick spacing manually. For example, `-l x -x 1 9 2' would produce a plot in which the x axis is logarithmic and extends from 1 to 9. Labeled ticks would be located at each integer multiple of 2, i.e., at 2, 4, 6, and 8. You may label the x and y axes with the `-X' and `-Y' options, respectively. For example, echo 1 1 2 3 3 1 | graph -T ps -l x -X "A Logarithmic Axis" > plot.ps will label the log axis in the preceding example. By default the label for the y axis (if any) will be rotated 90 degrees, unless you use the `--toggle-rotate-y-label' option. You may specify a `top label', or title for the plot, by using the `-L' option. Doing, for example, echo 1 1 2 3 3 1 | graph -T ps -l x -L "A Simple Example" > plot.ps will produce a plot with a title on top. The size of the x axis and y axis labels is specified with the `-f' option, and the size of the title is specified with the `--title-font-size' option. For example, echo 1 1 2 3 3 1 | graph -T ps -X "Abscissa" -f 0.1 > plot.ps will produce a plot in which the font size of the x axis label, and each of the numerical tick labels, is very large (0.1 times the size of the plotting box, i.e., the square within which the plot is drawn). The font in which the labels specified with the `-X', `-Y', and `-L' options are drawn can be specified with the `-F' option. For example, `-F Times-Roman' will make the labels appear in Times-Roman instead of the default font (which is Helvetica, unless `-T pnm', `-T gif', `-T pcl', `-T hpgl' or `-T tek' is specified). Font names are case-insensitive, so `-F times-roman' will work equally well. The available fonts include 35 Postscript fonts (for all variants of `graph' other than `graph -T pnm', `graph -T gif', `graph -T pcl', `graph -T hpgl' and `graph -T tek'), 45 PCL 5 fonts (for `graph -T ai', `graph -T pcl' and `graph -T hpgl'), a number of Hewlett-Packard vector fonts (for `graph -T pcl' and `graph -T hpgl'), and 22 Hershey vector fonts. The Hershey fonts include HersheyCyrillic, for Russian, and HersheyEUC, for Japanese. For a discussion of the available fonts, see *Note Text Fonts::. The `plotfont' utility will produce a character map of any available font. *Note plotfont::. The format of the labels drawn with the `-X', `-Y', and `-L' options may be quite intricate. Subscripts, superscripts, square roots, and switching fonts within a typeface are all allowed. The above examples do not illustrate this, but for details, see *Note Text String Format::. Each of the preceding examples produced a plot containing the default sort of grid (a square box, with ticks and labels drawn along its lower edge and its left edge). There are actually several sorts of grid you may request. The `-g 0', `-g 1', `-g 2', and `-g 3' options yield successively fancier grids. What they yield, respectively, is no grid at all, a pair of axes with ticks and labels, a square box with ticks and labels, and a square box with ticks, labels, and grid lines. As you can see, `-g 2' is the default. There is also a `-g 4' option, which yields a slightly different sort of grid: a pair of axes that cross at the origin. This last sort of grid is useful if the x or y coordinates of the data points you are plotting are both positive and negative. Rotated, non-square and displaced plots ======================================= To rotate the plotting box by 90 degrees counterclockwise on your graphics display, you would add `--rotation 90' to the `graph' command line. You may also specify `--rotation 180', to produce an upside-down plot, or `--rotation 270'. To alter the linear dimensions of the plotting box, and also to position it in a different part of the display, you could do something like graph -T ps -h .3 -w .6 -r .1 -u .1 < ascii_data_file > plot.ps Here the `-h' and `-w' options specify the height and width of the plotting box, and the `-r' and `-u' options indicate how far up and to the right the lower left corner of the plotting box should be positioned. All dimensions are expressed as fractions of the size of the graphics display, which by convention is a square. By default, the height and width of the plotting box equal 0.6, and the `upward shift' and the `rightward shift' equal 0.2. So the above example will produce a plot that is half as tall as usual. Compared to its usual position, the plot will be shifted slightly downward and to the left. Several command-line options specify sizes or dimensions as fractions of the size of the plotting box, rather than as fractions of the size of the display. For example, `-S 3 .01' specifies that the plotting symbols for the following dataset should be of type #3, and should have a font size equal to 0.01, i.e. 0.01 times the minimum dimension (height or width) of the plotting box. If the `-h' or `-w' options are employed to expand or contract the plot, such sizes or dimensions will scale in tandem. That is presumably the right thing to do. The `-h', `-w', `-r', and `-u' options may be combined with the `--rotation' option. If they appear together, the plotting box is first positioned, and then rotated. In fact, `--rotation' specifies how the plot should be mapped to the graphics display, rather than how the plot is designed. The `graphics display' is an abstraction. For `graph -T X', it is a window on an X display. For `graph -T pnm' and `graph -T gif', it is a square or rectangular bitmap. In these three cases, the size of the graphics display can be set by using the `--bitmap-size' option, or by setting the `BITMAPSIZE' environment variable. For `graph -T tek', the graphics display is a square region occupying the central part of a Tektronix display. (Tektronix displays are 4/3 times as wide as they are high.) For `graph -T ai' and `graph -T ps', by default it is a square region centered on an 8.5in by 11in page (US letter size), occupying its full width with allowance being made for margins. For `graph -T fig', by default it is a square region of the same size, positioned in the upper left corner of an `xfig' display. For `graph -T pcl' and `graph -T hpgl', by default it is a square region of the same size, with position and orientation on the page being controlled by environment variables. The page size used by `graph -T ai', `graph -T ps', `graph -T fig', `graph -T pcl', and `graph -T hpgl' can be set by using the `--page-size' option, or by setting the environment variable `PAGESIZE'. For example, setting `PAGESIZE' to "a4" would position the graphics display appropriately on an A4-size page (21cm by 29.7cm). Preparing a plot from more than one dataset =========================================== It is frequently the case that several datasets need to be displayed on the same plot. If so, you may wish to distinguish the points in different datasets by joining them by lines of different types, or by using plotting symbols of different types. A more complicated example would be the following. You may have a file containing a dataset that is the result of experimental observations, and a file containing closely spaced points that trace out a theoretical curve. The second file is a dataset in its own right. You would presumably plot it with line segments joining successive points, so as to trace out the theoretical curve. But the first dataset, resulting from experiment, would be plotted without such line segments. In fact, a plotting symbol would be plotted at each of its points. These examples, and others like them, led us to define a set of seven _attributes_ which define the way in which a dataset should be plotted. These attributes, which can be set by command-line options, are the following. 1. color/monochrome 2. linemode 3. linewidth 4. symbol type 5. symbol size 6. symbol font name 7. fill fraction Color/monochrome (a choice of one or the other) is the simplest. This choice is toggled with the `-C' option. The `linemode' (i.e., line style) specifies how the line segments joining successive points should be drawn; it is specified with the `-m' option. Linemode #0 means no linemode at all, for example. `Linewidth' means line thickness; it is specified with the `-W' option. `Symbol type' and `symbol size', which are specified with the `-S' option, specify the symbol plotted at each point of the dataset. `Symbol font name' refers to the font from which plotting symbols #32 and above, which are taken to be characters rather than geometric symbols, are selected. It is set with the `--symbol-font-name' option, and is relevant only if `-S' is used to request such special plotting symbols. Finally, the polygonal line joining the points in a dataset may be _filled_, to create a filled or shaded polygon. The `fill fraction' is set with the `-q' option. A negative fill fraction means no fill, or transparent; zero means white, and 1.0 means solid, or fully colored. The preceding seven attributes refer to the way in which datasets are plotted. Datasets may also differ from one another in the way in which they are read from files. The dataset(s) in a file may or may not contain error bars, for example. If a file contains data with error bars, the `-I e' option should occur on the command line before the file name. (The `-I' option specifies the input format for the following files.) The following illustrates how datasets in three different input files could be plotted simultaneously. graph -T ps -m 0 -S 3 file_1 -C -m 3 file_2 -C -W 0.02 file_3 > output.ps The dataset in `file_1' will be plotted in linemode #0, so successive points will not be joined by lines. But symbol #3 (an asterisk) will be plotted at each point. The dataset in `file_2' will be plotted in color, and linemode #3 will be used. In color plotting, linemode #3 is interpreted as a solid blue line. The second `-C' on the command line turns off color for `file_3'. The points in the third dataset will be joined by a black line with thickness 0.02, as a fraction of the size (i.e., minimum dimension) of the graphics display. The above command line could be made even more complicated by specifying additional options (e.g., `-q' or `-I') before each file. In fact the command line could also include such standard options as `-x' or `-y', which specify the range of each axis. Such options, which refer to the plot as a whole rather than to individual datasets, should appear before the first file name. For example, you could do graph -T ps -x 0 1 0.5 -m 0 -S 3 file_1 -C -m 3 file_2 > output.ps Note that it is possible to include the special file name `-', which refers to standard input, on the command line. So you may produce a plot in part from files, and in part from input that is piped to `graph' from another program. Each input file may include more than one dataset. If so, the command line options preceding a file on the command line will take effect for all datasets in that file. There are two exceptions to this. By default, the linemode is incremented (`bumped') from one dataset to the next. This feature is usually quite convenient. For example, if you do graph -T ps -m 3 file_1 > output.ps the first dataset in `file_1' will appear in linemode #3, the second in linemode #4, etc. In fact if you do graph -T ps file_1 file_2 ... > output.ps without specifying linemode explicitly, the successive datasets read from the files on the command line will appear in linemode #1, linemode #2, .... If you do not like this feature, you may turn it off, or in general toggle it, by using the `-B' option. You may also control manually the linemode and symbol type used for the datasets within any file. You would do this by including directives in the file itself, rather than on the command line. For example, if the line #m=-5,S=10 appeared in an ASCII-format input file, it would be interpreted as a directive to switch to linemode #-5 and symbol type #10 for the following dataset. Future releases of `graph' may provide the ability to set each of the seven dataset attributes in this way. Multiplotting: placing multiple plots on a single page ====================================================== It is occasionally useful to display several plots at once on a single page, or on a single graphics display. We call such a composite plot a _multiplot_. One common sort of multiplot is a small plot inset into a larger one. Another sort is two or more plots side by side. `graph' can draw multiplots consisting of an arbitrarily large number of sub-plots. When multiplotting, `graph' draws each sub-plot in its own `virtual display'. When an ordinary plot is drawn, the virtual display is the same as the physical display. But when a multiplot is drawn, the virtual display may be any smaller square region. The following example illustrates the idea. graph -T ps data_file_1 --reposition .35 .35 .3 data_file_2 Here `data_file_1' is plotted in the usual way. The `--reposition' option specifies that when `data_file_2' is plotted, it will be drawn within a virtual display. For the purposes of the `--reposition' option, the physical display is a square with lower left corner (0.0,0.0) and upper right corner (1.0,1.0). In those coordinates, the virtual display will be a square of size 0.3 with lower left corner (0.35,0.35). So the second sub-plot will be inset into the first. Just as the `-w', `-h', `-r', and `-u' options may be used to set the size and position of a plotting box within the physical display, so they may be used to set the size and position of a plotting box within a virtual display. For example, graph -T ps data_file_1 --reposition .35 .35 .3 -w .4 -r .3 data_file_2 will yield a multiplot in which the second sub-plot is significantly different. Its plotting box will have a width only 0.4 times the width of the virtual display. However, the plotting box will be centered within the virtual display, since the distance between the left edge of the plotting box and the left edge of the virtual display will be 0.3 times the width of the virtual display. By convention, before each sub-plot of a multiplot other than the first is drawn, a `blankout region' surrounding its plotting box is erased. (That is, it is filled with white.) This erasure prevents the sub-plots from overlapping and producing a messy result. By default, the blankout region is a rectangular region 30% larger in each dimension than the plotting box for the sub-plot. This is appropriate if the sub-plot is a small one that is inset into the first sub-plot. It may not be appropriate, however, if you are preparing a multiplot in which several sub-plots appear side by side. You may use the `--blankout' option to adjust this parameter. For example, specifying `--blankout 1.0' will make the blankout region for a sub-plot coincide with its plotting box. Specifying `--blankout 0.0' will prevent any blanking out from occurring. The blankout parameter may differ from sub-plot to sub-plot. It should be emphasized that every sub-plot in a multiplot is a plot in its own right. All the usual options (`-m', `-S', `-x', `-y', etc.) can be applied to each sub-plot separately. The options for a sub-plot should occur on the `graph' command line immediately after the `--reposition' option that applies to it. Each sub-plot may be prepared from more than a single dataset, also. The names of the data files for each subplot should occur on the command line before the following `--reposition' option, if any. Reading binary and other data formats ===================================== By default, `graph' reads datasets in ASCII format. But it can also read datasets in any of three binary formats (single precision floating point, double precision floating point, and integer). These three input formats are specified by the `-I d', `-I f', and `-I i' options, respectively. There are two advantages to using binary data: 1) `graph' runs significantly faster because the computational overhead for converting data from ASCII to binary is eliminated, and 2) the input files may be significantly smaller. If you have very large datasets, using binary format may reduce storage and runtime costs. For example, you may create a single precision binary dataset as output from a C language program: #include void write_point (float x, float y) { fwrite(&x, sizeof (float), 1, stdout); fwrite(&y, sizeof (float), 1, stdout); } You may plot data written this way by doing: graph -T ps -I f < binary_data_file > plot.ps The inclusion of multiple datasets within a single binary file is supported. If a binary file contains more than a single dataset, successive datasets should be separated by a single occurrence of the the largest possible number. For single precision datasets this is the quantity `FLT_MAX', for double precision datasets it is the quantity `DBL_MAX', and for integer datasets it is the quantity `INT_MAX'. On most machines `FLT_MAX' is approximately 3.4x10^38, `DBL_MAX' is approximately 1.8x10^308, and `INT_MAX' is 2^32-1. If you are reading datasets from more than one file, it is not required that the files be in the same format. For example, graph -T ps -I f binary_data_file -I a ascii_data_file > plot.ps will read `binary_data_file' in `f' (binary single precision) format, and `ascii_data_file' in `a' (normal ASCII) format. There is currently no support for reading and plotting binary data with error bars. If you have data with error bars, you should supply the data to `graph' in ASCII, and use the `-I e' option. `graph' can also read data files in the ASCII `table' format produced by the `gnuplot' plotting program. For this, you should use the `-I g' option. Such a data file may consist of more than one dataset. To sum up: there are six supported data formats, `a' (normal ASCII), `e' (ASCII with error bars), `g' (the ASCII `table' format produced by `gnuplot'), `f' (binary single precision), `d' (binary double precision), and `i' (binary integer). Input files may be in any of these six formats. `graph' command-line options ============================ The `graph' program reads one or more datasets from files named on the command line or from standard input, and prepares a plot. The output format or display type is specified with the `-T' option. By default, `graph' reads ASCII data from the files specified on the command line. The data are pairs of numbers, interpreted as the x and y coordinates of data points. 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 graph is displayed in a window on an X Window System display, and there is no output file. There are many command-line options for adjusting the visual appearance of the plot. The relative order of file names and command-line options is important. Only the options that precede a file name on the command line take effect for that file. The following sections list the possible options. Each option that takes an argument is followed, in parentheses, by the type and default value of the argument. There are five sorts of option. The behavior of `graph' is also affected by a number of environment variables, so there is a section discussing them as well. Plot options ------------ The following options affect an entire plot. They should normally occur at most once, and should appear on the command line before the first file name. If a multiplot is being drawn, they may (with the exception of the `-T' option) occur more than once. If so, the second and later occurrences should be placed on the command line immediately after each `--reposition X Y' option. `-T TYPE' `--display-type TYPE' (String, default "meta".) Select a display type or output format of type TYPE, which may be one of the strings "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta". These refer respectively to the X Window System, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the format used by Adobe Illustrator, `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. `-E X|Y' `--toggle-axis-end X|Y' Set the position of the indicated axis to be on the other end of the plotting box from what is currently the case. E.g., `-E y' will cause the y axis to appear on the right of the plot rather than the left, which is the default. Similarly, `-E x' will cause the x axis to appear at the top of the plot rather than the bottom. Note that if the x axis appears at the top, no plot title will be drawn (since there will be no room). `-f SIZE' `--font-size SIZE' (Float, default 0.0525.) Set the size of the font used for the axis and tick labels to be SIZE. The size is specified as a fraction of the minimum dimension (width or height) of the plotting box. `-F FONT_NAME' `--font-name FONT_NAME' (String, default "Helvetica" except for `graph -T pnm', `graph -T gif', `graph -T pcl', `graph -T hpgl', `graph -T tek', and raw `graph', for all of which "HersheySerif" is the default.) Set the font used for the axis and tick labels, and for the plot title (if any), to be FONT_NAME. The choice of font for the plot title may be overridden with the `--title-font-name' option (see below). 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 *Note Text Fonts::. The `plotfont' utility will produce a character map of any available font. *Note plotfont::. `-g GRID_STYLE' `--grid-style GRID_STYLE' (Integer in the range 0...4, default 2.) Set the grid style for the plot to be GRID_STYLE. Grid styles 0 through 3 are progressively more fancy, but style 4 is a somewhat different style. 0. no axes, tick marks or labels. 1. a pair of axes, with tick marks and labels. 2. box around plot, with tick marks and labels. 3. box around plot, with tick marks and labels; also grid lines. 4. axes intersect at the origin, with tick marks and labels. `-h HEIGHT' `--height-of-plot HEIGHT' (Float, default 0.6.) Set the fractional height of the plot with respect to the height of the display (or virtual display, in the case of a multiplot) to be HEIGHT. A value of 1.0 will produce a plotting box that fills the available area. Note that tick marks and labels are outside the plotting box, so that values less than 1.0 are generally used. `-k LENGTH' `--tick-size LENGTH' (Float, default .02.) Set the length of the tick marks on each axis to be LENGTH. A value of 1.0 produces tick marks whose length is equal to the minimum dimension (width or height) of the plotting box. A negative LENGTH yields tick marks that extend outside the box, rather than inside. `-K CLIP_MODE' `--clip-mode CLIP_MODE' (Integer, default 1.) Set the clip mode for the plot to CLIP_MODE. The clip mode is relevant only if data points are being joined by a line, and the line is not being filled to create a filled region (since filled regions are clipped in a fixed way). There are three clip modes: 0, 1, and 2. Clip mode 0 means that a line segment joining two data points will be plotted only if neither point is outside the plotting box. Clip mode 1 means that it will be plotted if no more than one of the two points is outside, and clip mode 2 means that it will be plotted even if both are outside. In all cases the line segment will be clipped to the plotting box. `-l X|Y' `--toggle-log-axis X|Y' Set the specified axis to be a log axis rather than a linear axis, or vice versa. By default, both axes are linear axes. `-L TOP_LABEL' `--top-label TOP_LABEL' (String, default empty.) Place the text string TOP_LABEL above the plot, as its `top label', i.e., title. The string may include escape sequences (*note Text String Format::.). The `--title-font-size' option may be used to specify the size of the font. The font is normally the same as the font used for labeling axes and ticks, as selected by the `-F' option. But this can be overridden with the `--title-font-name' option. `-N X|Y' `--toggle-no-ticks X|Y' Toggle the presence of ticks and tick labels on the specified axis. This applies to the grid styles that normally include ticks and tick labels, i.e., grid styles 1, 2, 3, and 4. `-r RIGHT' `--right-shift RIGHT' (Float, default 0.2.) Move the plot to the right by a fractional amount RIGHT with respect to the width of the display (or virtual display, in the case of a multiplot). This produces a margin on the left side of the plotting box. A value of 0.5 will produce a margin half the width of the available area. Note that the tick marks and labels are drawn in the margin. `-R X|Y' `--toggle-round-to-next-tick X|Y' Toggle whether or not the upper and lower limits of the specified axis should be expanded, so that they both become integer multiples of the spacing between labeled tick marks. This option is meaningful whenever the user specifies either or both of the limits, by using the `-x' or `-y' option. If the user leaves both limits unspecified, they will always be chosen to satisfy the `integer multiple' constraint. `-s' `--save-screen' Save the screen. This option requests that `graph' not erase the display device before it begins to plot. This option is relevant only to `graph -T tek' and raw `graph'. Tektronix displays and emulators are persistent, in the sense that previously drawn graphics remain visible. So by repeatedly using `graph -T tek -s', you can build up a multiplot. `-t' `--toggle-transpose-axes' Transpose the abscissa and ordinate. This causes the axes to be interchanged, and the options that apply to each axis to be applied to the opposite axis. That is, data points are read in as (y, x) pairs, and such options as `-x' and `-X' apply to the y axis rather than the x axis. If the `-I e' option is in force, so that the data points are read with error bars, the orientation of the error bars will be switched between vertical and horizontal. `-u UP' `--upward-shift UP' (Float, default 0.2.) Move the plot up by a fractional amount UP with respect to the height of the display (or virtual display, in the case of a multiplot). This produces a margin below the plotting box. A value of 0.5 will produce a margin half the height of the available area. Note that the tick marks and labels are drawn in the margin. `-w WIDTH' `--width-of-plot WIDTH' (Float, default 0.6.) Set the fractional width of the plot with respect to the width of the display (or virtual display, in the case of a multiplot) to be WIDTH. A value of 1.0 will produce a plotting box that fills the available area. Note that the tick marks and labels are outside the plotting box, so values less than 1.0 are generally used. `-x [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]' `--x-limits [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]' (Floats.) The arguments LOWER_LIMIT and UPPER_LIMIT specify the limits of the x axis, and the optional argument SPACING specifies the spacing of labeled ticks along the axis. If any of the three arguments is missing or is supplied as `-' (i.e., as a single hyphen), it is computed from the data. Both arguments LOWER_LIMIT and UPPER_LIMIT must be present if `graph' is to act as a real-time filter. By default, the supplied limit(s) are strictly respected. However, the `-R x' option may be used to request that they be rounded to the nearest integer multiple of the spacing between labeled ticks. The lower limit will be rounded downward, and the upper limit upward. `-X X_LABEL' `--x-label X_LABEL' (String, default empty.) Set the label for the x axis to be the text string X_LABEL. The string may include escape sequences (*note Text String Format::.). The `-F' and `-f' options may be used to specify the name of the font and the size of the font. `-y [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]' `--y-limits [LOWER_LIMIT [UPPER_LIMIT [SPACING]]]' (Floats.) The arguments specify the limits of the y axis, and the spacing of labeled ticks along it, as for the x axis (see above). Both arguments LOWER_LIMIT and UPPER_LIMIT must be present if `graph' is to act as a real-time filter. By default, the supplied limit(s) are strictly respected. However, the `-R y' option may be used to request that they be rounded to the nearest multiple of the tick spacing. The lower limit will be rounded downward, and the upper limit upward. `-Y Y_LABEL' `--y-label Y_LABEL' (String, default empty.) Set the label for the y axis to be the text string Y_LABEL. The string may include escape sequences (*note Text String Format::.). The label will be rotated by 90 degrees so that it is parallel to the axis, unless the `--toggle-rotate-y-label' option is used. Some old X Window System displays do not support rotated labels, and require the `--toggle-rotate-y-label' option. The `-F' and `-f' options can be used to specify the name of the font and the size of the font. `--bg-color NAME' (String, default "white".) Set the color used for the plot background to be NAME. This is relevant only to `graph -T X', `graph -T pnm', and `graph -T gif'. An unrecognized name sets the color to the default. For information on what names are recognized, see *Note Color Names::. 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. *Note graph Environment::. `--bitmap-size BITMAP_SIZE' (String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be BITMAP_SIZE. This is relevant only to `graph -T X', `graph -T pnm', and `graph -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 `graph -T X' is an X window. If you choose a rectangular (non-square) window size, the fonts in the plot 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'. `--frame-color NAME' (String, default "black".) Set the color used for drawing the plot frame, and for drawing monochrome datasets (if any) to be NAME. An unrecognized name sets the color to the default. For information on what names are recognized, see *Note Color Names::. `--frame-line-width FRAME_LINE_WIDTH' (Float, default -1.0.) Set the thickness of lines in the plot frame, as a fraction of the size (i.e., minimum dimension) of the graphics display, to FRAME_LINE_WIDTH. A negative value means that the default value for the line thickness provided by the `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. `graph -T tek' does not support drawing lines with other than a default thickness, and `graph -T hpgl' does not support doing so if the environment variable `HPGL_VERSION' is set to a value less than "2" (the default). `--max-line-length MAX_LINE_LENGTH' (Integer, default 500.) Set the maximum number of points that a polygonal line drawn through any dataset may contain, before it is flushed to the display device, to equal MAX_LINE_LENGTH. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. Splitting will not take place if the `-q' option, which requests filling, is used. The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable `MAX_LINE_LENGTH' can also be used to specify the maximum line length. This option has no effect on `graph -T tek' or raw `graph', since they draw polylines in real time and have no buffer limitations. `--page-size PAGESIZE' (String, default "letter".) Set the size of the page on which the plot will be positioned. This is relevant only to `graph -T ai', `graph -T ps', `graph -T fig', `graph -T pcl', and `graph -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 `graph -T ai' and `graph -T ps', the graphics display within which the plot is drawn will be a square region centered on the specified page, occupying its full width (with allowance being made for margins). For `graph -T fig', it will be a square region of the same size, located in the upper left corner of an `xfig' display. For `graph -T pcl' and `graph -T hpgl', the graphics display will be a square region of the same size, but may be positioned differently. Fine control over its positioning on the page can be accomplished by setting certain environment variables (*note graph Environment::.). `--pen-colors COLORS' (String, default "1=red:2=green:3=blue:4=magenta:5=cyan".) Set the colors of the pens used for drawing plots, as numbered, to be COLORS. The format should be self-explanatory. An unrecognized name sets the corresponding color to the default. For information on what names are recognized, see *Note Color Names::. `--rotation ANGLE' (Integer, default 0.) Set the rotation angle of the plot within the graphics display to be ANGLE degrees. Recognized values are 0, 90, 180, and 270. The rotation is counterclockwise. This option is used for switching between portrait mode and landscape mode. Postmodernists may also find it useful. `--title-font-name FONT_NAME' (String, default "Helvetica" except for `graph -T pnm', `graph -T gif', `graph -T pcl', `graph -T hpgl' and `graph -T tek', for which "HersheySerif" is the default.) Set the font used for the plot title to be FONT_NAME. Normally the font used for the plot title is the same as that used for labeling the axes and the ticks along the axes, as specified by the `-F' option. But the `--title-font-name' option can be used to override this. 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 *Note Text Fonts::. The `plotfont' utility will produce a character map of any available font. *Note plotfont::. `--title-font-size SIZE' (Float, default 0.07.) Set the size of the font used for the top label (`title'), as specified by the `-L' option, to be SIZE. The size is specified as a fraction of the minimum dimension (width or height) of the plotting box. `--toggle-rotate-y-label' Position the label on the y axis (which is set with the `-Y' option) horizontally instead of vertically, or vice versa. By default the label is rotated, so that it is parallel to the y axis. But some display devices (e.g., old X Window System displays) cannot handle rotated fonts. Dataset options --------------- The following options affect the way in which individual datasets are read from files, and drawn as part of a plot. They should appear on the command line before the file containing the datasets whose reading or rendering they will affect. They may appear more than once on a command line, if more than one file is to be read. The following three options affect the way in which datasets are read from files. `-I DATA-FORMAT' `--input-format DATA-FORMAT' This specifies which format the subsequent input file(s) are in. `a' ASCII format. Each input file is a sequence of floating point numbers, interpreted as the x and y coordinates of the successive data points in a dataset. The x and y coordinates of a point need not appear on the same line, and points need not appear on different lines. But if a blank line occurs (i.e., two newlines in succession are seen), it is interpreted as the end of a dataset, and the beginning of the next. `e' ASCII format, including error bars. Similar to `a' format, except that triples (x,y,error) appear instead of pairs (x,y). `g' The ASCII `table' format produced by the `gnuplot' plotting program. `f' Single precision binary format. Each input file is a sequence of single precision floating point numbers, interpreted as forming pairs (x,y). Successive datasets are separated by a single occurrence of the quantity `FLT_MAX', which is the largest possible single precision floating point number. On most machines this is approximately 3.4x10^38. `d' Double precision binary format. Each input file is a sequence of double precision floating point numbers, interpreted as forming pairs (x,y). Successive datasets are separated by a single occurrence of the quantity `DBL_MAX', which is the largest possible double precision floating point number. On most machines this is approximately 1.8x10^308. `i' Integer binary format. Each input file is a sequence of integers, interpreted as forming pairs (x,y). Successive datasets are separated by a single occurrence of the quantity `INT_MAX', which is the largest possible integer. On most machines this is 2^31-1. `-a [STEP_SIZE [LOWER_LIMIT]]' `--auto-abscissa [STEP_SIZE [LOWER_LIMIT]]' (Floats, defaults 1.0 and 0.0.) Automatically generate abscissa (x) values. Irrespective of data format (`a', `e', `f', `d', or `i'), this option specifies that the abscissa (x) values are missing from the input file: the dataset(s) to be read contain only ordinate (y) values. The increment from each x value to the next will be STEP_SIZE, and the first x value will be LOWER_LIMIT. To return to reading abscissa values from the input, i.e., for subsequent input files, you would use `-a 0', which disables automatic generation of the abscissa values and returns STEP_SIZE and LOWER_LIMIT to their default values. `-B' `--toggle-auto-bump' By default the linemode (set with `-m', see below) is `bumped' (incremented by unity) at the beginning of each new dataset. This option toggles auto-bumping: it turns it off if it was on, and on if it was off. The following options affect the way in which individual datasets are drawn as part of a plot. These options set the six `attributes' (symbol type, symbol font, linemode, line thickness, fill fraction, and color/monochrome) that each dataset has. `-m LINE_MODE' `--line-mode LINE_MODE' (Integer, default 1.) LINE_MODE specifies the mode (i.e., style) of the lines drawn between successive points in a dataset. By convention, linemode #0 means no line at all (points are disconnected). If the dataset is being rendered in monochrome, the interpretation of LINE_MODE is as follows. 1. solid 2. dotted 3. dotdashed 4. shortdashed 5. longdashed Thereafter (i.e., for LINE_MODE greater than 5) the sequence of five linemodes repeats. So besides linemode #0, there are a total of five distinct monochrome linemodes. If the dataset is being rendered in color (as may be requested with the `-C' option), the interpretation of linemodes #1 through #5 is instead 1. red, solid 2. green, solid 3. blue, solid 4. magenta, solid 5. cyan, solid Linemodes #6 through #10 use the same five colors, but are dotted; linemodes #11 through #15 are dotdashed; linemodes #16 through #20 are shortdashed; and linemodes #21 through #25 are longdashed. So besides linemode #0, there are a total of 25 distinct colored linemodes. A negative linemode indicates that no line should be drawn, but that the plotting symbol, if any (see below), should be in the color of the corresponding positive linemode. `-S [SYMBOL_NUMBER [SYMBOL_SIZE]]' `--symbol [SYMBOL_NUMBER [SYMBOL_SIZE]]' (Integer and float, defaults 0 and 0.03.) Draw a marker symbol at each data point. SYMBOL_NUMBER specifies the symbol type, and SYMBOL_SIZE specifies the font size of the symbol, as a fraction of the minimum dimension (width or height) of the plotting box. If the dataset is being rendered in color, the symbol will have the color of the line that is being drawn to connect the data points. You may request that symbols be drawn without any line connecting them by using the `-m' option to specify a negative linemode (see above). The following table lists the first few marker symbols (by convention, symbol #0 means no symbol at all). 1. dot 2. plus (+) 3. asterisk (*) 4. circle 5. cross Marker symbols 0 through 31 are furnished by the `libplot' graphics library. *Note Marker Symbols::. Symbol numbers greater than or equal to 32 are interpreted as characters to be selected from a symbol font, which can be set with the `--symbol-font-name' option (see below). `-W LINE_WIDTH' `--line-width LINE_WIDTH' (Float, default -1.0.) Set the thickness of the lines used to join successive points in a dataset, as a fraction of the size (i.e., minimum dimension) of the graphics display, to LINE_WIDTH. A negative value means that the default value for the line thickness provided by the `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. `graph -T tek' does not support drawing lines with other than a default thickness, and `graph -T hpgl' does not support doing so if the environment variable `HPGL_VERSION' is set to a value less than "2" (the default). `-q FILL_FRACTION' `--fill-fraction FILL_FRACTION' (Float, default -1.0.) If successive points in a dataset are joined by line segments, set the shading intensity for the polygon formed by the line segments to be FILL_FRACTION. A solid polygon (i.e., one filled with the `pen color' used for drawing the line segments) is obtained by choosing FILL_FRACTION=1.0. The interior of the polygon will be white if FILL_FRACTION=0.0. The polygon will be unfilled (transparent) if FILL_FRACTION is negative. If the polygon intersects itself, the `even-odd fill rule' will normally be used to determine which points are inside rather than outside, i.e., to determine which portions of the polygon should be shaded. The even-odd fill rule is explained in the `Postscript Language Reference Manual'. The `-q' option has no effect in `graph -T tek', and it is only partly effective in `graph -T hpgl' if the environment variable `HPGL_VERSION' is set to "1". `-C' `--toggle-use-color' Toggle between color and monochrome rendering of datasets. The interpretation of linemode depends on whether the rendering is being performed in color or monochrome; see the `-m' option above. `--symbol-font-name SYMBOL_FONT_NAME' (String, default "ZapfDingbats" unless `-T pnm', `-T gif', `-T pcl', `-T hpgl', or `-T tek' is specified, in which case it is "HersheySerif".) Set the symbol font, from which plotting symbols numbered 32 and higher are selected, to be SYMBOL_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 example, if the `-T pcl' or `-T hpgl' option is used then normally the Wingdings font, which is an alternative source of symbols, becomes available. For a list of all fonts, see *Note Text Fonts::. The `plotfont' utility will produce a character map of any available font. *Note plotfont::. Multiplot options ----------------- The following options are used for multiplotting (placing several plots on a display, or a page, at once). `--reposition X Y SIZE' (Floats, defaults 0.0, 0.0, 1.0) Set the `virtual display' within which the next plot will be drawn to be a square of size SIZE, with lower left corner (X,Y). Normalized coordinates are used here: (0,0) means the lower left corner of the physical display and (1,1) means the upper right corner of the physical display. The size of the plot within the virtual display may be adjusted with the `-h' and `-w' options, and its position within the virtual display with the `-u' and `-w' options. After a `--reposition' command, the arguments of those four options will be interpreted in terms of the virtual display, not the physical display. `--blankout BLANKOUT_FRACTION' (Float, default 1.3.) When drawing each additional plot of a multiplot, it is desirable to clear the region of the display on which the plot will be drawn. If BLANKOUT_FRACTION=1.0, the region covered by the plot's plotting box will be cleared. If BLANKOUT_FRACTION=1.3, a region 30% larger in each dimension will be cleared. This is appropriate for inset plots; 1.0 would be appropriate for side by side plots. Note that `graph -T tek' cannot clear regions, and `graph -T hpgl' cannot clear them if the environment variables `HPGL_VERSION' and `HPGL_OPAQUE_MODE' are set to non-default values (i.e., values other than "2" and "yes", respectively). Raw `graph' options ------------------- The following option is relevant only to raw `graph', i.e., is relevant only if no display type or output format is specified with the `-T' option. In this case `graph' outputs a graphics metafile, which may be translated to other formats by invoking `plot'. This option should appear on the command line before any file names, since it affects the output of the plot (or multiplot) as a whole. `-O' `--portable-output' Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default). This can also be requested by setting the environment variable `META_PORTABLE' to "yes". Informational options --------------------- The following options request information. `--help' Print a list of command-line options, and then exit. `--help-fonts' Print a table of available fonts, and then exit. The table will depend on which display type or output format is specified with the `-T' option. `graph -T X', `graph -T ai', `graph -T ps', and `graph -T fig' each support the 35 standard Postscript fonts. `graph -T ai', `graph -T pcl', and `graph -T hpgl' support the 45 standard PCL 5 fonts, and `graph -T pcl' and `graph -T hpgl' support a number of Hewlett-Packard vector fonts. All of the preceding, together with `graph -T pnm', `graph -T gif', and `graph -T tek', support a set of 22 Hershey vector fonts. Raw `graph' 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. *Note plotfont::. `--list-fonts' Like `--help-fonts', but lists the fonts in a single column to facilitate piping to other programs. If no display type or output format is specified with the `-T' option, the full set of supported fonts is listed. `--version' Print the version number of `graph' and the plotting utilities package, and exit. Environment variables ===================== The behavior of `graph' 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. `graph -T X', which pops up a window on an X Window System display and draws graphics in it, checks the `DISPLAY' environment variable. The value of this variable determines the display on which the window will be popped up. `graph -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. `graph -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 *Note Color Names::. `graph -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". This is not the same as the rotation obtained with the `--rotation' option, which sets the rotation angle of the plot within the display. Besides "no" and "yes", recognized values for the `PCL_ROTATE' 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. `graph -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 (the `-q' option may be used to fill circles and rectangles aligned with the coordinate axes, though). The position of the `graph -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". This is not the same as the rotation obtained with the `--rotation' option, which sets the rotation angle of the plot within the display. Besides "no" and "yes", recognized values for the `HPGL_ROTATE' 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, `graph -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 *Note Color Names::. 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 `graph -T hpgl' will also be affected by the environment variable `HPGL_ASSIGN_COLORS'. If the value of this variable is "yes", then `graph -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. `graph -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, `graph -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, `graph -T tek' will emit an escape sequence that switches the terminal emulator to Tektronix mode. Also, some of the Tektronix control codes emitted by `graph -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, `graph -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. The `plot' Program ****************** How to use `plot' ================= The GNU plot filter `plot' displays GNU graphics metafiles or translates them to other formats. It will take input from files specified on the command line or from standard input. The `-T' option is used to specify the desired output format. Supported output formats include "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta" (the default). The metafile format is a device-independent format for storage of vector graphics. By default, it is a binary rather than a human-readable format (*note Metafiles::.). Each of the `graph', `pic2plot', `tek2plot', and `plotfont' utilities will write a graphics metafile to standard output if no `-T' option is specified on its command line. The `libplot' graphics library may also be used to produce metafiles. Metafiles may contain arbitrarily many pages of graphics, but each metafile produced by `graph' contains only a single page. `plot', like the metafile format itself, is useful if you wish to preserve a vector graphics file, and display or edit it with more than one drawing editor. The following example shows how you may do this. To produce a plot of data arranged as alternating x and y coordinates in an ASCII file, you may use `graph' as follows: graph < ascii_data_file > test.meta The file `test.meta' will be a single-page graphics metafile. Similarly, to create in metafile format a plot consisting of a simple figure, you may do: echo 0 0 1 1 2 0 | spline | graph > test.meta To display any such plot on an X Window System display, you would do plot -T X test.meta or plot -T X < test.meta To print the plot on a Postscript printer, you would do something like plot -T ps < test.meta | lpr To edit it with the free `idraw' drawing editor, you would do plot -T ps < test.meta > test.ps idraw test.ps To produce a "portable anymap" (a file in PBM, PGM, or PPM format, whichever is most appropriate) you would do plot -T pnm < test.meta > test.pnm and to produce a pseudo-GIF file, you would do plot -T gif < test.meta > test.gif Similarly, to produce a version of the plot that can be edited with Adobe Illustrator, you would do plot -T ai < test.meta > test.ai and to produce a version that can be edited with the free `xfig' drawing editor, you would do plot -T fig < test.meta > test.fig xfig test.fig Other formats may be obtained by using `plot -T pcl', `plot -T hpgl', and `plot -T tek'. `plot' may behave differently depending on the environment in which it is invoked. In particular, `plot -T ai', `plot -T ps', `plot -T fig', `plot -T pcl', and `plot -T hpgl' are affected by the environment variable `PAGESIZE'. `plot -T X', `plot -T pnm', and `plot -T gif' are affected by the environment variable `BITMAPSIZE'. The `DISPLAY' environment variable affects the operation of `plot -T X', and the `TERM' environment variable affects the operation of `plot -T tek'. There are also several environment variables that affect the operation of `plot -T pcl' and `plot -T hpgl'. For a complete discussion of the effects of the environment on `plot', see *Note plot Environment::. `plot' command-line options =========================== The plot filter `plot' translates GNU graphics metafiles to other formats. The `-T' option is used to specify the output format or display type. Files in metafile format are produced by GNU `graph', `pic2plot', `tek2plot', `plotfont', and other applications that use the GNU `libplot' graphics library. For technical details on the metafile format, see *Note Metafiles::. 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 a window or 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 four sorts of option: 1. Options setting the values of drawing parameters. 2. Options relevant only to raw `plot', i.e., relevant only if no display type or output format is specified with the `-T' option. 3. Options specifying the type of metafile format the input is in (for backward compatibility only). 4. Options requesting information (e.g., `--help'). Each option that takes an argument is followed, in parentheses, by the type and default value of the argument. The following options set the values of drawing parameters. `-T TYPE' `--display-type TYPE' (String, default "meta".) Select a display type or output format of type TYPE, which may be one of the strings "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta". These refer respectively to the X Window System, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the format used by Adobe Illustrator, `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. `-p N' `--page-number N' (Positive integer.) Display only page number N, within the metafile or sequence of metafiles that is being translated. Metafiles may consist of one or more pages, numbered beginning with 1. Also, each page may contain multiple `frames'. `plot -T X' or `plot -T tek', which plot in real time, will separate successive frames by screen erasures. `plot -T pnm', `plot -T gif', `plot -T ai', `plot -T ps', `plot -T fig', `plot -T pcl', and `plot -T hpgl', which do not plot in real time, will display only the last frame of any multi-frame page. The default behavior, if `-p' is not used, is to display all pages. For example, `plot -T X' displays each page in its own X window. If the `-T pnm' option, the `-T gif' option, the `-T ai' option, or the `-T fig' option is used, the default behavior is to display only the first page, since files in PNM, pseudo-GIF, AI, or Fig format may contain only a single page of graphics. Most metafiles produced by the GNU plotting utilities (e.g., by raw `graph') contain only a single page, consisting of two frames: an empty one to clear the display, and a second one containing graphics. `-s' `--merge-pages' Merge all displayed pages into a single page, and also merge all `frames' within each displayed page. This option is useful when merging together single-page plots from different sources. For example, it can be used to merge together plots obtained from separate invocations of `graph'. This is an alternative form of multiplotting (*note Multiplotting::.). `--bitmap-size BITMAP_SIZE' (String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be BITMAP_SIZE. This is relevant only to `plot -T X', `plot -T pnm', and `plot -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. 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 MAX_LINE_LENGTH' (Integer, default 500.) Set the maximum number of points that a polygonal line may contain, before it is flushed to the display device, to equal MAX_LINE_LENGTH. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. Splitting will not take place if the line is the boundary of a filled polygon. The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable `MAX_LINE_LENGTH' can also be used to specify the maximum line length. This option has no effect on `plot -T tek' or raw `plot', since they draw polylines in real time and have no buffer limitations. `--page-size PAGESIZE' (String, default "letter".) Set the size of the page on which the plot will be positioned. This is relevant only to `plot -T ai', `plot -T ps', `plot -T fig', `plot -T pcl', and `plot -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 `plot -T ai' and `plot -T ps', the graphics display within which the plot is drawn will be a square region centered on the specified page, occupying its full width (with allowance being made for margins). For `plot -T fig', it will be a square region located of the same size, located in the upper left corner of an `xfig' display. For `plot -T pcl' and `plot -T hpgl', the graphics display will be a square region of the same size, but may be positioned differently. Fine control over its positioning on the page may be accomplished by setting certain environment variables (*note plot Environment::.). The following options set the initial values of additional drawing parameters. All of these may be overridden by directives in the metafile itself. In fact, these options are useful mostly for plotting old metafiles in the pre-GNU `plot(5)' format, which did not include such directives. `--bg-color NAME' (String, default "white".) Set the color used for the plot background to be NAME. This is relevant only to `plot -T X', `plot -T pnm', and `plot -T gif'. An unrecognized name sets the color to the default. For information on what names are recognized, see *Note Color Names::. 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. *Note plot Environment::. `-f FONT_SIZE' `--font-size FONT_SIZE' (Float, initial value device-dependent.) Set the initial size of the font used for rendering text, as a fraction of the width of the graphics display, to FONT_SIZE. `-F FONT_NAME' `--font-name FONT_NAME' (String, default "Helvetica" except for `plot -T pnm', `plot -T gif', `plot -T pcl', `plot -T hpgl', `plot -T tek', and raw `plot', for all of which "HersheySerif" is the default.) Set the font initially used for text (i.e., for `labels') 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 *Note Text Fonts::. The `plotfont' utility will produce a character map of any available font. *Note plotfont::. `-W LINE_WIDTH' `--line-width LINE_WIDTH' (Float, default -1.0.) Set the thickness of lines, as a fraction of the size (i.e., minimum dimension) of the graphics display, to LINE_WIDTH. A negative value means that the default value provided by the `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. `plot -T tek' does not support drawing lines with other than a default thickness, and `plot -T hpgl' does not support doing so if the environment variable `HPGL_VERSION' is set to a value less than "2" (the default). `--pen-color NAME' (String, default "black".) Set the pen color to be NAME. An unrecognized name sets the pen color to the default. For information on what color names are recognized, see *Note Color Names::. The following option is relevant only to raw `plot', i.e., relevant only if no output type is specified with the `-T' option. In this case `plot' outputs a graphics metafile, which may be translated to other formats by a second invocation of `plot'. `-O' `--portable-output' Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default). This can also be requested by setting the environment variable `META_PORTABLE' to "yes". `plot' will automatically determine which type of GNU metafile format the input is in. There are two types: binary (the default) and portable (human-readable). The binary format is machine-dependent. *Note Metafiles::. For compatibility with older plotting software, the reading of input files in the pre-GNU `plot(5)' format is also supported. This is normally a binary format, with each integer in the metafile represented as a pair of bytes. The order of the two bytes is machine dependent. You may specify that input file(s) are in plot(5) format rather than ordinary GNU metafile format by using either the `-h' option ("high byte first") or the `-l' option ("low byte first"), whichever is appropriate. Some non-GNU systems support an ASCII (human-readable) variant of plot(5) format. You may specify that the input is in this format by using the `-A' option. Irrespective of the variant, a file in plot(5) format includes only one page of graphics. `-h' `--high-byte-first-input' Input file(s) are assumed to be in traditional `plot(5)' metafile format, with the high-order byte of each integer occurring first. `-l' `--low-byte-first-input' Input file(s) are assumed to be in traditional `plot(5)' metafile format, with the low-order byte of each integer occurring first. `-A' `--ascii-input' Input file(s) are assumed to be in the ASCII variant of traditional `plot(5)' metafile format. The following options request information. `--help' Print a list of command-line options, and then exit. `--help-fonts' Print a table of available fonts, and then exit. The table will depend on which display type or output format is specified with the `-T' option. `plot -T X', `plot -T ai', `plot -T ps', and `plot -T fig' each support the 35 standard Postscript fonts. `plot -T ai', `plot -T pcl', and `plot -T hpgl' support the 45 standard PCL 5 fonts, and `plot -T pcl' and `plot -T hpgl' support a number of Hewlett-Packard vector fonts. All of the preceding, together with `plot -T pnm', `plot -T gif', and `plot -T tek', support a set of 22 Hershey vector fonts. Raw `plot' 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. *Note plotfont::. `--list-fonts' Like `--help-fonts', but lists the fonts in a single column to facilitate piping to other programs. If no display type or output format is specified with the `-T' option, the full set of supported fonts is listed. `--version' Print the version number of `plot' and the plotting utilities package, and exit. Environment variables ===================== The behavior of `plot' 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. `plot -T X', which pops up a window on an X Window System display and draws graphics in it, checks the `DISPLAY' environment variable. The value of this variable determines the display on which the window will be popped up. `plot -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. `plot -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 *Note Color Names::. `plot -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. `plot -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 `plot -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, `plot -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 *Note Color Names::. 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 `plot -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. `plot -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, `plot -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, `plot -T tek' will emit an escape sequence that switches the terminal emulator to Tektronix mode. Also, some of the Tektronix control codes emitted by `plot -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, `plot -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. The `pic2plot' Program ********************** 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. *Note 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. 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: 1. General options. 2. Options relevant only to raw `pic2plot', i.e., relevant only if no display type or output format is specified with the `-T' option. 3. Options requesting information (e.g., `--help'). Each option that takes an argument is followed, in parentheses, by the type and default value of the argument. The following are general options. `-T TYPE' `--display-type TYPE' (String, default "meta".) Select a display type or output format of type TYPE, which may be one of the strings "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta". These refer respectively to the X Window System, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the format used by Adobe Illustrator, `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. `-d' `--precision-dashing' Draw dashed and dotted lines carefully, i.e., draw each dash and dot as a separate object, so that they may be positioned individually. The default is to use the support for dashed and dotted lines provided by the underlying graphics library, `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. `-f FONT_SIZE' `--font-size FONT_SIZE' (Float, default 0.0175.) Set the size of the font used for rendering text, as a fraction of the width of the graphics display, to FONT_SIZE. `-F FONT_NAME' `--font-name FONT_NAME' (String, default "Helvetica" except for `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 *Note Text Fonts::. The `plotfont' utility will produce a character map of any available font. *Note plotfont::. `-n' `--no-centering' Turn off the automatic centering of each figure. If this option is specified, the position of the objects in each figure may be specified in terms of absolute coordinates. E.g., "line from (0,0) to (4,4)" will draw a line segment from the lower left corner to the center of the graphics display, since the display width and display height are defined to equal 8 virtual inches. `-W LINE_WIDTH' `--line-width LINE_WIDTH' (Float, default -1.0.) Set the default thickness of lines, as a fraction of the size (i.e., minimum dimension) of the graphics display, to LINE_WIDTH. A negative value means that the default value provided by the `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). `--bg-color NAME' (String, default "white".) Set the color used for the background to be NAME. This is relevant only to `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 *Note Color Names::. 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. *Note pic2plot Environment::. `--bitmap-size BITMAP_SIZE' (String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be BITMAP_SIZE. This is relevant only to `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 MAX_LINE_LENGTH' (Integer, default 500.) Set the maximum number of points that a polygonal line may contain, before it is flushed to the display device, to equal MAX_LINE_LENGTH. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable `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. `--page-size PAGESIZE' (String, default "letter".) Set the size of the page on which each figure will be positioned. This is relevant only to `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 (*note pic2plot Environment::.). `--pen-color NAME' (String, default "black".) Set the pen color to be NAME. An unrecognized name sets the pen color to the default. For information on what color names are recognized, see *Note Color Names::. `--rotation ANGLE' (Integer, default 0.) Set the rotation angle of each figure within the graphics display to be ANGLE degrees. Recognized values are 0, 90, 180, and 270. The rotation is counterclockwise. This option is used for switching between portrait mode and landscape mode. Postmodernists may also find it useful. 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'. `-O' `--portable-output' Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default). This can also be requested by setting the environment variable `META_PORTABLE' to "yes". The following options request information. `--help' Print a list of command-line options, and then exit. `--help-fonts' Print a table of available fonts, and then exit. The table will depend on which display type or output format is specified with the `-T' option. `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. *Note plotfont::. `--list-fonts' Like `--help-fonts', but lists the fonts in a single column to facilitate piping to other programs. If no display type or output format is specified with the `-T' option, the full set of supported fonts is listed. `--version' Print the version number of `pic2plot' and the plotting utilities package, and exit. Environment variables ===================== 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 *Note Color Names::. `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 *Note Color Names::. 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. The `tek2plot' Program ********************** What `tek2plot' is used for =========================== GNU `tek2plot' is a command-line Tektronix translator. It displays Tektronix graphics files, or translates them to other formats. The `-T' option is used to specify the output format or display type. Supported output formats include "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta" (the default). These are the same formats that are supported by the GNU `graph', `plot', and `pic2plot' programs. `tek2plot' will take input from a file specified on the command line or from standard input, just as the plot filter `plot' does. Tektronix graphics files are produced by many older applications, such as SKYMAP (http://tdc-www.harvard.edu/software/skymap), a powerful astronomical display program. A directory containing sample Tektronix graphics files, which you may experiment with, is distributed along with the GNU plotting utilities. On most systems it is installed as `/usr/share/tek2plot' or `/usr/local/share/tek2plot'. Tektronix graphics format is defined as a noninteractive version of the graphics format understood by Tektronix 4010/4014 terminals, as documented in the `4014 Service Manual', Tektronix Inc., 1974 (Tektronix Part #070-1648-00). `tek2plot' does not support interactive features such as graphics input mode ("GIN mode") or status enquiry. However, it does support a few additional features provided by popular Tektronix emulators, such as the color extensions supported by the Tektronix emulator contained in the MS-DOS version of `kermit'. `tek2plot' command-line options =============================== The `tek2plot' program translates the Tektronix graphics files produced by many older applications to other 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', `plot', and `pic2plot' 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: 1. General options. 2. Options relevant only to raw `tek2plot', i.e., relevant only if no display type or output format is specified with the `-T' option. 3. Options requesting information (e.g., `--help'). Each option that takes an argument is followed, in parentheses, by the type and default value of the argument. The following are general options. `-T TYPE' `--display-type TYPE' (String, default "meta".) Select a display type or output format of type TYPE, which may be one of the strings "X", "pnm", "gif", "ai", "ps", "fig", "pcl", "hpgl", "tek", and "meta". These refer respectively to the X Wind