/**

	@mainpage	gnuplot_i reference Manual

	@section intro Introduction

	gnuplot_i (formerly known as gnuplot_pipes) is yet another
	attempt to provide a programmer-friendly set of routines to
	use gnuplot as a data displayer from a C program. Looking
	into the code, you will see that it is actually talking to
	gnuplot through a Unix pipe (ports to Windows involve
	simulating a Unix pipe as well), instead of using a kind of
	API to gnuplot's plotting features.

	Why is that so? Simply because gnuplot has not been
	programmed with a C API in mind, but to be an interactive
	plotting program. There have been several attempts at trying
	to extract a set of communication functions to the core
	plotting engine, without success. Your best bet is to talk to
	a gnuplot session as you would type commands on the keyboard.
	This command interface is clearly defined, hard to get wrong,
	and offers all the functionalities you have in gnuplot. The
	only drawback is that since a Unix pipe is unidirectional, it
	is very hard to get an error status back from gnuplot.
	gnuplot_i is only implementing this thin layer around the
	pipe, with no error reporting.

	The idea of talking to a gnuplot session through a pipe is
	not new, various implementations have been circulating on the
	Usenet since a while. gnuplot_i is only a factorization of
	the best efforts seen so far to achieve such an interface, it
	is nothing particularly original or fancy. gnuplot_i is
	placed in the public domain in the hope that it can be useful
	to somebody. Thanks to the many contributors for bug reports,
	suggestions and additional code!

	@section ref Reference

	You can browse here the reference documentation for the two source
	files:

	- gnuplot_i.c
	- gnuplot_i.h

	@section install Installing gnuplot_i

	Follow these steps to compile the module:

	- Edit the Makefile to indicate the C compiler you want to use,
	the options to provide to compile ANSI C. If you want to use
	gcc, you have nothing to change.
	- Type make to make @c gnuplot_i.o.
	- Type make tests to make the test programs.
	- Type 'test/anim' or 'test/example' to get an overview of
	the possibilities offered by this module.

	To use the module in your programs, add the following line on top
	of your module:

	@code
	#include "gnuplot_i.h"
	@endcode

	And link your program against the gnuplot_i module by adding
	@c gnuplot_i.o to the compile line.

	See the files test/anim.c and test/example.c for examples.

	@section tuto Tutorial

	The procedure to follow to display graphics in a gnuplot
	session is:

	@subsection tuto1 Open a new session

	Open a new gnuplot session, referenced by a handle of type
	(pointer to) gnuplot_ctrl. This is done by calling gnuplot_init():

	@code
    gnuplot_ctrl * h ;
    h = gnuplot_init() ;
	@endcode

    @c h will be used as the handle to the gnuplot session
    which was just opened, by all further functions.

	Notice that the default behaviour of gnuplot_i is to check
	for the presence of an environment variable called DISPLAY,
	which is mandatory under X11 to display with gnuplot. If the
	module cannot found any DISPLAY variable in the environment,
	you get a warning on @c stderr.

	@subsection tuto2 Send optional configuration commands

	Send optionally display configuration orders. The following
	functions are available:

    - gnuplot_setstyle() sets the plotting style of the next plots
    - gnuplot_set_xlabel() sets the X label for the next plots
    - gnuplot_set_ylabel() sets the Y label for the next plots

    Examples:

	@code
    gnuplot_setstyle(h, "impulses") ;
    gnuplot_set_xlabel(h, "my X label") ;
    gnuplot_set_xlabel(h, "my Y label") ;
	@endcode

	The most useful routine is probably gnuplot_cmd(), which
	allows you to send character strings to gnuplot as though
	they were typed in by a user. This routine works in a printf
	fashion, accepting the same kind of format string and
	variable number of arguments. The prototype is:

	@code
    gnuplot_cmd(handle, command, ...)
	@endcode

    Example:

	@code
    char myfile[] = "/data/file_in.dat" ;
    int  i ;
    
    gnuplot_cmd(handle, "plot '%s'", myfile);
    for (i=0 ; i<10 ; i++) {
        gnuplot_cmd (handle, "plot y=%d*x", i);
    }
	@endcode

    The following commands request the output to be done to
    a postscript file named 'curve.ps':

	@code
    gnuplot_cmd(h, "set terminal postscript") ;
    gnuplot_cmd(h, "set output \"curve.ps\"") ;
	@endcode

	Using gnuplot_cmd(), it should be fairly easy to add up some
	more configuration-related functions whenever needed.


	@subsection tuto3 Send display commands

	Send some display orders: either functions or doubles, or
	double points. The following functions are available:

    - gnuplot_plot_slope() to display a slope
    - gnuplot_plot_equation() to display an equation
	- gnuplot_plot_x() to display user-defined 1d data with
	  a single variable. Input is a list of values, assumed
	  regularly spaced on the X-axis.
	- gnuplot_plot_xy() to display user-defined 1d data with two
	  variables. Provide x and y through two arrays of doubles.
	- gnuplot_resetplot() requests the current gnuplot display to
	  be cleared before next display is done.


	@subsection tuto4 Close the session

	Close the gnuplot session by calling gnuplot_close on the session
	handle. This is very important, since otherwise all temporary
	files will NOT be cleaned for /tmp and /var/tmp.

	@code
    gnuplot_close(h) ;
	@endcode

	See examples of gnuplot_i use in the provided files
	'example.c' and 'anim.c'.

	@section misc Some more points before you start using gnuplot_i

    gnuplot_i is completely free software. Use it for
	whatever you want to do with it without any fee, and do not
	hesitate to send feedback to me if you wish: @e ndevilla@free.fr
    
	If you can do it, I would appreciate a mention somewhere that you
	are using 'gnuplot_i' in your application. Something like:
	
	<em>
	"This software uses the gnuplot_i library written by N.Devillard"
	</em>

    If you are using gnuplot_i for a web-based
    application, you can also add a link to the gnuplot home
    page: http://ndevilla.free.fr/gnuplot/

	If you are so happy about this piece of code that you would
	like to fund more stuff like that, do not hesitate to send me
	cash @c :-)

    Notice that it is possible to open several gnuplot sessions
    from the same program. Just be careful then to which session
    you are talking when using functions. Example:

	@code
    h1 = gnuplot_init() ;
    h2 = gnuplot_init() ;

    gnuplot_plot_equation(h1, "sin(x)", "sine on first session");
    gnuplot_plot_equation(h2, "log(x)", "log on second session") ;
    sleep(3) ;
    gnuplot_close(h1) ;
    gnuplot_close(h2) ;
	@endcode

	Never forget to close opened sessions! This would leave some
	temporary files. Hopefully, your temporary directories should
	be cleaned automatically every now and then, but best is
	simply not to forget to close all windows before leaving the
	house.

	User interactions are not part of gnuplot_i. Feel free to use
	your own.

	No timing mechanisms are provided to leave the outputs on
	screen until e.g. a key is pressed. I leave it up to
	gnuplot_i users to provide that kind of functionality in
	their own application, depending on the kind of interaction
	they need.

	No programming so far of 'splot' related commands. Should you
	implement some, I would recommend making use of the 'plot'
	related commands as a canvas.

	@section example Example: generating web plots on the fly

	gnuplot can be used to generate PNG images of plots instead
	of plotting to a normal window session. This requires to have
	linked your version of gnuplot against the PNG library
	(freely available). Look up the gnuplot documentation about
	PNG support.

	The procedure is simple: open a new session, set the terminal
	type to PNG, set the output file name, and plot your data.
	Close the session, you are done. This translates to something
	like:

	@code
	gnuplot_ctrl * g = gnuplot_init();

	gnuplot_cmd(g, "set terminal png");
	gnuplot_cmd(g, "set output \"sine.png\"");
	gnuplot_plot_equation(g, "sin(x)", "Sine wave");
	gnuplot_close(g);
	@endcode

	You can also find this example in the source distribution,
	in the file sinepng.c.

 */
