bug#55984: 26.3; Doc string of `chmod' / `set-file-modes'

bug#55984: 26.3; Doc string of `chmod' / `set-file-modes'

[Drew Adams]

Please consider mentioning in the doc string that the command prompts
for the file name and (then for) the modes.  The doc currently says how
the modes are read, but it doesn't say that the command reads the file
name.

In GNU Emacs 26.3 (build 1, x86_64-w64-mingw32)
 of 2019-08-29
Repository revision: 96dd0196c28bc36779584e47fffcca433c9309cd
Windowing system distributor `Microsoft Corp.', version 10.0.19044
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#55984: 26.3; Doc string of `chmod' / `set-file-modes'

[Robert Pluim]

>>>>> On Tue, 14 Jun 2022 21:36:37 +0000, Drew Adams <drew.adams@oracle.com> said:

    Drew> Please consider mentioning in the doc string that the command prompts
    Drew> for the file name and (then for) the modes.  The doc currently says how
    Drew> the modes are read, but it doesn't say that the command reads the file
    Drew> name.

Passive voice as well. How about the following for emacs-28


diff --git a/src/fileio.c b/src/fileio.c
index 7d392e0de7..a240216dea 100644
--- a/src/fileio.c
+++ b/src/fileio.c
@@ -3510,8 +3510,9 @@ DEFUN ("set-file-modes", Fset_file_modes, Sset_file_modes, 2, 3,
 Only the 12 low bits of MODE are used.  If optional FLAG is `nofollow',
 do not follow FILENAME if it is a symbolic link.
 
-Interactively, mode bits are read by `read-file-modes', which accepts
-symbolic notation, like the `chmod' command from GNU Coreutils.  */)
+Interactively, prompts for FILENAME, and reads MODE with
+`read-file-modes', which accepts symbolic notation, like the `chmod'
+command from GNU Coreutils.  */)
   (Lisp_Object filename, Lisp_Object mode, Lisp_Object flag)
 {
   CHECK_FIXNUM (mode);


Robert
-- 

bug#55984: 26.3; Doc string of `chmod' / `set-file-modes'

[Lars Ingebrigtsen]

Robert Pluim <rpluim@gmail.com> writes:

> Passive voice as well. How about the following for emacs-28

Looks good to me.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#55984: 26.3; Doc string of `chmod' / `set-file-modes'

[Robert Pluim]

tags 55984 fixed
close 55984 28.2
quit

>>>>> On Wed, 15 Jun 2022 14:19:59 +0200, Lars Ingebrigtsen <larsi@gnus.org> said:

    Lars> Robert Pluim <rpluim@gmail.com> writes:
    >> Passive voice as well. How about the following for emacs-28

    Lars> Looks good to me.

Closing.
Committed as 32cff740e2

bug#55984: 26.3; Doc string of `chmod' / `set-file-modes'

[Eli Zaretskii]

> Cc: 55984@debbugs.gnu.org
> From: Robert Pluim <rpluim@gmail.com>
> Date: Wed, 15 Jun 2022 11:03:32 +0200
> 
> Passive voice as well. How about the following for emacs-28
> 
> 
> diff --git a/src/fileio.c b/src/fileio.c
> index 7d392e0de7..a240216dea 100644
> --- a/src/fileio.c
> +++ b/src/fileio.c
> @@ -3510,8 +3510,9 @@ DEFUN ("set-file-modes", Fset_file_modes, Sset_file_modes, 2, 3,
>  Only the 12 low bits of MODE are used.  If optional FLAG is `nofollow',
>  do not follow FILENAME if it is a symbolic link.
>  
> -Interactively, mode bits are read by `read-file-modes', which accepts
> -symbolic notation, like the `chmod' command from GNU Coreutils.  */)
> +Interactively, prompts for FILENAME, and reads MODE with
> +`read-file-modes', which accepts symbolic notation, like the `chmod'
> +command from GNU Coreutils.  */)

"prompt" and "read", please, to be consistent with our preferred
style.

Otherwise OK, thanks.

bug#55984: 26.3; Doc string of `chmod' / `set-file-modes'

[Robert Pluim]

>>>>> On Wed, 15 Jun 2022 16:08:38 +0300, Eli Zaretskii <eliz@gnu.org> said:

    >> Cc: 55984@debbugs.gnu.org
    >> From: Robert Pluim <rpluim@gmail.com>
    >> Date: Wed, 15 Jun 2022 11:03:32 +0200
    >> 
    >> Passive voice as well. How about the following for emacs-28
    >> 
    >> 
    >> diff --git a/src/fileio.c b/src/fileio.c
    >> index 7d392e0de7..a240216dea 100644
    >> --- a/src/fileio.c
    >> +++ b/src/fileio.c
    >> @@ -3510,8 +3510,9 @@ DEFUN ("set-file-modes", Fset_file_modes, Sset_file_modes, 2, 3,
    >> Only the 12 low bits of MODE are used.  If optional FLAG is `nofollow',
    >> do not follow FILENAME if it is a symbolic link.
    >> 
    >> -Interactively, mode bits are read by `read-file-modes', which accepts
    >> -symbolic notation, like the `chmod' command from GNU Coreutils.  */)
    >> +Interactively, prompts for FILENAME, and reads MODE with
    >> +`read-file-modes', which accepts symbolic notation, like the `chmod'
    >> +command from GNU Coreutils.  */)

    Eli> "prompt" and "read", please, to be consistent with our preferred
    Eli> style.

I said "prompts" because itʼs describing what it does, but OK, fixed.

Robert
--