bug#16550: Request review of CHOWN man page synopsis

[Eric Blake]

On 01/25/2014 11:28 AM, Pádraig Brady wrote:

>> On browsing the man pages on web i noticed this was only the case with UNIX
>> man page. Man pages at
>> freeBSD<http://www.freebsd.org/cgi/man.cgi?query=chown&apropos=0&sektion=0&manpath=FreeBSD+7.0-RELEASE&format=html>and
>> oracle 
>> <http://docs.oracle.com/cd/E19683-01/816-0210/6m6nb7m5t/index.html>showed
>> the command usage as expected.

BSD and Solaris do not have as many extensions as GNU.

>>
>> I believe the correct usage would be
>>
>> chown [OPTION]... OWNER[:GROUP] FILE...

Wrong - in GNU, we have intentionally chosen to add an extension that
allows owner to be optional, even though POSIX does not require such an
extension.

>>
>> Please do the corrections necessary and inform me if i am making a mistake
>> in interpreting this.
> 
> Owner is optional. The info docs illustrate this more clearly:
> https://www.gnu.org/software/coreutils/manual/html_node/chown-invocation.html

This document covers the GNU extension.

That said, there IS a bug about the documentation being misleading.  See
http://debbugs.gnu.org/15945 which states:

> But I _still_ think we need to
> split into two lines to make it obvious that the argument itself is
> mandatory, as in:
> 
> Usage: chown [OPTION]... OWNER[:[GROUP]] FILE...
>   or:  chown [OPTION]... :[GROUP] FILE...
> 
> or even rewrite it along the lines of the info page:
> 
> Usage: chown [OPTION]... NEWSPEC FILE...
> 
> and document that NEWSPEC is [OWNER][:[GROUP]]

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature