Mailing List Archive

Clarification in man page? (was Re: Cannot import private key)
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

_______________________________________________
Gnupg-users mailing list
Gnupg-users@gnupg.org
http://lists.gnupg.org/mailman/listinfo/gnupg-users
Re: Clarification in man page? [ In reply to ]
On Fri, 20 Apr 2012 14:29, peter@digitalbrains.com said:

> 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.

That is not a general Unix feature but a GNU feature.

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

gpg from master does this:

$ gpg2 foo --armor
gpg: NOTE: `--armor' is not considered an option
usage: gpg [options] [filename]

If you really want --armor as a filename, the warning will of course not
be shown

$ gpg2 -- foo --armor
usage: gpg [options] [filename]

> 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.

And that is actually the case. The difference between commands and
options is that you may only have one command.


Salam-Shalom,

Werner

--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.


_______________________________________________
Gnupg-users mailing list
Gnupg-users@gnupg.org
http://lists.gnupg.org/mailman/listinfo/gnupg-users
Re: Clarification in man page? [ In reply to ]
On 4/20/2012 7:17 AM, Werner Koch wrote:
> On Fri, 20 Apr 2012 14:29, peter@digitalbrains.com said:
>
>> 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.
>
> That is not a general Unix feature but a GNU feature.

I use/develop for a lot of different Unix', it's pretty commonly
accepted at this point.

>> Werner, perhaps it is an idea to have the man page more explicit that all
>> options *must* come before the command?
>
> gpg from master does this:
>
> $ gpg2 foo --armor
> gpg: NOTE: `--armor' is not considered an option
> usage: gpg [options] [filename]

That looks like a good change.

>> 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.
>
> And that is actually the case. The difference between commands and
> options is that you may only have one command.

To the OP, rather than saying, "Can you write better docs?" how about
proposing changes that make sense to you? Not only is that closer to the
open source model, it's notoriously hard for developers to document
their own work, since it all makes perfect sense to us. :)

Doug

--
If you're never wrong, you're not trying hard enough

_______________________________________________
Gnupg-users mailing list
Gnupg-users@gnupg.org
http://lists.gnupg.org/mailman/listinfo/gnupg-users
Re: Clarification in man page? [ In reply to ]
On 20/04/12 16:17, Werner Koch wrote:
> $ gpg2 foo --armor
> gpg: NOTE: `--armor' is not considered an option
> usage: gpg [options] [filename]
>
> If you really want --armor as a filename, the warning will of course not
> be shown

Why is --armor dropped when it is not wanted as a filename?

> And that is actually the case. The difference between commands and
> options is that you may only have one command.

I think you misread what I meant :). Confusion all around!

I have this command:

$ gpg2 -a -o foo.asc --export de500b3e

Now if commands and options are equal citizens in the land of the command line,
I think this should also work:

$ gpg2 --export de500b3e -a -o foo.asc

All I did was change the order; the only difference between commands and options
is how many are allowed in one command line. I stuck by the rule as I read it.

However, it doesn't do the same.

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

_______________________________________________
Gnupg-users mailing list
Gnupg-users@gnupg.org
http://lists.gnupg.org/mailman/listinfo/gnupg-users
Re: Clarification in man page? [ In reply to ]
On 20/04/12 18:55, Doug Barton wrote:
> To the OP, rather than saying, "Can you write better docs?" how about
> proposing changes that make sense to you? Not only is that closer to the
> open source model, it's notoriously hard for developers to document
> their own work, since it all makes perfect sense to us. :)

Because clarifying the docs is "non-invasive". If you change the way gpg parses
its options, you risk breaking scripts people wrote and such. Plus, there is a
good chance the parsing was deliberately designed the way it is :). So rather
than challenge the design, I chose clarifying it instead. You could say I chose
the lazy way (of least resistance).

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

_______________________________________________
Gnupg-users mailing list
Gnupg-users@gnupg.org
http://lists.gnupg.org/mailman/listinfo/gnupg-users
Re: Clarification in man page? [ In reply to ]
On Sat, 21 Apr 2012 11:55, peter@digitalbrains.com said:

> Why is --armor dropped when it is not wanted as a filename?

Sorry, I don't understand you. There is just a note telling the novice
that --armor is not an option.


Shalom-Salam,

Werner



--
Die Gedanken sind frei. Ausnahmen regelt ein Bundesgesetz.


_______________________________________________
Gnupg-users mailing list
Gnupg-users@gnupg.org
http://lists.gnupg.org/mailman/listinfo/gnupg-users
Re: Clarification in man page? [ In reply to ]
On 21/04/12 19:54, Werner Koch wrote:
> Sorry, I don't understand you. There is just a note telling the novice
> that --armor is not an option.

Okay, I initially misunderstood. Never mind.

When one of the arguments to --export does not actually match a key in the
keyring, GnuPG v2.0.18 silently ignores it. That means that if --armor does not
match a key, it is effectively ignored when specified after --export.

I like the note, it is definitely clarifying.

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

_______________________________________________
Gnupg-users mailing list
Gnupg-users@gnupg.org
http://lists.gnupg.org/mailman/listinfo/gnupg-users