We describe simple use of PLplot in this chapter which includes many cross-references to elements of our common (C) API that use PLplot C types such as &PLFLT; and &PLINT;. For full documentation of all PLplot C types see here. The best way to learn how to use our common API for the language of your choice is to look at our standard set of examples. For additional language documentation you should consult the various chapters in as well. We shall first consider plotting simple graphs showing the dependence of one variable upon another. Such a graph may be composed of several elements: A box which defines the ranges of the variables, perhaps with axes and numeric labels along its edges. A set of points or lines within the box showing the functional dependence. A set of labels for the variables and a title for the graph. For a good tutorial example of such a simple graph for each of our supported languages, see our standard example 00. In order to draw such a simple graph, it is necessary to call at least four of the PLplot functions: &plinit;, to initialize PLplot. &plenv;, to define the range and scale of the graph, and draw labels, axes, etc. One or more calls to &plline; or &plstring; to draw lines or points as needed. Other more complex routines include &plbin; and &plhist; to draw histograms, and &plerrx; and &plerry; to draw error-bars. &plend;, to close the plot. More than one graph can be drawn on a single set of axes by making repeated calls to the routines listed in item 3 above. PLplot only needs to be initialized once unless plotting to multiple output devices. Before any actual plotting calls are made, a graphics program must call &plinit;, is the main initialization routine for PLplot. It sets up all internal data structures necessary for plotting and initializes the output device driver. If the output device has not already been specified when &plinit; is called, a list of valid output devices is given and the user is prompted for a choice. Either the device number or a device keyword is accepted. There are several routines affecting the initialization that must be called before &plinit;, if they are used. The function &plsdev; allows you to set the device explicitly. The function &plsetopt; allows you to set any command-line option internally in your code. The function &plssub; may be called to divide the output device plotting area into several subpages of equal size, each of which can be used separately. One advances to the next page (or screen) via &pladv;. If subpages are used, this can be used to advance to the next subpage or to a particular subpage. The function &plenv; is used to define the scales and axes for simple graphs. &plenv; starts a new picture on the next subpage (or a new page if necessary), and defines the ranges of the variables required. The routine will also draw a box, axes, and numeric labels if requested. For greater control over the size of the plots, axis labelling and tick intervals, more complex graphs should make use of the functions &plvpor;, &plvasp;, &plvpas;, &plwind;, &plbox;, and routines for manipulating axis labelling &plgxax; through &plszax;. The function &pllab; may be called after &plenv; to write labels on the x and y axes, and at the top of the graph. More complex labels can be drawn using the function &plmtex;. For discussion of writing text within a plot see . PLplot can draw graphs consisting of points with optional error bars, line segments or histograms. Functions which perform each of these actions may be called after setting up the plotting environment using &plenv;. All of the following functions draw within the box defined by &plenv;, and any lines crossing the boundary are clipped. Functions are also provided for drawing surface and contour representations of multi-dimensional functions. See for discussion of finer control of plot generation. &plstring;, &plpoin;, and &plsym; plot n points (x[i], y[i]) using the specified symbol. The routines differ only in how the plotted symbol is specified. &plstring; is now the preferred way of drawing points for unicode-aware devices because it gives users full access via a UTF-8 string to any unicode glyph they prefer for the symbol that is is available via system fonts. &plpoin; and &plsym; are limited to Hershey glyphs and are therefore more suitable for device drivers that only use Hershey fonts. For both of these functions the Hershey glyph is indicated by a code value. &plpoin; uses an extended ASCII index of Hershey glyphs for that code value, with the printable ASCII codes mapping to the respective characters in the current Hershey font, and the codes from 0–31 mapping to various useful Hershey glyphs for symbols. In &plsym; however, the code is a Hershey font code number. Standard examples 04, 21, and 26, demonstrate use of &plstring; while standard example 06 demonstrates all the Hershey symbols available with &plpoin; and standard example 07 demonstrates all the Hershey symbols available with &plsym;. PLplot provides two functions for drawing line graphs. All lines are drawn in the currently selected color, style and width. See for information about changing these parameters. &plline; draws a line or curve. The curve consists of n-1 line segments joining the n points in the input arrays. For single line segments, &pljoin; is used to join two points. The &plptex; API allows UTF-* text to be written anywhere within the limits set by &plenv; with justification and text angle set by the user. Area fills are done in the currently selected color, line style, line width and pattern style. &plfill; fills a polygon. The polygon consists of n vertices which define the polygon. Functions &plbin; and &plhist; are provided for drawing histograms, and functions &plerrx; and &plerry; draw error bars about specified points. There are lots more too (see ). Before the end of the program, always call &plend; to close any output plot files and to free up resources. For devices that have separate graphics and text modes, &plend; resets the device to text mode. If a fatal error is encountered during execution of a PLplot routine then &plexit; is called. This routine prints an error message, does resource recovery, and then exits. The user may specify an error handler via plsexit that gets called before anything else is done, allowing either the user to abort the error termination, or clean up user-specific data structures before exit.