From 23a01dd32ed21061b52557b427b2dc39a656aa8b Mon Sep 17 00:00:00 2001
Message-ID: <23a01dd32ed21061b52557b427b2dc39a656aa8b.1698051344.git.yantar92@posteo.net>
From: Ihor Radchenko <yantar92@posteo.net>
Date: Mon, 23 Oct 2023 11:50:56 +0300
Subject: [PATCH] * doc/org-manual.org (Drag and Drop & ~yank-media~): Rewrite

---
 doc/org-manual.org | 54 +++++++++++++++++++++++++---------------------
 1 file changed, 29 insertions(+), 25 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 5a17d1c1f..00eb6680b 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -21101,39 +21101,43 @@ ** Drag and Drop & ~yank-media~
 :END:
 
 #+cindex: dropping files
+#+cindex: dragging files
+#+cindex: drag and drop
+#+cindex: dnd
 #+vindex: org-dnd-method
-Org can attach, insert =file:= links, or open files dropped onto an
-Emacs frame.  By default, Org asks the user what must be done with the
-dropped file but this can be changed by customizing the user option
-~org-dnd-method~.  Changing the variable can make Org do any of the
-above mentioned actions without prompting.
+Org mode supports drag and drop (DnD) of files.  By default, Org asks
+the user what must be done with the dropped file: attach it, insert
+=file:= link, or open the file.  Customize ~org-dnd-method~ to set the
+default DnD action.
+
+When DnD method is "attach", Org mode first consults DnD metadata to
+decide the attach method.  For example, when file/files are dragged
+from a file manager, Org may attach by copying or by moving.
 
 #+vindex: org-dnd-default-attach-method
-If Org cannot figure out which attachment method to use automatically,
-it defaults to using the attachment method mentioned in
-~org-dnd-default-attach-method~.  Org uses the attachment method
-mentioned in ~org-attach-method~ by default, so Org using the =cp=
-method to attach the dropped files.
+If Org cannot figure out which attachment method to use from the
+metadata, it defaults to ~org-dnd-default-attach-method~ [fn::By
+default, ~org-dnd-default-attach-method~ is set to nil -- use the same
+value as ~org-attach-method~ (~cp~ by default).]
 
 #+cindex: pasting files, images from clipboard
-From Emacs 29, Org can deal with images copied to the clipboard, and
-files copied from a file manager when pasted using the command
-~yank-media~.  Org deals with them differently.
+Starting from Emacs 29, Org mode supports ~yank-media~ command to yank
+images from the clipboard and files from a file manager.
 
 #+vindex: org-yank-image-save-type
+When yanking images from clipboard, Org saves the image on disk and
+inserts the image link to Org buffer.  Images are either saved as
+attachments to heading (default) or to a globally defined directory.
+The save location is controlled by ~org-yank-image-save-type~.
+
 #+vindex: org-yank-image-file-name-function
-For images, Org attaches the image when pasting but this can be
-changed by customizing ~org-yank-image-save-type~ to save them under
-another directory instead.  The name given to these images are
-autogenerated by default but you can customize what name should be
-given to the pasted image by customizing
-~org-yank-image-file-name-function~.  This function takes no argument
-and should return the filename without extension to use as the image's
-filename.
-
-For files copied from a file manager, Org attaches them to the current
-heading using the =mv= or the =cp= method if the files were cut or
-copied in the file manager respectively.
+The yanked images are saved under automatically generated name.  You
+can customize ~org-yank-image-file-name-function~ to make Org query
+the image names or change the naming scheme.
+
+When yanking files copied from a file manager, Org attaches them to
+the current heading using the =mv= or the =cp= method if the files
+were cut or copied in the file manager respectively.
 
 * Hacking
 :PROPERTIES:
-- 
2.42.0