Clarification in man page? (was Re: Cannot import private key)

[Peter Lebbing]

On 19/04/12 14:38, Scott Armitage wrote:
> For the record, I was using redirectors instead of the "-o" option
> because apparently it has no effect (at least in Powershell on
> Windows) if you use it after the --export option. I have now figured
> out that I can use "-ao <file.asc>" before the "--export-secret-key
> <key_id>" and everything works fine:

Yes, this is a property of the GnuPG command line that more people don't seem to
realise, that all options *must* come before the command. I initially missed it
myself, and I've seen it mentioned by others on this mailing list. At least on
*nix, it's relatively common that options can come in any position of the arguments.

Werner, perhaps it is an idea to have the man page more explicit that all
options *must* come before the command?

The man page does say in two locations (section COMMANDS and section OPTIONS):

> Please remember that option as well as command parsing stops as soon as  a  non-option  is
> encountered, you can explicitly stop parsing by using the special option --.

However, the significance of this statement is perhaps lessened by the first
sentence of the section COMMANDS:

> Commands  are  not distinguished from options except for the fact that only one command is
> allowed.

I think this sentence is easily misunderstood; in fact, I doubt the statement
can be made true. I read this as: since they are not distinguished, I can put
the (single) command in any old place I can put an option in.

While the very important difference between commands and options is that the
command comes after the options, and definitely not the other way around.

My suggestion would be to change the sentence

> Commands  are  not distinguished from options except for the fact that only one command is
> allowed.

to something like

> Only one command is allowed, and all options need to come before the command.
> If the command itself takes arguments, these come after the command.

Hmmmmm...

...

I just notice, this does work:

$ gpg2 -e -r <keyid> -o foo.gpg
$ gpg2 -r <keyid1> -o foo.gpg -e -r <keyid2>
etc...

All wanted keyid's get encrypted to, and foo.gpg is the output file.

Is perhaps the point that when a command can take multiple arguments, like
--export can, that the rest of the command line coming after the command is
always interpreted as arguments to the command? Still, it might be best to
educate users to put the options first, and then be liberal in what you actually
accept.

Peter.

-- 
I use the GNU Privacy Guard (GnuPG) in combination with Enigmail.
You can send me encrypted mail if you want some privacy.
My key is available at http://wwwhome.cs.utwente.nl/~lebbing/pubkey.txt