GNU bug report logs - #24897
24.5; doc for `M' in Dired

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 24897 in the body.
You can then email your comments to 24897 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.5; doc for `M' in Dired
Date: Mon, 7 Nov 2016 10:52:13 -0800 (PST)

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'

Message #8 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24897 <at> debbugs.gnu.org
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Mon, 07 Nov 2016 21:22:42 +0200

> Date: Mon, 7 Nov 2016 10:52:13 -0800 (PST)
> From: Drew Adams <drew.adams <at> 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.

Message #11 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 24897 <at> debbugs.gnu.org
Subject: RE: bug#24897: 24.5; doc for `M' in Dired
Date: Mon, 7 Nov 2016 11:28:52 -0800 (PST)

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

Message #14 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24897 <at> debbugs.gnu.org
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Mon, 07 Nov 2016 21:50:04 +0200

> Date: Mon, 7 Nov 2016 11:28:52 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 24897 <at> 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.

Message #17 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 24897 <at> debbugs.gnu.org
Subject: RE: bug#24897: 24.5; doc for `M' in Dired
Date: Mon, 7 Nov 2016 12:39:11 -0800 (PST)

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

Message #20 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24897 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Fri, 11 Oct 2019 16:43:23 +0200

[Message part 1 (text/plain, inline)]

tags 24897 + patch
quit

Drew Adams <drew.adams <at> 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

[0001-lisp-dired-aux.el-dired-do-chmod-Doc-fix.-Bug-24897.patch (text/x-patch, attachment)]

Message #25 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 24897 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Fri, 11 Oct 2019 17:51:31 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Fri, 11 Oct 2019 16:43:23 +0200
> Cc: Eli Zaretskii <eliz <at> gnu.org>, 24897 <at> 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.

Message #28 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: stefan <at> marxist.se
Cc: 24897 <at> debbugs.gnu.org
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Fri, 11 Oct 2019 17:56:05 +0300

> Date: Fri, 11 Oct 2019 17:51:31 +0300
> From: Eli Zaretskii <eliz <at> gnu.org>
> Cc: 24897 <at> 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.

Message #31 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 24897 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: RE: bug#24897: 24.5; doc for `M' in Dired
Date: Fri, 11 Oct 2019 08:42:21 -0700 (PDT)

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

Message #34 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, stefan <at> marxist.se
Cc: 24897 <at> debbugs.gnu.org
Subject: RE: bug#24897: 24.5; doc for `M' in Dired
Date: Fri, 11 Oct 2019 08:45:32 -0700 (PDT)

> >   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"?]

Message #37 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24897 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Fri, 11 Oct 2019 18:57:42 +0300

> Date: Fri, 11 Oct 2019 08:45:32 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 24897 <at> 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.

Message #40 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24897 <at> debbugs.gnu.org
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Mon, 14 Oct 2019 00:37:57 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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

[0001-Improve-documentation-of-dired-do-chmod.patch (text/x-patch, attachment)]

Message #43 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24897 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Mon, 14 Oct 2019 00:38:21 +0200

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

Drew Adams <drew.adams <at> 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

Message #46 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 24897 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: RE: bug#24897: 24.5; doc for `M' in Dired
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.

Message #49 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 24897 <at> debbugs.gnu.org
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Mon, 14 Oct 2019 09:40:21 +0300

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

LGTM, please install, and thanks.

Message #52 received at 24897 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 24897 <at> debbugs.gnu.org, stefan <at> marxist.se
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Mon, 14 Oct 2019 09:46:21 +0300

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

Message #57 received at 24897-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 24897-done <at> debbugs.gnu.org
Subject: Re: bug#24897: 24.5; doc for `M' in Dired
Date: Mon, 14 Oct 2019 16:01:06 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

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

Thanks.  Pushed to master as commit ed29d0239a.

Best regards,
Stefan Kangas

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.