From 12e5171882afb2bb31e3505cb077953b342920af Mon Sep 17 00:00:00 2001
From: Po Lu <luangruo@yahoo.com>
Date: Fri, 1 Jul 2022 18:10:39 +0800
Subject: [PATCH] Document XDS stuff

* doc/emacs/frames.texi (Drag and Drop):
* doc/lispref/frames.texi (Drag and Drop): Add documentation
about XDS features.
* etc/NEWS: Tag entry.
---
 doc/emacs/frames.texi   |  7 +++++++
 doc/lispref/frames.texi | 14 ++++++++++++++
 etc/NEWS                |  1 +
 3 files changed, 22 insertions(+)

diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi
index d90a6ac6729..d78cbffaa71 100644
--- a/doc/emacs/frames.texi
+++ b/doc/emacs/frames.texi
@@ -1249,6 +1249,13 @@ To drag text from Emacs to other programs, set the option
 @code{mouse-drag-and-drop-region-cross-program} to a non-@code{nil}
 value.
 
+  On the X window system, some programs can drop files on Emacs,
+expecting Emacs to save them.  Normally, Emacs will prompt for a file
+name under which the file will be saved, and then open the file, but
+that behavior can be changed by changing the variable
+@code{x-dnd-direct-save-function}.  @xref{Drag and Drop,,, elisp, The
+Emacs Lisp Reference Manual}.
+
 @node Menu Bars
 @section Menu Bars
 @cindex menu bar mode
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index f7491502f4c..f655ccdfa73 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -4090,6 +4090,20 @@ They can either be the same data types that are typically accepted by
 specific drag-n-drop protocol being used.  Plain text may be
 @code{"STRING"} or @code{"text/plain"}, for example.
 
+@vindex x-dnd-direct-save-function
+  However, @code{x-dnd-types-alist} does not handle a special kind of
+drop sent by a program which wants Emacs to save a file in a location
+Emacs must determine by itself.  These drops are handled via the
+variable @code{x-dnd-direct-save-function}, which should be a function
+that accepts two arguments.  If the first argument is non-@code{nil},
+then the second argument is a string describing the name (with no
+leading directory) that the other program recommends the file be saved
+under, and the function should return the complete file name under
+which it will be saved.  Otherwise, the file has already been saved,
+and the second argument is the complete name of the file.  The
+function should then perform whatever action is appropriate (i.e.,
+open the file or refresh the directory listing.)
+
 @cindex initiating drag-and-drop
   On capable window systems, Emacs also supports dragging contents
 from its frames to windows of other applications.
diff --git a/etc/NEWS b/etc/NEWS
index b0a5cd4f1db..3127e734261 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -423,6 +423,7 @@ This inhibits putting empty strings onto the kill ring.
 These options allow adjusting point and scrolling a window when
 dragging items from another program.
 
++++
 ** The X Direct Save (XDS) protocol is now supported.
 This means dropping an image or file link from programs such as
 Firefox will no longer create a temporary file in a random directory,
-- 
2.39.5