pl

---

SYNOPSIS

DESCRIPTION

EXAMPLES

COMMAND LINE ARGUMENTS

Arguments may be given in any order. If there are arguments that you want to always have in effect, you can invoke them (using option:) from a config file. Many settings can also be made dynamically from scripts via proc settings or proc page. Parameters are set in in this order: 1) config file; 2) proc page 3) command line (left to right); 4) proc settings. Hence, the command line always overrides the config file, and proc settings always overrides the command line.

-prefab prefabname

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

scriptfile
-f scriptfile

names a script file that will be interpreted to produce results. Alternatively, -stdin may be used to indicate that script will be available on standard input.

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. For example: CUTDATE=10-31-98 would declare the variable CUTDATE and set it to 10-31-98. Any argument on the command line that contains an embedded equals-sign (=) is taken as a var-value pair. Variable names are case-sensitive.

-o outfile | stdout

Specify a filename where the result will be written. No processing is applied to this name. If -o stdout is used, result will be sent to standard output. If -o is not specified, a default output filename will be used.

-dir dirname

Set ploticus' working directory to dirname. If used, this argument should be specified leftmost on the command line, since it affects evaluation of other args.

RESULT FORMAT OPTIONS (availability may depend on specific ploticus build):

-png       PNG image

-gif         pseudo-GIF image

-jpeg     JPEG image

-svg or -svgz       SVG graphic. See also SVG / XML options below.

-wbmp   WBMP image

-eps       EPS (encapsulated PostScript)

-ps         paginated PostScript to stdout

-x11         display on X11 screen

CLICKABLE IMAGE MAPS

-map

produce a server-side clickable imagemap file to accompany a png, gif, jpeg, or SVG.

-csmap

produce a client-side clickable imagemap file to accompany a png, gif, or jpeg.

-mapfile filename|stdout|stderr

explicitly name the output file containing the map info. The name may also be set in proc page. If a name is not specified, the imagemap file name will default to the same name as the output result file, except with a .map suffix.

RESULT SIZE OPTIONS

-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 origin (0,0) which is at the lower left.

-pagesize width,height

Control the size of the display window or image. width and height are in absolute units. Absolute location 0,0 is at the lower left corner.

This option may be used to control the size of the X11 display window result. The default size is 8 inches wide by 8 inches high. The resulting size is not influenced by the -scale option.

PNG, GIF, JPEG size will be determined by the extent of the graphic; however, -pagesize (or the proc page pagesize attribute) must be used for images where drawing occurred beyond (8.0,8.0) absolute (inch) coordinate, in order to allocate enough image memory (otherwise the top or right areas of the graphic will not be visible).

-pagesize has no effect with EPS or paginated PostScript results (the PostScript BoundingBox will be determined by the extent of the graphic).

Example: -pagesize 7,3

-tightcrop

For image or EPS output, crop the result tightly to the extent of the design. Normally a small margin is allowed on all four sides. This option sometimes crops a bit too tight; if so try -croprel.

-crop x1,y1,x2,y2

Crop image or EPS result to the box specified by x1,y1 and x2,y2, in absolute units. Note that there may be no spaces in the coordinates specification. Cropping takes place after design is rendered and does not affect coordinate locations.

-croprel left,bottom,right,top

Crop image or EPS result tightly to the extent of the design (like -tightcrop), but then adjust the cropping outward or inward on one or more sides. left is the amount to adjust the left side, in absolute units. Similarly for bottom, right, and top. Positive values always adjust outward from center; negative values adjust inward (tighter). There may be no spaces in the left,bottom,right,top specification. Cropping takes place after design is rendered and does not affect coordinate locations.

GRAPHICS ENVIRONMENT OPTIONS

-font font

sets the overall font to font. See fonts for more info.

-textsize pointsize

sets the overall default textsize to pointsize. All embedded size specifications will be rendered relative to this.

-linewidth w

sets the overall default linewidth to w. All embedded line width specifications will be rendered relative to this. See linedetails(pli) for more on line width.

-color color

sets the overall default text and line drawing color to color.

-backcolor color

sets the background color to color.

-cm

Use centimeters as absolute units. On the command line this must appear to the left of any arguments dealing with absolute unit values, such as -pagesize. If cm will always be the desired absolute units, the preferred way to achieve this is by using units: cm in a ploticus config file.

-inches

Use inches as absolute units. This is the default.

-outlabel label

Set the label or title for the output. For X11 this sets the window title; for PostScript and SVG it sets the %%Title attribute.

