Package: duplicity
Version: 0.4.1-8
Severity: wishlist
Here are a couple suggested enhancements for the duplicity(1) man page.
There are four reasonably standard man page sections missing: SYNTAX,
ENVIRONMENT, EXIT STATUS, and ERRORS. These would all be useful, and
are a good way to organize a man page to make it terse, easy to scan
for desired information, and complete.
Here, the SYNTAX section would briefly describe the syntax and
semantics of URLs accepted. Here is my own tentative list, which is
basically what I remembered from the FAQ plus editing down
$ man duplicity | tr ' ' '\n' | egrep ':.' | sort | uniq
file:///usr/local/backup
ftp://[EMAIL PROTECTED]/some_dir
scp://[EMAIL PROTECTED]//dir-root-relative
scp://[EMAIL PROTECTED]/dir-below-home-dir
(I don't know if file://dir is legal, and if so whether it corresponds
to /dir or to ~/dir or to ./dir .)
In debugging, or writing scripts, it can be helpful to have an
exhaustive list of environment variables. The ones I know of are
PASSPHRASE and FTP_PASSWORD, currently not clustered in the man page.
Are there more? Not in the man page, but ...
The exit status of duplicity under normal use is unclear as currently
written, as is its ways of dealing with anomolous situations of
varying severity, including those that might often arrise in practice.
This makes it hard to write robust scripts or to scan error logs.
What happens if a file is deleted between being noticed for backup and
being read: does this cause a printed warning? An error? Does the
exit status of the invocation of duplicity reflect this condition?
What about unreadable files, due to permissions? What about
filesystem anomalies, like an NFS problem or a disk error? What if
the target URL is inaccessible: do I get any details about what
happened? By having and ERRORS section, when the program is modified
to detect and handle another problem, it is easy to know how to update
the man page.
Last suggestion: the OPTIONS section lists
--encrypt-key key
Of couse that is *not* a key, at least not when using gpg. It is
rather a string that identifies a key available on the keyring.
Maybe this
--encrypt-key gnupg-key-name
would be better, for consistency with the notation used in gpg(1).
--
Barak A. Pearlmutter <[EMAIL PROTECTED]>
Hamilton Institute, NUI Maynooth, Co. Kildare, Ireland
http://www-bcl.cs.nuim.ie/~barak/
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
