textutils doc fixes: warn about features that POSIX says must go soon

[Paul Eggert]

I looked through textutils for obsolescent features that the next
version of POSIX will require to be withdrawn, and found three:

  sort +N
  tail +N
  uniq +N

In each case, POSIX 1003.1-200x will longer allow a conforming
application to support these options.  Users are supposed to use the
POSIX options instead, which have been supported for many years.

GNU textutils can't withdraw these features yet, since the current
POSIX requires them, but the documentation and usage strings can warn
users about the coming transition.  (I suppose we could rebel and
continue to support the obsolescent forms unless POSIXLY_CORRECT is
set, but I'm not sure it's worth the hassle and we should warn about
the problem in any event.)

Here's a proposed patch.

2001-03-17  Paul Eggert  <address@hidden>

        * src/sort.c, src/tail.c, src/uniq.c (usage):
        Warn that the +N form will be withdrawn.
        * doc/textutils.texi: Likewise.

===================================================================
RCS file: doc/textutils.texi,v
retrieving revision 2.0.12.2
retrieving revision 2.0.12.4
diff -pu -r2.0.12.2 -r2.0.12.4
--- doc/textutils.texi  2001/03/08 18:58:01     2.0.12.2
+++ doc/textutils.texi  2001/03/17 20:32:10     2.0.12.4
@@ -1439,7 +1439,7 @@ when given a @var{file} of @samp{-}.  Sy
 @example
 tail address@hidden@dots{} address@hidden@dots{}
 tail address@hidden address@hidden@dots{} address@hidden@dots{}
-tail address@hidden address@hidden@dots{} address@hidden@dots{}
+tail address@hidden address@hidden@dots{} address@hidden@dots{} # obsolescent
 @end example
 
 If more than one @var{file} is specified, @code{tail} prints a
@@ -1460,8 +1460,10 @@ typically 32k.  A more reliable and vers
 the @sc{gnu} @code{tac} command.
 
 @code{tail} accepts two option formats: the new one, in which numbers
-are arguments to the options (@samp{-n 1}), and the old one, in which
-the number precedes any option letters (@samp{-1} or @samp{+1}).
+are arguments to the options (@samp{-n 1}), and the obsolescent one, in
+which the number precedes any option letters (@samp{-1} or @samp{+1}).
+Warning: support for the @samp{+1} form will be withdrawn, as future
+versions of @sc{posix} will not allow it.
 
 If any option-argument is a number @var{n} starting with a @samp{+},
 @code{tail} begins printing with the @var{n}th item from the start of
@@ -1480,6 +1482,10 @@ a decimal number optionally followed by 
 @samp{k}, @samp{m}) as in @code{-c}, or @samp{l} to mean count by lines,
 or other option letters (@samp{cfqv}).
 
+Warning: the @address@hidden usage is obsolescent.  Future versions
+of @sc{posix} will require that support for it be withdrawn.  Use
address@hidden address@hidden instead.
+
 @item -c @var{bytes}
 @itemx address@hidden
 @opindex -c
@@ -2352,11 +2358,15 @@ reliably handle arbitrary pathnames (eve
 characters.)
 
 @item address@hidden@var{pos2}]
-The obsolete, traditional option for specifying a sort field.  The field
+The obsolescent, traditional option for specifying a sort field.  The field
 consists of the line between @var{pos1} and up to but @emph{not including}
 @var{pos2} (or the end of the line if @var{pos2} is omitted).  Fields
 and character positions are numbered starting with 0.  See below.
 
+Warning: the @address@hidden usage is obsolescent.  Future versions of
address@hidden will require that support for it be withdrawn.  Use
address@hidden instead.
+
 @end table
 
 In addition, when @sc{gnu} @code{sort} is invoked with exactly one argument,
@@ -2393,7 +2403,7 @@ Keys may span multiple fields.
 
 Here are some examples to illustrate various combinations of options.
 In them, the @sc{posix} @samp{-k} option is used to specify sort keys rather
-than the obsolete @address@hidden@var{pos2}} syntax.
+than the obsolescent @address@hidden@var{pos2}} syntax.
 
 @itemize @bullet
 
@@ -2537,6 +2547,10 @@ each other by at least one space or tab.
 Skip @var{n} characters before checking for uniqueness.  If you use both
 the field and character skipping options, fields are skipped over first.
 
