bug#7523: chmod example in docs

[Eric Blake]

[re-adding the list]

On 12/01/2010 09:24 AM, address@hidden wrote:
> Hi Eric,
> 
> 
> As much as I would love to contribute code to the open source community,
> unfortunately I have no idea how to code.

Even so, your suggestions in English are a good start for telling us
what you found to be lacking.

> 
> 'chown' has a very easy to understand example style to reflect off.
> 
> 
> Also, another stupid thing in the 'chmod' manual is the following:
> 
> ***
> 
> The format of a symbolic mode is  [ugoa...][[+-=][perms...]...],  where
>        perms  is  either zero or more letters from the set rwxXst, or a
> single
>        letter from the set ugo.  Multiple symbolic modes can be  given,
> sepa‐
>       rated by commas.
> 
>        A  combination  of the letters ugoa controls which users' access
> to the
>        file will be changed: the user who owns it  (u),  other  users 
> in  the
>        file's group (g), other users not in the file's group (o), or all
> users
>        (a).  If none of these are given, the effect is as if a were
> given, but
>       bits that are set in the umask are not affected.
> 
> ***
> 
> The above states three dots after 'ugoa' ([ugoa...]). From my understand
> this parameter has the options of 'u' 'g' 'o' 'a' only, therefore, there
> should not be three dots (...) in [ugoa...] as all the parameter options
> have been specified. This was a little bit confusing at the start.

Actually, it _should_ be 3 dots, because our convention is that 3 dots
imply that you can repeat one of the earlier items more than once.  That is:

chmod go-rw file

or even the (redundant) version:

chmod ggoo-rrww file

are both perfectly acceptable (multiple instances from the set [ugoa],
then [-], then multiple instances from the set of [PERMS]).

> 
> GNU manuals are full of this weird kinda logic, or I am not
> understanding something.

Hmm; I just noticed that 'info coreutils "File permissions"' gives a
much better overview of chmod arguments.  I stand corrected on my
earlier claim; the manual already states this under 'info coreutils chmod':

   If used, MODE specifies the new file mode bits.  For details, see
the section on *note File permissions::.

I suggest you read that chapter.

> I've gotta give it to Microsoft, they get their manuals right. With GNU
> it feels like I've bought an awesome product from China, only to find
> the user manual is in broken English. It is essential that the Linux
> community have the same high standards with user manuals like does
> Microsoft, if we are to win the Windows users over.

The man pages assume you already know Unix-like operations.  The info
pages, on the other hand, should cater to new users; if you have
suggestions on how we can improve that, we are all ears.

-- 
Eric Blake   address@hidden    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature