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#3516: 23.0.94; function key names in Info Date: Tue, 12 Jul 2011 13:04:14 -0700 Message-ID: <9F8D92A1589E4FEBBD8FD4F9D357247A@us.oracle.com> References: <838vs3fq0t.fsf@gnu.org> <8362n7fmj4.fsf@gnu.org> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1310501492 24218 80.91.229.12 (12 Jul 2011 20:11:32 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Tue, 12 Jul 2011 20:11:32 +0000 (UTC) Cc: larsi@gnus.org, 3516@debbugs.gnu.org To: "'Eli Zaretskii'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Jul 12 22:11:28 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QgjIj-0000zR-T6 for geb-bug-gnu-emacs@m.gmane.org; Tue, 12 Jul 2011 22:11:26 +0200 Original-Received: from localhost ([::1]:52461 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QgjIi-0000LX-Uh for geb-bug-gnu-emacs@m.gmane.org; Tue, 12 Jul 2011 16:11:25 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:45183) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QgjCc-0007rG-QK for bug-gnu-emacs@gnu.org; Tue, 12 Jul 2011 16:05:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QgjCZ-0000tW-Po for bug-gnu-emacs@gnu.org; Tue, 12 Jul 2011 16:05:06 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:59989) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QgjCZ-0000sw-Fw for bug-gnu-emacs@gnu.org; Tue, 12 Jul 2011 16:05:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1QgjCY-0007dw-51; Tue, 12 Jul 2011 16:05:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 12 Jul 2011 20:05:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 3516 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: notabug Original-Received: via spool by 3516-submit@debbugs.gnu.org id=B3516.131050107929350 (code B ref 3516); Tue, 12 Jul 2011 20:05:02 +0000 Original-Received: (at 3516) by debbugs.gnu.org; 12 Jul 2011 20:04:39 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QgjCA-0007dL-Lg for submit@debbugs.gnu.org; Tue, 12 Jul 2011 16:04:39 -0400 Original-Received: from acsinet15.oracle.com ([141.146.126.227]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1QgjC7-0007d8-Tx for 3516@debbugs.gnu.org; Tue, 12 Jul 2011 16:04:36 -0400 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p6CK4QoE026875 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 12 Jul 2011 20:04:28 GMT Original-Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p6CK4N9w024326 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 12 Jul 2011 20:04:23 GMT Original-Received: from abhmt113.oracle.com (abhmt113.oracle.com [141.146.116.65]) by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p6CK4H71028319; Tue, 12 Jul 2011 15:04:17 -0500 Original-Received: from dradamslap1 (/10.159.41.211) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Tue, 12 Jul 2011 13:04:17 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <8362n7fmj4.fsf@gnu.org> X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 Thread-Index: AcxAtwe+M353WGttTcil+FL8T4EJiQADwctw X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090207.4E1CA8CC.0090:SCFMA922111,ss=1,re=-4.000,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Tue, 12 Jul 2011 16:05:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) 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:48769 Archived-At: > > > "@key{F1}" in Texinfo produces "" in Info, > > > without the single quotes. In the printed output it produces > > > something resembling a keyboard key with a label on it. > > > Taking these in quotes would be wrong, e.g. because then > > > "@kbd{C-x @key{RET}}" would produce `C-x `'' with nested > > > quotes which looks ugly. > > > > What you describe is an implementation problem (Texinfo, Info). > > Actually, no: _you_ are talking about implementation. No. I am talking only about the appearance in Info. > There are no quotes in the manual sources here, there are 2 different > markups: @kbd and @key. They are different because they express two > different entities: characters typed by the user on the keyboard as > opposed to a single special key named by its label. And the cases I referred to were about _key sequences_, not key names. If @kbd is what you use to represent a key sequence, that is, a sequence of input events, then presumably it should be @kbd that is used in the cases I'm referring to. I don't know or care about the proper Texinfo implementation/representation in order to get the correct Info representation, but you seem to be saying that @kbd is what should be used for key sequences: a sequence of chars typed by the user. I am not speaking about references to the _name_ of the key. I made that clear from the beginning. In those contexts would be appropriate. I am speaking about references to the key sequence `', that is, to the _use_ of the key. And yes, a single key press, whether `' or `M-a' or `a', is a key _sequence_ as much as is the doubleton sequence `C-x '. > The quotes in one of the cases are the Info way of _implementing_ > the @kbd markup. Note that the printed manual doesn't have these > quotes, because there @kbd produces slanted typeface that stands > out without any need to quote it. Likewise with the other formats > supported by the Texinfo package. Only the Info and the plain text > formats use quotes -- it's their _implementation_ of the @kbd markup. I am concerned only with the appearance in Info, as I've made clear several times. I do not know or care how it is implemented. I also do not care here how it appears in other media - this bug report is only about Info. > > What I describe is from a user point of view: the resulting > > appearance in the Info manual. > > There's nothing wrong with the appearance. It is inconsistent for the doubleton key sequence `C-x ' and the singleton key sequence `M-a' to be represented using quotes, but not the singleton key sequence `'. > > The point is that `' should be used. > > According to you. According to 25-year long practice of writing GNU > manuals, practice that is codified in the Texinfo manual (which is a > de-facto standard for writing GNU documentation), @key{RET} should be > used, and in Info it produces without quotes. You alone are talking about @key. From what you've said above about it, the occurrences I'm talking about should presumably use @kbd (?). But I do not pretend to say how you should write it in Texinfo. I'm only speaking to how it is represented in the final, Info, result. > If you want to request a change in the _implementation_ of @key in the > Info format, the place to request that is in the Texinfo mailing list, > not here. It is only you who are speaking about the implementation and Texinfo. I've been trying to draw your attention to the appearance in the Info manual, but you keep descending into Texinfo. > > The entire key sequence - whatever that key sequence is, > > should be in quotes, consistently, to indicate a key sequence. > > `C-x ' and `' both correspond to the same convention: > > put the sequence of keys in quotes. > > is not a key sequence, The return key, when expressed in terms of input events (that is, pressing the return key), is a _key sequence_. In that context it should be written as a key sequence: `'. When talking only about the _name_ of the return key (and not _use_ of the key that is named), we should write . Any number of keys can constitute a key sequence, including a single key. We can write `a b c' and we can write `a'; `C-x a' and `M-a' and `a'. Or as the Emacs manual (node `Keys') says: A "key sequence", or "key" for short, is a sequence of one or more input events that is meaningful as a unit. NB: _one_ or more, not two or more. Throughout Emacs and Emacs Lisp, a key sequence can have _one_ or more keys. There is nothing new or shocking about this. When expressed as a sequence of input events, a single key press is a key sequence. This is as true of the sequence `' as it is of the sequence `a'. > it's a single key named by its label. The return key is named by its label , just as the A key is named by its label A. When expressed as a key sequence these should be written `' and `A'. I am not talking about the name of the key; I'm talking about representing the key as _used_ (or bound), i.e., as a key sequence. > Again, the distinction between @kbd and @key is very basic. Please speak in terms of Info and not Texinfo. Better yet, speak in terms of (a) representation of a key sequence (a sequence of input events) vs (b) names of keys. We can speak about the name of a single key, and we can speak about a single key as a singleton sequence of input events. It is the latter I'm concerned about - I have no problem with our writing (without quotes) when we are referring to the name of the key and not to use of the key (an input event). > If you disagree with it, at least accept that this is widely used practice in > GNU documentation and is explicitly described in the Texinfo manual. > > IOW, this is how the GNU project documents its software, whether you > like it or not. And no amount of bugs filed against Emacs will be > able to change that. No one is trying to change any of the things you mention. The point is to write `' when we mean about _use_ of the return key, that is, when referring to the key _as a key sequence_ (input event). The singleton key sequence `' should be denoted the same way we denote the doubleton key sequence `C-x ' and the singleton key sequences `M-a' and `a'. We should use the same quoting convention, consistently, regardless of which keys are in a key sequence and regardless of whether it is a singleton or longer. This should be a no-brainer, but you are making a big deal out of it. See, for example, the Emacs manual, node `User Input': you can enter `M-a' by typing ` a'. You can enter `C-M-a' by typing ` C-a'. Here we correctly write ` a' and not `a' or a. Other occurrences of in the same paragraph refer to the key name: no single quotes. That is all correct, IMO. Similarly, the singleton key sequence `M-a' is correctly written using quotes. What I am saying is that, just as we write ` a' here, so should we write `C-x '. And when referring to a single-key sequence, `' and `'.