C-h K and C-h F in the Help menu

C-h K and C-h F in the Help menu

[Eli Zaretskii]

"Find Key in Manual" and "Find Command in Manual" are in the "More
Manuals" submenu of the "Help" menu.  I think they should either in
"Search Documentation" or in "Describe", because these two submenus
are about Emacs, while "More Manuals" is about manuals of other
packages.

Does anyone object to moving these two items?

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

Eli Zaretskii wrote:
> "Find Key in Manual" and "Find Command in Manual" are in the "More
> Manuals" submenu of the "Help" menu.  I think they should either in
> "Search Documentation" or in "Describe", because these two submenus
> are about Emacs, while "More Manuals" is about manuals of other
> packages.
>
> Does anyone object to moving these two items?
>
>   
Sounds ok to me.

I recently got some comments about the help menu in CVS Emacs from a 
long term Emacs user and fan (+15 y usage). One of the comments were 
that there are too many things in the help menu. I wonder if it could 
help if it was restructured a bit more again? Some suggestions for quick 
fixes:

- Just one tutorial entry with two subentries:

    Tutorial
        Tutorial in English
        Tutorial in other languages

- Just one bug entry with two subentries:

    Emacs Problems and Bugs
        Emacs Known Problems
        Send Bug Report

- Just one about entry:

    About Emacs
        Welcome Screen
        Copying Conditions
        (Non)Warranty
        Getting New Versions

- Move "Find Emacs Packages" to under "Search Documentation"

Another complaint was that the manual is not easily available in HTML 
which is the "standard" today. Could perhaps the Emacs Info node start 
with a link to a description of how to get the manual in HTML format?

Re: C-h K and C-h F in the Help menu

[David Kastrup]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> I recently got some comments about the help menu in CVS Emacs from a
> long term Emacs user and fan (+15 y usage). One of the comments were
> that there are too many things in the help menu. I wonder if it could
> help if it was restructured a bit more again? Some suggestions for
> quick fixes:
>
> - Just one tutorial entry with two subentries:
>
>    Tutorial
>        Tutorial in English
>        Tutorial in other languages
>
> - Just one bug entry with two subentries:
>
>    Emacs Problems and Bugs
>        Emacs Known Problems
>        Send Bug Report

I don't think it worthwhile to make submenus with just two entries.

> - Just one about entry:
>
>    About Emacs
>        Welcome Screen
>        Copying Conditions
>        (Non)Warranty
>        Getting New Versions

Sounds reasonable.

> - Move "Find Emacs Packages" to under "Search Documentation"

Does not belong there.

> Another complaint was that the manual is not easily available in
> HTML which is the "standard" today. Could perhaps the Emacs Info
> node start with a link to a description of how to get the manual in
> HTML format?

Not a good idea since the navigation in HTML is much worse than in
info-mode.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

David Kastrup wrote:
>> - Just one tutorial entry with two subentries:
>>
>>    Tutorial
>>        Tutorial in English
>>        Tutorial in other languages
>>
>> - Just one bug entry with two subentries:
>>
>>    Emacs Problems and Bugs
>>        Emacs Known Problems
>>        Send Bug Report
>>     
>
> I don't think it worthwhile to make submenus with just two entries.
>   
It still makes the help menu two entries shorter. That is significant 
compared to our short memory span which is often said to have a capacity 
of 5-9 entries.

>> - Move "Find Emacs Packages" to under "Search Documentation"
>>     
>
> Does not belong there.
>   
Maybe you are right, but is it not documentation you are searching for 
in "Find Emacs Packages"?

>   
>> Another complaint was that the manual is not easily available in
>> HTML which is the "standard" today. Could perhaps the Emacs Info
>> node start with a link to a description of how to get the manual in
>> HTML format?
>>     
>
> Not a good idea since the navigation in HTML is much worse than in
> info-mode.
>   
Maybe not for a novice?

Re: C-h K and C-h F in the Help menu

[David Kastrup]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> David Kastrup wrote:
>
>>> - Move "Find Emacs Packages" to under "Search Documentation"
>>>     
>>
>> Does not belong there.
>>   
> Maybe you are right, but is it not documentation you are searching
> for in "Find Emacs Packages"?

No.  Not every information is documentation.  It would be more fitting
in "About Emacs", but still not 100%, as it talks about parts of Emacs
instead of Emacs as a whole.

