Improve man page for verify and --compare-data

[Aaron Whitehouse]

It likely needs some tweaks, but we should change the man page for verify/--compare-data to read something like:
"Enter verify mode instead of restore. Verify tests the integrity of the backup archives at the remote location by downloading each file and checking both that it can restore and that the restored file matches the signature of that file stored in the backup, i.e. compares the archived file with its hash value at archival time. Verify does not actually restore and will not overwrite any local files. If the --file-to-restore option is given, it will restrict verify to that file or directory. The --time option allows the selection of a specific backup to verify. Duplicity will exit with a non-zero error level if any files do not match the signature stored in the archive for that file. On verbosity level 4 or higher, it will log a message for each file that differs from the stored signature. Files must be downloaded to the local machine in order to compare them. Verify does not compare the backed-up version of the file to the current local copy of the files unless the --compare-data option is used (see below)."

"--compare-data
This conducts a verify to verify the integrity of the backup archives, but additionally compares restored files to those in target_directory to test that the remote archive could be restored to exactly match the local files. Duplicity will not replace any files in target_directory. Duplicity will exit with a non-zero error level if the files do not correctly verify or if any files from the archive differ from those in target_directory."

These topics have been discussed at length. A non-exhaustive list of links is:
http://lists.nongnu.org/archive/html/duplicity-talk/2014-07/msg00016.html
A long rundown of what verify actually does. Also https://answers.launchpad.net/duplicity/+question/116587

https://bugs.launchpad.net/duplicity/+bug/643973
The bug to add --compare-data option (comparison to local files)

https://bugs.launchpad.net/duplicity/+bug/1354880
And, after that, the changes to verify to stop it compare anything with the filesystem (mtime, permissions or file contents etc) unless the --compare-data is used

We've mentioned changing the man page a few times, but have not yet done it.

[Aaron Whitehouse (aaron-whitehouse)]

Revised explanation of verify:
"Verify tests the integrity of the backup archives at the remote location by downloading each file
and checking both that it can restore the archive and that the restored file matches the signature
of that file stored in the backup, i.e. compares the archived file with its hash value from archival
time. Verify does not actually restore and will not overwrite any local files. Duplicity
will exit with a non-zero error level if any files do not match the signature stored in the archive
for that file. On verbosity level 4 or higher, it will log a message for each file that differs
from the stored signature. Files must be downloaded to the local machine in order to compare them.
Verify does not compare the backed-up version of the file to the current local copy of the files
unless the --compare-data option is used (see below)."

Revised explanation of --compare-data:
"Enable data comparison of regular files on action verify. This conducts a
verify as described above to verify the integrity of the backup archives,
but additionally compares restored files to those in target_directory.
Duplicity will not replace any files in target_directory. Duplicity will
exit with a non-zero error level if the files do not correctly verify or
if any files from the archive differ from those in target_directory. On
verbosity level 4 or higher, it will log a message for each file that
differs from its equivalent in target_directory."