From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#56816: Missing documentation of function-key-map Date: Fri, 29 Jul 2022 10:19:59 +0300 Message-ID: <837d3w8jxc.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="33075"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 56816@debbugs.gnu.org To: Alan Mackenzie Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Jul 29 09:22:49 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 1oHKKe-0008O4-3I for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 29 Jul 2022 09:22:48 +0200 Original-Received: from localhost ([::1]:35212 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oHKKc-0003T7-G8 for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 29 Jul 2022 03:22:46 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:49162) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oHKHz-0003RM-Ta for bug-gnu-emacs@gnu.org; Fri, 29 Jul 2022 03:20:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:41838) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oHKHy-00009e-JD for bug-gnu-emacs@gnu.org; Fri, 29 Jul 2022 03:20:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oHKHy-00020C-D9 for bug-gnu-emacs@gnu.org; Fri, 29 Jul 2022 03:20:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 29 Jul 2022 07:20:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56816 X-GNU-PR-Package: emacs Original-Received: via spool by 56816-submit@debbugs.gnu.org id=B56816.16590791967679 (code B ref 56816); Fri, 29 Jul 2022 07:20:02 +0000 Original-Received: (at 56816) by debbugs.gnu.org; 29 Jul 2022 07:19:56 +0000 Original-Received: from localhost ([127.0.0.1]:59820 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oHKHr-0001zl-LO for submit@debbugs.gnu.org; Fri, 29 Jul 2022 03:19:55 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:36192) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oHKHq-0001zY-41 for 56816@debbugs.gnu.org; Fri, 29 Jul 2022 03:19:54 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:35046) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oHKHk-0008IS-CY; Fri, 29 Jul 2022 03:19:48 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=VTgEPEmFA8MiGzsivvU4s4vx6+kcULfLeR5zGnkvLMU=; b=Vrt8d8PwKk3b 1WPFuzJ/X/9evo0wPb5hQbylEz0NQyZY6wDGHkoa4MwMlTfRHb1K/YC1KUMLxqB0F7tGawrbKNA/d yUneTfEy7wSR0KVdyAfKnJldlboaiTB9ClfgoOprxSHYxQc4p9GOcvzoyB4R1VaEBYDjKFIgaar1K W54AHdO2LDOQ+RFasuvLH8ycJps9kjkQpe+dg5lD14gt3vZ4RiJRAx7owQ9bOQ2iBswV8UJkfh+Lt uKvSeZ3zYFFadXeN7a0LTb2YeWiyCpjqmnb1XFGM64LpgYl9d53if9CYHD0F1NfPBJvJG0pSQF/jT qHcZy39KScxRb5gTNbTIfQ==; Original-Received: from [87.69.77.57] (port=1503 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oHKHj-0000fm-Kd; Fri, 29 Jul 2022 03:19:48 -0400 In-Reply-To: (message from Alan Mackenzie on Thu, 28 Jul 2022 19:30:36 +0000) 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:238140 Archived-At: > Date: Thu, 28 Jul 2022 19:30:36 +0000 > From: Alan Mackenzie > > 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. Would you please state clearly what exactly is a bug here? Specifically, what is missing from the doc string of this variable? Would saying something like "Keymap for bindings of function keys." be enough, or is some other information missing in your opinion, and if so, what? Once we are done with the doc string, we can discuss whether the manual needs any changes in this respect; in general, not every variable must be in the manual, and as long as the doc string is sufficient, we are fine. Thanks.