docs: clarify copySelection() and Linux mouse selection documentation

[hluk]

Rewrite copySelection() overload descriptions to be brief and refer to
the Linux Mouse Selection section for details. Use the term "primary
selection" instead of X11-specific terminology (PRIMARY/CLIPBOARD atoms).

Rewrite the Linux Mouse Selection section to:

• Acknowledge BSD in addition to Linux.
• Note that the feature works on both X11 and Wayland.
• Document that Wayland support and GNOME as a notable exception.
• Mention the CopyQ Clipboard Monitor GNOME extension workaround in
  CopyQ 14.0.0+.
• Link to the Wayland protocol specification.

Regenerate src/gui/commandcompleterdocumentation.h via
utils/script_docs_to_cpp.py.

Based-on-patch-by: Chealer https://github.com/Chealer
Resolves: #3437
Assisted-by: Claude (Anthropic)

[hluk]

@Chealer Can you help me rephrase this?

The first sentence of description for each function in the API docs is used as hint in CopyQ GUI in the completion menu when writing commands/scripts. Ideally, if it is as brief as possible.

I also do not mention the term PRIMARY or atom anywhere else. I feel like users would find these terms confusing.

Apart from X11, this can apply to Wayland, if compositors support the selection.

Suggested change

	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).
	Equivalent to the ``copy`` function with the same argument, but modifying the `Linux mouse selection`_.
	This is supported only on X11 and some Wayland compositors. On other platforms, this has no effect.

[Chealer]

@Chealer Can you help me rephrase this?

The first sentence of description for each function in the API docs is used as hint in CopyQ GUI in the completion menu when writing commands/scripts. Ideally, if it is as brief as possible.

I agree that it is not so brief, but since this function is platform-dependent, there is necessarily added complexity. Moreover, even on X11, PRIMARY is a pretty complicated topic (not so standardized). Given that in CopyQ’s context, something complicated gets even more complex, I find my proposal reasonable, but it could indeed be shorter.

I also do not mention the term PRIMARY or atom anywhere else. I feel like users would find these terms confusing.

Right, it would be much better to have a link on “the PRIMARY selection atom”.

Apart from X11, this can apply to Wayland, if compositors support the selection.

Sorry, I never used Wayland but I realize that seems to be an important omission. Thank you

Suggested change
[…]

I consider the term ”Linux mouse selection” unclear, but most importantly misleading, because:

1. It is not really specific to Linux (BSD kernels seem to be somewhat supported).
2. It is not specific to mouses.

It is not simple to document this topic succinctly, clearly and correctly, but I would suggest:

1. Making the section clearer and accurate, with something like:

   X11/Wayland Mouse Pointer Selection
   ---------------------
   
   OSs based on Linux and BSD generally offer to paste via another mean than the normal clipboard. In addition to the selection atom used for explicit copy-pastes (``CLIPBOARD``), X11 features `the ``PRIMARY`` atom
   <https://www.freedesktop.org/wiki/Specifications/ClipboardsWiki/>`. In many applications, after content is selected using the (mouse) pointer, it is generally possible to paste it with a middle-click. Several Wayland compositors (including KWin) feature `X primary selection emulation
   <https://wayland.app/protocols/primary-selection-unstable-v1>`.
   
   CopyQ offers several functions dedicated to the ``PRIMARY`` atom. On OSs without that atom (including macOS and Microsoft Windows), pointer selection functions will do nothing
   (for example :js:func:`copySelection`) or return ``undefined`` (in case of
   :js:func:`selection`).
   

2. Relegating precisions to that section as much as possible. For example:

   Equivalent to the ``copy`` function with the same argument, but modifying the ``PRIMARY`` selection atom (rather than ``CLIPBOARD``).
   
   For explanations and supported platforms, see `X11/Wayland Mouse Pointer Selection`.
   On unsupported platforms, calls have no effect.
   

[hluk]

Honestly I don't like the description. What even is "atom"? Why does API user need to understand it? I do not understand why the original is so confusing.

I will probably just add details and the links to the "Linux mouse selection".

[hluk]

I asked Claude to make the updates based on the discussion and details I provided.

[Chealer]

Greetings Lukas,

Honestly I don't like the description. What even is "atom"?

It's a concept of X version 11 for communication between clients. The ICCCM defines it, but pretty technically: https://tronche.com/gui/x/icccm/sec-1.html#s-1.2.1
We could also give a short description.

Why does API user need to understand it?

I don't think API users in general need to understand it. Those who are interested in pointer selection do need to understand the distinction between PRIMARY and CLIPBOARD though… and those are atoms, as unknown as the concept may be.

I do not understand why the original is so confusing.

Well, to put it simply “GNU/Linux” itself is very complicated. It's developed in bazaar style (despite a few cathedrals inside that mess). There was 386BSD, which became FreeBSD and NetBSD, which itself split into OpenBSD. And then came DragonFlyBSD. But that was not enough to prevent Linux’s appearance. So nowadays, there are over 5 current kernels on which you can run X.

Meanwhile, XFree86 forked into X.org, but then another protocol appeared, Wayland. Which itself now has several "servers" (compositors). And Wayland does not mandate PRIMARY emulation.

Everything about GNU/* is complicated. It's super hard to write software which supports it well, and perhaps even harder to correctly document all the limitations/exceptions. And CopyQ supports even more than GNU/*, making documentation even more challenging.

Even just on KDE, Linux and X11, the concept is quite complicated. I used that for over 15 years, yet I don't think I truly understood how that worked until I discovered CopyQ.

The current documentation uses the term “Linux mouse selection”, which seems to be original, without a good definition. I doubt even 2% of people are aware of what that is, and even fewer would understand that term without context. If readers use a search engine to try understanding that, they will almost certainly end up on an unrelated document, or back on CopyQ’s documentation.

What it describes has nothing to do with Linux, except for the fact the Linux supports X. You could run OpenBSD on a laptop without a mouse, yet still want to use “Linux mouse selection”. Which does not only work with text. Conversely, you could run Linux on a desktop with a mouse, yet be unable to unable to use “Linux mouse selection” with text, because your Wayland compositor does not emulate PRIMARY.

It's possible that in a couple decades, a single kernel and a single “X server” will have triumphed, making this a lot less complicated to document… but I have been following GNU/* for decades, and so far, "the project" keeps diverging. Until then, cross-platform projects have to deal with that complexity and complication. Ideally, there would at least be a page documenting the topic, but with all that divergence, the Wayland page does not really explain the X concept, and the freedesktop.org page is pretty much abandoned.😔

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.30%. Comparing base (a47462a) to head (f61226b).

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3459      +/-   ##
==========================================
+ Coverage   80.18%   80.30%   +0.12%     
==========================================
  Files         243      243              
  Lines       30564    30564              
==========================================
+ Hits        24507    24545      +38     
+ Misses       6057     6019      -38     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.