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: Sat, 30 Jul 2022 09:42:14 +0300 Message-ID: <83zggr5cft.fsf@gnu.org> 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="11518"; 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 Sat Jul 30 08:43:47 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 1oHgCR-0002si-Fl for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 30 Jul 2022 08:43:47 +0200 Original-Received: from localhost ([::1]:58650 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oHgCQ-0003NB-C9 for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 30 Jul 2022 02:43:46 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:34300) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oHgBj-0003Mx-CS for bug-gnu-emacs@gnu.org; Sat, 30 Jul 2022 02:43:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:44047) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oHgBh-0007xo-V9 for bug-gnu-emacs@gnu.org; Sat, 30 Jul 2022 02:43:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oHgBh-0002et-Q1 for bug-gnu-emacs@gnu.org; Sat, 30 Jul 2022 02:43:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 30 Jul 2022 06:43:01 +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.165916334910173 (code B ref 56816); Sat, 30 Jul 2022 06:43:01 +0000 Original-Received: (at 56816) by debbugs.gnu.org; 30 Jul 2022 06:42:29 +0000 Original-Received: from localhost ([127.0.0.1]:33796 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oHgBB-0002e1-AT for submit@debbugs.gnu.org; Sat, 30 Jul 2022 02:42:29 -0400 Original-Received: from eggs.gnu.org ([209.51.188.92]:49566) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oHgB6-0002dm-OA for 56816@debbugs.gnu.org; Sat, 30 Jul 2022 02:42:28 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]:59956) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oHgB0-0007qS-RV; Sat, 30 Jul 2022 02:42:18 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=d/2ZeYTwtUyyOuoHqvke3Z06PVLunhSfPlMFY/abIU4=; b=XNaC0c9OvYoIYLE0UgUL GVaUSujtDS2DCyLo1zy8Wg2A/07Hg20TT6GCnhRghiF9jEDM07+qIdPXGEizmVM9ZWkj/lQ6cKFoD A21ZR9xlmlFjbvm3F+7NdW53M+FxOYImTm5dJkVIlerNJKh9HeUPLVRAfxG8VcDzUroecsEwFbJkU JGC0kvAWmW0DF/UZVWQtlJ+DZoo4AsSg/C42IryIT3KSIT9IKBMZq55IfXXUb77FR1zcHnNQLX/Ld KjhpVYVYz8Ub1Na5uHCXr7/2d/J/Sb0rnachPo3TYJQwHDREI+MEOyiVEds8AWLE+evzcbPfHtZaF HqNMUhJXfOBOoQ==; Original-Received: from [87.69.77.57] (port=4146 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 1oHgAz-0001Mo-D4; Sat, 30 Jul 2022 02:42:18 -0400 In-Reply-To: (message from Alan Mackenzie on Fri, 29 Jul 2022 19:50:35 +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:238233 Archived-At: > Date: Fri, 29 Jul 2022 19:50:35 +0000 > Cc: 56816@debbugs.gnu.org, acm@muc.de > From: Alan Mackenzie > > > > 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. The real description is in "Translation Keymaps" (where you get by following the cross-reference near local-function-key-map, which itself is referenced from function-key-map). I've now added an index entry for function-key-map in "Translation Keymaps". > > 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. The doc string includes a link top local-function-key-map, whose doc string describes some more. Given all of the above, what else is missing? Please be specific. > > 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. This doesn't really help, because I don't see how what you describe is related to the stuff that is or isn't in the documentation. I'm not even sure I understand why you think function-key-map is what you need to investigate, and how are your needs related to what, if anything, is wrong with or missing from the material in "Translation Keymaps". "Little clarity and little redundancy" doesn't help me understand what needs to be done.