bug#35367: 26.2; `dired-copy-how-to-fn' and HOW-TO arg of `dired-create-files'

[Drew Adams <drew.adams@oracle.com>]

1. I believe `dired-copy-how-to-fn' was added to Emacs quite a while ago
   (1991[1]).  But it's not clear to me what it's really for, and there
   seem to be no uses of it in the distributed Emacs code, apart from
   `dired-do-copy', which just passes it on to `dired-create-files'.
   The variable's doc just says to "See HOW-TO argument for
   `dired-create-files'."

   So why was this variable created?

2. Apart from the variable, why was the HOW-TO arg of
   `dired-do-create-files' added?  I find no uses of it, apart from
   `dired-do-copy' (which just passes it along).

   Presumably someone thought that someone might want to pass such a
   thing to `dired-do-copy', but why?

   Half the doc of `dired-do-create-files' is for this parameter.  And
   its description, although probably correct and complete, reads like
   gobbledygook, to me.

   For one thing, the nil case should not be described under this
   parameter; it should be described as the function's default behavior,
   up above the parameter list.  (That's already 4 lines of its
   description.)

   Beyond that:

   * A value of `t' is unclear to me.  What does it mean to target a
     plain file - is this the same as using a `nil' value?  What happens
     with `t' if the target is a directory or if there are multiple
     marked files?  Is that where the difference lies somehow (how)?

   * A unary function value is the most confusing.  I can't follow it,
     I'm afraid.

   If HOW-TO is to stay (and I assume it is) then we really need some
   kind of motivating explanation - perhaps an example of why/when/how
   you would use a function here.  With no existing examples in the code
   this seems a bit
   maybe-someone-someday-might-need-this-thing-that-somebody-dreamed.

   It was apparently RMS who added this [1].  I'm surprised that it's
   not more clear what good it is.

[1] https://debbugs.gnu.org/cgi/bugreport.cgi?bug=25075#20


In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32)
 of 2019-04-13
Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''