The Plotutils Package - plot Invocation

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

## `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 section The Graphics Metafile Format.

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 (see section Multiplotting: placing multiple plots on a single page).
``--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 (see section Environment variables).

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 section Specifying Colors by Name. The environment variable `BG_COLOR` can equally well be used to specify the background color. If the ``-T gif'` option is used, a transparent pseudo-GIF may be produced by setting the `TRANSPARENT_COLOR` environment variable to the name of the background color. See section Environment variables.
``-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 section Available text fonts. The `plotfont` utility will produce a character map of any available font. See section The `plotfont` Utility.
``-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 section Specifying Colors by Name.

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. See section The Graphics Metafile Format.

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. See section The `plotfont` Utility.
``--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.

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