GNU bug report logs - #15109
24.3.50; doc of `x-get-selection, `selection-converter-alist', `xselect-convert-to-*'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 15109 in the body.
You can then email your comments to 15109 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.3.50; doc of `x-get-selection, `selection-converter-alist',
 `xselect-convert-to-*'
Date: Thu, 15 Aug 2013 23:49:11 -0700 (PDT)

1. `x-get-selection': Doc string refers you to
`selection-converter-alist', without which you cannot understand
parameter DATA-TYPE.

2. `selection-converter-alist': There is NO doc string.  Please add one
and please make sure it describes (or links to the doc for) the various
`xselect-convert-to-*' functions that one sees in the value of
`selection-converter-alist'.

3. `xselect-convert-to-*' functions, such as
`xselect-convert-to-filename': There is NO doc string.  Please add one
for each such function.


In GNU Emacs 24.3.50.1 (i686-pc-mingw32)
 of 2013-08-07 on ODIEONE
Bzr revision: 113750 lekktu <at> gmail.com-20130808011911-0jzpc9xuncegg6x9
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --prefix=/c/Devel/emacs/binary --enable-checking=yes,glyphs
 CFLAGS=-O0 -g3 LDFLAGS=-Lc:/Devel/emacs/lib
 CPPFLAGS=-Ic:/Devel/emacs/include'

Message #8 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15109 <at> debbugs.gnu.org
Subject: Re: bug#15109: 24.3.50;
 doc of `x-get-selection, `selection-converter-alist',
 `xselect-convert-to-*'
Date: Fri, 07 Feb 2014 21:14:17 -0800

Drew Adams <drew.adams <at> oracle.com> writes:

> 1. `x-get-selection': Doc string refers you to
> `selection-converter-alist', without which you cannot understand
> parameter DATA-TYPE.
>
> 2. `selection-converter-alist': There is NO doc string.  Please add one
> and please make sure it describes (or links to the doc for) the various
> `xselect-convert-to-*' functions that one sees in the value of
> `selection-converter-alist'.

This has a huge doc string now, so this seems to be fixed.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #13 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15109 <at> debbugs.gnu.org
Subject: RE: bug#15109: 24.3.50; doc of `x-get-selection,
 `selection-converter-alist', `xselect-convert-to-*'
Date: Sun, 9 Feb 2014 16:27:47 -0800 (PST)

[Message part 1 (text/plain, inline)]

> > 1. `x-get-selection': Doc string refers you to
> > `selection-converter-alist', without which you cannot understand
> > parameter DATA-TYPE.
> >
> > 2. `selection-converter-alist': There is NO doc string.  Please
> > add one and please make sure it describes (or links to the doc
> > for) the various `xselect-convert-to-*' functions that one sees
> > in the value of `selection-converter-alist'.
> 
> This has a huge doc string now, so this seems to be fixed.

By "this" you apparently mean `x-get-selection'.  So yes, part
1 of this bug has been fixed.  But part 2 has not been fixed.
`selection-converter-alist' certainly does not have "a huge doc
string now".  Reopening.

Attached is the current select.el from
http://bzr.savannah.gnu.org/lh/emacs/trunk/annotate/head:/lisp/select.el

There IS NO DOC STRING for `selection-converter-alist'.

And in my build from 2014-02-07, this is what C-h v says:

,----
| selection-converter-alist's value is shown below.
| 
| Documentation:
| Not documented as a variable.
| 
| Value: ((TEXT . xselect-convert-to-string)
|  (COMPOUND_TEXT . xselect-convert-to-string)
|  (STRING . xselect-convert-to-string)
|  (UTF8_STRING . xselect-convert-to-string)
|  (TARGETS . xselect-convert-to-targets)
|  (LENGTH . xselect-convert-to-length)
|  (DELETE . xselect-convert-to-delete)
|  (FILE_NAME . xselect-convert-to-filename)
|  (CHARACTER_POSITION . xselect-convert-to-charpos)
|  (LINE_NUMBER . xselect-convert-to-lineno)
|  (COLUMN_NUMBER . xselect-convert-to-colno)
|  (OWNER_OS . xselect-convert-to-os)
|  (HOST_NAME . xselect-convert-to-host)
|  (USER . xselect-convert-to-user)
|  (CLASS . xselect-convert-to-class)
|  (NAME . xselect-convert-to-name)
|  (ATOM . xselect-convert-to-atom)
|  (INTEGER . xselect-convert-to-integer)
|  (SAVE_TARGETS . xselect-convert-to-save-targets)
|  (_EMACS_INTERNAL . xselect-convert-to-identity))
`----

[select.el (application/octet-stream, attachment)]

Message #18 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15109 <at> debbugs.gnu.org
Subject: Re: bug#15109: 24.3.50;
 doc of `x-get-selection, `selection-converter-alist',
 `xselect-convert-to-*'
