bug#907: 23.0.60; doc string for dired-do-create-files

bug#907: 23.0.60; doc string for dired-do-create-files

[Drew Adams]

emacs -Q
Same problem exists in Emacs 22.2, BTW.
 
The doc string of dired-do-create-files refers several times to
`into-dir' (without quotes or uppercase). Nowhere is there any
explanation of what is mean by this, however. Presumably, it is either
a global variable or an argument?
 
This renders the doc string incomprehensible. About 2/3 of the doc
string concerns `into-dir', and it includes a seemingly ridiculously
complex explanation of arg HOW-TO, complete with
if-then-else-if-then-else-if-then-else-if-then-else (no
exaggeration!).
 
Please rewrite the doc string so that it is self-contained and
readable. It should not simply mirror the code but should make clear
to users what each argument is.
 

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'
 

bug#907: 23.0.60; doc string for dired-do-create-files

[Drew Adams]

I said:

> This renders the doc string incomprehensible. About 2/3 of the doc
> string concerns `into-dir', and it includes a seemingly ridiculously
> complex explanation of arg HOW-TO, complete with
> if-then-else-if-then-else-if-then-else-if-then-else (no
> exaggeration!).

I was a little mistaken. It's both a bit worse and a bit better than I thought.

The last if-then-else-if-then-else supposedly explains HOW-TO; the first
if-then-else-if-then-else supposedly explains `into-dir' (which is an internal,
local variable).

This is all backwards and not clear at all. What's needed is a single,
straightforward explanation of HOW-TO, with no reference to `into-dir'.

Looking at previous Emacs versions, I discovered that this doc string derives
from a comment that was in the Emacs 20 code. The comment, which referred to
local variable `into-dir', was simply copied to a (then missing) doc string.

The rest still applies: 

> Please rewrite the doc string so that it is self-contained and
> readable. It should not simply mirror the code but should make clear
> to users what each argument is.

bug#907: marked as done (23.0.60; doc string for dired-do-create-files)

[Emacs bug Tracking System]

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


Your message dated Wed, 22 Oct 2008 16:21:49 -0400
with message-id <87wsg0bcte.fsf@cyd.mit.edu>
and subject line Re: 23.0.60; doc string for dired-do-create-files
has caused the Emacs bug report #907,
regarding 23.0.60; doc string for dired-do-create-files
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact don@donarmstrong.com
immediately.)


-- 
907: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=907
Emacs Bug Tracking System
Contact don@donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 3451 bytes --]

From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-pretest-bug@gnu.org>
Subject: 23.0.60; doc string for dired-do-create-files
Date: Sat, 6 Sep 2008 15:31:51 -0700
Message-ID: <000501c91070$5bc6b320$0200a8c0@us.oracle.com>

emacs -Q
Same problem exists in Emacs 22.2, BTW.
 
The doc string of dired-do-create-files refers several times to
`into-dir' (without quotes or uppercase). Nowhere is there any
explanation of what is mean by this, however. Presumably, it is either
a global variable or an argument?
 
This renders the doc string incomprehensible. About 2/3 of the doc
string concerns `into-dir', and it includes a seemingly ridiculously
complex explanation of arg HOW-TO, complete with
if-then-else-if-then-else-if-then-else-if-then-else (no
exaggeration!).
 
Please rewrite the doc string so that it is self-contained and
readable. It should not simply mirror the code but should make clear
to users what each argument is.
 

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'
 




[-- Attachment #3: Type: message/rfc822, Size: 1208 bytes --]

From: Chong Yidong <cyd@stupidchicken.com>
To: "Drew Adams" <drew.adams@oracle.com>
Cc: 907-done@emacsbugs.donarmstrong.com
Subject: Re: 23.0.60; doc string for dired-do-create-files
Date: Wed, 22 Oct 2008 16:21:49 -0400
Message-ID: <87wsg0bcte.fsf@cyd.mit.edu>

> The doc string of dired-do-create-files refers several times to
> `into-dir' (without quotes or uppercase). Nowhere is there any
> explanation of what is mean by this, however. Presumably, it is either
> a global variable or an argument?

Fixed, thanks.