>>> Another complaint was that the manual is not easily available in
>>> HTML which is the "standard" today. Could perhaps the Emacs Info
>>> node start with a link to a description of how to get the manual in
>>> HTML format?
>>>     
>>
>> Not a good idea since the navigation in HTML is much worse than in
>> info-mode.
>>   
> Maybe not for a novice?

We don't want to lead users into dead ends, even if it is easy to do.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

David Kastrup wrote:
>> Maybe you are right, but is it not documentation you are searching
>> for in "Find Emacs Packages"?
>>     
>
> No.  Not every information is documentation.
>   
You have a point there, but are you sure that it actually fits in this case?

>>> Not a good idea since the navigation in HTML is much worse than in
>>> info-mode.
>>>   
>>>       
>> Maybe not for a novice?
>>     
>
> We don't want to lead users into dead ends, even if it is easy to do.
>   
They are already there. I for one started reading the documentation in 
HTML before using Info. Now I only use Info of course, but it took quite 
a while. I think the HTML documentation helped me quite a lot in the 
beginning. Too many new things at once makes it a bit harder to get 
somewhere.

Re: C-h K and C-h F in the Help menu

[Mathias Dahl]

David wrote:

> >> Not a good idea since the navigation in HTML is much worse than in
> >> info-mode.
> >>
> > Maybe not for a novice?
>
> We don't want to lead users into dead ends, even if it is easy to do.

I can understand if there is a problem linking to the HTML-version of
the documentation (relying on a link to an external resource could be
a problem), but I don't see why the HTML-version should be that
bad. Exactly why is the "navigation much worse" and what is the "dead
end" here? People are used to find their way around HTML-pages these
days and modern browsers have good search capabilities. I think that
we might scare new users by just providing the internal Info
system. Personally I use both, depending on my mood mostly... :)

Re: C-h K and C-h F in the Help menu

[David Kastrup]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> David Kastrup wrote:
>>> Maybe you are right, but is it not documentation you are searching
>>> for in "Find Emacs Packages"?
>>>     
>>
>> No.  Not every information is documentation.
>>   
> You have a point there, but are you sure that it actually fits in this case?
>
>>>> Not a good idea since the navigation in HTML is much worse than in
>>>> info-mode.
>>>>         
>>> Maybe not for a novice?
>>>     
>>
>> We don't want to lead users into dead ends, even if it is easy to do.
>>   
> They are already there. I for one started reading the documentation in
> HTML before using Info. Now I only use Info of course, but it took
> quite a while. I think the HTML documentation helped me quite a lot in
> the beginning. Too many new things at once makes it a bit harder to
> get somewhere.

The navigation is in the menus and you page forward with space and
backward with backspace.

I am afraid that this is much better than the current state of Firefox
where keys will do nothing unless you clicked into the page
previously, and then will skip by quite unpredictable amounts and
might get stuck.

No, I don't think that an external reader is useful for somebody
learning Emacs.  The HTML is a red herring: the underlying format is
not user-visible, anyway.  I would not want to start an external info
reader (instead of an external HTML reader) either.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: C-h K and C-h F in the Help menu

[David Kastrup]

"Mathias Dahl" <mathias.dahl@gmail.com> writes:

> David wrote:
>
>> >> Not a good idea since the navigation in HTML is much worse than in
>> >> info-mode.
>> >>
>> > Maybe not for a novice?
>>
>> We don't want to lead users into dead ends, even if it is easy to do.
>
> I can understand if there is a problem linking to the HTML-version
> of the documentation (relying on a link to an external resource
> could be a problem), but I don't see why the HTML-version should be
> that bad. Exactly why is the "navigation much worse"

You don't have "up", "next", "previous", "top" keyboard keys, and the
respective buttons scroll around with the rest of the page.  You don't
have a working index command, and if you look manually in the index
(by choosing first the top node, then the index node) you don't have
completion.  If you jumped to an index location, you can't use "," to
jump to the next occurence.  You can't search for phrases except in
the current node.  You can't page scroll through successive nodes by
pressing just "space" repeatedly.  You can't follow links into other
info manuals.

> and what is the "dead end" here?

An utterly crippled hypertext system which the user thinks adequate
because he does not know the alternatives.

> People are used to find their way around HTML-pages these days and
> modern browsers have good search capabilities.

Come off it.  You'd need a web crawler to search more than a single
node.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

