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

["Basil L. Contovounesios" <contovob@tcd.ie>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Date: Wed, 26 Jun 2019 14:09:03 +0100
>> Cc: 36392@debbugs.gnu.org
>> 
>> >From 3d85d73858fe0c126277d04db8b99eeb9f09d672 Mon Sep 17 00:00:00 2001
>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Date: Wed, 26 Jun 2019 13:05:51 +0100
>> Subject: [PATCH] Clarify & update (elisp) Writing Emacs Primitives
>> 
>> * doc/lispref/internals.texi (Writing Emacs Primitives): Replace
>> outdated For listing with current Fwhile, so that the subsequent
>> paragraph on maybe_quit still applies.  Reconcile other code
>> listings with their current source.  Fix indentation of sample DEFUN
>> argument lists.  Replace ... with @dots{}.  Fix argument list of
>> Ffoo example.  Describe UNEVALLED special forms as taking a single
>> argument. (bug#36392)
>
> Hmm... I admit that I don't understand the rationale for these
> changes.
>
> Why replace the example?  It's a useful example, and I see nothing
> wrong with it per se.  The actual code doesn't have maybe_quit
> anymore, but so what?  I don't think we should chace every change in
> the sources with our examples in the manual.

Indeed there's nothing wrong with the current example, and I don't feel
too strongly about the change.

Fwhile just happens to be a conveniently similar special form that is
better represented by the paragraph on maybe_quit (not just because
Fwhile currently calls maybe_quit, but also because it epitomises the
need for maybe_quit).

Do you prefer not to switch the example to Fwhile?

>> @@ -863,20 +860,23 @@ Writing Emacs Primitives
>>  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
>
> This part sounds OK to me, and is probably more than enough to fix the
> issue at hand.

Indeed, thanks.

>> -    case ON_NOTHING:            /* NOT in window at all.  */
>> +    case ON_NOTHING:
>
> This seems a change for the worst?

I'll bring back the comments.

>> > 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 don't know about this.
>
> I clarified that.

Thanks,

-- 
Basil