describe-bindings: ^L, bad order, naming

describe-bindings: ^L, bad order, naming

[David Reitter]

[-- Attachment #1.1: Type: text/plain, Size: 1398 bytes --]

describe-bindings separates the different groups with  ^L even though  
the text that is output is intended to be human-readable.

Isn't there a nicer way the groups can be separated?

I also get a long list with latin key characters that are bound to  
encoded-kbd-self-insert-ccl.
That's rather annoying. If this needs to be listed (why?), it should  
come at the end.
As a novice user when trying out the describe-bindings function, I  
would see that there is a lot of uninteresting technical stuff at the  
beginning, so I would get rid of the window and try something else  
(like annoying people with questions in news groups...).
And that happens with a function that is of great use, especially to  
new Emacs users.

Couldn't there be a list of all groups in the beginning, with links  
going to the bindings belonging to the group?
Or ideally, a list of all groups with a widget on each group that  
expands the group to show the full list of bindings?


Lastly, I was wondering if one could use a better name for the menu  
item.
"List Key Bindings" is of course perfectly correct from an Emacs  
terminology point of view. But as a new user, I would be looking for  
something like "Keyboard Functions" or "Keyboard Shortcuts" or so,  
not for "Bindings".

The Help menu is really important and useful to newbies. It would be  
very helpful if one could make it easier to understand.


[-- Attachment #1.2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 2400 bytes --]

[-- Attachment #2: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    describe-bindings separates the different groups with  ^L even though
    the text that is output is intended to be human-readable.

    Isn't there a nicer way the groups can be separated?

    I also get a long list with latin key characters that are bound to
    encoded-kbd-self-insert-ccl.
    That's rather annoying. If this needs to be listed (why?), it should
    come at the end.
    As a novice user when trying out the describe-bindings function, I
    would see that there is a lot of uninteresting technical stuff at the
    beginning, so I would get rid of the window and try something else
    (like annoying people with questions in news groups...).
    And that happens with a function that is of great use, especially to
    new Emacs users.

    Couldn't there be a list of all groups in the beginning, with links
    going to the bindings belonging to the group?
    Or ideally, a list of all groups with a widget on each group that
    expands the group to show the full list of bindings?

    Lastly, I was wondering if one could use a better name for the menu
    item.
    "List Key Bindings" is of course perfectly correct from an Emacs
    terminology point of view. But as a new user, I would be looking for
    something like "Keyboard Functions" or "Keyboard Shortcuts" or so,
    not for "Bindings".

    The Help menu is really important and useful to newbies. It would be
    very helpful if one could make it easier to understand.

Good suggestions, all.

I wonder a bit about the last suggestion, however. It's true that menu items
are the one place where we've substituted some common terminology (e.g.
Paste) for Emacs jargon (e.g. Yank), but I'm not sure if the intention was
to do this everywhere in Emacs menus.

Clearest might be a short description that bridges the two namings - e.g.
"Paste (Yank)", but again, should we do that everywhere? It could be
cumbersome and overly complex. In the present case we might use "List
Keyboard Shortcuts (Bindings)", but that is a bit long.

I think "Keyboard Functions" is incorrect in this context, in any case.

One possibility, similar to the approach taken with CUA (IIUC), would be to
make the treatment configurable. Have a translation table between
Emacs-jargon names and conventional names, and provide a user option for
using one or the other (in menus). That might be heavy-handed for
maintenance, but it would also be convenient for some users. Users of the
conventional names would still need to make the transition at some point, of
course (e.g. when reading the manual). And this would open the door to the
possibility of menu translation for other languages... (=> can of worms).

Beyond menu-item names, I think the intention was that synonyms would be
introduced in the Emacs manual. If it is not already there, "keyboard
shortcut" could be added as a synonym for "key binding". The notion of
binding a command to a key sequence is important to understanding Emacs, so
it cannot be skipped over. But there's nothing wrong with also mentioning
that the bound key sequences are sometimes referred to elsewhere as
"keyboard shortcuts".

There is also the ternminology problem discussed recently of "key" sequences
(and bindings) not necessarily involving keyboard keys...

Anyway, I didn't mean to distract from your suggestions. It would be good if
some of them could be implemented before the release - in particular, adding
top-level links to sections and moving the encoded-kbd-self-insert-ccl stuff
to the back burner.

Re: describe-bindings: ^L, bad order, naming

[Lennart Borgman]

Drew Adams wrote:

>Good suggestions, all.
>  
>
I agree, David's points are good.

>In the present case we might use "List
>Keyboard Shortcuts (Bindings)", but that is a bit long.
>  
>
I would go for just "Keyboard Shortcuts". In the displayed help text it 
could say "Keyboard Shortcuts (Bindings)" or explain the terminology in 
another way. But keep the menus clean for the novice.

>Anyway, I didn't mean to distract from your suggestions. It would be good if
>some of them could be implemented before the release - in particular, adding
>top-level links to sections and moving the encoded-kbd-self-insert-ccl stuff
>to the back burner.
>  
>
I agree. I have found exactly the same points as David points out annoying.

Re: describe-bindings: ^L, bad order, naming

[Robert J. Chassell]

   I would go for just "Keyboard Shortcuts". 

But that is inaccurate!  They are certainly not shortcuts!  You have
to type them!  Perhaps compared to something you type, voice
recognition would provide `shortcuts', until voice recognition became
common.

"Keyboard Bindings" makes much more sense.  If recent terminology is
wrong and misleading, we should tell people that, and point them
towards better language.  

(Just so we do not waste time in argument, that is why I have long
argued against Emacs' use of the word `kill' meaning Christian-style
resurrection, which is not a `killing' in most people's language.
`Cut', a non-Emacs term, comes from a poor metaphor, too.  Nowadays,
few people with computers physically cut up paper newspapers and paste
elsewhere the resulting printed text.)

   ... explain the terminology in another way.

Yes.  Definitely.  

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: describe-bindings: ^L, bad order, naming

[Miles Bader]

2005/11/11, Robert J. Chassell <bob@rattlesnake.com>:
>    I would go for just "Keyboard Shortcuts".
>
> But that is inaccurate!  They are certainly not shortcuts!  You have
> to type them!  Perhaps compared to something you type, voice
> recognition would provide `shortcuts', until voice recognition became
> common.

I presume the use of "shortcut" in other programs reflects the notion
that the menu-item is the "primary" method of invocation, and that any
keybindings are for the use of experts.

Obviously in Emacs, this is a very silly notion, and we shouldn't use the term.

A phrase like "Keyboard Commands" might be more familar than
"bindings", without the objectional implication of "shortcuts".

-miles
--
Do not taunt Happy Fun Ball.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

[-- Attachment #1.1: Type: text/plain, Size: 852 bytes --]

On 11 Nov 2005, at 01:03, Robert J. Chassell wrote:

> "Keyboard Bindings" makes much more sense.  If recent terminology is
> wrong and misleading, we should tell people that, and point them
> towards better language.

Natural language is rarely sensical. It's use is idiomatic, and  
forcefully changing established usage is not only patronizing, but  
also not very fruitful. The "Académie Française" might disagree.

There is no educational value in a menu item hidden in a Help submenu  
anyways when people don't find the list of key bindings that they are  
looking for

On 11 Nov 2005, at 02:55, Miles Bader wrote:

> A phrase like "Keyboard Commands" might be more familar than
> "bindings", without the objectional implication of "shortcuts".

Yes, "Keyboard Commands" or maybe even "Key Commands" would be a good  
choice.

[-- Attachment #1.2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 2400 bytes --]

[-- Attachment #2: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> From: David Reitter <david.reitter@gmail.com>
> Date: Thu, 10 Nov 2005 20:29:35 +0000
> 
> describe-bindings separates the different groups with  ^L even though  
> the text that is output is intended to be human-readable.

The ^L is there so that one could use forward-page to quickly move to
the next group.

> Isn't there a nicer way the groups can be separated?

We could use overlays to display the ^L as something more visually
appealing, while leaving ^L in the buffer.

> I also get a long list with latin key characters that are bound to  
> encoded-kbd-self-insert-ccl.

I think this is a bug.

> As a novice user when trying out the describe-bindings function, I  
> would see that there is a lot of uninteresting technical stuff at the  
> beginning

Please be more specific: what uninteresting technical stuff is there
at the beginning that you want to remove?

> Lastly, I was wondering if one could use a better name for the menu  
> item.
> "List Key Bindings" is of course perfectly correct from an Emacs  
> terminology point of view. But as a new user, I would be looking for  
> something like "Keyboard Functions" or "Keyboard Shortcuts" or so,  
> not for "Bindings".

We could modify the help echo string to mention "shortcuts".  I don't
think the name of the menu item itself should change, since this is
Emacs terminology, and newbies need to learn it as fast as possible.

> The Help menu is really important and useful to newbies. It would be  
> very helpful if one could make it easier to understand.

That is the goal, yes.  But given the limited real estate in the
menus, we need to compromise.

> --Apple-Mail-17-876036934
> Content-Transfer-Encoding: base64
> Content-Type: application/pkcs7-signature;
> 	name=smime.p7s
> Content-Disposition: attachment;
> 	filename=smime.p7s

Could you please drop this signature stuff?  It's very long and thus
annoying.  TIA.

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Thu, 10 Nov 2005 13:27:43 -0800
> 
> Beyond menu-item names, I think the intention was that synonyms would be
> introduced in the Emacs manual.

It's already there: that's what the Glossary is for.  Here's the item
relevant to the current discussion:

    Keyboard Shortcut
	 A keyboard shortcut is a key sequence (q.v.) which invokes a
	 command.  What other programs call "assign a keyboard shortcut"
	 Emacs calls "bind a key sequence".  See `binding.'

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> Date: Fri, 11 Nov 2005 01:03:00 +0000 (UTC)
> From: "Robert J. Chassell" <bob@rattlesnake.com>
> 
> "Keyboard Bindings" makes much more sense.  If recent terminology is
> wrong and misleading, we should tell people that, and point them
> towards better language.  

You cannot point people towards better language without mentioning the
misleading terminology, somewhere.  How else will they know we are
talking about the same thing?

So I think if the menu help text mentions "keyboard shortcuts" in
parentheses, that would be consistent with your suggestion to teach
people a better terminology, the one adopted throughout in Emacs
documentation.  Do you agree?

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> From: David Reitter <david.reitter@gmail.com>
> Date: Fri, 11 Nov 2005 07:43:43 +0000
> Cc: Emacs-Devel ' <emacs-devel@gnu.org>
> 
> Natural language is rarely sensical. It's use is idiomatic, and  
> forcefully changing established usage is not only patronizing, but  
> also not very fruitful.

I think Emacs invented the "key binding" term many years before the
"keyboard shortcuts" term.  So we are not forcing anyone, nor
patronizing them, we are simply using the same term since 1985.

Btw, googling for "key bindings" brings up many hits that have nothing
to do with Emacs.  So this term appears to be quite known in the UI
context.

> There is no educational value in a menu item hidden in a Help submenu  
> anyways when people don't find the list of key bindings that they are  
> looking for

In my experience, most newbies rarely look for the key bindings
anyway, they use the menus and the tool bar.  So please don't overplay
your (otherwise correct, IMHO) suggestions to make this feature more
useful.  A correct argument doesn't become more convincing if you try
to back it up by extreme or even absurd assertions.

> On 11 Nov 2005, at 02:55, Miles Bader wrote:
> 
> > A phrase like "Keyboard Commands" might be more familar than
> > "bindings", without the objectional implication of "shortcuts".
> 
> Yes, "Keyboard Commands" or maybe even "Key Commands" would be a good  
> choice.

I think it would be a rather bad choice, since neither of these terms
is widely used.  But that's me.

Re: describe-bindings: ^L, bad order, naming

[Kim F. Storm]

Miles Bader <snogglethorpe@gmail.com> writes:

> 2005/11/11, Robert J. Chassell <bob@rattlesnake.com>:
>>    I would go for just "Keyboard Shortcuts".
>>
>> But that is inaccurate!  They are certainly not shortcuts!  You have
>> to type them!  Perhaps compared to something you type, voice
>> recognition would provide `shortcuts', until voice recognition became
>> common.
>
> I presume the use of "shortcut" in other programs reflects the notion
> that the menu-item is the "primary" method of invocation, and that any
> keybindings are for the use of experts.

Well I don't think this is silly.

In emacs a "keyboard shortcut" could reflect the notion that without
it, you would have to use M-x and spell out the full command name.

E.g. C-x 4 C-f is a shortcut for M-x find-file-other-window RET.

> A phrase like "Keyboard Commands" might be more familar than
> "bindings", without the objectional implication of "shortcuts".

IMO, if we don't like "shortcut", we should stick to the term we
already use (bindings) rather than invent yet another term.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> Date: Fri, 11 Nov 2005 01:03:00 +0000 (UTC)
> From: "Robert J. Chassell" <bob@rattlesnake.com>
> 
>    I would go for just "Keyboard Shortcuts". 
> 
> But that is inaccurate!  They are certainly not shortcuts!

They are shortcuts because they bypass the hierarchical menu
structure one needs to go though to invoke the same functionality
through menus.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

[-- Attachment #1.1: Type: text/plain, Size: 2344 bytes --]

On 11 Nov 2005, at 08:47, Eli Zaretskii wrote:

> The ^L is there so that one could use forward-page to quickly move to
> the next group.

That's great, but it shouldn't be displayed.

>
>> Isn't there a nicer way the groups can be separated?
>
> We could use overlays to display the ^L as something more visually
> appealing, while leaving ^L in the buffer.

Sounds like a complicated solution to me. But if that's the only way...


>
>> I also get a long list with latin key characters that are bound to
>> encoded-kbd-self-insert-ccl.
>
> I think this is a bug.
>
>> As a novice user when trying out the describe-bindings function, I
>> would see that there is a lot of uninteresting technical stuff at the
>> beginning
>
> Please be more specific: what uninteresting technical stuff is there
> at the beginning that you want to remove?

the bug described before.

> We could modify the help echo string to mention "shortcuts".  I don't
> think the name of the menu item itself should change, since this is
> Emacs terminology, and newbies need to learn it as fast as possible.

Unless newbies are successful at finding what they want (help on  
functions assigned to keys), there is no learning effect. They will  
just skip over "Key Bindings" if they don't know what a binding is.

And sorry, the echo area is not enough.

1. It is not displayed on my system when going through the menus.
2. the echo area is far away from the menus (visually), and I  
wouldn't be used to check it anyways when going through menus. Menu  
strings have to be self explanatory.

I think a useful compromise would be "Keyboard Commands". I don't  
think that this is inconsistent with Emacs terminology.

>> Content-Transfer-Encoding: base64
>> Content-Type: application/pkcs7-signature;
>> 	name=smime.p7s
>> Content-Disposition: attachment;
>> 	filename=smime.p7s
>
> Could you please drop this signature stuff?  It's very long and thus
> annoying.  TIA.

It's an attachment and shouldn't be displayed on your screen.
Most mail readers will display "signed".
This uses the S/MIME standard, which is fairly wide-spread.

I support encrypted e-mail and electronic signatures. You can get a  
free X.509 certificate (an open standard) at Thawte, and if you meet  
me in person one day and bring your passport, I can even notarize  
your certificate for you. 

[-- Attachment #1.2: smime.p7s --]
[-- Type: application/pkcs7-signature, Size: 2400 bytes --]

[-- Attachment #2: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> Cc: emacs-devel@gnu.org
> From: David Reitter <david.reitter@gmail.com>
> Date: Fri, 11 Nov 2005 09:33:06 +0000
> 
> > We could use overlays to display the ^L as something more visually
> > appealing, while leaving ^L in the buffer.
> 
> Sounds like a complicated solution to me.

It isn't complicated.

> But if that's the only way...

I don't know if that's the only way, that's the first way I could
think of.  Others might have other, perhaps better, ideas.

> > We could modify the help echo string to mention "shortcuts".  I don't
> > think the name of the menu item itself should change, since this is
> > Emacs terminology, and newbies need to learn it as fast as possible.
> 
> Unless newbies are successful at finding what they want (help on  
> functions assigned to keys), there is no learning effect. They will  
> just skip over "Key Bindings" if they don't know what a binding is.
> 
> And sorry, the echo area is not enough.
> 
> 1. It is not displayed on my system when going through the menus.

Did you turn the tooltips off?  If not, perhaps there's some bug?

> 2. the echo area is far away from the menus (visually), and I  
> wouldn't be used to check it anyways when going through menus. Menu  
> strings have to be self explanatory.

First, the default is to display the help text in a tooltip, not in
the echo area.

Second, the area near the bottom of the display is where other GUI
applications display longer descriptions of the menu items.  So I
think users do know to look there' even if tooltips are somehow
disabled.

> I think a useful compromise would be "Keyboard Commands". I don't  
> think that this is inconsistent with Emacs terminology.

IMHO, it _is_ inconsistent.  And in addition, it is not mentioned
anywhere in the docs where a newbie might look for basic terminology.
It's not in Glossary, for example.

> > Could you please drop this signature stuff?  It's very long and thus
> > annoying.  TIA.
> 
> It's an attachment and shouldn't be displayed on your screen.
> Most mail readers will display "signed".

Rmail does display it.

I don't mind short signatures, but this one is annoyingly long.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

On 11 Nov 2005, at 10:02, Eli Zaretskii wrote:

> It isn't complicated.

Well then, good solution.

>>
>> 1. It is not displayed on my system when going through the menus.
>
> Did you turn the tooltips off?  If not, perhaps there's some bug?

I'm using the Carbon port, and I think the port just doesn't  
implement it. And it would be weird if it did, because on OS X there  
should be no extra explanations: Menu entries should be self- 
explanatory.  (I don't see a technical way to display anything in a  
tooltip above the menu. Menu interaction is handled by the system.)

> Second, the area near the bottom of the display is where other GUI
> applications display longer descriptions of the menu items.

Yes, on Windows and on GNU/Linux systems.

Re: describe-bindings: ^L, bad order, naming

[Henrik Enberg]

> Date: Fri, 11 Nov 2005 11:05:44 +0200
> From: Eli Zaretskii <eliz@gnu.org>
> 
> > From: David Reitter <david.reitter@gmail.com>
> > Date: Fri, 11 Nov 2005 07:43:43 +0000
> > Cc: Emacs-Devel ' <emacs-devel@gnu.org>
> > 
> > Natural language is rarely sensical. It's use is idiomatic, and  
> > forcefully changing established usage is not only patronizing, but  
> > also not very fruitful.
> 
> I think Emacs invented the "key binding" term many years before the
> "keyboard shortcuts" term.  So we are not forcing anyone, nor
> patronizing them, we are simply using the same term since 1985.
> 
> Btw, googling for "key bindings" brings up many hits that have nothing
> to do with Emacs.  So this term appears to be quite known in the UI
> context.

And I've never seen anyone on help-gnu-emacs or similar be confused by
the term "key binding".  I think the meaning fairly self-evident for
people computer-literate enough to consider using Emacs.
> 

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    > Isn't there a nicer way the groups can be separated?

    We could use overlays to display the ^L as something more visually
    appealing, while leaving ^L in the buffer.

Yes, that's what I was thinking too. The ^L should stay, but can be made
more user-friendly.

    > I also get a long list with latin key characters that are bound to
    > encoded-kbd-self-insert-ccl.

    I think this is a bug.

I see that list too. I thought it was intended, but didn't know what it was
for. It is quite annoying, in any case.

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    > Beyond menu-item names, I think the intention was that
    > synonyms would be introduced in the Emacs manual.

    It's already there: that's what the Glossary is for.  Here's the item
    relevant to the current discussion:

        Keyboard Shortcut
    	 A keyboard shortcut is a key sequence (q.v.) which invokes a
    	 command.  What other programs call "assign a keyboard shortcut"
    	 Emacs calls "bind a key sequence".  See `binding.'

Perfect. That's just what I meant. Thx.

(I would insert "some": "some other programs". And do we really expect
people to understand "q.v."? Can we please change that to common English?)

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 11 Nov 2005 10:02:40 -0800
> 
> And do we really expect people to understand "q.v."? Can we please
> change that to common English?

I'm not a native English speaker, so I wouldn't know how common is
this nowadays.  To me, "q.v." is a well-known term.

We could replace it with "which see", I suppose, if people find "q.v."
too cryptic.

In any case, Glossary was using "q.v." since long ago, and no one ever
complained, AFAIR.

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 11 Nov 2005 10:02:31 -0800
> 
>     > Isn't there a nicer way the groups can be separated?
> 
>     We could use overlays to display the ^L as something more visually
>     appealing, while leaving ^L in the buffer.
> 
> Yes, that's what I was thinking too. The ^L should stay, but can be made
> more user-friendly.

Here's one more idea for displaying the bindings (it could also be
useful for what display-mode shows): put the help buffer into Outline
mode and use Outline-style headings instead of the ^L delimiters.
Initially, the display could be collapsed so that only the headings
are shown; users then could use Outline commands both for movement
between groups of bindings and for showing only those groups they are
interested in.

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    >     > Isn't there a nicer way the groups can be separated?
    >
    >     We could use overlays to display the ^L as something more visually
    >     appealing, while leaving ^L in the buffer.
    >
    > Yes, that's what I was thinking too. The ^L should stay, but
    > can be made more user-friendly.

    Here's one more idea for displaying the bindings (it could also be
    useful for what display-mode shows): put the help buffer into Outline
    mode and use Outline-style headings instead of the ^L delimiters.
    Initially, the display could be collapsed so that only the headings
    are shown; users then could use Outline commands both for movement
    between groups of bindings and for showing only those groups they are
    interested in.

