bug#29069: bug#31043: [PATCH] changed presentation in 'File permissions' in 'numeric, modes'

[Paul Eggert]

On 04/11/2018 05:44 AM, kalle wrote:

I don't even know if this methodology of
encoding information (I mean "symbolical notation rwx for owner =
symbolical notation rwx = symbolical notation 111= interpreting 111
numerically in binary = transforming to numerical octal 7") is just used
in this special case or is used more generally throughout the GNU
programs.


The symbolic notation's primary use is in the core GNU (and POSIX) 
utilities. It was introduced in Unix (a predecessor to GNU/Linux) and is 
standardized by POSIX. The symbolic notation is not generally used 
elsewhere, so it's good to document it in the coreutils manual. In 
contrast, octal numbers are generally used throughout computing and 
mathematics, and we shouldn't have to explain them here.


I'd be more sympathetic if octal numbers were required. But users don't 
have to use them; they can use symbolic modes. That's what symbolic 
modes were invented for: to help users who don't understand or like 
octal. The documentation should exploit this, not fight it.

bug#29069: bug#31043: [PATCH] changed presentation in 'File permissions' in 'numeric, modes'

[kalle]

Am 04.04.2018 um 00:10 schrieb Paul Eggert:
> On 04/03/2018 12:29 PM, kalle wrote:
>>
>> But what do you think of my teaching concept, to try to explain why a
>> `7' in `755' means =4+2+1=111=rwx="rwx for owner", which is assumed as
>> self-evident or intuitive in both the original text and your patch?
> 
> I think it's out of place in the coreutils manual, just as (for example)
> the manual need not mention computer keyboard layouts in order to tell
> users how to type 'sort -r'. Assuming basic computer concepts simplifies
> the manual and makes it easier for typical users to read, which is a win.

I find your example far away from the actual problem: computer keyboard
layouts and how to define them is important but much more  general than
'sort -r' and in my opinion it should be described somewhere (actually
keymaps(5),loadkeys(1) and so forth) and be referred to at crucial moments.
While for `File Permission', I don't even know if this methodology of
encoding information (I mean "symbolical notation rwx for owner =
symbolical notation rwx = symbolical notation 111= interpreting 111
numerically in binary = transforming to numerical octal 7") is just used
in this special case or is used more generally throughout the GNU
programs. In any case it is _not_ just octal, but a specific way of
translating numerical octal to a symbolic notation (and that's what I
tried to explain in my patch) even if some nerds knew it's meaning by
experience.
At least it should be referred to the place, where the concept is
explained. And referencing to the internet is non an elegant way, as it
could be the case, that the person doesn't have any access to it.

Assuming that new users necessarily know about this special way of using
octal numbers is simply newbie-unfriendly. Imagine someone starting to
learn `ls' or `mv' or just 'File Permissions' now directly being stuck
with this methodology.

What is this person expected to have read before starting learning how
to work with the CLI through documentation-systems as `info' or `man'
apart from complicated imperialist english language?


after my patch proposal, paul eggert wrote:
"I think part of the problem is that this is not really the place to
explain octal notation; any reader who doesn't know octal before reading
the manual is not likely to understand it even with the proposed
rewrite. I think we should just give up and assume that the reader knows
octal (if they don't they should be using symbolic modes)."

The more appropriate way imo would be to look up for a good place for a
explanation rather than "giving up" so quickly.

kalle

bug#29069: bug#31043: [PATCH] changed presentation in 'File permissions' in 'numeric, modes'

[Paul Eggert]

On 04/03/2018 12:29 PM, kalle wrote:


But what do you think of my teaching concept, to try to explain why a
`7' in `755' means =4+2+1=111=rwx="rwx for owner", which is assumed as
self-evident or intuitive in both the original text and your patch?


I think it's out of place in the coreutils manual, just as (for example) 
the manual need not mention computer keyboard layouts in order to tell 
users how to type 'sort -r'. Assuming basic computer concepts simplifies 
the manual and makes it easier for typical users to read, which is a win.




where would be a place, to formulate the problem `7=4+2+1'
more generally?


One place would be:

https://en.wikipedia.org/wiki/Octal



Why didn't you take over my correction from "are sometimes special" to
"have a special meaning for directories" ?


I didn't think that was necessary, since the parenthesized 
cross-reference already mentioned "Directory". The main point here is 
that the leading "0" is not necessary, not that excess leading "0"s 
sometimes have special meanings.

bug#29069: bug#31043: [PATCH] changed presentation in 'File permissions' in 'numeric, modes'

[kalle]

hello,


Am 03.04.2018 um 17:45 schrieb Paul Eggert:
> Thanks for mentioning the problem.
so you see a problem there too?

 However, I found the proposed rewrite
> to be more confusing than the original. 
It may me that my way of building sentences is quite amendable. I'm not
a native english writer.
But what do you think of my teaching concept, to try to explain why a
`7' in `755' means =4+2+1=111=rwx="rwx for owner", which is assumed as
self-evident or intuitive in both the original text and your patch? 


I think part of the problem is
> that this is not really the place to explain octal notation;
maybe. But where would be a place, to formulate the problem `7=4+2+1'
more generally? and then to just refer to it?

 any reader
> who doesn't know octal before reading the manual is not likely to
> understand it even with the proposed rewrite.
Because of what, do you think?

 I think we should just
> give up and assume that the reader knows octal (if they don't they
> should be using symbolic modes) 
if they don't miss any important features..
but why already giving up? does it seem so impossible to find a more
newbie-friendly solution?

. That being said, we could briefly give
> an example of how the individual bits are combined into an octal digit,
> and rearrange the description to make it more intuitive. I installed the
> attached patch to try to improve things.
Why didn't you take over my correction from "are sometimes special" to
"have a special meaning for directories" ?
> 
> I also merged Bug#31043 with Bug#29069 since they're the same topic.
The problem was, that when writing  "Bug#29069" in the subject, nobody
responded to my patch proposal, which at the end was nearly to frustrating.

greetings,
kalle

bug#29069: bug#31043: [PATCH] changed presentation in 'File permissions' in 'numeric, modes'

[Paul Eggert]

Thanks for mentioning the problem. However, I found the proposed rewrite 
to be more confusing than the original. I think part of the problem is 
that this is not really the place to explain octal notation; any reader 
who doesn't know octal before reading the manual is not likely to 
understand it even with the proposed rewrite. I think we should just 
give up and assume that the reader knows octal (if they don't they 
should be using symbolic modes). That being said, we could briefly give 
an example of how the individual bits are combined into an octal digit, 
and rearrange the description to make it more intuitive. I installed the 
attached patch to try to improve things.


I also merged Bug#31043 with Bug#29069 since they're the same topic.
>From a20bf723b62bb54c32154c6bf0c7c4d9e6e8a708 Mon Sep 17 00:00:00 2001
From: Paul Eggert 
Date: Tue, 3 Apr 2018 08:40:34 -0700
Subject: [PATCH] doc: Clarify octal bits in permissions

* doc/perm.texi (Numeric Modes): Briefly explain octal.
Reorder description to make it more intuitive (Bug#29069).
---
 doc/perm.texi | 66 +++
 1 file changed, 35 insertions(+), 31 deletions(-)

diff --git a/doc/perm.texi b/doc/perm.texi
index af8fa3827..77ec1a59c 100644
--- a/doc/perm.texi
+++ b/doc/perm.texi
@@ -494,57 +494,61 @@ the file to all users.
 As an
 alternative to giving a symbolic mode, you can give an octal (base 8)
 number that represents the mode.
-This number is always interpreted in octal; you do not have to add a
-leading @samp{0}, as you do in C.  Mode @samp{0055} is the same as
-mode @samp{55}.  (However, modes of five digits or more, such as
-@samp{00055}, are sometimes special.  @xref{Directory Setuid and Setgid}.)
-
-A numeric mode is usually shorter than the corresponding symbolic
-mode, but it is limited in that normally it cannot take into account the
-previous file mode bits; it can only set them absolutely.
-The set-user-ID and set-group-ID bits of directories are an exception
-to this general limitation.  @xref{Directory Setuid and Setgid}.
-Also, operator numeric modes can take previous file mode bits into
-account.  @xref{Operator Numeric Modes}.
 
 The permissions granted to the user,
 to other users in the file's group,
 and to other users not in the file's group each require three
-bits, which are represented as one octal digit.  The three special
+bits: one bit for read, one for write, and one for execute/search permission.
+These three bits are represented as one octal digit;
+for example, if all three are present, the resulting 111 (in binary)
+is represented as the digit 7 (in octal).  The three special
 mode bits also require one bit each, and they are as a group
 represented as another octal digit.  Here is how the bits are arranged,
-starting with the lowest valued bit:
+starting with the highest valued bit:
 
 @example
 Value in  Corresponding
 Mode  Mode Bit
 
-  Other users not in the file's group:
-   1  Execute/search
-   2  Write
-   4  Read
-
-  Other users in the file's group:
-  10  Execute/search
-  20  Write
-  40  Read
+  Special mode bits:
+4000  Set user ID on execution
+2000  Set group ID on execution
+1000  Restricted deletion flag or sticky bit
 
   The file's owner:
- 100  Execute/search
- 200  Write
  400  Read
+ 200  Write
+ 100  Execute/search
 
-  Special mode bits:
-1000  Restricted deletion flag or sticky bit
-2000  Set group ID on execution
-4000  Set user ID on execution
+  Other users in the file's group:
+  40  Read
+  20  Write
+  10  Execute/search
+
+  Other users not in the file's group:
+   4  Read
+   2  Write
+   1  Execute/search
 @end example
 
-For example, numeric mode @samp{4755} corresponds to symbolic mode
-@samp{u=rwxs,go=rx}, and numeric mode @samp{664} corresponds to symbolic mode
+For example, numeric mode @samp{4751} corresponds to symbolic mode
+@samp{u=srwx,g=rx,o=x}, and numeric mode @samp{664} corresponds to symbolic mode
 @samp{ug=rw,o=r}.  Numeric mode @samp{0} corresponds to symbolic mode
 @samp{a=}.
 
+A numeric mode is usually shorter than the corresponding symbolic
+mode, but it is limited in that normally it cannot take into account the
+previous file mode bits; it can only set them absolutely.
+The set-user-ID and set-group-ID bits of directories are an exception
+to this general limitation.  @xref{Directory Setuid and Setgid}.
+Also, operator numeric modes can take previous file mode bits into
+account.  @xref{Operator Numeric Modes}.
+
+Numeric modes are always interpreted in octal; you do not have to add a
+leading @samp{0}, as you do in C@.  Mode @samp{0055} is the same as
+mode @samp{55}.  However, modes of five digits or more, such as
+@samp{00055}, are sometimes special (@pxref{Directory Setuid and Setgid}).
+
 @node Operator Numeric Modes
 @section