docs+man: Add documentation for the --wrapper feature.

Add documentation manual page part for the command line
feature `--wrapper`.
Signed-off-by: NRudá Moura <rmoura@redhat.com>

docs/source/WrapProcess.rst

+Wrap process in tests
+=====================
+
+Avocado allows the instrumentation of applications being
+run by a test in a transparent way.
+
+The user specifies a script ("the wrapper") to be used to run the actual
+program called by the test.  If the instrument is
+implemented correctly, it should not interfere with the test behavior.
+
+So it means that the wrapper should avoid to change the return status,
+standard output and standard error messages of the process.
+
+The user can optionally specify a target program to wrap.
+
+Usage
+-----
+
+This feature is implemented as a plugin, that adds the `--wrapper` option
+to the Avocado `run` command.  For a detailed explanation please consult the     
+avocado man page.
+
+Example of a transparent way of running strace as a wrapper::
+
+    #!/bin/sh
+    exec strace -ff -o $AVOCADO_TEST_LOGDIR/strace.log -- $@
+
+
+Now you can run::
+
+    # run all programs started by test.py with ~/bin/my-wrapper.sh
+    $ scripts/avocado run --wrapper ~/bin/my-wrapper.sh tests/test.py
+
+    # run only my-binary (if/when started by a test) with ~/bin/my-wrapper.sh
+    $ scripts/avocado run --wrapper ~/bin/my-wrapper.sh:my-binary tests/test.py
+
+
+Caveats
+-------
+
+* It is not possible to debug with GDB (`--gdb-run-bin`) and use
+  wrappers (`--wrapper`), both options together are incompatible.
+
+* You cannot set multiples (global) wrappers
+  -- like `--wrapper foo.sh --wrapper bar.sh` -- it will trigger an error.
+  You should use a single script that performs both things
+  you are trying to achieve.
+
+* The only process that can be wrapper are those that uses the Avocado
+  module `avocado.utils.process` and the modules that make use of it,
+  like `avocado.utils.build` and so on.
+
+* If paths are not absolute, then the process name matches with the base name,
+  so `--wrapper foo.sh:make` will match `/usr/bin/make`, `/opt/bin/make`
+  and  `/long/path/to/make`.
+
+*  When you use a relative path to a script, it will use the current path
+   of the running avocado program.
+   Example: If I'm running avocado on `/home/user/project/avocado`,
+   then `avocado run --wrapper examples/wrappers/strace.sh datadir`  will
+   set the wrapper to `/home/user/project/avocado/examples/wrappers/strace.sh`

docs/source/index.rst

@@ -23,6 +23,7 @@ Contents:
    VirtualMachinePlugin
    RemoteMachinePlugin
    DebuggingWithGDB
+   WrapProcess
    ContributionGuide
    api/modules
 

man/avocado.rst

@@ -310,6 +310,46 @@ In this example, `/tmp/disable-signals` is a simple text file containing two lin
 Each line is a GDB command, so you can have from simple to very complex
 debugging environments configured like that.
 
+WRAP PROCESS IN TESTS
+=====================
+
+Avocado allows the instrumentation of applications being
+run by a test in a transparent way.
+
+The user specify a script ("the wrapper") to be used to run the actual
+program called by the test.  If the instrument is
+implemented correctly, it should not interfere with the test behavior.
+
+So it means that the wrapper should avoid to change the return status,
+standard output and standard error messages of the process.
+
+By using an optional parameter to the wrapper, you can specify the
+"target binary" to wrap, so that for every program spawned by the test,
+the program name will be compared to the target binary.
+
+If the target binary is absolute path and the program name is absolute,
+then both paths should be equal to the wrapper take effect, otherwise
+the wrapper will not be used.
+
+For the case that the target binary is not absolute or the program name
+is not absolute, then both will be compared by its base name, ignoring paths.
+
+Examples::
+
+ $ avocado run datadir --wrapper examples/wrappers/strace.sh
+ $ avocado run datadir --wrapper examples/wrappers/ltrace.sh:make \
+                       --wrapper examples/wrappers/perf.sh:datadir
+
+Note that it's not possible to use ``--gdb-run-bin`` together
+with ``--wrapper``, they are incompatible.::
+
+ $ avocado run mytest --wrapper examples/wrappers/strace:/opt/bin/foo
+
+In this case, the possible program that can wrapped by ``mytest`` is
+``/opt/bin/foo`` (absolute paths equal) and ``foo`` without absolute path
+will be wrapped too, but ``/opt/bin/foo`` will never be wrapped, because
+the absolute paths are not equal.
+
 RECORDING TEST REFERENCE OUTPUT
 ===============================