From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: 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 Message-ID: <83zjlyubjn.fsf@gnu.org> References: <87r47e2nkm.fsf@building.gnus.org> <87a9dzy9hk.fsf@building.gnus.org> <601544f2-1018-4a52-9aca-6b0d815ab7d9@default> <87y51jwuco.fsf@building.gnus.org> <63fb8060-d4e0-4a2b-a506-6c758acee56d@default> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1392053050 15526 80.91.229.3 (10 Feb 2014 17:24:10 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 10 Feb 2014 17:24:10 +0000 (UTC) Cc: larsi@gnus.org, 15109@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Feb 10 18:24:16 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1WCuad-0007SN-80 for geb-bug-gnu-emacs@m.gmane.org; Mon, 10 Feb 2014 18:24:15 +0100 Original-Received: from localhost ([::1]:56931 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WCuac-0002Xi-R7 for geb-bug-gnu-emacs@m.gmane.org; Mon, 10 Feb 2014 12:24:14 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:32878) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WCuaV-0002RC-7C for bug-gnu-emacs@gnu.org; Mon, 10 Feb 2014 12:24:12 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WCuaQ-0001Fa-By for bug-gnu-emacs@gnu.org; Mon, 10 Feb 2014 12:24:07 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:33690) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WCuaQ-0001FW-85 for bug-gnu-emacs@gnu.org; Mon, 10 Feb 2014 12:24:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1WCuaP-00036w-Pi for bug-gnu-emacs@gnu.org; Mon, 10 Feb 2014 12:24:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 10 Feb 2014 17:24:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15109 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 15109-submit@debbugs.gnu.org id=B15109.139205303011941 (code B ref 15109); Mon, 10 Feb 2014 17:24:01 +0000 Original-Received: (at 15109) by debbugs.gnu.org; 10 Feb 2014 17:23:50 +0000 Original-Received: from localhost ([127.0.0.1]:41585 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCuaD-00036X-AK for submit@debbugs.gnu.org; Mon, 10 Feb 2014 12:23:49 -0500 Original-Received: from mtaout21.012.net.il ([80.179.55.169]:43322) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WCuaA-00036D-Ae for 15109@debbugs.gnu.org; Mon, 10 Feb 2014 12:23:47 -0500 Original-Received: from conversion-daemon.a-mtaout21.012.net.il by a-mtaout21.012.net.il (HyperSendmail v2007.08) id <0N0S00200IJUUO00@a-mtaout21.012.net.il> for 15109@debbugs.gnu.org; Mon, 10 Feb 2014 19:23:39 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout21.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0N0S002ZHIZETH50@a-mtaout21.012.net.il>; Mon, 10 Feb 2014 19:23:39 +0200 (IST) In-reply-to: <63fb8060-d4e0-4a2b-a506-6c758acee56d@default> X-012-Sender: halo1@inter.net.il X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:85281 Archived-At: > Date: Sun, 9 Feb 2014 19:09:33 -0800 (PST) > From: Drew Adams > Cc: 15109@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?