Re: [BUG] [PATCH] Add yank-media and DND handler [9.6.7 (9.6.7-g6eb773 @ /home/viz/lib/emacs/straight/build/org/)]

[Ihor Radchenko]

Visuwesh <visuweshm@gmail.com> writes:

>> Is there any particular reason why you insert a newline after the image
>> link?
>
> I think this can stay here until Po Lu writes the platform-agnostic code
> that you requested further down this thread?

Sure.

>> Also, we might want to add a subsection describing the new customization to
>> 17 Miscellaneous section of the manual. Otherwise, users might have
>> difficulties discovering relevant settings to customize dnd and yank
>> behavior.
>
> I have now added these to the manual with a few relevant concept
> indices.  Please check if they are understandable as I am terrible at
> writing documentation.  Thanks.

Thanks!
Upon reading the manual sections I have further comments on the code:

1. org-yank-image-save-type feels a bit inconsistent. What about
   org-yank-image-save-method? "Type" sounds more like extension (png,
   jpeg, etc)

2. org-dnd-method allows either attaching files/images or putting them
   into a dedicated directory. Same for yanked images. But it is not the
   case for yanked files - they are always attached, which is not
   consistent. May we also allow dedicated directory for yanked files?
   Or maybe simply merge the org-dnd-method customization for yank and
   dnd together.

I am attaching my further amendments on top of your patch.
For simpler review, I am also adding the manual section verbatim.

To other readers of this thread: Please help reviewing the manual
section - it should be as clear as possible for everyone.

------------------
** Drag and Drop & ~yank-media~
:PROPERTIES:
:DESCRIPTION: Dropping and pasting files and images
:END:

#+cindex: dropping files
#+cindex: dragging files
#+cindex: drag and drop
#+cindex: dnd
#+vindex: org-dnd-method
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 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
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
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.
-----------

>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


-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>