From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#30660: mention describe-bindings on (info "(emacs) Keymaps") Date: Fri, 23 Aug 2019 18:46:19 -0700 (PDT) Message-ID: <831b5f34-28c7-4753-bed9-0a28de484aa8@default> References: Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="248750"; mail-complaints-to="usenet@blaine.gmane.org" Cc: 30660@debbugs.gnu.org, =?UTF-8?Q?=E7=A9=8D=E4=B8=B9=E5=B0=BC?= Dan Jacobson To: Stefan Kangas Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Aug 24 03:47:12 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1i1L94-0012Wa-Qg for geb-bug-gnu-emacs@m.gmane.org; Sat, 24 Aug 2019 03:47:10 +0200 Original-Received: from localhost ([::1]:35650 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1L93-00016s-AY for geb-bug-gnu-emacs@m.gmane.org; Fri, 23 Aug 2019 21:47:09 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:33871) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1i1L8x-00016m-A6 for bug-gnu-emacs@gnu.org; Fri, 23 Aug 2019 21:47:04 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1i1L8w-0004sc-0Y for bug-gnu-emacs@gnu.org; Fri, 23 Aug 2019 21:47:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:60854) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1i1L8v-0004sV-TQ for bug-gnu-emacs@gnu.org; Fri, 23 Aug 2019 21:47:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1i1L8v-0004Wg-Ou for bug-gnu-emacs@gnu.org; Fri, 23 Aug 2019 21:47:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 24 Aug 2019 01:47:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 30660 X-GNU-PR-Package: emacs Original-Received: via spool by 30660-submit@debbugs.gnu.org id=B30660.156661119417363 (code B ref 30660); Sat, 24 Aug 2019 01:47:01 +0000 Original-Received: (at 30660) by debbugs.gnu.org; 24 Aug 2019 01:46:34 +0000 Original-Received: from localhost ([127.0.0.1]:41442 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1i1L8U-0004Vz-89 for submit@debbugs.gnu.org; Fri, 23 Aug 2019 21:46:34 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:42638) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1i1L8P-0004Vj-Ht for 30660@debbugs.gnu.org; Fri, 23 Aug 2019 21:46:30 -0400 Original-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 x7O1ijDd041212; Sat, 24 Aug 2019 01:46:23 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-2019-08-05; bh=2kq4oGy0YT4vY4A5nOlBTQwLN3Hpnhs91W6I5wbqZF4=; b=aKTn2bls6TuixHjUxme6aZcPOLyiTZGixpT2srUa4blufk6842h1+4ZLDU9HFajhwvEI 8/wOLU8xtOTC6i56P+ZlLxfPJenA4PRh+NZY7Z/pWY2EJFJhed9PGsWk/bdJly/4yPx7 6rkOz/FnucYS6HbPIfdUPEnaVTGsSdDSf/q1h4SUnRDjfbnzBp68ZsqakLChcbsqpbju u0HB9WFT/UhMud0ABsYdxvchR8E0+PAawobo4s3HzU80PeSuGyXBdZSWznQfO2w8BM3Z SlYcQs27lPORuLZX4im/A5/YnJ+OK3Xq3qb8DGP+7oIrsLPZorSYaePe2zQNpqCokT6S 3w== Original-Received: from userp3020.oracle.com (userp3020.oracle.com [156.151.31.79]) by userp2120.oracle.com with ESMTP id 2uea7rfqfy-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sat, 24 Aug 2019 01:46:22 +0000 Original-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 x7O1gOVo083856; Sat, 24 Aug 2019 01:46:22 GMT Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by userp3020.oracle.com with ESMTP id 2ujca8qpv5-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Sat, 24 Aug 2019 01:46:22 +0000 Original-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 x7O1kKWD011452; Sat, 24 Aug 2019 01:46:20 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4873.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9358 signatures=668684 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-1906280000 definitions=main-1908240017 X-Proofpoint-Virus-Version: vendor=nai engine=6000 definitions=9358 signatures=668684 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-1906280000 definitions=main-1908240017 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 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.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:165737 Archived-At: > > Non-interactively: > > * KEYMAP can be such a keymap variable or a keymap. > > * Non-nil optional arg SEARCH-SYMBOLS-P means that if KEYMAP is not a > > symbol then search all variables for one whose value is KEYMAP." >=20 > Is the purpose of SEARCH-SYMBOLS-P just to allow for calling it like > this: > (describe-keymap 'my-keymap t) > (describe-keymap my-keymap t) >=20 > And have it work automatically? Or am I missing something? Also see > below. KEYMAP can be a keymap, instead of a symbol. (This was not the case originally. I added handling this case later, as it was requested and turned out to be useful. It's not rare to have a keymap object ready-to-hand and without its variable. This lets you not only see the bindings but also identify the keymap.) If it's not a symbol there might still be a symbol that has it as value. Non-nil SEARCH-SYMBOLS-P means try to find such a symbol. If such a symbol is found then the help is better - it tells you more about the keymap and its context, by (1) providing its doc (in addition to listing the key bindings) and even just (2) providing its name, letting you know (typically) what mode or other context defines it. If the search finds no symbol with KEYMAP as its value then the behavior is the same as if no search was made (except for the time wasted on a failed search): a symbol is generated for the map (just to use the same code path). The other difference is that because you provided SEARCH-SYMBOLS-P you know that a search turned up no symbol - more information. > I admit that I find this code a bit hard to follow. If I understand > correctly, then most of this can be removed if we don't want to > support SEARCH-SYMBOLS-P, and instead just require that the KEYMAP > argument is a symbol. Is that correct or am I missing something? Who's "we"? If a _user_ or calling code doesn't want to search existing symbols then SEARCH-SYMBOLS-P is supplied. Nothing is lost by having it as a behavior option, and something (quite a lot, actually) is gained by making it available. Putting a name on a keymap object can be quite helpful. The case where a user (or calling code) has a keymap but no variable for it is not uncommon, even if it is not the most common case. Being able to find the variable and see its doc is helpful. > I'm sort of leaning towards simplifying this by removing the > SEARCH-SYMBOLS-P argument, but I might not understand the use case > here. If I'm missing something, could you please briefly describe the > use case for that and if and why it's important to keep? See above. > > (let* ((name (symbol-name keymap)) > > (doc (let ((raw-doc (documentation-property keymap > 'variable-documentation 'RAW))) > > (substitute-command-keys raw-doc))) >=20 > Why not just say (documentation-property keymap 'variable- > documentation) > without the 'RAW argument? That should have the same effect as > passing the 'RAW argument and then calling substitute-command-keys on > the result, AFAICT. Yes; sorry. My code uses `help-documentation-property' and `help-substitute-command-keys'. I too quickly substituted the body of `help-documentation-property', changing its occurrence of `help-substitute-command-keys' to just `substitute-command-keys'. None of `h-d-p' is needed here if you don't have `h-s-c-k'. IOW, if neither of those is available then yes, all you need is (documentation-property keymap 'variable-documentation). Sorry about that mistake. You might want to take a look at the full code, in help-fns+.el, to see what the differences are. Some are to support older Emacs versions too, others are to provide additional features. > > (doc (and (not (equal "" doc)) doc))) >=20 > Is this to allow us to simply say (when doc ...) below Yes. It makes DOC be either nil or real doc. > instead of (when (not (equal "" doc)) ...) [aka (unless (equal "" doc)...)] No. That's not the same. That does `...' when doc is nil. The code should do `...' only when doc is non-nil and not "".