master ae337884107: Revise documentation concerning selections outside X

[Po Lu]

branch: master
commit ae337884107c4d5f66aaceef0e8b548565317412
Author: Po Lu <luangruo@yahoo.com>
Commit: Po Lu <luangruo@yahoo.com>

    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.
---
 doc/lispref/frames.texi   | 91 +++++++++++++++++++++++++++++++++++------------
 doc/misc/efaq.texi        |  6 ++--
 doc/misc/use-package.texi |  2 +-
 3 files changed, 73 insertions(+), 26 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 75bc4de4f61..3589bc35f4f 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -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.
-
-  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
+  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 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}.
-
-  @code{gui-set-selection} also only accepts strings, encodes them
-in the selection coding system, and saves them to the clipboard.
-
-  On Nextstep, Emacs only supports saving strings to selections.
-However, requests for the following targets are accepted:
+@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.
+
+  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}.)
+
+@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
diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index 2fc8e60d400..d8097a8d21e 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -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
diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index 55e56f7ce4e..4046c3a62ce 100644
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -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