Taxonomy and hierarchy of "common" include files

These notes are intended to help QA script developers understand
the set of common include files that are provided in the PCP qa
(aka testsuite) directory.

Most QA scripts are generated by ./new and contain the
following includes in order:

    common.product
      - included first by all the qa tests (at least the ones created
	with ./new)
      - includes common.setup and localconfig

	common.setup
	  - includes common.rc if not already included

	    common.rc
	      - includes $PCP_DIR/etc/pcp.env
	      - sets $PATH
	      - sets $sudo
	      - sets $here
	      - sets $tmp

	localconfig
	  - sets $PCP_PLATFORM and $PCP_VER

    common.filter
      - included second by all the qa tests (at least the ones created
	with ./new)
      - all of the _filter_foo() and related functions

    common.check
      - included third by all the qa tests (at least the ones created
	with ./new)
      - sets $here if not already set

Alternatively, QA scripts can include one of the following wrappers
which themselves include common.product, common.filter and common.check
in that order along with other service-specific initialization.

    common.avahi
    common.compress
    common.discovery
    common.containers
    common.gfs2
    common.pcpweb
    common.python
    common.qt
    common.secure

And QA scripts may include these optional "common" files after the
other ones:

    common.config
      - includes localconfig
      - sets environment-specific things like $PCPQA_CLOSE_X_SERVER,
        $PCPQA_FAR_PMCD, $PCPQA_HYPHEN_HOST, $PCPQA_SOCKS_SERVER and
        $PCPQA_CISCO_ROUTER.

common.install.cisco

common
  - starting point for all of ./check, ./remake, ./show-me
  - includes common.check and common.setup
  - sets $here
