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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 35367 in the body.
You can then email your comments to 35367 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.2; `dired-copy-how-to-fn' and HOW-TO arg of `dired-create-files'
Date: Sun, 21 Apr 2019 12:30:14 -0700 (PDT)

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

Message #8 received at 35367 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 35367 <at> debbugs.gnu.org
Subject: Re: bug#35367: 26.2;
 `dired-copy-how-to-fn' and HOW-TO arg of `dired-create-files'
Date: Tue, 09 Jul 2019 16:21:24 +0200

Drew Adams <drew.adams <at> 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

Message #11 received at 35367 <at> debbugs.gnu.org (full text, mbox):

From: Mike Kupfer <mkupfer <at> alum.berkeley.edu>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 35367 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#35367: 26.2;
 `dired-copy-how-to-fn' and HOW-TO arg of `dired-create-files'
Date: Wed, 10 Jul 2019 22:51:11 -0700

Lars Ingebrigtsen wrote:

> Drew Adams <drew.adams <at> oracle.com> writes:
> 
> > 1. I believe `dired-copy-how-to-fn' was added to Emacs quite a while ago
> >    (1991[1]).

lisp/ChangeLog.8 in the 25.3 tarball attributes the change to Inge
Frick, with a date of 1999-09-14 (a couple days before the date listed
in bug#25075).

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

Presumably it's so you could override dired's behavior for handling a
target.  If the target is a symlink to a directory, the default behavior
would be to treat it as a directory, but maybe there are cases where you
want to replace the link instead.

The bit about

   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:

looks like it might be useful when the target is, for example, a tar
file.  By default, copying a single file would replace the tar file.
But this could be overridden (I think) to add or replace entries in the
tar file.

Besides the possibility of a user setting dired-copy-how-to-fn, I can
imagine a package might want to dynamically rebind dired-copy-how-to-fn,
perhaps as a buffer-local variable in a dired buffer.  (I'm not sure
what sort of package might want to do that, but it seems like a possible
reason for having a variable.)

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

dired-into-dir-with-symlinks returns t if TARGET is a real directory.
It returns nil if TARGET is a plain file or a symlink to a directory.
The first generation automounter(s) mounted your home directory in a
temporary directory and then created a symlink to the mounted directory.
But $HOME would be the path to the symlink.

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

No, you can only copy one file if the target is a plain file.  From
earlier in the docstring for dired-do-create-files:

    The target may also be a non-directory file, if only
    one file is marked.

Maybe this sentence should be deleted:

    Otherwise, the target is a plain file;
    an error is raised unless there is exactly one marked file.

The way the docstring is currently written, it seems to imply that the
error only gets raised in the case where HOW-TO is nil.

I agree that this is all very complicated and confusing.  It doesn't
help that if HOW-TO is t, the target is treated as a plain file.  But if
HOW-TO is a function, it returns nil to indicate a plain file.

mike

Message #14 received at 35367 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Mike Kupfer <mkupfer <at> alum.berkeley.edu>
Cc: 35367 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#35367: 26.2;
 `dired-copy-how-to-fn' and HOW-TO arg of `dired-create-files'
Date: Thu, 11 Jul 2019 16:04:48 +0200

Mike Kupfer <mkupfer <at> alum.berkeley.edu> writes:

> Presumably it's so you could override dired's behavior for handling a
> target.  If the target is a symlink to a directory, the default behavior
> would be to treat it as a directory, but maybe there are cases where you
> want to replace the link instead.

Ah, I see.

[More useful explanation deleted; thanks for figuring it out.]

>> 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...
>
> No, you can only copy one file if the target is a plain file.  From
> earlier in the docstring for dired-do-create-files:
>
>     The target may also be a non-directory file, if only
>     one file is marked.
>
> Maybe this sentence should be deleted:
>
>     Otherwise, the target is a plain file;
>     an error is raised unless there is exactly one marked file.
>
> The way the docstring is currently written, it seems to imply that the
> error only gets raised in the case where HOW-TO is nil.
>
> I agree that this is all very complicated and confusing.  It doesn't
> help that if HOW-TO is t, the target is treated as a plain file.  But if
> HOW-TO is a function, it returns nil to indicate a plain file.

Could you perhaps propose a rewrite of the doc string here to make it
more understandable; both what it does and say when it might be useful?

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

