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

Previous Next

Full log

View this message in rfc822 format

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

Previous Next

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