GNU bug report logs - #10783
Some built-in functions lost their argument names

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 10783 in the body.
You can then email your comments to 10783 AT debbugs.gnu.org in the normal way.

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

Message #3 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: submit <at> debbugs.gnu.org
Subject: Some built-in functionslost their argument names
Date: Fri, 10 Feb 2012 16:25:57 -0500

Package: emacs
Version: 24.0.93

Current trunk on x86_64 GNU/Linux:

emacs -Q
C-h f x-get-selection-internal

  x-get-selection-internal is a built-in function in `xselect.c'.

  (x-get-selection-internal ARG1 ARG2 &optional ARG3 ARG4)


It has lost the argument names.
Actually, it is also missing the entire second paragraph of the doc
("TERMINAL should be a terminal object...").


In 23.4, it says:

  x-get-selection-internal is a built-in function in `C source code'.

  (x-get-selection-internal SELECTION-SYMBOL TARGET-TYPE &optional TIME-STAMP)


Similar problem for at least x-disown-selection-internal,
x-own-selection-internal. It still works for eg x-get-atom-name though.

`documentation' no longer returns the "(fn )" part, which causes
help-split-fundoc to return nil.

Message #6 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sat, 11 Feb 2012 00:04:06 +0100

Glenn Morris <rgm <at> gnu.org> writes:

> Package: emacs
> Version: 24.0.93
>
> Current trunk on x86_64 GNU/Linux:
>
> emacs -Q
> C-h f x-get-selection-internal
>
>   x-get-selection-internal is a built-in function in `xselect.c'.
>
>   (x-get-selection-internal ARG1 ARG2 &optional ARG3 ARG4)
>
>
> It has lost the argument names.
> Actually, it is also missing the entire second paragraph of the doc
> ("TERMINAL should be a terminal object...").

That's because of the duplicate definition in term/pc-win.el (you get
the doc string of the definition that comes last in DOC).

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Message #9 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 10783 <at> debbugs.gnu.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Fri, 10 Feb 2012 18:30:59 -0500

Andreas Schwab wrote:

>> It has lost the argument names.
>> Actually, it is also missing the entire second paragraph of the doc
>> ("TERMINAL should be a terminal object...").
>
> That's because of the duplicate definition in term/pc-win.el

Oh, this nuisance again. Sync'ing the doc-strings won't help with the
argument names. At least it is better than 23.4, where eg

 x-own-selection-internal is a built-in function in `C source code'.
 [Missing arglist.  Please make a bug report.]

Deleting the doc-strings altogether from the duplicate definitions in
pc-win.el would make this problem go away.

Message #12 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sat, 11 Feb 2012 08:43:32 +0100

Glenn Morris <rgm <at> gnu.org> writes:

> Deleting the doc-strings altogether from the duplicate definitions in
> pc-win.el would make this problem go away.

There are more duplicates in nsselect.m, w16select.c and w32select.c,
that are not up-to-date wrt xselect.c.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Message #15 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: rgm <at> gnu.org, 10783 <at> debbugs.gnu.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sat, 11 Feb 2012 11:54:01 +0200

> From: Andreas Schwab <schwab <at> linux-m68k.org>
> Date: Sat, 11 Feb 2012 08:43:32 +0100
> Cc: 10783 <at> debbugs.gnu.org
> 
> There are more duplicates in nsselect.m, w16select.c and w32select.c,
> that are not up-to-date wrt xselect.c.

Thanks, I fixed w16select.c and pc-win.el in revision 107240, and
w32select.c in revision 107241.

Message #18 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sat, 11 Feb 2012 12:01:55 +0200

> From: Glenn Morris <rgm <at> gnu.org>
> Date: Fri, 10 Feb 2012 18:30:59 -0500
> Cc: 10783 <at> debbugs.gnu.org
> 
> Deleting the doc-strings altogether from the duplicate definitions in
> pc-win.el would make this problem go away.

Maybe I'm missing something, but deleting the doc string from
pc-win.el shows x-get-selection-internal as "not documented" in the
MS-DOS build.

So for now, I sync'ed the doc strings with the X sources.

Note that some doc strings seem to require "more work™".  E.g., this:

  DEFUN ("x-disown-selection-internal", Fx_disown_selection_internal,
	 Sx_disown_selection_internal, 1, 3, 0,
	 doc: /* If we own the selection SELECTION, disown it.
  Disowning it means there is no such selection.

  TERMINAL should be a terminal object or a frame specifying the X
  server to query.  If omitted or nil, that stands for the selected
  frame's display, or the first available X display.  */)
    (Lisp_Object selection, Lisp_Object time_object, Lisp_Object terminal)

(TIME_OBJECT is not mentioned).  Or this:

  DEFUN ("x-get-selection-internal", Fx_get_selection_internal,
	 Sx_get_selection_internal, 2, 4, 0,
	 doc: /* Return text selected from some X window.
  SELECTION is a symbol, typically `PRIMARY', `SECONDARY', or `CLIPBOARD'.
  \(Those are literal upper-case symbol names, since that's what X expects.)
  TYPE is the type of data desired, typically `STRING'.
  TIME_STAMP is the time to use in the XConvertSelection call for foreign
  selections.  If omitted, defaults to the time for the last event.

  TERMINAL should be a terminal object or a frame specifying the X
  server to query.  If omitted or nil, that stands for the selected
  frame's display, or the first available X display.  */)
    (Lisp_Object selection_symbol, Lisp_Object target_type,
     Lisp_Object time_stamp, Lisp_Object terminal)