That might be OK, but I believe Outline mode can be a bit scary for
newbies - it's not always immediately clear how to use it.

I think the main problem is the extraneous, uninteresting bindings, which
you say is a bug. Getting rid of them will be a big help.

Beyond that, identifying the sections (e.g. with a horizontal overlay line
or something, in place of ^L), and providing links to them near the top,
should be sufficient.

Re: describe-bindings: ^L, bad order, naming

[Lennart Borgman]

Eli Zaretskii wrote:

>Here's one more idea for displaying the bindings (it could also be
>useful for what display-mode shows): put the help buffer into Outline
>mode and use Outline-style headings instead of the ^L delimiters.
>Initially, the display could be collapsed so that only the headings
>are shown; users then could use Outline commands both for movement
>between groups of bindings and for showing only those groups they are
>interested in.
>  
>
A very good suggestion in my opinion.

Re: describe-bindings: ^L, bad order, naming

[Juri Linkov]

> describe-bindings separates the different groups with  ^L even though  
> the text that is output is intended to be human-readable.
>
> Isn't there a nicer way the groups can be separated?

I use (aset standard-display-table ?\f (vconcat (make-vector 64 ?-) "^L"))
to display the page delimiter as a horizontal line, and this is very helpful
not only in the *Help* buffer, but in other places too, including source code
buffers.

