Documentation fix

Documentation fix

[Po Lu]

Would someone who can please install the following change to emacs-29?
Savannah seems to be down again.

2023-04-07  Po Lu  <luangruo@yahoo.com>

	* doc/lispref/frames.texi (Drag and Drop): Fix
	description of `x-dnd-direct-save-function'.

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 9083b4b01c9..fd3bf67cf9f 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -4177,19 +4177,25 @@ Drag and Drop
   However, @code{x-dnd-types-alist} does not handle a special kind of
 drop sent by a program that wants Emacs to tell it where to save a
 file in a specific location determined by the user.  These drops are
-instead handled by a function that is the value of the variable
-@code{x-dnd-direct-save-function}.  This function should accept two arguments.
-If the first argument is non-@code{nil}, then the second argument is a
-file name to save (with leading directories) that the other
-program recommends, and the
-function should return the full file name under which it should be
-saved.  After the function completes, Emacs will ask the other program
-to save the file under the name that was returned, and if the file was
-successfully saved, call the function again with the first argument
-set to a non-@code{nil} value 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.)
+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.
+
+  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.
+
+  If the file was successfully saved, 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.)
 
 @cindex initiating drag-and-drop
   On capable window systems, Emacs also supports dragging contents

Re: Documentation fix

[Eli Zaretskii]

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

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.

Re: Documentation fix

[Eli Zaretskii]

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

Re: Documentation fix

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

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

No, you didn't.  Thanks.