INDEX
** Prepare a (preliminary) version of the ChangeLog file for this release
** Prepare the README.release file and/or press those who have made
   changes in this release cycle to update that file
** Prepare and test the documentation
** Check and potentially fix internal consistency
** Update website-related files
** Install and test a (preliminary) local copy of the PLplot website
** Update Release date and versions
** Update this file (README.Release_Manager_CookBook)
** Create (a preliminary version of) the release tarball and check the
   result for errors
** Do comprehensive test of PLplot
** Install and test a local copy of the PLplot website
** Create ChangeLog.release
** Create the PLplot Release
   ++ Preliminaries
   ++ Install and test a local copy of the PLplot website
   ++ Upload the local website to SourceForge
   ++ Create a final release tarball and check the result for errors
   ++ Sign the release with your plplot Release Manager gpg key
   ++ Verify the release tarball signing
   ++ Make a SourceForge file release
** Publicize the release announcement
** Prepare immediately for the next release cycle

INDEX for Appendix
** GNU Privacy Guard (gpg)
** Creating a test tarball from trunk
** Correct computer time

N.B. the order of steps below is important because of the dependencies
between the steps which are noted (except for the generation of the
final release tarball and ChangeLog which depend on virtually all
prior steps).
_________________________________________________________________________

** Prepare a (preliminary) version of the ChangeLog file for this release

This step does not depend on other steps.

# This makes the BASE used below correct.
svn update

svn log --revision <LAST_RELEASE_REVISION>:BASE --verbose  >| ChangeLog.release_preliminary

where <LAST_RELEASE_REVISION> stands for the last revision number of
the previous release which can be determined e.g., by viewing the
ChangeLog.release file from the previous release.  Note the
"_preliminary" suffix to distinguish this from the final result below
which will contain (if all goes well in the steps below) a record of
all but the last commit (of the ChangeLog itself) for this release.

Note the order of the --revision components puts this preliminary version
in chronological order.  But it is traditional for the final version
to have the result in reverse chronological order (see below).

_________________________________________________________________________

** Prepare the README.release file and/or press those who have made
   changes in this release cycle to update that file

This step depends on the step above entitled

"Prepare a (preliminary) version of the ChangeLog file for this release".

To double-check that file is complete with regards to all major
developments during this release cycle, skim all the commit messages in
ChangeLog.release_preliminary determined above.
_________________________________________________________________________

** Prepare and test the documentation

This step does not depend on other steps.

The steps below entitled 

"Check and potentially fix internal consistency" and
"Install and test a (preliminary) local copy of the PLplot website"
"Install and test a local copy of the PLplot website"

depend on this step.

Update the doxygen documentation (in our source code) and DocBook
documentation (in doc/docbook/src) to reflect any changes (new drivers
or new PLplot functionality) in the current release cycle.  Or
alternatively, press those who made the changes to update the
documentation.  Generate and test our doxygen form of documentation
following the instructions in doc/README.doxygen.

Update, generate and test our Docbook documentation following the
instructions in doc/docbook/README.developers.
_________________________________________________________________________

** Check and potentially fix internal consistency

This step depends on the step above entitled 

"Prepare and test the documentation".

This step potentially affects the swig-generated bindings and
the f95, tcl, and ocaml bindings.  Thus, the step below entitled

"Comprehensive test of PLplot"

may depend on this step.

Some of the files in the source tree are generated from other files
in the source tree using build-system targets.  All targets that
have "check" in the name prefix are these kind of targets.  So to get
a complete list of such targets, execute

make help |grep '... check'

in the build tree.  The current such list of targets is

... check_plplotcapi_defines
... check_swig_documentation
... check_f95_parameters
... check_tcl_parameters
... check_plplot_h.inc