+Warning: the @address@hidden usage is obsolescent.  Future versions of
address@hidden will require that support for it be withdrawn.  Use @samp{-s
address@hidden instead.
+
 @item -c
 @itemx --count
 @opindex -c
===================================================================
RCS file: src/tail.c,v
retrieving revision 2.0.12.0
retrieving revision 2.0.12.1
diff -pu -r2.0.12.0 -r2.0.12.1
--- src/tail.c  2001/01/08 08:34:14     2.0.12.0
+++ src/tail.c  2001/03/17 20:11:59     2.0.12.1
@@ -274,7 +274,8 @@ print the last N items in the file.  N m
 b for 512, k for 1024, m for 1048576 (1 Meg).  A first OPTION of -VALUE\n\
 or +VALUE is treated like -n VALUE or -n +VALUE unless VALUE has one of\n\
 the [bkm] suffix multipliers, in which case it is treated like -c VALUE\n\
-or -c +VALUE.\n\
+or -c +VALUE.  Warning: a first option of +VALUE is obsolescent, and support\n\
+for it will be withdrawn.\n\
 \n\
 With --follow (-f), tail defaults to following the file descriptor, which\n\
 means that even if a tail'ed file is renamed, tail will continue to track\n\
===================================================================
RCS file: src/uniq.c,v
retrieving revision 2.0.12.0
retrieving revision 2.0.12.1
diff -pu -r2.0.12.0 -r2.0.12.1
--- src/uniq.c  2000/06/20 06:41:18     2.0.12.0
+++ src/uniq.c  2001/03/17 20:11:59     2.0.12.1
@@ -121,7 +121,7 @@ standard input), writing to OUTPUT (or s
   -u, --unique          only print unique lines\n\
   -w, --check-chars=N   compare no more than N characters in lines\n\
   -N                    same as -f N\n\
-  +N                    same as -s N\n\
+  +N                    same as -s N (obsolescent; will be withdrawn)\n\
       --help            display this help and exit\n\
       --version         output version information and exit\n\
 \n\
===================================================================
RCS file: src/sort.c,v
retrieving revision 2.0.12.4
retrieving revision 2.0.12.5
diff -pu -r2.0.12.4 -r2.0.12.5
--- src/sort.c  2001/03/11 22:06:52     2.0.12.4
+++ src/sort.c  2001/03/17 20:11:59     2.0.12.5
@@ -291,18 +291,13 @@ Usage: %s [OPTION]... [FILE]...\n\
       printf (_("\
 Write sorted concatenation of all FILE(s) to standard output.\n\
 \n\
-  +POS1 [-POS2]    start a key at POS1, end it *before* POS2 (obsolescent)\n\
-                     field numbers and character offsets are numbered\n\
-                     starting with zero (contrast with the -k option)\n\
   -b               ignore leading blanks in sort fields or keys\n\
   -c               check if given files already sorted, do not sort\n\
   -d               consider only blanks and alphanumeric characters in keys\n\
   -f               fold lower case to upper case characters in keys\n\
   -g               compare according to general numerical value, imply -b\n\
   -i               consider only printable characters in keys\n\
-  -k POS1[,POS2]   start a key at POS1, end it *at* POS2\n\
-                     field numbers and character offsets are numbered\n\
-                     starting with one (contrast with zero-based +POS form)\n\
+  -k POS1[,POS2]   start a key at POS1, end it *at* POS2 (origin 1)\n\
   -m               merge already sorted files, do not sort\n\
   -M               compare (unknown) < `JAN' < ... < `DEC', imply -b\n\
   -n               compare according to string numerical value, imply -b\n\
@@ -316,6 +311,9 @@ Write sorted concatenation of all FILE(s
   -u               with -c, check for strict ordering;\n\
                    with -m, only output the first of an equal sequence\n\
   -z               end lines with 0 byte, not newline, for find -print0\n\
+  +POS1 [-POS2]    start a key at POS1, end it *before* POS2 (origin 0)\n\
+                     Warning: this option is obsolescent and support for it\n\
+                     will be withdrawn.  Use -k instead.\n\
       --help       display this help and exit\n\
       --version    output version information and exit\n\
 \n\