David Kastrup wrote:
> The navigation is in the menus and you page forward with space and
> backward with backspace.
>
> I am afraid that this is much better than the current state of Firefox
> where keys will do nothing unless you clicked into the page
> previously, and then will skip by quite unpredictable amounts and
> might get stuck.
>   
The merits of Info that you point to here are true but is quite another 
matter than if it is better for a novice user.

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

David Kastrup wrote:
> Come off it.  You'd need a web crawler to search more than a single
> node.
>   
That is one of the things that I expect to change quite soon. It is 
quite natural to integrate an index of the local discs with the web browser.

Re: C-h K and C-h F in the Help menu

[David Kastrup]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> David Kastrup wrote:
>> The navigation is in the menus and you page forward with space and
>> backward with backspace.
>>
>> I am afraid that this is much better than the current state of Firefox
>> where keys will do nothing unless you clicked into the page
>> previously, and then will skip by quite unpredictable amounts and
>> might get stuck.
>>   
> The merits of Info that you point to here are true but is quite
> another matter than if it is better for a novice user.

A novice user will be more comfortable at first using firefox rather
than info-mode, more comfortable using nautilus rather than dired, and
more comfortable using nano rather than a major mode from Emacs.

So it would seem that it is better for a novice not to use Emacs at
all, and consequently we need not accommodate novices according to
your logic, since they have no business learning Emacs.

Seriously, it does not make sense for Emacs to promote not using Emacs
when doing so is by far the best solution.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: C-h K and C-h F in the Help menu

[David Kastrup]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> David Kastrup wrote:
>> Come off it.  You'd need a web crawler to search more than a single
>> node.

> That is one of the things that I expect to change quite soon. It is
> quite natural to integrate an index of the local discs with the web
> browser.

So what?  This would still not structure the documentation into
searchable domains corresponding to single manuals.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

David Kastrup wrote:
> Lennart Borgman <lennart.borgman.073@student.lu.se> writes:
>
>   
>> David Kastrup wrote:
>>     
>>> Come off it.  You'd need a web crawler to search more than a single
>>> node.
>>>       
>
>   
>> That is one of the things that I expect to change quite soon. It is
>> quite natural to integrate an index of the local discs with the web
>> browser.
>>     
>
> So what?  This would still not structure the documentation into
> searchable domains corresponding to single manuals.
>   
Are you sure? Can't the directory structures be used for this?

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

David Kastrup wrote:
> A novice user will be more comfortable at first using firefox rather
> than info-mode, more comfortable using nautilus rather than dired, and
> more comfortable using nano rather than a major mode from Emacs.
>
> So it would seem that it is better for a novice not to use Emacs at
> all, and consequently we need not accommodate novices according to
> your logic, since they have no business learning Emacs.
>
> Seriously, it does not make sense for Emacs to promote not using Emacs
> when doing so is by far the best solution.
>   
:-)

But my point was that the novice user might be better of learning Emacs 
in small steps. It has been fun arguing with you but I think I have said 
most of what I want to say now.

Re: C-h K and C-h F in the Help menu

[David Kastrup]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> David Kastrup wrote:
>
>> Seriously, it does not make sense for Emacs to promote not using
>> Emacs when doing so is by far the best solution.
>
> But my point was that the novice user might be better of learning
> Emacs in small steps.

Info is a small step.

> It has been fun arguing with you but I think I have said most of
> what I want to say now.

Well, I said more than I would have wanted to.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: C-h K and C-h F in the Help menu

[David Kastrup]

Lennart Borgman <lennart.borgman.073@student.lu.se> writes:

> David Kastrup wrote:
>> Lennart Borgman <lennart.borgman.073@student.lu.se> writes:
>>   
>>> David Kastrup wrote:
>>>     
>>>> Come off it.  You'd need a web crawler to search more than a
>>>> single node.
>>   
>>> That is one of the things that I expect to change quite soon. It
>>> is quite natural to integrate an index of the local discs with the
>>> web browser.
>>
>> So what?  This would still not structure the documentation into
>> searchable domains corresponding to single manuals.
>>   
> Are you sure? Can't the directory structures be used for this?

Sounds so much easier than using the info reader.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> Cc: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> From: David Kastrup <dak@gnu.org>
> Date: Sun, 21 May 2006 01:20:38 +0200
> 
> > It has been fun arguing with you but I think I have said most of
> > what I want to say now.
> 
> Well, I said more than I would have wanted to.

