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

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

[Drew Adams]

This: http://emacs.stackexchange.com/q/28504/105, asks how to make files
read-only using Dired.  Besides using wdired, the obvious answer is to
use `M'.

However, in answering that, it becomes clear that the questioner does
not know the UNIX command `chmod', and might not know about file and
directory permissions.  S?he might not even have what it takes locally
to use `M-x man', to find out.  And the doc for `M' - both the doc
string and the Emacs manual, does not really explain `chmod' or what
kind of input a user can type to the prompt from `M'.

I think it would be helpful, for at least some users, to add some more
explanation.  In particular, it could explain about u, g, o, and a, and
about the permissions fields rwx and their values.


In GNU Emacs 24.5.1 (i686-pc-mingw32)
 of 2015-04-11 on LEG570
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/usr --host=i686-pc-mingw32'

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

[Eli Zaretskii]

> Date: Mon, 7 Nov 2016 10:52:13 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 
> This: http://emacs.stackexchange.com/q/28504/105, asks how to make files
> read-only using Dired.  Besides using wdired, the obvious answer is to
> use `M'.
> 
> However, in answering that, it becomes clear that the questioner does
> not know the UNIX command `chmod', and might not know about file and
> directory permissions.

Since the original question was about "making the file read-only", I'm
guessing the OP is on Windows, and if that is so, explaining the
Unix-style permission bits won't help a bit.

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

[Drew Adams]

> Since the original question was about "making the file read-only",
> I'm guessing the OP is on Windows,

That the user might be on Windows is a good guess.  Or s?he could just
be a beginner wrt UNIX (or GNU/Linux).

> and if that is so, explaining the
> Unix-style permission bits won't help a bit.

True enough for r and x, but not for w.  It is reasonable for a user
on Windows to use `M' to make files read-only or writable.

A little bit more help from the doc for such users could help, I think.

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

[Eli Zaretskii]

> Date: Mon, 7 Nov 2016 11:28:52 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 24897@debbugs.gnu.org
> 
> > and if that is so, explaining the
> > Unix-style permission bits won't help a bit.
> 
> True enough for r and x, but not for w.  It is reasonable for a user
> on Windows to use `M' to make files read-only or writable.

But there's no "write" bit on Windows, at least not on the level on
which the 'M' command in Dired works on Windows.  So you cannot really
explain the w bit, either.

You need a completely separate description for Windows users.

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

[Drew Adams]

> But there's no "write" bit on Windows, at least not on the level on
> which the 'M' command in Dired works on Windows.  So you cannot
> really explain the w bit, either.
> 
> You need a completely separate description for Windows users.

I don't suggest that we "explain the w bit", for Windows users.

My suggestion is to:

1. State that `chmod' does not apply, in general, to MS Windows.
   (If you want to say why - no such bits etc., fine, but that's
   not really needed, IMO.)
2. State that you can use `chmod' to make a file writable or
   read-only.  And say how to do so.

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 733 bytes --]

tags 24897 + patch
quit

Drew Adams <drew.adams@oracle.com> writes:

>> But there's no "write" bit on Windows, at least not on the level on
>> which the 'M' command in Dired works on Windows.  So you cannot
>> really explain the w bit, either.
>>
>> You need a completely separate description for Windows users.
>
> I don't suggest that we "explain the w bit", for Windows users.
>
> My suggestion is to:
>
> 1. State that `chmod' does not apply, in general, to MS Windows.
>    (If you want to say why - no such bits etc., fine, but that's
>    not really needed, IMO.)
> 2. State that you can use `chmod' to make a file writable or
>    read-only.  And say how to do so.

How about the attached patch?

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-lisp-dired-aux.el-dired-do-chmod-Doc-fix.-Bug-24897.patch --]
[-- Type: text/x-patch, Size: 1013 bytes --]

