Subject: bug#24897: 24.5; doc for `M' in Dired

From: Drew Adams <[email-masked]>
Date: Sun, 13 Oct 2019 23:21:51 +0000 (UTC)

> Are you suggesting that we fully document how both symbolic and octal
> modes work on Unix-like systems here?

How they work?  No.
Everything about them ("fully")?  No.
Something about them - a simple example?  Why not?

I suggest something like this: Instead of
"symbolic modes like `g+w'" we say
"symbolic modes like `a+w' and `a-w'".

`a+w' and `a-w'o are likely the most useful for users on
MS Windows.  And I think it helps to show both + and -.

(I wouldn't mind if we even indicated that +w adds write
permission and -w takes it away.  But I don't push for that.)

> If so, I think it's outside the
> scope of this doc string.  Linking to separate documentation seems
> more sensible, and the new patch I suggested does that.

Linking to complete doc (which is necessarily outside
Emacs, as you say), is helpful, of course.  It's even
necessary.

But the Emacs doc can provide at least a little help -
something simple that even an MS Windows user can use.
A simple example can go a long way.

> +Note that on MS-Windows only the `w' (write) bit is meaningful:
> +resetting it makes the file read-only.  Changing any other bit
> +has no effect on MS-Windows

I'm not sure "resetting" is as clear as this can be.
How about something like this?

  Note that on MS-Windows only the `w' (write) bit is
  meaningful.  Adding it (`a+w') makes a file writable.
  Removing it (`a-w') makes a file read-only.  Changing
  any other bit has no effect on MS-Windows.

(I also think, but Eli will correct me - and this might
depend on one's setup, that the use of `g',`u', and `o'
is useless on MS Windows.  At least in my case there's
no distinction between `g', `u', `o', and `a'.  But I
think I recall Eli saying that it is possible on Windows
for these to make a difference.)

Anyway, what you have already is an improvement.  Thx.