GNU bug report logs - #7523
chmod example in docs

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 7523 in the body.
You can then email your comments to 7523 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: nikkae <at> email.com
To: bug-coreutils <at> gnu.org
Date: Wed, 01 Dec 2010 00:50:23 -0500

The manual for CHMOD is very hard to understand.

The manual does not even have an example of CHMOD being used.

I have given up on CHMOD.

Message #8 received at 7523 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: nikkae <at> email.com
Cc: 7523 <at> debbugs.gnu.org
Subject: Re: bug#7523: chmod example in docs
Date: Wed, 01 Dec 2010 08:12:08 -0700

[Message part 1 (text/plain, inline)]

retitle 7523 chmod example in docs
thanks

On 11/30/2010 10:50 PM, nikkae <at> email.com wrote:
> The manual for CHMOD is very hard to understand.
> 
> The manual does not even have an example of CHMOD being used.
> 
> I have given up on CHMOD.

Which manual?  'chmod --help', which is reproduced in 'man chmod', or
the official documentation 'info coreutils chmod'?  However, you are
correct that the info pages do not currently have any example for chmod;
would you care to help us write a patch?

-- 
Eric Blake   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Message #13 received at 7523 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: nikkae <at> email.com, 7523 <at> debbugs.gnu.org
Subject: Re: bug#7523: chmod example in docs
Date: Wed, 01 Dec 2010 09:47:22 -0700

[Message part 1 (text/plain, inline)]

[re-adding the list]

On 12/01/2010 09:24 AM, nikkae <at> email.com 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   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Message #16 received at 7523 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Eric Blake <eblake <at> redhat.com>
Cc: 7523 <at> debbugs.gnu.org, nikkae <at> email.com
Subject: Re: bug#7523: chmod example in docs
Date: Wed, 01 Dec 2010 11:34:35 -0800

>> > I've gotta give it to Microsoft, they get their manuals right.

Sorry, but I had to laugh at that one.

Here's a quote from a Microsoft manual on this very topic:

  chmod   A UNIX command meaning "change module."

which is bogus, of course: even someone with only passing acquaintance
with chmod should know that the "mod" doesn't stand for module.
(Even Wikipedia's page on chmod is better that Microsoft's on this point.)

A note at the start of that Microsoft page says:

  "No warranty is made as to technical accuracy."

which is a remark that you can take the bank, when reading
Microsoft manuals.

I'm not saying GNU manuals are perfect.  Far from it!  But
we should not aim for being merely as good as Microsoft manuals,
as that would be far too low a target.  In many cases they're
not much better than Wikipedia, and all too often they're worse.

My sources:

http://technet.microsoft.com/en-us/library/cc749930.aspx
http://en.wikipedia.org/wiki/Chmod

Message #19 received at 7523 <at> debbugs.gnu.org (full text, mbox):

From: Assaf Gordon <assafgordon <at> gmail.com>
To: 7523 <at> debbugs.gnu.org
Subject: Re: bug#7523: chmod example in docs
Date: Thu, 18 Oct 2018 18:01:33 -0600

tags 7523 moreinfo notabug
close 7523
stop

(triaging old bugs)
With no further comments and no improvement suggestions
in 8 years, I'm closing this bug.

-assaf

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.