Date: Sun, 09 Feb 2014 18:41:59 -0800

Drew Adams <drew.adams <at> oracle.com> writes:

> By "this" you apparently mean `x-get-selection'.  So yes, part
> 1 of this bug has been fixed.  But part 2 has not been fixed.
> `selection-converter-alist' certainly does not have "a huge doc
> string now".  Reopening.

It certainly has a huge doc string on the trunk; see below.

Windows issue?

selection-converter-alist is a variable defined in `xselect.c'.
Its value is shown below.

Documentation:
An alist associating X Windows selection-types with functions.
These functions are called to convert the selection, with three args:
the name of the selection (typically `PRIMARY', `SECONDARY', or `CLIPBOARD');
a desired type to which the selection should be converted;
and the local selection value (whatever was given to `x-own-selection').

The function should return the value to send to the X server
(typically a string).  A return value of nil
means that the conversion could not be done.
A return value which is the symbol `NULL'
means that a side-effect was executed,
and there is no meaningful selection value.

Value: ((TEXT . xselect-convert-to-string)
 (COMPOUND_TEXT . xselect-convert-to-string)
 (STRING . xselect-convert-to-string)
 (UTF8_STRING . xselect-convert-to-string)
 (TARGETS . xselect-convert-to-targets)
 (LENGTH . xselect-convert-to-length)
 (DELETE . xselect-convert-to-delete)
 (FILE_NAME . xselect-convert-to-filename)
 (CHARACTER_POSITION . xselect-convert-to-charpos)
 (LINE_NUMBER . xselect-convert-to-lineno)
 (COLUMN_NUMBER . xselect-convert-to-colno)
 (OWNER_OS . xselect-convert-to-os)
 (HOST_NAME . xselect-convert-to-host)
 (USER . xselect-convert-to-user)
 (CLASS . xselect-convert-to-class)
 (NAME . xselect-convert-to-name)
 (ATOM . xselect-convert-to-atom)
 (INTEGER . xselect-convert-to-integer)
 (SAVE_TARGETS . xselect-convert-to-save-targets)
 (_EMACS_INTERNAL . xselect-convert-to-identity))

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #21 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15109 <at> debbugs.gnu.org
Subject: RE: bug#15109: 24.3.50; doc of `x-get-selection,
 `selection-converter-alist', `xselect-convert-to-*'
Date: Sun, 9 Feb 2014 18:47:39 -0800 (PST)

> > By "this" you apparently mean `x-get-selection'.  So yes, part
> > 1 of this bug has been fixed.  But part 2 has not been fixed.
> > `selection-converter-alist' certainly does not have "a huge doc
> > string now".  Reopening.
> 
> It certainly has a huge doc string on the trunk; see below.
> 
> Windows issue?
> 
> selection-converter-alist is a variable defined in `xselect.c'.
> Its value is shown below.
> 
> Documentation:
> An alist associating X Windows selection-types with functions.
> These functions are called to convert the selection, with three
> args:
> the name of the selection (typically `PRIMARY', `SECONDARY', or
> `CLIPBOARD');
> a desired type to which the selection should be converted;
> and the local selection value (whatever was given to `x-own-
> selection').
> 
> The function should return the value to send to the X server
> (typically a string).  A return value of nil
> means that the conversion could not be done.
> A return value which is the symbol `NULL'
> means that a side-effect was executed,
> and there is no meaningful selection value.
> 
> Value: ((TEXT . xselect-convert-to-string)
>  (COMPOUND_TEXT . xselect-convert-to-string)
>  (STRING . xselect-convert-to-string)
>  (UTF8_STRING . xselect-convert-to-string)
>  (TARGETS . xselect-convert-to-targets)
>  (LENGTH . xselect-convert-to-length)
>  (DELETE . xselect-convert-to-delete)
>  (FILE_NAME . xselect-convert-to-filename)
>  (CHARACTER_POSITION . xselect-convert-to-charpos)
>  (LINE_NUMBER . xselect-convert-to-lineno)
>  (COLUMN_NUMBER . xselect-convert-to-colno)
>  (OWNER_OS . xselect-convert-to-os)
>  (HOST_NAME . xselect-convert-to-host)
>  (USER . xselect-convert-to-user)
>  (CLASS . xselect-convert-to-class)
>  (NAME . xselect-convert-to-name)
>  (ATOM . xselect-convert-to-atom)
>  (INTEGER . xselect-convert-to-integer)
>  (SAVE_TARGETS . xselect-convert-to-save-targets)
>  (_EMACS_INTERNAL . xselect-convert-to-identity))

Message #24 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15109 <at> debbugs.gnu.org
Subject: RE: bug#15109: 24.3.50; doc of `x-get-selection,
 `selection-converter-alist', `xselect-convert-to-*'
