The Plotutils Package - pic2plot Invocation

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

## `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 section Available text fonts. The `plotfont` utility will produce a character map of any available font. See section The `plotfont` Utility.
``-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 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.
``--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 (see section Environment variables).
``--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.
``--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. 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 `pic2plot` and the plotting utilities package, and exit.

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