Re: Documentation fix

[Eli Zaretskii <eliz@gnu.org>]

> From: Po Lu <luangruo@yahoo.com>
> Date: Fri, 07 Apr 2023 20:04:43 +0800
> 
> Would someone who can please install the following change to emacs-29?
> Savannah seems to be down again.

It isn't down from here.

> +instead handled by a function determined by the variable
> +@code{x-dnd-direct-save-function}.  This function is essentially two
> +functions in one---its first argument is a boolean which tells it what
> +operations to perform.
> +
> +  When the drop takes place, the function is first called with its
> +first argument set to a non-@code{nil} value, and its second argument
> +set to a file name that the file should be saved under; this file name
> +does not contain the directory under which the file should be saved.

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

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

> +  If the file was successfully saved,

And if not?

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

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.

Thanks.