(refers to SELECTION, TYPE and TIME_STAMP, whereas the actual
parameters are SELECTION-SYMBOL, TARGET-TYPE, and TIME-STAMP).

Message #21 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sat, 11 Feb 2012 17:40:13 -0500

Eli Zaretskii wrote:

>> Deleting the doc-strings altogether from the duplicate definitions in
>> pc-win.el would make this problem go away.
>
> Maybe I'm missing something, but deleting the doc string from
> pc-win.el shows x-get-selection-internal as "not documented" in the
> MS-DOS build.

I hadn't got round to checking whether that happened, or whether it
picked up a doc string from one of the other definitions.
I was also thinking that there would not be many users of the MS-DOS
build wanting to look at the doc of the x-* functions, so rather than
you having to keep them in sync all the time, you could just remove
them. Eg there are already many compat x-* functions without docs in
pc-win.el.

> So for now, I sync'ed the doc strings with the X sources.

Thanks.

It still leaves the initial problem I noticed of the argument names
being lost. I wonder if it helps if to also add the "(fn ..." part to
the end of the pc-win.el doc strings?

Message #24 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sat, 11 Feb 2012 22:23:40 -0500

Glenn Morris wrote:

> I wonder if it helps if to also add the "(fn ..." part to the end of
> the pc-win.el doc strings?

That fixes the problem on GNU/Linux.

Message #27 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sun, 12 Feb 2012 06:02:45 +0200

> From: Glenn Morris <rgm <at> gnu.org>
> Cc: schwab <at> linux-m68k.org,  10783 <at> debbugs.gnu.org
> Date: Sat, 11 Feb 2012 17:40:13 -0500
> 
> I was also thinking that there would not be many users of the MS-DOS
> build wanting to look at the doc of the x-* functions

I don't understand how this would be TRT.  The MS-DOS build of Emacs
supports the clipboard, so these functions are there not just for
beauty.

> Eg there are already many compat x-* functions without docs in
> pc-win.el.

They all lack a doc string in their X versions as well, AFAICS.

> I wonder if it helps if to also add the "(fn ..." part to the end of
> the pc-win.el doc strings?

Sorry, I don't follow.  Can you give an example?

Message #30 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sun, 12 Feb 2012 06:05:51 +0200

> From: Glenn Morris <rgm <at> gnu.org>
> Cc: 10783 <at> debbugs.gnu.org,  schwab <at> linux-m68k.org
> Date: Sat, 11 Feb 2012 22:23:40 -0500
> 
> Glenn Morris wrote:
> 
> > I wonder if it helps if to also add the "(fn ..." part to the end of
> > the pc-win.el doc strings?
> 
> That fixes the problem on GNU/Linux.

How and why does it do that?  And what problem is that?

Message #33 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sun, 12 Feb 2012 00:14:23 -0500

Eli Zaretskii wrote:

>> That fixes the problem on GNU/Linux.
>
> How and why does it do that?  And what problem is that?

The problem that I reported with the argument names being lost (replaced
by ARG1 etc).

Because help-function-arglist calls help-split-fundoc which expects to
find \n\n(fn in the doc of built-in functions. It doesn't expect
functions to be built-in on some platforms and not on others.

Example:

--- pc-win.el   2012-02-11 19:22:20.968856000 -0800
+++ pc-win.el.~1~          2012-02-11 19:21:36.185359943 -0800
@@ -289,7 +289,9 @@
 FRAME should be a frame that should own the selection.  If omitted or
 nil, it defaults to the selected frame.
 
-On Nextstep, FRAME is unused."
+On Nextstep, FRAME is unused.
+
+\(fn SELECTION VALUE &optional FRAME)"
   (ignore-errors
     (x-select-text value))
   value)

Message #36 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: Glenn Morris <rgm <at> gnu.org>, 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sun, 12 Feb 2012 10:28:27 -0500

Just for the record: such duplicate definitions should be removed.
E.g. the C and pc-win.el definitions should be refactored such that
there is only one C definition (which might call an Elisp implementation
in the MS-DOS case).


        Stefan

Message #39 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: rgm <at> gnu.org, 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sun, 12 Feb 2012 18:29:19 +0200

