From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#17362: 24.4.50; inconsistent key notation: `ESC' vs `' Date: Tue, 29 Apr 2014 12:38:00 -0700 (PDT) Message-ID: <70552b88-0d96-470d-ae4d-237e3b884637@default> References: <> <<8338gwlz7v.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1398800375 7695 80.91.229.3 (29 Apr 2014 19:39:35 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 29 Apr 2014 19:39:35 +0000 (UTC) Cc: 17362@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Apr 29 21:39:27 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1WfDsD-00031Y-CS for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 Apr 2014 21:39:25 +0200 Original-Received: from localhost ([::1]:52240 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WfDsD-0006DX-1f for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 Apr 2014 15:39:25 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53734) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WfDs1-00066G-L4 for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 15:39:22 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WfDrq-00052o-PG for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 15:39:13 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:56305) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WfDrq-00052j-Kw for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 15:39:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1WfDrq-0001AI-1R for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 15:39:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 29 Apr 2014 19:39:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 17362 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 17362-submit@debbugs.gnu.org id=B17362.13988002914397 (code B ref 17362); Tue, 29 Apr 2014 19:39:01 +0000 Original-Received: (at 17362) by debbugs.gnu.org; 29 Apr 2014 19:38:11 +0000 Original-Received: from localhost ([127.0.0.1]:45423 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WfDr0-00018q-Rn for submit@debbugs.gnu.org; Tue, 29 Apr 2014 15:38:11 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:35718) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WfDqy-00018Y-Cf for 17362@debbugs.gnu.org; Tue, 29 Apr 2014 15:38:09 -0400 Original-Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s3TJc1eS021785 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 29 Apr 2014 19:38:02 GMT Original-Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85]) by ucsinet22.oracle.com (8.14.5+Sun/8.14.5) with ESMTP id s3TJc1rR009305 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Tue, 29 Apr 2014 19:38:01 GMT Original-Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s3TJc0wv010159; Tue, 29 Apr 2014 19:38:00 GMT In-Reply-To: <<8338gwlz7v.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6691.5000 (x86)] X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 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.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:88458 Archived-At: > > And you write , using the Lisp symbol name `left', because what > > is printed on the keyboard key is an arrow, not "Left". And yet for > > , the manual refers to it as both and (in > > Emacs 20 it was referred to as (only) ). >=20 > I simply never saw a keyboard with a "next" key, so I don't know how > it is labeled. I left those as they were because of that. is how Emacs calls the "PageDown" key. You did not leave that as . Or maybe you meant that you left it as because it is never labeled `next'? > > These are inconsistencies within the manual, IMO. They complicate > > understanding unnecessarily. >=20 > They are not inconsistencies to me, because there's a reason for > selecting each spelling, and I explained that reasoning. Others are > welcome to come up with different schemes, if they want, but I think > in general too drastic changes should be avoided, because people are > used to see "TAB" and "ESC". TAB and ESC is also how Emacs (UI/help) refers to those, so no problem there. > > > I disagree. The manual should make it easier for the reader to > > > identify the keys it talks about. For that reason, using the keys' > > > labels is IMO more useful and efficient than using their lowercase > > > variants. > > > > See above. The manual can mention commonly used key labels, to help > > users make connections. But it makes little sense for the manual > > to represent these keys differently in key sequences from the way > > Emacs itself represents them. >=20 > If you mention the labels in just one place, it is as if you didn't > mention them at all. It's a large manual, and no one reads the > section about why the keys are named like they are.=20 Cross references. > Most readers want > to read what directly pertains to the subject they need now, and > little else. So the key sequences in the manual need to use a > consistent naming scheme throughout, and not just in some obscure > subsubsubsection. The consistent naming scheme is the one Emacs itself uses. It is what users are used to seeing from Emacs. It is what users will see when they go back to the UI from the manual. A "consistent" naming scheme that sometimes bases the name on a key label and sometimes bases it on a Lisp symbol, and so on, is unnecessarily complicated. You can give a reasonable reason why you named this or that key the way you did in the manual, but if the reasoning has to go through multiple possibilities it is unecessarily complicated. Users should not need to know what the complicated rule is (or to look it up, in the lone manual location where it is explained). They should not wonder why sometimes this is done and sometimes that, even if you have a good explanation for it. > > > > > I only fixed inconsistencies in the manual, without any relation = to > > > > > what Emacs says in help mode. > > > > > > > > You fixed only some inconsistencies in the manual, but that is OK > > > > for this bug report. It is inconsistent to use sometim= es > > > > and other times, and , and , > > > > and so on. > > > > > > There should be only these variants in the manual: > > > >=20 > Sorry, that was incorrect: it should be , in all caps. The > others are correct. On my keyboard, "Backspace" is as much a label as are "Delete" and "Home". And I have a pretty common, standard keyboard. You will perhaps argue that keyboards change over time and differ according to location. Exactly. The most that can and should be said wrt keyboard key labels is to give some examples: `DEL' and (which are not the same) are sometimes labeled "Backspace". is sometimes labeled "Page Down". is sometimes labeled with a left-pointing arrow. And so on. If Emacs itself can refer to a key as then so can the Emacs manual. Emacs does not jump up every time it writes and say that this key might be labeled "PageDown", "Page Down", or "PageDwn" on your keyboard. And neither should the manual. It is enough to have a short section of the manual that talks about this - key labels vs Emacs key-sequence notation. > > There are lots of occurrences of . >=20 > Before my changes, yes. Now I see only one, in the Glossary. OK.