From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Robert Pluim Newsgroups: gmane.emacs.devel Subject: Re: Native line numbers landed on master Date: Wed, 09 Oct 2019 14:14:48 +0200 Message-ID: References: <834l4xbfmp.fsf@gnu.org> <83lfu389vn.fsf@gnu.org> <87ftk9v4kx.fsf@wavexx.thregr.org> <83wodl54yt.fsf@gnu.org> <87pnjchm7p.fsf@wavexx.thregr.org> <83pnj8zff9.fsf@gnu.org> <83blurxw6a.fsf@gnu.org> <838spuwcyj.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="53973"; mail-complaints-to="usenet@blaine.gmane.org" Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Oct 09 20:26:39 2019 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1iIGfW-000Drx-NW for ged-emacs-devel@m.gmane.org; Wed, 09 Oct 2019 20:26:38 +0200 Original-Received: from localhost ([::1]:53812 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iIGfU-0003X6-VM for ged-emacs-devel@m.gmane.org; Wed, 09 Oct 2019 14:26:37 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:39449) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iIArm-0004Co-Am for emacs-devel@gnu.org; Wed, 09 Oct 2019 08:14:55 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iIArk-0004UR-Tx for emacs-devel@gnu.org; Wed, 09 Oct 2019 08:14:54 -0400 Original-Received: from mail-wr1-x42c.google.com ([2a00:1450:4864:20::42c]:44977) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iIArk-0004UD-Nb; Wed, 09 Oct 2019 08:14:52 -0400 Original-Received: by mail-wr1-x42c.google.com with SMTP id z9so2639276wrl.11; Wed, 09 Oct 2019 05:14:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:message-id:mime-version :content-transfer-encoding; bh=DzTW9NNl0RAWwni8qjm5byQX7mW55OMfQ//xjLeKO7c=; b=j6rOW3YEpLWDxzKePTOiaT6A4FBh1jWjDQYpv5x260HyT3T0+2zTGfMXx4ON1zB331 szTW/PZhE9wXXmtlBAmbBGfYzoO9YLKNwMyzcnHIZAo2DLP9zi8uBoG1cTq7LyXQlBXI xF+/aOggF1GUgXSXgAVfr7fXVUbxPU8fqTnBlCND6GRpZehaK1DGhFzbFBtnECKl7dDZ XR4PLqA0GqMLdpEe0rtOiX5Wl3jATLSHP7xW0pexT9Vb9thKHYDyDjscziqFlbLF1NDB xbNkkjtietBe4KuVk9kZuZjRBUY2Re6eKa/DVqM+M2lgGYi4NDuWdtbkLbsqmtvjoMYg GbJw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:message-id :mime-version:content-transfer-encoding; bh=DzTW9NNl0RAWwni8qjm5byQX7mW55OMfQ//xjLeKO7c=; b=TEjXysrBO87fBweFScRku+LrxxYxJqY6vtt0nRF9gQ3uFxCMofCntj3cxo07oKL1Cf sAtx94biDDeFB1qD0rqHXVqoEE5Xl9LwgAjw1lTUf9ax30QayhDe1HRyxbbIW+EXKzPM 70oY4PMlKuBU7/bgWxTZtf71RfpEqtOxCfUPBD9iyBEPM1SPbfdqFpFJ7t0SF7ZLr02H 47cf/rf5tTVkameQEP1yfH8VuR7A7/olLVapiDloy6T/l3TK/AnkXx28aBUDQ0C95Jsr VX4+NtNFxFZVWzqz3IYz5ujmvwregYY3C6pZqYvTOohf8XEs47+RNY4N6h7GJKKGZNm9 NGyQ== X-Gm-Message-State: APjAAAWm+iou8g8R8tTkaOknBEncfuiJ96iR8TnpkwaMjd7vHEgytQgH RShG5Xa5KXL0VqPCRh3geRLVNty3 X-Google-Smtp-Source: APXvYqykUmWUe/rg/o/ba2cRMf30ajii6QEWY4BU32G5dw7Yh3RzsmHfzonwfQvY9EUokXcpCFehiA== X-Received: by 2002:adf:ecd0:: with SMTP id s16mr2608248wro.65.1570623290991; Wed, 09 Oct 2019 05:14:50 -0700 (PDT) Original-Received: from rpluim-mac ([149.5.228.1]) by smtp.gmail.com with ESMTPSA id a71sm2272189wme.11.2019.10.09.05.14.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 09 Oct 2019 05:14:49 -0700 (PDT) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::42c X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:240778 Archived-At: >>>>> On Wed, 09 Oct 2019 11:16:36 +0300, Eli Zaretskii said: >> I=CA=BCve done my best, although I don=CA=BCt see where init_buffer_= once comes >> in. Eli> I meant the likes of this: Eli> XSETFASTINT (BVAR (&buffer_local_flags, tab_width), idx); ++idx; Eli> Anyone who defines buffer-local variables should generally be fami= liar Eli> with this stuff. That=CA=BCs for variables defined with DEFVAR_PER_BUFFER, not Fmake_variable_buffer_local, no? Do people add those often enough that we need to document it? >> + 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 pre= fix >> +the C variable name with ``V''. i.e. Eli> ^^^^^ Eli> @code{V} Fixed. >> +@smallexample >> +DEFSYM (Qmy_lisp_variable, "my-lisp-variable"); >> +Fmake_variable_buffer_local (Qmy_lisp_variable); >> +@end smallexample Eli> This is great, but I think it would be even better if we explained= the Eli> general principle: the Qfoo symbol is needed where in Lisp you'd u= se a Eli> quoted symbol 'foo. Added. >> +@file{cus-start.el}. @xref{Variable Definitions} for a description= of >> +the format to use. ^ Eli> Comma is missing there, although recent versions of Texinfo no lon= ger Eli> flag this. Fixed. * doc/lispref/internals.texi (Writing Emacs Primitives): Add description of DEFVAR_* arguments. Describe variable naming conventions. Explain how to express quoting of symbols in C, plus 'specbind' and how to create buffer-local variables. diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index c52999e1cd..c2a15fe8af 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{D= EFSYM} 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,78 @@ Writing Emacs Primitives defined with @code{DEFVAR_BOOL} are automatically added to the list @code{byte-boolean-vars} used by the byte compiler. =20 + 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 @code{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 + + In Lisp symbols sometimes need to be quoted, to achieve the same +effect in C you again use the corresponding constant symbol +@code{Qmy_lisp_variable}. For example, when creating a buffer-local +variable (@pxref{Buffer-Local Variables}) in Lisp you would write: + +@smallexample +(make-variable-buffer-local 'my-lisp-variable) +@end smallexample + +In C the corresponding code uses @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. =20 @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: =20 @example staticpro (&@var{variable});