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#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap' Date: Sat, 23 Oct 2021 11:03:26 -0700 Message-ID: References: <4f0b5f4f-74bd-5610-0cff-14da7ca90f39@topbug.net> <2e495171-34f8-436e-9fc5-334bd93fde00@default> 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="11684"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/29.0.50 (gnu/linux) Cc: Andreas Schwab , 30958@debbugs.gnu.org To: Hong Xu Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Oct 23 20:04:21 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 1meLNV-0002p7-5A for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 23 Oct 2021 20:04:21 +0200 Original-Received: from localhost ([::1]:56158 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1meLNT-0002Uz-Q9 for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 23 Oct 2021 14:04:19 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:54232) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1meLND-0002U0-IE for bug-gnu-emacs@gnu.org; Sat, 23 Oct 2021 14:04:04 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:53858) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1meLNB-0001An-Pb for bug-gnu-emacs@gnu.org; Sat, 23 Oct 2021 14:04:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1meLNB-0005NZ-LM for bug-gnu-emacs@gnu.org; Sat, 23 Oct 2021 14:04:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Stefan Kangas Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 23 Oct 2021 18:04:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 30958 X-GNU-PR-Package: emacs Original-Received: via spool by 30958-submit@debbugs.gnu.org id=B30958.163501221920649 (code B ref 30958); Sat, 23 Oct 2021 18:04:01 +0000 Original-Received: (at 30958) by debbugs.gnu.org; 23 Oct 2021 18:03:39 +0000 Original-Received: from localhost ([127.0.0.1]:37171 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1meLMm-0005Mw-3Q for submit@debbugs.gnu.org; Sat, 23 Oct 2021 14:03:39 -0400 Original-Received: from mail-pj1-f48.google.com ([209.85.216.48]:51096) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1meLMi-0005MV-3X for 30958@debbugs.gnu.org; Sat, 23 Oct 2021 14:03:32 -0400 Original-Received: by mail-pj1-f48.google.com with SMTP id gn3so5192533pjb.0 for <30958@debbugs.gnu.org>; Sat, 23 Oct 2021 11:03:32 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:in-reply-to:references:user-agent :mime-version:date:message-id:subject:to:cc; bh=jxrTpwmF6agT8f6HSKQnyKUtU1C8Np3H5pgEk3+cFn8=; b=1YIXN7ZOXErTOJFAK6b1pUWu6b/1kg+ZOrb9KM410dOJ/7rsH37MPHVTWYFW9SVlpv Jm7TtSRfmk1XOzjiPmDRnqL2nkoHFFu0NiWIkzeBKh+jonrXLfE+7VgspDPS1zB8gRhF UfQ5DF3+ih9uhYdptZ3/3FtX3DTRG8I8A7F0RBjX4G1Gj8AU8aLqAlxDdTwSQRuBUyZi zLOyj6QF7de/G2kMSoYgPRM6JYti7LEf1uXhgBm4hb8TxzSjs7EiO+dosKefztPBzzYY SoF2tpZ7rApwAVXSjwcioTzPxcHHG+3+IkKu1FS+tPYfG0N6s016yZaw0FFE0EtETTk5 NbZw== X-Gm-Message-State: AOAM530H/kswfZ8kz7kreAPxPpNEd0RsOI3cjrwvY5WHOhL5F1AkEIv/ gptGvRJ4QZAfdI3RBoANJCLQP/Im3XsDfzmnSxI= X-Google-Smtp-Source: ABdhPJyFNvSvNALa+qUlAU+/qi3p9qc9X45MrMAN1AuBFCxkf9vuypAKIDx9vfyagmUNVI3S4U2Um9oSjEcr0ZhVxj0= X-Received: by 2002:a17:902:b691:b029:12d:2b6:d116 with SMTP id c17-20020a170902b691b029012d02b6d116mr6448228pls.71.1635012206516; Sat, 23 Oct 2021 11:03:26 -0700 (PDT) Original-Received: from 753933720722 named unknown by gmailapi.google.com with HTTPREST; Sat, 23 Oct 2021 11:03:26 -0700 In-Reply-To: (Hong Xu's message of "Tue, 27 Mar 2018 10:39:09 -0700") 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:218016 Archived-At: Hong Xu writes: > Thanks, Drew. Actually it's also obvious for me to look up for a keymap > is. What is unobvious is the value of the binding. Even if you go to > "Format of Keymaps", it still does not talk about the actual value of > the binding. The reason it is important for `map-keymap' is that this > seems to be the only place that users need to know the exact value of > binding---in other places, they are operated by some provided functions. The docstring of `map-keymap' says: Call FUNCTION once for each event binding in KEYMAP. FUNCTION is called with two arguments: the event that is bound, and the definition it is bound to. The event may be a character range. A keymap is fundamentally either a list or a char table with mappings from events to a definition. The event could be e.g. a key sequence, and the definitions might be commands or other things. I find "the event that is bound" to be clear enough, in the sense that you know what to look for in the manual. I also find "the definition it is bound to" clear in the same sense. I don't see what to add to make this any clearer, without pulling in the entire reference manual worth of stuff to explain all possible types of values. IOW, I think the answer here is that to use this particular function, you cannot just read the docstring, you must study the info node `(elisp) Keymaps' in detail. I don't see any way around that. So maybe you are right, but maybe also there is just not much we can do about it. Or there is some way to explain this that none of us have seen so far. Perhaps you have a suggestion for what we could add here?