describe-mode's treatment of minor-modes is annoying

describe-mode's treatment of minor-modes is annoying

[Miles Bader]

Am I the only one who's annoyed by the way describe-mode now displays
minor modes?

It fills up the beginning of the buffer with notes about a zillion minor
modes, most of which I don't care about, and which almost always manage
to push the major mode description (which I usually _do_ care about)
entirely off the screen?

For instance, here's what it showed when I did `C-h m' in my
message-sending buffer:

   Summary of minor modes:
     Abbrev minor mode (indicator Abbrev):
     Auto Fill minor mode (indicator Fill):
     Auto-Compression minor mode (no indicator):
     Auto-Image-File minor mode (no indicator):
     Display-Time minor mode (no indicator):
     File-Name-Shadow minor mode (no indicator):
     Font-Lock minor mode (no indicator):
     Global-Font-Lock minor mode (no indicator):
     Line-Number minor mode (no indicator):
     Minibuffer-Electric-Default minor mode (no indicator):
     Mouse-Wheel minor mode (no indicator):
     Recentf minor mode (no indicator):
     Temp-Buffer-Resize minor mode (no indicator):
     Transient-Mark minor mode (no indicator):
     Unify-8859-On-Encoding minor mode (no indicator):
     Utf-Translate-Cjk minor mode (no indicator):

   (Full information about these minor modes
   follows the description of the major mode.)

   Message mode:
   ....

I think all that should be moved to _after_ the major mode description,
with a single-line hyper link at the beginning of the buffer that jumps
there.

E.g., make the layout something like:

   (Information on [minor modes] comes after the major mode description)

   Message mode:
   ....long major mode description....

   ^L
   Summary of minor modes in this buffer:
     [Abbrev minor mode] (indicator Abbrev):
     [Auto Fill minor mode] (indicator Fill):
     [Auto-Compression minor mode] (no indicator):
     ...

   ^L
   Abbrev minor mode (indicator Abbrev):
   Toggle abbrev mode.
   With argument ARG, turn abbrev mode on iff ARG is positive.
   ...

   ^L
   ...

where bracketed phrases [...] indicate hyperlinks.

Thanks,

-Miles
-- 
"Though they may have different meanings, the cries of 'Yeeeee-haw!' and
 'Allahu akbar!' are, in spirit, not actually all that different."

Re: describe-mode's treatment of minor-modes is annoying

[Juanma Barranquero]

On 04 May 2004 13:05:09 +0900
Miles Bader <miles@gnu.org> wrote:

> Am I the only one who's annoyed by the way describe-mode now displays
> minor modes?

No.

                                                                Juanma

Re: describe-mode's treatment of minor-modes is annoying

[Romain Francoise]

Miles Bader <miles@gnu.org> writes:

> I think all that should be moved to _after_ the major mode description,
> with a single-line hyper link at the beginning of the buffer that jumps
> there.

I second that; the new behavior is annoying as hell.

-- 
Romain Francoise <romain@orebokech.com> | But you don't care for me and
it's a miracle -- http://orebokech.com/ | I don't care now for anybody.

Re: describe-mode's treatment of minor-modes is annoying

[Stefan Monnier]

>> I think all that should be moved to _after_ the major mode description,
>> with a single-line hyper link at the beginning of the buffer that jumps
>> there.
> I second that; the new behavior is annoying as hell.

Well, I don't know about hell, but I agree in the sense that I find it
unhelpful.  Maybe we should not only move the minor mode summary to after
the major mode, but also split the minor mode summary into buffer-local
minor modes vs global minor modes.


        Stefan

Re: describe-mode's treatment of minor-modes is annoying

[Miles Bader]

On Tue, May 04, 2004 at 09:52:03AM -0400, Stefan Monnier wrote:
> >> I think all that should be moved to _after_ the major mode description,
> >> with a single-line hyper link at the beginning of the buffer that jumps
> >> there.
> > I second that; the new behavior is annoying as hell.
> 
> Well, I don't know about hell, but I agree in the sense that I find it
> unhelpful.  Maybe we should not only move the minor mode summary to after
> the major mode, but also split the minor mode summary into buffer-local
> minor modes vs global minor modes.

Yeah I agree about that too; if the minor modes are on their own page after
the major modes, I think it would suffice to just put the global modes after
the local modes, with a blank line or two in between them, just enough to
make the separation clear.

-Miles
-- 
Come now, if we were really planning to harm you, would we be waiting here, 
 beside the path, in the very darkest part of the forest?

Re: describe-mode's treatment of minor-modes is annoying

[Romain Francoise]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Maybe we should not only move the minor mode summary to after the
> major mode, but also split the minor mode summary into buffer-local
> minor modes vs global minor modes.

That sounds like a good idea indeed.

-- 
Romain Francoise <romain@orebokech.com> | But you don't care for me and
it's a miracle -- http://orebokech.com/ | I don't care now for anybody.

