Re: Reducing mouse-dependency In Emacs.

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

The current version of `print-local-help' only works with `help-echo'
properties that are strings.  The fact that it does not work with
help-echo's that evaluate to strings was just an omission on my part
and is trivial to fix (I forgot some eval's).  I knew I still had to
take care of the rarer case of help-echo's that are functions.  I also
want `short-help' to have the same legal values as `help-echo',
including functions.

To take care of functional values, I need not only the value of the
property but also need to know whether it was found in an overlay (and
if so which overlay) or as a text property.
`get_char_property_and_overlay' provides that information, but in a
form that I do not know how to use from Lisp.  (I am not very familiar
at all with the Emacs C code.)  Assuming there is no better way, would
it be OK to define the following new primitive (the documentation
string would have to get a much shorter first line and maybe the name
is not right, but I could worry about such things later):

DEFUN ("find-char-property", Ffind_char_property, Sfind_char_property, 2, 3, 0,
       doc: /* Return a cons whose car is the value of POSITION's
property PROP, in OBJECT and whose cdr is the overlay in which the
property was found, or nil if it was found as a text property.  OBJECT
is optional and defaults to the current buffer.  If POSITION is at the
end of OBJECT, the value is nil.  If OBJECT is a buffer, then overlay
properties are considered as well as text properties.  If OBJECT is a
window, then that window's buffer is used, but window-specific
overlays are considered only if they are associated with OBJECT.  */)
     (position, prop, object)
     Lisp_Object position, object;
     register Lisp_Object prop;
{
  Lisp_Object *overlay = (Lisp_Object *) alloca (sizeof (Lisp_Object));
  Lisp_Object val=
    get_char_property_and_overlay (position, prop, object, overlay);
  return Fcons(val, *overlay);
}

I also put in a "defsubr (&Sadd_text_properties);" and a "EXFUN
(Ffind_char_property, 3);" in intervals.h.

(All of this in my own Emacs, not in the CVS, of course.)

The new primitive would take the same arguments as `get-char-property'
and return a cons with car the return value of `get-char-property' and
as cdr the overlay in which it was found, or nil if none.

I am really unfamiliar with the Emacs source code, but my Emacs
version still bootstraps, my Emacs has not crashed yet after some use
and everything seems to return the correct values, even in some
reasonably complex situations.

Is here a better way to access the information I need from Lisp or is
the above OK?  I know how to access the information I need completely
from Lisp, without any new primitives, but in a somewhat inelegant
way.

Sincerely,

Luc.

Re: Reducing mouse-dependency In Emacs.

[Miles Bader]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> To take care of functional values, I need not only the value of the
> property but also need to know whether it was found in an overlay (and
> if so which overlay) or as a text property.

How come?

> DEFUN ("find-char-property", Ffind_char_property, Sfind_char_property, 2, 3, 0,

I think (as you said) the name is wrong -- `find' implies that it does
some sort of searching, when really it's just the same as
get-char-property with an additional return value -- why not just use
the same name as the C code:  get-char-property-and-overlay?

Also, you don't need to use alloca, you can just use a stack variable:


DEFUN ("get-char-property-and-overlay", Fget_char_property_and_overlay,
       Sget_char_property_and_overlay, 2, 3, 0,
       doc: /* Return a cons whose car is the value of POSITION's
property PROP, in OBJECT and whose cdr is the overlay in which the
property was found, or nil if it was found as a text property.  OBJECT
is optional and defaults to the current buffer.  If POSITION is at the
end of OBJECT, the value is nil.  If OBJECT is a buffer, then overlay
properties are considered as well as text properties.  If OBJECT is a
window, then that window's buffer is used, but window-specific
overlays are considered only if they are associated with OBJECT.  */)
     (position, prop, object)
     Lisp_Object position, object;
     register Lisp_Object prop;
{
  Lisp_Object overlay;
  Lisp_Object val
    = get_char_property_and_overlay (position, prop, object, &overlay);
  return Fcons (val, overlay);
}
 

-Miles
-- 
We have met the enemy, and he is us.  -- Pogo

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Miles Bader wrote:

   Luc Teirlinck <teirllm@dms.auburn.edu> writes:
   > To take care of functional values, I need not only the value of the
   > property but also need to know whether it was found in an overlay (and
   > if so which overlay) or as a text property.

   How come?

Because:

     If the value of the `help-echo' property is a function, that
     function is called with three arguments, WINDOW, OBJECT and
     POSITION and should return a help string or NIL for none.  The
     first argument, WINDOW is the window in which the help was found.
     The second, OBJECT, is the buffer, overlay or string which had
     the
     `help-echo' property.  The POSITION argument is as follows:

        * If OBJECT is a buffer, POS is the position in the buffer
          where the `help-echo' text property was found.

        * If OBJECT is an overlay, that overlay has a `help-echo'
          property, and POS is the position in the overlay's buffer
          under the mouse.

        * If OBJECT is a string (an overlay string or a string
          displayed
          with the `display' property), POS is the position in that
          string under the mouse.

I do not believe that in my case I need to worry about the string case
(unlike the mouse, point can not get "inside" a string given as a
value for the display property), but I do need to worry about the
buffer and overlay cases.  I need to know which arguments to pass to
the function.  In my case, WINDOW will be (selected-window) and
POSITION will be (point), but I need to know which value to pass for
OBJECT.

Sincerely,

Luc.

Re: Reducing mouse-dependency In Emacs.

[Nick Roberts]

Luc Teirlinck writes:
 > 
 > Miles Bader wrote:
 > 
 >    Luc Teirlinck <teirllm@dms.auburn.edu> writes:
 >    > To take care of functional values, I need not only the value of the
 >    > property but also need to know whether it was found in an overlay (and
 >    > if so which overlay) or as a text property.
 > 
 >    How come?
 > 
 > Because:
 > 
 >      If the value of the `help-echo' property is a function, that
 >      function is called with three arguments, WINDOW, OBJECT and
 >      POSITION and should return a help string or NIL for none.  The
 >      first argument, WINDOW is the window in which the help was found.
 >      The second, OBJECT, is the buffer, overlay or string which had
 >      the
 >      `help-echo' property.  The POSITION argument is as follows...

I must admit I've lost the plot but it seems to have got far too complicated.

I agree with Miles, I don't think that you need to know all these
things.  I think that Emacs *provides* the appropriate arguments depending on
the context, which can then used in the function that evaluates to a string.

I'm always in favour of re-use to keep things simple and, IMO, `customize'
works well with and without the mouse. Here, a tooltip is displayed if the
mouse is placed over a widget. In the mouseless scenario, the help is
displayed in the echo area. However, this doesn't happen when point is over a
widget but when the user types <tab> (widget-forward) or <S-tab>
(widget-backward). This is less distracting and fits well with earlier
comments about emacspeak. Could you not do something similar with
next-help-echo-region and previous-help-echo-region?


Nick

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Nick Roberts wrote:

   I agree with Miles, I don't think that you need to know all these
   things.  I think that Emacs *provides* the appropriate arguments
   depending on the context, which can then used in the function that
   evaluates to a string.

If you, or anybody else, can point me to an existing Lisp function or
any other way that Emacs already "provides" these arguments in Lisp
and without mouse-over, I obviously will use it (and then everything I
write below can just be ignored).  I could not find any, but I did not
read through the entire Emacs Lisp code.

I do not even really believe that Miles was necessarily arguing
against my proposed new primitive (he can tell), I believe he was just
asking me for information.

   IMO, `customize' works well with and without the mouse. Here, a
   tooltip is displayed if the mouse is placed over a widget. In the
   mouseless scenario, the help is displayed in the echo
   area.

Did you check in detail how Custom manages to print the help-echo in
the echo area?  If I understood correctly (it does not at all seem
that "simple" to me), it apparently uses two extra text properties it
manages itself, `button' and `field', depending on the situation, to
store and recover the information.

I propose to use one extremely simple and short C function and one
very simple and short Lisp function, compared to the entire machinery
used by Custom, and it would work in a way more general situation.  In
my situation, I can not do what Custom does, because I do not have the
information stored in `button' and `field' properties.

Sincerely,

Luc.

Re: Reducing mouse-dependency In Emacs.

[Miles Bader]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> I do not even really believe that Miles was necessarily arguing
> against my proposed new primitive (he can tell), I believe he was just
> asking me for information.

Yes

[I suppose it's useful to have this function exported to lisp in any
case, though I think the name's a bit odd (I actually named the original
C function -- I just couldn't think of anything better).]

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

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Nick Roberts wrote:

   In the mouseless scenario, the help is displayed in the echo
   area. However, this doesn't happen when point is over a widget but
   when the user types <tab> (widget-forward) or <S-tab>
   (widget-backward). This is less distracting and fits well with
   earlier comments about emacspeak. Could you not do something
   similar with next-help-echo-region and previous-help-echo-region?

Nobody is going to be distracted without asking to be.  The
information would only show up either on explicit demand or through a
customizable option, where even some extra flexibility would be
provided, and that would not be enabled by default.

I believe that I will indeed make `next-help-echo-region' and
`previous-help-echo-region' automatically call `print-local-help',
since the user probably wants it, if he is calling those functions.  I
do not really believe this is a _substitute_ for call on demand,
however.  Moreover, some people may want the information shown
automatically, especially in the case of `keymap' and `local-map'
properties, which are both not that frequent and important to know
about.  I believe I am going to provide an option to show automatic
help only if one of those two properties are present, as well as
options to show all help automatically or no help automatically (the
default).

Sincerely,

Luc.

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Miles Bader wrote:

   I think (as you said) the name is wrong -- `find' implies that it does
   some sort of searching, when really it's just the same as
   get-char-property with an additional return value -- why not just use
   the same name as the C code:  get-char-property-and-overlay?

   Also, you don't need to use alloca, you can just use a stack variable:

I agree that the changes you suggest are improvements.  Thanks.

Sincerely,

Luc.

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

The following (still strictly experimental) version of automatic
help-echo display eliminates the main obnoxiousness of the original
version.  In the original version, you could be asked a question in
the minibuffer, have to think about the answer, and suddenly the
question disappears for some useless help-echo.  The following version
prevents that.  It will only display the help-echo if the minibuffer
is empty or contains "Quit".  So, if you have "Mark set" in the echo
area, you have to do C-g or otherwise clear the echo area (say by
moving point) to get the help-echo.  Seems better than to miss an
important message, if not paying attention, by having it overridden by
help-echo.  Anyway, I wound up finding the original version unbearable
in actual use.  I found the one below much better.

===File ~/newhelp-timer.el==================================
(defun print-local-help (&optional timer)
  "Display help related text or overlay properties.
This displays a short help message in the echo area, namely the
value of the `short-help' text or overlay property at point.  If
there is no `short-help' property at point, but there is a
`help-echo' property whose value is a string, then that is
printed instead.

The timer argument is meant for use in `run-with-idle-timer' and
prevents display of a message in case there is no help."
  (interactive)
  (let ((short (get-char-property (point) 'short-help))
	(echo (get-char-property (point) 'help-echo)))
    (cond (short (message "%s" short))
	  ((stringp echo) (message "%s" echo))
	  ((not timer) (message "No local help at point")))))

(defvar delay 1)

(defvar local-help-timer nil)

(unless local-help-timer
  (setq local-help-timer
	(run-with-idle-timer delay t #'maybe-display-help)))
   
(defun maybe-display-help ()
  (unless (and (current-message)
	       (not (string= (current-message) "Quit")))
    (print-local-help t)))

(defun cancel-echo ()
  (interactive)
  (cancel-timer local-help-timer)
  (setq local-help-timer nil))

(global-set-key "\C-h\C-l" 'print-local-help)
============================================================

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Here are my highlighting functions for text-properties.

You can do C-h C-k to highlight help-echo regions and C-u C-h C-k to
remove the highlight.  To make things more interesting, you should
have adjacent regions with different non-nil help-echo properties.

More generally, M-x highlight-text-property-regions will prompt for a
property and two faces.  Specifying nil for the first face will remove
any highlight associated with the property.

These functions are more meant to get an idea of "what is in the
buffer" than for permanent highlighting.  They do _not_ automatically
set a timer to update.

===File ~/highlightprops.el=================================
(defun highlight-text-property-regions (prop &optional face1 face2)
  "Highlight regions with non-nil text or overlay property PROP.
Regions get highlighted using face1, except that adjacent regions
with non-nil but different PROP properties get highlighted
alternatively with face1 and face2.
If face1 is nil, remove all highlighting.
If face2 is nil, highlight all regions with face1."
  (interactive "SProperty to highlight: \nSMain face: \nSBackup face: ")
  (unless prop (error "PROP must be non-nil"))
  (let ((overlay-list (overlays-in (point-min) (point-max))))
    (dolist (overlay overlay-list)
      (when (eq (overlay-get overlay 'highlight-text-property-regions) prop)
	(delete-overlay overlay))))
  (if face1
      (let ((pos (point-min))
	    (oldpos)
	    (current-face face1)
	    (change-face nil)
	    (current-overlay))
	(overlay-recenter (point-max))
	(unless face2 (setq face2 face1))
	(while (/= pos (point-max))
	  (if (get-char-property pos prop)
	      (progn
		(setq oldpos pos)
		(setq pos (next-single-char-property-change pos prop))
		(if change-face
		    (setq current-face (if (eq current-face face1)
					   face2 face1)))
		(setq current-overlay
		      (make-overlay oldpos pos (current-buffer) t)) 
		(overlay-put current-overlay 'face current-face)
		(overlay-put current-overlay
			     'highlight-text-property-regions prop)
		(setq change-face t))
	    (setq pos (next-single-char-property-change pos prop))
	    (setq change-face nil))))))

(defface help-echo-primary-face
  '((t (:background "yellow")))
  "Used by `highlight-help-echo-regions' as its main face."
  :group 'faces)

(defface help-echo-secondary-face
  '((t (:background "orange")))
  "Used by `highlight-help-echo-regions' as its secondary face."
  :group 'faces)

(defun highlight-help-echo-regions (&optional arg)
  "Highlight regions with non-nil help-echo-property.
With a numeric argumenr, remove all such highlighting.
Regions are normally highlighted with `help-echo-primary-face'.
However, regions are highlighted with'help-echo-secondary-face',
if necessary to distinguish them from adjacent regions.  This is
mainly useful for temporary highlighting, as it might override
other highlighting. No automatic updating takes place."
  (interactive "P")
  (if arg (highlight-text-property-regions 'help-echo)
    (highlight-text-property-regions
     'help-echo 'help-echo-primary-face 'help-echo-secondary-face)))

(global-set-key "\C-h\C-k" 'highlight-help-echo-regions)	
	  
  
				 
============================================================

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

I forgot to check the documentation string of
`highlight-help-echo-regions' for typos, but the typos are obvious.

Sincerely,

Luc.

Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Text properties like `mouse-face' and `help-echo' are, as presently
conceived, not only completely useless to the blind, but to any
non mouse oriented user.  Unfortunately, quite a bit of documentation
relies exclusively on those type of features.  A disturbing recent
trend, already pointed out by others, is to rely more and more on
such mouse-exclusive features.

I propose to complement `mouse-face' and `help-echo' with two new text
properties, `short-help' and `long-help', which would be strings or
evaluate to strings.

The idea would be that `help-echo' could rely on the fact that the
user is busy using the mouse, `short-help' on the fact that he is
using the keyboard (if it makes a difference) and `long-help' would
provide more thorough documentation, in a more limited number of
situations.  `help-echo' would be the one that would always be
present if any one of the three is, with `short-help' defaulting to it.

Below is a function, `print-local-help' (which could be bound to some
help key sequence, say C-h C-l, as implemented below) that first looks
for a `short-help' property and, if none is found, for `help-echo' and
prints the resulting string in the echo area.  `long-help' would be
for documenting more elaborate and potentially confusing features like
keymap or local-map text-properties.  `long-help' would be accessed by
giving `print-local-help' a numeric argument.  This would display the
help in a help-buffer with all the usual features available, including
the ones provided by `substitute-command-keys' to print out keymaps,
the usual links and a completely functional "back" button. This could
be used for all kinds of information, including how to customize the
keymap provided by the text property.  (Hopefully, that would
encourage authors to make sure that such keymaps are easily
customizable.)

Two other functions `next-help-echo-region' and
`previous-help-echo-region' would carry one forward and backward to
the beginning of successive regions with non-nil `help-echo'
properties.  (They are bound to C-tab and C-M-tab in the
implementation below.)

I believe that this would allow for efficient use of local
documentation contained in text properties in a mouse-independent way.

If there is interest in the functionality below, then there is one
issue I still might need to address.  Below, I only handle `help-echo'
properties that are strings or evaluate to strings.  Strictly
speaking, the ((stringp echo) (message echo)) clause should be
replaced by an (echo (help-echo-string echo)) clause, where
`help-echo-string' would be a function computing the string
corresponding to the help-echo property if that property is a
function.  Is there already an Elisp function with that functionality?
If not are help-echo properties that are functions used in practice in
ordinary buffers?  (The only example I know of is used in the mode
line.)  If there is interest in the functionality, then I could, if
necessary, provide a function of this type myself.

I do not necessarily propose to put those functions in a separate
file.  (It would be too short.)  Maybe there is a natural place they
could go.

===File ~/local-help.el=====================================
;; The next variable and function are needed for xref info related to
;; print-local-help.

(defvar print-local-help-long "")

(defun print-local-help-setup-xref ()
  (help-setup-xref
   (list #'(lambda ()
	     (print-local-help-setup-xref)
	     (with-output-to-temp-buffer (help-buffer)
	       (princ (substitute-command-keys print-local-help-long)))))
   (interactive-p)))

(defun print-local-help (arg)
  "Display help related text or overlay properties.
Normally, this displays a short help message in the echo area,
namely the value of the `short-help' text or overlay property at
point.  If there is no `short-help' property at point, but there
is a `help-echo' property whose value is a string, then that is
printed instead.
If a numeric argument is given and there is a `long-help' text or
overlay property at point, then that is displayed in a temporary
help buffer, after `substitute-command-keys' is called on the
string."
  (interactive "P")
  (let ((short (get-char-property (point) 'short-help))
	(echo (get-char-property (point) 'help-echo)))
    (setq print-local-help-long (get-char-property (point) 'long-help))
    (print-local-help-setup-xref)
    (cond ((and arg print-local-help-long)
	   (with-output-to-temp-buffer (help-buffer)
	     (princ (substitute-command-keys print-local-help-long))
	     (print-help-return-message)))
	  (short (message short))
	  ((stringp echo) (message echo))
	  (print-local-help-long
	   (message
	    (substitute-command-keys
	     "Only long help is available. Type C-u \\[print-local-help]")))
	  (t (message "No local help at point")))))

(defun next-help-echo-region ()
  "Go to the start of the next region with non-nil help-echo property.
Adjacent areas with different non-nil help-echo properties are
considered different regions."
  (interactive)
  (let ((pos (next-single-char-property-change (point) 'help-echo)))
    (if (get-char-property pos 'help-echo)
	(goto-char pos)
      (setq pos (next-single-char-property-change pos 'help-echo))
      (if (= pos (point-max))
	  (message "No further help-echo regions in this buffer")
	(goto-char pos)))))

(defun previous-help-echo-region ()
  "Move back to the start of a region with non-nil help-echo property.
Adjacent areas with different non-nil help-echo properties are
considered different regions."
  (interactive)
  (let ((pos (previous-single-char-property-change (point) 'help-echo)))
    (if (get-char-property pos 'help-echo)
	(goto-char pos)
      (setq pos (previous-single-char-property-change pos 'help-echo))
      (if (get-char-property pos 'help-echo)
	  (goto-char pos)
	(message "No prior help-echo regions in this buffer")))))



(global-set-key "\C-h\C-l" 'print-local-help)
(global-set-key [C-tab] 'next-help-echo-region)
(global-set-key [C-M-tab] 'previous-help-echo-region)
============================================================

Re: Reducing mouse-dependency In Emacs.

[Eli Zaretskii]

> Date: Sat, 9 Aug 2003 22:42:33 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> Text properties like `mouse-face' and `help-echo' are, as presently
> conceived, not only completely useless to the blind, but to any
> non mouse oriented user.

True.

> I propose to complement `mouse-face' and `help-echo' with two new text
> properties, `short-help' and `long-help', which would be strings or
> evaluate to strings.

Rather than introducing new properties, I'd think it's better to have
an option to display the text defined thru mouse-face and help-echo
when point is anywhere inside the text covered by those properties.

Or am I missing some of your intent?

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Eli Zaretskii wrote:

   Rather than introducing new properties, I'd think it's better to have
   an option to display the text defined thru mouse-face and help-echo
   when point is anywhere inside the text covered by those properties.

That might be another thing that could be done.  However, it would
seem that even if that were implemented, we still would need a
function of the type `print-local-help', which could indeed be a lot
shorter without the additional properties.  The person who first
complained about this (T. V. Raman) very explicitly did not want
automatic display of the type you suggest:

   Would be a nice means to exploit some of the newer features of emacs
    ---as an example, balloon help in itself may not be 
   directly useful to the emacspeak user --- you really dont want emacs
   intrrupting what you're listening to and tell you things --makes it
   too much like the dreaded office-clip from idiot-proven interfaces. On
   the other hand it would be nice to ask for a tooltip.

The new text properties and the way to make them accessible are two
separate issues.  The new properties would just provide some extra
flexibility.  `short-help' would default to `help-echo' and would just
be used if the author thought that whether the user is currently using
the mouse or the keyboard makes a difference. `long-help' just
provides a way to provide more elaborate help.  In as far as
`long-help' is concerned, that was inspired by another thread on
`bug-gnu-emacs@gnu.org'.  Quoting Peter Seibel:

    Anyway, I noticed this problem because I was trying to use RET to
    enter a new line in the middle of a longish list (like the value of
    load-path) that I had just dumped into my *scratch* buffer to see what
    the heck it was and was pretty confused at what the heck was going on
    since the binding didn't show up in the mode documentation (nor, as it
    turns out, in the output of describe-bindings) I eventually figured
    out from experiments with C-h k more or less what was going on.

Meant is the rebinding of RET (and mouse-2) in C-j output in Lisp
interaction mode.

So I thought that it might be good to be able to provide people with
more elaborate information if they are confused, with links to other
places, printed out keymaps and such.  Maybe also information on how
to customize or disable the feature if they are not happy with it.

For this type of situation, optional automatic highlighting and display
(of short `help-echo' type text) on "point-over" might indeed be a
nice additional feature.  Maybe `describe-bindings' could also list
text and overlay property keymaps, that could also help.

Sincerely,

Luc.

Re: Reducing mouse-dependency In Emacs.

[Richard Stallman]

    Rather than introducing new properties, I'd think it's better to have
    an option to display the text defined thru mouse-face and help-echo
    when point is anywhere inside the text covered by those properties.

I agree that it would be better to use the existing properties in
different ways, if we can work out a way to do so.

    The idea would be that `help-echo' could rely on the fact that the
    user is busy using the mouse, `short-help' on the fact that he is
    using the keyboard (if it makes a difference) and `long-help' would
    provide more thorough documentation, in a more limited number of
    situations.

`long-help' seems superfluous; we already have the doc string for that.
I think it is ok to define `short-help' for this purpose, when the default
handling seems suboptimal; but we should try to provide a default that is
good enough that few commands need to use `short-help'.

    Two other functions `next-help-echo-region' and
    `previous-help-echo-region' would carry one forward and backward to
    the beginning of successive regions with non-nil `help-echo'
    properties.  (They are bound to C-tab and C-M-tab in the
    implementation below.)

I agree that this feature could be useful.  However, it won't be
terribly useful if people have to remember commands for it.  It will
be much more useful if we can find a self-evident way to invoke it.
That may not be possible, but let's try.  Can people try looking for
one?

Re: Reducing mouse-dependency In Emacs.

[Stefan Monnier]

> I propose to complement `mouse-face' and `help-echo' with two new text
> properties, `short-help' and `long-help', which would be strings or
> evaluate to strings.

Sounds like overengineering to me.  It's already hard enough to
get people to add the `help-echo' property (additionally to docstrings,
comments, and the manual).
I think we only need some ways for those properties to be used/usable
without a mouse.
What you suggested sounds pretty good.  We could also have a more noisy
option that always echos the help-echo property around point (after some
idle delay, of course).  Or some other that hilights text with the
`mouse-face' face when point is inside.



	Stefan

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Stefan Monnier wrote:

   Sounds like overengineering to me.  It's already hard enough to
   get people to add the `help-echo' property (additionally to docstrings,
   comments, and the manual).

And the NEWS.  But the text properties would be optional, defaulting
to `help-echo'.  The reason for a separate `short-help' is that a much
too large percentage of the help-echo properties are like:

mouse-2: visit this file in other window

on a file name in dired.  There is no reason to single out this
command among the zillion possible, other than that the user has the
mouse in the hand and hence is planning to use the mouse, so only
mouse commands "make sense".  If 100% of the help-echo's were like
that, there would be no need at all to access `help-echo' from the
keyboard.  If 0% were like that, you would be completely right.  The
problem is that it is not close to 0, but not close to 100 either.

In the case of `long-help', there might be instances where an author
might want to provide more information than would comfortably fit in
the echo area.

There are some bugs in the version of `print-local-help' I sent, but
they are easy to correct.  Anyway, we need to decide what we want to
do with these new text properties.  If one definitely does not want
them, the function would get shorter.

   What you suggested sounds pretty good.  We could also have a more noisy
   option that always echos the help-echo property around point (after some
   idle delay, of course).  Or some other that hilights text with the
   `mouse-face' face when point is inside.

In as far as an option to automatically display the help-echo text on
"point-over" is concerned, I told Eli, who suggested the same thing,
this morning that it would be a good idea, but after actually
implementing it, I completely changed my mind.  I found all that text
popping up in the echo area very distracting.  Most of it was of the
"mouse-2: do something you do not want to do" type.

I believe something should be done with highlighting, but at the
moment I am not sure what the best thing would be.

Sincerely,

Luc.

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

I have implemented a function:

(defun highlight-text-property-regions (prop &optional face1 face2) 
     ...

It takes any text property PROP and highlights all regions with
non-nil text or overlay property PROP.  Two faces face1 and face2 are
needed to be able to distinguish adjacent regions with non-nil but
different values for PROP.  This could be used not just for
`help-echo' but for also to recognize regions with `keymap' and
`local-map' properties and so on.  (I personally believe that regions
with local keymaps should be already highlighted anyway, but that is
definitely not always the case in practice.)  The function is mainly
useful for temporary highlighting, as it might conceal other
highlighting.

To remove the highlighting, one just uses nil for face1, that is, give
no optional arguments.

Seems to work well and be useful after some experimentation.

I am still thinking about some additional user interface functions and
will send some code later.

Sincerely,

Luc.

Re: Reducing mouse-dependency In Emacs.

[Richard Stallman]

    I have implemented a function:

    (defun highlight-text-property-regions (prop &optional face1 face2) 

It sounds potentially useful.

Re: Reducing mouse-dependency In Emacs.

[Eli Zaretskii]

> Date: Sun, 10 Aug 2003 18:09:24 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> In as far as an option to automatically display the help-echo text on
> "point-over" is concerned, I told Eli, who suggested the same thing,
> this morning that it would be a good idea, but after actually
> implementing it, I completely changed my mind.  I found all that text
> popping up in the echo area very distracting.  Most of it was of the
> "mouse-2: do something you do not want to do" type.

Why is this distracting?  A user who turns such a feature on must be
knowing what they are doing.  For example, I assume a blind person
_wants_ this info to be spelled by the speech synthesizer; otherwise,
how would she know about these properties sitting around the text?

(I assume that your implementation waits for some amount of time
before it displays the text in the echo area, so the text is shown
only if one dwells long enough on the text covered by the property.)

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Eli Zaretskii wrote:

   Why is this distracting?  A user who turns such a feature on must be
   knowing what they are doing.  For example, I assume a blind person
   _wants_ this info to be spelled by the speech synthesizer; otherwise,
   how would she know about these properties sitting around the text?

   (I assume that your implementation waits for some amount of time
   before it displays the text in the echo area, so the text is shown
   only if one dwells long enough on the text covered by the property.)

I only used a rudimentary implementation to experiment.  It is
provided below.  If we would go for a "real" implementation, the
variable `delay' would be replaced by a real defcustom for a variable
with a longer name and there would be a user option to enable or
cancel the timer.  In the meantime, one can experiment with 
(setq delay some_number)

Do: `M-x cancel-echo' when you are fed up with it.  (Which may happen
rather quickly.)  Again, this command is only provided for
experimentation convenience.

Some of the really rough edges could be improved by a more
sophisticated implementation.

However, I do not know what to do about the fact that the vast
majority of things popping up are of the:
"mouse-2: do something you do not want to do" type.

(In the most often used buffers, dired, *info* and the like.)

I find that stuff popping up in the echo area all the time annoying,
let alone have it spoken to me.  (And a blind person can not use the
mouse anyway.)

   otherwise,
   how would she know about these properties sitting around the text?

That is a problem.  That is one of the reasons I provided
`next-help-echo-region' and `previous-help-echo-region'.  They allow
to scan the buffer and check what kind of features are provided.  This
can be done while the user is focused on this subject, without
distracting her while she is working on something else and should be
focusing on that.  For the seeing non mouse oriented user, my
highlighting functions, which I will send somewhat later could be used
as a complement to these motion functions.  They too are meant more to
get some idea of "what is in the buffer" than as permanent
highlighting.  I do not know how highlighting works in emacspeak.

===File ~/help-timer.el=====================================
(defun print-local-help (&optional timer)
  "Display help related text or overlay properties.
This displays a short help message in the echo area, namely the
value of the `short-help' text or overlay property at point.  If
there is no `short-help' property at point, but there is a
`help-echo' property whose value is a string, then that is
printed instead.

The timer argument is meant fro use in `run-with-idle-timer' and
prevents displey of a message in case there is no help."
  (interactive)
  (let ((short (get-char-property (point) 'short-help))
	(echo (get-char-property (point) 'help-echo)))
    (cond (short (message short))
	  ((stringp echo) (message echo))
	  ((not timer) (message "No local help at point")))))

(defvar delay 1)

(defvar local-help-timer nil)

(unless local-help-timer
  (setq local-help-timer (run-with-idle-timer delay t #'print-local-help t)))
   
(defun cancel-echo ()
  (interactive)
  (cancel-timer local-help-timer)
  (setq local-help-timer nil))

(global-set-key "\C-h\C-l" 'print-local-help)
============================================================

Re: Reducing mouse-dependency In Emacs.

[Eli Zaretskii]

> Date: Mon, 11 Aug 2003 10:52:10 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> However, I do not know what to do about the fact that the vast
> majority of things popping up are of the:
> "mouse-2: do something you do not want to do" type.

I think there should be another binding for the same command that
doesn't use the mouse, and the help echo should print that binding
when this option is set (since it's obvious the mouse is not used).

Re: Reducing mouse-dependency In Emacs.

[Stefan Monnier]

> And the NEWS.  But the text properties would be optional, defaulting
> to `help-echo'.  The reason for a separate `short-help' is that a much
> too large percentage of the help-echo properties are like:
> 
> mouse-2: visit this file in other window

Reminds me of the suggestion I had a while ago to make such help
partly automatic (at least when a `local-map' or `keymap' property
is present, but maybe also when a `mouse-face' is present).

Having it automatic saves work from the coder, but also allows the help
text to be different in the `point-over' than in the `mouse-over' case.


	Stefan

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Stefan Monnier wrote:

   Reminds me of the suggestion I had a while ago to make such help
   partly automatic (at least when a `local-map' or `keymap' property
   is present, but maybe also when a `mouse-face' is present).

   Having it automatic saves work from the coder, but also allows the help
   text to be different in the `point-over' than in the `mouse-over' case.

I was not a part of that discussion and hence am unfamiliar with the
arguments pro and con.

Eli Zaretskii wrote:

   I think there should be another binding for the same command that
   doesn't use the mouse, and the help echo should print that binding
   when this option is set (since it's obvious the mouse is not used).

There are two problems here.

1. In the dired case, which is rather typical, the problem with
"mouse-2: visit this file in other window" is not just that it
mentions mouse-2 instead of `o', but also that it singles out this
particular command for documentation.  The reason for that is that it
is bound to a mouse command and that the user has the mouse in hand
and hence the author knows that he wants to use a mouse command.
Plenty of help-echo's are in this category.  There is no need to
access these from the keyboard.
2. It seems that your suggestion would require plenty of work
rewriting `help-echo' properties.

If we are going to provide automatic display, I believe we should be
conservative in what we show.  It should really be relevant, since,
especially in spoken version, it is distracting.

I would propose to only show `short-help' on point-over, or at least
provide an option to only show that one.  Maybe `short-help' for
`keymap' and `local-map' properties could be generated automatically
(but overridden by an explicit `short-help' property).  If not, we
could show `help-echo' on point-over, *if* one of those properties is
present, because in that case `help-echo' is very likely to be
relevant.  We could use the convention that a value of t for
`short-help' would mean to show `help-echo' on point-over.  So we
would have three types of `short-help': automatically generated, `t'
to indicate that the `help-echo' property is really relevant to the
keyboard user and explicitly provided strings.

In the beginning most `short-help' properties might be of the first
type, but that could change quickly.  In the meantime, `help-echo' is
available when explicitly asked for, or maybe as an option for
automatic display, for users who do not mind about irrelevant info
showing up in the echo area.

Sincerely,

Luc.

Re: Reducing mouse-dependency In Emacs.

[Eli Zaretskii]

> Date: Mon, 11 Aug 2003 21:30:21 -0500 (CDT)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> 1. In the dired case, which is rather typical, the problem with
> "mouse-2: visit this file in other window" is not just that it
> mentions mouse-2 instead of `o', but also that it singles out this
> particular command for documentation.  The reason for that is that it
> is bound to a mouse command and that the user has the mouse in hand
> and hence the author knows that he wants to use a mouse command.
> Plenty of help-echo's are in this category.

I think the reason is that the command bound to mouse-2 is the single
most important command at that spot: it allows you to edit the file at
point.

> 2. It seems that your suggestion would require plenty of work
> rewriting `help-echo' properties.

Not necessarily; we could do something similar to function-key-map, or
some other means of redirection.  We could arrange for this to be set
up whenever some option is customized.

Re: Reducing mouse-dependency In Emacs.

[Luc Teirlinck]

Eli Zeretskii wrote:

   > 2. It seems that your suggestion would require plenty of work
   > rewriting `help-echo' properties.

   Not necessarily; we could do something similar to function-key-map, or
   some other means of redirection.  We could arrange for this to be set
   up whenever some option is customized.

I do not see the relation with `function-key-map'.  All you have to
work with is an arbitrary string that does not follow any rigid
conventions.  In the dired case, mouse-2 is bound (by default) to
`dired-mouse-find-file-other-window', which does not have any default
keyboard binding.  But `dired-find-file-other-window', usually bound
to `o', has the same functionality.  In the dired case, help-echo is:
"mouse-2: visit this file in other window", but, again, help-echo does
not need to follow any fixed pattern.

Note that there is a problem with an help-echo style: 

"mouse-2: visit this file in other window".

The user could have rebound mouse-2.  Many help-echo strings have this
problem.  The vast majority refer to default bindings, not actual bindings.

Sincerely,

Luc.