bug#11326: 24.1.50; doc of `dired-recursive-copies', `dired-recursive-deletes'

bug#11326: 24.1.50; doc of `dired-recursive-copies', `dired-recursive-deletes'

[Drew Adams]

The doc strings are incomprehensible, especially the one for *-copies.
They do not explain what is meant by a "recursive copy" or a "recursive
delete".  A copy is a duplicate.  What is a recursive copy?  What is a
"recursive delete"?
 
The fault is to use "recursive" in combination with "copy/delete" as a
noun instead of a verb.  This is not about recursive objects (which is
what nouns denote).  It is about acting recursively.
 
Recursive copying makes sense, and users can figure out what is meant
by that term.  A "recursive copy" makes no sense.  Similarly
"recursive delete" vs recursively deleting.
 
(And FWIW there is no such thing as a "delete".  The correct noun here
is "deletion".  A correct noun phrase is "delete operation".  But not
just "delete".)
 
See the Emacs manual description for `dired-recursive-copies' - it makes
sense:
 
     The variable `dired-recursive-copies' controls whether to copy
     directories recursively (like `cp -r').  The default is `top',
     which means to ask before recursively copying a directory.
 
For `dired-recursive-deletes', the Emacs manual says this, which also
makes sense:
 
     You can delete empty directories just like other files, but normally
     Dired cannot delete directories that are nonempty.  If the variable
     `dired-recursive-deletes' is non-`nil', then Dired can delete nonempty
     directories including all their contents.  That can be somewhat risky.
 
The doc string for `dired-recursive-deletes' is slightly better than
that for `dired-recursive-copies', because it at least mentions deleting
recursively.  But it still suffers from talking about "recursive
deletes".
 
Please look to the descriptions in the manual for guidance wrt these doc
strings.
 

In GNU Emacs 24.1.50.1 (i386-mingw-nt5.1.2600)
 of 2012-04-23 on MARVIN
Bzr revision: 108006
agustin.martin@hispalinux.es-20120423103325-xmra3329elgzhmpc
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include
 -ID:/devel/emacs/libs/libiconv-1.13.1-1-dev/include
 -ID:/devel/emacs/libs/libxml2-2.7.8/include/libxml2'
 

bug#11326: 24.1.50; doc of `dired-recursive-copies', `dired-recursive-deletes'

[Drew Adams]

> The doc string for `dired-recursive-deletes' is slightly better than
> that for `dired-recursive-copies', because it at least 
> mentions deleting recursively.

This part was wrong.  They both mention copying/deleting recursively.

But the rest of what I wrote was correct.  It is misleading and unclear to talk
about recursive copies etc.

bug#11326: 24.1.50; doc of `dired-recursive-copies', `dired-recursive-deletes'

[Chong Yidong]

> A copy is a duplicate.  What is a recursive copy?  What is a
> "recursive delete"?

Should be obvious, but I clarified the docstrings.