Provided by: plotutils_2.6-11_amd64 bug

NAME

       plot - translate GNU metafiles to other graphics formats

SYNOPSIS

       plot [ options ] [ files ]

DESCRIPTION

       plot  translates  files in GNU metafile format to other graphics formats, or displays them
       on an X Window System display.  GNU metafile format is a device-independent format for the
       storage  of  graphic  data.   It  is  the  default output format of the programs graph(1),
       pic2plot(1), tek2plot(1), and plotfont(1), and is further documented in plot(5), since  it
       is an enhanced version of the traditional plot(5) format found on non-GNU systems.  It can
       also be produced by the GNU libplot 2-D graphics export library (see plot(3)).

       The output format is specified with the  -T  option.   The  possible  output  formats  and
       display  types  are the same as those supported by graph(1), plotfont(1), pic2plot(1), and
       tek2plot(1).  If an output file is produced, it is written to standard output.

       Options and file names may be interspersed on  the  command  line,  but  the  options  are
       processed  before the file names are read.  If -- is seen, it is interpreted as the end of
       the options.  If no file names are specified, or the  file  name  -  is  encountered,  the
       standard input is read.

OPTIONS

   General Options
       -T type
       --output-format type
              Select type as the output format.  It may be "X", "png", "pnm", "gif", "svg", "ai",
              "ps", "cgm", "fig", "pcl", "hpgl", "regis", "tek", or "meta" (the default).   These
              refer  respectively to the X Window System, PNG (Portable Network Graphics) format,
              portable anymap format (PBM/PGM/PPM), a pseudo-GIF format that  does  not  use  LZW
              encoding,  the  new  XML-based  Scalable Vector Graphics format, the format used by
              Adobe Illustrator, Postscript or Encapsulated Postscript (EPS) that can  be  edited
              with  idraw(1),  CGM  format  (by  default,  confirming to the WebCGM profile), the
              format used by the xfig(1)  drawing  editor,  the  Hewlett-Packard  PCL  5  printer
              language,  the  Hewlett-Packard Graphics Language, ReGIS graphics format (which can
              be displayed by the dxterm(1) terminal emulator or by a VT330 or  VT340  terminal),
              Tektronix  format  (which  can be displayed by the xterm(1) terminal emulator), and
              device-independent GNU metafile format itself.  Unless type is "X", an output  file
              is produced and written to standard output.

              Omitting  the  -T  option  is  equivalent  to specifying -T meta.  Translating from
              metafile format to itself is occasionally useful, since there are two  versions  of
              metafile format (see the -O option below).

              A  listing  of  the  fonts available in any specified output format may be obtained
              with the --help-fonts option (see below).  If a requested font  is  unavailable,  a
              default  font will be substituted.  The default font is "Helvetica" for "X", "svg",
              "ai", "ps", "cgm", and "fig", "Univers" for "pcl", and  "HersheySerif"  for  "png",
              "pnm", "gif", "hpgl", "regis", "tek", and "meta".

       -p n
       --page-number n
              Output  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, plot -T regis, and plot -T tek,
              which plot in real time, will separate successive frames by screen erasures.   plot
              -T png, plot -T pnm, plot -T gif, plot -T svg, plot -T ai, plot -T ps, plot -T cgm,
              plot -T fig, plot -T pcl, and plot -T hpgl, which do not plot in  real  time,  will
              output only the last frame of any multi-frame page.

              The default behavior, if -p is not used, is to output all pages.  For example, plot
              -T X displays each page in its own X window.  If the -T png, -T pnm, -T gif, -T ai,
              or -T fig option is used, the default behavior is to output only the first nonempty
              page, since files in those output formats contain only a single page of graphics.

              Metafiles produced by graph(1) and plotfont(1) contain only  a  single  page  (page
              #1),  which  consists  of  two  frames:  an empty frame to clear the display, and a
              second frame that contains the graphics.

       -s
       --merge-pages
              Merge all displayed pages into a single page, and also merge all `frames'.

              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(1).

       --bitmap-size bitmap_size
              Set the size of the graphics display in which the plot will be drawn, in  terms  of
              pixels,  to  be  bitmap_size.   The default is "570x570".  This is relevant only to
              plot -T X, plot -T png, plot -T pnm, and plot -T gif, all of which produce bitmaps.
              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
              directions.   For  plot -T X, 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
              vector font "HersheySerif".

              The  environment variable BITMAPSIZE can equally well be used to specify the window
              size.  For backward compatibility,  the  X  resource  Xplot.geometry  may  be  used
              instead.

       --emulate-color option
              If option is yes, replace each color in the output by an appropriate shade of gray.
              This is seldom useful, except when using plot -T pcl to prepare output for a PCL  5
              device.   (Many  monochrome  PCL 5 devices, such as monochrome LaserJets, do a poor
              job of emulating color on their own.)  You may equally well request color emulation
              by setting the environment variable EMULATE_COLOR to "yes".

       --max-line-length max_line_length
              Set  the  maximum  number of points that a polygonal line may contain, before it is
              flushed out, to be 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 default value of max_line_length is 500.

              The reason for splitting long polygonal lines is that some display  devices  (e.g.,
              old  Postscript  printers  and  pen HP-GL plotters) have limited buffer sizes.  The
              environment variable MAX_LINE_LENGTH can also be used to specify the  maximum  line
              length.

       --page-size pagesize
              Set  the  size  of the page on which the plot will be positioned.  This is relevant
              only to plot -T svg, plot -T ai, plot -T ps, plot -T cgm, plot -T fig, plot -T pcl,
              and  plot  -T  hpgl.   The  default is "letter", which means an 8.5 inch by 11 inch
              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" and "ledger" are recognized page sizes  also.   The  environment
              variable PAGESIZE can equally well be used to specify the page size.

              The  graphics  display  in  which  the  plot is drawn will, by default, be a square
              region that occupies nearly the full width of the specified page.   An  alternative
              size  for  the graphics display can be specified.  For example, the page size could
              be specified as "letter,xsize=4in,ysize=6in", or "a4,xsize=5.0cm,ysize=100mm".  For
              all  of  the  above  except plot -T hpgl, the graphics display will, by default, be
              centered on the page.  For all of the above except plot -T svg and plot -T cgm, the
              graphics  display  may  be repositioned manually, by specifying the location of its
              lower left corner, relative to the lower left corner of the page.  For example, the
              page    size   could   be   specified   as   "letter,xorigin=2in,yorigin=3in",   or
              "a4,xorigin=0.5cm,yorigin=0.5cm".  It is also possible to specify an offset vector.
              For  example,  the  page  size  could  be  specified  as  "letter,xoffset=1in",  or
              "letter,xoffset=1in,yoffset=1.2in", or "a4,yoffset=-1cm".  In SVG format and WebCGM
              format  it  is  possible  to  specify the size of the graphics display, but not its
              position.

       --rotation angle
              Rotate the graphics display by angle degrees.  Recognized  values  are  "0",  "90",
              "180",  and  "270".   "no"  and "yes" are equivalent to "0" and "90", respectively.
              The environment variable ROTATION can also be used to specify a rotation angle.

   Parameter Initialization Options
       The following options set the initial values of drawing parameters.  However, all of these
       may  be  overridden  by  directives  in  a  metafile.   In  fact, these options are useful
       primarily when plotting old metafiles in the traditional (pre-GNU) plot(5)  format,  which
       did not support such directives.

       --bg-color name
              Set  the color initially used for the background to be name.  This is relevant only
              to plot -T X, plot -T png, plot -T pnm, plot -T gif, plot -T svg, plot -T cgm,  and
              plot  -T  regis.   An  unrecognized  name  sets  the color to the default, which is
              "white".  The environment variable BG_COLOR can equally well be used to specify the
              background color.

              If  the  -T  png  or -T gif option is used, a transparent PNG file or a transparent
              pseudo-GIF,  respectively,  may  be  produced  by  setting  the   TRANSPARENT_COLOR
              environment  variable to the name of the background color.  If the -T svg or -T cgm
              option is used, an output file without a background may be produced by setting  the
              background color to "none".

       -f size
       --font-size size
              Set  the  size  of the font initially used for rendering text, as a fraction of the
              width of the graphics display, to be size.  The default is 0.0525.

       -F name
       --font-name name
              Set the font initially used for text to be name.  Font names are  case-insensitive.
              If the specified font is not available, the default font will be used.  Which fonts
              are available, and the default font, depend on which -T option  is  specified  (see
              above).   A  list  of  available fonts can be obtained with the --help-fonts option
              (see below).

       -W line_width
       --line-width line_width
              Set the initial width of lines, as a fraction of the width of the  display,  to  be
              line_width.   A  negative  value  means  that a default value should be used.  This
              value is format-dependent.  The interpretation of zero line width is  also  format-
              dependent  (in some output formats, a zero-width line is the thinnest line that can
              be drawn; in others, a zero-width line is invisible).

       --pen-color name
              Set the initial pen color to be name.  An unrecognized name sets the pen  color  to
              the default, which is "black".

   Options for Metafile Output
       The  following  option is relevant only if the -T option is omitted or if -T meta is used.
       In this case the output of plot, like the input, will be in GNU graphics metafile format.

       -O
       --portable-output
              Output the portable (human-readable) version of GNU metafile  format,  rather  than
              the  binary  version  (the  default).  The format of the binary version is machine-
              dependent.

   Options for Backward Compatibility
       By default, plot assumes that its input file(s) are in either the binary  version  or  the
       portable  version  of GNU metafile format.  You may specify that the input is, instead, in
       the traditional Unix (pre-GNU) graphics metafile format, which is documented  in  plot(5).
       The traditional graphics metafile format was produced by pre-GNU versions of graph(1).

       -h
       --high-byte-first-input
              Input  file(s)  are  assumed  to  be  in  the  binary, `high byte first' version of
              traditional metafile format.  This variant is uncommon.

       -l
       --low-byte-first-input
              Input file(s) are assumed to  be  in  the  binary,  `low  byte  first'  version  of
              traditional metafile format.  This variant is the most common.

       -A
       --ascii-input
              Input  file(s)  are  assumed  to  be  in  the  ASCII  (human-readable)  variant  of
              traditional metafile format.  On some older Unix systems, this variant was produced
              by plottoa(1).

   Informational Options
       --help Print a list of command-line options, and exit.

       --help-fonts
              Print  a table of available fonts, and exit.  The table will depend on which output
              format is specified with the -T option.  plot -T X, plot -T svg, plot -T  ai,  plot
              -T  ps, plot -T cgm, and plot -T fig each support the 35 standard Postscript fonts.
              plot -T svg, plot -T pcl, and plot -T hpgl support the 45 standard PCL 5 fonts, and
              the latter two support a number of Hewlett-Packard vector fonts.  All seven support
              a set of 22 Hershey vector fonts, as do plot -T png, plot -T pnm, plot -T gif, plot
              -T  regis,  and plot -T tek.  plot without a -T option in principle supports any of
              these fonts, since its output must be translated to  other  formats  by  a  further
              invocation of plot.

              The  plotfont(1)  utility  may  be  used to obtain a character map of any supported
              font.

       --list-fonts
              Like --help-fonts, but lists the fonts in a single column to facilitate  piping  to
              other  programs.  If no 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

       The environment variables BITMAPSIZE, PAGESIZE, BG_COLOR,  EMULATE_COLOR,  MAX_LINE_LENGTH
       and  ROTATION  serve  as  backups  for the options --bitmap-size, --page-size, --bg-color,
       --emulate-color,  --max-line-length,  and   --rotation,   respectively.    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.  Its value determines the display  that  will  be
       used.

       plot  -T  png  and  plot  -T gif, which produce output in PNG format and pseudo-GIF format
       respectively, are affected by the INTERLACE environment variable.  If its value is  "yes",
       the output will be interlaced.  Also, if the TRANSPARENT_COLOR environment variable is set
       to the name of a color, that color will be treated as transparent in the output.

       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 will be in a
       human-readable format rather than binary (the default).

       plot -T cgm, which produces output in CGM (Computer Graphics Metafile) format, is affected
       by  the CGM_MAX_VERSION and CGM_ENCODING environment variables.  By default, it produces a
       binary-encoded version of CGM version 3 format.  For backward compatibility,  the  version
       number  may be reduced by setting CGM_MAX_VERSION to "2" or "1".  Irrespective of version,
       the output CGM file will use the human-readable clear text encoding if CGM_ENCODING is set
       to "clear_text".  However, only binary-encoded CGM files conform to the WebCGM profile.

       plot  -T  pcl,  which  produces PCL 5 output for Hewlett-Packard printers and plotters, is
       affected by the environment variable PCL_ASSIGN_COLORS.  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  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
       width (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 rotated 90 degrees
       counterclockwise by setting the HPGL_ROTATE environment variable to "yes".   This  is  not
       the  same  as  the rotation obtained with the --rotation option, since it both rotates the
       graphics display and repositions its lower left corner toward another corner of the  page.
       Besides "no" and "yes", recognized values for HPGL_ROTATE 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).

       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.  All color names recognized by the X Window System may be used.
       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  its  value 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.

       Opaque  filling  and the drawing of visible white lines are supported only if HPGL_VERSION
       is "2" and the environment variable HPGL_OPAQUE_MODE is "yes" (the default).  If its value
       is  "no"  then  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 may, in fact, malfunction if asked to draw opaque objects.

       plot -T tek, which produces output for a Tektronix terminal or emulator, checks  the  TERM
       environment  variable.  If the value of TERM is a string beginning with "xterm", "nxterm",
       or "kterm", it is taken as a sign that plot  is  running  in  an  X  Window  System  VT100
       terminal  emulator:  a copy of xterm(1), nxterm(1), or kterm(1).  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 a string beginning with "kermit", "ansi.sys", or "nansi.sys", it
       is taken as a sign that plot is running in the VT100 terminal emulator provided by the MS-
       DOS  version  of  kermit(1).   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.

SEE ALSO

       graph(1),  pic2plot(1),  tek2plot(1), plotfont(1), plot(3), plot(5), and "The GNU Plotting
       Utilities Manual".

AUTHORS

       plot was written by Robert S. Maier (rsm@math.arizona.edu).

BUGS

       Email bug reports to bug-gnu-utils@gnu.org.