Date: Sun, 9 Feb 2014 18:49:46 -0800 (PST)

> It certainly has a huge doc string on the trunk; see below.
> 
> Windows issue?
> 
> selection-converter-alist is a variable defined in `xselect.c'.

I see.  I did not try to download the latest C sources; sorry.
I see from what you've shown that I was wrong.

I do not see anything for `C-h v' in a build from 2 days ago,
but it is possible that it was added since then.

Or maybe, as you suggest, it is a MS Windows problem.

Message #27 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 15109 <at> debbugs.gnu.org
Subject: Re: bug#15109: 24.3.50;
 doc of `x-get-selection, `selection-converter-alist',
 `xselect-convert-to-*'
Date: Sun, 09 Feb 2014 18:54:15 -0800

Drew Adams <drew.adams <at> oracle.com> writes:

> I do not see anything for `C-h v' in a build from 2 days ago,
> but it is possible that it was added since then.

bzr seems to say that it's been there since at least 2001...

> Or maybe, as you suggest, it is a MS Windows problem.

It's pretty odd.  Could it have something to do with these variables
being X-related and...  somehow... stripped of their doc strings under
Windows?

I think that sounds wildly unlikely, but I'm just guessing here.  >"?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

Message #30 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 15109 <at> debbugs.gnu.org
Subject: RE: bug#15109: 24.3.50; doc of `x-get-selection,
 `selection-converter-alist', `xselect-convert-to-*'
Date: Sun, 9 Feb 2014 19:09:33 -0800 (PST)

> > I do not see anything for `C-h v' in a build from 2 days ago,
> > but it is possible that it was added since then.
> 
> bzr seems to say that it's been there since at least 2001...

I see.  Then maybe it is a Windows problem somehow.  Perhaps
Eli can help.  He can hopefully confirm that C-h v shows no doc.

> > Or maybe, as you suggest, it is a MS Windows problem.
> 
> It's pretty odd.  Could it have something to do with these variables
> being X-related and...  somehow... stripped of their doc strings
> under Windows?
> 
> I think that sounds wildly unlikely, but I'm just guessing here.

We'll get there eventually.  When this is all said and done,
what about adding a comment in select.el next to the setq that
initializes the variable, saying that the doc string is defined
in select.c?  And maybe saying _why_ it is done there and not
in Lisp?  I would think that such a dependence would be pointed
out somewhere.  A comment there seems appropriate.

Message #33 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, 15109 <at> debbugs.gnu.org
Subject: Re: bug#15109: 24.3.50; doc of `x-get-selection,
 `selection-converter-alist',	`xselect-convert-to-*'
Date: Mon, 10 Feb 2014 19:23:24 +0200

> Date: Sun, 9 Feb 2014 19:09:33 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: 15109 <at> debbugs.gnu.org
> 
> > > I do not see anything for `C-h v' in a build from 2 days ago,
> > > but it is possible that it was added since then.
> > 
> > bzr seems to say that it's been there since at least 2001...
> 
> I see.  Then maybe it is a Windows problem somehow.  Perhaps
> Eli can help.  He can hopefully confirm that C-h v shows no doc.

You don't need Eli to realize that any symbol that starts with "x-"
smells X Window system, and is thus prone to the platform-specific
documentation problems, see below.

> > > Or maybe, as you suggest, it is a MS Windows problem.
> > 
> > It's pretty odd.  Could it have something to do with these variables
> > being X-related and...  somehow... stripped of their doc strings
> > under Windows?
> > 
> > I think that sounds wildly unlikely, but I'm just guessing here.

Good guess, actually.  Look at Snarf-documentation, and you will see
that it skips any symbols that are defined by files which are not in
the build-files list for the current binary.  And xselect.c is,
obviously, not compiled into a Windows build of Emacs.  So this:

  (get 'selection-converter-alist 'variable-documentation)

returns nil, and you get "Not documented as a variable."

There's some history to this issue.  For a short introduction, see
bug#3888.  We ended up having several identical copies of doc strings
for symbols that are implemented separately and differently on
different platforms.  

Personally, I think that the code in Snarf-documentation that skips
"foreign" C source files can be removed; if the order of scanning the
C files is important (e.g., so that Unix users won't see some variable
defined on a w32-something.el file, and be surprised), we can always
add some Makefile wizardry to have the platform specific files last in
the list submitted to make-docfile.  But until this is done, we will
have "incidents" such as this one from time to time.

> We'll get there eventually.  When this is all said and done,
> what about adding a comment in select.el next to the setq that
> initializes the variable, saying that the doc string is defined
> in select.c?  And maybe saying _why_ it is done there and not
> in Lisp?  I would think that such a dependence would be pointed
> out somewhere.  A comment there seems appropriate.

We could add a dummy definition of selection-converter-alist on some
w32-specific file, and copy there the doc string from xselect.c.
However, I see no reason to have selection-converter-alist documented
on Windows, since the functionality it encompasses is not available
there, and the DATA-TYPE argument to x-get-selection is completely
ignored on MS-Windows.

So what I did instead (in trunk revision 116402) is mention in the doc
string of x-get-selection that DATA-TYPE is not used on MS-Windows.  I
think this is good enough for now, until a more flexible and
sophisticated mechanism is introduced to deal with these situations:
once told that an argument is ignored, there's no need for the user to
dig deeper in what it can or cannot be.

OK?

Message #36 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, 15109 <at> debbugs.gnu.org
Subject: RE: bug#15109: 24.3.50;	doc of `x-get-selection,
 `selection-converter-alist',	`xselect-convert-to-*'