Re: describe-mode's treatment of minor-modes is annoying

[Richard Stallman]

    Am I the only one who's annoyed by the way describe-mode now displays
    minor modes?

    It fills up the beginning of the buffer with notes about a zillion minor
    modes, most of which I don't care about, and which almost always manage
    to push the major mode description (which I usually _do_ care about)
    entirely off the screen?

I think it used to put the minor modes after the major mode.  The
problem was, people did not even know the minor mode info was there.

    E.g., make the layout something like:

       (Information on [minor modes] comes after the major mode description)

This might be ok.  It should also suggest typing C-x ] C-x ] to get to
the minor mode information.  That should always work, since the major
mode doc string should never contain a page break.

RE: describe-mode's treatment of minor-modes is annoying

[Drew Adams]

> I think it used to put the minor modes after the major mode.  The
> problem was, people did not even know the minor mode info was there.

In Emacs 20, the first two lines said this:

 The major mode is described first.
 For minor modes, see following pages.

So users knew the minor mode info was there, and they saw the major mode
info first.

>>      E.g., make the layout something like:
>>        (Information on [minor modes] comes after the major mode
description)

> This might be ok.  It should also suggest typing C-x ] C-x ] to get to
> the minor mode information.  That should always work, since the major
> mode doc string should never contain a page break.

C-x ] and C-x [ are not obvious. And the pages are all displayed together
(at least in Emacs 20): ^L is all that appears as page separator, so the
buffer is quite busy.

Instead of using separate pages in the same buffer, why not use separate
incarnations of the *Help* buffer. `C-h m' would display just a one-liner
about each mode in *Help*, with a link for each mode (part or all of the
one-liner) to its detailed description:

 Major mode
  SQL[oracle] mode: Major mode to edit SQL.

 Minor modes
  Font-Lock minor mode (no indicator): Toggle Font Lock mode.
  ...

If there are no minor modes, just show the major-mode doc directly.

The links would display the individual mode descriptions in *Help*, with a
back button. Less busy. Uses links instead of C-x ] to navigate.

Drawback: cannot see (or print) everything at once. Would that be worth
another link/button that displays everything at once (separate pages)?

 - Drew

Re: describe-mode's treatment of minor-modes is annoying

[Stefan Monnier]

> C-x ] and C-x [ are not obvious. And the pages are all displayed together
> (at least in Emacs 20): ^L is all that appears as page separator, so the
> buffer is quite busy.

Place an overlay with an `invisible' property on every page, and turn on
reveal-mode.


        Stefan

Re: describe-mode's treatment of minor-modes is annoying

[Miles Bader]

On Tue, May 04, 2004 at 04:08:14PM -0400, Richard Stallman wrote:
>     E.g., make the layout something like:
> 
>        (Information on [minor modes] comes after the major mode description)
> 
> This might be ok.  It should also suggest typing C-x ] C-x ] to get to
> the minor mode information.  That should always work, since the major
> mode doc string should never contain a page break.

You don't think the hyperlink is enough?

-Miles
-- 
Somebody has to do something, and it's just incredibly pathetic that it
has to be us.  -- Jerry Garcia

Re: describe-mode's treatment of minor-modes is annoying

[Miles Bader]

On Tue, May 04, 2004 at 01:58:35PM -0700, Drew Adams wrote:
> Instead of using separate pages in the same buffer, why not use separate
> incarnations of the *Help* buffer. `C-h m' would display just a one-liner
> about each mode in *Help*, with a link for each mode (part or all of the
> one-liner) to its detailed description:
> 
>  Major mode
>   SQL[oracle] mode: Major mode to edit SQL.
> 
>  Minor modes
>   Font-Lock minor mode (no indicator): Toggle Font Lock mode.
>   ...
> 
> If there are no minor modes, just show the major-mode doc directly.

I think that the major-mode doc should _always_ be displayed.  In most cases
I think that's what people are interested in, and _always_ having to follow a
hyperlink to get at it would just be annoying (and I think in practice it
would be _always_, too, as there's usually some random minor mode or another
turned on).

However, maybe it would be a good idea to separate the minor mode
descriptions as you say, and just include a hyper link that described them
(using the format I gave in my earlier message, with a single line at the
beginning of the major-mode description).  There could be a [back] button at
the beginning of the minor-mode help to allow easily jumping back and forth.

That way it wouldn't waste any time formatting all that minor mode stuff in
the common case, and a user could even invoke `describe-minor-modes'
directly if that's what he was really interested in.

Hmmm, I like it...

-Miles
-- 
`Suppose Korea goes to the World Cup final against Japan and wins,' Moon said.
`All the past could be forgiven.'   [NYT]

Re: describe-mode's treatment of minor-modes is annoying

[Richard Stallman]

     The major mode is described first.
     For minor modes, see following pages.

    So users knew the minor mode info was there, and they saw the major mode
    info first.

