Improve manpage description of "verify" option

[Aaron Whitehouse]

Following on from the (somewhat messy) Answer here:
https://answers.launchpad.net/duplicity/+question/116587
I believe that the manpage could better-describe how verify works.

The current manpage excerpts relating to verify are:
"
SYNOPSIS
duplicity verify [options] source_url target_directory
[…]

EXAMPLES
The following command compares the files we backed up, so see what has changed since then:
duplicity verify scp://<email address hidden>/some_dir /home/me
[…]

ACTIONS
verify
Enter verify mode instead of restore. If the --file-to-restore option is given, restrict verify to that file or directory. duplicity will exit with a non-zero error level if any files are different. On verbosity level 4 or higher, log a message for each file that has changed.
"

I suggest (as a starting point for improvement) that this be changed to:
"
EXAMPLES
The following command tests the integrity of the backup archives at the remote location by checking each file can restore and that the restored file matches the signature of that file stored in the backup:
duplicity verify scp://<email address hidden>/some_dir /home/me
[…]

ACTIONS
verify
Enter verify mode instead of restore. Verify tests the integrity of the backup archives at the remote location by checking each file can restore and that the restored file matches the signature of that file stored in the backup. Verify does not actually restore and will not overwrite any local files. If the --file-to-restore option is given, restrict verify to that file or directory. 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, log a message for each file that has changed. 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.
"

Some comments in the above Answer report that verify notes changes in the metadata of local files. That does not seem in line with what I now understand it to do. It would be great if someone (Ken?) could clarify this point.

[edso (ed.so)]

we really should remove the functionality that verify in addition to checking the backups integrity is comparing dates/modtimes with the backups source.

here a citation from the mailing list lately:
-->
> 2. Why we get 'Difference found: File etc/resolv.conf has mtime Wed Jan 19 09:49:14 2011, expected Wed Jan 19 00:21:25 2011' lines on this process?

confusing isn't it. For reasons not transparent to me, additionally to verifying the backed up data, verify also compares the date with the source. This should be removed from my point of view. It could be part of a new command compare, which actually really compares backup with source.
<--

ede

[Aaron Whitehouse (aaron-whitehouse)]

Ede, see Bug #1354880 for the point addressed in your comment.

[Aaron Whitehouse (aaron-whitehouse)]

Superseded by Bug #1354880 , --compare-data etc.