> Couldn't there be a list of all groups in the beginning, with links  
> going to the bindings belonging to the group?

Like in the *Help* buffer created by `C-h m'?

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: describe-bindings: ^L, bad order, naming

[Robert J. Chassell]

   I'm not a native English speaker, so I wouldn't know how common is
   this nowadays.  To me, "q.v." is a well-known term.

I am a native English speaker and to me, "q.v." is also a well-known
term, at least in glossaries and the like.  

My hunch is that if you write "q.v." without a context, many people
will not understand.  But a glossary provides context.

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: describe-bindings: ^L, bad order, naming

[Luc Teirlinck]

Drew Adams wrote:

   That might be OK, but I believe Outline mode can be a bit scary for
   newbies

Indeed.

David Reitter wrote, in response to Eli Zaretskii:

   On 11 Nov 2005, at 08:47, Eli Zaretskii wrote:

   > The ^L is there so that one could use forward-page to quickly move to
   > the next group.

   That's great, but it shouldn't be displayed.

If the ^L is not displayed, how do you know that forward-page will
move you there?

More importantly, what the ^L is _really_ there for is to force a page
break if the user prints the stuff off.  Obviously, it should be
displayed as is, because the user printing it off should know that
there is going a page break there.  He should be able to remove it
after C-x C-q if he does not want a page break there.  People who are
less comfortable with computers tend to print _more_ stuff to hardcopy
than advanced users and print off more plain text, which uses ^L for
page breaks.  They may not know the meaning of ^L the very first time
they print a buffer with ^L, but they will the second time, and then
they will start using it in their own buffers.

^L is by no means an obscure character, although it might be obscure
for people who never print plaintext buffers.  People who need to know
what the ^L means (people who want to print the stuff off) will know
what it means.  People who do not need to know it can either ignore
it, or check it up if they are curious (good for them), but I do not
see how it can really harm them.

   > We could use overlays to display the ^L as something more visually
   > appealing, while leaving ^L in the buffer.

Definitely not, for the reasons above.  If there is a ^L in the buffer,
the user needs to know that.

Sincerely,

Luc.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

On 11 Nov 2005, at 19:35, Juri Linkov wrote:

>> describe-bindings separates the different groups with  ^L even though
>> the text that is output is intended to be human-readable.
>>
>> Isn't there a nicer way the groups can be separated?
>
> I use (aset standard-display-table ?\f (vconcat (make-vector 64 ?-)  
> "^L"))
> to display the page delimiter as a horizontal line, and this is  
> very helpful
> not only in the *Help* buffer, but in other places too, including  
> source code
> buffers.

This would have global implications, right?
The idea with an overlay could easily work locally, and it's prettier  
as well.

>> Couldn't there be a list of all groups in the beginning, with links
>> going to the bindings belonging to the group?
>
> Like in the *Help* buffer created by `C-h m'?

Yup. That would be fine.
Outline mode, as suggested by Eli, is OK only if it doesn't require  
people to know some keys in order to even look up the keys.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

On 11 Nov 2005, at 20:49, Luc Teirlinck wrote:
>
> ^L is by no means an obscure character, although it might be obscure
> for people who never print plaintext buffers.

I just typed   ^L in Google and I couldn't find the meaning.
I tried to use the Help menu to find it in the Emacs manual,  to no  
avail. (Maybe I didn't search correctly, but I did what a naive user  
would do.).
I also checked "Emacs Terminology" and couldn't find it.

Sorry to say, but yes, it is obscure.

Something like this is - nowadays - displayed in a graphical way.

>> We could use overlays to display the ^L as something more visually
>> appealing, while leaving ^L in the buffer.
>
> Definitely not, for the reasons above.  If there is a ^L in the  
> buffer,
> the user needs to know that.

Why does he need to know?
Doesn't a dashed horizontal line suggest that there's a page break  
much better than a ^L?

Divider lines exist because they visually divide something. That  
helps me analyze the structure of a document more quickly.
A ^L doesn't divide anything visually.

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

       > The ^L is there so that one could use forward-page to
       > quickly move to the next group.

       That's great, but it shouldn't be displayed.

    If the ^L is not displayed, how do you know that forward-page will
    move you there?

`forward-page' looks for the character ^L (control L, form-feed).  Wouldn't
Eli's overlay suggestion give a better appearance and still leave the ^L in
the buffer for `forward-page' to find and the printer to interpret as a
form-feed?

    More importantly, what the ^L is _really_ there for is to force a page
    break if the user prints the stuff off.  Obviously, it should be
    displayed as is, because the user printing it off should know that
    there is going a page break there.

I think the display in a buffer can be made independent of what character is
actually there. The suggestion was to leave the control-L character there,
but display it as, for example, a horizontal line (perhaps with some space
before and after it). That would still let the user know that the printer
would make a page break (provided the convention were explained, as is also
needed to understand that seeing "^L" means a page break).

       > We could use overlays to display the ^L as something more visually
       > appealing, while leaving ^L in the buffer.

    Definitely not, for the reasons above.  If there is a ^L in the buffer,
    the user needs to know that.

I don't see those reasons. The user needs to see a section delimiter; that's
all. He need not see "^L" (which is just one representation of a form-feed
character, anyway). I think what people are saying is that the form-feed
character should be kept in the buffer, but it should be displayed as
something more user-friendly.

Re: describe-bindings: ^L, bad order, naming

[Luc Teirlinck]

   On 11 Nov 2005, at 20:49, Luc Teirlinck wrote:
   >
   > ^L is by no means an obscure character, although it might be obscure
   > for people who never print plaintext buffers.

   I just typed   ^L in Google and I couldn't find the meaning.
   I tried to use the Help menu to find it in the Emacs manual,  to no  
   avail. (Maybe I didn't search correctly, but I did what a naive user  
   would do.).
   I also checked "Emacs Terminology" and couldn't find it.

   Sorry to say, but yes, it is obscure.

C-h i emacs m pages, but really, all you have to do is print off a
buffer containing ^L's once and you will notice.

Sincerely,

Luc.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

On 11 Nov 2005, at 21:26, Luc Teirlinck wrote:
>
> C-h i emacs m pages, but really, all you have to do is print off a
> buffer containing ^L's once and you will notice.

I'm afraid I lack the ingenuity to guess that I have to look for  
"pages" in order to find out that this unknown new character ^L has  
to do with pages.

Some people are more visually oriented, some aren't.
I suspect a metaphor like a dashed horizontal line visualized a page  
break won't hurt you.
If you don't know what ^L is, then it will only distract you.
And it won't provide visual guidance as to where groups start for  
either of us. 

Re: describe-bindings: ^L, bad order, naming

[Miles Bader]

2005/11/12, David Reitter <david.reitter@gmail.com>:
> Sorry to say, but yes, it is obscure.

Perhaps for mac users it is obscure, but it is well supported in Emacs
-- many commands apply to pages separated by ^L

> Something like this is - nowadays - displayed in a graphical way.

This is not macwrite.  Sorry.

Emacs can accomodate beginners to a degree, but I often get the
impression you want to _replace_ well-worn Emacs conventions with
whatever dancing elephants you're used to from the mac, and that isn't
something that's always desirable.  We want to _help_ new users, but
that doesn't always mean simply copying other interfaces; often it
means simply offering a bridge to make it easier for new users to
understand Emacs conventions.

Displaying ^L characters as a horizontal line might be visually nicer
(for everybody, not just beginners), but in normal text (source
buffers etc), hiding the fact that it's simply a character which can
be inserted or deleted etc. like any other, may actually be harmful to
beginners.

If an Emacs convention is scary and distressing to new users, maybe
that's something to consider, but I don't think ^L is in that
category, it's simply something that they may not be used to -- the
presence of ^L characters isn't going to notably inconvenience anyone,
even if they may not be cognizant of all the ways they could take
advantage of them.

[A compromise might be to display a ^L at the beginning of the line,
but a magic-horizontal-rule following it.  This would be even nicer if
emacs had real support for things like horizontal rules of course...
I've often wanted to add new "line drawing" glyph types...]

-miles
--
Do not taunt Happy Fun Ball.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

On 11 Nov 2005, at 22:42, Miles Bader wrote:

> Emacs can accomodate beginners to a degree, but I often get the
> impression you want to _replace_ well-worn Emacs conventions with
> whatever dancing elephants you're used to from the mac, and that isn't
> something that's always desirable.

Sometimes I'd like to coerce Emacs into supporting operating-system  
specific standards. But I wouldn't propose to change the UI in a  
general way to accomodate that. What we are talking about - a  
horizontal line as a page divider - is nothing mac specific. You can  
see it in pretty much every GUI based application that deals with  
text, not just on the Mac.

> We want to _help_ new users, but
> that doesn't always mean simply copying other interfaces; often it
> means simply offering a bridge to make it easier for new users to
> understand Emacs conventions.

Your suggestion about ^L with a horizontal line next to it implements  
that nicely.

I have noticed that a lot of people here are actually open to  
reforms: conventions can be modernized, if there are good arguments  
for it and if one is considerate of people's long-learnt ways of  
interacting with the program. Because of this view, and because I  
think the naïve perspective of a relative newcomer can be helpful in  
such things, I make these suggestions. (I have been using computers  
since 1984, Atari, Windows, GNU/Linux, GNU/OS X - I'm biased towards  
graphical interfaces, yes, but not biased towards the Mac in  
particular, I would say).

Most people seemed to be quite happy with a nicer key bindings list,  
I believe.
Implementing this - for example your compromise below - is probably a  
matter of minutes for one of the experts. Is the topic isn't worth  
spending hours discussing?

> Displaying ^L characters as a horizontal line might be visually nicer
> (for everybody, not just beginners), but in normal text (source
> buffers etc), hiding the fact that it's simply a character which can
> be inserted or deleted etc. like any other, may actually be harmful to
> beginners.

I think the crucial distinction is whether the text is meant to be  
edited, or read. We're in Help View Mode here. I can see no harm in  
displaying horizontal lines to divide the groups.
By the way, the tutorial routines go a long way at inserting blank  
space to make the first page be a real, visual page. I'm not  
suggesting that this is what should be done here, but it shows that  
at some points, the current implementation is considerate towards a  
first-time reader.

- D

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 11 Nov 2005 11:10:16 -0800
> 
>     Here's one more idea for displaying the bindings (it could also be
>     useful for what display-mode shows): put the help buffer into Outline
>     mode and use Outline-style headings instead of the ^L delimiters.
>     Initially, the display could be collapsed so that only the headings
>     are shown; users then could use Outline commands both for movement
>     between groups of bindings and for showing only those groups they are
>     interested in.
> 
> That might be OK, but I believe Outline mode can be a bit scary for
> newbies - it's not always immediately clear how to use it.