From b439ecc70b7f13f2559281316924253492f52b2d Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Fri, 11 Oct 2019 16:37:44 +0200
Subject: [PATCH] * lisp/dired-aux.el (dired-do-chmod): Doc fix.  (Bug#24897)

---
 lisp/dired-aux.el | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index bfc37c5cde..ba7d80cb0e 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -367,7 +367,12 @@ dired-do-chmod
   "Change the mode of the marked (or next ARG) files.
 Symbolic modes like `g+w' are allowed.
 Type M-n to pull the file attributes of the file at point
-into the minibuffer."
+into the minibuffer.
+
+See the man page for \"chmod\" for more information on file mode
+bits, using the command \\[man] in Emacs.
+
+This command is generally not relevant on MS-Windows."
   (interactive "P")
   (let* ((files (dired-get-marked-files t arg nil nil t))
 	 ;; The source of default file attributes is the file at point.
-- 
2.20.1

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Fri, 11 Oct 2019 16:43:23 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, 24897@debbugs.gnu.org
> 
> +See the man page for \"chmod\" for more information on file mode
> +bits, using the command \\[man] in Emacs.

On GNU/Linux, 'chmod' is documented in the Coreutils Info manual, and
the GNU Coding Standards generally prefer Info to man pages.  So I'd
suggest to point to the Coreutils manual first, and to the man page
only as fallback.

> +This command is generally not relevant on MS-Windows."

This is too extreme.  The correct statement is this:

  Note that on MS-Windows this command can only set or reset
  the `w' (write) bit, but cannot change any other bits.

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

[Eli Zaretskii]

> Date: Fri, 11 Oct 2019 17:51:31 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 24897@debbugs.gnu.org
> 
>   Note that on MS-Windows this command can only set or reset
>   the `w' (write) bit, but cannot change any other bits.

Actually, here's a more useful text:

  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.

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

[Drew Adams]

> > I don't suggest that we "explain the w bit", for Windows users.
> >
> > My suggestion is to:
> >
> > 1. State that `chmod' does not apply, in general, to MS Windows.
> >    (If you want to say why - no such bits etc., fine, but that's
> >    not really needed, IMO.)
> > 2. State that you can use `chmod' to make a file writable or
> >    read-only.  And say how to do so.
> 
> How about the attached patch?

Thanks for looking at this enhancement request.  But,
sorry, that's not it at all.

1. It's definitely not the case that "This command
is generally not relevant on MS-Windows."

`M' _is_ relevant for MS Windows.  I use it all the
time - every day.  What's the case is that on Windows
you can't distinguish the different parts of the
permissions string: you can only change them for all
users at once.

But you can certainly change, for all users, from
read-only to writable, etc.

Admittedly, the text from me that you quote above
can give the impression that `M' is not relevant
for MS Windows.  But reading all of the report
makes clear that it is very relevant.  For example:

  It is reasonable for a user on Windows to use `M'
  to make files read-only or writable.

2. The main point of the request is to ask that the
doc for `M' say something about the permissions, that
it _not_ just point to a `man' page (which typically
won't be available for MS Windows users anyway).

It's good for the doc to _also_ mention the `chmod'
command and its `man' page, but this bug report asks
that the `M' doc itself provide at least a minimum of
help about this - the possible user inputs and their
effects.

The doc currently says, e.g., "Symbolic modes like
`g+w' are allowed."  But that means nothing by itself.

This is the point of the bug report - what it says
at the outset:

  [The user might] not know the UNIX command `chmod',
  and might not know about file and directory permissions.
  S?he might not even have what it takes locally to use
  `M-x man', to find out.

  And the doc for `M' - both the doc string and the Emacs
  manual, does not really explain `chmod' or what kind of
  input a user can type to the prompt from `M'.

  I think it would be helpful, for at least some users,
  to add some more explanation.  In particular, it could
  explain about u, g, o, and a, and about the permissions
  fields rwx and their values.

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

[Drew Adams]

> >   Note that on MS-Windows this command can only set or reset
> >   the `w' (write) bit, but cannot change any other bits.
> 
> Actually, here's a more useful text:
> 
>   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.

Yes, that's fine.

(And it's good to say that `w' is a write bit.)


[But do we usually write "MS-Windows" or "MS Windows"?]

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

[Eli Zaretskii]

> Date: Fri, 11 Oct 2019 08:45:32 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 24897@debbugs.gnu.org
> 
> >   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.
> 
> Yes, that's fine.
> 
> (And it's good to say that `w' is a write bit.)
> 
> 
> [But do we usually write "MS-Windows" or "MS Windows"?]

As written.

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

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 719 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> On GNU/Linux, 'chmod' is documented in the Coreutils Info manual, and
> the GNU Coding Standards generally prefer Info to man pages.  So I'd
> suggest to point to the Coreutils manual first, and to the man page
> only as fallback.

Yes, good thinking.  But I pointed to the "File permissions" section
instead, which seemed more to the point.

> Actually, here's a more useful text:
>
>   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.

Thanks.  I'm pretty ignorant about MS-Windows so that definitely helps.

How about the attached?

Best regards,
Stefan Kangas

[-- Attachment #2: 0001-Improve-documentation-of-dired-do-chmod.patch --]
[-- Type: text/x-patch, Size: 1464 bytes --]

From 6ff8d2e525dc2b948059033d7901288f0921d576 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Fri, 11 Oct 2019 16:37:44 +0200
Subject: [PATCH] Improve documentation of dired-do-chmod

* lisp/dired-aux.el (dired-do-chmod): Doc fix.  The part about
MS-Windows was written by Eli Zaretskii.  (Bug#24897)
---
 lisp/dired-aux.el | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index bfc37c5cde..8bda25e9e3 100644
--- a/lisp/dired-aux.el
+++ b/lisp/dired-aux.el
@@ -365,9 +365,17 @@ dired-do-chxxx
 ;;;###autoload
 (defun dired-do-chmod (&optional arg)
   "Change the mode of the marked (or next ARG) files.
-Symbolic modes like `g+w' are allowed.
-Type M-n to pull the file attributes of the file at point
-into the minibuffer."
+Both octal numeric modes like `644' and symbolic modes like `g+w'
+are supported.  Type M-n to pull the file attributes of the file
+at point into the minibuffer.
+
+See Info node `(coreutils)File permissions' for more information.
+Alternatively, see the man page for \"chmod\", using the command
+\\[man] in Emacs.
+
+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."
   (interactive "P")
   (let* ((files (dired-get-marked-files t arg nil nil t))
 	 ;; The source of default file attributes is the file at point.
-- 
2.20.1

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

[Stefan Kangas]

Thanks for your comments Drew.  I think the patch I sent separately
fixes your comments, but see also below.

Drew Adams <drew.adams@oracle.com> writes:

> 2. The main point of the request is to ask that the
> doc for `M' say something about the permissions, that
> it _not_ just point to a `man' page (which typically
> won't be available for MS Windows users anyway).
[...]
> It's good for the doc to _also_ mention the `chmod'
> command and its `man' page, but this bug report asks
> that the `M' doc itself provide at least a minimum of
> help about this - the possible user inputs and their
> effects.

Are you suggesting that we fully document how both symbolic and octal
modes work on Unix-like systems here?  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.

See also:
https://www.gnu.org/software/coreutils/manual/html_node/File-permissions.html

Best regards,
Stefan Kangas

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

[Drew Adams]

> 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.

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Mon, 14 Oct 2019 00:37:57 +0200
> Cc: 24897@debbugs.gnu.org
> 
> How about the attached?

LGTM, please install, and thanks.

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

[Eli Zaretskii]

> Date: Sun, 13 Oct 2019 23:21:51 +0000 (UTC)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, 24897@debbugs.gnu.org
> 
> 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 -.

On Windows there's no difference between a+w, g+w, u+w, and o+w.  You
will just confuse people by giving them too many examples.  They
should read the full docs instead (if they want to use this facility,
which on Windows I find not very probable).

> > +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.

It's clear enough IMNSHO.  Let's not split hair here, shall we?

> 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.

See above: using a- or a+ only muddies the water.

> (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'.

"No distinction" is correct, "useless" in confusingly misleading.

I think the doc string is fine as proposed in the last message, we
should stop bikeshedding about this minor issue.

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

[Stefan Kangas]

Eli Zaretskii <eliz@gnu.org> writes:

> > How about the attached?
>
> LGTM, please install, and thanks.

Thanks.  Pushed to master as commit ed29d0239a.

Best regards,
Stefan Kangas