GNU bug report logs - #3888
Some variables get the wrong, platform-specific, documentation

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 3888 in the body.
You can then email your comments to 3888 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #3 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

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

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.

Message #8 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>, 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific,	documentation
Date: Mon, 20 Jul 2009 21:56:38 +0300

> From: Glenn Morris <rgm <at> 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?

Message #13 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Glenn Morris <rgm <at> gnu.org>, 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific,	documentation
Date: Mon, 20 Jul 2009 16:25:38 -0400

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

I think, as a temporary solution, we should make the docstrings of all
the affected functions and variables the same.  If necessary, they can
say somehthing like, "On Windows, this does X.  On Nexstep, this does
Y", and so on.

Message #18 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Glenn Morris <rgm <at> gnu.org>, 3888 <at> debbugs.gnu.org
Subject: Re: Re: bug#3888: Some variables get the wrong, platform-specific, documentation
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?

Right now, this change is only on the branch.  I'll check this into the
trunk, at a later date, only if we can't come up with a better solution.

Message #23 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Chong Yidong <cyd <at> stupidchicken.com>
Cc: rgm <at> gnu.org, 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific,	documentation
Date: Tue, 21 Jul 2009 06:12:13 +0300

> From: Chong Yidong <cyd <at> stupidchicken.com>
> Cc: Glenn Morris <rgm <at> gnu.org>, 3888 <at> emacsbugs.donarmstrong.com
> Date: Mon, 20 Jul 2009 16:25:38 -0400
> 
> I think, as a temporary solution, we should make the docstrings of all
> the affected functions and variables the same.

This would also need a change in make-docfile, to warn about
duplicate, but different doc strings for the same symbol.  Otherwise,
the doc strings will diverge again after a while.

Message #28 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Chong Yidong <cyd <at> stupidchicken.com>
Cc: 3888 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>
Subject: Re: bug#3888: Some variables get the wrong, platform-specific, documentation
Date: Tue, 21 Jul 2009 12:18:27 -0400

> I think, as a temporary solution, we should make the docstrings of all
> the affected functions and variables the same.  If necessary, they can
> say somehthing like, "On Windows, this does X.  On Nexstep, this does
> Y", and so on.

That sounds OK as a quick temporary solution.  The longer-term solution
is to say that such variables defined in various places are bugs.
I.e. the definition should be moved to a common file.


        Stefan

Message #33 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: cyd <at> stupidchicken.com, 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific, documentation
Date: Tue, 21 Jul 2009 21:30:45 +0300

> From: Stefan Monnier <monnier <at> iro.umontreal.ca>
> Cc: 3888 <at> emacsbugs.donarmstrong.com,  Eli Zaretskii <eliz <at> gnu.org>
> Date: Tue, 21 Jul 2009 12:18:27 -0400
> 
> > I think, as a temporary solution, we should make the docstrings of all
> > the affected functions and variables the same.  If necessary, they can
> > say somehthing like, "On Windows, this does X.  On Nexstep, this does
> > Y", and so on.
> 
> That sounds OK as a quick temporary solution.  The longer-term solution
> is to say that such variables defined in various places are bugs.
> I.e. the definition should be moved to a common file.

Sorry, I don't follow.  Each instance of the definitions of these
identically-named symbols is a different platform-specific
implementation of the same API.  Sometimes, one implementation is in
C, the other in Lisp.  How can they be moved to the same file?  What
am I missing?

Message #38 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Chong Yidong <cyd <at> stupidchicken.com>
Cc: rgm <at> gnu.org, 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific, documentation
Date: Tue, 21 Jul 2009 21:59:52 +0300

> From: Chong Yidong <cyd <at> stupidchicken.com>
> Cc: Glenn Morris <rgm <at> gnu.org>, 3888 <at> 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?

Message #43 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: cyd <at> stupidchicken.com, 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific, documentation
Date: Wed, 22 Jul 2009 14:32:49 -0400

>> > I think, as a temporary solution, we should make the docstrings of all
>> > the affected functions and variables the same.  If necessary, they can
>> > say somehthing like, "On Windows, this does X.  On Nexstep, this does
>> > Y", and so on.
>> 
>> That sounds OK as a quick temporary solution.  The longer-term solution
>> is to say that such variables defined in various places are bugs.
>> I.e. the definition should be moved to a common file.

