Subject: bug#36392: (info "(elisp)Writing Emacs Primitives") might need some clarifications

From: Stefan Kangas <[email-masked]>
Date: Wed, 26 Jun 2019 13:31:06 +0200

As a beginner on Emacs Internals, I've been reading:

(info "(elisp)Writing Emacs Primitives")

I hope that you find the following observations useful:

1.  "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 ‘Lisp_Object’.  ...  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."

The example given is DEFUN( "or", ...)

This function has no upper limit on the number of Lisp arguments, but
still has only ONE argument.  Unless I'm missing something, this
contradicts the statement above that "it must have exactly TWO C
arguments" (my emphasis).

2.  "Although the garbage collector does not reclaim objects reachable
    from C ‘Lisp_Object’ stack variables, it may move non-object
    components of an object, such as string contents; so functions
    that access non-object components must take care to refetch their
    addresses after performing Lisp evaluation."

I don't think this is very clear.  What is non-object components?  How
would I refetch their addresses?  How is this relevant to the topic at
hand?

I suggest that the above two points are clarified in the manual
somehow.

Thanks,
Stefan Kangas