missing documentation / rant

[Martin Blais]

On Saturday 09 March 2002 16:03, Werner Koch wrote:
> On Sat, 9 Mar 2002 15:02:23 -0500, Martin Blais said:
> > these options don't know show up in the man page. someone really ought to
> > do the grunt work of cross-checking the man page documentation with the
> > actual
>
> There are reasons for this.  --dump-options is for example also not
> listed in the man page.  But hey, you have the source, so where is the
> problem.

there is no real problem, one of the users (me) is confused, and is making 
comments to the developers in order to allow them to improve the 
documentation of their software.

i'd like to know what they are? it would be nice if there was a clear 
separation between options that are shown by --help and those that aren't and 
that are explained in the man page and manual (perhaps dub them "extended" or 
"private" options?).  in any case, either the manual or documentation should 
reflect all options, right?

i understand that documentation is difficult to keep up-to-date by a 
distributed team (and the handbook is actually quite impressive), but this is 
indeed a 1.0 release and for such an important release documentation should 
be polished... i wouldn't have bothered making comments for a development 
release, because i understand that. my own system is that i make it a 
requirement to releasing, i.e. i don't allow myself to release until i've 
updated the docs. if i want to release something i have to bite the bullet 
and slave at the docs.

(and besides, sorry, but looking at the source doesn't qualify as 
documentation, which is what my comments are about. the beauty of oss is that 
i can if i want to (especially to make modifications), but that doesn't mean 
that all users of gpg SHOULD have to become acquainted with the source to 
find out what an option listed in --help is meant to do. i'm sure you'll 
agree with this.)


> > fixed (and if so, why doesn't it do that by itself?).  besides, i cannot
> > figure out how to use check-trustdb, all i get is output like this:
>
> So don't use it.  As said, there is a reason that it is not listed.

well, it IS indeed listed in "gpg --help".  i didn't mean to use it, i meant 
to understand what it does because it was listed, and is not documented, and 
that is why i was trying it. if i'm not meant to use it, then the problem is 
that it was listed.


> BTW, the next version has it mentioned because this command has a real
> use then.
>
> > also of interest:
> >     --allow-secret-key-import
> >
> > is not mentioned on the output of "gpg --help". i'm sure there are many
>
> If you try to import a secret key, a messge is printed, telling you to
> use this option.  Anyway, this option is just a temporary hack and not
> anymore needed in 1.0.6d.  Printing all 202 commands and options with

cool.


> --help make no sense, it is just too much and can't probably not be
> understood without a more verbose description.  Anyway, recent
> versions do print:
>
>       --photo-viewer               Set command line to view Photo IDs
>    -N, --notation-data NAME=VALUE   use this notation data
>

>   (See the man page for a complete listing of all commands and options)

that's exactly my point!  is at least the man page complete? options that are 
listed in --help should at least also be in the man page. the opposite is not 
necessarily true, and some kind of grouping to acknowledge that is a nice way 
to let the user understand this (something like "basic options" and "extended 
options").



> There is nothing important missing, some things are maintainer only.
> If you or the people attracted by encryption real want to get into it,
> use the source.

those maintainer-only options should then not be visible to the user if he's 
not to use them. all i'm arguing for, is that the maintainer/for-debug 
options be somehow marked as such or not visible.


> > another big one (for me and other friends): the default behaviour for
> > "gpg file.gpg" is to decrypt to a file "file", and apart from asking for
> > the passphrase it doesn't say it has output the PLAINTEXT to a FILE. the
>
> Which is the correct behaviour of a Unix tool.  Use --verbose to get
> what you want.

agreed, read on...


> > lies in the filesystem!  that is a big problem!  IMHO that should not be
> > the default behaviour, the default, just as for input, should be that it
> > outputs to stdout, just like --decrypt does, and that using --decrypt
> > should output
>
> A lot of tools do have this behaviour and it makes a lot of sense. IF
> you want to have the output on stdout, send the input to stdin.

i know i can use --decrypt and i do now (actually, you make me think, i'll 
try putting it in my options file).

well, please consider that a default behaviour of writing plaintext files out 
to the filesystem is behaviour that does not foster trust in a program that 
is meant to provide data security for its user. i mean, there is a reason for 
that file to be encrypted in the first place. if i considered my filesystem 
permissions to be secure i probably wouldn't use encryption to store files on 
it.

i have often forgotten to delete unencrypted files because of that (and even 
sometimes on my cd backups, which were recently robbed with the rest of the 
computing equipment. not a cool feeling. i agree that it is my fault because 
i misused gpg, but food for thought anyway. IMHO plaintext should only be 
written to files on request. consider it a security feature, and not a minor 
one---the user is less likely to make the mistake of decrypting to disk.)

thanks for your quick answer.
cheers,