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:09:25 -0700 (PDT) Message-ID: References: <> <<834n1cm1bx.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 1398798635 10115 80.91.229.3 (29 Apr 2014 19:10:35 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 29 Apr 2014 19:10: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:10:28 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 1WfDQA-0005wm-A8 for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 Apr 2014 21:10:26 +0200 Original-Received: from localhost ([::1]:52020 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WfDQ9-0000wr-GT for geb-bug-gnu-emacs@m.gmane.org; Tue, 29 Apr 2014 15:10:25 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46190) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WfDPx-0000le-Gx for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 15:10:22 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WfDPn-0000io-Qk for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 15:10:13 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:56272) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WfDPn-0000hx-Nw for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 15:10:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1WfDPm-0007c6-V1 for bug-gnu-emacs@gnu.org; Tue, 29 Apr 2014 15:10:03 -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:10:02 +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.139879857629225 (code B ref 17362); Tue, 29 Apr 2014 19:10:02 +0000 Original-Received: (at 17362) by debbugs.gnu.org; 29 Apr 2014 19:09:36 +0000 Original-Received: from localhost ([127.0.0.1]:45390 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WfDPL-0007bH-TF for submit@debbugs.gnu.org; Tue, 29 Apr 2014 15:09:36 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:20874) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WfDPJ-0007au-Kd for 17362@debbugs.gnu.org; Tue, 29 Apr 2014 15:09:34 -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 s3TJ9R5u021662 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 29 Apr 2014 19:09:27 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 s3TJ9Qfh028739 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Tue, 29 Apr 2014 19:09:26 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 s3TJ9Qv3003611; Tue, 29 Apr 2014 19:09:26 GMT In-Reply-To: <<834n1cm1bx.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:88452 Archived-At: > > > > > > from how Emacs itself communicates with users. AFAIK, Emacs > > > > > > writes for the Delete key etc. The rule for function > > > > > > keys and pseudo function keys has always been to use lowercase > > > > > > (in angle brackets), no? > > > > > > > > > > Yes, because they are symbols. I did nothing about symbols, of > > > > > course. > > > > > > > > What does that mean? > > > Which part is unclear? > > > > Apparently you agree that the rule for function keys is lowercase. > > Yet you leave some of them capitalized or uppercase? And the reason > > is because those that you make lowercase are symbols? >=20 > They are symbols used in Lisp code, whereas the other kind are words > used in the user documentation. I understand. Emacs itself speaks with one voice here, however, which is less confusing for users, IMO. Users, especially non-Lispers, should not be concerned with whether a given key name corresponds to a Lisp symbol. They should not need to know or guess that you call a key because you feel that "Delete" is sufficiently common as the name printed on the keyboard key, even though Emacs refers to that key as . 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) ). These are inconsistencies within the manual, IMO. They complicate understanding unnecessarily. It would be much clearer to refer to these keys, in key sequences, always as , , and . Nothing prevents the manual from also saying that such keys might be labeled "Delete", "<--" (using an actual arrow symbol in the manual), and "PageDown". But such names should not appear in key sequences - in the manual or anywhere else. > > > > Emacs writes . Why write ? Emacs writes > > > > . Why write Delete or ? > > > > > > See the guidelines I used to decide on names and capitalization, I > > > tried to explain why I choose this or that convention. > > > > The convention used should be the one that Emacs itself uses to > > write key sequences. >=20 > 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. > > > 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 sometimes > > and other times, and , and , > > and so on. >=20 > There should be only these variants in the manual: > >=20 > If you find others, please report them as documentation bugs. I tried > to fix them all, but maybe I missed some; it is a large manual. There are lots of occurrences of . And yes, it is a large manual. Keeping multiple representations only makes it more difficult for people to correct and maintain the manual, I'm guessing. Feel free to close this bug, and thanks for doing what fixing you have done. Every little bit helps.