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

[Lars Ingebrigtsen <larsi@gnus.org>]

Drew Adams <drew.adams@oracle.com> writes:

> 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?

I hoped that the code might throw some light on this variable, but:

(defun dired-into-dir-with-symlinks (target)
  (and (file-directory-p target)
       (not (file-symlink-p target))))
;; This may not always be what you want, especially if target is your
;; home directory and it happens to be a symbolic link, as is often the
;; case with NFS and automounters.  Or if you want to make symlinks
;; into directories that themselves are only symlinks, also quite
;; common.

;; So we don't use this function as value for HOW-TO in
;; dired-do-symlink, which has the minor disadvantage of
;; making links *into* a symlinked-dir, when you really wanted to
;; *overwrite* that symlink.  In that (rare, I guess) case, you'll
;; just have to remove that symlink by hand before making your marked
;; symlinks.

(defvar dired-copy-how-to-fn nil
  "Either nil or a function used by `dired-do-copy' to determine target.
See HOW-TO argument for `dired-do-create-files'.")

It's still clear as mud to me.

> 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.)

Well...  I think it makes sense (in so far as this parameter makes any
sense) to keep it where it is:

Optional arg HOW-TO determines how to treat the target.
  If HOW-TO is nil, use `file-directory-p' to determine if the
   target is a directory.  If so, the marked file(s) are created
   inside that directory.  Otherwise, the target is a plain file;
   an error is raised unless there is exactly one marked file.
  If HOW-TO is t, target is always treated as a plain file.
  Otherwise, HOW-TO should be a function of one argument, TARGET.
   If its return value is nil, TARGET is regarded as a plain file.
   If it return value is a list, TARGET is a generalized
    directory (e.g. some sort of archive).  The first element of
    this list must be a function with at least four arguments:
      operation - as OPERATION above.
      rfn-list  - list of the relative names for the marked files.
      fn-list   - list of the absolute names for the marked files.
      target    - the name of the target itself.
    The rest of elements of the list returned by HOW-TO are optional
    arguments for the function that is the first element of the list.
   For any other return value, TARGET is treated as a directory."


>    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)?

My interpretation of t is that all files you copy will up in the same
file if it's t, which is a supremely useless thing, you'd think...

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

Does anybody know what this parameter and variable was meant to do, and
whether it's used anywhere out-of-tree?

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