Re: Documentation fix

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> Does this mean the function gets on the basename of the file, without
> any leading directories?  Or does it mean something else?

Yes.

>> +  The function should return the complete file name under which the
>> +file should be saved, including the directory where it should be
>> +saved, under which Emacs will ask the other program to save the file.
>
> How would the function know what is the "right" directory to save the
> file?  Without some hints to that effect, this documentation is not
> very useful, IMO.

How about:

  For example, a function defined for Dired buffers may want to return
  the directory containing the file under the position of the drop.

>> +  If the file was successfully saved,
>
> And if not?

Emacs never gets a reply from the program performing the drop, and thus
cannot do anything.

>>                                        the function is called again,
>> +this time with the first argument set to @code{nil}, and the second
>> +argument set to the file name that was returned.  The function should
>> +then perform whatever action is appropriate (i.e., opening the file or
>> +refreshing a directory listing.)             ^^^^
>
> I guess, you mean "e.g." there.

Yes, sorry.

> More importantly, I don't understand why would Emacs need to do
> anything with the file at all.  As a matter of fact, I don't think I
> understand the purpose of this protocol at all, and I don't see it
> clarified in the manual.  Can you explain what is this used for?
> Without such explanation, this documentation lacks context without
> which the information makes no sense.

It allows a program to drop files into a file manager, such as Dired,
and directly save the file into the directory that is currently open in
the file manager's window.

This is a three-step process:

  1. The program performing the drop sends the name of a file to Emacs,
  such as gen_sqrtab.c.

  2. Emacs replies with the file name under which the file should be
  saved.  If it's dropped on top of a Dired buffer visiting
  /export/home/user/Documents, for example, Emacs should reply with
  /export/home/user/Documents/gen_sqrtab.c.

  3. If saving the file is successful, the program performing the drop
  notifies Emacs, at which point the Dired buffer is reverted.

This protocol is mainly supported by web browsers and GTK based file
managers, and now Emacs as well.