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

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

[Stefan Kangas]

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)?

For example:

    Its default value is @code{nil}.  On old versions of MS-Windows ...

And so on for the other paragraphs.

Maybe the MS-DOS stuff could be moved to a footnote, or to some separate
file where we document that port.

Thanks in advance.

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

[Po Lu]

Stefan Kangas <stefankangas@gmail.com> writes:

> 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)?

I thought MS-Windows systems were either 9X/Me or NT/2K/XP, as mentioned
in the doc string for selection-coding-system.  At any rate, I've no
objections to reorganizing the MS-Windows part of that paragraph, but
would rather the order of the paragraph as a whole remain intact, since
that variable's value is of less consequence under X than it is under
the other systems.

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

[Eli Zaretskii]

> 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.

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

[Po Lu]

Eli Zaretskii <eliz@gnu.org> writes:

> 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.

I wrote this description consulting the doc string of
selection-coding-system rather than the code in w32select.c.  Any
corrections are welcome, of course.

We do want the manual to enter into more detail on this subject, since
many packages are now trying to undertake selection transfer themselves,
being subsequently caught on snags occasioned by the absence of thorough
documentation.  Snags attached to thorny stems of bramble, as it were.