GNU bug report logs - #17362
24.4.50; inconsistent key notation: `ESC' vs `<ESC>'

Previous Next

Full log

Message #52 received at 17362 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 17362 <at> debbugs.gnu.org, dmoncayo <at> gmail.com
Subject: Re: bug#17362: 24.4.50; inconsistent key notation: `ESC' vs `<ESC>'
Date: Tue, 29 Apr 2014 22:20:20 +0300

> Date: Tue, 29 Apr 2014 12:09:25 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> Cc: dmoncayo <at> gmail.com, 17362 <at> debbugs.gnu.org
> 
> And you write <left>, using the Lisp symbol name `left', because what
> is printed on the keyboard key is an arrow, not "Left".  And yet for
> <next>, the manual refers to it as both <next> and <PageDown> (in
> Emacs 20 it was referred to as (only) <NEXT>).

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.

> These are inconsistencies within the manual, IMO.  They complicate
> understanding unnecessarily.

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".

> > 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.

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.  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.

> > > > 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 <BACKSPACE> sometimes
> > > and <Backspace> other times, <DELETE> and <Delete>, <left> and <Home>,
> > > and so on.
> > 
> > There should be only these variants in the manual:
> >   <BACKSPACE>  <Delete>  <left> <Home>

Sorry, that was incorrect: it should be <LEFT>, in all caps.  The
others are correct.

> > 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 <Backspace>.

Before my changes, yes.  Now I see only one, in the Glossary.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.