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: Some variables get the wrong, platform-specific, documentation

[Chong Yidong]

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

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

[Chong Yidong]

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.

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

[Eli Zaretskii]

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

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

[Stefan Monnier]

> 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

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: 3888@emacsbugs.donarmstrong.com,  Eli Zaretskii <eliz@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?

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

[Eli Zaretskii]

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

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

[Stefan Monnier]

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

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

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: cyd@stupidchicken.com,  3888@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.

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

[Stefan Monnier]

> 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

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.