Note, one of these targets (check_plplot_h.inc) only exists if the
-DGENERATE_PLPLOT_H_INC=ON cmake option is used which in turn requires
that at least the OCaml version of the Perl regular expression library
be installed.  (On debian the associated package name is
libpcre-ocaml-dev.)  Normally, GENERATE_PLPLOT_H_INC is OFF by default
to reduce build dependencies, but to make the complete list of such
targets available you should run the cmake command with the
-DGENERATE_PLPLOT_H_INC=ON option and make sure there are no
OCaml-related warnings in the results.

To actually do the internal consistency checks, run each of the above
targets which typically generate a file in the build tree which is
then compared (using the Unix cmp command) with the file that is being
checked in the source tree.  If the two files are inconsistent (which
can be caused by documentation updates, for example), the cmp command
complains, and you should follow up by doing a diff between the two
files to confirm that the changes are reasonable followed by copying
the build-tree version of the file on top of the source-tree version
and committing the source-tree version.  When this process is completed,
all the above targets should run with no cmp or other errors/warnings
at all, e.g.,

software@raven> make check_swig_documentation check_f95_parameters check_tcl_parameters check_plplot_h.inc
Check that swig_documentation.i is consistent with doc/docbook/src/api.xml
Built target check_swig_documentation
Check that plplot_parameters.h is consistent with the #defines in bindings/swig-support/plplotcapi.i
Built target check_f95_parameters
Check that plplot_parameters.h is consistent with the #defines in bindings/swig-support/plplotcapi.i
Built target check_tcl_parameters
Check that plplot_h.inc is consistent with touchup.ml and plplot_h
Built target check_plplot_h.inc
_________________________________________________________________________

** Update website-related files

This step does not depend on other steps.

The steps below entitled

"Install and test a (preliminary) local copy of the PLplot website"
"Install and test a local copy of the PLplot website"
"Create (a preliminary version of) the release tarball and check the result"
"Create the release tarball and check the result"

depends on this step.

If necessary, update the examples list in
scripts/htdocs-gen_plot-examples.sh. That list is used to generate the
website example-related files and copy the results to the website. The
list automatically controls what example source code is configured
(for source code that needs that), as well as what example plots and
example thumbnails are generated.  The list also automatically
controls what examples-related files are copied to the website.

Update the project web page, including the examples: edit
www/examples.php to reflect any changes to the examples themselves
(i.e. pages added or removed from an existing example or entirely new
examples).

Note, the xmlto package that must be installed in order to generate
the DocBook documentation (see doc/docbook/README.developers referred
to above) is also used to generate some of our older release
announcements for the website, and could also be used to generate
present release announcements for the website if desired.  See
www/announce/README for just how easy this step would be.
_________________________________________________________________________

** Install and test a (preliminary) local copy of the PLplot website

This step depends on the steps above entitled

"Prepare and test the documentation" and
"Update website-related files"

but does not depend on any steps below.

To build the local form of the website (including both the doxygen and
DocBook forms of our documentation) run (on a Linux host that is
capable of building the documentation for the source tree that has all
local changes)

scripts/generate_website.sh

with no arguments.  The script asks you four questions, gives you a chance
to verify your answers, then does all the rest of it (downloading a
throwaway copy of the PLplot source code, building the doxygen and DocBook documentation,
generating the announcements that are part of the base website, uploading
the base website, uploading the documentation, building the examples,
running the examples, uploading the example source code and example results)
automatically.  I (AWI) tested this script using the four answers

Summary:
USERNAME = irwin
GROUPNAME = irwin
HOSTNAME = raven
WEBSITE_PREFIX = /home/irwin/public_html/plplot

(raven is my local computer name, and /home/irwin/public_html is a location
where I can put various websites).  You can check for errors (e.g., due
to missing commands that need to be installed) by running

find /tmp/plplotdoc -name '*.out' |xargs grep -i error

You should install both apache and PHP on your computer.  For Debian stable
(a.k.a. wheezy) that is done (as root) by installing libapache2-mod-php5
and enabling user directories using the command

a2enmod userdir

and editing /etc/apache2/mods-available/php5.conf as indicated in that
file to allow user directories for php.  I am not sure, but I believe
from some google results I found that editing of that file is also
necessary on modern versions of Ubuntu in order to allow php-based websites
like that of PLplot to work when installed in local user directories.