Message #17 received at 35367 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Mike Kupfer <mkupfer <at> alum.berkeley.edu>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 35367 <at> debbugs.gnu.org
Subject: RE: bug#35367: 26.2; `dired-copy-how-to-fn' and HOW-TO arg of
 `dired-create-files'
Date: Thu, 11 Jul 2019 07:18:26 -0700 (PDT)

Thanks, Mike.  I probably would never have
figured out all of that.

Kinda seems odd that we'd have created a
variable for something that someone _might_
want to do (but probably never has done).

Usually, when someone proposes something
like that it gets rejected as fulfilling
only a hypothetical need.

Anyway, if the variable will stay then it
would be great if the doc could be fixed
a bit, based on some of what you said here.

Message #20 received at 35367 <at> debbugs.gnu.org (full text, mbox):

From: Mike Kupfer <mkupfer <at> alum.berkeley.edu>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 35367 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: Re: bug#35367: 26.2;
 `dired-copy-how-to-fn' and HOW-TO arg of `dired-create-files'
Date: Thu, 11 Jul 2019 20:20:27 -0700

Drew Adams wrote:

> Kinda seems odd that we'd have created a
> variable for something that someone _might_
> want to do (but probably never has done).
> 
> Usually, when someone proposes something
> like that it gets rejected as fulfilling
> only a hypothetical need.

Indeed.  Maybe there were consumers of dired-copy-how-to-fn back in the
1990s.  While poking around in the sources I noticed a comment in
vc-dir.el saying that it *used to be* based on dired.  (Or maybe whoever
was the Emacs maintainer at the time thought dired-copy-how-to-fn was a
cool idea and didn't insist on having a consumer for it.)

> Anyway, if the variable will stay then it
> would be great if the doc could be fixed
> a bit, based on some of what you said here.

I can try proposing clearer wording for the dired-do-create-files
docstring, though it'll probably be several days before I can get to it.

I want to be cautious about proposing ways to use dired-copy-how-to-fn.
My earlier comments were based on my reading of the documentation and a
tiny bit of testing.  I wasn't involved with Emacs development when the
dired how-to stuff was introduced, so I don't have any special insights
into what the thinking was at the time.  Though the more I think about
my tarfile example, the more I think it'd be a fun little hack.

mike

Message #23 received at 35367 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Mike Kupfer <mkupfer <at> alum.berkeley.edu>
Cc: 35367 <at> debbugs.gnu.org, Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: RE: bug#35367: 26.2; `dired-copy-how-to-fn' and HOW-TO arg of
 `dired-create-files'
Date: Thu, 11 Jul 2019 20:33:47 -0700 (PDT)

> > Kinda seems odd that we'd have created a
> > variable for something that someone _might_
> > want to do (but probably never has done).
> >
> > Usually, when someone proposes something
> > like that it gets rejected as fulfilling
> > only a hypothetical need.
> 
> Indeed.  Maybe there were consumers of dired-copy-how-to-fn back in the
> 1990s.  While poking around in the sources I noticed a comment in
> vc-dir.el saying that it *used to be* based on dired.  (Or maybe whoever
> was the Emacs maintainer at the time thought dired-copy-how-to-fn was a
> cool idea and didn't insist on having a consumer for it.)
> 
> > Anyway, if the variable will stay then it
> > would be great if the doc could be fixed
> > a bit, based on some of what you said here.
> 
> I can try proposing clearer wording for the dired-do-create-files
> docstring, though it'll probably be several days before I can get to it.
> 
> I want to be cautious about proposing ways to use dired-copy-how-to-fn.
> My earlier comments were based on my reading of the documentation and a
> tiny bit of testing.  I wasn't involved with Emacs development when the
> dired how-to stuff was introduced, so I don't have any special insights
> into what the thinking was at the time.  Though the more I think about
> my tarfile example, the more I think it'd be a fun little hack.

Sounds good.  I don't think you have to worry
about hurrying.  Instead of several days it
could probably be several years (decades?)
without anyone noticing. ;-)

Message #26 received at 35367 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Mike Kupfer <mkupfer <at> alum.berkeley.edu>
Cc: 35367 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#35367: 26.2; `dired-copy-how-to-fn' and HOW-TO arg of
 `dired-create-files'
Date: Sat, 22 Jan 2022 15:43:35 +0100

Mike Kupfer <mkupfer <at> alum.berkeley.edu> writes:

> The bit about
>
>    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:
>
> looks like it might be useful when the target is, for example, a tar
> file.  By default, copying a single file would replace the tar file.
> But this could be overridden (I think) to add or replace entries in the
> tar file.

I've now added something like this to the doc string in Emacs 29, and
that should hopefully clarify the use case slightly.

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.