tooltips for minor modes

tooltips for minor modes

[Dan Nicolaescu]

It would be nice if the mode-line :lighter for minor modes would have a
tooltip with a brief description of what the minor mode is.
Things like "Fly", "hs", "Fill" are not very explicit, providing a
tooltip would be very helpful for some users.

Not sure what is the best way to provide a generic mechanism for doing this...

Re: tooltips for minor modes

[David Kastrup]

Dan Nicolaescu <dann@ics.uci.edu> writes:

> It would be nice if the mode-line :lighter for minor modes would have a
> tooltip with a brief description of what the minor mode is.
> Things like "Fly", "hs", "Fill" are not very explicit, providing a
> tooltip would be very helpful for some users.
>
> Not sure what is the best way to provide a generic mechanism for doing this...

Well a tooltip "minor mode" "minor mode help" is not really useful.
Substituting the actual name of the mode in the tooltip would seem like
an improvement.

-- 
David Kastrup

Re: tooltips for minor modes

[Dan Nicolaescu]

David Kastrup <dak@gnu.org> writes:

  > Dan Nicolaescu <dann@ics.uci.edu> writes:
  > 
  > > It would be nice if the mode-line :lighter for minor modes would have a
  > > tooltip with a brief description of what the minor mode is.
  > > Things like "Fly", "hs", "Fill" are not very explicit, providing a
  > > tooltip would be very helpful for some users.
  > >
  > > Not sure what is the best way to provide a generic mechanism for doing this...
  > 
  > Well a tooltip "minor mode" "minor mode help" is not really useful.
  > Substituting the actual name of the mode in the tooltip would seem like
  > an improvement.

Agreed, but it's still not even close to being good enough.
Something like "Minor mode: glasses-mode" gives close to zero useful
information if you are not familiar with the mode...

Re: tooltips for minor modes

[Richard Stallman]

    It would be nice if the mode-line :lighter for minor modes would have a
    tooltip with a brief description of what the minor mode is.

I think it is a good idea.  We could perhaps establish a convention
that a certain part of the doc string of the minor mode function is
used for this.  Or, if that would require changing too many doc
strings, we could have some other way to specify the string for this.

RE: tooltips for minor modes

[Drew Adams]

>     It would be nice if the mode-line :lighter for minor 
>     modes would have a
>     tooltip with a brief description of what the minor mode is.
> 
> I think it is a good idea.  We could perhaps establish a convention
> that a certain part of the doc string of the minor mode function is
> used for this.  Or, if that would require changing too many doc
> strings, we could have some other way to specify the string for this.

Perhaps add a :help keyword to `define-minor-mode' etc.?

Note that if Dan's other suggestion, about having at least a rudimentary
menu that supplies a Help item, that would lessen the utility of or need for
a tooltip. But I too think a tooltip is also a good idea - I support both of
his suggestions.

Re: tooltips for minor modes

[Dan Nicolaescu]

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

  > >     It would be nice if the mode-line :lighter for minor 
  > >     modes would have a
  > >     tooltip with a brief description of what the minor mode is.
  > > 
  > > I think it is a good idea.  We could perhaps establish a convention
  > > that a certain part of the doc string of the minor mode function is
  > > used for this.  Or, if that would require changing too many doc
  > > strings, we could have some other way to specify the string for this.

One possibility would be to use the first line of the doc-string. But a
quick "grep --after=1 define-minor-mode" shows that for quite a lot of
minor modes the first line of the doc-string gives not useful
information:

scroll-all.el:106:(define-minor-mode scroll-all-mode
scroll-all.el-107-  "Toggle Scroll-All minor mode.

So doing either the above or the proposal below requires some editing.

  > Perhaps add a :help keyword to `define-minor-mode' etc.?

Sounds good, and consistent with other uses for :help. Where would that
:help property be stored?

Drew, given that you are you touched this minor-mode stuff most
recently, do you want to implement one of these ?

RE: tooltips for minor modes

[Drew Adams]

