Search


Home >

pl(1) command... man page

pl scriptfile [options]
.. OR ..
pl -prefab prefabname [prefabparms] [options]

Description

pl generates plots and graphs

Package

pl is the primary executable component of the ploticus data display utility.
See also the libploticus API.

Usage examples

pl myscript -png -o out.png (PNG result)
pl myscript -ps > out.ps (postscript result)
pl -prefab scat -png datafile=results.dat x=2 y=3 (scatterplot using the scat prefab)

Options and arguments

-f scriptfile
or simply scriptfile

names a script file that will be interpreted to produce results. You can also use -stdin

-prefab prefabname

Produce a plot using a prefab plot template. prefabname identifies the template, eg. cron or vbars. Graphing parameters are supplied on the command line using the form parm=value.

variable=value

Declares the named variable and sets it to the given value. This is a convenient way to pass information to prefabs and scripts. Variable names are case-sensitive. Example: CUTDATE=10-31-98 sets the variable CUTDATE to 10-31-98.

-o filename

Specify output filename. Name must be appropriate for your output format (such as .png for PNG files) or use -o stdout. If -o isn't specified, a default output filename will be generated. Example: -o fp001.png

-dir dirname

Set working directory. If used, specify leftmost on command line,

-outlabel label

Set the result's title or label. Mostly an issue with -ps

... Output graphics file format options

-png ..... PNG image

-gif ..... GIF image

-ps ..... paginated PostScript to stdout. See also ps2pdf(1) for creating PDF

-eps ..... EPS encapsulated PostScript to file

-svg or -svgz .... SVG output / options

-jpeg or -wbmp ..... JPEG or WBMP image if supported

-drawdump filename     Create a textfile code representation of the graphic, to overlay multiple results etc. (use -drawdumpa to append to file). Render graphic later using draw prefab or proc drawcommands.

-x11 .... display on X11 screen (deprecated)

-swf .... SWF flash result (deprecated)

-csmap     Use along with -png -gif or -svg to produce a client-side clickable imagemap to accompany an image for web use. Enables popup tooltip textboxes or clickthru hyperlinks. Clientside map content is written to stdout by default. For development you can use the -csmapdemo option instead, to see boundaries in green and get an HTML code chunk with the map tags. To write the imagemap content to a file use -mapfile filename. To produce an older type server-side imagemap you can still use -map

... Output result sizing options

-pagesize width,height

Allocates memory for the pre-crop drawable PNG or GIF image. Default is 8,8 (8 inches square). MUST be used for results larger than 8" x 8" in either dimension. The width and height parms are in absolute units; and 0,0 is the lower left corner. Not affected by -scale or any of the crop options. Ignored when generating PostScript or SVG. Example: -pagesize 7,3

-tightcrop
-crop x1,y1,x2,y2
-croprel left,right,bottom,top

Crop the result image. -tightcrop crops to the internally-computed bounding box of your result with no extra. -crop crops to an explicit bounding box in absolute units. -croprel is same as -tightcrop but adds specified margin amounts to left bottom right and top (negative values ok). All cropping takes place after design is rendered and does not affect coordinate locations.
Example: -tightcrop
Example: -crop 1.2,0.8,4.4,5.2
Example: -croprel 0,-0.1,0,0.1

-scale sx[,sy]

Scale the final result. If one value is given, the result is scaled by this amount in both x and y. If two values are given, scaling in x and scaling in y may be done independently. A scale value of less than 1.0 reduces the size; an scale value of greater than 1.0 enlarges. Scaling is done relative to the lower-left origin (0,0). Example: -scale 0.7

-pixsize width,height

Render the result image (PNG or GIF) to exactly this pixel width and height. Not compatible with the cropping options... your result must be drawn to the prescribed area thus this option could be a bother to use, and -pagesize may still be needed for memory allocation purposes.

... Drawing environment options

These can be used to set underlying defaults for font, drawing color, background color, etc. As usual these can be overridden from within scripts, etc.

-font font     sets the font

-textsize pointsize     Sets the overall default text size, and all size specifications will be rendered relative to this based on 10 pt as standard.

-linewidth w     sets the overall default linewidth to w. All embedded line width specifications will be rendered relative to this based on 1.0 as standard.

-color color     sets the default text and line drawing color

-backcolor color     sets the background color

-landscape     Set paper orientation to landscape (with -ps only)

-portrait     Set paper orientation to portrait (with -ps only)

-posteroffset     For combining several paper sheets into a large poster. More info

-cm     Use centimeters as your absolute units, instead of inches. Specify leftmost on command line. Also settable in proc settings. or in config file. -inches is also available but it's usually the default.

... Raising capacities and develpment / debug options

For raising internal capacities see the program limitations page

-help or -? or -version     Print version number, copyright info, web site address, etc.

-debug     Debug mode. Dianostic information is written to the diagnostic stream (stderr by default, or see -diagfile), and refrains from deleting working temp files. Use leftmost on command line.

For more development/debug options see this page.

Output file names

The output file may be specified on the command line using the -o option, or via proc page's outfilename attribute. If so, the result is written to a file of that name. -o stdout may also be used to send result to standard output.

Otherwise, if your script filename has a "recognized extension" ( .p, .pl, .plo, .pls, .htm or .html ), the base part of the script file name is used and .png, .gif, etc. is appended. If your script filename doesn't have a recognized extension, the generic name out.* will be used.

Pagination: If page breaks (proc page) are encountered when rendering in any format other than paginated PostScript, special action is necessary since each page must go into a separate file. A proc page outfilename may be specified for each page; otherwise a pn prefix will be attached to the beginning of each page's output file name to indicate page n.

Other ways to set the options

If there are arguments that you want to always have in effect, you can invoke them from a config file. Many settings can also be made dynamically from scripts via proc settings or proc page. If options are given in more than one place the precedence order is (highest to lowest): 1) proc settings or proc page; 2) command line args; 3) config file.

Environment

PLOTICUS_PREFABS

The path name of a directory where ploticus will look for prefab scripts. The "factory" prefabs are located in the ploticus ./prefabs subdirectory.

PLOTICUS_CONFIG

The name of a ploticus configuation file for setting defaults to be always in effect, for things like date notations, number notations, measurement units, etc.

LC_CTYPE, LC_COLLATE, LANG

Locale support. Thanks to Oleg Bartunov oleg@sai.msu.su for contributing this. pl must be built with -DLOCALE for this to work.

TDH_ERRMODE

Control the disposition of error messages. Allowable values: stderr which is the default, and cgi which causes error messages to be written to stdout with html formatting.

Bugs

Ploticus has some stated limitations (mostly related to capacities that you may run into if you're dealing with large data sets). To report problems or get help see the ploticus support page.