Re: Native line numbers landed on master

[Eli Zaretskii]

> From: Robert Pluim <address@hidden>
> Cc: address@hidden,  address@hidden,  address@hidden,
>   address@hidden,  address@hidden,  address@hidden
> Date: Tue, 08 Oct 2019 13:15:46 +0200
> 
> I donʼt know about a separate node. How about this:

Thanks, it's a good start.  See a few comments below.

> +@table @code
> +@item lname
> +The Lisp-level name of the variable.
> +@item vname
> +The C-level name of the variable.

Instead of "Lisp-level" and "C-level", which IMO are somewhat unclear,
I'd use the likes of "the name of the variable to be used by Lisp
programs" and "the name of the variable in the C source".

> +@item doc
> +The documentation for the variable, as a C comment.

Here, please include a cross-reference to the tips about writing doc
strings.

> +  By convention, when defining variables of a ``native'' type
> +(@code{int} and @code{bool}), the name of the C variable is the same
> +as the name of the Lisp variable with ``-'' replaced by ``_''.  When
> +the variable can hold any Lisp object, the convention is
> +to also prefix the C variable name with ``V''.  i.e.

I think -, _, and V should be in @code or @samp, not in quotes.  Also,
I'd mention explicitly that the C data type of the latter category is
Lisp_Object.

> +If you want to define a constant symbol rather than a variable, use
> +@code{DEFSYM} instead.  e.g.
> +
> +@smallexample
> +DEFSYM ("Qmy_symbol", "my-symbol");
> +@end smallexample

This is IMO confusing, because it doesn't explain when would the C
programmer want "to define a constant symbol rather than a variable".
I think it's important to explain that the symbol corresponding to a
variable is needed where in Lisp one would use a quoted symbol.  A
good example is the use of specbind which is the equivalent of
let-binding on the Lisp level.

Bonus points for adding information missing from the above, such as
how to define buffer-local variables (see init_buffer_once), and how
to define custom forms for variables defined in C.