From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.bugs Subject: bug#56816: Missing documentation of function-key-map Date: Thu, 28 Jul 2022 19:30:36 +0000 Message-ID: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="32568"; mail-complaints-to="usenet@ciao.gmane.io" To: 56816@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Jul 28 21:32:23 2022 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 1oH9F9-0008Kg-Bc for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 28 Jul 2022 21:32:23 +0200 Original-Received: from localhost ([::1]:49748 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oH9F8-0003lr-6L for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 28 Jul 2022 15:32:22 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47752) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oH9Dq-0003L0-7s for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 15:31:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:41437) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oH9Dp-0002nr-Uq for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 15:31:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oH9Dp-0007vN-Km for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 15:31:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 28 Jul 2022 19:31:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 56816 X-GNU-PR-Package: emacs X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.165903665830448 (code B ref -1); Thu, 28 Jul 2022 19:31:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 28 Jul 2022 19:30:58 +0000 Original-Received: from localhost ([127.0.0.1]:59419 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH9Dm-0007v2-2T for submit@debbugs.gnu.org; Thu, 28 Jul 2022 15:30:58 -0400 Original-Received: from lists.gnu.org ([209.51.188.17]:36284) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oH9Di-0007ut-LW for submit@debbugs.gnu.org; Thu, 28 Jul 2022 15:30:57 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:47740) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oH9Di-00038V-EQ for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 15:30:54 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:54976 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.90_1) (envelope-from ) id 1oH9Dg-0002mG-CT for bug-gnu-emacs@gnu.org; Thu, 28 Jul 2022 15:30:54 -0400 Original-Received: (qmail 83330 invoked by uid 3782); 28 Jul 2022 19:30:37 -0000 Original-Received: from acm.muc.de (p2e5d5f61.dip0.t-ipconnect.de [46.93.95.97]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Thu, 28 Jul 2022 21:30:37 +0200 Original-Received: (qmail 8528 invoked by uid 1000); 28 Jul 2022 19:30:37 -0000 Content-Disposition: inline X-Submission-Agent: TMDA/1.3.x (Ph3nix) X-Primary-Address: acm@muc.de Received-SPF: pass client-ip=193.149.48.1; envelope-from=acm@muc.de; helo=mail.muc.de X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action 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:238131 Archived-At: Hello, Emacs. function-key-map is not defined in the Elisp manual. It is mentioned, in passing, on the page "Translation Keymaps" thusly: `local-function-key-map' inherits from `function-key-map'. The latter should only be altered if you want the binding to apply in all terminals, so using the former is almost always preferred. So, all we know about function-key-map is when to alter it (and even here, it is unclear what the "all" in "all terminals" means). Not what it's for, not when it's looked up and used, not what its contents are. ######################################################################### The doc string for function-key-map is a little better. It, at least, attempts to give a context for the variable ("The parent keymap of all `local-function-key-map' instances."). The doc string gives an example of what belongs in the variable ("Function key definitions that apply to all terminal devices should go here."), but this doesn't define its contents. It contains more than function key definitions - for example, function keys with modifier keys, and modifier keys on their own (for example, a binding for event-apply-control-modifier). These are all documentation bugs. -- Alan Mackenzie (Nuremberg, Germany).