Re: Documentation fix

[Eli Zaretskii <eliz@gnu.org>]

> From: Po Lu <luangruo@yahoo.com>
> Cc: emacs-devel@gnu.org
> Date: Fri, 07 Apr 2023 21:37:30 +0800
> 
> 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.

Thanks.  I rewrote the documentation of the XDS support, please take a
look and tell if I made any mistakes.