GNU bug report logs - #36478
26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: emacs; Severity: minor; Reported by: Drew Adams <drew.adams@HIDDEN>; dated Tue, 2 Jul 2019 18:06:02 UTC; Maintainer for emacs is bug-gnu-emacs@HIDDEN.

Message received at 36478 <at> debbugs.gnu.org:


Received: (at 36478) by debbugs.gnu.org; 8 Jul 2019 23:30:32 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jul 08 19:30:32 2019
Received: from localhost ([127.0.0.1]:59973 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1hkd5b-00047K-NI
	for submit <at> 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 <monnier@HIDDEN>) id 1hkd5a-00040T-8S
 for 36478 <at> 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 <monnier@HIDDEN>
To: Lars Ingebrigtsen <larsi@HIDDEN>
Subject: Re: Perhaps rearrange *Help* buffer a bit?
Message-ID: <jwv5zocaz3r.fsf-monnier+emacs@HIDDEN>
References: <m3lfx81dql.fsf@HIDDEN> <jwvlfx8ck2j.fsf-monnier+emacs@HIDDEN>
 <m3bly4yxgq.fsf@HIDDEN>
Date: Mon, 08 Jul 2019 19:30:21 -0400
In-Reply-To: <m3bly4yxgq.fsf@HIDDEN> (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-Debbugs-Envelope-To: 36478
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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






Information forwarded to bug-gnu-emacs@HIDDEN:
bug#36478; Package emacs. Full text available.

Message received at 36478 <at> debbugs.gnu.org:


Received: (at 36478) by debbugs.gnu.org; 8 Jul 2019 23:22:07 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jul 08 19:22:07 2019
Received: from localhost ([127.0.0.1]:59947 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1hkcxT-0003Qg-Bi
	for submit <at> 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 <drew.adams@HIDDEN>) id 1hkcxR-0003QB-3V
 for 36478 <at> 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 <drew.adams@HIDDEN>
To: Lars Ingebrigtsen <larsi@HIDDEN>, Stefan Monnier
 <monnier@HIDDEN>
Subject: RE: bug#36478: Perhaps rearrange *Help* buffer a bit?
References: <m3lfx81dql.fsf@HIDDEN> <jwvlfx8ck2j.fsf-monnier+emacs@HIDDEN>
 <m3bly4yxgq.fsf@HIDDEN>
In-Reply-To: <m3bly4yxgq.fsf@HIDDEN>
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-Debbugs-Envelope-To: 36478
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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.




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#36478; Package emacs. Full text available.

Message received at 36478 <at> debbugs.gnu.org:


Received: (at 36478) by debbugs.gnu.org; 8 Jul 2019 22:26:36 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jul 08 18:26:36 2019
Received: from localhost ([127.0.0.1]:59854 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1hkc5k-000698-9T
	for submit <at> 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 <larsi@HIDDEN>) id 1hkc5j-00068z-2A
 for 36478 <at> 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 <larsi@HIDDEN>)
 id 1hkc5d-0005mB-IV; Tue, 09 Jul 2019 00:26:32 +0200
From: Lars Ingebrigtsen <larsi@HIDDEN>
To: Stefan Monnier <monnier@HIDDEN>
Subject: Re: Perhaps rearrange *Help* buffer a bit?
References: <m3lfx81dql.fsf@HIDDEN> <jwvlfx8ck2j.fsf-monnier+emacs@HIDDEN>
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: <jwvlfx8ck2j.fsf-monnier+emacs@HIDDEN> (Stefan Monnier's message
 of "Mon, 08 Jul 2019 17:14:05 -0400")
Message-ID: <m3bly4yxgq.fsf@HIDDEN>
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 <monnier@HIDDEN> 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-Debbugs-Envelope-To: 36478
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -1.0 (-)

Stefan Monnier <monnier@HIDDEN> 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




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#36478; Package emacs. Full text available.

Message received at 36478 <at> debbugs.gnu.org:


Received: (at 36478) by debbugs.gnu.org; 8 Jul 2019 21:14:15 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Mon Jul 08 17:14:15 2019
Received: from localhost ([127.0.0.1]:59729 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1hkaxj-0004CH-31
	for submit <at> 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 <monnier@HIDDEN>) id 1hkaxh-0004C4-EX
 for 36478 <at> 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 <monnier@HIDDEN>
To: Lars Ingebrigtsen <larsi@HIDDEN>
Subject: Re: Perhaps rearrange *Help* buffer a bit?
Message-ID: <jwvlfx8ck2j.fsf-monnier+emacs@HIDDEN>
References: <m3lfx81dql.fsf@HIDDEN>
Date: Mon, 08 Jul 2019 17:14:05 -0400
In-Reply-To: <m3lfx81dql.fsf@HIDDEN> (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-Debbugs-Envelope-To: 36478
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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





Information forwarded to bug-gnu-emacs@HIDDEN:
bug#36478; Package emacs. Full text available.

Message received at 36478 <at> debbugs.gnu.org:


Received: (at 36478) by debbugs.gnu.org; 4 Jul 2019 01:35:33 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Jul 03 21:35:33 2019
Received: from localhost ([127.0.0.1]:50206 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1hiqer-0008M6-B8
	for submit <at> 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 <rms@HIDDEN>) id 1hiqep-0008Lu-P7
 for 36478 <at> 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 <rms@HIDDEN>)
 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 <rms@HIDDEN>)
 id 1hiqea-0006HP-Vj; Wed, 03 Jul 2019 21:35:17 -0400
Content-Type: text/plain; charset=Utf-8
From: Richard Stallman <rms@HIDDEN>
To: Drew Adams <drew.adams@HIDDEN>
In-Reply-To: <21500c6e-9743-40ce-89d8-d63c9351e8c0@default> (message from Drew
 Adams on Tue, 2 Jul 2019 13:13:40 -0700 (PDT))
