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