Re: Native line numbers landed on master

[Robert Pluim <rpluim@gmail.com>]

>>>>> On Tue, 08 Oct 2019 15:23:57 +0300, Eli Zaretskii <eliz@gnu.org> said:

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

Done

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

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

Done

    >> +  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.

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

Done

    >> +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

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

Not just confusing, my example was wrong. I expanded that bit.

    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 done my best, although I donʼt
see where init_buffer_once comes in.

Thereʼs a sentence further down that talks about cus-start.el, I added
a cross-reference to the defcustom node.

* doc/lispref/internals.texi (Writing Emacs Primitives): Add
description of DEFVAR_* arguments.  Describe variable naming
conventions. Explain 'specbind' and how to create buffer-local
variables.

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index c52999e1cd..45725c3c80 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -945,7 +945,7 @@ Writing Emacs Primitives
 @anchor{Defining Lisp variables in C}
 @vindex byte-boolean-vars
 @cindex defining Lisp variables in C
-@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}
+@cindex @code{DEFVAR_INT}, @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}, @code{DEFSYM}
   The function @code{syms_of_@var{filename}} is also the place to define
 any C variables that are to be visible as Lisp variables.
 @code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
@@ -956,15 +956,71 @@ Writing Emacs Primitives
 defined with @code{DEFVAR_BOOL} are automatically added to the list
 @code{byte-boolean-vars} used by the byte compiler.
 
+  These macros all expect three arguments:
+
+@table @code
+@item lname
+The name of the variable to be used by Lisp programs.
+@item vname
+The name of the variable in the C sources.
+@item doc
+The documentation for the variable, as a C
+comment.  @xref{Documentation Basics} for more details.
+@end table
+
+  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.
+
+@smallexample
+DEFVAR_INT ("my-int-variable", my_int_variable,
+           doc: /* An integer variable.  */);
+
+DEFVAR_LISP ("my-lisp-variable", Vmy_lisp_variable,
+           doc: /* A Lisp variable.  */);
+@end smallexample
+
+  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
+
 @cindex defining customization variables in C
   If you want to make a Lisp variable that is defined in C behave
 like one declared with @code{defcustom}, add an appropriate entry to
-@file{cus-start.el}.
+@file{cus-start.el}.  @xref{Variable Definitions} for a description of
+the format to use.
 
 @cindex @code{staticpro}, protection from GC
-  If you define a file-scope C variable of type @code{Lisp_Object},
-you must protect it from garbage-collection by calling @code{staticpro}
-in @code{syms_of_@var{filename}}, like this:
+  If you directly define a file-scope C variable of type
+@code{Lisp_Object}, you must protect it from garbage-collection by
+calling @code{staticpro} in @code{syms_of_@var{filename}}, like this:
 
 @example
 staticpro (&@var{variable});