Re: Native line numbers landed on master

[Eli Zaretskii]

> From: Robert Pluim <address@hidden>
> Cc: address@hidden
> Date: Wed, 09 Oct 2019 09:19:57 +0200
> 
>     Eli> Bonus points for adding information missing from the above, such as
>     Eli> how to define buffer-local variables (see init_buffer_once), and how
>     Eli> to define custom forms for variables defined in C.
> 
> Youʼre a hard taskmaster Eli :-) .

I've been told that, yes ;-)

> Iʼve done my best, although I donʼt see where init_buffer_once comes
> in.

I meant the likes of this:

  XSETFASTINT (BVAR (&buffer_local_flags, tab_width), idx); ++idx;

Anyone who defines buffer-local variables should generally be familiar
with this stuff.

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

> +  There are situations in Lisp where you need to refer to the symbol
> +itself rather than the value of that symbol.  One such case is when
> +temporarily overriding the value of a variable, which in Lisp is done
> +with @code{let}.  In C sources, this is done by defining a
> +corresponding, constant symbol, and using @code{specbind}.  By
> +convention @code{Qmy_lisp_variable} corresponds to
> +@code{Vmy_lisp_variable}; to define it, use the @code{DEFSYM} macro.
> +i.e.
> +
> +@smallexample
> +DEFSYM (Qmy_lisp_variable, "my-lisp-variable");
> +@end smallexample
> +
> +  To perform the actual binding:
> +
> +@smallexample
> +specbind (Qmy_lisp_variable, Qt);
> +@end smallexample
> +
> +  Another use for constant symbols is when creating a buffer-local
> +variable (@pxref{Buffer-Local Variables}).  In C this is done with
> +@code{Fmake_variable_buffer_local} in combination with @code{DEFSYM},
> +i.e.
> +
> +@smallexample
> +DEFSYM (Qmy_lisp_variable, "my-lisp-variable");
> +Fmake_variable_buffer_local (Qmy_lisp_variable);
> +@end smallexample

This is great, but I think it would be even better if we explained the
general principle: the Qfoo symbol is needed where in Lisp you'd use a
quoted symbol 'foo.

> +@file{cus-start.el}.  @xref{Variable Definitions} for a description of
> +the format to use.                               ^

Comma is missing there, although recent versions of Texinfo no longer
flag this.

Otherwise, this is a very good addition; thank you.