CAPACITY SETTING OPTIONS: These options (new with version 2.10) allow capacities to be raised for accomodation of very large data sets, or lowered to minimize memory usage. The defaults in this section are defined in pl.h.

-maxrows nrows

Set the capacity for data rows to nrows. Default nrows is 10,000. Ploticus will allocate one pointer for each row.

-maxfields nfields

Set the capacity for data fields to nfields. Default nfields is 200,000. Ploticus will allocate one pointer for each field.

-maxproclines nlines

Set the capacity for script lines for active procs to nlines. Default nlines is 5000. Active procs are the current proc, all #saved procs, and all proc getdata procs that contain embedded data. Ploticus will allocate one pointer for each line in each active proc.

-maxvector ncells

Set the capacity for the data plotting vector to ncells. Default ncells is 100,000. The data plotting vector is an array which holds plottable values for situations where the values must be sorted or pre-screened for bad values. Ploticus will allocate one double value for each cell.

SVG / XML OPTIONS:

Use this option to suppress the XML declaration line if the SVG result is to be embedded into a larger XML document.

Set the XML character encoding method. This encoding will be indicated in the XML declaration line. The default is iso-8859-1 which provides Latin and Western European character sets. For Unicode fonts this should be set to utf-8 (for more discussion see the Unicode section in fonts ).

-tag

Causes a suitable HTML <EMBED> tag to be written to standard output.

-zlevel n

This may be used to set the compression level to n for SVGZ output (0 - 9 where 9 is highest level of compression and the default).

INTERACTIVE USE OPTIONS

-winloc x,y

Control where on the screen the upper-left corner of the X11 display window will be placed. x and y are in pixels. Example: -winloc 200 0

-v command
-viewer command

After generating results in the specified format, execute command in order to view the results on your screen. The output file will automatically be included in the command. For example, if a GIF file is being generated you might use this to invoke the xv utility: -viewer xv. If PostScript is being generated you could use something like this to invoke the ghostview utility: -viewer "gv -magstep -1". The given command must be available on your system and locatable in your command search path. This option may not be used with -o stdout.

PAPER ORIENTATION OPTIONS

-landscape

For paginated postscript, set paper orientation to landscape (oblong).

-portrait

For paginated postscript, set paper orientation to portrait.

-posteroffset x,y

Allows production of large-size posters made up of multiple standard sheets of paper butted together. May be used only with paginated PostScript, and should be used in combination with the -scale and -textsize options. x,y is the point within your result (in absolute units ) that is to be placed at the lower left corner of the page. For further discussion of this, see posters .

DEVELOPMENT AND DEBUGGING OPTIONS

-debug

Debug mode. Causes dianostic information to be written to the diagnostic stream (stderr by default, see -diagfile below). Highly recommended if you are experiencing difficulty. Best to use -debug as the first (leftmost) argument so that it can report on all arguments gotten. Another effect of debug mode is that any temporary files are not removed upon termination.

-showbad

Identify unplottable data, showing the value, and its row and field.

-diagfile filename | stderr | stdout

All non-error messages and output will be written to this file (default is stderr).

-errfile filename | stderr | stdout

All error messages will be written to this file (default is stderr).

-help or -? or -version

Print version number, copyright info, web site address, etc.

OUTPUT FILE NAMES

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.

X11 output is always displayed on the screen, and paginated PostScript is written to standard output unless -o is used.

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.

If a clickmap is being generated, the result file is named similarly to the above.

USAGE EXAMPLES

The following example uses the scat prefab :

pl -prefab scat -png datafile=results.dat x=2 y=3

The following examples assume that you have a script file called lineplot1.p.

pl -x lineplot1.p = view on X11 screen

pl -png lineplot1.p = create PNG image lineplot1.png

pl -gif lineplot1.p -o stdout = create GIF image on standard output

pl -gif lineplot1.p -viewer xv = produce GIF and view using xv (assuming xv image viewer is available on your system).

pl -eps lineplot1.p = produce EPS file lineplot1.eps

pl -eps lineplot1.p -viewer gv = produce EPS and view using gv (that's ghostview, assuming it is available on your system).

pl -eps lineplot1.p -o lineplot.eps = produce EPS into file lineplot.eps

pl -ps lineplot1.p | lp = produce paginated postscript and send to unix lp print spooler.

pl -ps lineplot1.p -veiwer gv = produce paginated postscript and view using ghostview.

ENVIRONMENT

PLOTICUS_CONFIG

The name of a ploticus configuation file , for setting default date notations, number notations, measurement units, etc.

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.

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

AUTHOR

SEE ALSO