We could put some basic instructions at the beginning of the buffer,
like we do in Custom.

Or (gasp) we could put a graphic control that looks like a button with a
`+' character before each heading, which most people will recognize as
a sign that there's something hidden here that will show if one clicks
on the button.

> I think the main problem is the extraneous, uninteresting bindings, which
> you say is a bug. Getting rid of them will be a big help.

What is uninteresting to you and me might be very important to
someone else.  Outline makes it simple to display only what one wants
to see.

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> Date: Fri, 11 Nov 2005 14:49:09 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: emacs-devel@gnu.org
> 
> If the ^L is not displayed, how do you know that forward-page will
> move you there?

We could say that at the beginning of the buffer.

> More importantly, what the ^L is _really_ there for is to force a page
> break if the user prints the stuff off.  Obviously, it should be
> displayed as is, because the user printing it off should know that
> there is going a page break there.

??? Strange logic.  If I print the buffer (I admit I never did that;
is there someone here that did?), why should I care exactly how many
printed pages will I get?

> He should be able to remove it after C-x C-q if he does not want a
> page break there.

It sounds like you are searching low and high for any argument, no
matter how feeble, against this idea.  Do you really believe newbies
will know about C-x C-q and removing the page break?

Anyway, the user still can remove the page break, even though it's
covered by an overlay: just press DEL or Backspace or C-d.  What made
you think this would be impossible?

>    > We could use overlays to display the ^L as something more visually
>    > appealing, while leaving ^L in the buffer.
> 
> Definitely not, for the reasons above.  If there is a ^L in the buffer,
> the user needs to know that.

We already do something similar in Emacs, although not with ^L: in
Info, for example.  I don't see how ^L is more special than the other
parts of text that we hide.

Re: describe-bindings: ^L, bad order, naming

[Robert J. Chassell]

    ??? Strange logic.  If I print the buffer (I admit I never did
    that; is there someone here that did?), why should I care exactly
    how many printed pages will I get?

The logic makes sense but the procedures are not for experts.

You are an expert.  Many novices print what they see.  They should not
-- after all, a computer plus printer is more than an early 20th
century typesetting machine plus printing machine -- but they do.

Also, novices tend not to distinguish between buffers that are
visiting files and buffers that are not visiting files:  they just
print what they see or, if they are blind and have a braille printer,
what they hear.

I know one person who prints her email!  (She also did not want to
print a book of mine because she feared it would have too many pages
and take too long.)  Experts print far less frequently.

Years ago, I wrote the page-ext.el functions so I could readily
determine whether the number of lines in a page was too many for my
printer, which could only print pages of 66 or fewer lines.

Nowadays, I hardly ever print hardcopy and forget the keybinding for a
`pages-directory' command that lists the number of lines in each page.
(It uses a positive, numeric prefix key.  Also, you must load
"page-ext" first; it is part of the distribution but not autoloaded.)

On looking, the command turns out to be `C-u 8 C-x C-p C-d' and works
with Juri Linkov's display setting,

    (aset standard-display-table ?\f (vconcat (make-vector 64 ?-) "^L"))

since that setting does not effect contents only display.

I just checked: Mile's suggestion also works:  to put the caret and
the L characters after an indent and then a line of hyphens,

  (aset standard-display-table ?\f (vconcat  "    ^L " (make-vector 64 ?-)))

Thus, when I run `C-h b' (describe-bindings) on this email buffer, and
then run `C-u 8 C-x C-p C-d' on the resulting *Help* buffer, I see

      8: Key translations:
      4: `say-minor-mode' Minor Mode Bindings:
     17: `mc-write-mode' Minor Mode Bindings:
     52: Major Mode Bindings:
    1094: Global Bindings:
     88: Function key map translations:

Everyone starts out as a novice.  Consequently, it is worth making it
easy for novices to learn the jargon and to learn how to become more
efficient.

I remember -- more than 20 years ago, before learning about Emacs --
typing each key chord in a program to discover the keybindings.  The
program lacked documentation but was easy for a novice to learn since
you could put a mouse cursor on a menu item and execute the command
that way.  But those commands were inefficient -- after all, who wants
to move the mouse cursor to a menu in order to mark a whole buffer
when you can type `C-x h'?

