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: Fri, 29 Jul 2022 19:50:35 +0000 Message-ID: References: <837d3w8jxc.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="33531"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 56816@debbugs.gnu.org, acm@muc.de To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Jul 29 21:51:10 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 1oHW0r-0008Ur-Rm for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 29 Jul 2022 21:51:09 +0200 Original-Received: from localhost ([::1]:60644 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oHW0q-00010C-2J for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 29 Jul 2022 15:51:08 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46500) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oHW0k-0000zf-NX for bug-gnu-emacs@gnu.org; Fri, 29 Jul 2022 15:51:02 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:43759) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oHW0k-00053c-FC for bug-gnu-emacs@gnu.org; Fri, 29 Jul 2022 15:51:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oHW0k-0008Uh-BO for bug-gnu-emacs@gnu.org; Fri, 29 Jul 2022 15:51:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Alan Mackenzie Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 29 Jul 2022 19:51: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.165912424732628 (code B ref 56816); Fri, 29 Jul 2022 19:51:02 +0000 Original-Received: (at 56816) by debbugs.gnu.org; 29 Jul 2022 19:50:47 +0000 Original-Received: from localhost ([127.0.0.1]:33508 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oHW0U-0008UC-Rb for submit@debbugs.gnu.org; Fri, 29 Jul 2022 15:50:47 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:37045 helo=mail.muc.de) by debbugs.gnu.org with smtp (Exim 4.84_2) (envelope-from ) id 1oHW0R-0008Tu-1P for 56816@debbugs.gnu.org; Fri, 29 Jul 2022 15:50:45 -0400 Original-Received: (qmail 78368 invoked by uid 3782); 29 Jul 2022 19:50:36 -0000 Original-Received: from acm.muc.de (p4fe1596f.dip0.t-ipconnect.de [79.225.89.111]) (using STARTTLS) by colin.muc.de (tmda-ofmipd) with ESMTP; Fri, 29 Jul 2022 21:50:36 +0200 Original-Received: (qmail 9227 invoked by uid 1000); 29 Jul 2022 19:50:35 -0000 Content-Disposition: inline In-Reply-To: <837d3w8jxc.fsf@gnu.org> X-Submission-Agent: TMDA/1.3.x (Ph3nix) X-Primary-Address: acm@muc.de 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:238217 Archived-At: Hello, Eli. On Fri, Jul 29, 2022 at 10:19:59 +0300, Eli Zaretskii wrote: > > 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? That there is a reference to function-key-map in that manual page, but there is no description of function-key-map whatsoever in the manual. If things are to stay that way, perhaps we could add something like "(not documented in this manual. See the variable's doc string for details.)" as a footnote. > 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? That description would be a big improvement. Perhaps it could also say "including modifiers for some keys" or something like that; The modifiers, all 7 combinations, are included for each keypad key, but not for the other function keys. > 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. I'll tell you what gave rise to this. On a proprietary system in my day job, typing C-M-a is giving the result M-á, and similarly for the other four vowels with C-M-. This should be relatively straightforward to remedy, but I've been struggling with that manual page for two evenings, now. The manual page ("Translation Keymaps") seems to have most of the information, but there is little clarity and little redundancy. I think I need to add a binding for M-á to convert it to C-M-a, but in which keymap? There are three keymaps described on the page, but their purposes are not entirely clear. One of them is the one I need, I think. It surely shouldn't take several hours to digest the information on a single moderately sized info page. > Thanks. -- Alan Mackenzie (Nuremberg, Germany).