That's what you get for arguing so late in the night ;-)

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> Date: Sun, 21 May 2006 01:16:43 +0200
> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
> CC: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> 
> But my point was that the novice user might be better of learning Emacs 
> in small steps.

Yes, and their very first step should be to learn the Emacs
documentation system, i.e. Info.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> Date: Sun, 21 May 2006 00:28:39 +0200
> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
> CC: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> 
> > We don't want to lead users into dead ends, even if it is easy to do.
> >   
> They are already there.

Then we should help them out.  Please become part of those who try to
educate newbies to use Info as their main documentation system.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> Date: Sat, 20 May 2006 23:19:02 +0200
> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
> CC:  emacs-devel@gnu.org
> 
> I recently got some comments about the help menu in CVS Emacs from a 
> long term Emacs user and fan (+15 y usage). One of the comments were 
> that there are too many things in the help menu.

For some value of ``too many'': we have 17 entries there.  Why is this
bad?  Each entry can be useful in specific situations.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> Date: Sat, 20 May 2006 23:54:47 +0200
> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
> CC: Eli Zaretskii <eliz@gnu.org>,  emacs-devel@gnu.org
> 
> >> - Move "Find Emacs Packages" to under "Search Documentation"
> >>     
> >
> > Does not belong there.
> >   
> Maybe you are right, but is it not documentation you are searching for 
> in "Find Emacs Packages"?

No, it searches the keywords in the comments of each package.

Re: C-h K and C-h F in the Help menu

[Juri Linkov]

>> - Move "Find Emacs Packages" to under "Search Documentation"
>
> Does not belong there.

Surely, it doesn't belong there, but I think that two items
"Find Emacs Packages" and "Find Extra Packages" should be located
together (in a new submenu).

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

Re: C-h K and C-h F in the Help menu

[Juri Linkov]

> "Find Key in Manual" and "Find Command in Manual" are in the "More
> Manuals" submenu of the "Help" menu.  I think they should either in
> "Search Documentation" or in "Describe", because these two submenus
> are about Emacs, while "More Manuals" is about manuals of other
> packages.
>
> Does anyone object to moving these two items?

I think the most suitable menu for "Find Key in Manual" and
"Find Command in Manual" is the first you mentioned, i.e.
"Search Documentation", since this menu is now shorter than "Describe",
and its items have the same prefix "Find ..." unlike the items
in "Describe" that have the prefix "Describe ..." and create the
*Help* buffer instead of *Info*.

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

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

Eli Zaretskii wrote:
>> Date: Sat, 20 May 2006 23:19:02 +0200
>> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
>> CC:  emacs-devel@gnu.org
>>
>> I recently got some comments about the help menu in CVS Emacs from a 
>> long term Emacs user and fan (+15 y usage). One of the comments were 
>> that there are too many things in the help menu.
>>     
>
> For some value of ``too many'': we have 17 entries there.  Why is this
> bad?  Each entry can be useful in specific situations.
>   
It is a good question. As I understand it the complaints was from a user 
interface view. Such a view is a mixture of logical and psychological 
matters. Neither a logical or a psychological argument is then entirely 
useful on its own even if they on their own are completely valid.

At first sight one might think that the time to find something in a menu 
is proportional to the length of the menu. I think however that the time 
required rises much faster, but I have not read any research about this. 
As I said before one of the factors is probably the short term memory 
span. This means that clear grouping with horizontal lines will probably 
help (as soon as the user understands the grouping). In the process of 
trying to grasp the grouping it seems to me that there should be a big 
advantage in fewer items.

Submenus will reduce the number of items even if there is only two 
subitems and I believe that this will be helpful for the reasons I have 
tried to outline above.

Re: C-h K and C-h F in the Help menu

[Slawomir Nowaczyk]

On Sun, 21 May 2006 00:48:00 +0200
David Kastrup <dak@gnu.org> wrote:

#>>>>> Not a good idea since the navigation in HTML is much worse than
#>>>>> in info-mode.

#>>> We don't want to lead users into dead ends, even if it is easy to
#>>> do.

#> The navigation is in the menus 

Those are all true... but the usefulness depends on how do you intend
to use the manual.

#> and you page forward with space and backward with backspace.

I have the same in my web browser.

#> No, I don't think that an external reader is useful for somebody
#> learning Emacs.

Well, it depends... I have, for example, an ancient handheld for which
I believe no info reader exists. I do have a html browser there,
though. I often use it to read various stuff when I have some free
time while travelling, for example. Having an opportunity to read
emacs manual would be nice.

