From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 02 Jul 2019 18:06:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 36478@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.15620907471168 (code B ref -1); Tue, 02 Jul 2019 18:06:02 +0000 Received: (at submit) by debbugs.gnu.org; 2 Jul 2019 18:05:47 +0000 Received: from localhost ([127.0.0.1]:47902 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiNA3-0000Im-Dg for submit@debbugs.gnu.org; Tue, 02 Jul 2019 14:05:47 -0400 Received: from lists.gnu.org ([209.51.188.17]:50889) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiNA1-0000Ic-3A for submit@debbugs.gnu.org; Tue, 02 Jul 2019 14:05:45 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:49792) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1hiN9u-0003uG-8t for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:05:41 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-1.5 required=5.0 tests=BAYES_50,RCVD_IN_DNSWL_MED autolearn=disabled version=3.3.2 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1hiN9p-000789-Un for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:05:38 -0400 Received: from userp2120.oracle.com ([156.151.31.85]:34674) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1hiN9o-0006xK-8z for bug-gnu-emacs@gnu.org; Tue, 02 Jul 2019 14:05:32 -0400 Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x62I3xFL012300 for ; Tue, 2 Jul 2019 18:05:21 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=JUNhW9L0pkTXpJ6AkDZ+/DPTw+dxn3K8iLcme7eZBCc=; b=RoXpSnXgduEL0pLqTUYKo3Q+BOjxlh46mVDG7jDsWK8SkGuYl+4UBx6aP9jih7d2tSze HeDXqQ9yqq6GKW+QTrGUeK4ZDPyO+PMnpZ5vSsI3ew9Uoo1ggOno+zYAfBdFHVse3sL+ ZwHJTWFF4mAYRFyu5Smcbh0R8ONKeej70NYnpJzij2Sr2u/AN4yQ5czAjkIjiqrQUt0C NUSw+/CfqqWXcMs6uvdYdroLjegZ9pD5/NGfBsnTlVuIbdJxaCdf8tnOn/t2b/i9vi12 tihJQcG1nBFt8C1faDE9R0NhD44ywBCiom2bHfZI9g0817LhAd3tlMbVDsE4CFYa0+eI /A== Received: from aserp3020.oracle.com (aserp3020.oracle.com [141.146.126.70]) by userp2120.oracle.com with ESMTP id 2te61pw87r-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Tue, 02 Jul 2019 18:05:21 +0000 Received: from pps.filterd (aserp3020.oracle.com [127.0.0.1]) by aserp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x62I39VS088672 for ; Tue, 2 Jul 2019 18:05:20 GMT Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserp3020.oracle.com with ESMTP id 2tebkudq2k-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Tue, 02 Jul 2019 18:05:20 +0000 Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x62I5JOS020075 for ; Tue, 2 Jul 2019 18:05:19 GMT MIME-Version: 1.0 Message-ID: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> Date: Tue, 2 Jul 2019 11:05:18 -0700 (PDT) From: Drew Adams X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4861.0 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9306 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907020199 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9306 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907020199 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] X-Received-From: 156.151.31.85 X-Spam-Score: -1.3 (-) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.3 (--) `C-h f zerop' tells you this: zerop is a compiled Lisp function in 'subr.el'. (zerop NUMBER) This function has a compiler macro 'zerop--anon-cmacro'. Return t if NUMBER is zero. This function does not change global state, including the match data. Why on earth would we put that info about the function having a compiler macro before the first doc string line? What does it even mean? Searching for "compiler macro" in the Elisp manual I find mention of it (in passing only) in node `Defining Functions', but no definition of it. And there's no index entry for it, AFAICT. Reading that node, I still don't know what "compiler macro" really means. Perhaps it means code that inlines a function definition at byte-compilation time? That whole node `Defining Functions' is pretty much incomprehensible now, with the additions about ...inline.... Compare node `Inline Functions', which is quite clear. For example: Functions defined via 'define-inline' have several advantages with respect to macros defined by 'defsubst' or 'defmacro'... Huh? `defsubst' defines macros? I don't think so. I think a node should probably be dedicated to `define-inline' or to whatever it does. The concepts really need to be developed. Putting this, whatever it is, in with `defun' in the main node about defining functions does users, especially newbies, a disservice. The help for a function (e.g. `zerop') should, after showing the signature, start with the doc string, which says what the function does. The help should not start by providing peripheral info about the function. Putting this info first doesn't follow Emacs longstanding help convention. Not to mention that if you click that `zerop--anon-cmacro' link you get this: zerop--anon-cmacro is a compiled Lisp function in 'subr.el'. (zerop--anon-cmacro _ NUMBER) Not documented. What's more: if you click the `subr.el' link you get nowhere that tells you anything about `zerop--anon-cmacro' - there are no occurrences of `zerop--anon-cmacro' in that file. Wunderbar. Thanks for the help, Emacs! This is a real mess - doesn't help users. Instead, it gets in their way. Please DTRT. Either get rid of such obscurantism or put it at the end of the `C-h f' output and fix its useless links. --- In addition, why do we automatically add the following sentence to the help (without even an intervening blank line), as if it were the second doc-string line: This function does not change global state, including the match data. Who asked for that? Which functions get that added to their doc strings? Every function for which that's true? I doubt that, and if I'm right then the fact that some functions do get that added is misleading. In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32) of 2019-04-13 Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749 Windowing system distributor `Microsoft Corp.', version 10.0.17134 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install 'CFLAGS=3D-O2 -static -g3'' From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 02 Jul 2019 19:42:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Drew Adams Cc: 36478@debbugs.gnu.org Received: via spool by 36478-submit@debbugs.gnu.org id=B36478.156209650026538 (code B ref 36478); Tue, 02 Jul 2019 19:42:01 +0000 Received: (at 36478) by debbugs.gnu.org; 2 Jul 2019 19:41:40 +0000 Received: from localhost ([127.0.0.1]:47985 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiOen-0006tt-37 for submit@debbugs.gnu.org; Tue, 02 Jul 2019 15:41:39 -0400 Received: from eggs.gnu.org ([209.51.188.92]:58260) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiOei-0006te-G0 for 36478@debbugs.gnu.org; Tue, 02 Jul 2019 15:41:34 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:54644) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hiOeZ-0003jN-J2; Tue, 02 Jul 2019 15:41:24 -0400 Received: from [176.228.60.248] (port=3719 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1hiOeY-0006wG-BL; Tue, 02 Jul 2019 15:41:23 -0400 Date: Tue, 02 Jul 2019 22:41:07 +0300 Message-Id: <83r278cjho.fsf@gnu.org> From: Eli Zaretskii In-reply-to: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> (message from Drew Adams on Tue, 2 Jul 2019 11:05:18 -0700 (PDT)) References: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > Date: Tue, 2 Jul 2019 11:05:18 -0700 (PDT) > From: Drew Adams > > `C-h f zerop' tells you this: > > zerop is a compiled Lisp function in 'subr.el'. > > (zerop NUMBER) > > This function has a compiler macro 'zerop--anon-cmacro'. > > Return t if NUMBER is zero. > This function does not change global state, including the match data. > > Why on earth would we put that info about the function having a compiler > macro before the first doc string line? The parts that got you so worked up are generated automatically. From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 02 Jul 2019 20:14:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Eli Zaretskii , Drew Adams Cc: 36478@debbugs.gnu.org Received: via spool by 36478-submit@debbugs.gnu.org id=B36478.156209843729501 (code B ref 36478); Tue, 02 Jul 2019 20:14:02 +0000 Received: (at 36478) by debbugs.gnu.org; 2 Jul 2019 20:13:57 +0000 Received: from localhost ([127.0.0.1]:48012 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiPA5-0007fl-60 for submit@debbugs.gnu.org; Tue, 02 Jul 2019 16:13:57 -0400 Received: from userp2120.oracle.com ([156.151.31.85]:32790) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiPA3-0007fY-59 for 36478@debbugs.gnu.org; Tue, 02 Jul 2019 16:13:55 -0400 Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x62KDn9S112077; Tue, 2 Jul 2019 20:13:49 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=jAsHC8mWAjdNTTgZZlA9xc3T03Of0Q07UTXNIlCbosU=; b=hPTtvXhPgJVMCsr/GPpDUFmSEW/B+x9z4IIHyzfiUy3SD91dezL2SGPtfwlouxpoveOG weCUpf7FoslNgDkrorUNsreG2eZntpWiSFV2n9hxdHIoHS2Oigkr2zAHMYg8q59g76GP k/kzxK86NAirURKL+AZV3+sYND1NGor/91I5LA42DI/OEmzO5gjvYT0J9XuOQhsSZ13E 4EvKt88nkEZCM7s5xIznudY7t3HFTrHHEUvG8CojTWfcLUht3+yyTGMBHt/lRn/7Ih8N bjtNxK0UQS26d7SqfPFE+6N/pYbvJla6VWnlWSbho4m+vNzRh+dPnWjiDhmjt1+ihjAh sA== Received: from userp3020.oracle.com (userp3020.oracle.com [156.151.31.79]) by userp2120.oracle.com with ESMTP id 2te61pwrqj-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 02 Jul 2019 20:13:48 +0000 Received: from pps.filterd (userp3020.oracle.com [127.0.0.1]) by userp3020.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x62KD8iU031876; Tue, 2 Jul 2019 20:13:44 GMT Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userp3020.oracle.com with ESMTP id 2tebbjyns8-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Tue, 02 Jul 2019 20:13:44 +0000 Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x62KDghg030096; Tue, 2 Jul 2019 20:13:43 GMT MIME-Version: 1.0 Message-ID: <21500c6e-9743-40ce-89d8-d63c9351e8c0@default> Date: Tue, 2 Jul 2019 13:13:40 -0700 (PDT) From: Drew Adams References: <<13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default>> <<83r278cjho.fsf@gnu.org>> In-Reply-To: <<83r278cjho.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4861.0 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9306 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907020225 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9306 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1011 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907020225 X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > > Why on earth would we put that info about the function having a compile= r > > macro before the first doc string line? >=20 > The parts that got you so worked up are generated automatically. Yes, obviously; I realize that. "We" (someone) created and added the code that does that. And "we" (someone) added the descriptions of `define-inline' etc. to the manual. However "automatic", none of this fell from the sky. From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Resent-From: Richard Stallman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 04 Jul 2019 01:35:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Drew Adams Cc: 36478@debbugs.gnu.org Reply-To: rms@gnu.org Received: via spool by 36478-submit@debbugs.gnu.org id=B36478.156220406232007 (code B ref 36478); Thu, 04 Jul 2019 01:35:02 +0000 Received: (at 36478) by debbugs.gnu.org; 4 Jul 2019 01:34:22 +0000 Received: from localhost ([127.0.0.1]:50201 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiqdg-0008K8-3Z for submit@debbugs.gnu.org; Wed, 03 Jul 2019 21:34:22 -0400 Received: from eggs.gnu.org ([209.51.188.92]:58373) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiqde-0008Jw-5J for 36478@debbugs.gnu.org; Wed, 03 Jul 2019 21:34:18 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:49591) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hiqdY-0007DN-Pw; Wed, 03 Jul 2019 21:34:12 -0400 Received: from rms by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1hiqdX-00065N-Tz; Wed, 03 Jul 2019 21:34:12 -0400 Content-Type: text/plain; charset=Utf-8 From: Richard Stallman In-Reply-To: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> (message from Drew Adams on Tue, 2 Jul 2019 11:05:18 -0700 (PDT)) References: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> Message-Id: Date: Wed, 03 Jul 2019 21:34:11 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > zerop is a compiled Lisp function in 'subr.el'. > (zerop NUMBER) > This function has a compiler macro 'zerop--anon-cmacro'. > Return t if NUMBER is zero. > This function does not change global state, including the match data. The "compiler macro" line is useful for people debugging compilation, but for Lisp programmers in general it is only clutter. How about replacing that line with the text "(+ compiler macro)" after "compiled Lisp function"? That way it will still be easy to see when you're debugging compilation, but the amount of clutter for everyone else will be less. -- Dr Richard Stallman President, Free Software Foundation (https://gnu.org, https://fsf.org) Internet Hall-of-Famer (https://internethalloffame.org) From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Resent-From: Richard Stallman Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 04 Jul 2019 01:36:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Drew Adams Cc: eliz@gnu.org, 36478@debbugs.gnu.org, drew.adams@oracle.com Reply-To: rms@gnu.org Received: via spool by 36478-submit@debbugs.gnu.org id=B36478.156220413332127 (code B ref 36478); Thu, 04 Jul 2019 01:36:01 +0000 Received: (at 36478) by debbugs.gnu.org; 4 Jul 2019 01:35:33 +0000 Received: from localhost ([127.0.0.1]:50206 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiqer-0008M6-B8 for submit@debbugs.gnu.org; Wed, 03 Jul 2019 21:35:33 -0400 Received: from eggs.gnu.org ([209.51.188.92]:58499) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hiqep-0008Lu-P7 for 36478@debbugs.gnu.org; Wed, 03 Jul 2019 21:35:32 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:49614) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1hiqef-0008Ra-1m; Wed, 03 Jul 2019 21:35:23 -0400 Received: from rms by fencepost.gnu.org with local (Exim 4.82) (envelope-from ) id 1hiqea-0006HP-Vj; Wed, 03 Jul 2019 21:35:17 -0400 Content-Type: text/plain; charset=Utf-8 From: Richard Stallman In-Reply-To: <21500c6e-9743-40ce-89d8-d63c9351e8c0@default> (message from Drew Adams on Tue, 2 Jul 2019 13:13:40 -0700 (PDT)) References: <<13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default>> <<83r278cjho.fsf@gnu.org>> <21500c6e-9743-40ce-89d8-d63c9351e8c0@default> Message-Id: Date: Wed, 03 Jul 2019 21:35:16 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) [[[ To any NSA and FBI agents reading my email: please consider ]]] [[[ whether defending the US Constitution against all enemies, ]]] [[[ foreign or domestic, requires you to follow Snowden's example. ]]] > Yes, obviously; I realize that. "We" (someone) > created and added the code that does that. And "we" > (someone) added the descriptions of `define-inline' > etc. to the manual. However "automatic", none of > this fell from the sky. I agree with your point, but that is a harsh way to put it. Would you please make an effort to express your points in a kind way? See https://gnu.org/philosophy/kind-communication.html. In addition to helping people generally feel better, it could predispose others to be more receptive to your substantial points. -- Dr Richard Stallman President, Free Software Foundation (https://gnu.org, https://fsf.org) Internet Hall-of-Famer (https://internethalloffame.org) From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: Perhaps rearrange *Help* buffer a bit? Resent-From: Stefan Monnier Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 08 Jul 2019 21:15:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Lars Ingebrigtsen Cc: bug#36478 <36478@debbugs.gnu.org> Received: via spool by 36478-submit@debbugs.gnu.org id=B36478.156262045516141 (code B ref 36478); Mon, 08 Jul 2019 21:15:01 +0000 Received: (at 36478) by debbugs.gnu.org; 8 Jul 2019 21:14:15 +0000 Received: from localhost ([127.0.0.1]:59729 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkaxj-0004CH-31 for submit@debbugs.gnu.org; Mon, 08 Jul 2019 17:14:15 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:35054) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkaxh-0004C4-EX for 36478@debbugs.gnu.org; Mon, 08 Jul 2019 17:14:13 -0400 Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id E92B01008C2; Mon, 8 Jul 2019 17:14:07 -0400 (EDT) Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 952A8100737; Mon, 8 Jul 2019 17:14:06 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1562620446; bh=XDeNcq0VVGIAcySBKUYAlCvo7eunXsW6x1nfh3gUjow=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=DMKLDxCdIfhov+VKoT42MxTQLi8K2rMyl1vPADxZvfVbXCcxQDwLlUT0Mz8venBjP D2I3Y8q5WnwL/EJmBCl4d9SG5uJLJWl1vVjVOXIe0IjZshWsNDxPsQZ9gxF0rF+zIQ 29WYhE3bMJF1cbwaCjzWEa3vT7AaxMn8fd5thS/Bhduk/cbalqUeBOwzR0kgx9RQ7k +hsNb3mVUGNESJNyLarbCjznWChtE6ns7wZVc5Kr89sfft9gdYa+716SfURvNOQgGa i1aq/qCqZPtpAUXtYT93SCUwOeRY/j/PmvSrq4U9WBZbmt8uywRMwo3wjrysgkXyjt QjNe0JNwlR6IQ== Received: from alfajor (76-10-138-228.dsl.teksavvy.com [76.10.138.228]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 638B7120C0A; Mon, 8 Jul 2019 17:14:06 -0400 (EDT) From: Stefan Monnier Message-ID: References: Date: Mon, 08 Jul 2019 17:14:05 -0400 In-Reply-To: (Lars Ingebrigtsen's message of "Mon, 08 Jul 2019 22:18:58 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-SPAM-INFO: Spam detection results: 0 ALL_TRUSTED -1 Passed through trusted hosts only via SMTP AWL 0.111 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain X-SPAM-LEVEL: X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) > I think Drew (or somebody?) mentioned this in a bug report the other > day: The way the automated stuff is arranged in the *Help* buffer is > perhaps not optimal. > This function has a compiler macro =E2=80=98internal--compiler-macro-cX= Xr=E2=80=99. > Probably introduced at or before Emacs version 20. [...] > Probably introduced at or before Emacs version 1.2. > This function does not change global state, including the match data. [...] > So the thought here is that those indented lines isn't what's most > interesting to the user. I recently reworked the generation of this text specifically to try and make it easier to tweak it. > Anyway, what about rearranging this a bit so that the stuff the users > are interested in comes first? [...] > Let the bike-shedding commence! Here's my favorite color:=20 - don't move it to the end, because it's much too far. - hide it by default, with some obvious-enough button-like thingy to expand it on demand. - maybe the first line could also be moved into this "metadata" block. - These *Help* buffers would benefit from a bit of face-lift (e.g. put a different face on the metadata part, yet another on the calling-convention example, ...). Stefan From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: Perhaps rearrange *Help* buffer a bit? Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 08 Jul 2019 22:27:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Stefan Monnier Cc: bug#36478 <36478@debbugs.gnu.org> Received: via spool by 36478-submit@debbugs.gnu.org id=B36478.156262479623634 (code B ref 36478); Mon, 08 Jul 2019 22:27:02 +0000 Received: (at 36478) by debbugs.gnu.org; 8 Jul 2019 22:26:36 +0000 Received: from localhost ([127.0.0.1]:59854 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkc5k-000698-9T for submit@debbugs.gnu.org; Mon, 08 Jul 2019 18:26:36 -0400 Received: from quimby.gnus.org ([80.91.231.51]:34690) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkc5j-00068z-2A for 36478@debbugs.gnu.org; Mon, 08 Jul 2019 18:26:35 -0400 Received: from cm-84.212.202.86.getinternet.no ([84.212.202.86] helo=stories) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1hkc5d-0005mB-IV; Tue, 09 Jul 2019 00:26:32 +0200 From: Lars Ingebrigtsen References: Face: iVBORw0KGgoAAAANSUhEUgAAADAAAAAwBAMAAAClLOS0AAAAFVBMVEXw4sqykINZDASXcGD+ /OtyPB/SuK5HtkdZAAACfElEQVQ4jXWTsXLbMAyG4ZrVLEaq5oY5d7ZKyTN5wXFOlCgzWat4/0fo D8pxlxZ3uVD8APwAAVO00Q+ZmmLtsvHBW5FshsNGJTYi0gH+chc7SiZq8sY9bSngerTZPLhHhBIV n/vQE3OaEZ+p/HQvBu6dtdvlakgkjlYaa+2De4G7hYiJAwMkEeu9zV/ci9jB5qb0FoBDEEgg+283 iNRcW4tUjUWJNpPgj4MJxQ+y9Wmj4Zwg3XTjxjBoSRbTh40u5yBNQV16z0W0174tSNVRgUTJFQQE db63mWm8RH0G2cxOUK81LVKZmGxGwb0CaA+SszlElJsIlVsxCiigDmjEC9N2DI0dpAEIcCMS9MET 01XLRRc30CCXGAUck+TSWVaQWJ+TDPcK4A4vVo3EotPZ4siUS7Kd9ziZQAf+tr6t63REHaWNfvZv r0EjIs+L9+sUkUq647rO62vIFSAYgIUptc8r7KPBLPmZZ2SdJylMlxArSLdU8zr4KW1M1h7/RkSa 9WNqk6HRV7A+BQUOJ2gMANxUsDzp2z47rXadus6QPVfx5VFBPNXoaTgYaveq1h+aKq07yNFgfMfF wfEDLwSNau9GNcKxfnzXt0s3ENC5PXz9BHwH6Vw7rx9nTRVQhYJnbGIZjjcAAlAjDhajpBpxanGi gICTW94FK5pu4hWQgtW952Aoph3kCua9j4JUh+ZaFes9/VwXBYK9Emy7mv4Q5B5xZfK+VDA737mx Hv2ETaZo4v5Aznu332OCWIZktNwTZMDWz0dkneDVnXDrXGW1wUm3SadzWrSu2sMeMfEOdlPvG8DG 6jLcwWfI1NaI6O827//6iyj4h0n+D4D9AehP82BHjrQVAAAAAElFTkSuQmCC Date: Tue, 09 Jul 2019 00:26:29 +0200 In-Reply-To: (Stefan Monnier's message of "Mon, 08 Jul 2019 17:14:05 -0400") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Stefan Monnier writes: > Here's my favorite color: > - don't move it to the end, because it's much too far. > - hide it by default, with some obvious-enough button-like thingy to > expand it on demand. > - maybe the first l [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) Stefan Monnier writes: > Here's my favorite color:=20 > - don't move it to the end, because it's much too far. > - hide it by default, with some obvious-enough button-like thingy to > expand it on demand. > - maybe the first line could also be moved into this "metadata" block. A button that says "Technical details..." or something? Or... a text-less button would perhaps be better. To take the `car' example again: --- (car LIST) ... Return the car of LIST. If arg is nil, return nil. Error if arg is not nil and not a cons cell. See also =E2=80=98car-safe=E2= =80=99. See Info node =E2=80=98(elisp)Cons Cells=E2=80=99 for a discussion of relat= ed basic Lisp concepts such as car, cdr, cons cell and list. --- The "..." after the function call signature could be marked in the link face, and could expand into: --- car is a built-in function in =E2=80=98C source code=E2=80=99. Probably introduced at or before Emacs version 1.2. This function does not change global state, including the match data. --- And `car' in the signature could be a link to the source code, as the "C source code" is now, so you don't have to expand the details to get to the link. > - These *Help* buffers would benefit from a bit of face-lift (e.g. put > a different face on the metadata part, yet another on the > calling-convention example, ...). The parameters are in an italic face... If we're hiding the details, perhaps a special face for the details isn't necessary? --=20 (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: Perhaps rearrange *Help* buffer a bit? Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 08 Jul 2019 23:23:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Lars Ingebrigtsen , Stefan Monnier Cc: bug#36478 <36478@debbugs.gnu.org> Received: via spool by 36478-submit@debbugs.gnu.org id=B36478.156262812713190 (code B ref 36478); Mon, 08 Jul 2019 23:23:02 +0000 Received: (at 36478) by debbugs.gnu.org; 8 Jul 2019 23:22:07 +0000 Received: from localhost ([127.0.0.1]:59947 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkcxT-0003Qg-Bi for submit@debbugs.gnu.org; Mon, 08 Jul 2019 19:22:07 -0400 Received: from userp2120.oracle.com ([156.151.31.85]:43966) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkcxR-0003QB-3V for 36478@debbugs.gnu.org; Mon, 08 Jul 2019 19:22:06 -0400 Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x68NJBUX046937; Mon, 8 Jul 2019 23:21:59 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2018-07-02; bh=XeAin84uHLeRL+2gI/Pk+b4XHSG6oNYdulHXq1Ye+yI=; b=TWihzabEUUNsk60QMR8mszM35XDNOpyiuOTIhT1I3zkPaqFkZEGGET6gJy0Ciu/Jx8Of gt00WCetsmPslm4vRz1kontBKREwemPOSI5pcO8nQGyhGuhPB/hhHdsaok/gxga+3os/ iieRS0oSq6xWyl92CdRJ853QgyzZhoAKMcVeZY0Q1gEDyafyl2Tgi6yyk2tJh6jIWtig uDY1dNRR3lghmhAPNvfKT0fISk4cbE74RGFRFfLUt/dAsX3EDyME7LXOxY+jaZa89l9f pdX7UWOzDf24ZJZMahIUuBqCbVnWlfu2B3XlmlUS+pJLIGUGAqj3JQmDBDKUMLgQXc1G bw== Received: from aserp3030.oracle.com (aserp3030.oracle.com [141.146.126.71]) by userp2120.oracle.com with ESMTP id 2tjm9qh2hj-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 08 Jul 2019 23:21:58 +0000 Received: from pps.filterd (aserp3030.oracle.com [127.0.0.1]) by aserp3030.oracle.com (8.16.0.27/8.16.0.27) with SMTP id x68NIGD0086501; Mon, 8 Jul 2019 23:21:58 GMT Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by aserp3030.oracle.com with ESMTP id 2tjhpcrfc6-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 08 Jul 2019 23:21:58 +0000 Received: from abhmp0018.oracle.com (abhmp0018.oracle.com [141.146.116.24]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id x68NLrVg016751; Mon, 8 Jul 2019 23:21:54 GMT MIME-Version: 1.0 Message-ID: <3c3e15e3-ab92-430a-ba21-adb6224cbb55@default> Date: Mon, 8 Jul 2019 16:21:52 -0700 (PDT) From: Drew Adams References: In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4861.0 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9312 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907080286 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9312 signatures=668688 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 priorityscore=1501 malwarescore=0 suspectscore=0 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1907080287 X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) > > Here's my favorite color: > > - don't move it to the end, because it's much too far. > > - hide it by default, with some obvious-enough button-like thingy to > > expand it on demand. > > - maybe the first line could also be moved into this "metadata" block. >=20 > A button that says "Technical details..." or something? Or... a > text-less button would perhaps be better. FWIW, I think I disagree with handling all such "metadata" equally, e.g. hiding it all by default. To me, it makes sense to show, without fishing, that a function is autoloaded (e.g. not yet loaded), compiled, etc.; and to show its definition location, with a link to it; and to show a link to its advice - especially if the advice changes the doc (which is what the help is mainly for); and to show a variable's value. Such things are helpful for most users, I think, and they're not in the way. Such things are not so concerned with "our" implementation details as they are with the definition - what the thing is/does. This is a bit like using `C-u C-x =3D'. Both kinds of help can and do show lots of information. And it's not good to overwhelm users at the outset with too much info, especially in a not-very-organized way. But I think that for `*Help*' the info we've long shown is pretty much user-oriented. It's more a question of organization. I objected, in bug #36478, to sticking the following kind of info near the top, before even the first line of the doc string: This function has a compiler macro 'zerop--anon-cmacro'. Dunno how useful that info is, but a priori that's not the place to stick it, IMO. =20 Many users (I'm one) have no clue what a "compiler macro" is or why they should care. (And it's not explained in the manual, which is a big part of what bug bu#36478g is about.) But if that info is actually useful for users (I'm ignorant, so can't judge that) and if it were put at or near the end of `*Help*' (and if "compiler macro" got documented, and especially if those words linked to the place in the manual where that's documented), then I'd have no problem with it. From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: Perhaps rearrange *Help* buffer a bit? Resent-From: Stefan Monnier Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 08 Jul 2019 23:31:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Lars Ingebrigtsen Cc: bug#36478 <36478@debbugs.gnu.org> Received: via spool by 36478-submit@debbugs.gnu.org id=B36478.156262863215853 (code B ref 36478); Mon, 08 Jul 2019 23:31:02 +0000 Received: (at 36478) by debbugs.gnu.org; 8 Jul 2019 23:30:32 +0000 Received: from localhost ([127.0.0.1]:59973 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkd5b-00047K-NI for submit@debbugs.gnu.org; Mon, 08 Jul 2019 19:30:32 -0400 Received: from mailscanner.iro.umontreal.ca ([132.204.25.50]:10402) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1hkd5a-00040T-8S for 36478@debbugs.gnu.org; Mon, 08 Jul 2019 19:30:30 -0400 Received: from pmg1.iro.umontreal.ca (localhost.localdomain [127.0.0.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id A629F100737; Mon, 8 Jul 2019 19:30:24 -0400 (EDT) Received: from mail01.iro.umontreal.ca (unknown [172.31.2.1]) by pmg1.iro.umontreal.ca (Proxmox) with ESMTP id 2C69810067D; Mon, 8 Jul 2019 19:30:23 -0400 (EDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=iro.umontreal.ca; s=mail; t=1562628623; bh=gnKbVu51wG2psFSSlHiGOIzR1M29tqii12zCXEoW98U=; h=From:To:Cc:Subject:References:Date:In-Reply-To:From; b=HeKHTbGqSjcGlPmMHrvgZbLMjhUu0j9wK5oX3NMR2rlEhg4TwYYo2cxY++uJ0jq8R Gm7WA5QoaH7lVEDyYX1RvfAc4tyPo97eBR5bAJdqssGHqJiqJ1r6qUFApvQKIg6YEc 2IGBOXQjeMcUm6n7C46Ula1hMtYNBkzAJp6e9PG+WCV94AUH13rPSzzDbB0KjU/81l g+871Epmi0NDV/rjVkL7x6Y1kH1einxvSfhM6dxrt+8thPWtKbKR6hgXAfcEx2QTuk kxG8oo1ipdfzCyJec/mlTKLrsAiC7mD1QusMtpNIEvNoPUxQ+sNuHUZxtTH+zj0hgu 6ezhQgHN8ZnUw== Received: from alfajor (76-10-138-228.dsl.teksavvy.com [76.10.138.228]) by mail01.iro.umontreal.ca (Postfix) with ESMTPSA id 99FF1120152; Mon, 8 Jul 2019 19:30:22 -0400 (EDT) From: Stefan Monnier Message-ID: References: Date: Mon, 08 Jul 2019 19:30:21 -0400 In-Reply-To: (Lars Ingebrigtsen's message of "Tue, 09 Jul 2019 00:26:29 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-SPAM-INFO: Spam detection results: 0 ALL_TRUSTED -1 Passed through trusted hosts only via SMTP AWL 0.110 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DKIM_SIGNED 0.1 Message has a DKIM or DK signature, not necessarily valid DKIM_VALID -0.1 Message has at least one valid DKIM or DK signature DKIM_VALID_AU -0.1 Message has a valid DKIM or DK signature from author's domain X-SPAM-LEVEL: X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) > To take the `car' example again: > > --- > (car LIST) ... > > Return the car of LIST. If arg is nil, return nil. > Error if arg is not nil and not a cons cell. See also =E2=80=98car-safe= =E2=80=99. > > See Info node =E2=80=98(elisp)Cons Cells=E2=80=99 for a discussion of rel= ated basic > Lisp concepts such as car, cdr, cons cell and list. > --- Sounds about right, yes. I think I'd vote to keep the function/macro distinction displayed by default at least (and maybe function/command as well). Maybe simply as Function: (car LIST) ... =20=20=20=20 Return the car of LIST. If arg is nil, return nil. Error if arg is not nil and not a cons cell. See also =E2=80=98car-saf= e=E2=80=99. =20=20=20=20 See Info node =E2=80=98(elisp)Cons Cells=E2=80=99 for a discussion of r= elated basic Lisp concepts such as car, cdr, cons cell and list. > And `car' in the signature could be a link to the source code, as the > "C source code" is now, so you don't have to expand the details to get > to the link. Sounds good. >> - These *Help* buffers would benefit from a bit of face-lift (e.g. put >> a different face on the metadata part, yet another on the >> calling-convention example, ...). > The parameters are in an italic face... If we're hiding the details, > perhaps a special face for the details isn't necessary? Maybe you're right. Then again, I think it's worth keeping the block highlighted somehow to clearly indicate the difference between the docstring and the auto-generated metadata, maybe with a discreet background color. Stefan From unknown Fri Jun 13 11:20:56 2025 X-Loop: help-debbugs@gnu.org Subject: bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 02 Feb 2022 18:56:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 36478 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Drew Adams Cc: 36478@debbugs.gnu.org Received: via spool by 36478-submit@debbugs.gnu.org id=B36478.1643828160371 (code B ref 36478); Wed, 02 Feb 2022 18:56:02 +0000 Received: (at 36478) by debbugs.gnu.org; 2 Feb 2022 18:56:00 +0000 Received: from localhost ([127.0.0.1]:53595 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nFKnP-00005v-Sg for submit@debbugs.gnu.org; Wed, 02 Feb 2022 13:56:00 -0500 Received: from quimby.gnus.org ([95.216.78.240]:42892) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nFKnO-00005b-A6 for 36478@debbugs.gnu.org; Wed, 02 Feb 2022 13:55:58 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Content-Type:MIME-Version:Message-ID:In-Reply-To:Date: References:Subject:Cc:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=JKrq34yVGzBtS7Zmm7Bs6usUC1aLaiQKIIPrDFPshdQ=; b=ZeXWjAmlr1DY5VHysGquKLj4Ah bLiE/cIoMmQgp4HdUvWRskpfzwCf3Q63SnElS79+TH71XnJtC0A1+A1kf0fkLdOW7EIGI8fAr+Mbu aWGMyHcSaCxB1tBSVCdb5iwD+oTR+mp4Y3TWWzQeUkm4v77mrTeh6aSwaJVoOy72+WxA=; Received: from [84.212.220.105] (helo=giant) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nFKnD-00079O-O7; Wed, 02 Feb 2022 19:55:50 +0100 From: Lars Ingebrigtsen References: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> X-Now-Playing: Brian Eno, Jah Wobble's _Spinner_: "Steam" Date: Wed, 02 Feb 2022 19:55:47 +0100 In-Reply-To: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> (Drew Adams's message of "Tue, 2 Jul 2019 11:05:18 -0700 (PDT)") Message-ID: <87o83pp07g.fsf@gnus.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: Drew Adams writes: > `C-h f zerop' tells you this: > > zerop is a compiled Lisp function in 'subr.el'. > > (zerop NUMBER) > > This function has a compiler macro 'zerop--anon-cmacro'. > > Return t if NUMBER is zero. > Th [...] Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) Drew Adams writes: > `C-h f zerop' tells you this: > > zerop is a compiled Lisp function in 'subr.el'. > > (zerop NUMBER) > > This function has a compiler macro 'zerop--anon-cmacro'. > > Return t if NUMBER is zero. > This function does not change global state, including the match data. > > Why on earth would we put that info about the function having a compiler > macro before the first doc string line? In Emacs 29 these details have been moved to the end of the help buffer. I've now also added some indexing to the manual so that it's easier to find out what a "compiler macro" is. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no From debbugs-submit-bounces@debbugs.gnu.org Wed Feb 02 13:56:12 2022 Received: (at control) by debbugs.gnu.org; 2 Feb 2022 18:56:12 +0000 Received: from localhost ([127.0.0.1]:53599 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nFKnc-00006j-3H for submit@debbugs.gnu.org; Wed, 02 Feb 2022 13:56:12 -0500 Received: from quimby.gnus.org ([95.216.78.240]:42906) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nFKnR-00005k-S0 for control@debbugs.gnu.org; Wed, 02 Feb 2022 13:56:10 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnus.org; s=20200322; h=Subject:From:To:Message-Id:Date:Sender:Reply-To:Cc: MIME-Version:Content-Type:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=oYvei6hAZ5f7Pf5k/rLwvZMIGSm/TM5bqN4rOnEPeoE=; b=mERS5Bi7GKX7gEkgkvNm6yXZ36 mFSAdIFGjpIx2vkMeZ4QR+M7X4cNLTZbVZ3hOk5nq9fUCtBBkfKG1N6hRzBhHVz3aIv/CykI3EYA0 x4fIYKKBP5ftwO4tsQbt/mXFoPtkXxSPbSLYo+mYiEyVSMldbeUlf1FD5sdcL4qnT+Yc=; Received: from [84.212.220.105] (helo=giant) by quimby.gnus.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nFKnJ-00079Y-BY for control@debbugs.gnu.org; Wed, 02 Feb 2022 19:55:55 +0100 Date: Wed, 02 Feb 2022 19:55:52 +0100 Message-Id: <87mtj9p07b.fsf@gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #36478 X-Spam-Report: Spam detection software, running on the system "quimby.gnus.org", has NOT identified this incoming email as spam. The original message has been attached to this so you can view it or label similar future email. If you have any questions, see @@CONTACT_ADDRESS@@ for details. Content preview: close 36478 29.1 quit Content analysis details: (-2.9 points, 5.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] X-Spam-Score: -2.3 (--) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -3.3 (---) close 36478 29.1 quit