GNU bug report logs - #19287
sort: doc: improve "-k/--key" explanation

Message received at submit <at> debbugs.gnu.org:

Received: (at submit) by debbugs.gnu.org; 6 Dec 2014 13:03:04 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Sat Dec 06 08:03:04 2014
Received: from localhost ([127.0.0.1]:55231 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.80)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1XxF0p-0007jE-SI
	for submit <at> debbugs.gnu.org; Sat, 06 Dec 2014 08:03:04 -0500
Received: from eggs.gnu.org ([208.118.235.92]:37996)
 by debbugs.gnu.org with esmtp (Exim 4.80)
 (envelope-from <lsatenstein@HIDDEN>) id 1XxF0n-0007j6-W7
 for submit <at> debbugs.gnu.org; Sat, 06 Dec 2014 08:03:02 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <lsatenstein@HIDDEN>) id 1XxF0d-0007zj-OT
 for submit <at> debbugs.gnu.org; Sat, 06 Dec 2014 08:03:01 -0500
X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org
X-Spam-Level: **
X-Spam-Status: No, score=2.4 required=5.0 tests=BAYES_50,FORGED_YAHOO_RCVD,
 FREEMAIL_FROM,T_DKIM_INVALID autolearn=disabled version=3.3.2
Received: from lists.gnu.org ([2001:4830:134:3::11]:40172)
 by eggs.gnu.org with esmtp (Exim 4.71)
 (envelope-from <lsatenstein@HIDDEN>) id 1XxF0d-0007zd-Lf
 for submit <at> debbugs.gnu.org; Sat, 06 Dec 2014 08:02:51 -0500
Received: from eggs.gnu.org ([2001:4830:134:3::10]:39686)
 by lists.gnu.org with esmtp (Exim 4.71)
 (envelope-from <lsatenstein@HIDDEN>) id 1XxF0V-0003y8-Dw
 for bug-coreutils@HIDDEN; Sat, 06 Dec 2014 08:02:51 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
 (envelope-from <lsatenstein@HIDDEN>) id 1XxF0N-0007tM-6t
 for bug-coreutils@HIDDEN; Sat, 06 Dec 2014 08:02:43 -0500
Received: from nm22-vm1.bullet.mail.bf1.yahoo.com ([98.139.212.127]:44573)
 by eggs.gnu.org with esmtp (Exim 4.71)
 (envelope-from <lsatenstein@HIDDEN>) id 1XxF0N-0007so-27
 for bug-coreutils@HIDDEN; Sat, 06 Dec 2014 08:02:35 -0500
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yahoo.com; s=s2048;
 t=1417870954; bh=a/LhxRn9iL5Y/WKplptEDwBGNppzX6SwNdQNtjeZZE4=;
 h=Subject:From:To:Date:From:Subject;
 b=eEupeiddvCc/KB+K0WMz+GCVe91BonJHqrcH52a8M6HEbIMY5wtWy9DXtEAs+ISfcTW/BXlNcnfZexY5H6XXDx084ObuRXTrzeJDjAOSCigy5evqjnw+YKej3rQQY3a19Yp5yYwQBJvcXsk+XPcaDDimSmJ/8kwV/hmjYIHV8Tx4Lc4wBo+sbldKorwR+uTDcQ9uApgZ/mILLUyPkG0ILavpBaNjPRYiCqCJDf3WAjx/lN8G3yevaCazdGcAH8GOo8Sh77VElihx+cpPdGjJmIqz3uk8jV/85ZCVTdUIOmta8R1tv0DndbWXrJN2byvSLAtM+QNsFNp2YDKqGM/JNg==
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=s2048; d=yahoo.com;
 b=O8NY2pmA0AQLx82oa1TGDur1yfg0w5Ctjj4G+vuoUKRRRvgqv5+Y6DOeMye8IfyIOu6mOEAMbWHoEi8wlnY72vfAASyh7YNG/nYzw4/UndvoXmtMJ0mHIrDIZtaeLkeDYtFSpdTNCCyHwJig+ulHZuiVKSAyMdmLLHbqK5gBMc0Au2yNsy+i94ycgUR/X8UcoCbs44alURSVOx3K5B1Osp/EKH7pGu2VqU+Xsqioxl4jC6lQQEpM2aPvnj6/set6ZxiyNgkdyi+UvjndI6u9MdEVFCPr/Mg/+jGF2qRiCwMMyoQuq2hly+Ln3pH+NHPkPhq6Z4su4SarCoY/YB1maQ==;
