Subject: bug#916 closed by Chong Yidong <[email-masked]> (Re: 23.0.60; doc string of dired-get-marked-files)

From: [email-masked] (Emacs bug Tracking System)

This is an automatic notification regarding your bug report
which was filed against the emacs package:

#916: 23.0.60; doc string of dired-get-marked-files

It has been closed by Chong Yidong <[email-masked]>.

Their explanation is attached below along with your original report.
If this explanation is unsatisfactory and you have not received a
better one in a separate message then please contact Chong Yidong <[email-masked]> by
replying to this email.

-- 
916: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=916
Emacs Bug Tracking System
Contact [email-masked] with problems
>From [email-masked] Wed Oct 22 13:39:41 2008
From: Chong Yidong <[email-masked]>
To: "Drew Adams" <[email-masked]>
Cc: [email-masked]
Subject: Re: 23.0.60; doc string of dired-get-marked-files
Date: Wed, 22 Oct 2008 16:39:40 -0400

> The doc string says this about optional arg ARG:
> 
> Optional second argument arg specifies files near point
>  instead of marked files.  If arg is an integer, use the next arg files.
>   If arg is otherwise non-nil, use file.  Usually arg comes from
>   the command's prefix arg.
> 
> This is not correct, or at least it is incomplete.

It is correct, because of the word "instead": if ARG is non-nil, it
modifies the behavior of the function.

I fixed the doc string to make this distinction clearer, and to prevent
similar confusion.

>From [email-masked] Sun Sep  7 10:17:23 2008
From: "Drew Adams" <[email-masked]>
To: <[email-masked]>
Subject: 23.0.60; doc string of dired-get-marked-files
Date: Sun, 7 Sep 2008 10:17:10 -0700

The doc string says this about optional arg ARG:
 
Optional second argument arg specifies files near point
 instead of marked files.  If arg is an integer, use the next arg files.
  If arg is otherwise non-nil, use file.  Usually arg comes from
  the command's prefix arg.
 
This is not correct, or at least it is incomplete. It says that the
current file is used if ARG is non-nil but not an integer, which is
true, but it suggests that no file is used if ARG is nil. That is, the
entire ARG description suggests that a singleton list of the current
file is returned only when ARG is non-nil. It suggests that if ARG is
nil then the empty list is returnedl.
 
In fact, if ARG is nil, the current file is used. That is,
(dired-get-marked-files) in Dired returns the singleton list of the
file where the cursor is. This behavior is not a bug; it is the doc
string that is incomplete by not covering this case.
 
The doc string should say something like this regarding ARG:
 
Optional second argument arg specifies files near point instead of
 marked files.  If arg is an integer, use the next arg files.
 Otherwise, use the file on the current line.  Usually arg comes from
 the command's prefix arg.
 
`dired-get-marked-files' uses `dired-map-over-marks', and the doc
string of that function correctly states "If no marked file could be
found, execute body on the current line."

In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600)
 of 2008-08-29 on LENNART-69DE564
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include
-fno-crossjumping'