From 419aa62c4690a05c642c95f67bcd34dbb13a1ccf Mon Sep 17 00:00:00 2001 From: Evan Hunt Date: Wed, 3 Jan 2007 12:24:35 +0100 Subject: [PATCH] [oops] Document what the ".0" in e.g., "-k 2,3.0" means, and... * coreutils.texi (sort invocation): ... that it can be applied to the field-end spec, but not the field-start one. Patch from Evan Hunt. Signed-off-by: Jim Meyering --- doc/coreutils.texi | 46 +++++++++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 21 deletions(-) diff --git a/doc/coreutils.texi b/doc/coreutils.texi index ab95db4..ae072d7 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -3584,9 +3584,21 @@ Other options are: @cindex sort field Specify a sort field that consists of the part of the line between @var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is -omitted), @emph{inclusive}. Fields and character positions are numbered -starting with 1. So to sort on the second field, you'd use -@option{--key=2,2} (@option{-k 2,2}). See below for more examples. +omitted), @emph{inclusive}. + +Each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]}, +where @var{f} is the number of the field to use, and @var{c} is the number +of the first character from the beginning of the field. Fields and character +positions are numbered starting with 1; a character position of zero in +@var{pos2} indicates the field's last character. If @samp{.@var{c}} is +omitted from @var{pos1}, it defaults to 1 (the beginning of the field); +if omitted from @var{pos2}, it defaults to 0 (the end of the field). +@var{opts} are ordering options, allowing individual keys to be sorted +according to different rules; see below for details. Keys can span +multiple fields. + +Example: To sort on the second field, use @option{--key=2,2} +(@option{-k 2,2}). See below for more examples. @item -o @var{output-file} @itemx --output=@var{output-file} @@ -3725,29 +3737,21 @@ consistency, @option{-M} has been changed in the same way. This may affect the meaning of character positions in field specifications in obscure cases. The only fix is to add an explicit @option{-b}. -A position in a sort field specified with the @option{-k} -option has the form @samp{@var{f}.@var{c}}, where @var{f} is the number -of the field to use and @var{c} is the number of the first character -from the beginning of the field. In a start position, an omitted -@samp{.@var{c}} stands for the field's first character. In an end -position, an omitted or zero @samp{.@var{c}} stands for the field's -last character. If the start field falls after the end of the line -or after the end field, the field is empty. If the -@option{-b} option was specified, the @samp{.@var{c}} part of a field -specification is counted from the first nonblank character of the field. - -A sort key position may also have any of the option letters @samp{Mbdfinr} -appended to it, in which case the global ordering options are not used -for that particular field. The @option{-b} option may be independently -attached to either or both of the start and -end positions of a field specification, and if it is inherited -from the global options it will be attached to both. +A position in a sort field specified with @option{-k} may have any +of the option letters @samp{Mbdfinr} appended to it, in which case the +global ordering options are not used for that particular field. The +@option{-b} option may be independently attached to either or both of +the start and end positions of a field specification, and if it is +inherited from the global options it will be attached to both. If input lines can contain leading or adjacent blanks and @option{-t} is not used, then @option{-k} is typically combined with @option{-b}, @option{-g}, @option{-M}, or @option{-n}; otherwise the varying numbers of leading blanks in fields can cause confusing results. -Keys can span multiple fields. +If the start position in a sort field specifier falls after the end of +the line or after the end field, the field is empty. If the @option{-b} +option was specified, the @samp{.@var{c}} part of a field specification +is counted from the first nonblank character of the field. @vindex _POSIX2_VERSION @vindex POSIXLY_CORRECT -- 2.7.4