README wording changes for consistency with public website

Wording improvements:

* Consistency with the subtitle on the public website at
  http://stb-tester.com/

* Reference the location of the LICENSE file because this README /
  manpage can be viewed at http://stb-tester.com/stbt.html or from
  `man`.

* Grammar

And add a link to stb-tester.com, for those viewing the README from
github, from a checkout of the source, or from `man`.
README: Recommend decodebin2 over decodebin

"decodebin2 is considered stable now and replaces the old decodebin
element"
-- http://gstreamer.freedesktop.org/data/doc/gstreamer/head/gst-plugins-base-plugins/html/gst-plugins-base-plugins-decodebin2.html
jenkins-stbt-run: Shell script to be run by Jenkins

Runs the stbt scripts specified on the command line; creates logfiles
(stdout, stderr, result code, stbt's failure screenshot) as "build
artifacts" in the location expected by Jenkins; and generates an xUnit
xml file with the test results.

jenkins-stbt-run doesn't return a failure exit status if the test
scripts fail; a failure exit status means an error in the script itself.
Instead configure the Jenkins xUnit plugin to consider the job as
"failed" or "unstable" above 0 failing tests.

I didn't find any conclusive documentation on the xUnit xml format; the
closest was this schema:
https://svn.jenkins-ci.org/trunk/hudson/dtkit/dtkit-format/dtkit-junit-model/src/main/resources/com/thalesgroup/dtkit/junit/model/xsd/junit-4.xsd

Jenkins groups the test results by "package" and "classname", which it
takes from the dot-separated names in the "name" attribute of the
"testsuite" xml element.

Note that I don't need to put quotes around parameter (variable)
expansions, even when the variables could contain spaces, because
jenkins-stbt-run modifies IFS so that word-splitting after parameter-
expansion doesn't split on spaces. This is necessary in case the test
script paths themselves contain spaces. I do need the quoting in the
argument to `trap`, because it is expanded once as a string and then
evaluated later.

jenkins-stbt-run cleans out $WORKSPACE before each invocation. In spite
of having configured the Jenkins job to "Wipe out workspace before
build" (under "Source code management" > "Git" > "Advanced") the whole
workspace isn't cleared out; only the git repository containing the test
scripts. So if a test script succeeded, but had failed in a previous
run, the failure screenshot was still lying around and captured by
Jenkins as a "build artifact".

JENKINS CONFIGURATION
=====================

Nodes
-----

Install the Jenkins SSH Slaves plugin.

A "slave" or "node" is a PC with video-capture and remote-control
connections to the set-top box under test. Jenkins will connect to the
slave and run `jenkins-stbt-run` on the slave. Jenkins requires java and
"jenkins.jar" to be running on the slave; the "SSH Slaves" plugin merely
connects to the slave via ssh and installs and runs jenkins.jar, so that
you don't have to do that installation manually.

At the Jenkins index page:

Manage Jenkins > Manage nodes > New Node

* # of executors: 1
* Remote FS root: /home/stb-tester
* Launch method: Launch slave agents on Unix machines via SSH
* Host: the slave's hostname or ip address
* Username: stb-tester
* Private key file: Path (on the Jenkins master) to the ssh key
  (add the corresponding public key to ~stb-tester/.ssh/authorized_keys
  on the slave)

Jobs
----

Create a new Jenkins job (aka project):

* Restrict where this project can be run
  Label expression: the name of the node(s) to run this job

  Note that the entire job (all its stbt scripts) will be run on a single
  slave; this system (currently, at least) doesn't split the job across
  multiple slaves. Specifying multiple slaves (nodes) here means that
  Jenkins will pick one of the available nodes to run this job.

* Build > Execute shell
  Command: /home/stb-tester/jenkins-stbt-run tests-repo/path/to/test_directory

  where "tests-repo" is a repository containing your stbt scripts, which
  will be checked out by Jenkins according to your configuration in the
  job's "Source Code Management" section. "path/to/test_directory" is
  any path within that repo. Don't include "test.py", just the directory
  containing "test.py". You can also specify a parent directory
  containing multiple stbt scripts: jenkins-stbt-run looks for
  **/test.py under the path you specify. You can specify multiple paths
  on this command line.

xUnit
-----

Install the xUnit plugin.

In the job/project:

* Configure > Post-build actions > Publish xUnit test result report; then

* Add > JUnit > JUnit Pattern: results.xml
  (This is the path to the xml file generated by jenkins-stbt-run,
  relative to the Jenkins workspace.)

Build artifacts
---------------

In the job/project:

* Post-build actions > Archive the artifacts
* Files to archive: runs/

stbt scripts
------------

Install the plugin for your source-control system (git, svn, etc.).

Configure the Jenkins job to checkout the repository containing your
stbt test scripts into a subdirectory of the workspace (so it won't
conflict with files generated by jenkins-stbt-run in the workspace).

SLAVE CONFIGURATION
===================

The slave must have a user (say, "stb-tester") that Jenkins connects as
(specified in the Jenkins "nodes" configuration). This user's
~/.ssh/authorized_keys must include Jenkins' public key so that the
Jenkins master can connect to the slave without entering a password.
Test this configuration by `ssh`ing from the Jenkins master to the
slave; you have to do this at least once to avoid the warning "the
authenticity of host ... can't be established. Are you sure you want to
continue connecting?".

The user that Jenkins connects as must have permission to read from
/dev/video0 -- on my Linux distribution I had to add the user to group
"video".

The slave must have `stbt` installed and available on the PATH.

The slave must have `jenkins-stbt-run` available. It doesn't have to
be on the PATH because when you configure the Jenkins job you can give
a full path to `jenkins-stbt-run`.

The slave must have a `stbt.conf` with the correct configuration for
stbt (the correct gstreamer source pipeline, the set-top box's IP
address if using the virtual remote control, etc.). Set `sink_pipeline =
fakesink`.

You can place this config file in ~/.config/stbt/stbt.conf or else in
any location you like and set STBT_CONFIG_FILE in the Jenkins job
configuration.

Note that I had to set DISPLAY=:0.0, and run "xhost +" on the slave,
even though stbt.conf configures "sink_pipeline = fakesink" (i.e. no
video is shown on the slave's screen) because stbt.py's "import gtk"
actually requires a connection to the X display. (This is something that
should be fixed in stb-tester.)

The slave must be able to connect to your source-control server (to
checkout or update the repository containing the test scripts) without
a password.
Don't read configuration from $PWD/stbt.conf

This was a bad idea. It caused too much confusion, when running a `stbt
run` command from one directory worked correctly but from a different
directory failed. Use the environment variable STBT_CONFIG_FILE instead.
Makefile: Rename PREFIX and SYSCONFDIR to standard lowercase naming

See
http://www.gnu.org/software/make/manual/html_node/Directory-Variables.html
Makefile: Use standard $(libdir) etc

See
http://www.gnu.org/software/make/manual/html_node/Directory-Variables.html
gstreamer plugin: Boilerplate C code for stbt-motiondetect element

It's called STBT-motiondetect because we plan to move the templatematch
element from gst-opencv/gst-plugins-bad here to stb-tester (so that we
can make custom modifications to the image matching algorithm that
probably won't be of generic interest); we will call that element
stbt-templatematch so that it won't clash for users with gst-opencv
installed, so the name "stbt-motiondetect" is consistent with that
future element.

The stbt-motiondetect element doesn't actually do anything yet, but all
the GObject boilerplate and the Makefile to build it is in place.

This does compile and work in a gstreamer pipeline:

    GST_PLUGIN_PATH=/path/to/stb-tester/gst \
    gst-launch \
        videotestsrc ! ffmpegcolorspace ! stbt-motiondetect ! \
        ffmpegcolorspace ! ximagesink
gstreamer plugin: Implement stbt-motiondetect element

stbt-motiondetect is a no-op when its "enabled" property is false. When
enabled, it analyses successive frames and issues a bus message, with
boolean parameter "has_motion", for every frame.

The intent of this element is to allow stbt scripts to detect when video
is or isn't playing.
Automated tests for stbt-motiondetect element
stbt-run: add function "wait_for_motion" available to stbt scripts

Uses the newly-added stbt-motiondetect gstreamer element. The python
code is virtually identical to that for templatematch.
Merge branch 'motiondetect'

Adds function "wait_for_motion", available to stbt scripts to assert
that video is playing.

Adds a new gstreamer plugin "libgst-stb-tester.so" with the element
"stbt-motiondetect", used by "wait_for_motion".

* motiondetect:
  stbt-run: add function "wait_for_motion" available to stbt scripts
  Automated tests for stbt-motiondetect element
  gstreamer plugin: Implement stbt-motiondetect element
  gstreamer plugin: Boilerplate C code for stbt-motiondetect element
  Makefile: Use standard $(libdir) etc
  Makefile: Rename PREFIX and SYSCONFDIR to standard lowercase naming
gsttemplatematch element copied from gst-plugins-bad RELEASE-0.10.21

I am copying the templatematch element here because we need to customise
its matching algorithm in a way that is not necessarily applicable to
other users of templatematch.
gsttemplatematch: make work with openCV 2.2

https://bugzilla.gnome.org/show_bug.cgi?id=641796
Build templatematch element as part of libgst-stb-tester.so plugin

I register the element as "stbt-templatematch" so that it can coexist
with an installation of gst-plugins-bad's original templatematch.
templatematch: Remove no-op call to gst_templatematch_load_template

We have just set filter->template to NULL, so
gst_templatematch_load_template did nothing.
templatematch: Allow changing template property on the fly

Previously changing the template property resulted in an exception
thrown from cvMatchTemplate, because "dist_image" (the intermediate
match-certainty-distribution) was the wrong size (because the
template image size had changed).
Makefile: Cleanup internal order of various targets

I'm aiming for the best order for reading top-to-bottom for someone new
to this project/Makefile.

First the customisation points that can be set on the command line, e.g.

    make install prefix=/usr

Next the project's dependencies, makefile variables (VERSION), and
configuration of the behaviour of `make` (.DELETE_ON_ERROR). I thought
about moving OBJS down to where the details of building the gstreamer
plugin are, but the dist target needs OBJS to have been set.

Next the main targets of interest: all, install, doc, clean, check, dist
(the aim is that the reader can see the main targets available, without
being overwhelmed with details).

Finally the details of building the gstreamer plugin.
templatematch: Pass video through when nothing to match against

The early return was bypassing the call to gst_pad_push. With no
filter->template (and thus no filter->cvTemplateImage) the rest of this
function is essentially a no-op (except for the call to gst_pad_push).

This (plus the previous commit) allows templatematch to be
enabled/disabled without removing it entirely from the pipeline, by
setting/unsetting the template property.
Makefile: Add missing files to dist tarball

The gstreamer plugin, the tests and the bash-completion script were
missing from the dist tarball.

This also includes .gitignore which probably isn't of interest to a
non-git source distribution, but using `git ls-files` guarantees I
won't forget to include a file again.
templatematch: Add locking around filter properties

To allow changing the properties (e.g. the pattern to match) while the
pipeline is playing.

* gst_element_post_message is moved outside of the lock, because it will
call into arbitrary user code (otherwise, if that user code calls into
gst_templatematch_set_property on this same thread it would deadlock).

* gst_template_match_load_template: If we fail to load the new template
we still unload the previous template, so this element becomes a no-op
in the pipeline. The alternative would be to keep the previous template;
I believe unloading the previous template is a better choice, because it
is consistent with the state this element would be in if it fails to
load the very first template at start-up.