>   > >     It would be nice if the mode-line :lighter for minor 
>   > >     modes would have a
>   > >     tooltip with a brief description of what the minor mode is.
>   > > 
>   > > I think it is a good idea.  We could perhaps establish 
> a convention
>   > > that a certain part of the doc string of the minor mode 
> function is
>   > > used for this.  Or, if that would require changing too many doc
>   > > strings, we could have some other way to specify the 
> string for this.
> 
> One possibility would be to use the first line of the 
> doc-string. But a
> quick "grep --after=1 define-minor-mode" shows that for quite a lot of
> minor modes the first line of the doc-string gives not useful
> information:
> 
> scroll-all.el:106:(define-minor-mode scroll-all-mode
> scroll-all.el-107-  "Toggle Scroll-All minor mode.
> 
> So doing either the above or the proposal below requires some editing.
> 
>   > Perhaps add a :help keyword to `define-minor-mode' etc.?
> 
> Sounds good, and consistent with other uses for :help. Where 
> would that :help property be stored?
> 
> Drew, given that you are you touched this minor-mode stuff most
> recently, do you want to implement one of these ?

I don't feel up to it, and I don't have the time right now to look into it.
Someone else likely has an idea how to do it. I certainly don't want to
touch the `define-minor-mode' code, in any case - it's a precision Swiss
watch. ;-) Sorry.

Re: tooltips for minor modes

[Richard Stallman]

    One possibility would be to use the first line of the doc-string. But a
    quick "grep --after=1 define-minor-mode" shows that for quite a lot of
    minor modes the first line of the doc-string gives not useful
    information:

I am not surprised that the first line doesn't do it.
But we could make the second line do it.

We might want to establish the convention that the second line
of a minor mode's doc string starts with the start of a sentence that explains
briefly what the mode does.

Then the tooltip  could show the sentence which starts at that point.

RE: tooltips for minor modes

[Drew Adams]

>     One possibility would be to use the first line of the 
>     doc-string. But a quick "grep --after=1 define-minor-mode"
>     shows that for quite a lot of minor modes the first line
>     of the doc-string gives not useful information:
> 
> I am not surprised that the first line doesn't do it.
> But we could make the second line do it.
> 
> We might want to establish the convention that the second line
> of a minor mode's doc string starts with the start of a 
> sentence that explains
> briefly what the mode does.
> 
> Then the tooltip  could show the sentence which starts at that point.

That sounds a bit artificial to me. The doc string needs also to be readable
on its own.  I'm not sure it's good to press doc-string parts into doing
double duty.

I would opt for a :help keyword or just forget about the tooltip.

After all, now that we have a mouse-1 menu with a Help item that displays
the whole doc string, there is a little less need for a tooltip. 

Yes, a tooltip would still be good, so that simply hovering over the lighter
would give some info. But I'm not sure it's worth adding a new doc-string
convention and counting on people to follow it.

Re: tooltips for minor modes

[Stefan Monnier]

> That sounds a bit artificial to me. The doc string needs also to be readable
> on its own.  I'm not sure it's good to press doc-string parts into doing
> double duty.

> I would opt for a :help keyword or just forget about the tooltip.

Agreed.


        Stefan

Re: tooltips for minor modes

[Dan Nicolaescu]

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

  > > That sounds a bit artificial to me. The doc string needs also to be readable
  > > on its own.  I'm not sure it's good to press doc-string parts into doing
  > > double duty.
  > 
  > > I would opt for a :help keyword or just forget about the tooltip.
  > 
  > Agreed.

So the only question is where to store the :help info.

Re: tooltips for minor modes

[Richard Stallman]

    > We might want to establish the convention that the second line
    > of a minor mode's doc string starts with the start of a 
    > sentence that explains
    > briefly what the mode does.
    > 
    > Then the tooltip  could show the sentence which starts at that point.

    That sounds a bit artificial to me. The doc string needs also to be readable
    on its own.  I'm not sure it's good to press doc-string parts into doing
    double duty.

I expect that this will be perfectly readable -- give it a try
for a few minor modes and see.

But there should also be a :mode-feature keyword to override this when
necessary.