If you've checked this, you're surely correct.  But I remember that the
minor mode info was not very visible, and not easy to use.  That was
the reason for the change.

Re: describe-mode's treatment of minor-modes is annoying

[Richard Stallman]

    > This might be ok.  It should also suggest typing C-x ] C-x ] to get to
    > the minor mode information.  That should always work, since the major
    > mode doc string should never contain a page break.

    You don't think the hyperlink is enough?

Moving to that link and using it is a lot more characters
than C-x ] C-x ].

RE: describe-mode's treatment of minor-modes is annoying

[Drew Adams]

Yes, I checked it in vanilla (GNU) Emacs 20.7 (emacs -q).

       The major mode is described first.
       For minor modes, see following pages.

    So users knew the minor mode info was there, and they saw the major mode
    info first.

> If you've checked this, you're surely correct.  But I remember that the
> minor mode info was not very visible, and not easy to use.  That was
> the reason for the change.

I too think the minor (and major!) mode info was not very visible - because
everything was visible together, separated only by ^L. And not very easy to
use, because users needed to know about C-].

Even a horizontal bar (a la <HR> in HTML) would be a better separator
visually than ^L.

 - Drew

Re: describe-mode's treatment of minor-modes is annoying

[Miles Bader]

On Wed, May 05, 2004 at 04:21:08PM -0400, Richard Stallman wrote:
>     > This might be ok.  It should also suggest typing C-x ] C-x ] to get to
>     > the minor mode information.  That should always work, since the major
>     > mode doc string should never contain a page break.
> 
>     You don't think the hyperlink is enough?
> 
> Moving to that link and using it is a lot more characters
> than C-x ] C-x ].

It's actually fewer characters:

    TAB RET

[I think the `TAB reflex' is one many people already have too, as it works in
(mainstream) web-browsers, as well as for most uses of hyperlinks in emacs.]

-Miles
-- 
Come now, if we were really planning to harm you, would we be waiting here, 
 beside the path, in the very darkest part of the forest?

Re: describe-mode's treatment of minor-modes is annoying

[Juri Linkov]

"Drew Adams" <drew.adams@oracle.com> writes:
> I too think the minor (and major!) mode info was not very visible - because
> everything was visible together, separated only by ^L. And not very easy to
> use, because users needed to know about C-].
>
> Even a horizontal bar (a la <HR> in HTML) would be a better separator
> visually than ^L.

For better visual separation, a buffer-local variable `buffer-display-table'
could be modified in the Help buffer as below:

      (aset buffer-display-table ?\f
            (vconcat (make-vector (window-width) ?-) "^L"))

It displays a horizontal bar, but still allows to move between pages
by C-x ].

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

Re: describe-mode's treatment of minor-modes is annoying

[Richard Stallman]

    It's actually fewer characters:

	TAB RET

I'm surprised, I had no idea that TAB would move there.

Re: describe-mode's treatment of minor-modes is annoying

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
> 	TAB RET
> 
> I'm surprised, I had no idea that TAB would move there.

When there are buttons/hyperlinks in a read-only buffer, there's a good
chance that TAB will jump to the next one (and Shift-TAB jump
backwards).  It's very handy.

-Miles
-- 
Love is a snowmobile racing across the tundra.  Suddenly it flips over,
pinning you underneath.  At night the ice weasels come.  --Nietzsche

Re: describe-mode's treatment of minor-modes is annoying

[Peter Whaite]

Miles Bader <miles@gnu.org> wrote:

> When there are buttons/hyperlinks in a read-only buffer, there's a good
> chance that TAB will jump to the next one (and Shift-TAB jump
> backwards).  It's very handy.

I find the mode help far too busy.  The minor modes coming first are a
distraction. The ^L look messy and dont visually separate the different
sections well enough.  Having an index of buttons sounds good. 

Has it been suggested that the button action could show/hide inline the
description of its corresponding mode rather than displaying it in
another buffer?  Thats what mh-e does for mime parts (gnus too?), and I
find it quite usable.

-- 
Peter Whaite (http://whaite.ca)

Re: describe-mode's treatment of minor-modes is annoying

[Thien-Thi Nguyen]

Peter Whaite <emacs@whaite.ca> writes:

   inline the description of its corresponding mode rather than
   displaying it in another buffer?

reading this reminds me of similar presentation style, using
outline, for buffer-local variables, as implemented in:

 http://www.glug.org/people/ttn/software/ttn-pers-elisp/dist/
        lisp/low-stress/print-buffer-local-variables.el

it seems to me for a flat set of items numbering less than 100
(such as buffer-local variables, or contemporaneous major/minor
modes), outline as top-level presentation format is ideal.
particular outline style as well as what to do w/ each item --
hiding, hyperlinking, further decoration -- can be considered as
separate questions.

thi