Besides, my emacs is optimised for *writing* stuff, while my web
browser is optimised for *reading* stuff. I use fixed-width font in
emacs, for example, and proportional in web browser.

Sure, if I just want to check something while working, I would use
emacs info reader every day. But sometimes I want to read large chunks
of the manual, in order to learn something.

I *do* see some benefits of html format in such cases.

-- 
 Best wishes,
   Slawomir Nowaczyk
     ( slawomir.nowaczyk.847@student.lu.se )

Strange how people who don't even know their neighbors
are extremely curious to know if there's extra-terrestrial life.

Re: C-h K and C-h F in the Help menu

[Mathias Dahl]

> You don't have "up", "next", "previous", "top" keyboard keys, and the
> respective buttons scroll around with the rest of the page.
> ...

Okay okay okay, I get your point. I won't argue with you on the
benefits on using Info vs HTML; as I said I use it myself when I feel
like using it. Some days though, I just like to browse around some
plain "dumb" HTML. And, I won't give in here, "forcing" new users to
use this (for some of them at least) "strange" Info interface when we
could also provide a link (it would not need to be the default) to
some HTML-version of the documentation, is a pity. Just because we
know Info is superior to HTML in many respect does not mean that we
should not provide an alternative.

For example, we could add a new menu item, "Read the manual online"
(or maybe "Read the HTML manual online") under the sub menu Help ->
More manuals.

I did not read this thread from the beginning so I probably should stop now...

Re: C-h K and C-h F in the Help menu

[David Kastrup]

"Mathias Dahl" <mathias.dahl@gmail.com> writes:

>> You don't have "up", "next", "previous", "top" keyboard keys, and the
>> respective buttons scroll around with the rest of the page.
>> ...
>
> Okay okay okay, I get your point. I won't argue with you on the
> benefits on using Info vs HTML; as I said I use it myself when I
> feel like using it. Some days though, I just like to browse around
> some plain "dumb" HTML. And, I won't give in here, "forcing" new
> users to use this (for some of them at least) "strange" Info
> interface when we could also provide a link (it would not need to be
> the default) to some HTML-version of the documentation, is a
> pity. Just because we know Info is superior to HTML in many respect
> does not mean that we should not provide an alternative.
>
> For example, we could add a new menu item, "Read the manual online"
> (or maybe "Read the HTML manual online") under the sub menu Help ->
> More manuals.

I strongly object.  From inside of Emacs, the info manual is the
appropriate resource.  Whether we keep a HTML version in our tree for
the sake of offline reading (when Emacs is not available) is a
different thing, and how we may point the user to its availability.
But starting a HTML browser on it via an Emacs menu entry is utterly
the wrong thing to do.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: C-h K and C-h F in the Help menu

[Andreas Schwab]

"Mathias Dahl" <mathias.dahl@gmail.com> writes:

>> You don't have "up", "next", "previous", "top" keyboard keys, and the
>> respective buttons scroll around with the rest of the page.
>> ...
>
> Okay okay okay, I get your point. I won't argue with you on the
> benefits on using Info vs HTML; as I said I use it myself when I feel
> like using it. Some days though, I just like to browse around some
> plain "dumb" HTML.

There is info2html which can be used to translate info to html on the
fly.  Konqueror is using it for info URLs.

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: C-h K and C-h F in the Help menu

[Richard Stallman]

    "Find Key in Manual" and "Find Command in Manual" are in the "More
    Manuals" submenu of the "Help" menu.  I think they should either in
    "Search Documentation" or in "Describe", because these two submenus
    are about Emacs, while "More Manuals" is about manuals of other
    packages.

"Search Documentation" seems like the right place.

Re: C-h K and C-h F in the Help menu

[Richard Stallman]

    - Just one tutorial entry with two subentries:
    
       Tutorial
           Tutorial in English
           Tutorial in other languages
    
I think it is worth having them both at the current level.

    - Just one bug entry with two subentries:

	Emacs Problems and Bugs
	    Emacs Known Problems
	    Send Bug Report

That is good.  We could add one more item that takes you to
the Emacs Manual chapter on how to send useful bug reports.

    - Just one about entry:

	About Emacs
	    Welcome Screen
	    Copying Conditions
	    (Non)Warranty
	    Getting New Versions