> From: Stefan Monnier <monnier <at> iro.umontreal.ca>
> Cc: Glenn Morris <rgm <at> gnu.org>,  10783 <at> debbugs.gnu.org,  schwab <at> linux-m68k.org
> Date: Sun, 12 Feb 2012 10:28:27 -0500
> 
> Just for the record: such duplicate definitions should be removed.
> E.g. the C and pc-win.el definitions should be refactored such that
> there is only one C definition (which might call an Elisp implementation
> in the MS-DOS case).

That would require extracting the common parts from the various
*select.c source files and putting them on a common file compiled into
all ports.  Not something for the current pretest, IMO.

Message #42 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Glenn Morris <rgm <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sun, 12 Feb 2012 18:30:07 +0200

> From: Glenn Morris <rgm <at> gnu.org>
> Cc: 10783 <at> debbugs.gnu.org,  schwab <at> linux-m68k.org
> Date: Sun, 12 Feb 2012 00:14:23 -0500
> 
> -On Nextstep, FRAME is unused."
> +On Nextstep, FRAME is unused.
> +
> +\(fn SELECTION VALUE &optional FRAME)"
>    (ignore-errors
>      (x-select-text value))
>    value)

OK, I will do that for DOS-related Lisp functions that shadow C
primitives.

Message #45 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: rgm <at> gnu.org, 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sun, 12 Feb 2012 12:01:53 -0500

>> Just for the record: such duplicate definitions should be removed.
>> E.g. the C and pc-win.el definitions should be refactored such that
>> there is only one C definition (which might call an Elisp implementation
>> in the MS-DOS case).

> That would require extracting the common parts from the various
> *select.c source files and putting them on a common file compiled into
> all ports.

Yup.

> Not something for the current pretest, IMO.

Yup.


        Stefan

Message #48 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Eli Zaretskii <eliz <at> gnu.org>, schwab <at> linux-m68k.org, 10783 <at> debbugs.gnu.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sun, 12 Feb 2012 14:53:16 -0500

Stefan Monnier wrote:

> Just for the record: such duplicate definitions should be removed.
> E.g. the C and pc-win.el definitions should be refactored such that
> there is only one C definition (which might call an Elisp implementation
> in the MS-DOS case).

http://debbugs.gnu.org/cgi/bugreport.cgi?bug=4402 :)

Obviously for 24.1 we can keep papering over it by syncing up all the
various docs, and doing something about this arglist issue.

Message #51 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 10783 <at> debbugs.gnu.org, schwab <at> linux-m68k.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Sun, 12 Feb 2012 14:58:49 -0500

Eli Zaretskii wrote:

>> Eg there are already many compat x-* functions without docs in
>> pc-win.el.
>
> They all lack a doc string in their X versions as well, AFAICS.

The only one I looked at was x-server-vendor, which does have a doc in
X.

Message #54 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Jason Rumney <jasonr <at> gnu.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: Eli Zaretskii <eliz <at> gnu.org>, schwab <at> linux-m68k.org, 10783 <at> debbugs.gnu.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Mon, 13 Feb 2012 21:19:38 +0800

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> Just for the record: such duplicate definitions should be removed.
> E.g. the C and pc-win.el definitions should be refactored such that
> there is only one C definition (which might call an Elisp implementation
> in the MS-DOS case).

Wouldn't it be better for the common definition to be Lisp, with calls
into C where neccesary?

Message #57 received at 10783 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> IRO.UMontreal.CA>
To: Jason Rumney <jasonr <at> gnu.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, schwab <at> linux-m68k.org, 10783 <at> debbugs.gnu.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Mon, 13 Feb 2012 10:19:34 -0500

>> Just for the record: such duplicate definitions should be removed.
>> E.g. the C and pc-win.el definitions should be refactored such that
>> there is only one C definition (which might call an Elisp implementation
>> in the MS-DOS case).
> Wouldn't it be better for the common definition to be Lisp, with calls
> into C where necessary?

Depends on the actual code in the common part.  It will have some kind
of dispatch to the appropriate backend, which can either go through the
terminal methods or through some case/switch.  In the case we use
case/switch it can just as well be performed in Elisp, indeed.

But the common code may also include more shared code which may require
the use of C, or in some other cases we won't want to expose the
backend-specific code to Elisp.


        Stefan


PS: Of course, the common code should not use the "x-" prefix.

Message #64 received at 10783-done <at> debbugs.gnu.org (full text, mbox):

From: Glenn Morris <rgm <at> gnu.org>
To: 10783-done <at> debbugs.gnu.org
Subject: Re: bug#10783: Some built-in functionslost their argument names
Date: Tue, 06 Mar 2012 14:50:04 -0500

Version: 24.0.95

Glenn Morris wrote:

>> I wonder if it helps if to also add the "(fn ..." part to the end of
>> the pc-win.el doc strings?
>
> That fixes the problem on GNU/Linux.

Installed.

Previous Next

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