Scripting API: `copySelection(...)` documentation unclear

[Chealer]

The scripting API provides a copySelection(...) function, which is presented as 3 different functions in the documentation, all specified as follows (except for variation in synopsis):

copySelection(text)

Equivalent to the copy function with the same arguments, but for Linux mouse selection.

Throws:
Error() – Thrown if selection fails to be set.

This is unclear, mostly because:

1. Most variants accept a single argument.
2. It is not really specific to Linux (BSD seems to be somewhat supported).
3. It is not specific to mouses.

The following clarifies:

diff --git a/docs/scripting-api.rst b/docs/scripting-api.rst
--- docs/scripting-api.rst
+++ docs/scripting-api.rst
@@ -295,9 +295,9 @@
    :rtype: bool
 
 .. js:function:: copy(text)
 
-   Sets clipboard plain text.
+   Sets the system clipboard to the specified string (of plain text).
 
    Same as ``copy(mimeText, text)``.
 
    :throws Error: Thrown if clipboard fails to be set.
@@ -362,24 +362,27 @@
        popup('Copied Text', text)
 
 .. js:function:: copySelection(text)
 
-   Equivalent to the ``copy`` function with the same arguments, but for `Linux
-   mouse selection`_.
+   On X11, equivalent to the ``copy`` function with the same argument, but modifying the ``PRIMARY`` selection atom rather than ``CLIPBOARD`` (see `Linux
+   mouse selection`_).
+   On other platforms, has no effect (no-op).
 
    :throws Error: Thrown if selection fails to be set.
 
 .. js:function:: /*data*/ copySelection(mimeType, data, [mimeType, data]...)
 
-   Equivalent to the ``copy`` function with the same arguments, but for `Linux
-   mouse selection`_.
+   On X11, equivalent to the ``copy`` function with the same arguments, but modifying the ``PRIMARY`` selection atom rather than ``CLIPBOARD`` (see `Linux
+   mouse selection`_).
+   On other platforms, has no effect (no-op).
 
    :throws Error: Thrown if selection fails to be set.
 
 .. js:function:: /*item*/ copySelection(Item)
 
-   Equivalent to the ``copy`` function with the same arguments, but for `Linux
-   mouse selection`_.
+   On X11, equivalent to the ``copy`` function with the same argument, but modifying the ``PRIMARY`` selection atom rather than ``CLIPBOARD`` (see `Linux
+   mouse selection`_).
+   On other platforms, has no effect (no-op).
 
    :throws Error: Thrown if selection fails to be set.
 
 .. js:function:: paste()

License

This report (including all messages and attachments I add to it) is offered under the terms of CC0 1.0.

[hluk]

Any chance you can create PR for this? I would prefer not to apply other user's patches myself.

[Chealer]

Greetings Lukas,

Any chance you can create PR for this?

If you mean a "merge request", I don't have a branch just for that.

I would prefer not to apply other user's patches myself.

To be clear, this is just an issue report. It is not a request for anyone in particular to solve.

Now, if you mean nobody but you can commit to this repository, I have very little experience managing GitHub repositories, but I don't think it sets such a limitation, even for free accounts. For instance, I gave access to ckanext-categroupy to a very anti-Microsoft colleague who was in charge of our government’s development forge (based on GitLab). I would be very surprised if he was paying for GitHub extras. I was doing that as an employee, but using my personal account, and I have never paid a cent to GitHub, yet it still let me add you to categroupy’s collaborators. It does not say a word about plan restrictions. So I would bet any GitHub account can share commit access with any other GitHub account. I just had to go to the Settings tab, in the Collaborators pane, and use the Manage access section.

[hluk]

@Chealer I'm not sure what you suggest with your previous comment.

What I meant is, it would be best if you can create a pull request, since you can already provide the diff. I would prefer not to apply the changes myself, because they are not really mine.

I think I could override Author of a commit, but that seems wrong. Maybe mentioning the real author in the commit message would work.

[hluk]

I asked Claude to apply the patch: #3459

[Chealer]

Thank you Lukas

What I meant is, it would be best if you can create a pull request, since you can already provide the diff.

Thanks, but if you're suggesting to do a "merge request", I can't really do that. I created the patch with github.dev, so I don't have any branch to merge (I would kind of need to start over to do that).

@Chealer I'm not sure what you suggest with your previous comment.

I would prefer not to apply the changes myself, because they are not really mine.

Sorry, I had misinterpreted your 2026-03-01 comment. I thought you basically meant it was inefficient to involve several people in a change, but I now realize you meant that for you to commit could be misleading.

I think I could override Author of a commit, but that seems wrong.

I agree I would not do that unless taking the patch verbatim.

Maybe mentioning the real author in the commit message would work.

From a legal perspective, the patch is in the public domain, so there is no issue.

From an ethical perspective, as with any commit, it is best to indicate contributors in the message, whether these are issue reporters or other contributors of significant analysis or code/artifacts. Some projects standardize pseuso-tags for purposes like that.

For my part, I have seen tens of projects and developers (whether amateurs or professionals) fail to properly credit contributors to commits, so any kind of credit is better than nothing😅