Re: bug in sort manpage: -k syntax is wrong

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Jeff Lerman on 8/26/2008 10:48 AM:
> I note that in the manpage for the "sort" utility, the -k flag syntax
> claims that an "=" should be used between the flag and the argument(s).

Thanks for the report.  However, this is a misunderstanding on your part:

> Quoting:
> 
>        -k, --key=POS1[,POS2]
> 
>               start a key at POS1, end it at POS2 (origin 1)

Coreutils in general (and for that matter, several other GNU applications)
use the following notational conventions:

- -k, --key=...  => required argument, usable as one of:
sort -k 1    (preferred short form)
sort -k1     (supported, but not preferred)
sort --key=1 (preferred long form)
sort --key 1 (supported, but not preferred)

- --help => no argument, no short form, usable as:
sort --help  (only form)

- -r, --reverse => no argument, both short and long
sort -r -k 1 (preferred short form)
sort -rk1    (concatenation of short args is supported, but not preferred)
sort --reverse (only supported long form)

And finally, in some other programs, you might see optional arguments:

- -d, --debug[=...] => optional argument, usable as one of:
m4 -d        (argument omitted, short form)
m4 --debug   (argument omitted, long form)
m4 --debug=  (argument explicitly empty, only possible with long form)
m4 -da       (argument a, short form)
m4 --debug=a (argument a, long form)


> 
> This is incorrect and results in an error from "sort.  The correct
> syntax omits the "=" and allows but does not require whitespace between
> -k and the argument(s).

Correct.  But that is already implied by the conventions spelled out
above, so although the --help output/man page is terse, it is correct once
you understand the conventions.  Perhaps the info documentation should go
into more details on all the forms (the node Common Options would be the
right place to put it all); care to write a patch, perhaps using this
email as the starting point?

> The syntax for other flags may also be similarly affected - have only
> tested -k.  I see this error in the manpage for 5.93 under Linux (seen
> under Suse), and it also appears in the January 2008 version 6.10
> manpage (seen under Cygwin).

The man pages are generated from the --help output, and are necessarily
terse.  Refer to the info documentation for more details.

> This email message (and any attached document) contains information from 
> Ingenuity Systems Inc. which may be considered confidential

A word of advice - it is considered poor netiquette to send mail to
publicly archived mailing lists from an account that adds an unenforceable
legal disclaimer.  Some people refuse to reply to such email on principle.
 Please consider using an alternate email account.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAki0o0oACgkQ84KuGfSFAYBQigCeJMP1dywnzWl34AoC8vch9B+V
MfgAn1j++zW4NbuejL2OKyepkQMt2kR1
=3tEC
-----END PGP SIGNATURE-----