* bug#3516: 23.0.94; function key names in Info @ 2009-06-09 16:11 Drew Adams 2009-06-10 22:23 ` Eli Zaretskii 2011-07-12 12:47 ` Lars Magne Ingebrigtsen 0 siblings, 2 replies; 13+ messages in thread From: Drew Adams @ 2009-06-09 16:11 UTC (permalink / raw) To: emacs-pretest-bug emacs -Q C-h r g keys We see things like <F1>, <F2>, <RET>, and <ESC> without single quotes. Similarly, in other parts of the manual. Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'? We use `C-x <RET>' here, and we use `C-x', but not `<RET>'. Likewise, we use `<ESC>C-h' (which should be `<ESC> C-h', BTW), but not `<ESC>'. The notation used does not seem consistent. Why write "(`C-h' or <F1>)", instead of "(`C-h' or `<F1>')"? (This also has the side effect of not fontifying, in contexts where `...' is fontified.) In GNU Emacs 23.0.94.1 (i386-mingw-nt5.1.2600) of 2009-05-24 on SOFT-MJASON Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (3.4)' ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2009-06-09 16:11 bug#3516: 23.0.94; function key names in Info Drew Adams @ 2009-06-10 22:23 ` Eli Zaretskii 2009-06-10 22:33 ` Drew Adams 2011-07-12 12:47 ` Lars Magne Ingebrigtsen 1 sibling, 1 reply; 13+ messages in thread From: Eli Zaretskii @ 2009-06-10 22:23 UTC (permalink / raw) To: Drew Adams, 3516 > From: "Drew Adams" <drew.adams@oracle.com> > Date: Tue, 9 Jun 2009 09:11:07 -0700 > Cc: > Reply-To: Drew Adams <drew.adams@oracle.com>, 3516@emacsbugs.donarmstrong.com > > emacs -Q > C-h r > g keys > > We see things like <F1>, <F2>, <RET>, and <ESC> without single > quotes. Similarly, in other parts of the manual. > > Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'? > > We use `C-x <RET>' here, and we use `C-x', but not `<RET>'. Likewise, > we use `<ESC>C-h' (which should be `<ESC> C-h', BTW), but not `<ESC>'. > > The notation used does not seem consistent. > Why write "(`C-h' or <F1>)", instead of "(`C-h' or `<F1>')"? Please show here the Texinfo sources, not just the text from the Info manual. I'm not saying that all you report is necessarily correct, but it could be: ESC and RET are both characters and keys. In the character context, ESC and RET are correct, while in the key context, `<ESC>' and `<SPC>' are correct (the latter comes from @key, and I don't remember now whether @key produces the quotes in addition to <..>). ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2009-06-10 22:23 ` Eli Zaretskii @ 2009-06-10 22:33 ` Drew Adams 2009-06-11 10:42 ` Eli Zaretskii 0 siblings, 1 reply; 13+ messages in thread From: Drew Adams @ 2009-06-10 22:33 UTC (permalink / raw) To: 'Eli Zaretskii', 3516 > > emacs -Q > > C-h r > > g keys > > > > We see things like <F1>, <F2>, <RET>, and <ESC> without single > > quotes. Similarly, in other parts of the manual. > > > > Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'? > > > > We use `C-x <RET>' here, and we use `C-x', but not `<RET>'. > > Likewise, we use `<ESC>C-h' (which should be `<ESC> C-h', BTW), > > but not `<ESC>'. > > > > The notation used does not seem consistent. > > Why write "(`C-h' or <F1>)", instead of "(`C-h' or `<F1>')"? > > Please show here the Texinfo sources, not just the text from the Info > manual. I'm not saying that all you report is necessarily correct, > but it could be: ESC and RET are both characters and keys. In the > character context, ESC and RET are correct, while in the key context, > `<ESC>' and `<SPC>' are correct (the latter comes from @key, and I > don't remember now whether @key produces the quotes in addition to > <..>). I don't have the Texinfo sources. I'm just an Emacs user reporting what seems to be an Emacs bug - in Info. You are the Texinfo & Info expert, and you will know better than I what is the appropriate Texinfo coding. You decide, after looking over my bug report and the Texinfo sources or whatever. For my part, I was referring to (or trying to refer to) passages that talk about keys, not characters. To me, key sequences should be wrapped in `...', even when they have <...>. To me, the key sequence should be written `<SPC>' even if the character is written SPC. It sounds like that is what you're saying also. It is not, however, what I see in the manual in various places, such as the node I mentioned. ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2009-06-10 22:33 ` Drew Adams @ 2009-06-11 10:42 ` Eli Zaretskii 2009-06-11 15:33 ` Drew Adams 0 siblings, 1 reply; 13+ messages in thread From: Eli Zaretskii @ 2009-06-11 10:42 UTC (permalink / raw) To: Drew Adams; +Cc: 3516 > From: "Drew Adams" <drew.adams@oracle.com> > Date: Wed, 10 Jun 2009 15:33:50 -0700 > > > > We see things like <F1>, <F2>, <RET>, and <ESC> without single > > > quotes. Similarly, in other parts of the manual. > > > > > > Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'? > > > > > > We use `C-x <RET>' here, and we use `C-x', but not `<RET>'. > > > Likewise, we use `<ESC>C-h' (which should be `<ESC> C-h', BTW), > > > but not `<ESC>'. > > > > > > The notation used does not seem consistent. > > > Why write "(`C-h' or <F1>)", instead of "(`C-h' or `<F1>')"? > > > > Please show here the Texinfo sources, not just the text from the Info > > manual. I'm not saying that all you report is necessarily correct, > > but it could be: ESC and RET are both characters and keys. In the > > character context, ESC and RET are correct, while in the key context, > > `<ESC>' and `<SPC>' are correct (the latter comes from @key, and I > > don't remember now whether @key produces the quotes in addition to > > <..>). > > I don't have the Texinfo sources. > > I'm just an Emacs user reporting what seems to be an Emacs bug - in Info. You are more than "just a user", Drew, let's be honest. Anyway, at least provide these quotes with context. Grepping through Info files for "<SPC>" and the likes is no fun. Since you already look at the surrounding text, pasting it into the bug report should be easy. > For my part, I was referring to (or trying to refer to) passages that talk about > keys, not characters. To me, key sequences should be wrapped in `...', even when > they have <...>. To me, the key sequence should be written `<SPC>' even if the > character is written SPC. We use <ESC> and such likes for keyboard keys that are labeled with more than a single character. The issue here is to prevent confusion on the reader's part between a single key labeled "ESC" and a sequence of 3 keys E, S, C. When a key is labeled with a single character, this confusion cannot happen, so <..> is not used in that case, because it would just make the reading harder with no good reason. Likewise, key sequences such as C-k are not single keys, you actually use 2 or more keys to type them. So <..> is inappropriate in that context as well. Thus, single keys and key sequences get different markup. ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2009-06-11 10:42 ` Eli Zaretskii @ 2009-06-11 15:33 ` Drew Adams 0 siblings, 0 replies; 13+ messages in thread From: Drew Adams @ 2009-06-11 15:33 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: 3516 > > > Please show here the Texinfo sources, > Anyway, at least provide these quotes with context. I don't have the context anymore, beyond what I originally reported: emacs -Q C-h r g keys That provides the context of at least one node that appears to have problematic occurrences. (See also bug #3508, which identified other such contexts.) > Grepping through Info files for "<SPC>" and the likes is no fun. ... for anyone. Likewise, C-s searching for "<[-_a-zA-Z]+>" or some such. > > For my part, I was referring to (or trying to refer to) passages > > that talk about keys, not characters. To me, key sequences > > should be wrapped in `...', even when they have <...>. To me, > > the key sequence should be written `<SPC>' even if the > > character is written SPC. > > We use <ESC> and such likes for keyboard keys that are labeled with > more than a single character. You know the conventions we use better than I, Eli. For my part, there is a difference between three things: 1. character: ESC, SPC 2. physical keyboard key (e.g. labeled): Esc, Page Up (not sure how Emacs denotes these) 3. key sequence: `<ESC>', `<SPC>', `<prior>' What I'm referring to is #3. I believe that was the sense intended in the doc here. It is the sense that is meant in most occurrences in the doc, in any case. I have no problem with #1 and #2 being written without `...'. It is cases of #3 that I'm concerned about. If you look at node `Keys', for instance, I believe that the occurrences of <ESC> should really be `<ESC>', since they refer to key sequences, not to characters or physical keys. [I wouldn't propose changing notations now, but I will point out that if we used a very different notation for each of #1, 2, 3 there might be less confusion. For instance, if we used `<space>' and `<escape>' for key sequences (as we do for `<prior>'), Esc, Page Up, and Space Bar for key names, and SPC and ESC for characters. Or some other such more obvious difference.] > The issue here is to prevent confusion > on the reader's part between a single key labeled "ESC" and a sequence > of 3 keys E, S, C. If you mean the physical key labeled "Esc" or "Escape", then I think we write that as ESC. If you mean the key sequence (i.e. hitting that physical key), then I think we write that `<ESC>'. If you mean the key sequence of hitting the keys E, S, C, in order, then I think we write that `E S C'. But again, you're the expert here, not I. I'm just pointing out that there seem to be places where we mean the key sequence `<ESC>', `<RET>' etc. but we have (mistakenly) written the key name ESC, RET etc. Or else we have written (incorrectly, IMO) the hybrid form <ESC>, <RET>, when we mean the key sequence. See bug #3508, for instance: DA>>> Similarly, <SPC> should be `<SPC>'. DA>>> Similarly, <TAB> should be `<TAB>' (in node CDLaTeX mode). CY>> This is not necessary. With few exceptions, we leave don't CY>> enclose @key in @kbd if it's the only key in the key sequence. DA> I don't think that's true. We write `i', not i, for command DA> `Info-index'. That's the general notation rule, and we DA> respect it generally. I think that what Yidong is saying is wrong, but that's my opinion - I can't speak for what the established convention is. The convention _should_ be consistent, IMO: _always_ use `...' for a key sequence. There is enough confusion between #1, 2, and 3 (above) due to similar names (char ESC, physical key ESC, key sequence ESC), without using a hybrid notation that encourages further confusion. > When a key is labeled with a single character, this confusion cannot > happen, so <..> is not used in that case, because it would just make > the reading harder with no good reason. Even for a key labeled with a single character, we generally do (and always should IMO) denote the key sequence using `...': `g', not g for `Info-goto-node'. > Likewise, key sequences such as C-k are not single keys, you actually > use 2 or more keys to type them. So <..> is inappropriate in that > context as well. Sure, but for the key sequence, we wrap with `...': `C-k', `<prior>', `<ESC>'. > Thus, single keys and key sequences get different markup. When you say "key" there is an ambiguity. You could be referring to the physical key (e.g. labeled "Page Up") or to the key sequence - the act of hitting the physical key. Yes, it's handy to sometimes use "keys" as a shortcut for "key sequences" - I don't have a problem with that generally. But in a context where we might be talking also about physical keys (or about characters), we need to carefully distinguish. Distinct notation helps distinguish. ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2009-06-09 16:11 bug#3516: 23.0.94; function key names in Info Drew Adams 2009-06-10 22:23 ` Eli Zaretskii @ 2011-07-12 12:47 ` Lars Magne Ingebrigtsen 2011-07-12 16:00 ` Eli Zaretskii 1 sibling, 1 reply; 13+ messages in thread From: Lars Magne Ingebrigtsen @ 2011-07-12 12:47 UTC (permalink / raw) To: Drew Adams; +Cc: 3516 "Drew Adams" <drew.adams@oracle.com> writes: > We see things like <F1>, <F2>, <RET>, and <ESC> without single > quotes. Similarly, in other parts of the manual. > > Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'? That might be argued, but the difference you're seeing is the difference between these two markups: @kbd{C-h} @key{F1} So I think this is done on purpose, and isn't a bug. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog http://lars.ingebrigtsen.no/ ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2011-07-12 12:47 ` Lars Magne Ingebrigtsen @ 2011-07-12 16:00 ` Eli Zaretskii 2011-07-12 16:38 ` Drew Adams 0 siblings, 1 reply; 13+ messages in thread From: Eli Zaretskii @ 2011-07-12 16:00 UTC (permalink / raw) To: Lars Magne Ingebrigtsen; +Cc: 3516 > From: Lars Magne Ingebrigtsen <larsi@gnus.org> > Date: Tue, 12 Jul 2011 14:47:09 +0200 > Cc: 3516@debbugs.gnu.org > > "Drew Adams" <drew.adams@oracle.com> writes: > > > We see things like <F1>, <F2>, <RET>, and <ESC> without single > > quotes. Similarly, in other parts of the manual. > > > > Shouldn't those be `<f1>', `<f2>', `<RET>', and `<ESC>'? > > That might be argued, but the difference you're seeing is the difference > between these two markups: > > @kbd{C-h} > @key{F1} Yes, that's true. "@key{F1}" in Texinfo produces "<F1>" 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 `<RET>'' with nested quotes which looks ugly. ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2011-07-12 16:00 ` Eli Zaretskii @ 2011-07-12 16:38 ` Drew Adams 2011-07-12 17:15 ` Eli Zaretskii 0 siblings, 1 reply; 13+ messages in thread From: Drew Adams @ 2011-07-12 16:38 UTC (permalink / raw) To: 'Eli Zaretskii', 'Lars Magne Ingebrigtsen'; +Cc: 3516 > "@key{F1}" in Texinfo produces "<F1>" 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 `<RET>'' with nested quotes which looks ugly. What you describe is an implementation problem (Texinfo, Info). What I describe is from a user point of view: the resulting appearance in the Info manual. No one is suggesting that `C-x `<RET>'' should be used. The point is that `<RET>' should be used. The entire key sequence - whatever that key sequence is, should be in quotes, consistently, to indicate a key sequence. `C-x <RET>' and `<RET>' both correspond to the same convention: put the sequence of keys in quotes. We don't write just i - we write `i' when we want to refer to the key sequence consisting of just the i key. And we write `C-x i' when we want to refer to the sequence of the C-x key followed by the i key. And we write `C-x <RET>' to refer to the sequence of the C-x key followed by the <RET> key. Why should we write <RET> for the key sequence `<RET>'? ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2011-07-12 16:38 ` Drew Adams @ 2011-07-12 17:15 ` Eli Zaretskii 2011-07-12 20:04 ` Drew Adams 0 siblings, 1 reply; 13+ messages in thread From: Eli Zaretskii @ 2011-07-12 17:15 UTC (permalink / raw) To: Drew Adams; +Cc: larsi, 3516 > From: "Drew Adams" <drew.adams@oracle.com> > Cc: <3516@debbugs.gnu.org> > Date: Tue, 12 Jul 2011 09:38:24 -0700 > > > "@key{F1}" in Texinfo produces "<F1>" 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 `<RET>'' with nested quotes which looks ugly. > > What you describe is an implementation problem (Texinfo, Info). Actually, no: _you_ are talking about implementation. 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. 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. > What I describe is from a user point of view: the resulting appearance in the > Info manual. There's nothing wrong with the appearance. > The point is that `<RET>' 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 <RET> without quotes. 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. > The entire key sequence - whatever that key sequence is, should be in quotes, > consistently, to indicate a key sequence. `C-x <RET>' and `<RET>' both > correspond to the same convention: put the sequence of keys in quotes. <RET> is not a key sequence, it's a single key named by its label. Again, the distinction between @kbd and @key is very basic. 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. ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2011-07-12 17:15 ` Eli Zaretskii @ 2011-07-12 20:04 ` Drew Adams 2011-07-12 20:30 ` Eli Zaretskii 0 siblings, 1 reply; 13+ messages in thread From: Drew Adams @ 2011-07-12 20:04 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: larsi, 3516 > > > "@key{F1}" in Texinfo produces "<F1>" 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 `<RET>'' 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 <RET> would be appropriate. I am speaking about references to the key sequence `<RET>', that is, to the _use_ of the key. And yes, a single key press, whether `<RET>' or `M-a' or `a', is a key _sequence_ as much as is the doubleton sequence `C-x <RET>'. > 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 <RET>' and the singleton key sequence `M-a' to be represented using quotes, but not the singleton key sequence `<RET>'. > > The point is that `<RET>' 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 <RET> 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 <RET>' and `<RET>' both correspond to the same convention: > > put the sequence of keys in quotes. > > <RET> 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: `<RET>'. When talking only about the _name_ of the return key (and not _use_ of the key that is named), we should write <RET>. 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 `<RET>' as it is of the sequence `a'. > it's a single key named by its label. The return key is named by its label <RET>, just as the A key is named by its label A. When expressed as a key sequence these should be written `<RET>' 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 <RET> (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 `<RET>' 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 `<RET>' should be denoted the same way we denote the doubleton key sequence `C-x <RET>' 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 `<ESC> a'. You can enter `C-M-a' by typing `<ESC> C-a'. Here we correctly write `<ESC> a' and not <ESC> `a' or <ESC> a. Other occurrences of <ESC> 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 `<ESC> a' here, so should we write `C-x <RET>'. And when referring to a single-key sequence, `<RET>' and `<ESC>'. ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2011-07-12 20:04 ` Drew Adams @ 2011-07-12 20:30 ` Eli Zaretskii 2011-07-12 21:03 ` Drew Adams 0 siblings, 1 reply; 13+ messages in thread From: Eli Zaretskii @ 2011-07-12 20:30 UTC (permalink / raw) To: Drew Adams; +Cc: larsi, 3516 > From: "Drew Adams" <drew.adams@oracle.com> > Cc: <larsi@gnus.org>, <3516@debbugs.gnu.org> > Date: Tue, 12 Jul 2011 13:04:14 -0700 > > > > 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. The appearance in Info _is_ implementation. > And the cases I referred to were about _key sequences_, not key names. Go back and re-read your report. Then look up the corresponding portions of the manual, and you will see that <RET>, <F1> etc. are used in the context that names keys by their names. If you are saying that sometimes <..> is used where we talk about keyboard input, then please point out specific instances where that happens, instead of making a general observation. As a general observation, what you say is incorrect. > 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. Which cases, specifically? Your reference is to an entire node. > I am not speaking about references to the _name_ of the key. I made that clear > from the beginning. You made nothing clear about that, till now. > In those contexts <RET> would be appropriate. Thank you! We have hope! > I am speaking about references to the key sequence `<RET>', that is, to the > _use_ of the key. "use" is a grey area. What about the following sentence: To end a line, press the <RET> key. ? Are we naming a key by its label or are we talking about a "key sequence"? > > > The point is that `<RET>' 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 <RET> 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 (?). @kbd{@key{..}} > 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 don't understand Texinfo and don't care about the other output formats, your report is not of much use, because changes to the manual _must_ consider all supported forms of output. > The return key is named by its label <RET>, just as the A key is named by its > label A. Not "just". There's a fundamental difference: "A" is a key and a character; <RET> is "just" a key. > > Again, the distinction between @kbd and @key is very basic. > > Please speak in terms of Info and not Texinfo. No. > This should be a no-brainer, but you are making a big deal out of it. Yeah, right. _I_ am making a big deal. > you can enter `M-a' by typing `<ESC> a'. > You can enter `C-M-a' by typing `<ESC> C-a'. > > Here we correctly write `<ESC> a' and not <ESC> `a' or <ESC> a. When it's clearly part of a sequence of inputs, yes. > Other occurrences of <ESC> 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 `<ESC> a' here, so should we write > `C-x <RET>'. And when referring to a single-key sequence, `<RET>' and `<ESC>'. Exactly where? Be specific, if you want any result other than "wontfix". ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2011-07-12 20:30 ` Eli Zaretskii @ 2011-07-12 21:03 ` Drew Adams 2011-07-13 3:00 ` Eli Zaretskii 0 siblings, 1 reply; 13+ messages in thread From: Drew Adams @ 2011-07-12 21:03 UTC (permalink / raw) To: 'Eli Zaretskii'; +Cc: larsi, 3516 > > > > 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. > > The appearance in Info _is_ implementation. When you look at it only as an implementor, perhaps. Try to take an Info reader point of view. > > I am not speaking about references to the _name_ of the key. > > I made that clear from the beginning. > > You made nothing clear about that, till now. Yes, I did, by speaking about "key sequence". > > I am speaking about references to the key sequence `<RET>', > > that is, to the _use_ of the key. > > "use" is a grey area. What about the following sentence: > > To end a line, press the <RET> key. It's fine, as shorthand for "press the key named <RET>". <RET> is the name of the key. But it is also fine to write "press `<RET>'". Here we are using the name to refer to the key sequence, that is, the key. We are saying press the key. We are saying the same thing as "press the key named <RET>". IOW, if we refer to that key-pressing action using the Emacs key-sequence notation, we say "press `<RET>'" or similar. `<RET>' refers to using the key named <RET> in an input sequence. > Are we naming a key by its label or are we talking about a "key > sequence"? See above. We can say either. It depends whether what is important is the key sequence or the name of the key. If we want to talk about the name, then <RET>; if we want to talk about the input (key) sequence then `<RET>'. > If you don't understand Texinfo and don't care about the other output > formats, your report is not of much use, because changes to the manual > _must_ consider all supported forms of output. You consider them, then. I reported the bug. I'm not proposing what internal coding to fix it with, i.e., to get the proper appearance in Info. > > you can enter `M-a' by typing `<ESC> a'. > > You can enter `C-M-a' by typing `<ESC> C-a'. > > > > Here we correctly write `<ESC> a' and not <ESC> `a' or <ESC> a. > > When it's clearly part of a sequence of inputs, yes. Thank you. Now please go DTRT. That's what this bug report is about. In Emacs we have a conventional way to represent an input sequence of key presses (and other input events, including mouse clicks etc.): we put the key names, in order, between single quotes: `...'. We call such an input sequence a "key sequence". We speak of a key sequence whenever we refer to such an input sequence, including in the context of key bindings: "this command is bound to the key sequence `M-x'." This is as true for a key named <RET> as it is for any other key. When referring to it in the context of a key sequence it should be between single quotes. ^ permalink raw reply [flat|nested] 13+ messages in thread
* bug#3516: 23.0.94; function key names in Info 2011-07-12 21:03 ` Drew Adams @ 2011-07-13 3:00 ` Eli Zaretskii 0 siblings, 0 replies; 13+ messages in thread From: Eli Zaretskii @ 2011-07-13 3:00 UTC (permalink / raw) To: Drew Adams; +Cc: larsi, 3516 > From: "Drew Adams" <drew.adams@oracle.com> > Cc: <larsi@gnus.org>, <3516@debbugs.gnu.org> > Date: Tue, 12 Jul 2011 14:03:19 -0700 > > > To end a line, press the <RET> key. > > It's fine, as shorthand for "press the key named <RET>". > <RET> is the name of the key. > > But it is also fine to write "press `<RET>'". So we are taking the former view and using just <RET>. > Thank you. Now please go DTRT. That's what this bug report is about. I don't see any bug, so there's no RTTD except leave the bug report closed. I asked for specific pointers to where the usage is incorrect, but you declined (in so many words). So that's it. ^ permalink raw reply [flat|nested] 13+ messages in thread
end of thread, other threads:[~2011-07-13 3:00 UTC | newest] Thread overview: 13+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2009-06-09 16:11 bug#3516: 23.0.94; function key names in Info Drew Adams 2009-06-10 22:23 ` Eli Zaretskii 2009-06-10 22:33 ` Drew Adams 2009-06-11 10:42 ` Eli Zaretskii 2009-06-11 15:33 ` Drew Adams 2011-07-12 12:47 ` Lars Magne Ingebrigtsen 2011-07-12 16:00 ` Eli Zaretskii 2011-07-12 16:38 ` Drew Adams 2011-07-12 17:15 ` Eli Zaretskii 2011-07-12 20:04 ` Drew Adams 2011-07-12 20:30 ` Eli Zaretskii 2011-07-12 21:03 ` Drew Adams 2011-07-13 3:00 ` Eli Zaretskii
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).