That seems good.

    - Move "Find Emacs Packages" to under "Search Documentation"

I don't think so.  That isn't searching documentation, it is
searching through the packages.

Re: C-h K and C-h F in the Help menu

[Richard Stallman]

    Another complaint was that the manual is not easily available in HTML 
    which is the "standard" today.

Info is our standard documentation format.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> Date: Sun, 21 May 2006 09:38:49 +0200
> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
> CC:  emacs-devel@gnu.org
> 
> At first sight one might think that the time to find something in a menu 
> is proportional to the length of the menu. I think however that the time 
> required rises much faster, but I have not read any research about this. 

That might be so, but several popular GUI programs I checked have
menus whose length is comparable or even larger than our 17 items.  So
I should we shouldn't bother to change that.

> Submenus will reduce the number of items

And increase the time required to figure out in which submenu I find
what I'm looking for.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> Date: Sun, 21 May 2006 11:57:47 +0200
> From: "Mathias Dahl" <mathias.dahl@gmail.com>
> Cc: "Lennart Borgman" <lennart.borgman.073@student.lu.se>, 
> 	"Eli Zaretskii" <eliz@gnu.org>, emacs-devel@gnu.org
> 
> And, I won't give in here, "forcing" new users to
> use this (for some of them at least) "strange" Info interface when we
> could also provide a link (it would not need to be the default) to
> some HTML-version of the documentation, is a pity. Just because we

No one's forcing anyone.  The HTML version of the Emacs manuals is
accessible on-line at the GNU Web site.

> For example, we could add a new menu item, "Read the manual online"
> (or maybe "Read the HTML manual online") under the sub menu Help ->
> More manuals.

I hate programs that reach out to the network to read the docs.  If I
need to find an external doc, I will do it myself.

Re: C-h K and C-h F in the Help menu

[Alan Mackenzie]

Hi, Lennart!

Just sticking my oar in a bit ....

On Sun, 21 May 2006, Lennart Borgman wrote:

>Eli Zaretskii wrote:
>>> Date: Sat, 20 May 2006 23:19:02 +0200
>>> From: Lennart Borgman <lennart.borgman.073@student.lu.se>
>>> CC:  emacs-devel@gnu.org

>>> I recently got some comments about the help menu in CVS Emacs from a
>>> long term Emacs user and fan (+15 y usage). One of the comments were
>>> that there are too many things in the help menu.

>> For some value of ``too many'': we have 17 entries there.  Why is this
>> bad?  Each entry can be useful in specific situations.

>It is a good question. As I understand it the complaints was from a user
>interface view. Such a view is a mixture of logical and psychological
>matters. Neither a logical or a psychological argument is then entirely
>useful on its own even if they on their own are completely valid.

>At first sight one might think that the time to find something in a menu
>is proportional to the length of the menu. I think however that the time
>required rises much faster, but I have not read any research about this.
>As I said before one of the factors is probably the short term memory
>span. This means that clear grouping with horizontal lines will probably
>help (as soon as the user understands the grouping).

I think this is right.

>In the process of trying to grasp the grouping it seems to me that there
>should be a big advantage in fewer items.

>Submenus will reduce the number of items even if there is only two 
>subitems and I believe that this will be helpful for the reasons I have 
>tried to outline above.

Submenus don't reduce the number of items.  They just make some of them
invisible, thus _increasing_ search effort.  Activating a menu item when
it is hidden within a sub-menu is much slower than when it is directly
there.

A deep tree structure is fine if you're playing a dungeons and dragons
type game, but can be infuriating if you need to do a depth-first search
to find some "lost" menu item.  That's one of the main reasons I detest
most menu interfaces.

The way to reduce the number of items is to reduce the number of items.
If 17 is too many (which I can quite well believe), then categorise them
into "must have", "should have" and "nice to have", and get rid of all of
the last lot.  :-)

-- 
Alan.

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

Alan Mackenzie wrote:
> Hi, Lennart!
>
>   
Hi Alan!
>> Submenus will reduce the number of items even if there is only two 
>> subitems and I believe that this will be helpful for the reasons I have 
>> tried to outline above.
>>     
>
> Submenus don't reduce the number of items.  They just make some of them
> invisible, thus _increasing_ search effort.  Activating a menu item when
> it is hidden within a sub-menu is much slower than when it is directly
> there.
>   
You are right. It has disadvantages that some items are invisible but it 
also has advantages. However I do not believe that accessing an item 
fast is of much importance in the help menus. Is it not more important 
to easily get an overview of what is there?

