bug#29069: improvement proposals texinfo-coreutils, 27.3 (numeric modes)

[kalle]

hello there,
this e-mail continues the discussion about improvement proposals about
info coreutils,section "File permissions". '>>' was me
(address@hidden writing, '>' was address@hidden
This mail continues the specialized debate about `27.3 (numeric modes)'.



>> -27.3: is there an info/man-document, where binary,
>> octal, hex-numbers are explained? If, it should be referred to. If
not, shouldn't there be one (and where would it fit in? ) ?-- I
>> could write the text...Since this documentation assumes the knowledge
>> of it..

>Not sure this belongs in the coreutils manual,
>however if you send a patch that would go a long way towards
considering it for inclusion.

I wrote some text,attached to this mail. I think man 7 would be an
appropriate place for this.

>For comparison, I see that "chmod" manual page in OpenBSD, FreeBSD and
>POSIX mention octal code values but do not explain with octal is.
>The reader is expected to either use them as-is, or search for more
details elsewhere.

>https://man.openbsd.org/chmod.1
>https://www.freebsd.org/cgi/man.cgi?query=chmod
>http://pubs.opengroup.org/onlinepubs/9699919799/utilities/chmod.html

In the introduction of the coreutils-texinfo-document, it says: "many
sections make no attempt to explain basic concepts in a way suitable for
novices. […] get involved in improving this manual"


>  "However, modes of five digits or more, such as ‘00055’,
>   are sometimes special. See Directory Setuid and Setgid."
>https://www.gnu.org/software/coreutils/manual/html_node/Numeric-Modes.html

My improvement proposal:
Modes of five digits or more, such as `00055', have a special meaning
for directories (see Directory Setuid and Setgid)


REMARK: the below section is my improvement proposal of the section
27.3. I left the two first paragraphs unchanged here.The above
transformations are not incorporated yet for your better overview, since
the below part is only a different explanation of the octal model. The
above correction proposals thus still have to be worked in.

27.3 Numeric Modes
==================

As an alternative to giving a symbolic mode, you can give an octal
(base8) number that represents the mode.  This number is always
interpretedin octal; you do not have to add a leading ‘0’, as you do in
C. Mode‘0055’ is the same as mode ‘55’.  (However, modes of five digits
ormore, such as ‘00055’, are sometimes special.  *Note Directory
Setuidand Setgid::.)

A numeric mode is usually shorter than the corresponding symbolicmode,
but it is limited in that normally it cannot take into account
theprevious file mode bits; it can only set them absolutely.
Theset-user-ID and set-group-ID bits of directories are an exception
tothis general limitation.  *Note Directory Setuid and Setgid::.
Also,operator numeric modes can take previous file mode bits into
account.*Note Operator Numeric Modes::.

The octal notation can be derived from the symbolic one,as an
intermediate step transforming it into a binary string (1), which is
then easily changed into octal base (2):

(1)For the intermediate step the `r',`w' and `x'-symbols of the symbolic
notation are changed out at the corresponding place by a `0' or a `1',
according to whether the bits are clear or set  (this works as long as
there are no special mode bits, because every place belongs specifically
to one kind of bit), thus transforming e.g. the string `rwxr-xr--' into
`111101100'.Then instead of overriding the `x'-bits, the special mode
bits are represented by grouping them at the beginning, in the order
suid|guid|sticky/restricted_deletion, thus e.g. describing symbolic
`rwsr-xr-t' as `101111101101'.

(2)Every 3 digits can then be grouped together and described as octal
digits, following the logic that three binary digits `abc' are
translated into an octal number a*2^2+b*2^1+c*2^0=a*4+b*2+c*1, e.g.:

binary  octal
101     5
111     7
011     3

thus transforming the binary `101111101101' from the last example into
octal `5755',

man_number-rep
Description: Text document