Clarify & update (elisp) Writing Emacs Primitives

* doc/lispref/internals.texi (Writing Emacs Primitives): Update some
of the sample code listings, fixing argument lists and parentheses.
Replace ... with @dots{}.  Describe UNEVALLED special forms as
taking a single argument. (bug#36392)

1 files changed, 31 insertions, 29 deletions

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 7cbd2966839..6a7ea1c6913 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -654,8 +654,8 @@ appearance.)
 @smallexample
 @group
 DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
-  doc: /* Eval args until one of them yields non-nil, then return
-that value.
+       doc: /* Eval args until one of them yields non-nil,
+then return that value.
 The remaining args are not evalled at all.
 If all args return nil, return nil.
 @end group
@@ -729,7 +729,7 @@ less than 8.
 This is an interactive specification, a string such as might be used
 as the argument of @code{interactive} in a Lisp function
 (@pxref{Using Interactive}).  In the case
-of @code{or}, it is 0 (a null pointer), indicating that @code{or}
+of @code{or}, it is @code{0} (a null pointer), indicating that @code{or}
 cannot be called interactively.  A value of @code{""} indicates a
 function that should receive no arguments when called interactively.
 If the value begins with a @samp{"(}, the string is evaluated as a
@@ -737,11 +737,11 @@ Lisp form.  For example:
 
 @example
 @group
-DEFUN ("foo", Ffoo, Sfoo, 0, UNEVALLED, 0
+DEFUN ("foo", Ffoo, Sfoo, 0, 3,
        "(list (read-char-by-name \"Insert character: \")\
               (prefix-numeric-value current-prefix-arg)\
-              t))",
-  doc: /* @dots{} */)
+              t)",
+       doc: /* @dots{} */)
 @end group
 @end example
 
@@ -771,8 +771,8 @@ this:
 @example
 @group
 DEFUN ("bar", Fbar, Sbar, 0, UNEVALLED, 0
-  doc: /* @dots{} */
-  attributes: @var{attr1} @var{attr2} @dots{})
+       doc: /* @dots{} */
+       attributes: @var{attr1} @var{attr2} @dots{})
 @end group
 @end example
 
@@ -808,15 +808,18 @@ arguments.  If the primitive accepts a fixed maximum number of Lisp
 arguments, there must be one C argument for each Lisp argument, and
 each argument must be of type @code{Lisp_Object}.  (Various macros and
 functions for creating values of type @code{Lisp_Object} are declared
-in the file @file{lisp.h}.)  If the primitive has no upper limit on
-the number of Lisp arguments, it must have exactly two C arguments:
-the first is the number of Lisp arguments, and the second is the
-address of a block containing their values.  These have types
-@code{int} and @w{@code{Lisp_Object *}} respectively.  Since
-@code{Lisp_Object} can hold any Lisp object of any data type, you
-can determine the actual data type only at run time; so if you want
-a primitive to accept only a certain type of argument, you must check
-the type explicitly using a suitable predicate (@pxref{Type Predicates}).
+in the file @file{lisp.h}.)  If the primitive is a special form, it
+must accept a Lisp list containing its unevaluated Lisp arguments as a
+single argument of type @code{Lisp_Object}.  If the primitive has no
+upper limit on the number of evaluated Lisp arguments, it must have
+exactly two C arguments: the first is the number of Lisp arguments,
+and the second is the address of a block containing their values.
+These have types @code{ptrdiff_t} and @w{@code{Lisp_Object *}},
+respectively.  Since @code{Lisp_Object} can hold any Lisp object of
+any data type, you can determine the actual data type only at run
+time; so if you want a primitive to accept only a certain type of
+argument, you must check the type explicitly using a suitable
+predicate (@pxref{Type Predicates}).
 @cindex type checking internals
 
 @cindex garbage collection protection
@@ -906,9 +909,9 @@ of macros and functions to manipulate Lisp objects.
 @smallexample
 @group
 DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
-  Scoordinates_in_window_p, 2, 2, 0,
-  doc: /* Return non-nil if COORDINATES are in WINDOW.
-  ...
+       Scoordinates_in_window_p, 2, 2, 0,
+       doc: /* Return non-nil if COORDINATES are in WINDOW.
+  @dots{}
 @end group
 @group
   or `right-margin' is returned.  */)
@@ -921,16 +924,15 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
 @end group
 
 @group
-  CHECK_LIVE_WINDOW (window);
-  w = XWINDOW (window);
+  w = decode_live_window (window);
   f = XFRAME (w->frame);
   CHECK_CONS (coordinates);
   lx = Fcar (coordinates);
   ly = Fcdr (coordinates);
-  CHECK_NUMBER_OR_FLOAT (lx);
-  CHECK_NUMBER_OR_FLOAT (ly);
-  x = FRAME_PIXEL_X_FROM_CANON_X (f, lx) + FRAME_INTERNAL_BORDER_WIDTH(f);
-  y = FRAME_PIXEL_Y_FROM_CANON_Y (f, ly) + FRAME_INTERNAL_BORDER_WIDTH(f);
+  CHECK_NUMBER (lx);
+  CHECK_NUMBER (ly);
+  x = FRAME_PIXEL_X_FROM_CANON_X (f, lx) + FRAME_INTERNAL_BORDER_WIDTH (f);
+  y = FRAME_PIXEL_Y_FROM_CANON_Y (f, ly) + FRAME_INTERNAL_BORDER_WIDTH (f);
 @end group
 
 @group
@@ -940,14 +942,14 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
       return Qnil;
 @end group
 
-    ...
+    @dots{}
 
 @group
     case ON_MODE_LINE:          /* In mode line of window.  */
       return Qmode_line;
 @end group
 
-    ...
+    @dots{}
 
 @group
     case ON_SCROLL_BAR:         /* On scroll-bar of window.  */
@@ -957,7 +959,7 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
 
 @group
     default:
-      abort ();
+      emacs_abort ();
     @}
 @}
 @end group