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#61183: 29.0.60; Add describe-repeat-maps to the manual Date: Mon, 30 Jan 2023 20:36:28 +0200 Message-ID: <83y1pj3m4z.fsf@gnu.org> References: <86pmawgl17.fsf@mail.linkov.net> <838rhj52en.fsf@gnu.org> <86tu07evv6.fsf@mail.linkov.net> 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="14195"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 61183@debbugs.gnu.org To: Juri Linkov Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Mon Jan 30 19:37:44 2023 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 1pMZ2G-0003WN-8u for geb-bug-gnu-emacs@m.gmane-mx.org; Mon, 30 Jan 2023 19:37:44 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pMZ1t-0004sq-Ee; Mon, 30 Jan 2023 13:37:21 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pMZ1a-0004rN-MZ for bug-gnu-emacs@gnu.org; Mon, 30 Jan 2023 13:37:03 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pMZ1a-0002d4-EB for bug-gnu-emacs@gnu.org; Mon, 30 Jan 2023 13:37:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pMZ1a-0002vh-6P for bug-gnu-emacs@gnu.org; Mon, 30 Jan 2023 13:37:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 30 Jan 2023 18:37:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 61183 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 61183-submit@debbugs.gnu.org id=B61183.167510380311231 (code B ref 61183); Mon, 30 Jan 2023 18:37:02 +0000 Original-Received: (at 61183) by debbugs.gnu.org; 30 Jan 2023 18:36:43 +0000 Original-Received: from localhost ([127.0.0.1]:50512 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pMZ1G-0002v4-Fz for submit@debbugs.gnu.org; Mon, 30 Jan 2023 13:36:42 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:55106) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pMZ1E-0002us-UI for 61183@debbugs.gnu.org; Mon, 30 Jan 2023 13:36:41 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pMZ18-0002bd-Tt; Mon, 30 Jan 2023 13:36:34 -0500 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=WqYZFKgIy4ucReZ+KMlCkUFDgIzPzhxr2j1mnm5Uevc=; b=BiJj4ioY3kRwADf2tS7l qhWM2jEe9fysoCe2xLBiKgHi5R3OCn07iAjnRkyWb/j5aI+xMjEenjEEAW+KzAne1B3B4xS9jtq1i PyyFZwKKnyMyswp8/I1YjfF74Tm90IMbgx2w5T5pIPRPnTQiqGUpq8VOF1hnnYiAbw0Kxh+9fgANt nPq6a+xzk+fcTR+lIE31fJacYEkI9o6IWdzyBaAVM92h/U5Vamv4tYSXza9fgkTsd4H9u36cnDthA cc6UgEig9sXU1YrZJxvS1Z0NB1UsjuCztcqs+kt0k4Akc7sVOaaE5NQS+GtAcAVubIC+aJRGZMlWv jlTZO31PJAgY7g==; Original-Received: from [87.69.77.57] (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 1pMZ18-0002Of-9S; Mon, 30 Jan 2023 13:36:34 -0500 In-Reply-To: <86tu07evv6.fsf@mail.linkov.net> (message from Juri Linkov on Mon, 30 Jan 2023 20:10:53 +0200) 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-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:254469 Archived-At: > From: Juri Linkov > Cc: 61183@debbugs.gnu.org > Date: Mon, 30 Jan 2023 20:10:53 +0200 > > >> +navigate @code{next-error} matches, @kbd{C-x ] ] [ [} to navigate > >> +through pages, and other listed in @code{describe-repeat-maps}. > > > > "and other commands", I presume? > > This is what I already tried, but noticed that it's talking about > key sequences. But "other key sequences" looks awkward too. "Other key sequences" sounds OK to me. > > Also, saying that commands are "listed in" a function sounds > > awkwardly; I guess you meant in the window shown by > > describe-repeat-maps instead? > > Maybe simply "listed by describe-repeat-maps"? Also works. > > And finally, I think this is insufficient to document > > describe-repeat-maps, because its output is not very > > self-explanatory. I actually have difficulty understanding what it > > wants to tell me. The heading line says > > > > A list of keymaps used by commands with the symbol property `repeat-map' > > > > which isn't a user-level information. This is followed by keymap > > names and some bindings in each keymap. What is the user supposed to > > understand from that? I think we lack some short introductory text > > immediately after the heading. Or maybe the manual should have some > > more detailed explanation of what that command shows. > > Its output is easy to understand for anyone who uses this feature > and just wants to check what commands are already supported. That's not the correct criterion for judging documentation, definitely not when the manual is concerned. The manual should be clear enough to explain the command's effect even to someone who reads about repeated commands for the first time. And even if you only consider experienced users, how can a user understand that these commands support repeating? Which part(s) of that buffer say that in terns that are clear enough? A naïve reader of the buffer will just see a list of commands and their bindings, preceded by a sentence whose intent is hard to understand without some background in Emacs keymaps.