tooltip-mode docstring

tooltip-mode docstring

[Luc Teirlinck]

The docstring of tooltip-mode does not seem very helpful.  It
misleadingly suggests that if you disable it, you do not get to see
any help-text on mouse-over, whereas tooltip-mode only determines
_where_ you see that thext rather than _whether_ you see it.

Unless there are objections, I plan to install the following doc fix:

===File ~/tooltip-diff======================================
*** tooltip.el	20 Dec 2005 15:59:43 -0600	1.72
--- tooltip.el	09 Jan 2006 21:14:26 -0600	
***************
*** 48,54 ****
  
  (define-minor-mode tooltip-mode
    "Toggle Tooltip display.
! With ARG, turn tooltip mode on if and only if ARG is positive."
    :global t
    :init-value (not (or noninteractive
  		       emacs-basic-display
--- 48,57 ----
  
  (define-minor-mode tooltip-mode
    "Toggle Tooltip display.
! With ARG, turn tooltip mode on if and only if ARG is positive.
! When this minor mode is enabled, Emacs displays help text
! in a pop-up tooltip on mouse-over.  When it is disabled,
! Emacs displays the help text in the echo area instead."
    :global t
    :init-value (not (or noninteractive
  		       emacs-basic-display
============================================================

Re: tooltip-mode docstring

[Luc Teirlinck]

Nick Roberts wrote:

   A tooltip is, by definition, a window that pops up on mouse-over (it's
   called balloon help in the manual).

This assumes that the reader knows this.

What about just replacing "tooltip" in my original text with "window"
to avoid redundancy:

===File ~/tooltip-diff======================================
*** tooltip.el	20 Dec 2005 15:59:43 -0600	1.72
--- tooltip.el	09 Jan 2006 21:14:26 -0600	
***************
*** 48,54 ****
  
  (define-minor-mode tooltip-mode
    "Toggle Tooltip display.
! With ARG, turn tooltip mode on if and only if ARG is positive."
    :global t
    :init-value (not (or noninteractive
  		       emacs-basic-display
--- 48,57 ----
  
  (define-minor-mode tooltip-mode
    "Toggle Tooltip display.
! With ARG, turn tooltip mode on if and only if ARG is positive.
! When this minor mode is enabled, Emacs displays help text
! in a pop-up window on mouse-over.  When it is disabled,
! Emacs displays the help text in the echo area instead."
    :global t
    :init-value (not (or noninteractive
  		       emacs-basic-display
============================================================

Re: tooltip-mode docstring

[Nick Roberts]

 >    A tooltip is, by definition, a window that pops up on mouse-over (it's
 >    called balloon help in the manual).
 > 
 > This assumes that the reader knows this.

I think it's reasonable to start with certain assumptions.  It's a doc string,
not a primer (or legal document).  tool-bar-mode doesn't explain what a
tool bar is, menu-bar-mode what a menu-bar is...

Nick

Re: tooltip-mode docstring

[Luc Teirlinck]

Nick Roberts wrote:

   I think it's reasonable to start with certain assumptions.  It's a
   doc string, not a primer (or legal document).  tool-bar-mode
   doesn't explain what a tool bar is, menu-bar-mode what a menu-bar is...

"Tooltip" is sometimes misunderstood to mean the help message instead
of the window showing that message.  The purpose of my proposed doc
fix is to prevent that confusion.

Sincerely,

Luc.

Re: tooltip-mode docstring

[Richard M. Stallman]

    I think it's reasonable to start with certain assumptions.  It's a doc string,
    not a primer (or legal document).  tool-bar-mode doesn't explain what a
    tool bar is, menu-bar-mode what a menu-bar is...

Tooltips are more obscure than menu bars.  I think it won't hurt to
make that doc string say what a tooltip is.