GNU bug report logs - #8904
24.0.50; describe `describe-prefix-bindings' in Emacs manual

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 8904 in the body.
You can then email your comments to 8904 AT debbugs.gnu.org in the normal way.

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

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 24.0.50; describe `describe-prefix-bindings' in Emacs manual
Date: Mon, 20 Jun 2011 10:08:55 -0700

Consider mentioning command `describe-prefix-bindings' in the Emacs
manual.  It is mentioned only in the Elisp manual, but it is for users
(interactive).
 

In GNU Emacs 24.0.50.1 (i386-mingw-nt5.1.2600)
 of 2011-06-13 on 3249CTO
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.5) --no-opt --cflags
-Ic:/build/include'
 

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8904 <at> debbugs.gnu.org
Subject: Re: 24.0.50; describe `describe-prefix-bindings' in Emacs manual
Date: Fri, 15 Jul 2011 16:21:29 +0200

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

> Consider mentioning command `describe-prefix-bindings' in the Emacs
> manual.  It is mentioned only in the Elisp manual, but it is for users
> (interactive).

Why is that function interactive?  I mean, how could it be used
interactively?

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

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

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
Cc: 8904 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#8904: 24.0.50;
	describe `describe-prefix-bindings' in Emacs manual
Date: Fri, 15 Jul 2011 17:20:18 +0200

Lars Magne Ingebrigtsen <larsi <at> gnus.org> writes:

> Why is that function interactive?  I mean, how could it be used
> interactively?

Just how it is used now.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: Andreas Schwab <schwab <at> linux-m68k.org>
Cc: 8904 <at> debbugs.gnu.org, Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#8904: 24.0.50;
	describe `describe-prefix-bindings' in Emacs manual
Date: Fri, 15 Jul 2011 17:26:33 +0200

Andreas Schwab <schwab <at> linux-m68k.org> writes:

>> Why is that function interactive?  I mean, how could it be used
>> interactively?
>
> Just how it is used now.

I've only used it once, and this is how that went:

`M-x describe-prefix-bindings'

Global Bindings Starting With M-x d e s c r i b e - p r e f i x - b i n d i n g s:
key             binding
---             -------

[back]

I was not enlightened.

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

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>,
	"'Andreas Schwab'" <schwab <at> linux-m68k.org>
Cc: 8904 <at> debbugs.gnu.org
Subject: RE: bug#8904: 24.0.50;
	describe `describe-prefix-bindings' in Emacs manual
Date: Fri, 15 Jul 2011 08:40:32 -0700

> I was not enlightened.

Lars, you need better doc for this command. ;-)  Seriously.

To enlighten yourself and thus help in coming up with that doc:

1. See what the Elisp manual says, as the bug report indicated.
2. Consult the code, in help.el.

In #2 you will see this:

;; Make C-h after a prefix, when not specifically bound,
;; run describe-prefix-bindings.
(setq prefix-help-command 'describe-prefix-bindings)

Maybe this will help you see why code comments are not substitutes for doc
strings.  Had appropriate info been available to you interactively via `C-h f
describe-prefix-bindings' you would not have needed to ask others or consult the
code.

Now try it:

C-x C-h
C-x RET C-h
M-s C-h
...

Another lesson learned: Not every command is designed to work best with `M-x'.

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

From: Lars Magne Ingebrigtsen <larsi <at> gnus.org>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 8904 <at> debbugs.gnu.org, 'Andreas Schwab' <schwab <at> linux-m68k.org>
Subject: Re: bug#8904: 24.0.50;
	describe `describe-prefix-bindings' in Emacs manual
Date: Fri, 15 Jul 2011 17:48:18 +0200

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

> Lars, you need better doc for this command. ;-)  Seriously.

Or better bug reports.

I've now added `describe-prefix-bindings' to the "Misc Help" node in the
Emacs manual.

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

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 8904 <at> debbugs.gnu.org,
	"'8904 <at> debbugs.gnu.org \"'Andreas Schwab'\"'" <schwab <at> linux-m68k.org>
Subject: RE: bug#8904: 24.0.50;
	describe `describe-prefix-bindings' in Emacs manual
Date: Fri, 15 Jul 2011 09:05:19 -0700

> > Lars, you need better doc for this command. ;-)  Seriously.
> 
> Or better bug reports.

It's not up to a bug report to teach what the function does or how it's
implemented or used.

This bug report was to say that this is not sufficiently documented.

> I've now added `describe-prefix-bindings' to the "Misc Help" 
> node in the Emacs manual.

Thanks.

Hopefully you added some of the info I provided that helped you understand, so
that other users will also understand.  Likewise for the doc string (and perhaps
for the text in the Elisp manual too).

The goal should be for someone like Lars to be able to understand this function
by reading its doc: what it's for, how to use it, what it does.

Previous Next

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