From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Karl Fogel Newsgroups: gmane.emacs.devel Subject: Re: [Emacs-diffs] emacs-26 9a53b6d: Say how to override a primitive interactive spec Date: Sun, 24 Jun 2018 22:47:18 -0500 Message-ID: <87y3f3a5o9.fsf@red-bean.com> References: <20180624121111.28772.8847@vcs0.savannah.gnu.org> <20180624121113.215CF206CC@vcs0.savannah.gnu.org> <83d0wgtfa3.fsf@gnu.org> <87lgb36dlc.fsf@red-bean.com> <83tvprsig4.fsf@gnu.org> Reply-To: Karl Fogel NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1529898330 18829 195.159.176.226 (25 Jun 2018 03:45:30 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 25 Jun 2018 03:45:30 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: monnier@IRO.UMontreal.CA, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jun 25 05:45:25 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fXIRQ-0004oq-Q7 for ged-emacs-devel@m.gmane.org; Mon, 25 Jun 2018 05:45:25 +0200 Original-Received: from localhost ([::1]:44092 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fXITX-0002Qi-Qj for ged-emacs-devel@m.gmane.org; Sun, 24 Jun 2018 23:47:35 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37279) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fXITK-0002QO-6v for emacs-devel@gnu.org; Sun, 24 Jun 2018 23:47:23 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fXITJ-0001ja-9c for emacs-devel@gnu.org; Sun, 24 Jun 2018 23:47:22 -0400 Original-Received: from mail-ot0-x22b.google.com ([2607:f8b0:4003:c0f::22b]:32832) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fXITJ-0001in-4C; Sun, 24 Jun 2018 23:47:21 -0400 Original-Received: by mail-ot0-x22b.google.com with SMTP id h6-v6so13568047otj.0; Sun, 24 Jun 2018 20:47:20 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:references:reply-to:date:message-id :user-agent:mime-version:content-transfer-encoding; bh=QE51Gu+c74fsyVOc2u2TA0CoMkqNhFh4LUp5gORTghQ=; b=V/TezGa7nRjdGzsvvLz4uOESITNns1jC7/9EIqKkxeSrcZ6zST4dLLOnyWhXcDhtoF S4u4zQFeqlQQJtRqDKoGzxCkTLWxYFNq96sQl0+Mtb0JUNwATvLh0Hpl2mc4TGGjkdVO 6N3UM0R/WMoRqny/CPRgwFPganQLLi5oj0HM10HKSLD5JU3zuz34+VmcN67TcQP2OmcB oB3iotYwfqbsA6LkLZyxg8POZjGa27F066ggsWyhWKwo+ZXH/Sgq16csUe1KkHqqjs1d fL3RMjAp1GL4T2Ga2YENkXzScAk/Kiu5iYsH8y/j3aECj52Nio4EN6N3e19bApoecJ2k Ab4g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:references:reply-to :date:message-id:user-agent:mime-version:content-transfer-encoding; bh=QE51Gu+c74fsyVOc2u2TA0CoMkqNhFh4LUp5gORTghQ=; b=Aoq6xujRvMoAk3ONDgRhVDgtLVo/Y/Qem1r/8zLLfQr0VWNxU+z6W7KecdhSJzFmrO IBhEckxQS93fqv0bt66IjZKGhbXtMafqgTsPorUN0yNlCxJif0QJ1YjA2ppe4ITg3Gwe LWJJDLViv1j2mZlsy3O/45aYbwsEE7cyPPL0YqaX9KjL1pJVrskqjHDedmJIyxre1cLR GzDj7Ke4pmEf5cyqhKhpMrJTBOmTeszZehfABLMkAohb1DxHwJXt+9VYNdOibl0ZXZ+L YXoQ+g9sZj/YBQKWQMnYrjNJI4I0rcJcW9oJNZd6aVHAqZtL8BMamlRtR0MF6zxClXQ+ Hi2w== X-Gm-Message-State: APt69E3XwIcEZG1YAUW0EDJ6hb5VVIAGm41KLJJuaT7kW14hDa+tb+5p 15dxSemb0OqU4H58AHnF4Qj7IQ== X-Google-Smtp-Source: AAOMgpdNoO0tLoDNdCGzE8PpaXSh/Vl6/G9DTs3+hDEXILOPdi09OybqSmYanQ2+7A8NiG42680JrA== X-Received: by 2002:a9d:4785:: with SMTP id b5-v6mr499132otf.158.1529898439988; Sun, 24 Jun 2018 20:47:19 -0700 (PDT) Original-Received: from floss ([2602:306:3707:da30:bccb:fed9:2216:e3f2]) by smtp.gmail.com with ESMTPSA id d67-v6sm6559339oia.46.2018.06.24.20.47.19 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 24 Jun 2018 20:47:19 -0700 (PDT) X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2607:f8b0:4003:c0f::22b X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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:226696 Archived-At: Eli Zaretskii writes: >No, I meant the former: your original addition. > >"Internals" is where the reader learns how to write Emacs primitives >and how some features work internally. It is a place where Lisp >programmers seldom if ever look for stuff that's important for writing >Lisp programs. Your text is for those Lisp programmers, so IMO it >doesn't belong where you put it. In your post [1] that I reference from the commit message, you seemed to ha= ve a different opinion (which is fine, of course -- one's opinion can chang= e). I'd stated my intention to document this potential use of `interactive= -form', there in "@item interactive" in doc/lispref/internals.texi, and you= r reply suggested doing it as a cross-reference. That's basically what my = change is, though with a sentence discussing the motivation for why one mig= ht want to. I took your reply as indicating agreement, or at the very leas= t non-objection, to an addition along these lines. Anyway, here's why I think the addition is useful: If someone who normally writes Emacs Lisp and hasn't had much exposure to t= he C code finds herself wanting to override the interactive form of a primi= tive function, there are several places she might go in the documentation, = depending on what research path she takes. In most of those places, we alr= eady document or refer to this technique, so no change is necessary for the= m. But she might say to herself "Aha, the function I'm overriding is a pri= mitive, so I'd better go look at how primitives are defined. Maybe that wi= ll teach me how to override a primitive's interactive spec, which I obvious= ly can't do by just editing and re-evaluating a Lisp `defun' the way one no= rmally would". In that case, she would end up in the place that I modified= , and the question she's interested in would now be addressed there (by fla= gging itself as her use case and then referring her to a more complete desc= ription in another part of the documentation). I see your point about how this part of the documentation is really focused= on how Emacs works internally, though. This is always a tricky issue in d= ocumentation: how much to keep to tight topic discipline versus how much to= anticipate potential use cases in a more directly utilitarian fashion (whi= ch inevitably means loosening the topic discipline). I welcome your thoughts, now that I've laid out the best argument I can abo= ve. One route might be to just put a "(@pxref{Using interactive})" at the = end of the sentence... This is an interactive specification, a string such as might be used as the argument of =E2=80=98interactive=E2=80=99 in a Lisp function. ...instead of my larger change, which I'd be happy to do; maybe that's the = kind of thing you had mind by "cross-reference" in the first place. Best regards, -Karl [1] https://lists.gnu.org/archive/html/emacs-devel/2018-03/msg00923.html