GNU bug report logs - #3801
23.0.96; Emacs manual: add index entry for "notation, keys" or "key notation"

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 3801 in the body.
You can then email your comments to 3801 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <emacs-pretest-bug <at> gnu.org>
Subject: 23.0.96; Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Thu, 9 Jul 2009 14:19:30 -0700

I tried looking for the place in the Emacs manual where the notation
for key sequences (the one used in the doc) is described. I tried
`notation' and found there was only one match:
`gdb-use-colon-colon-notation'. Users should be able to find this by
looking for terms such as `notation' and `conventions'.
 

In GNU Emacs 23.0.96.1 (i386-mingw-nt5.1.2600)
 of 2009-07-09 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: bugs <at> gnus.org, 3801 <at> debbugs.gnu.org
Subject: Re: 23.0.96;
	Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Tue, 12 Jul 2011 17:24:02 +0200

"Drew Adams" <drew.adams <at> oracle.com> writes:

> I tried looking for the place in the Emacs manual where the notation
> for key sequences (the one used in the doc) is described. I tried
> `notation' and found there was only one match:
> `gdb-use-colon-colon-notation'. Users should be able to find this by
> looking for terms such as `notation' and `conventions'.

In what circumstances does Emacs talk about notations for key sequences? 

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bugs <at> gnus.org>
Cc: 3801 <at> debbugs.gnu.org
Subject: RE: 23.0.96;
	Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Tue, 12 Jul 2011 09:27:55 -0700

> > I tried looking for the place in the Emacs manual where the notation
> > for key sequences (the one used in the doc) is described. I tried
> > `notation' and found there was only one match:
> > `gdb-use-colon-colon-notation'. Users should be able to find this by
> > looking for terms such as `notation' and `conventions'.
> 
> In what circumstances does Emacs talk about notations for key 
> sequences? 

The conventions used in the doc should be described.  They are, for the Elisp
manual: see node `Conventions' and its subnodes.  See how detailed those nodes
are, and how well they explain the notations used in the Elisp manual.

The Emacs manual should also describe the notations it uses.  In particular,
key-sequence notation.

There should be a description of how the manual indicates key sequences,
including for different kinds of keys (e.g. angle-bracket notation vs no angle
brackets).

If there is not yet such a desciption, it should be added.  And then it should
be indexed (this bug report).

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: bugs <at> gnus.org, 3801 <at> debbugs.gnu.org
Subject: Re: bug#3801: 23.0.96;
	Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Tue, 12 Jul 2011 20:51:10 +0300

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Date: Tue, 12 Jul 2011 09:27:55 -0700
> Cc: 3801 <at> debbugs.gnu.org
> 
> There should be a description of how the manual indicates key sequences,
> including for different kinds of keys (e.g. angle-bracket notation vs no angle
> brackets).

I think you are looking for "User Input" and "Keys" nodes.

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: bug-gnu-emacs <at> gnu.org
Subject: Re: bug#3801: 23.0.96;
	Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Tue, 12 Jul 2011 21:35:17 +0200

Eli Zaretskii <eliz <at> gnu.org> writes:

> I think you are looking for "User Input" and "Keys" nodes.

Yes, I can't remember "notation" as a word people use for keys.

Closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>, <3801 <at> debbugs.gnu.org>
Subject: RE: bug#3801: 23.0.96;
	Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Tue, 12 Jul 2011 13:25:08 -0700

> > I think you are looking for "User Input" and "Keys" nodes.
> 
> Yes, I can't remember "notation" as a word people use for keys.
> 
> Closing this bug report.

It's not about anyone using "notation" as a word for keys.

It's about being able to easily locate the notational conventions we use in our
manuals.

As I said, contrast the case of the Elisp manual.

In the Elisp manual too we should probably add "notational conventions" as an
index entry, in addition to the existing entry "typographical conventions"
(which takes you to node `Some Terms', a subnode of node `Conventions').

But in that manual (Elisp) things are much clearer because of this top-level
table of contents entry:

 `Conventions' - How the manual is formatted

There is no similar organization for the Emacs manual, and consequently it is
more difficult to find a presentation of "how the manual is formatted".

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Eli Zaretskii'" <eliz <at> gnu.org>
Cc: bugs <at> gnus.org, 3801 <at> debbugs.gnu.org
Subject: RE: bug#3801: 23.0.96;
	Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Tue, 12 Jul 2011 13:25:10 -0700

> > There should be a description of how the manual indicates 
> > key sequences, including for different kinds of keys (e.g.
> > angle-bracket notation vs no angle brackets).
> 
> I think you are looking for "User Input" and "Keys" nodes.

Yes and no.  Yes, those nodes speak about keys, and they _use_ the notational
conventions defined for the manual.

But no, those nodes do not _present_ (introduce, describe, explain) the
notational conventions that are used.

I don't see any place in the Emacs manual where we introduce the notational
conventions used.  Contrast that with the Elisp manual, where we go into quite a
bit of detail about the notation used in the manual.

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: bugs <at> gnus.org, 3801 <at> debbugs.gnu.org
Subject: Re: bug#3801: 23.0.96;
	Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Tue, 12 Jul 2011 23:33:29 +0300

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: <bugs <at> gnus.org>, <3801 <at> debbugs.gnu.org>
> Date: Tue, 12 Jul 2011 13:25:10 -0700
> 
> I don't see any place in the Emacs manual where we introduce the notational
> conventions used.

Right.  It doesn't do that.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Eli Zaretskii'" <eliz <at> gnu.org>
Cc: bugs <at> gnus.org, 3801 <at> debbugs.gnu.org
Subject: RE: bug#3801: 23.0.96;
	Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Tue, 12 Jul 2011 14:16:23 -0700

> > I don't see any place in the Emacs manual where we 
> > introduce the notational conventions used.
> 
> Right.  It doesn't do that.

Glad we agree.  That's the bug.  Please introduce the conventions and then index
that doc.

Message #42 received at 3801-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 3801-done <at> debbugs.gnu.org, bugs <at> gnus.org
Subject: Re: bug#3801: 23.0.96;
	Emacs manual: add index entry for "notation, keys" or "key notation"
Date: Wed, 13 Jul 2011 05:53:57 +0300

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Cc: <bugs <at> gnus.org>, <3801 <at> debbugs.gnu.org>
> Date: Tue, 12 Jul 2011 14:16:23 -0700
> 
> > > I don't see any place in the Emacs manual where we 
> > > introduce the notational conventions used.
> > 
> > Right.  It doesn't do that.
> 
> Glad we agree.  That's the bug.

Not necessarily.  It's marked "notabug".

Previous Next

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