Revise documentation concerning selections outside X

* doc/lispref/frames.texi (Accessing Selections, X Selections):
Correct markup, averting the recognition of X followed by a
sentence stop as an acronym.
(Other Selections): Relate the nature of the MS-Windows
selection emulation, how it functions, and its deficiencies.
Clarify paragraphs concerning PGTK and Nextstep.

* doc/misc/efaq.texi (Emacs in a Linux console):

* doc/misc/use-package.texi (Conditional loading): Correct
markup, averting the recognition of X followed by a sentence
stop as an acronym.
This commit is contained in:
Po Lu 2023-10-22 07:54:50 +00:00
parent b446294faa
commit ae33788410
3 changed files with 70 additions and 23 deletions

View file

@ -4104,7 +4104,7 @@ only used by Emacs to communicate with session managers, and is a
separate topic.
@menu
* X Selections:: Selection data types (and more) on X.
* X Selections:: Selection data types (and more) on X@.
* Other Selections:: How they work on other window systems.
@end menu
@ -4497,28 +4497,68 @@ bounds of the selection data in the buffer @var{buf}.
@node Other Selections
@subsection Other Selections
Window systems such as MS-Windows, Nextstep, Haiku and Android do
not provide selections corresponding to the X semantics. Each window
system provides its own ad-hoc emulation of selections, none of which
make use of the ``selection converter'' mechanism described above. In
addition, only the @code{PRIMARY}, @code{CLIPBOARD}, and
@code{SECONDARY} selections are typically supported, alongside the
@code{XdndSelection} used for drag-and-drop operations.
Selections under such window systems as MS-Windows, Nextstep, Haiku
and Android are not aligned with those under X@. Each of these window
system improvises its own selection mechanism without employing the
``selection converter'' mechanism illustrated in the preceeding node.
Only the @code{PRIMARY}, @code{CLIPBOARD}, and @code{SECONDARY}
selections are generally supported, with the @code{XdndSelection}
selection that records drag-and-drop data also available under
Nextstep and Haiku.
GTK itself exposes emulations of X selections to applications, but
those emulations are of varying completeness. While Emacs built with
PGTK will use the same selection interface as Emacs built with X, many
GTK itself seeks to emulate the X selection system, but its
emulations are not altogether dependable, with their overall quality
subject to the GDK backend being used. While Emacs built with PGTK
will supply the same selection interface as Emacs built with X, many
selection targets will not be useful.
On MS-Windows, @code{gui-get-selection} accepts a single target,
@code{STRING}. The value returned is the selection data decoded
using @code{selection-coding-system}.
@cindex MS-Windows selection emulation
@cindex MS-Windows primary and secondary selection
Although a clipboard exists, there is no concept of primary or
secondary selections within the MS-Windows operating system. On this
system, Emacs simulates the presence of a primary and secondary
selection, while saving to and retrieving from the clipboard when so
requested.
@code{gui-set-selection} also only accepts strings, encodes them
in the selection coding system, and saves them to the clipboard.
The simulation of the primary and secondary selections is conducted
by saving values supplied to @code{gui-set-selection} within the
@code{x-selections} property of the symbol designating the pertinent
selection, namely the @var{type} argument to @code{gui-get-selection}.
Each subsequent call to @code{gui-get-selection} in turn returns its
value, which is not subject to further examination (such as type
checks and the like). Under such circumstances, @var{data-type}
argument is generally disregarded. (But see below for the
qualification concerning @code{TARGETS}.)
On Nextstep, Emacs only supports saving strings to selections.
However, requests for the following targets are accepted:
@cindex MS-Windows clipboard
Where the clipboard selection is concerned (whenever @var{type} is
@code{CLIPBOARD}), @code{gui-set-selection} verifies that the value
provided is a string and saves it within the system clipboard once it
is encoded by the coding system configured in
@var{selection-coding-system}. Callers of @code{gui-get-selection}
are required to set @var{data-type} to either @code{STRING} or
@code{TARGETS}.
When @var{data-type} is set to @code{TARGETS} in a call to
@code{gui-get-selection}, a vector of symbols is returned when
selection data exists, much as it is under X@. It is impossible to
request clipboard data in any format besides @code{STRING}, for the
prerequisite data conversion routines are absent. Just as strings
saved into the clipboard are encoded by the
@code{selection-coding-system}, so those read from the clipboard are
decoded by that same coding system; this variable and its cousin
@code{next-selection-coding-system} merit particular scrutiny when
difficulties are encountered with saving selection text into the
clipboard.
@cindex Nextstep selections
All three selections standard in X exist in Nextstep as well, but
Emacs is only capable of saving strings to such selections.
Restrictions imposed upon calls to @code{gui-set-selection} there are
much the same as those on MS-Windows, though text is uniformly encoded
as @code{utf-8-unix} without regard to the value of
@code{selection-coding-system}. @code{gui-get-selection} is more
charitable, and accepts requests for the following selection targets:
@c FIXME: how is the text coding system determined, and do image/* or
@c application/* return image data or file names?
@ -4534,7 +4574,14 @@ However, requests for the following targets are accepted:
@item image/tiff
@end itemize
On Haiku, Emacs supports the same selection values as on X. In
The @code{XdndSelection} selection is also present under Nextstep,
in the form of a repository that records values supplied to
@code{gui-set-selection}. Its sole purpose is to save such values for
the benefit of the fundamental drag-and-drop function
@code{x-begin-drag} (@pxref{Drag and Drop}); no guarantees exist
concerning its value when read by anything else.
On Haiku, Emacs supports the same selection values as on X@. In
addition, Emacs fully implements the primary and secondary selections.
However, instead of taking ownership over the selection data, Emacs
transfers the selection data to the window server when

View file

@ -3156,9 +3156,9 @@ Registry), like this:
If possible, we recommend running Emacs inside @command{fbterm}, when
in a Linux console. This brings the Linux console on par with most
terminal emulators under X. To do this, install @command{fbterm}, for
example with the package manager of your GNU/Linux distribution, and
execute the command
terminal emulators under X@. To do this, install @command{fbterm},
for example with the package manager of your GNU/Linux distribution,
and execute the command
@example
$ fbterm

View file

@ -451,7 +451,7 @@ docstring of @code{system-type} for other valid values.
@item
Window system
The example below loads a package only on macOS and X. See the
The example below loads a package only on macOS and X@. See the
docstring of @code{window-system} for valid values.
@lisp