I think submenus can help very much for that. But they can also damage 
the overview if they are not logical (from the users point of view, not 
the developers of course).

> The way to reduce the number of items is to reduce the number of items.
> If 17 is too many (which I can quite well believe), then categorise them
> into "must have", "should have" and "nice to have", and get rid of all of
> the last lot.  :-)
>   
I did not find anything that was not useful in the help menu and I 
thought that the existence of the items had been discussed before.

Re: C-h K and C-h F in the Help menu

[Richard Stallman]

    > Maybe you are right, but is it not documentation you are searching for 
    > in "Find Emacs Packages"?

    No, it searches the keywords in the comments of each package.

Also, what it finds is not documentation.  What it finds is
packages.

Re: C-h K and C-h F in the Help menu

[Luc Teirlinck]

Eli Zaretskii wrote:

   Also, what it finds is not documentation.  What it finds is
   packages.

~C-h p' eventually leads to the commentary section of the packages'
source file, which is supposed to be documentation of the package.
For many features, this is the only documentation they have.  So `C-h p'
is an essential complement to the Emacs manual, which has not enough
room to document all features.

Sincerely,

Luc.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> Date: Sun, 21 May 2006 21:04:11 +0000 (GMT)
> From: Alan Mackenzie <acm@muc.de>
> cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> 
> The way to reduce the number of items is to reduce the number of items.
> If 17 is too many (which I can quite well believe), then categorise them
> into "must have", "should have" and "nice to have", and get rid of all of
> the last lot.  :-)

I think they all should be left in the menu.  Some of them have
political, rather than technical, value, but the GNU project has a
clear political agenda.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> Date: Sun, 21 May 2006 21:56:21 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: eliz@gnu.org, lennart.borgman.073@student.lu.se, emacs-devel@gnu.org
> 
> ~C-h p' eventually leads to the commentary section of the packages'
> source file, which is supposed to be documentation of the package.
> For many features, this is the only documentation they have.  So `C-h p'
> is an essential complement to the Emacs manual, which has not enough
> room to document all features.

Yes, and that's why "C-h p" is in the Help menu.

The question was not whether it belongs to the general category of
documentation-related features (it does), the question was whether it
should be under "Search Documentation" submenu.  The other items in
that submenu are very different from "C-h p", mainly in what they
search and what they find.

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

Richard Stallman wrote:
>     > Maybe you are right, but is it not documentation you are searching for 
>     > in "Find Emacs Packages"?
>
>     No, it searches the keywords in the comments of each package.
>
> Also, what it finds is not documentation.  What it finds is
> packages.
>   
To me the end results seems to be documentation about the package.

Re: C-h K and C-h F in the Help menu

[Richard Stallman]

    You are right. It has disadvantages that some items are invisible but it 
    also has advantages. However I do not believe that accessing an item 
    fast is of much importance in the help menus. Is it not more important 
    to easily get an overview of what is there?

I think that is a good point.  In Emacs, generally, the menus are not
intended for speed.  If you want speed, you use the keyboard.  The
menus are there to help beginners get an idea of what they can do.

RE: C-h K and C-h F in the Help menu

[Drew Adams]

        However I do not believe that accessing an item
        fast is of much importance in the help menus. Is it not
        more important to easily get an overview of what is there?

    I think that is a good point.  In Emacs, generally, the menus are not
    intended for speed.  If you want speed, you use the keyboard.  The
    menus are there to help beginners get an idea of what they can do.

Jumping in...

Yes, a very good point, Lennart.

I would add that menus can provide another advantage: They provide a certain
structuring, categorizing, or grouping of commands - not the only useful
organization, but often quite useful.

Menu organization can help you find a command. If you are looking for some
printing option or command, you can look in a Print menu. If you are looking
for help, look in the Help menu, and so on.

Of course, `apropos' offers similar functionality, but the grouping is
different - `apropos' works by command name (or keywords in the doc string).
Menu organization need pay no attention to command name, and it can provide
multiple levels of grouping. Consider all of the commands grouped under the
Help menu: many do not have "help" in their names or doc strings. Look at
the commands under Help > More Manuals: how many have "manual" in their
names? The point is not that menus are more useful than `apropos'; it is
that both are useful in different ways for finding a command.

Menu structure provides the advantages of a Yahoo or Google directory
structure, as opposed to search, which is basically what `apropos' provides.
Sometimes you prefer to just google-search, and sometimes it can be more
efficient to navigate the Google directory structure. And, of course, the
best is to be able to combine the two (as you can in Google, for instance):
navigate the directory and then search only a subtree. Emacs menu structure
is not as wide or deep as the Google directory, but the principle and the
advantages are the same.