> Sorry, I don't follow.  Each instance of the definitions of these
> identically-named symbols is a different platform-specific
> implementation of the same API.  Sometimes, one implementation is in
> C, the other in Lisp.  How can they be moved to the same file?

A defvar can trivially be moved from Lisp to C.  I don't see any
obstacle here.  As for functions, it's even easier since you can rename
one of the two from `foo' to `foo-internal' or somesuch and move some
code from one to the other.  We've already done such things for lote and
lots of functions.  There's no technical problem here.


        Stefan

Message #48 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: cyd <at> stupidchicken.com, 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific, documentation
Date: Wed, 22 Jul 2009 21:45:51 +0300

> From: Stefan Monnier <monnier <at> iro.umontreal.ca>
> Cc: cyd <at> stupidchicken.com,  3888 <at> emacsbugs.donarmstrong.com
> Date: Wed, 22 Jul 2009 14:32:49 -0400
> 
> A defvar can trivially be moved from Lisp to C.  I don't see any
> obstacle here.  As for functions, it's even easier since you can rename
> one of the two from `foo' to `foo-internal' or somesuch and move some
> code from one to the other.  We've already done such things for lote and
> lots of functions.  There's no technical problem here.

No technical problems, but experience teaches me that these solutions
don't hold in practice, i.e. new non-internal functions that overload
others pop up with time.

Also, the `foo-internal' trick does not solve the problem of the doc
string that needs to say something platform-specific without bothering
too much the users of other platforms.

Finally, there's (an admittedly very specific and quite rare) problem
of ls-lisp and its ilk that overload the default implementation with
something utterly different, and whose doc string _must_ be very
different if we want it to be useful.

I tried to think of an infrastructure that would solve all these
use-cases in a relatively elegant way that would not become a
maintenance burden.

Message #53 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: cyd <at> stupidchicken.com, 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific, documentation
Date: Wed, 22 Jul 2009 22:43:47 -0400

> No technical problems, but experience teaches me that these solutions
> don't hold in practice, i.e. new non-internal functions that overload
> others pop up with time.

Yes, clearly, this solution is of the form "let's try and impose this
discipline on ourselves in the future".  But it's not like we usually
shy away from coding conventions.

> Also, the `foo-internal' trick does not solve the problem of the doc
> string that needs to say something platform-specific without bothering
> too much the users of other platforms.

That is a docstring problem that needs to be addressed with good use of
language and judgement.  There's no silver bullet for this one.

> Finally, there's (an admittedly very specific and quite rare) problem
> of ls-lisp and its ilk that overload the default implementation with
> something utterly different, and whose doc string _must_ be very
> different if we want it to be useful.

Yes, but again it's not difficult to find a way to do it right, e.g. by
having a shared function whose docstring hyperlinks to the two possible
implementation alternatives and their respective docstrings.  We've done
it already and can do it again.

> I tried to think of an infrastructure that would solve all these
> use-cases in a relatively elegant way that would not become a
> maintenance burden.

That would be swell, but my proposal is a lot more modest.


        Stefan

Message #58 received at 3888-done <at> emacsbugs.donarmstrong.com (full text, mbox):

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

> Date: Tue, 21 Jul 2009 21:59:52 +0300
> From: Eli Zaretskii <eliz <at> gnu.org>
> Cc: 3888 <at> emacsbugs.donarmstrong.com
> 
> > From: Chong Yidong <cyd <at> stupidchicken.com>
> > Cc: Glenn Morris <rgm <at> gnu.org>, 3888 <at> 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.

Message #59 received at 3888-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Chong Yidong <cyd <at> stupidchicken.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 3888-done <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific,	documentation
Date: Fri, 24 Jul 2009 12:49:58 -0400

Eli Zaretskii <eliz <at> gnu.org> writes:

> I fixed all these problems on the branch now.

Thanks.

Message #62 received at 3888 <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 3888 <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific, documentation
Date: Fri, 24 Jul 2009 13:41:18 -0400

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.

Message #63 received at 3888-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 3888-done <at> debbugs.gnu.org
Subject: Re: bug#3888: Some variables get the wrong, platform-specific, documentation
Date: Sat, 25 Jul 2009 12:32:26 +0300

> From: Glenn Morris <rgm <at> gnu.org>
> cc: 3888 <at> emacsbugs.donarmstrong.com
> Date: Fri, 24 Jul 2009 13:41:18 -0400
> 
> 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.

I moved these fixes to the trunk.

Previous Next

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