Date: Mon, 10 Feb 2014 13:36:12 -0800 (PST)

> I see no reason to have selection-converter-alist documented
> on Windows, since the functionality it encompasses is not available
> there, and the DATA-TYPE argument to x-get-selection is completely
> ignored on MS-Windows.

In that case, why define `selection-converter-alist' at all on
Windows?  And why not rename it to `x-selection-converter-alist',
if it is X-specific?

On the other hand, although `x-get-selection' has that prefix,
it _is_ defined and used on Windows.  Likewise, `x-set-selection'.
Code that makes use of the secondary selection will make use of
such functions, for instance.

So maybe they should lose their `x-' prefix (or suitable unprefixed
synonyms or wrapper functions be provided).

IOW, things do not seem so cut-and-dried as you describe them.
In the past we have renamed `x-defined-colors' to `defined-colors' etc.
Sounds like maybe some more such cleanup is in order.

Message #41 received at 15109-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: larsi <at> gnus.org, drew.adams <at> oracle.com, 15109-done <at> debbugs.gnu.org
Subject: Re: bug#15109: 24.3.50; doc of `x-get-selection,
 `selection-converter-alist',	`xselect-convert-to-*'
Date: Tue, 11 Feb 2014 05:36:03 +0200

> Date: Mon, 10 Feb 2014 13:36:12 -0800 (PST)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: larsi <at> gnus.org, 15109 <at> debbugs.gnu.org
> 
> > I see no reason to have selection-converter-alist documented
> > on Windows, since the functionality it encompasses is not available
> > there, and the DATA-TYPE argument to x-get-selection is completely
> > ignored on MS-Windows.
> 
> In that case, why define `selection-converter-alist' at all on
> Windows?  And why not rename it to `x-selection-converter-alist',
> if it is X-specific?

I explained why: because we must have identical doc strings for these
on all platforms, due to limitations of how the DOC file is built and
used.

> On the other hand, although `x-get-selection' has that prefix,
> it _is_ defined and used on Windows.  Likewise, `x-set-selection'.
> Code that makes use of the secondary selection will make use of
> such functions, for instance.
> 
> So maybe they should lose their `x-' prefix (or suitable unprefixed
> synonyms or wrapper functions be provided).
> 
> IOW, things do not seem so cut-and-dried as you describe them.
> In the past we have renamed `x-defined-colors' to `defined-colors' etc.
> Sounds like maybe some more such cleanup is in order.

Could be.  But that's a different issue.  This one is done.

Message #44 received at 15109 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, larsi <at> gnus.org, 15109 <at> debbugs.gnu.org
Subject: Re: bug#15109: 24.3.50; doc of `x-get-selection,
 `selection-converter-alist',	`xselect-convert-to-*'
Date: Mon, 10 Feb 2014 22:50:57 -0500

> On the other hand, although `x-get-selection' has that prefix,
> it _is_ defined and used on Windows.  Likewise, `x-set-selection'.
> Code that makes use of the secondary selection will make use of
> such functions, for instance.
> So maybe they should lose their `x-' prefix (or suitable unprefixed
> synonyms or wrapper functions be provided).

Indeed.


        Stefan

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.