Document new syntax: "chown +0:+287 file", "chgrp +99 file"

[Jim Meyering]

Here's the documentation for the new chown/chgrp syntax:

        * coreutils.texi (Disambiguating names and IDs): New section.
        (chown invocation, chgrp invocation): Mention the new syntax
        with an xref to the new section.

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index ff049bc..05bf7c6 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -208,6 +208,7 @@ Common Options
 * Exit status::                 Indicating program success or failure.
 * Backup options::              Backup options
 * Block size::                  Block size
+* Disambiguating names and IDs:: chgrp and chown owner and group syntax
 * Random sources::              Sources of random data
 * Target directory::            Target directory
 * Trailing slashes::            Trailing slashes
@@ -644,6 +645,7 @@ name.
 * Exit status::                 Indicating program success or failure.
 * Backup options::              -b -S, in some programs.
 * Block size::                  BLOCK_SIZE and --block-size, in some programs.
+* Disambiguating names and IDs:: chgrp and chown owner and group syntax
 * Random sources::              --random-source, in some programs.
 * Target directory::            Specifying a target directory, in some 
programs.
 * Trailing slashes::            --strip-trailing-slashes, in some programs.
@@ -924,6 +926,46 @@ set.  The @option{-h} or @option{--human-readable} option 
is equivalent to
 @option{--block-size=human-readable}.  The @option{--si} option is
 equivalent to @option{--block-size=si}.

address@hidden Disambiguating names and IDs
address@hidden chown and chgrp: Disambiguating user names and IDs
address@hidden user names, disambiguating
address@hidden user IDs, disambiguating
address@hidden group names, disambiguating
address@hidden group IDs, disambiguating
address@hidden disambiguating group names and IDs
+
+Since the @var{owner} and @var{group} arguments to @command{chown} and
address@hidden may be specified as names or numeric IDs, there is an
+apparent ambiguity.
+What if a user or group @emph{name} is a string of digits?
address@hidden a number as a user name is common in some environments.}
+Should the command interpret it as a user name or as an ID?
address@hidden requires that @command{chown} and @command{chgrp}
+first attempt to resolve the specified string as a name, and
+only once that fails, then try to interpret it as an ID.
+This is troublesome when you want to specify a numeric ID, say 42,
+and it must work even in a pathological situation where
address@hidden is a user name that maps to some other user ID, say 1000.
+Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to
+1000---not what you intended.
+
+GNU @command{chown} and @command{chgrp} provide a way to work around this,
+that at the same time may result in a significant performance improvement
+by eliminating a database look-up.
+Simply precede each numeric user ID and/or group ID with a @samp{+},
+in order to force its interpretation as an integer:
+
address@hidden
+chown +42 F
+chgrp +$numeric_group_id another-file
+chown +0:+0 /
address@hidden example
+
+GNU @command{chown} and @command{chgrp}
+skip the name look-up process for each @samp{+}-prefixed string,
+because a string containing @samp{+} is never a valid user or group name.
+This syntax is accepted on most common Unix systems, but not on Solaris 10.
+
 @node Random sources
 @section Sources of random data

@@ -8778,6 +8820,10 @@ owner nor the group is changed.

 @end table

+If @var{owner} or @var{group} is intended to represent a numeric user
+or group ID, then you may specify it with a leading @samp{+}.
address@hidden names and IDs}.
+
 Some older scripts may still use @samp{.} in place of the @samp{:} separator.
 @acronym{POSIX} 1003.1-2001 (@pxref{Standards conformance}) does not
 require support for that, but for backward compatibility @acronym{GNU}
@@ -8953,6 +8999,10 @@ or to the group of an existing reference file.  Synopsis:
 chgrp address@hidden@dots{} @address@hidden | address@hidden@} @address@hidden
 @end example

+If @var{group} is intended to represent a
+numeric group ID, then you may specify it with a leading @samp{+}.
address@hidden names and IDs}.
+
 The program accepts the following options.  Also see @ref{Common options}.

 @table @samp