Received: from [98.139.212.153] by nm22.bullet.mail.bf1.yahoo.com with NNFMP;
 06 Dec 2014 13:02:34 -0000
Received: from [98.139.211.163] by tm10.bullet.mail.bf1.yahoo.com with NNFMP;
 06 Dec 2014 13:02:34 -0000
Received: from [127.0.0.1] by smtp220.mail.bf1.yahoo.com with NNFMP;
 06 Dec 2014 13:02:34 -0000
X-Yahoo-Newman-Id: 260620.6817.bm@HIDDEN
X-Yahoo-Newman-Property: ymail-3
X-YMail-OSG: 9FRvDuAVM1nZElZgdziCIqZkEkFIJP_UOCwHVcmK6BI4Fq4
 bDBnePkjgGlDmBt9lHoPR1SJFCTtaHK5jE6beVynJ2oOvg9DoExRHpiahk_t
 JX_ktCv6R_SlzNyHYvSSdZ7NBylDdVmg3l0IpdhauXCoKzOyhr.EkQmy.fXA
 qaOmZr_X0PRrxkuCZGEVKTLzMMbFXPcH1VjIMDgzE6jyokGkgW5wJZaL5CCQ
 QEizWGgDBUu1InC1BDEagjHqbxlQdPIla.S9mWkKfg3pR5IM8dfxyg3ffdPd
 bcK6rWwpQDC9BMsVrSSOu8ijbkXHSFlzfXOf.a6dkvfWegRVG.TjfYgwgez6
 q2UFfL2UgF_YkIRM1JwdPwXLvZoQUvswa9YVxYEN9M5krOzaeAKHMiGhe.RG
 hQd7Zg4aFmyhAIpN2yzCJKtFk6ikQwi7xKdiu2lT88B4qWrL02y4bdhL.eU_
 1nil1.pd01syvs5UUFMdSIm9u0LJrZm20D1tytQJ7Ly0CL1t2BZKXPzhMqg.
 BE.xr.AoIjCb_EYRyOIrcDvST
X-Yahoo-SMTP: qWLWhsmswBAJ2u3KnYMy.7_EJg1ktIVt
Message-ID: <1417870952.17788.31.camel@HIDDEN>
Subject: Request to improve the Man document for "sort."
From: Leslie Satenstein <lsatenstein@HIDDEN>
To: bug-coreutils@HIDDEN
Date: Sat, 06 Dec 2014 08:02:32 -0500
Content-Type: text/plain; charset="UTF-8"
X-Mailer: Evolution 3.12.8 (3.12.8-1.fc21) 
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x
X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address
 (bad octet value).
X-Received-From: 2001:4830:134:3::11
X-Spam-Score: -3.3 (---)
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

I had a lot of head scratching until someone clarified the
documentation.

Here is the line and explanation that bothers me.
Explanation of -k ... 

        -k, --key=POS1[,POS2]
            start a key at POS1 (origin 1), end it at POS2 (default end
        of line) 
        

with accompanying explanation

        POS is F[.C][OPTS], where F is the field number and C the
        character position in the field; both are origin 1. If neither
        -t nor -b is in effect, characters in a field are counted from
        the beginning of the preceding whitespace. OPTS is one or more
        single-letter ordering options, which override global ordering
        options for that key. If no key is given, use the entire line as
        the key. 
        


It was not clear to me that when -t was used with a field delimited
file, then to sort only by the entire enclosed field, we need to specify
-k F.F  and that -k F'.F' may occur multiple times.

It was only with the SEE ALSO that with the visit to info coreutils sort
invocation that explanation about sorting fields was described.

Can a clarification of the explanation for -k be provided.

I would add one sentence after the last line of the above indented
paragraph.
                                                                        
   For additional rules pertaining to the sort of field delimited
   records, consult info coreutils sort invocation
        
      
We should not have to visit two references (man and info) in order to
setup sort keys.

Regards

Leslie Satenstein