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

From: Paul Eggert <[email-masked]>
Date: Tue, 3 Apr 2018 08:45:06 -0700

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 <[email-masked]>
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 Operator Numeric Modes
 
-- 
2.14.3