Subject: Re: bug#36478: 26.2;
 Doc strings with "This function has a compiler macro..." and "This
 function does not change global state"
References: <<13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default>>
 <<83r278cjho.fsf@HIDDEN>> <21500c6e-9743-40ce-89d8-d63c9351e8c0@default>
Message-Id: <E1hiqea-0006HP-Vj@HIDDEN>
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-Debbugs-Envelope-To: 36478
Cc: eliz@HIDDEN, 36478 <at> debbugs.gnu.org, drew.adams@HIDDEN
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Reply-To: rms@HIDDEN
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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)






Information forwarded to bug-gnu-emacs@HIDDEN:
bug#36478; Package emacs. Full text available.

Message received at 36478 <at> debbugs.gnu.org:


Received: (at 36478) by debbugs.gnu.org; 4 Jul 2019 01:34:22 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Jul 03 21:34:22 2019
Received: from localhost ([127.0.0.1]:50201 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1hiqdg-0008K8-3Z
	for submit <at> 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 <rms@HIDDEN>) id 1hiqde-0008Jw-5J
 for 36478 <at> 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 <rms@HIDDEN>)
 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 <rms@HIDDEN>)
 id 1hiqdX-00065N-Tz; Wed, 03 Jul 2019 21:34:12 -0400
Content-Type: text/plain; charset=Utf-8
From: Richard Stallman <rms@HIDDEN>
To: Drew Adams <drew.adams@HIDDEN>
In-Reply-To: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> (message from Drew
 Adams on Tue, 2 Jul 2019 11:05:18 -0700 (PDT))
Subject: Re: bug#36478: 26.2;
 Doc strings with "This function has a compiler macro..." and "This
 function does not change global state"
References: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default>
Message-Id: <E1hiqdX-00065N-Tz@HIDDEN>
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-Debbugs-Envelope-To: 36478
Cc: 36478 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Reply-To: rms@HIDDEN
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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)






Information forwarded to bug-gnu-emacs@HIDDEN:
bug#36478; Package emacs. Full text available.

Message received at 36478 <at> debbugs.gnu.org:


Received: (at 36478) by debbugs.gnu.org; 2 Jul 2019 20:13:57 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Jul 02 16:13:57 2019
Received: from localhost ([127.0.0.1]:48012 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1hiPA5-0007fl-60
	for submit <at> 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 <drew.adams@HIDDEN>) id 1hiPA3-0007fY-59
 for 36478 <at> 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 <drew.adams@HIDDEN>
To: Eli Zaretskii <eliz@HIDDEN>, Drew Adams <drew.adams@HIDDEN>
Subject: RE: bug#36478: 26.2; Doc strings with "This function has a compiler
 macro..." and "This function does not change global state"
References: <<13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default>>
 <<83r278cjho.fsf@HIDDEN>>
In-Reply-To: <<83r278cjho.fsf@HIDDEN>>
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-Debbugs-Envelope-To: 36478
Cc: 36478 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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.




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#36478; Package emacs. Full text available.

Message received at 36478 <at> debbugs.gnu.org:


Received: (at 36478) by debbugs.gnu.org; 2 Jul 2019 19:41:40 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Jul 02 15:41:40 2019
Received: from localhost ([127.0.0.1]:47985 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1hiOen-0006tt-37
	for submit <at> 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 <eliz@HIDDEN>) id 1hiOei-0006te-G0
 for 36478 <at> 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 <eliz@HIDDEN>)
 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 <eliz@HIDDEN>)
 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@HIDDEN>
From: Eli Zaretskii <eliz@HIDDEN>
To: Drew Adams <drew.adams@HIDDEN>
In-reply-to: <13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default> (message from Drew
 Adams on Tue, 2 Jul 2019 11:05:18 -0700 (PDT))
Subject: Re: bug#36478: 26.2;
 Doc strings with "This function has a compiler macro..." and "This
 function does not change global state"
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-Debbugs-Envelope-To: 36478
Cc: 36478 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

> Date: Tue, 2 Jul 2019 11:05:18 -0700 (PDT)
> From: Drew Adams <drew.adams@HIDDEN>
> 
> `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.




Information forwarded to bug-gnu-emacs@HIDDEN:
bug#36478; Package emacs. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 2 Jul 2019 18:05:47 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Jul 02 14:05:47 2019
Received: from localhost ([127.0.0.1]:47902 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1hiNA3-0000Im-Dg
	for submit <at> 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 <drew.adams@HIDDEN>) id 1hiNA1-0000Ic-3A
 for submit <at> 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 <drew.adams@HIDDEN>) id 1hiN9u-0003uG-8t
 for bug-gnu-emacs@HIDDEN; 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 <drew.adams@HIDDEN>) id 1hiN9p-000789-Un
 for bug-gnu-emacs@HIDDEN; 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 <drew.adams@HIDDEN>)
 id 1hiN9o-0006xK-8z
 for bug-gnu-emacs@HIDDEN; 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 <bug-gnu-emacs@HIDDEN>; 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 <bug-gnu-emacs@HIDDEN>; 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 <bug-gnu-emacs@HIDDEN>; 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 <bug-gnu-emacs@HIDDEN>; 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 <bug-gnu-emacs@HIDDEN>; 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 <drew.adams@HIDDEN>
To: bug-gnu-emacs@HIDDEN
Subject: 26.2; Doc strings with "This function has a compiler macro..." and
 "This function does not change global state"
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-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
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''




Acknowledgement sent to Drew Adams <drew.adams@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs@HIDDEN. Full text available.
Report forwarded to bug-gnu-emacs@HIDDEN:
bug#36478; Package emacs. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Mon, 25 Nov 2019 12:00:02 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.