bug#8904: 24.0.50; describe `describe-prefix-bindings' in Emacs manual

bug#8904: 24.0.50; describe `describe-prefix-bindings' in Emacs manual

[Drew Adams]

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'
 

bug#8904: 24.0.50; describe `describe-prefix-bindings' in Emacs manual

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#8904: 24.0.50; describe `describe-prefix-bindings' in Emacs manual

[Andreas Schwab]

Lars Magne Ingebrigtsen <larsi@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@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#8904: 24.0.50; describe `describe-prefix-bindings' in Emacs manual

[Lars Magne Ingebrigtsen]

Andreas Schwab <schwab@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/

bug#8904: 24.0.50; describe `describe-prefix-bindings' in Emacs manual

[Drew Adams]

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

bug#8904: 24.0.50; describe `describe-prefix-bindings' in Emacs manual

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@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/

bug#8904: 24.0.50; describe `describe-prefix-bindings' in Emacs manual

[Drew Adams]

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