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

[Bob Proulx]

Jeff Lerman wrote:
> 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).
>        -k, --key=POS1[,POS2]
>               start a key at POS1, end it at POS2 (origin 1)
> 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).

Thanks for taking the time to write to us.  You are right but you are
also wrong.  You are looking at the 'sort --help' output which is
designed as a very compact online help reference guide.  It doesn't
have the space to be fully verbose.  What you are seeing is the
standardized way of describing options in GNU programs.  The coding
standards require GNU programs to accept both short options and long
options.  The short options in this case conform to the POSIX
definition.

  http://www.opengroup.org/onlinepubs/009695399/utilities/sort.html

  sort -k2,2
  sort -k 2,2

The long options conform to GNU long option syntax.

  http://www.gnu.org/prep/standards/

When using long options an equals character ('=') may be used between
the long option and the option argument.

  sort --key=2,2
  sort --key 2,2

The full documentation is in the info pages.  If you look at the sort
info pages you will see this described more fully this way:

  `-k POS1[,POS2]'
  `--key=POS1[,POS2]'
       Specify a sort field that consists of the part of the line between
       POS1 and POS2 (or the end of the line, if POS2 is omitted),
       _inclusive_.  Fields and character positions are numbered starting
       with 1.  So to sort on the second field, you'd use `--key=2,2'
       (`-k 2,2').  See below for more examples.

> 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 created directly from the --help output and are
designed as quick reference guides.  when using man pages it helps to
already know somewhat how commands operate.  To really learn how
commands operate from the beginning you should refer to the info
documentation where things are described fully.

Hoope that helps,
Bob