bug#10783: Some built-in functionslost their argument names

bug#10783: Some built-in functionslost their argument names

[Glenn Morris]

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.

bug#10783: Some built-in functionslost their argument names

[Andreas Schwab]

Glenn Morris <rgm@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@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#10783: Some built-in functionslost their argument names

[Glenn Morris]

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.

bug#10783: Some built-in functionslost their argument names

[Andreas Schwab]

Glenn Morris <rgm@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@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#10783: Some built-in functionslost their argument names

[Eli Zaretskii]

> From: Andreas Schwab <schwab@linux-m68k.org>
> Date: Sat, 11 Feb 2012 08:43:32 +0100
> Cc: 10783@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.

bug#10783: Some built-in functionslost their argument names

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Fri, 10 Feb 2012 18:30:59 -0500
> Cc: 10783@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).

bug#10783: Some built-in functionslost their argument names

[Glenn Morris]

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?

bug#10783: Some built-in functionslost their argument names

[Glenn Morris]

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.

bug#10783: Some built-in functionslost their argument names

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: schwab@linux-m68k.org,  10783@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?

bug#10783: Some built-in functionslost their argument names

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: 10783@debbugs.gnu.org,  schwab@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?

bug#10783: Some built-in functionslost their argument names

[Glenn Morris]

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)

bug#10783: Some built-in functionslost their argument names

[Stefan Monnier]

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

bug#10783: Some built-in functionslost their argument names

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Glenn Morris <rgm@gnu.org>,  10783@debbugs.gnu.org,  schwab@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.

bug#10783: Some built-in functionslost their argument names

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: 10783@debbugs.gnu.org,  schwab@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.

bug#10783: Some built-in functionslost their argument names

[Stefan Monnier]

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

bug#10783: Some built-in functionslost their argument names

[Glenn Morris]

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.

bug#10783: Some built-in functionslost their argument names

[Glenn Morris]

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.

bug#10783: Some built-in functionslost their argument names

[Jason Rumney]

Stefan Monnier <monnier@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?

bug#10783: Some built-in functionslost their argument names

[Stefan Monnier]

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

bug#10783: Some built-in functionslost their argument names

[Glenn Morris]

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.