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

From: kalle <[email-masked]>
Date: Wed, 11 Apr 2018 14:44:36 +0200

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