bug#3888: Some variables get the wrong, platform-specific, documentation

[Eli Zaretskii <eliz@gnu.org>]

> From: Glenn Morris <rgm@gnu.org>
> Date: Mon, 20 Jul 2009 14:21:00 -0400
> Cc: 
> 
> 
> In GNU Emacs 23.0.96.1 on GNU/Linux:
> 
> emacs -Q
> C-h v x-select-enable-clipboard
> 
>     x-select-enable-clipboard is a variable defined in `x-win.el'.
>     Its value is nil
> 
>     Documentation:
>     Non-nil means cutting and pasting uses the clipboard.
>     This is the default on this system, since MS-Windows does not
>     support other types of selections.
> 
> I guess this is because term/pc-win.elc is now in SOME_MACHINE_LISP in
> src/Makefile.in. (It was not there in Emacs 22.)

None of the *-win.elc files was in SOME_MACHINE_LISP in Emacs 22,
which is why documentation of several important functions and
variables were not in etc/DOC.  But there were other platform-specific
files in SOME_MACHINE_LISP: dos-fns.elc, w32-fns.elc, vmsproc.elc,
etc.  So the problem is not new.

> Similarly, from ns-win.el, we get the following in GNU/Linux under X:
> 
>     x-display-name:
>     The name of the Nextstep display on which Emacs was started.
> 
>     x-setup-function-keys:
>     Set up function Keys for Nextstep for frame FRAME.
> 
>     x-select-text:
>     Put TEXT, a string, on the pasteboard.
> 
>     x-colors:
>     The list of colors defined in non-PANTONE color files.
> 
>     xw-defined-colors:
>     Return a list of colors supported for a particular frame.
>     The argument FRAME specifies which frame to try.
>     The value may be different for frames on different Nextstep displays.

Similarly (but for slightly different reasons), in the Windows port:

    x-set-selection is a compiled Lisp function in `w32-fns.el'.

    (x-set-selection type data)

    Not documented.

and the same for x-get-selection and x-selection-owner, even though
there's a doc string for all of these in the X-specific files.

I think this calls for some infrastructure that is currently missing:
how to define a platform-specific implementation of an API without
clobbering the doc string for other platforms.  Maybe some markup in
the doc string that would allow to have platform-specific parts there?