Re: master 9e9bc2af514: Correct documentation of selection-coding-system

[Eli Zaretskii <eliz@gnu.org>]

> From: Stefan Kangas <stefankangas@gmail.com>
> Date: Tue, 24 Oct 2023 01:45:20 -0700
> 
> Po Lu via Mailing list for Emacs changes <emacs-diffs@gnu.org> writes:
> 
> > diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
> > index 9f969603023..56e4fe419e3 100644
> > --- a/doc/lispref/frames.texi
> > +++ b/doc/lispref/frames.texi
> > @@ -4053,10 +4053,20 @@ under X, and @xref{Other Selections} for those elsewhere.
> >  @end defun
> >
> >  @defopt selection-coding-system
> > -This variable specifies the coding system to use when reading and
> > -writing selections or the clipboard.  @xref{Coding
> > -Systems}.  The default is @code{compound-text-with-extensions}, which
> > -converts to the text representation that X11 normally uses.
> > +This variable provides a coding system (@pxref{Coding Systems}) which
> > +is used to encode selection data, and takes effect on MS-DOS,
> > +MS-Windows and X@.
> > +
> > +Under MS-DOS and MS-Windows, it is the coding system by which all
> > +clipboard text will be encoded and decoded, whereas on X it merely
> > +supplies the EOL format of the selection text sent in response to a
> > +request for text encoded by a matching coding system; which is to say
> > +that if its value is @code{utf-8-dos}, it will influence requests for
> > +@code{UTF8_STRING} data, but not those for @code{STRING}.
> > +
> > +Its default value is the system code page under MS-Windows 95, 98 or
> > +Me, @code{utf-16le-dos} under NT/W2K/XP, @code{iso-latin-1-dos} on
> > +MS-DOS, and @code{nil} elsewhere.
> >  @end defopt
> 
> Could we please shift this around so that we mention free operating
> systems before non-free ones (i.e. X before MS-Windows) and current
> operating systems before obsolete ones (i.e. MS-Windows before XP and
> MS-DOS)?

AFAIK, the new description is also not very accurate in its MS-Windows
part (see w32select.c:w32-get-clipboard-data), to the degree that it
might mislead the reader into a completely wrong mental model of what
happens.  If we want a detailed description of this stuff, we should
describe what happens on Windows much more accurately.