From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Stefan Kangas Newsgroups: gmane.emacs.bugs Subject: bug#50599: [PATCH] Don't recommend against "\[...]" substitutions for performance Date: Wed, 15 Sep 2021 16:13:59 +0200 Message-ID: References: <83v932bawy.fsf@gnu.org> <83tuimb61d.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="13059"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 50599@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Sep 15 16:15:40 2021 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1mQVhM-0003Ct-D7 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 15 Sep 2021 16:15:40 +0200 Original-Received: from localhost ([::1]:41754 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mQVhL-000193-7Q for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 15 Sep 2021 10:15:39 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42126) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mQVgl-00016P-4S for bug-gnu-emacs@gnu.org; Wed, 15 Sep 2021 10:15:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:41269) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mQVgk-0000mT-SN for bug-gnu-emacs@gnu.org; Wed, 15 Sep 2021 10:15:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mQVgk-0005mq-4L for bug-gnu-emacs@gnu.org; Wed, 15 Sep 2021 10:15:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 15 Sep 2021 14:15:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 50599 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 50599-submit@debbugs.gnu.org id=B50599.163171525822176 (code B ref 50599); Wed, 15 Sep 2021 14:15:02 +0000 Original-Received: (at 50599) by debbugs.gnu.org; 15 Sep 2021 14:14:18 +0000 Original-Received: from localhost ([127.0.0.1]:52814 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mQVg2-0005lc-HW for submit@debbugs.gnu.org; Wed, 15 Sep 2021 10:14:18 -0400 Original-Received: from mail-pf1-f178.google.com ([209.85.210.178]:39929) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mQVg0-0005lO-FD for 50599@debbugs.gnu.org; Wed, 15 Sep 2021 10:14:17 -0400 Original-Received: by mail-pf1-f178.google.com with SMTP id e16so2809587pfc.6 for <50599@debbugs.gnu.org>; Wed, 15 Sep 2021 07:14:16 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=8pUUYKiWnEZaRBYwLrBPEQHBOLoWmNEOAhnMEEmK7FA=; b=Mv0xHpUjB2w6nVLsfh+0jE+fkkF6UMUslAXcYriOXk4cJFVK8o2lBVQUPQd5EN7wcD Rd0Kxq5QgeisDTh/l3IGc0xH/5Zef6uFTUwUsmSHg92JAyzDMdeylTWQE5hgqH5nBGYl Twza8NgCXMI0u8vDgtK+ngdVlNDR/ikVqm1fGFMVfgvOS2DS349LYiAzrxJgDdfafIpz +I7onaXMmkqydQrqgM7CRbEkgh4KtZ/WB7YUHcyTrSVn6OjNs2uHg6FKVFHETfzRJcKX p/sS9OrECgXbLwcFo+fn4z7qlOft50wp71slsHKwGkDM61sEFrpN3SrjC3yoWK+sVvTY f/kA== X-Gm-Message-State: AOAM532449KkchXQ8vP2qcbka/5UtxaNlJyhFVacSz3PVfOwfyGqc0VA osCUeIdO7jJrZKzmwzAMpD4NXgW8obG0s3cDAieT9Em+zt8= X-Google-Smtp-Source: ABdhPJyRaHC66AjLIIwyiVT2ok9wn3vaSXeYlYXCySaB4R+7ohegeh0lN4DMHBZzeIa+M0XzO+2yRhCvmmKFfbpVlfc= X-Received: by 2002:a62:1c85:0:b0:440:3583:9fda with SMTP id c127-20020a621c85000000b0044035839fdamr198537pfc.0.1631715250548; Wed, 15 Sep 2021 07:14:10 -0700 (PDT) In-Reply-To: <83tuimb61d.fsf@gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:214400 Archived-At: Eli Zaretskii writes: > We have no idea what could Lisp programmers out there want to do with > this. For example, I could envision some programmatically generated > help text with many such references. Where there are limitations due > to the implementation, we should strive to let people know about them. But not every such limitation belongs in `(elisp) Documentation Tips'. Even if one can imagine that there exists specialized applications where this limitation will become a problem, that does not mean that we should mention it here. This section should IMO be about general advice for Emacs Lisp programming, and this is not a general problem. > I disagree with the "completely irrelevant" part, the general advice > to keep the use of \\[..] to the minimum is still valid, I see no reason to keep use of "\\[...]" to the minimum. In any realistic use, my investigation has demonstrated that there is no problem with using it for reasons of performance. Instead of discouraging it, we should encourage its use, as it leads to better documentation. For example, compare the current 'ibuffer-mode' docstring to what you get if you replace the list of commands (with its categories, explanations, etc.) with a blanket "\\{ibuffer-mode-map}". So I find the advice not only irrelevant but misleading. How about this: We change, in my patch, 'checkdoc-max-keyref-before-warn' to a value like 1000 or 500 instead of nil. This would make me happy by not impacting any real use-cases [none of which will have 500+ commands in its docstring, or at least none of the ones that I care about will] and it would (hopefully) make you happy by sufficiently calling attention to any possible performance issues in some other cases. With that, perhaps we could agree that it is okay to delete the paragraph in `(elisp) Documentation Tips'. Running 'checkdoc' is after all recommended in that section as well. WDYT?