Another consideration is learning. Because a menu structure is ~fixed,
repeated use of the menu to access commands helps you learn the menu
organization: which commands are associated with which other commands in the
same part of the tree. This forms a useful conceptual model for finding new,
related info: you know what the tree looks like, so you have an idea where
to look.

For this and other reasons mentioned above, it is important that the menu be
well organized. Although we sometimes have food-fight menu battles here, I'm
not sure that everyone considers the menu structure to be all that important
(e.g. for non-newbies too), precisely because there is sometimes the
background idea that only wimps and newbies will use the menu.

Taking advantage of menu organization is all the easier if menu items can be
accessed using completion (from the keyboard), and especially if one can
match a pattern (prefix or regexp) against any part(s) of the menu item name
and path. My library icicles-menu.el (somewhat similar to tmm) offers this,
for instance. I mention this functionality as a possibility for future
consideration (e.g. for enhancement of tmm). With it, I would argue that
using menus will not be only for wimps and newbies.

Here are some arguments and description, with an example:
http://www.emacswiki.org/cgi-bin/wiki/IciclesMenu.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: acm@muc.de, eliz@gnu.org, emacs-devel@gnu.org
> Date: Mon, 22 May 2006 11:12:06 -0400
> 
>     You are right. It has disadvantages that some items are invisible but it 
>     also has advantages. However I do not believe that accessing an item 
>     fast is of much importance in the help menus. Is it not more important 
>     to easily get an overview of what is there?
> 
> I think that is a good point.  In Emacs, generally, the menus are not
> intended for speed.  If you want speed, you use the keyboard.  The
> menus are there to help beginners get an idea of what they can do.

Speed is not the main consideration here; the ease of finding the menu
item you looking for is.  Disseminating the menu items between many
submenus will make that much harder.

Other applications have menus of similar length, so I think we are in
good company and shouldn't bother.

Re: C-h K and C-h F in the Help menu

[Richard Stallman]

       Also, what it finds is not documentation.  What it finds is
       packages.

    ~C-h p' eventually leads to the commentary section of the packages'
    source file, which is supposed to be documentation of the package.

Yes, but what you are seaching for is not documentation, it is packages.

Re: C-h K and C-h F in the Help menu

[Lennart Borgman]

Drew Adams wrote:
> Another consideration is learning. Because a menu structure is ~fixed,
> repeated use of the menu to access commands helps you learn the menu
> organization: which commands are associated with which other commands in the
> same part of the tree. This forms a useful conceptual model for finding new,
> related info: you know what the tree looks like, so you have an idea where
> to look.
>   
A very important point in my opinion. Our visual memory is very 
important and I believe the organisation in menus help us store the 
information in places close to our visual memory. (Just a guess at the 
moment, can't remember anything that in a more hard way support that 
right now.)

Re: C-h K and C-h F in the Help menu

[Richard Stallman]

    Speed is not the main consideration here; the ease of finding the menu
    item you looking for is.  Disseminating the menu items between many
    submenus will make that much harder.

That depends on the details.  If the submenu corresponds to a clear
category, and has a good name, it could make finding things easier.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: lennart.borgman.073@student.lu.se, acm@muc.de, emacs-devel@gnu.org
> Date: Mon, 22 May 2006 20:42:10 -0400
> 
> If the submenu corresponds to a clear
> category, and has a good name, it could make finding things easier.

I don't think we can hope for that in practice: this is Help menu;
people who need it most by definition don't have clear ideas about
what belongs to which category.

Re: C-h K and C-h F in the Help menu

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> CC: emacs-devel@gnu.org
> Date: Sun, 21 May 2006 13:08:27 -0400
> 
>     "Find Key in Manual" and "Find Command in Manual" are in the "More
>     Manuals" submenu of the "Help" menu.  I think they should either in
>     "Search Documentation" or in "Describe", because these two submenus
>     are about Emacs, while "More Manuals" is about manuals of other
>     packages.
> 
> "Search Documentation" seems like the right place.

I moved them to "Search Documentation".