This document is a quick overview of building and configuring drivers from
the perspective of what system files have to be modified.  (For actual details
about how to construct a new device driver read the source for some of
the drivers in plplot/drivers.  Also, there are several useful sections in
the DocBook documentation [see, for example, "Output Devices" and "Driver
Functions" in Chapter 3] that you should look at.)

The following is the list of PLplot system files that must be modified if
you are creating a new PLplot driver:

plplot/configure.ac
plplot/cf/*.ac  (e.g., plplot/cf/gd.ac)
plplot/cf/drivers-pre.ac
plplot/cf/drivers-post.ac
plplot/include/plDevs.h.in
plplot/drivers/Makefile.am
plplot/include/drivers.h
plplot/include/plcore.h
plplot/drivers/*.c (e.g., plplot/drivers/gd.c)

where plplot is the top-level directory for the plplot software tree that is
created when you unpacked the tarball (or used cvs checkout).

Some short notes follow on what is done for the individual files mentioned
above. Basically, you should be okay if you just try to follow what is done
for the gd.c driver, the associated png and jpeg devices, and any additional
headers or libraries you might require for your driver.  (libgd, libjpeg,
libpng, and libz are required for the gd driver to work and are found on
the user's system with the aid of the macros in the cf/gd.ac file.).

* plplot/configure.ac with plplotcf/gd.ac as an example of what is required
for the gd device driver (which could be used as a template for other new
devices).

Note, configure.ac has the line

m4_include(cf/gd.ac)

that includes the gd.ac file.  That latter file is used to find the system
resources used by the gd device. If you look in that file you will see logic
for finding and testing the required system headers and include libraries,
enabling or disabling the jpeg and png devices associated with the gd
driver, and ultimately forming GDINCCMD and GDLIBCMD which summarizes this
information.  For your new driver, follow this same paradigm, i.e. include
command in configure.ac, and the corresponding cf/*.ac for your particular
device driver.  For more details see plplot/cf/README.

* Some additional setup of the png and jpeg devices for the gd driver is
done in plplot/cf/drivers-pre.ac with the line

png:gd:yes, jpeg:gd:yes,

Add in a similar line for your own list of devices for your driver.

* Some additional setup of devices is done in  plplot/cf/drivers-post.ac.
I have no idea why that is separated from plplot/cf/drivers-pre.ac, but
there is nothing relevant to gd there, and probably not for your device driver
as well.

* plplot/include/plDevs.h.in

The entries in this file for the png and jpeg devices associated with the gd
driver are

#undef PLD_png
#undef PLD_jpeg

These entries inform the configure script to store the actual configured
results

#define PLD_png 
#define PLD_jpeg 

(say) in the created file plplot/include/plDevs.h.

In turn, the information in this header is used in drivers/gd.c to decide
which of the associated devices to compile.

* plplot/drivers/Makefile.am

This file tells automake and libtool how to build the various drivers, what
libraries must be linked to them, etc., for the two cases of
--enable-dyndrivers (where the drivers are built as loadable modules [i.e.,
plug-ins or DLL's]) and --disable-dyndrivers (where the drivers are built
and stored in a libtool convenience library which eventually becomes part of
libplplot).  For the gd driver look for all references to gd.  You will see
references to GDINCCMD and GDLIBCMD that are set up with sysloc.in and
configure.ac above.

* plplot/include/drivers.h

This file contains prototype definitions that occur in drivers/*.c.  For the
gd driver, these prototypes are

void plD_dispatch_init_jpeg	( PLDispatchTable *pdt );
void plD_dispatch_init_png	( PLDispatchTable *pdt );

The point of plD_dispatch_init_??? is to initialize the driver dispatch
table with the data it needs to know.  Look for void plD_dispatch_init_jpeg
and void plD_dispatch_init_png in drivers/gd.c.

* plplot/include/plcore.h

This file contains a definition of the table static_device_initializers.  In
the jpeg and png case the relevant lines are 

#if defined(PLD_png) && !defined(ENABLE_DYNDRIVERS)
    plD_dispatch_init_png,
#endif
#if defined(PLD_jpeg) && !defined(ENABLE_DYNDRIVERS)
    plD_dispatch_init_jpeg,
endif

* plplot/drivers/*.c

This is where the core of the driver software is defined.  plplot/drivers/gd.c
contains the software defining the gd driver with the associated png and jpeg 
devices.