In general, as people become more proficient, they want to waste their
time less.  For this Emacs is good.  (As is Emacspeak, which is for
listening rather than seeing -- for the permanently blind and for
people driving cars and such, who are `situationally blind').

-- 
    Robert J. Chassell                         
    bob@rattlesnake.com                         GnuPG Key ID: 004B4AC8
    http://www.rattlesnake.com                  http://www.teak.cc

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

On 12 Nov 2005, at 12:28, Robert J. Chassell wrote:
> You are an expert.  Many novices print what they see.  They should not
> -- after all, a computer plus printer is more than an early 20th
> century typesetting machine plus printing machine -- but they do.

Yes they do - you're talking about computer illiterates like my mom,  
right? Or people who use AOL as their ISP... But is my mom every  
going to need a text editor? No.

In our context, novices are people new to the program and its  
concepts. I know plenty of people who are good programmers and  
experts in their (computer science related) fields, but who don't  
know a single Emacs specific shortcut. As you said, they don't want  
to waste their time. So they would like to find out quickly how to do  
things.

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    > I think the main problem is the extraneous, uninteresting
    > bindings, which you say is a bug. Getting rid of them will
    > be a big help.

    What is uninteresting to you and me might be very important to
    someone else.

You said those extraneous lines represented a bug (not I). To whom would it
be important that we include a bug? ;-)

Re: describe-bindings: ^L, bad order, naming

[Luc Teirlinck]

   ??? Strange logic.  If I print the buffer (I admit I never did that;
   is there someone here that did?), why should I care exactly how many
   printed pages will I get?

Not to waste too much paper and not too wind up with too many nearly
blank pages.

   It sounds like you are searching low and high for any argument, no
   matter how feeble, against this idea.  Do you really believe newbies
   will know about C-x C-q and removing the page break?

Of course.  C-x C-q is on the reference card and the meaning of ^L is
self-evident once you have printed off a buffer containing ^L.

Sincerely,

Luc.

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> Date: Sat, 12 Nov 2005 08:28:08 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: drew.adams@oracle.com, emacs-devel@gnu.org
> 
>    ??? Strange logic.  If I print the buffer (I admit I never did that;
>    is there someone here that did?), why should I care exactly how many
>    printed pages will I get?
> 
> Not to waste too much paper and not too wind up with too many nearly
> blank pages.

Never seen anyone who'd worry that much about this.

>    Do you really believe newbies will know about C-x C-q and
>    removing the page break?
> 
> Of course.  C-x C-q is on the reference card

Ha!  I invite you to take a poll among newbies how many of them have
read the reference card.

Re: describe-bindings: ^L, bad order, naming

[Miles Bader]

2005/11/13, Eli Zaretskii <eliz@gnu.org>:
> > Not to waste too much paper and not too wind up with too many nearly
> > blank pages.
>
> Never seen anyone who'd worry that much about this.

Actually this _is_ a slight issue in my experience -- in practice (at
least in the free software community) ^L seems to usually be used more
for logically structuring files than for formatting them for printing.
 I like this usage, it's actually very handy, but it means that in the
rare case where you actually print something it's quite common to get
way too many page breaks ...

[Though at this point in the thread I've forgotten why it's even being
discussed :-]

-Miles
--
Do not taunt Happy Fun Ball.

Re: describe-bindings: ^L, bad order, naming

[Juri Linkov]

>> I use (aset standard-display-table ?\f (vconcat (make-vector 64 ?-) "^L"))
>> to display the page delimiter as a horizontal line, and this is
>> very helpful not only in the *Help* buffer, but in other places
>> too, including source code buffers.
>
> This would have global implications, right?
> The idea with an overlay could easily work locally, and it's prettier
> as well.

Yes, this affect everything.  Instead of that, in the Help buffer
overlays or text properties could be used locally.

>>> Couldn't there be a list of all groups in the beginning, with links
>>> going to the bindings belonging to the group?
>>
>> Like in the *Help* buffer created by `C-h m'?
>
> Yup. That would be fine.
> Outline mode, as suggested by Eli, is OK only if it doesn't require
> people to know some keys in order to even look up the keys.

By default, Outline mode is harmless and doesn't require to know its
keys to read the Help buffer.  Advanced users should know Outline keys
to use it and to hide/show uninteresting parts.  So it doesn't harm to set
outline-regexp and enable outline-minor-mode on the Help buffer.

I imagine that code like below could be used to enable Outline minor mode
and to add a horizontal line to page breaks:

(defadvice describe-bindings (after my-describe-bindings activate)
  (with-current-buffer "*Help*"
    (save-excursion
      (let ((inhibit-read-only t))
        (goto-char (point-min))
        (while (re-search-forward "^\^L$" nil t)
          (put-text-property (match-beginning 0) (match-end 0)
                             'display (concat (make-string 64 ?-) "^L")))))
    (set (make-local-variable 'outline-regexp) "^.*:$")
    (outline-minor-mode 1)))

-- 
Juri Linkov
http://www.jurta.org/emacs/

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    >>> Couldn't there be a list of all groups in the beginning, with links
    >>> going to the bindings belonging to the group?
    >>
    >> Like in the *Help* buffer created by `C-h m'?
    >
    > Yup. That would be fine.
    > Outline mode, as suggested by Eli, is OK only if it doesn't require
    > people to know some keys in order to even look up the keys.

    By default, Outline mode is harmless and doesn't require to know its
    keys to read the Help buffer.  Advanced users should know Outline keys
    to use it and to hide/show uninteresting parts.

If the point is to make the less interesting parts less visible to start
with (so, less distracting), then Outline mode would help only if it hid
such stuff, by default.

Why not just do what the OP suggested: list the section titles in the
beginning, linked to the sections themselves (exactly as in the *Help*
buffer). That would be perfect. Such an approach is common both on the Web
and in technical documents (e.g. reference-book chapters): a preliminary TOC
with links.

Re: describe-bindings: ^L, bad order, naming

[Miles Bader]

2005/11/13, Drew Adams <drew.adams@oracle.com>:
> Why not just do what the OP suggested: list the section titles in the
> beginning, linked to the sections themselves (exactly as in the *Help*
> buffer). That would be perfect. Such an approach is common both on the Web
> and in technical documents (e.g. reference-book chapters): a preliminary TOC
> with links.

Though in practice, it's highly annoying in for instance
describe-mode, because the "table of contents" is usually very bloated
and pushes useful text off the screen.

-Miles
--
Do not taunt Happy Fun Ball.

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    > Why not just do what the OP suggested: list the section titles in
    > the beginning, linked to the sections themselves (exactly as in
    > the *Help* buffer). That would be perfect. Such an approach is
    > common both on the Web and in technical documents (e.g.
    > reference-book chapters): a preliminary TOC with links.

    Though in practice, it's highly annoying in for instance
    describe-mode, because the "table of contents" is usually
    very bloated and pushes useful text off the screen.

I don't see that, but it could happen if there are many minor modes in
effect.

IIUC, we would have the same problem using Outline mode for `describe-mode'.
If the outline were all closed up, by default, then it would appear just
like the TOC. If it were only partly closed up, then the problem you mention
would be worse.

And worse would happen when any of the outline lines were opened - even more
stuff would be pushed off the screen.

The only way around the problem you raise, if it really is a problem, is to
have a hierarchical outline (or a hierachy of TOCs), which shows a smaller
number of more-major topic lines. I don't see the `describe-bindings'
content being organized that way - it's naturally flat.

I also don't see it having the problem you raise, however. Here's a
`describe-bindings' TOC for Dired mode (some other modes would have even
fewer entries). Each line would be a link to its list of bindings, and
*only* its bindings. IOW, instead of having pages in linear order
(^L...^L...^L...), we would have a hyperlinked (shallow) tree.

  Key Translations
  Minor Mode Bindings
  Major Mode Bindings
  Global Bindings
  Function Key Map Translations

(I'm not sure that's the best order, BTW, but that's the order we have
today. And is that "function-key map translations" or "function keymap
translations" - or perhaps just "function-key translations"?)

That's not too much for one screen, is it? The link could open the
appropriate bindings list in another window (another frame, if pop-up-frames
= non-nil), so that the TOC remains visible. If not, the bindings-list pages
should at least have a Back button, to get back to the TOC.

Yes, that's just like outline mode, but the link metaphor is more obvious
and more familiar. Yes, if we had +/- signs, outline mode would act like the
GUI trees that people are accustomed to, and it would be (almost) as good as
the TOC, here.

Re: describe-bindings: ^L, bad order, naming

[Chong Yidong]

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

> IIUC, we would have the same problem using Outline mode for `describe-mode'.
> If the outline were all closed up, by default, then it would appear just
> like the TOC. If it were only partly closed up, then the problem you mention
> would be worse.
>
> And worse would happen when any of the outline lines were opened - even more
> stuff would be pushed off the screen.

One possibility is to use the speedbar to display the TOC.

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    > IIUC, we would have the same problem using Outline mode for
    > `describe-mode'. If the outline were all closed up, by
    > default, then it would appear just like the TOC. If it were
    > only partly closed up, then the problem you mention
    > would be worse.
    >
    > And worse would happen when any of the outline lines were
    > opened - even more stuff would be pushed off the screen.

    One possibility is to use the speedbar to display the TOC.

In what you quoted, I was speaking to the problem Miles sees for
`describe-mode'. I don't see that as a problem for `describe-bindings' -
there are only four or five TOC entries.

And some people might not want to use speedbar.

This seems so simple, to me - just four or five links that open to buffers
showing the corresponding bindings. Why look to heavy-handed solutions like
outline-mode and speedbar to help here? That's overkill, IMO.

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

    I also get a long list with latin key characters that are bound to  
    encoded-kbd-self-insert-ccl.
    That's rather annoying. If this needs to be listed (why?), it should  
    come at the end.

I do not see that when I try it.  Can you figure out what causes
them to appear?

    As a novice user when trying out the describe-bindings function, I  
    would see that there is a lot of uninteresting technical stuff at the  
    beginning


Could you show me specifically what this "uninteresting technical stuff"
consists of?  I don't see anything that fits that description.
Since you have only told me your opinion of it, not what it is,
I cannot tell whether I am seeing the same stuff that you see.

    Couldn't there be a list of all groups in the beginning, with links  
    going to the bindings belonging to the group?

What does "groups" mean?  Do you mean, a list of keymaps?

    Lastly, I was wondering if one could use a better name for the
    menu item.  "List Key Bindings" is of course perfectly correct
    from an Emacs terminology point of view.

We will stick with the term "key bindings", in general.
However, we could change C-h C-h to describe this as
"list of defined key sequences and what they do".
I think that requires a little less knowledge, to be understood.

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

    > Isn't there a nicer way the groups can be separated?

    We could use overlays to display the ^L as something more visually
    appealing, while leaving ^L in the buffer.

^L is the standard way to indicate page boundaries.
If it is nicer to display them another way,
we could change redisplay to show ^L differently.
For instance, as a horizontal line.

I think it can wait till after the release.

    [A compromise might be to display a ^L at the beginning of the line,
    but a magic-horizontal-rule following it.

That could be a good variant of that feature.

    Here's one more idea for displaying the bindings (it could also be
    useful for what display-mode shows): put the help buffer into Outline
    mode and use Outline-style headings instead of the ^L delimiters.
    Initially, the display could be collapsed so that only the headings
    are shown; users then could use Outline commands both for movement
    between groups of bindings and for showing only those groups they are
    interested in.

That is an interesting idea.  However, I am concerned that the need
to understand Outline mode will be a big obstacle to making use of
the information.

    > Couldn't there be a list of all groups in the beginning, with links  
    > going to the bindings belonging to the group?

    Like in the *Help* buffer created by `C-h m'?

Something like that would be ok with me, as a general idea.
Whether it would really be an improvement depends on working out
the details in a good way.

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

    Btw, googling for "key bindings" brings up many hits that have nothing
    to do with Emacs.  So this term appears to be quite known in the UI
    context.

They all go back to one program, Emacs, which popularized this
concept in 1975.

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

[-- Attachment #1: Type: text/plain, Size: 795 bytes --]

        I also get a long list with latin key characters that are bound to
        encoded-kbd-self-insert-ccl.

    I do not see that when I try it.

        As a novice user when trying out the describe-bindings function, I
        would see that there is a lot of uninteresting technical
        stuff at the beginning

    Could you show me specifically what this "uninteresting technical stuff"
    consists of?

Attached is a screenshot showing the (beginning of the)
encoded-kbd-self-insert-ccl stuff, which is, I think, the "uninteresting
technical stuff" David referred to. There are 122 lines of such bindings
listed at the beginning of the `describe-bindings' *Help* buffer.

This is from a July CVS snapshot. Perhaps this has been fixed - I don't know
what version David sees it in.

[-- Attachment #2: describe-bindings-bug.gif --]
[-- Type: image/gif, Size: 8770 bytes --]

[-- Attachment #3: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: describe-bindings: ^L, bad order, naming

[Lennart Borgman]

Drew Adams wrote:

>Attached is a screenshot showing the (beginning of the)
>encoded-kbd-self-insert-ccl stuff, which is, I think, the "uninteresting
>technical stuff" David referred to. There are 122 lines of such bindings
>listed at the beginning of the `describe-bindings' *Help* buffer.
>  
>
123 ;-)  -- Sorry for but I have hard time to resist those "it is even a 
bit worse".

I am seeing this on w32. From the discussions I have guessed that this 
might be rather w32 specific.

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> Date: Sun, 13 Nov 2005 15:54:23 -0500
> Cc: david.reitter@gmail.com, emacs-devel@gnu.org
> 
>     Btw, googling for "key bindings" brings up many hits that have nothing
>     to do with Emacs.  So this term appears to be quite known in the UI
>     context.
> 
> They all go back to one program, Emacs, which popularized this
> concept in 1975.

Perhaps that's how it happened historically, but the important thing
is that by now this term is also known to people who don't use Emacs.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

On 13 Nov 2005, at 21:16, Drew Adams wrote:
> Attached is a screenshot showing the (beginning of the)
> encoded-kbd-self-insert-ccl stuff, which is, I think, the  
> "uninteresting
> technical stuff" David referred to. There are 122 lines of such  
> bindings
> listed at the beginning of the `describe-bindings' *Help* buffer.

Yes, that's what I meant.
This is in the Carbon port.

> I do not see that when I try it.  Can you figure out what causes
> them to appear?

Sure. I'll see what I can do.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

On 13 Nov 2005, at 22:08, Eli Zaretskii wrote:

>>
>> They all go back to one program, Emacs, which popularized this
>> concept in 1975.
>
> Perhaps that's how it happened historically, but the important thing
> is that by now this term is also known to people who don't use Emacs.

It's the concept that counts, and none of the merit is taken away  
from Emacs if the term denotating the concept changes.

But if you look up a term in a corpus such as Google's, you will want  
to have a look at the distribution of its alternate, near-synonymous  
variants.

"key bindings" --> 277,000
"key shortcuts" --> 111,000
"keyboard commands" --> 311,000
"key commands" --> 208,000
"keyboard shortcuts" --> 2,630,000 hits

Re: describe-bindings: ^L, bad order, naming

[Miles Bader]

2005/11/14, David Reitter <david.reitter@gmail.com>:
> It's the concept that counts, and none of the merit is taken away
> from Emacs if the term denotating the concept changes.

No of course not.  But the name shortcuts is misleading, a bit ugly,
and annoying for Emacs veterans (because it drops a familar term for
something that's not particularly nice); morever it hasn't been shown
to be so newbie unfriendly as to warrant _that_ much concern

There can be aids to understanding (entries in the glossary etc,
tweaks here and there) but I think it's pretty clear that Emacs is
_not_ going to adopt the term "shortcuts".

"Bindings" may not the most popular term (and GNU is not the most
popular OS), but it's certainly good enough.

-miles
--
Do not taunt Happy Fun Ball.

Re: describe-bindings: ^L, bad order, naming

[Lennart Borgman]

Miles Bader wrote:

>2005/11/14, David Reitter <david.reitter@gmail.com>:
>  
>
>>It's the concept that counts, and none of the merit is taken away
>>from Emacs if the term denotating the concept changes.
>>    
>>
>
>No of course not.  But the name shortcuts is misleading, a bit ugly,
>and annoying for Emacs veterans (because it drops a familar term for
>something that's not particularly nice); morever it hasn't been shown
>to be so newbie unfriendly as to warrant _that_ much concern
>  
>
It is the sum of all newbie unfriendliness that counts. At least for the 
newbie.

Re: describe-bindings: ^L, bad order, naming

[Juri Linkov]

> Why not just do what the OP suggested: list the section titles in
> the beginning, linked to the sections themselves (exactly as in the
> *Help* buffer). That would be perfect. Such an approach is common
> both on the Web and in technical documents (e.g. reference-book
> chapters): a preliminary TOC with links.

All three improvements (TOC, Outline mode and horizontal lines for
page breaks) are not mutually exclusive.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: describe-bindings: ^L, bad order, naming

[Stefan Monnier]

> It is the sum of all newbie unfriendliness that counts.  At least for
> the newbie.

If they want Notepad, they know where to find it,


        Stefan


PS: By the way, AFAIK, keyboard shortcuts are the things displayed in menus
saying how you can use the keyboard to get the same result.  Key bindings
are slightly different since they exist completely independently from menus.
The two are related but not identical.

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> Date: Mon, 14 Nov 2005 09:10:42 +0900
> From: Miles Bader <snogglethorpe@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, rms@gnu.org, emacs-devel@gnu.org
> 
> 2005/11/14, David Reitter <david.reitter@gmail.com>:
> > It's the concept that counts, and none of the merit is taken away
> > from Emacs if the term denotating the concept changes.
> 
> No of course not.  But the name shortcuts is misleading, a bit ugly,
> and annoying for Emacs veterans (because it drops a familar term for
> something that's not particularly nice); morever it hasn't been shown
> to be so newbie unfriendly as to warrant _that_ much concern
> 
> There can be aids to understanding (entries in the glossary etc,
> tweaks here and there) but I think it's pretty clear that Emacs is
> _not_ going to adopt the term "shortcuts".
> 
> "Bindings" may not the most popular term (and GNU is not the most
> popular OS), but it's certainly good enough.

I still didn't see any real objections to mention "keyboard shortcuts"
in the help message for that menu item.  Anyone?  Or should I go out
and do that now?

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

    Though in practice, it's highly annoying in for instance
    describe-mode, because the "table of contents" is usually very bloated
    and pushes useful text off the screen.

Not usually.  For me, it contains 9 lines.

I don't think most beginners will have lots of minor modes enabled.

Re: describe-bindings: ^L, bad order, naming

[Jason Rumney]

David Reitter wrote:

> But if you look up a term in a corpus such as Google's, you will want  
> to have a look at the distribution of its alternate, near-synonymous  
> variants.
>
Looking at NEAR-synonymous variants is not useful. It is confusing to 
use a term that does not quite mean what you intend it to. For example, 
the only term with significantly more Google matches than "key bindings" 
is "keyboard shortcuts", which, in other applications, refers 
specifically to key bindings that can be used to invoke menu commands.

Re: describe-bindings: ^L, bad order, naming

[David Reitter]

On 13 Nov 2005, at 20:54, Richard M. Stallman wrote:

> I do not see that when I try it.  Can you figure out what causes
> them to appear?


What we see is the key-translation-map. It is defined by encoded-kbd- 
mode, which is off on GNU/Linux (tested on X11), but on under GNU/OS  
X and on Windows. On the Mac, (keyboard-coding-system) is mac-roman,  
for example.  This causes encoded-kbd-mode to insert a bunch of  
bindings to encoded-kbd-self-insert-ccl. On various coding system  
types, it will insert bindings to one of the following

encoded-kbd-self-insert-iso2022-8bit
encoded-kbd-self-insert-iso2022-7bit
encoded-kbd-self-insert-big5
encoded-kbd-self-insert-sjis
encoded-kbd-self-insert-ccl

One solution to the issue might be to simply have describe_map (in  
keymap.c) not show any bindings to "self-insert" commands. Of course  
that would only make sense if such commands need not be seen in any  
situations. One such situation might be when an inheriting keymap  
overwrites a binding. I don't know if describe-bindings deals with this.

Another solution would be to show the key-translation-map bindings  
only under the heading "`encoded-kbd-mode' Minor Mode Bindings:" and  
ensure that this group is folded away by default, so people can  
activate it when needed. (But please, do not require knowledge of  
outline mode. Use a widget or insert text like "press ... to show  
these bindings".)

RE: describe-bindings: ^L, bad order, naming

[Drew Adams]

    > I do not see that when I try it.  Can you figure out what causes
    > them to appear?

    What we see is the key-translation-map.

Thanks for tracking this down.

    It is defined by encoded-kbd-mode, which is off on GNU/Linux
    (tested on X11), but on under GNU/OS
    X and on Windows. On the Mac, (keyboard-coding-system) is mac-roman,
    for example.  This causes encoded-kbd-mode to insert a bunch of
    bindings to encoded-kbd-self-insert-ccl. On various coding system
    types, it will insert bindings to one of the following

    encoded-kbd-self-insert-iso2022-8bit
    encoded-kbd-self-insert-iso2022-7bit
    encoded-kbd-self-insert-big5
    encoded-kbd-self-insert-sjis
    encoded-kbd-self-insert-ccl

    One solution to the issue might be to simply have describe_map (in
    keymap.c) not show any bindings to "self-insert" commands. Of course
    that would only make sense if such commands need not be seen in any
    situations. One such situation might be when an inheriting keymap
    overwrites a binding. I don't know if describe-bindings deals with this.

    Another solution would be to show the key-translation-map bindings
    only under the heading "`encoded-kbd-mode' Minor Mode Bindings:" and
    ensure that this group is folded away by default, so people can
    activate it when needed. (But please, do not require knowledge of
    outline mode. Use a widget or insert text like "press ... to show
    these bindings".)

The latter is far better - there is no reason to make exceptionsa and not
list all bindings.

Which would be clearer: "`encoded-kbd-mode' Minor Mode Bindings:" or
"Keyboard Coding Translation"? I'd prefer something like the latter, but I
don't really understand what this is. I'd just ask that those who do
understand try to come up with an intelligible name - something that someone
who would want to look at these bindings would recognize and something that
others would recognize that they don't want to bother to look at.

Re: describe-bindings: ^L, bad order, naming

[Lennart Borgman]

Stefan Monnier wrote:

>>It is the sum of all newbie unfriendliness that counts.  At least for
>>the newbie.
>>    
>>
>
>If they want Notepad, they know where to find it,
>  
>
I would say that one of the challenges when making software is making 
complex functionality available in a way that is at the same time both 
simple and flexible. Making things behave similar at the surface is a 
tool for this. It makes the complexity less for the beginners.

Maybe I think this is more important since I am (still) using Emacs on 
w32 and that is a bit more complex than using it in a *nix style 
environment I believe. The learning curve is heavier and often you run 
into small things that stops you from what you want to do. (For example 
tools that does not accept w32 line style.) Those small things together 
takes an awful lot of time.

>PS: By the way, AFAIK, keyboard shortcuts are the things displayed in menus
>saying how you can use the keyboard to get the same result.  Key bindings
>are slightly different since they exist completely independently from menus.
>The two are related but not identical.
>  
>
Probably that is the history. But I believe that has changed because 
software UI has become more flexible. In some common applications (MS 
Office) you can decide what to have in the menus without changing what 
they call keyboard shortcuts.

Looking at the documentation for OpenOffice.org they seem to use 
"keyboard shortcuts" the same way. They also use the term "shortcut 
keys" for the same thing.

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

    I still didn't see any real objections to mention "keyboard shortcuts"
    in the help message for that menu item.

Including it in parentheses can't hurt.

Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[David Reitter]

On 14 Nov 2005, at 17:48, Richard M. Stallman wrote:

>     I still didn't see any real objections to mention "keyboard  
> shortcuts"
>     in the help message for that menu item.
>
> Including it in parentheses can't hurt.

How about including it in the menu item name on systems that don't  
display the help texts?

The "Describe" sub-menu could also drop the myriad of "Describe ..."  
texts.

Right now, it is

Describe -->
	 Describe Buffer Modes...
	Describe Key or Mouse Operation ...
	Describe ...
	Describe ...
	List Key Bindings
	---
	Describe ...
	Describe ...
	Show all of Mule Stats


wouldn't it be easier for users to keep an oversight if we had  
something like

Describe -->
	Buffer Modes
	Key or Mouse Operation
	...
	Key Bindings

(Keyboard Shortcuts)


In the main Help menu, I don't really understand why it is structured  
the way it is. Maybe I don't have to, fair enough. But one may wonder  
why the Emacs Tutorial is at the top, but the "Read the Emacs manual"  
is in the bottom half.

If it is "Tutorial", why is it not "Emacs manual" instead of "Read  
the Emacs Manual"?

"Find Emacs packages' sounds like "find extra packages", but one is a  
function that lists "Included packages", the other one is a text  
explaining something.

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Sun, 13 Nov 2005 23:28:50 -0500
> Cc: emacs-devel@gnu.org, miles@gnu.org
> 
> PS: By the way, AFAIK, keyboard shortcuts are the things displayed in menus
> saying how you can use the keyboard to get the same result.  Key bindings
> are slightly different since they exist completely independently from menus.
> The two are related but not identical.

Please don't forget that this discussion is about what to say
_in_the_menu_item_.  So it _is_ about those ``things displayed in
menus''.

Re: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Eli Zaretskii]

> Cc: Eli Zaretskii <eliz@gnu.org>,
>  emacs-devel@gnu.org
> From: David Reitter <david.reitter@gmail.com>
> Date: Mon, 14 Nov 2005 18:18:55 +0000
> 
> > Including it in parentheses can't hurt.
> 
> How about including it in the menu item name on systems that don't  
> display the help texts?

What systems are those?  I thought we display the help echo on all
systems, the only difference is whether they are displayed in tooltips
or in the echo area.

> Describe -->
> 	 Describe Buffer Modes...
> 	Describe Key or Mouse Operation ...
> 	Describe ...
> 	Describe ...
> 	List Key Bindings
> 	---
> 	Describe ...
> 	Describe ...
> 	Show all of Mule Stats
> 
> 
> wouldn't it be easier for users to keep an oversight if we had  
> something like
> 
> Describe -->
> 	Buffer Modes
> 	Key or Mouse Operation
> 	...
> 	Key Bindings

Sorry, this cannot be done by just dropping the "Describe" part.  The
reason is that on some systems (notably, the non-toolkit X build),
only the last submenu is displayed.  That is, if you click Help, then
select Describe, the initial Help menu disappears, and only the
Describe submenu stays on the screen.  So, if you remove the
"Describe" part, what one sees is incomprehensible.

Similar problem exists when one uses tmm (e.g., on a tty).

Re: Help menu

[Juri Linkov]

[-- Attachment #1: Type: text/plain, Size: 500 bytes --]

> Sorry, this cannot be done by just dropping the "Describe" part.  The
> reason is that on some systems (notably, the non-toolkit X build),
> only the last submenu is displayed.  That is, if you click Help, then
> select Describe, the initial Help menu disappears, and only the
> Describe submenu stays on the screen.  So, if you remove the
> "Describe" part, what one sees is incomprehensible.

Actually on the non-toolkit X build the parent's menu name is
displayed in the header of the submenu:


[-- Attachment #2: menu.png --]
[-- Type: image/png, Size: 3480 bytes --]

[-- Attachment #3: Type: text/plain, Size: 376 bytes --]


So "Describe" is unnecessarily duplicated.

> Similar problem exists when one uses tmm (e.g., on a tty).

This is rather a failure of tmm.  It doesn't display the full path
to the current submenu.  It would be useful to implement this.
And shorter menu names are much better for tmm to occupy less space
in its completion buffer.

-- 
Juri Linkov
http://www.jurta.org/emacs/

[-- Attachment #4: Type: text/plain, Size: 142 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-devel

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

Normally we don't get a lot of boring entries for self-insert-command
because consecutive characters are grouped into one line.  Why doesn't
that work for encoded-kbd-self-insert-ccl as well?

Any sort of reordering or abbreviation of boring entries
in describe-bindings would be fine.  For instance,
I was just thinking of putting all function keys (symbols)
after all characters (numbers).

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

      This causes encoded-kbd-mode to insert a bunch of  
    bindings to encoded-kbd-self-insert-ccl.

Why don't they get grouped together by the code that detects
a run of consecutive characters with the same binding?

Another idea: put key-translation-map last.

    One solution to the issue might be to simply have describe_map (in  
    keymap.c) not show any bindings to "self-insert" commands.

It would be bad to hide them.  Anyway, they normally use only two
lines, for unibyte characters, since the runs of consecutive characters
are combined:

SPC .. ~	self-insert-command
DEL		delete-backward-char
  .. ÿ		self-insert-command

However, I see that we have these lines for
MULE characters:


    <RHP of Latin-1>
      <<default>>	self-insert-command
    <RHP of Latin-2>
      <<default>>	self-insert-command
    <RHP of Latin-3>
      <<default>>	self-insert-command
    <RHP of Latin-4>
      <<default>>	self-insert-command
    <RHP of TIS620>
      <<default>>	self-insert-command

and dozens more.  It would be nice to combine those lines somehow.
Perhaps like this:

    <RHP of Latin-1> <RHP of Latin-2> <RHP of Latin-3>   self-insert-command
    <RHP of Latin-4> <RHP of TIS620> ...

Would someone like to write the code to do that?
It can be quite ad-hoc, as long as it is careful to check
that the raw data fits the change it makes.

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

Can we please drop the discussion of "keyboard shortcuts"?
I already said it was ok to add that term to the help echo.
Would someone please do that?  And meanwhile, would everone else
please stop arguing about this?

Re: Help menu

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Cc: david.reitter@gmail.com, emacs-devel@gnu.org
> Date: Tue, 15 Nov 2005 06:11:45 +0200
> 
> > Sorry, this cannot be done by just dropping the "Describe" part.  The
> > reason is that on some systems (notably, the non-toolkit X build),
> > only the last submenu is displayed.  That is, if you click Help, then
> > select Describe, the initial Help menu disappears, and only the
> > Describe submenu stays on the screen.  So, if you remove the
> > "Describe" part, what one sees is incomprehensible.
> 
> Actually on the non-toolkit X build the parent's menu name is
> displayed in the header of the submenu:

Yes, I know.  But, depending on your font definitions, it can be
barely visible, and even if one does pay attention and reads it, it is
not immediately apparent that this header is the beginning of the menu
items' names.

Re: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Richard M. Stallman]

    How about including it in the menu item name on systems that don't  
    display the help texts?

That is going too far.

    wouldn't it be easier for users to keep an oversight if we had  
    something like

    Describe -->
	    Buffer Modes
	    Key or Mouse Operation
	    ...
	    Key Bindings

I am not sure; what do others think?

RE: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Drew Adams]

    The "Describe" sub-menu could also drop the myriad of "Describe ..."
    Describe -->
    	Describe Buffer Modes...
    	Describe Key or Mouse Operation ...
    	Describe ...
    	Describe ...
    	List Key Bindings
    	---
    	Describe ...
    	Describe ...
    	Show all of Mule Stats

    wouldn't it be easier for users to keep an oversight if we had
    something like

    Describe -->
    	Buffer Modes
    	Key or Mouse Operation
    	...
    	Key Bindings (Keyboard Shortcuts)

FWIW, I've long done this in my library `help+.el' (which I haven't had time
to port to a version newer than Emacs 20).

 Describe ->

   This...             (C-h RET)
   Buffer Modes        (C-h m)
   Key...              (C-h k)
   Function...         (C-h f)
   Variable...         (C-h v)
   All Key Bindings    (C-h b)
   Major Mode Syntax   (C-h s)
   Apropos Commands... (C-h a)
   Apropos Variables...

The last two items should really be called "Commands..." and "Variables...",
but I just reuse the existing menu-items here (out of laziness). (There is
also an "Apropos" submenu of "Help".)

The first item, "This...", lets you type a key sequence or click something
(e.g. mode-line, minibuffer, Emacs-related name in a buffer, menu item), and
it gives you information on that object. The info is that provided by
`describe-*', plus apropos + Info doc, if appropriate.

    In the main Help menu, I don't really understand why it is structured
    the way it is. Maybe I don't have to, fair enough. But one may wonder
    why the Emacs Tutorial is at the top, but the "Read the Emacs manual"
    is in the bottom half.

    If it is "Tutorial", why is it not "Emacs manual" instead of "Read
    the Emacs Manual"?

    "Find Emacs packages' sounds like "find extra packages", but one is a
    function that lists "Included packages", the other one is a text
    explaining something.

FWIW - I have a Help-menu submenu "Learn More" that has submenus for
"Emacs", "Emacs Lisp", and additional items "Last Accessed Manual (`Info')",
"All Manuals (Info)", and "Unix Man Page...". Many of the top-level
Help-menu items are moved to the "Learn More" submenu (which is, itself,
structured). That is, it gives you high-level entries to Info, but it also
gives you separate access to Emacs stuff and Emacs-Lisp stuff.

In the case of Emacs 22+ (23?), we might consider something like that,
combining some top-level Help items with some of the stuff from submenus
"Search Documentation" and "More Manuals" in a hierarchical "Learn More"
submenu. The basic idea would be to group informational stuff together
(stuff that goes beyond `describe-*').

My (Emacs 20) "Learn More > Emacs" submenu looks like this:

  Tutorial  (C-h t)
  Manual (`Info')
  Find Command in Manual (C-h C-f)
  Find Key in Manual     (C-h C-k)
  ----------------
  Change History (News)  (C-h n)
  FAQ                    (C-h F)

The "Learn More > Emacs Lisp" submenu, for instance, looks like this:

  Intro
  Manual (`Info')
  ----------------
  Locate Library...           (C-h C-l)
  Locate Libraries by Keyword (C-h p)
  Change History              (C-h n)

The available menu items are those of Emacs 20 - they are not up-to-date for
22.

RE: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Drew Adams]

        wouldn't it be easier for users to keep an oversight if we had
        something like
        Describe -->
    	    Buffer Modes
    	    Key or Mouse Operation
    	    ...
    	    Key Bindings

    I am not sure; what do others think?

I already gave my opinion in a separate email, but in case it got lost in my
long message: I agree that the repetitive "Describe"s should be removed.

Re: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Richard M. Stallman]

    The first item, "This...", lets you type a key sequence or click something
    (e.g. mode-line, minibuffer, Emacs-related name in a buffer, menu item), and
    it gives you information on that object. The info is that provided by
    `describe-*', plus apropos + Info doc, if appropriate.

I don't see concretely how that differs from C-h k.
Could you give details?

Re: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Richard M. Stallman]

    In the case of Emacs 22+ (23?), we might consider something like that,
    combining some top-level Help items with some of the stuff from submenus
    "Search Documentation" and "More Manuals" in a hierarchical "Learn More"
    submenu. The basic idea would be to group informational stuff together
    (stuff that goes beyond `describe-*').

This could be desirable if it reduces the number of top-level entries
enough to matter.  But the tutorial should not be obscured by moving
it to the second level.  It should remain a top-level menu item.

Would someone like to propose such a change?

RE: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Drew Adams]

        The first item, "This...", lets you type a key sequence or
        click something (e.g. mode-line, minibuffer, Emacs-related
        name in a buffer, menu item), and it gives you information
        on that object. The info is that provided by
        `describe-*', plus apropos + Info doc, if appropriate.

    I don't see concretely how that differs from C-h k.
    Could you give details?

Something similar was discussed a while back, I believe. I'm not sure it's
worth people spending time considering now, but here's a description
(below). Take it as food for thought - some parts of it might be more useful
than others.

The basic idea is to let users discover features of Emacs by pointing to
them  (or their names) individually and saying "what's this?". It emulates
some UIs that provide a menu item that, when clicked, turns the mouse
pointer to a question mark. The user then clicks the pointer on some object,
and some info is provided on that object. In MS Windows, this is called
"What's This". The emacs-devel discussion a while back turned around the
question of whether or not Windows still has this feature etc. This is not
something that started with Windows, BTW - it was available in applications
long before Windows existed.

The "What's This" feature on Windows was often poorly implemented, providing
little help. However, Emacs already has online help about all of its
features - this would simply help users get to that help on a
feature-by-feature basis: just point and ask.

In my case, I didn't change the mouse pointer to a question mark, but that
would probably be a good thing to do. Also, I wanted to give a maximum of
info on the object, whereas Windows "What's This" tends to give minimal,
one-liner info (similar to tool-tip info). So, I combined info from the
various help commands (e.g. `describe-key', `apropos') with info from the
manual.

I simply let the various component help sources open their own windows
(frames in my case), so the user could decide which to read and which to
ignore (that was also the easiest implementation for me). That is, I made no
attempt to integrate the various help sources that I tapped. Emacs help is
more or less detailed, depending, for example, on whether it is provided by
`describe-variable', `apropos', `apropos-documentation', or `info'. Each of
these (if available and appropriate) was displayed in a separate frame - the
user could choose which to examine, depending on the context and the user's
background.

Any feature that you can designate through the UI is a candidate for
explaining this way, BTW, not just UI features. For example, you can point
to an Emacs name (wherever you see it) and get info about it.

This was also the case for Windows' "What's This", to some extent, though
often it was not clear if you were asking for help about a UI feature or
about the underlying functionality. Obviously, there needs to be some
hierarchy in the implementation, to guess whether the user wants info on
some name or the buffer where it occurs, and so on.

Anyway, here's the description (from the doc string of command
`help-on-click/key':

 "(help-on-click/key KEY)

 Give help on a key/menu sequence or object clicked with the mouse.
 The object can be any part of an Emacs window or a name appearing in a
 buffer.  You can do any of the following:

    type a key sequence (e.g. `C-M-s')
    choose a menu item (e.g. [menu-bar files open-file])
    click on a scroll bar
    click on the mode line
    click in the minibuffer
    click on an Emacs-related name in a buffer: apropos is called
    click anywhere else in a buffer: its modes are described

 Help is generally provided using `describe-key' and the Emacs online
 manual (via `Info-goto-emacs-key-command-node').  If no entry is found
 in the index of the Emacs manual, then the manual is searched from the
 beginning for literal occurrences of KEY.

 For example, the KEY `C-g' is not in the index (for some reason), so
 the manual is searched.  (Once an occurrence is found, you can
 repeatedly type `s' in *Info* to search for additional occurrences.)

 If you click on a name in a buffer, then `apropos-documentation' and
 `apropos' are used to find information on the name.  These functions
 are not used when you do something besides click on a name.

 If you click elsewhere in a buffer other than the minibuffer, then
 `describe-mode' is used to describe the buffer's current mode(s)."

Again, this was for Emacs 20, so this description would not be complete for
Emacs 22 (there are a lot more things to point to now: fringe etc.).

And the comment about `C-g' not being in the Emacs-manual index is no longer
true. Nevertheless, that functionality might still be useful: search the
manual text if the term to find is not in the index.

The expectation, BTW, was not that users would learn about this by reading
the above help - that would be confusing for someone who didn't know what a
minibuffer was etc. The idea was that users would just try it (click
"Describe > This..." in the menu) and find out what it is by using it.

If such a feature were considered for Emacs (for after the release), these
aspects could be discussed:

 - What info should be provided (e.g. what info sources, how much detail)?

 - For what objects?

 - How would a user designate each of those objects?

This command is intended to help people to discover Emacs features. The
general idea is, I think, a good one, regardless of what design might be
used. Emacs is feature-rich, and its UI offers a lot that many newbies have
never experienced elsewhere (it is unusual). And many of the UI features are
not obvious (not to mention the non-UI features).

HTH.

Re: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Richard M. Stallman]

	type a key sequence (e.g. `C-M-s')
	choose a menu item (e.g. [menu-bar files open-file])
	click on a scroll bar
	click on the mode line
	click in the minibuffer
	click on an Emacs-related name in a buffer: apropos is called
	click anywhere else in a buffer: its modes are described

It sounds like this does everything that C-x k does
except in the case of clicking on the buffer contents.
Is that right?

     Help is generally provided using `describe-key' and the Emacs online
     manual (via `Info-goto-emacs-key-command-node').  If no entry is found
     in the index of the Emacs manual, then the manual is searched from the
     beginning for literal occurrences of KEY.

I don't quite understand.  How does it decide which one of these to do?
Does it always try each of them?

RE: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Drew Adams]

    	type a key sequence (e.g. `C-M-s')
    	choose a menu item (e.g. [menu-bar files open-file])
    	click on a scroll bar
    	click on the mode line
    	click in the minibuffer
    	click on an Emacs-related name in a buffer: apropos is called
    	click anywhere else in a buffer: its modes are described

    It sounds like this does everything that C-x k does
    except in the case of clicking on the buffer contents.
    Is that right?

I'm not that familiar with the current C-x k. If it gives help on the
mode-line, minibuffer, and scroll-bar, then yes.

However, this gives a lot more info than what `describe-key' provides. It
tries to give a maximum of info, by using apropos, apropos-documentation
(both with apropos-do-all=t), and `Info-goto-emacs-key-command-node', in
addition to `describe-key'. The idea is essentially, "Find me all
information about ____".

         Help is generally provided using `describe-key' and the
         Emacs online manual (via `Info-goto-emacs-key-command-node').
         If no entry is found in the index of the Emacs manual, then
         the manual is searched from the
         beginning for literal occurrences of KEY.

    I don't quite understand.  How does it decide which one of these to do?
    Does it always try each of them?

The important thing is the general idea of providing something like this;
it's not important what my implementation does. Anyway, it does this:

The type of the object is tested and used to determine what help to gather.
If `describe-key' makes sense for the object (key, mode-line, menu-bar menu
item, mouse-menu menu item, etc.), then that is called. If
`Info-goto-emacs-key-command-node' also makes sense, then that is called
too. (The first info is in *Help*; the second in *Info*.) Specific objects
such as mode-line and minibuffer open the appropriate Info node directly.

If the object is a mouse click on text, then apropos-documentation is called
on symbol-at-point (with apropos-do-all bound to t). Next, apropos is called
on the symbol. (If apropos-documentation produced something, then buffer
*Apropos* is renamed to *Apropos Doc*.)

If a buffer is clicked, but not on text, then `describe-mode' is called.

A message tells you where to look for the help, depending on which sources
produced it:

 "`%s': summary in *Help* buffer; doc in *info* buffer."

 "`%s': summary in *Help* buffer."

 "`%s': doc in *info* buffer."

 "`%s' is undefined."

 "See *Apropos* and *Apropos Doc* buffers."

 "See information on `%s' in the *Apropos* buffer."

 "See information on `%s' in the *Apropos Doc* buffer."

 "No information found regarding `%s'."

 "Mode(s) of buffer `%s' are described in *Help* buffer."

Note: Some basic functions, such as `Info-goto-emacs-key-command-node', were
tweaked to return non-nil if Info doc is found. These are in library
info+.el, not help+.el.

`Info-goto-emacs-key-command-node' was also tweaked to call `Info-search' if
not found. That is, if the term can't be found in the index, then a literal
search for it is made.

The source code is here:
 http://www.emacswiki.org/cgi-bin/wiki/help%2b.el

 http://www.emacswiki.org/cgi-bin/wiki/info%2b.el

help+.el is only for Emacs 20. info+.el works with Emacs 22 too.

HTH.

Re: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Fri, 18 Nov 2005 09:58:11 -0800
> 
>     	type a key sequence (e.g. `C-M-s')
>     	choose a menu item (e.g. [menu-bar files open-file])
>     	click on a scroll bar
>     	click on the mode line
>     	click in the minibuffer
>     	click on an Emacs-related name in a buffer: apropos is called
>     	click anywhere else in a buffer: its modes are described
> 
>     It sounds like this does everything that C-x k does
>     except in the case of clicking on the buffer contents.
>     Is that right?
> 
> I'm not that familiar with the current C-x k. If it gives help on the
> mode-line, minibuffer, and scroll-bar, then yes.

It's C-h k, and yes, it does tell what clicking on each portion of the
display does.

Re: describe-bindings: ^L, bad order, naming

[Eli Zaretskii]

> From: "Richard M. Stallman" <rms@gnu.org>
> Date: Tue, 15 Nov 2005 00:43:40 -0500
> Cc: miles@gnu.org, monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> Can we please drop the discussion of "keyboard shortcuts"?
> I already said it was ok to add that term to the help echo.
> Would someone please do that?

Done.

Re: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Richard M. Stallman]

    > I'm not that familiar with the current C-x k. If it gives help on the
    > mode-line, minibuffer, and scroll-bar, then yes.

    It's C-h k, and yes, it does tell what clicking on each portion of the
    display does.

What does it mean to "give help on the minibuffer"?

Re: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Richard M. Stallman]

This sort of command seems like a good idea.  It is a shame that we
cannot install your code, for want of papers.  But if someone
wants to implement a command along these general lines,
we could install it at a suitable time.

RE: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Drew Adams]

    This sort of command seems like a good idea.  It is a shame that we
    cannot install your code, for want of papers.  But if someone
    wants to implement a command along these general lines,
    we could install it at a suitable time.

Yes, I'm sorry about that, as you know - it's beyond my control (short of
quitting my job).

It's probably not such a bad thing, however, in this case:

 - The code is not up-to-date wrt Emacs 22 - it works only with Emacs 20.

 - It's probably worth rethinking parts of the design.

WRT the design: I use pop-up-frames = t, so the opening of multiple frames
for the results of apropos*, describe-*, and Info is not too distracting for
the user (IMO). However, with pop-up-frames = nil, the opening of multiple
windows should perhaps be reconsidered or somehow organized, as it might be
a bit confusing.

RE: Help menu (was: Re: describe-bindings: ^L, bad order, naming)

[Drew Adams]

        > I'm not that familiar with the current C-x k. If it gives
          help on the mode-line, minibuffer, and scroll-bar, then yes.

        It's C-h k, and yes, it does tell what clicking on each
        portion of the display does.

    What does it mean to "give help on the minibuffer"?

It just displays the Info section about the minibuffer - node Minibuffer in
the Emacs manual.

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

    Attached is a screenshot showing the (beginning of the)
    encoded-kbd-self-insert-ccl stuff, which is, I think, the "uninteresting
    technical stuff" David referred to. There are 122 lines of such bindings
    listed at the beginning of the `describe-bindings' *Help* buffer.

I think I have fixed this, but I don't know how to make
any encoded-kbd-self-insert-ccl entries appear.
What exactly do I need to do, to reproduce them?

Re: describe-bindings: ^L, bad order, naming

[Stefan Monnier]

>     Attached is a screenshot showing the (beginning of the)
>     encoded-kbd-self-insert-ccl stuff, which is, I think, the "uninteresting
>     technical stuff" David referred to. There are 122 lines of such bindings
>     listed at the beginning of the `describe-bindings' *Help* buffer.

> I think I have fixed this, but I don't know how to make
> any encoded-kbd-self-insert-ccl entries appear.
> What exactly do I need to do, to reproduce them?

M-x set-keyboard-coding-system RET

and then select a coding-system like iso-2022 or utf-8 or ...

Running in a utf-8 locale should do the trick as well (under a tty of
course).


        Stefan

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

    M-x set-keyboard-coding-system RET

    and then select a coding-system like iso-2022 or utf-8 or ...

That did the trick.  My code seems to work; it collapses all of those
bindings to one line.  I will install it.

    Running in a utf-8 locale should do the trick as well (under a tty of
    course).

That was not an option for me, since I don't know the name of any
valid UTF-8 locale,

Re: describe-bindings: ^L, bad order, naming

[Stefan Monnier]

>     Running in a utf-8 locale should do the trick as well (under a tty of
>     course).

> That was not an option for me, since I don't know the name of any
> valid UTF-8 locale,

I use LANG=fr_CH.UTF-8 (on Debian Sarge)
But it seems this varies depending on the system you're using and how
it's configured.


        Stefan

Re: describe-bindings: ^L, bad order, naming

[Andreas Schwab]

"Richard M. Stallman" <rms@gnu.org> writes:

> That was not an option for me, since I don't know the name of any
> valid UTF-8 locale,

`locale -a' should list all valid locales on your system.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux Products GmbH, Maxfeldstraße 5, 90409 Nürnberg, Germany
PGP key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: describe-bindings: ^L, bad order, naming

[Richard M. Stallman]

    `locale -a' should list all valid locales on your system.

Thanks.  My system has no UTF-8 locales; it is too old.
Fortunately I was able to test it the other way.