From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Native line numbers landed on master Date: Tue, 08 Oct 2019 15:23:57 +0300 Message-ID: <83blurxw6a.fsf@gnu.org> References: <834l4xbfmp.fsf@gnu.org> <87d0fgagjl.fsf@gnus.org> <20191001225254.mwjnxlynjdc3mz7y@Ergus> <83lfu389vn.fsf@gnu.org> <87ftk9v4kx.fsf@wavexx.thregr.org> <83wodl54yt.fsf@gnu.org> <87pnjchm7p.fsf@wavexx.thregr.org> <83pnj8zff9.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="246937"; mail-complaints-to="usenet@blaine.gmane.org" Cc: spacibba@aol.com, lekktu@gmail.com, stefan@marxist.se, emacs-devel@gnu.org, wavexx@thregr.org, larsi@gnus.org To: Robert Pluim Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Oct 08 14:24:52 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 1iHoXs-001230-38 for ged-emacs-devel@m.gmane.org; Tue, 08 Oct 2019 14:24:52 +0200 Original-Received: from localhost ([::1]:54786 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iHoXq-0003pJ-Gm for ged-emacs-devel@m.gmane.org; Tue, 08 Oct 2019 08:24:50 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:57316) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iHoXH-0003nm-Vp for emacs-devel@gnu.org; Tue, 08 Oct 2019 08:24:17 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:41458) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1iHoXE-00076L-7u; Tue, 08 Oct 2019 08:24:12 -0400 Original-Received: from [176.228.60.248] (port=4154 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1iHoXC-0000K9-Ua; Tue, 08 Oct 2019 08:24:11 -0400 In-reply-to: (message from Robert Pluim on Tue, 08 Oct 2019 13:15:46 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] 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:240745 Archived-At: > From: Robert Pluim > Cc: lekktu@gmail.com, wavexx@thregr.org, stefan@marxist.se, > larsi@gnus.org, spacibba@aol.com, emacs-devel@gnu.org > 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.