After the above changes, you must restart the apache server.  On
Debian this is done with

service apache2 restart

(When user directories are enabled this way, for the above case
/home/irwin/public_html/plplot/htdocs, browses as
http://raven/~irwin/plplot/htdocs/.)

I test http://raven/~irwin/plplot/htdocs/ by clicking on most links,
checking the documentation looks good, checking the examples are
complete and look good and the source code for each language for
examples is accessible, etc.  Some iterations with the
steps above entitled

"Prepare and test the documentation" and
"Update website-related files"

will likely be required.

N.B. scripts/generate_website.sh uses the local source tree where that
script resides (including all local changes) as the source tree for
generating the local website.  So there is no need to commit every
documentation, example, and version change until you are completely satisfied
with the local website.  But after you _are_ satisfied with the
local website you should commit all your changes so they are available
for generating the tarball and ChangeLog (see below) for this release.

N.B. The iterated result should be identical to the final result (see
below) except that the release date (configured as RELEASE_DATE) and
the PLplot version in www/example.php will be wrong.  Those
issues are addressed in "Update release date and versions" below.
_________________________________________________________________________

** Update Release date and versions

This step depends on no others.

The following steps entitled

"Create (a preliminary version of) the release tarball and check the result
for errors."
"Install and test a local copy of the PLplot website"
"Comprehensive test of PLplot"

depend on this step.

Update PLplot version in www/examples.php.  In addition,
update cmake/modules/plplot_version.cmake to reflect the current
RELEASE_DATE (which affects the documentation build) and
version. Also, follow the instructions in that file for updating the
SOVERSION, the minor number and the patch number for each versioned
library created by the PLplot build.
_________________________________________________________________________

** Update this file (README.Release_Manager_CookBook)

Edit this file to reflect latest practices by the release manager and
also to update the many version numbers in it to the latest version
value.

_________________________________________________________________________
** Create (a preliminary version of) the release tarball and check the
   result for errors

This step depends on the steps above entitled

"Prepare and test documentation"
"Check and potentially fix internal consistency"

The -c option runs ctest on the directory tree unpacked from the
release tarball, and the -i option installs a build from that
directory tree

scripts/make_tarball.sh -c -i /tmp/plplot_install

find /tmp/plplot-dist-prep -name "*.out" |xargs grep -i error

If the above find command discovers any errors, then those errors
need to be fixed and this step needs to be repeated.

Browse the following install locations that were generated from the
tarball:

/tmp/plplot_install/share/doc/plplot/html/index.html
/tmp/plplot_install/share/doc/plplot/plplot-5.10.0.pdf
/tmp/plplot-dist-prep/plplot-5.10.0.tar.gz

In the latter, look carefully for any files that should not be part
of the source tarball.

Look at a few man pages that were generated from the tarball, e.g.,

nroff -man /tmp/plplot_install/share/man/man3/pllegend.3plplot |less

Look at the info pages that were generated from the tarball using

info /tmp/plplot_install/share/info/plplotdoc.info
_________________________________________________________________________

** Do comprehensive test of PLplot

This step depends on the steps above entitled

"Check and potentially fix internal consistency"
"Update date/versions"

Do a comprehensive test of the interactive and noninteractive
results.

scripts/comprehensive_test.sh --do_ctest no --do_test_noninteractive no
find ../comprehensive_test_disposeable -name "*.out" |grep -v a.out |xargs grep -i error
scripts/comprehensive_test.sh  --do_test_interactive no
find ../comprehensive_test_disposeable -name "*.out" |grep -v a.out |xargs grep -i error

Enter results of these and all other tests of this release into
README.release.
_________________________________________________________________________

** Create ChangeLog.release

N.B. commit all local changes to the repository so they will be
reflected in the ChangeLog, tagged version of the release, and the release
tarball.  And if there are committed changes after this one
repeat this step so the ChangeLog.release commit is the last trunk
commit for this release cycle (with the possible exception of the current
file, README.Release_Manager_Cookbook).

Prepare the ChangeLog.release file to keep track of all changes
made for the release.  Use the following commands:

# This makes the BASE used below correct.
svn update

svn log --revision BASE:<LAST_RELEASE_REVISION> --verbose  >| ChangeLog.release

(This destroys the ChangeLog.release file
from the previous release.)  LAST_REVISION should be the same as in
the generation of the preliminary version of this file above.

Check that ChangeLog.release is in the appropriate date range (i.e. only the
changes that were made since the last release should be included) then
(IMPORTANT) commit it so it will also be available for the tagged
release version, the release tarball, etc.  This should be the
last commit for the trunk version of PLplot (see remarks above
about when it is necessary to repeat this step).

Note the order of the --revision components which puts this file in
the traditional reverse chronological order (unlike the preliminary
version above which is in chronological order). 

Commit the result which ideally should be the last commit of this release.

svn commit ChangeLog.release
_________________________________________________________________________

** Create the PLplot Release

   ++ Preliminaries

Based on suggestions in the svn manual, the PLplot svn archive is configured
as follows:

/trunk
/tags/older_plplot_versions
/branches/??

For the release, you will be using svn to copy the /trunk version to
/tags/vX_Y_Z (v5_10_0 for example to follow the previous naming
conventions).

To do this strictly on the server side with no local files involved at all
use the following commands:

# Check that you have committed everything and there are no other updates you
# are unaware of.
svn update
svn status
# Complete server side copy using new SourceForge Allura version of repository.
# This is _much_ faster than copying from the local version.
svn copy https://svn.code.sf.net/p/plplot/code/trunk https://svn.code.sf.net/p/plplot/code/tags/v5_10_0

# Check out this release tag

svn checkout https://svn.code.sf.net/p/plplot/code/tags/v5_10_0 plplot_tags_5.10.0

In the event that problems are found in the release tarball generated
from the release tag, then trunk should be fixed, the trunk
ChangeLog.release
file recreated and committed (see instructions above).  Then merge the
trunk version into the tags/vX_Y_Z branch as follows:

cd tags/vX_Y_Z
svn merge -r A:B /path/to/trunk

Where A and B specify the range of revisions in trunk to be applied
to tags/vX_Y_Z in the merge process. These can be determined by commit
messages.


# IMPORTANT: use this tagged version to create the website and tarball
cd plplot_tags_5.10.0

   ++ Install and test a local copy of the PLplot website

This step depends on the steps above entitled

"Prepare and test the documentation"
"Update website-related files"
"Update release date and versions"

The step below entitled

"Upload the local website to SourceForge"

depends on this one.

Follow the exact steps given above in "Install and test a
(preliminary) local copy of the PLplot website" but this time with the
correct RELEASE_DATE and VERSION and also do this
using the files from the tagged release directory, e.g., plplot_tags_5.10.0

   ++ Upload the local website to SourceForge

Once you are satisfied with the local website, you should upload it to
SourceForge with rsync.

For the above WEBSITE_PREFIX, here is what worked for me from my computer
with the hostname of raven where that WEBSITE_PREFIX directory was
created.

rsync -av --delete \
/home/irwin/public_html/plplot/htdocs/ \
airwin,plplot@web.sourceforge.net:htdocs 

Adjust for your username and WEBSITE_PREFIX.  The ",plplot" part of the
username makes sure you have the right group permissions and default website
directory location for PLplot.  

N.B. the trailing slash on the source directory is essential and means rsync
the contents of this directory with the contents of the destination htdocs
directory.  Without the trailing slash you would rsync the the contents of
the source directory with the contents of the htdocs/htdocs destination
directory which is not what you want to do.  

N.B. the --dry-run option for rsync is a god-send and tells you exactly what
will happen without actually doing it.

Note that when changing release managers, the SF permissions are not set
up correctly to delete files belonging to the old release manager
using rsync.  (Or else we need to learn more about how to change
ownership using rsync.)

So you need to use sftp to do that, e.g.,

sftp airwin,plplot@web.sourceforge.net

Then use the 

ls -l

command to figure out who owns what and the

rm *

command on the _file_ contents of each subdirectory of htdocs, and use
the

rmdir <directory name>

command on empty directories.

Note, sftp has no recursive feature so you have to figure out the
directory structure and cd to the correct directory levels to remove
the files in each directory, ugh.  I did try the sftp chown command,
but that did not work so the only possibility I could find was the above
commands to remove htdocs and everything below it in a piece-meal fashion.

Once you have a proper upload of the local website to SourceForge, test
it as before.  Also, click the xhtml and css validate buttons on each of
index.php, download.php, examples.php, documentation.php, and credits.php
to validate those pages.

   ++ Create a final release tarball and check the result for errors

Follow the above step entitled 

"Create (a preliminary version of) the release tarball and check the result for errors"

but this time for the tagged release to make sure the tarball is exactly
consistent with the release tag.

   ++ Sign the release with your plplot Release Manager gpg key

gpg --default-key YYYYYYYY --detach-sign --armor /tmp/plplot-dist-prep/plplot-X.Y.Z.tar.gz

A list of your GPG keys can be obtained using the command "gpg --list-keys <name>".

   ++ Verify the release tarball signing
gpg --verify /tmp/plplot-dist-prep/plplot-X.Y.Z.tar.gz.asc

   ++ Make a SourceForge file release

#IMPORTANT
cd /tmp/plplot-dist-prep/

sftp airwin,plplot@frs.sourceforge.net
cd /home/frs/project/p/pl/plplot/plplot
mkdir 5.10.0\ Source
cd 5.10.0\ Source
put plplot-5.10.0.tar.gz.asc
put plplot-5.10.0.tar.gz
exit

Make, e.g., plplot-5.10.0.tar.gz, the "latest" version.

login to SF website
files ==> plplot ==> 5.10.0 Source ==> view details (the "i" icon) for
plplot-5.10.0.tar.gz ==> select "all" for the default

The above used to spin indefinitely with iceweasel.  Now it finishes
with a "properties updated" message, but it doesn't appear to "take"
immediately so check it later.

# Save a local copy of the release tarball for future reference and
# also check it.
cd /home/software/plplot_svn/HEAD/export #(or wherever)
cp -a /tmp/plplot-dist-prep/plplot-5.10.0.tar.gz* .
gpg --verify plplot-5.10.0.tar.gz.asc

Prepare concatanated release notes + Changelog.

cd plplot_tags_5.10.0
echo "

DETAILED CHANGELOG FOR THIS RELEASE

" | cat README.release - ChangeLog.release >| /tmp/README.release

cd /tmp
sftp airwin,plplot@frs.sourceforge.net
cd /home/frs/project/p/pl/plplot/plplot/5.10.0\ Source
put /tmp/README.release
exit

Create a news item for this release largely following previous
news items (or even identical to them but with a changed title).

Point your browser to http://sf.net/projects/plplot and login.  A
news item will then be available on the menu bar.  Click that, then
"new post".

Enter the title (e.g., PLplot Release 5.10.0) and the text.  Surround
the URL's in the text with angle brackets, e.g.
<http://sourceforge.net/projects/plplot/files/plplot>.

For now I simply make all paragraphs one giant line which seems
to give reasonable default results.

(15) Publicize the release announcement

Jerry: macresearch.org

Barbara Irwin: linuxtoday.com, lwn.net, lxer.com

(16) Prepare immediately for the next release cycle

  a. Preserve the historical record of the
     significant changes between versions of PLplot in one file by
     prepending README.release for 5.10.0 to OLD-README.release

cat README.release OLD-README.release > OLD-README.release_new
mv OLD-README.release_new OLD-README.release


  b. Update README.release file to reflect the start of a new release cycle.

--- Appendix ---
_________________________________________________________________________

** GNU Privacy Guard (gpg)
A brief summary of developer relevant gpg commands, see also:
http://dewinter.com/gnupg_howto/english/GPGMiniHowto.html,
man gpg, and http://www.gnupg.org/faq/GnuPG-FAQ.html.

   ++ Configure key-server (if you haven't done that already) by editing
  $HOME/.gnupg/gpg.conf.  Also specify the auto-key-retrieve option
  for convenience.

   ++ List keys on your keyring that have been retrieved or generated so far:

gpg --list-keys irwin

   ++Search for any previously published keys that you might want to
  revoke.  (Note the search phrase is case insensitive but the search
  is done on the Boolean AND of the terms so the following search would
  miss any key generated in the past by Alan Irwin because of the
  middle initial "W." that is specified for the search).  OTOH, I
  always use my middle initial for publications to reduce name clashes.

gpg --search-keys Alan W. Irwin

   ++ Create a new key:

gpg --gen-key

  With gnupg 1.4.10, I chose the following options when creating a new key:
  
Please select what kind of key you want:
  (1) RSA and RSA (default)

What keysize do you want?
2048 (default)
5-year expiration date.

....

Real name: Alan W. Irwin
Email address: airwin@users.sourceforge.net
Comment: Time Ephemerides key
You selected this USER-ID:
    "Alan W. Irwin (Time Ephemerides key) <airwin@users.sourceforge.net>"


N.B. nameofkey below is the name of the key, usually specified by the
second number after the slash for the first pub line given by
"gpg --list-keys".  For example, the above key gives the following
result:

software@raven> gpg --list-keys irwin
pub   2048R/BB159E92 2011-08-19 [expires: 2016-08-17]
uid                  Alan W. Irwin (Time Ephemerides key) <airwin@users.sourceforge.net>
sub   2048R/C5ECCF77 2011-08-19 [expires: 2016-08-17]

So the name could be BB159E92.  Other possibilities exist as well such
as "irwin", but that might not be unique.

Here is a complete recording of the gpg --edit-keys commands where I
added an additional user ID with the different comment "PLplot key" to my
existing key.  Note  this technique
could be used to add an additional user ID with a different
Real name or Email address as well.

gpg --edit-key irwin
gpg> adduid
Real name: Alan W. Irwin
Email address: airwin@users.sourceforge.net
Comment: PLplot key
Okay # to accept this added subkey
... need to enter passphrase

gpg> uid 5 # to select the new user ID for additional changes
gpg> trust # select ultimate since you ultimately trust yourself.  :-)
Your decision? 5
Do you really want to set this key to ultimate trust? (y/N) y

# Do to a gpg bug, the trust value looks like it is not updated, but
# it is so if you

gpg > save  # To save your changes, the trust value listed by

gpg --list-keys irwin

is correct.

If you make a mistake in adding a new user id.... (which happened to
me when I put down a wrong e-mail address).

gpg --edit-key irwin

adduid  (fill in correct e-mail address this time)
uid number (to select uid to work on for further commands
revuid  (revoke bad e-mail one)
primary (to make the new one the primary one, I am not sure that is necessary)
trust  (to make the new one ultimately trusted, again, not sure that is necessary.  N.B. didn't seem to change trust value, but that was just bad output)

save  (to get out again)

When edited the next time showed ultimate trust value for correct id, but
I don't know whether that was the above primary/trust subcommands or
whether those were necessary at all.  It turned out those were not
necessary at all as I later used the above sequence to generate
a libLASi key and a FreeEOS uid key.

   ++ Generate a revocation certificate.  Note this requires the pass phrase
  specified at the time of key generation so keep that pass phrase in
  a safe place or else generate the revocation certificate right after
  generating the key, and keep that certificate in a safe place.  I chose
  the former course (keep the pass phrase safe).  N.B. the options should
  appear below in the order given!

gpg --armor -o nameofkey-revocation.asc --gen-revoke nameofkey

   ++ Publicly revoke old key (from FAQ):

gpg --import old-revocation.asc
gpg --send-keys nameofkey

   ++ Upload your (public) key to GPG key server so that others can obtain it to
verify your signature on the release tarball.
gpg --send-keys nameofkey

gpg --refresh-keys  (to update from the server all keys including your own).

This verified that the bad irwin address was revoked even though
gpg --search-keys Alan W. Irwin

still shows revoked uid as the #1 uid.
_________________________________________________________________________

** (Optional) Creating a test tarball from trunk

This step is only required if you have some concerns about how
recent changes may have affected the generated source tarball, and you want
to generate that tarball and test it _before_ you create a tag for the
release.  (The release process for the tag below also generates a tarball
from the tag directory and tests it which is why this trunk version of the
same is optional.)

cd /tmp
/path-to-trunk-source/scripts/make_tarball.sh \
-w https://plplot.svn.sourceforge.net/svnroot/plplot
-c -i /tmp/trunk_install -t trunk 2>&1 | tee build.log

The above exports the current trunk
and uses 

/tmp/plplot-dist-prep/build_dir

to build the distribution source tarball

and uses

/tmp/plplot-dist-prep/ctest_build_dir

to configure and build PLplot from the unpacked tarball, ctest the build
tree, and install the built PLplot in /tmp/trunk_install

Here are the *.out files generated by this process which should be checked.

/tmp/plplot-dist-prep/build_dir/cmake.out
/tmp/plplot-dist-prep/build_dir/make_prebuild_dist.out
/tmp/plplot-dist-prep/build_dir/make_package_source.out
/tmp/plplot-dist-prep/ctest_build_dir/cmake.out
/tmp/plplot-dist-prep/ctest_build_dir/make.out
/tmp/plplot-dist-prep/ctest_build_dir/ctest.out
/tmp/plplot-dist-prep/ctest_build_dir/make_install.out

Here is how the install location should be checked:

cd /tmp/trunk_install/share/plplotX.Y.Z/examples
make >& make_examples.out
./plplot-test.sh --help  #to see what kinds of tests can be run
./plplot-test.sh --device=psc
./plplot-test.sh --device=pscairo
./plplot-test.sh --device=pngcairo
./plplot-test.sh --device=png

etc.  Check the results with, e.g.,

display x01c.pngcairo.01
display x08c.pscairo

where "display" is the general image viewer from the imagemagick suite
of programmes.
_________________________________________________________________________

** Correct computer time

(While it is useful to have the correct time on your computer, this is no 
longer strictly necessary).
Verify that your computer has the right date and time using the command date.
The easiest way to make sure the time and date are correct is to do the 
following:
1. Install the debian ntpdate package.
2. Execute the command "/usr/sbin/ntpdate pool.ntp.org", which you will
   have to do as root.
This will immediately change your system clock. It is not recommended if you
have other apps running on your system that expect time to increase in a
smooth and linear fashion.

If you would like your computer to always have the correct time and date, you 
can install the debian ntp package.  The default configuration appears
to give good results.  You can check those results by the ntpq -pe command,
e.g.,

software@raven> ntpq -dp
1 packets reassembled into response
     remote           refid      st t when poll reach   delay   offset  jitter
==============================================================================
2 packets reassembled into response
 one.tariox.com  24.150.241.178   2 u   7d 1024    0   79.179   -6.028   0.000
2 packets reassembled into response
 tor-web-02.surr 97.107.129.217   3 u  33d 1024    0   79.696   -4.199   0.000
2 packets reassembled into response
*helliana.com    128.9.176.30     2 u  580 1024  177   82.416    0.120   0.518
2 packets reassembled into response
 chelsea.ii1.net 216.218.254.202  2 u  16d 1024    0   33.252    5.646   0.000

The delay column is the round-trip travel time (in ms) to the indicated server.

The offset column is the "combined time offset" (in ms) for the
indicated server.  I assume this is the offset of that server clock from
the weighted mean of all the clocks.

The jitter column is the "exponentially-weighted rms average" for the
indicated server.  I assume it is in ms so the above jitters of 0.000
show a very small rms for those servers, i.e., a clock of extremely
high quality.