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

[Eli Zaretskii]

> Date: Sun, 9 Feb 2014 19:09:33 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> 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?