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

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

[Glenn Morris]

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.)


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.

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

[Eli Zaretskii]

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

bug#3888: marked as done (Some variables get the wrong, platform-specific, documentation)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 916 bytes --]


Your message dated Fri, 24 Jul 2009 19:35:35 +0300
with message-id <83k51y3up4.fsf@gnu.org>
and subject line Re: bug#3888: Some variables get the wrong, platform-specific,	documentation
has caused the Emacs bug report #3888,
regarding Some variables get the wrong, platform-specific, documentation
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
3888: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=3888
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 3208 bytes --]

From: Glenn Morris <rgm@gnu.org>
To: bug-gnu-emacs@gnu.org
Subject: Some variables get the wrong, platform-specific, documentation
Date: Mon, 20 Jul 2009 14:21:00 -0400
Message-ID: <qrr5wbxlkj.fsf@fencepost.gnu.org>


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.)


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.



[-- Attachment #3: Type: message/rfc822, Size: 3127 bytes --]

From: Eli Zaretskii <eliz@gnu.org>
To: 3888-done@emacsbugs.donarmstrong.com
Cc: cyd@stupidchicken.com
Subject: Re: bug#3888: Some variables get the wrong, platform-specific,	documentation
Date: Fri, 24 Jul 2009 19:35:35 +0300
Message-ID: <83k51y3up4.fsf@gnu.org>

> Date: Tue, 21 Jul 2009 21:59:52 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: 3888@emacsbugs.donarmstrong.com
> 
> > From: Chong Yidong <cyd@stupidchicken.com>
> > Cc: Glenn Morris <rgm@gnu.org>, 3888@emacsbugs.donarmstrong.com
> > Date: Mon, 20 Jul 2009 17:33:28 -0400
> > 
> > As a work-around, I changed the affected doc-strings so that the
> > different versions all say the same thing.  Eli, could you check if this
> > works OK on Windows?
> 
> It works on Windows, thanks.
> 
> However:
> 
>  . the doc string of x-select-enable-clipboard:
> 
>      (defcustom x-select-enable-clipboard t
>        "Non-nil means cutting and pasting uses the clipboard.
>     -This is in addition to the primary selection."
>     +This is in addition to, but in preference to, the primary selection."
> 
>    should IMO say that on Windows this is the default, and perhaps
>    also that primary selection is not accessible to other programs
>    there.
> 
>  . the doc string of x-colors:
> 
>      (defvar x-colors (mapcar 'car msdos-color-values)
>     -  "The list of colors available on a PC display under MS-DOS.")
>     +  "List of available colors for graphical frames.
>     +For X, the list comes from the `rgb.txt' file,v 10.41 94/02/20.
>     +For Nextstep, this is a list of non-PANTONE colors returned by
>     +the operating system.")
> 
>    incorrectly says that these are colors for graphical frames, which
>    the MS-DOS display isn't.
> 
>  . you didn't add doc strings to x-set-selection and x-get-selection
>    on w32-fns.el -- was that on purpose?

I fixed all these problems on the branch now.

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

[Glenn Morris]

Emacs bug Tracking System wrote:

> I fixed all these problems on the branch now.

Thanks; but since there is no automatic syncing from branch to trunk
(AFAIK), someone needs to remember to find a better a solution for the
trunk, or copy these doc fixes there. It might therefore be an idea to
leave this bug open.