locate-with-filter

locate-with-filter

[Richard Stallman]

The doc string of locate-with-filter is not clear at all.
Can someone make it clearer?

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

   The doc string of locate-with-filter is not clear at all.
   Can someone make it clearer?

I have no problem understanding it myself, so I do not know what the
exact problem is.  However, does the patch below make it clearer?
The other changes in the patch are meant to distinguish more clearly
between the external locate program and the Emacs locate command,
remove a confusing self-referential link in the locate docstring and
replace an alias for `keep-lines' by the current name.

I can install if desired.

===File ~/locate-diff=======================================
*** locate.el	06 Feb 2006 16:01:50 -0600	1.35
--- locate.el	12 Mar 2006 17:45:59 -0600	
***************
*** 190,196 ****
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run the program `locate', putting results in `*Locate*' buffer.
  With prefix arg, prompt for the locate command to run."
    (interactive
        (list
--- 190,196 ----
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run the locate program, putting results in `*Locate*' buffer.
  With prefix arg, prompt for the locate command to run."
    (interactive
        (list
***************
*** 255,264 ****
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run the locate command with a filter.
  
! The filter is a regular expression. Only results matching the filter are
! shown; this is often useful to constrain a big search."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
--- 255,265 ----
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run the locate program with a filter.
  
! FILTER is a regular expression.  Only the lines in the output of
! the locate program that contain a match for FILTER are shown in
! the `*Locate*' buffer; this is often useful to constrain a big search."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
***************
*** 269,275 ****
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (delete-non-matching-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
--- 270,276 ----
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (keep-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
============================================================

Re: locate-with-filter

[Luc Teirlinck]

The following might be better than my previous patch:

===File ~/locate-diff=======================================
*** locate.el	06 Feb 2006 16:01:50 -0600	1.35
--- locate.el	12 Mar 2006 18:20:10 -0600	
***************
*** 190,196 ****
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run the program `locate', putting results in `*Locate*' buffer.
  With prefix arg, prompt for the locate command to run."
    (interactive
        (list
--- 190,196 ----
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run the locate program, putting results in `*Locate*' buffer.
  With prefix arg, prompt for the locate command to run."
    (interactive
        (list
***************
*** 255,264 ****
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run the locate command with a filter.
  
! The filter is a regular expression. Only results matching the filter are
! shown; this is often useful to constrain a big search."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
--- 255,270 ----
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run the locate program with a filter.
  
! When invoked interactively, this command prompts for both SEARCH-STRING
! and FILTER.  It passes SEARCH-STRING to the locate program.
! It only shows those lines in the output of the locate program
! that contain a match for the regular expression FILTER in the
! `*Locate*' buffer; this is often useful to constrain a big search.
! 
! When called from Lisp, this function is identical with `locate',
! except that FILTER is not optional."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
***************
*** 269,275 ****
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (delete-non-matching-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
--- 275,281 ----
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (keep-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
============================================================

Re: locate-with-filter

[Eli Zaretskii]

> Date: Sun, 12 Mar 2006 18:18:05 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: pbreton@cs.umb.edu, emacs-devel@gnu.org
> 
>   ;;;###autoload
>   (defun locate (search-string &optional filter)
> !   "Run the program `locate', putting results in `*Locate*' buffer.
>   With prefix arg, prompt for the locate command to run."
>     (interactive
>         (list
> --- 190,196 ----
>   
>   ;;;###autoload
>   (defun locate (search-string &optional filter)
> !   "Run the locate program, putting results in `*Locate*' buffer.
>   With prefix arg, prompt for the locate command to run."

This change is for the worse, IMHO.  The original doc string makes it
clear that `locate' is a program, whereas the new strings could be
misunderstood to talk about some mysterious ``locate program'' (as in
``relocation program'').

There are more instances of using ``the locate program'' in your
changes; I think they all need to be modified in the same way to make
sure the meaning is clear.

Re: locate-with-filter

[Peter Breton]

I agree with Eli on this one.

I did like all Luc's other changes tho.

Peter

> > Date: Sun, 12 Mar 2006 18:18:05 -0600 (CST)
> > From: Luc Teirlinck <teirllm@dms.auburn.edu>
> > Cc: pbreton@cs.umb.edu, emacs-devel@gnu.org
> > 
> >   ;;;###autoload
> >   (defun locate (search-string &optional filter)
> > !   "Run the program `locate', putting results in
> `*Locate*' buffer.
> >   With prefix arg, prompt for the locate command
> to run."
> >     (interactive
> >         (list
> > --- 190,196 ----
> >   
> >   ;;;###autoload
> >   (defun locate (search-string &optional filter)
> > !   "Run the locate program, putting results in
> `*Locate*' buffer.
> >   With prefix arg, prompt for the locate command
> to run."
> 
> This change is for the worse, IMHO.  The original
> doc string makes it
> clear that `locate' is a program, whereas the new
> strings could be
> misunderstood to talk about some mysterious ``locate
> program'' (as in
> ``relocation program'').
> 
> There are more instances of using ``the locate
> program'' in your
> changes; I think they all need to be modified in the
> same way to make
> sure the meaning is clear.
> 

Re: locate-with-filter

[Richard Stallman]

      (defun locate (search-string &optional filter)
    !   "Run the program `locate', putting results in `*Locate*' buffer.
      With prefix arg, prompt for the locate command to run."
	(interactive
	    (list
    --- 190,196 ----

      ;;;###autoload
      (defun locate (search-string &optional filter)
    !   "Run the locate program, putting results in `*Locate*' buffer.

This is a small step in the wrong direction, so please don't do it.

The problem is that this description is not self-contained.  It
assumes the reader knows about the `locate' program and knows what its
output looks like.

This command should have a self-contained description which is comprehensible
without knowing about `locate'.

      ;;;###autoload
      (defun locate-with-filter (search-string filter)
    !   "Run the locate program with a filter.

    ! FILTER is a regular expression.  Only the lines in the output of
    ! the locate program that contain a match for FILTER are shown in
    ! the `*Locate*' buffer; this is often useful to constrain a big search."

That is a little better.  It eliminates the ambiguity.

    ! When invoked interactively, this command prompts for both SEARCH-STRING
    ! and FILTER.  It passes SEARCH-STRING to the locate program.
    ! It only shows those lines in the output of the locate program
    ! that contain a match for the regular expression FILTER in the
    ! `*Locate*' buffer; this is often useful to constrain a big search.
    ! 
    ! When called from Lisp, this function is identical with `locate',
    ! except that FILTER is not optional."

That is a little better than the first try.

With this change, `locate-with-filter's doc string still has the same
problem as that of `locate'.

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

   This is a small step in the wrong direction, so please don't do it.

The problem with `locate' in the docstring of `locate' is that it
creates a confusing self-referential link.  The problem with `locate'
to refer to the executable program of that name is that it creates a
link to the _Emacs_ command locate, creating even more confusion.

   The problem is that this description is not self-contained.  It
   assumes the reader knows about the `locate' program and knows what its
   output looks like.

   This command should have a self-contained description which is
   comprehensible without knowing about `locate'.

That is not as easy as it sounds.  There appear to be _very_ different
versions of locate, even of GNU locate, around.  Some treat
SEARCH-STRING as a literal string, some treat it as a shell pattern
and in certain cases, it treats SEARCH-STRING as a POSIX regular
expression.  The Info documentation I have installed says that locate
treats SEARCH-STRING as a shell pattern.  The man page says that it
treats it as a literal string, but that it has an option to treat it
as a POSIX regular expression instead.  The actual behavior matches
the man page.  Many operating systems, even UNIX style ones, have, by
default, no locate program installed at all.

Currently, you may need to read the comments at the beginning of
locate.el to use its functionality.  The patch below tries to put more
of that info in the docstrings.

I kept some references to "locate program", but in a context where I
first refer to the program as a `"locate" type program', so that no
confusion with relocation programs is possible.  I could
systematically write "locate executable program" instead, but in the
given context, that seemed redundant.

===File ~/locate-diff=======================================
*** locate.el	06 Feb 2006 16:01:50 -0600	1.35
--- locate.el	13 Mar 2006 20:35:53 -0600	
***************
*** 122,128 ****
    :group 'external)
  
  (defcustom locate-command "locate"
!   "*The executable program used to search a database of files."
    :type 'string
    :group 'locate)
  
--- 122,144 ----
    :group 'external)
  
  (defcustom locate-command "locate"
!   "Executable program for searching a database of files.
! The Emacs commands `locate' and `locate-with-filter' use this.
! The value should be a program that can be called from a shell
! with one argument, SEARCH-STRING.  The output of the program
! should consist of those file names in the database that match
! SEARCH-STRING, listed one per line, possibly with leading or
! trailing whitespace.  If the output is in another form, you may
! have to redefine the function `locate-get-file-positions'.
! 
! The program may interpret SEARCH-STRING as a literal string, a
! shell pattern or a regular expression.  The exact rules of what
! constitutes a match may also depend on the program.
! 
! The standard value of this variable is \"locate\".
! Do `M-x man RET locate RET' to check whether you have this
! program installed, how it interprets SEARCH-STRING and how it
! determines which files match SEARCH-STRING."
    :type 'string
    :group 'locate)
  
***************
*** 133,139 ****
    "The history list used by the \\[locate-with-filter] command.")
  
  (defcustom locate-make-command-line 'locate-default-make-command-line
!   "*Function used to create the locate command line."
    :type 'function
    :group 'locate)
  
--- 149,160 ----
    "The history list used by the \\[locate-with-filter] command.")
  
  (defcustom locate-make-command-line 'locate-default-make-command-line
!   "Function used to create the locate command line.
! The Emacs commands `locate' and `locate-with-filter' use this.
! This function should take one argument, a string (the name to find)
! and return a list.  The first element of the list should be a command
! to be executed by a shell, the remaining elements should be the arguments
! to that command (including the name to find)."
    :type 'function
    :group 'locate)
  
***************
*** 143,149 ****
    :group 'locate)
  
  (defcustom locate-fcodes-file nil
!   "*File name for the database of file names."
    :type '(choice (const :tag "None" nil) file)
    :group 'locate)
  
--- 164,170 ----
    :group 'locate)
  
  (defcustom locate-fcodes-file nil
!   "File name for the database of file names used by `locate'."
    :type '(choice (const :tag "None" nil) file)
    :group 'locate)
  
***************
*** 161,172 ****
    :version "22.1")
  
  (defcustom locate-update-command "updatedb"
!   "The command used to update the locate database."
    :type 'string
    :group 'locate)
  
  (defcustom locate-prompt-for-command nil
!   "If non-nil, the locate command prompts for a command to run.
  Otherwise, that behavior is invoked via a prefix argument."
    :group 'locate
    :type 'boolean
--- 182,193 ----
    :version "22.1")
  
  (defcustom locate-update-command "updatedb"
!   "The executable command used to update the locate database."
    :type 'string
    :group 'locate)
  
  (defcustom locate-prompt-for-command nil
!   "If non-nil, the `locate' command prompts for a command to run.
  Otherwise, that behavior is invoked via a prefix argument."
    :group 'locate
    :type 'boolean
***************
*** 190,197 ****
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run the program `locate', putting results in `*Locate*' buffer.
! With prefix arg, prompt for the locate command to run."
    (interactive
        (list
         (if (or (and current-prefix-arg
--- 211,232 ----
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run a \"locate\" type program, putting results in `*Locate*' buffer.
! Pass it SEARCH-STRING as argument.  Interactively, prompt for SEARCH_STRING.
! With prefix arg, prompt for the exact \"locate\" command to run instead.
! 
! Without prefix arg, this normally runs the executable program GNU locate.
! This program searches for those file names in a database that match
! SEARCH-STRING and normally outputs all matching absolute file names,
! one per line.  Do `M-x man RET locate RET' to check whether you have this
! program installed, how it interprets SEARCH-STRING and how it determines
! what constitutes a match.  (The details vary highly with the version.)
! 
! You can specify another program for this command to run by customizing
! the variables `locate-command' or `locate-make-command-line'.
! 
! The main use of FILTER is to implement `locate-with-filter'.  See
! the docstring of that function for its meaning."
    (interactive
        (list
         (if (or (and current-prefix-arg
***************
*** 255,264 ****
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run the locate command with a filter.
  
! The filter is a regular expression. Only results matching the filter are
! shown; this is often useful to constrain a big search."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
--- 290,305 ----
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run a \"locate\" type program with a filter.
! This is similar to `locate', which see.  The difference is that,
! when invoked interactively, this command prompts for both SEARCH-STRING
! and FILTER.  It passes SEARCH-STRING to the locate program.
! It only shows those lines in the output of the locate program
! that contain a match for the regular expression FILTER in the
! `*Locate*' buffer; this is often useful to constrain a big search.
  
! When called from Lisp, this function is identical with `locate',
! except that FILTER is not optional."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
***************
*** 269,275 ****
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (delete-non-matching-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
--- 310,316 ----
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (keep-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
============================================================
 LocalWords:  docstrings

Re: locate-with-filter

[Eli Zaretskii]

> Date: Mon, 13 Mar 2006 20:55:15 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> Cc: pbreton@cs.umb.edu, emacs-devel@gnu.org
> 
> Richard Stallman wrote:
> 
>    This is a small step in the wrong direction, so please don't do it.
> 
> The problem with `locate' in the docstring of `locate' is that it
> creates a confusing self-referential link.  The problem with `locate'
> to refer to the executable program of that name is that it creates a
> link to the _Emacs_ command locate, creating even more confusion.

The style of quotes around "locate" is a separate issue.  What I meant
to say was that the doc strings should make it clear when they talk
about an executable program `locate' and when about an Emacs command
`locate'.

>   (defcustom locate-update-command "updatedb"
> !   "The executable command used to update the locate database."
>     :type 'string
>     :group 'locate)

I think "executable command" is not clear enough.  How about "program"
or "executable program"?

>   (defun locate (search-string &optional filter)
> !   "Run a \"locate\" type program, putting results in `*Locate*' buffer.

I like this.  Thanks.

Re: locate-with-filter

[Luc Teirlinck]

Eli Zaretskii wrote:

   I think "executable command" is not clear enough.  How about "program"
   or "executable program"?

I used this in the patch below.  In addition, I also noticed that
even after my changes, it may not be clear what the database consists
of or where it comes from.  So I suggest the following updated patch,
which addresses this.

===File ~/locate-diff=======================================
*** locate.el	06 Feb 2006 16:01:50 -0600	1.35
--- locate.el	13 Mar 2006 23:39:11 -0600	
***************
*** 122,128 ****
    :group 'external)
  
  (defcustom locate-command "locate"
!   "*The executable program used to search a database of files."
    :type 'string
    :group 'locate)
  
--- 122,148 ----
    :group 'external)
  
  (defcustom locate-command "locate"
!   "Executable program for searching a database of files.
! The Emacs commands `locate' and `locate-with-filter' use this.
! The value should be a program that can be called from a shell
! with one argument, SEARCH-STRING.  The program determines which
! database it searches.  The output of the program should consist
! of those file names in the database that match SEARCH-STRING,
! listed one per line, possibly with leading or trailing
! whitespace.  If the output is in another form, you may have to
! redefine the function `locate-get-file-positions'.
! 
! The program may interpret SEARCH-STRING as a literal string, a
! shell pattern or a regular expression.  The exact rules of what
! constitutes a match may also depend on the program.
! 
! The standard value of this variable is \"locate\".
! This program normally searches a database of all files on your
! system, or of all files that you have access to.  Do
! `M-x man RET locate RET' to check whether you have this program
! installed, how it interprets SEARCH-STRING, how it determines
! which files match SEARCH-STRING, and how it maintains its
! database.  (The details vary highly with the version.)"
    :type 'string
    :group 'locate)
  
***************
*** 133,139 ****
    "The history list used by the \\[locate-with-filter] command.")
  
  (defcustom locate-make-command-line 'locate-default-make-command-line
!   "*Function used to create the locate command line."
    :type 'function
    :group 'locate)
  
--- 153,164 ----
    "The history list used by the \\[locate-with-filter] command.")
  
  (defcustom locate-make-command-line 'locate-default-make-command-line
!   "Function used to create the locate command line.
! The Emacs commands `locate' and `locate-with-filter' use this.
! This function should take one argument, a string (the name to find)
! and return a list.  The first element of the list should be a command
! to be executed by a shell, the remaining elements should be the arguments
! to that command (including the name to find)."
    :type 'function
    :group 'locate)
  
***************
*** 143,149 ****
    :group 'locate)
  
  (defcustom locate-fcodes-file nil
!   "*File name for the database of file names."
    :type '(choice (const :tag "None" nil) file)
    :group 'locate)
  
--- 168,181 ----
    :group 'locate)
  
  (defcustom locate-fcodes-file nil
!   "File name for the database of file names used by `locate'.
! If non-nil, `locate' uses this name in the header of the `*Locate*'
! buffer.  If nil, it mentions no file name in that header.
! 
! Just setting this variable does not actually change the database
! that `locate' searches.  The executive program that the Emacs
! function `locate' uses, as given by the variables `locate-command'
! or `locate-make-command-line', determines the database."
    :type '(choice (const :tag "None" nil) file)
    :group 'locate)
  
***************
*** 161,172 ****
    :version "22.1")
  
  (defcustom locate-update-command "updatedb"
!   "The command used to update the locate database."
    :type 'string
    :group 'locate)
  
  (defcustom locate-prompt-for-command nil
!   "If non-nil, the locate command prompts for a command to run.
  Otherwise, that behavior is invoked via a prefix argument."
    :group 'locate
    :type 'boolean
--- 193,204 ----
    :version "22.1")
  
  (defcustom locate-update-command "updatedb"
!   "The executable program used to update the locate database."
    :type 'string
    :group 'locate)
  
  (defcustom locate-prompt-for-command nil
!   "If non-nil, the `locate' command prompts for a command to run.
  Otherwise, that behavior is invoked via a prefix argument."
    :group 'locate
    :type 'boolean
***************
*** 190,197 ****
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run the program `locate', putting results in `*Locate*' buffer.
! With prefix arg, prompt for the locate command to run."
    (interactive
        (list
         (if (or (and current-prefix-arg
--- 222,246 ----
  
  ;;;###autoload
  (defun locate (search-string &optional filter)
!   "Run a \"locate\" type program, putting results in `*Locate*' buffer.
! Pass it SEARCH-STRING as argument.  Interactively, prompt for SEARCH_STRING.
! With prefix arg, prompt for the exact \"locate\" command to run instead.
! 
! Without prefix arg, this normally runs the executable program GNU locate.
! This program searches for those file names in a database that match
! SEARCH-STRING and normally outputs all matching absolute file names,
! one per line.  The database normally consists of all files on your
! system, or of all files that you have access to.  Do
! `M-x man RET locate RET' to check whether you have this program
! installed, how it interprets SEARCH-STRING, how it determines
! what constitutes a match, and how it maintains its database.
! \(The details vary highly with the version.)
! 
! You can specify another program for this command to run by customizing
! the variables `locate-command' or `locate-make-command-line'.
! 
! The main use of FILTER is to implement `locate-with-filter'.  See
! the docstring of that function for its meaning."
    (interactive
        (list
         (if (or (and current-prefix-arg
***************
*** 255,264 ****
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run the locate command with a filter.
  
! The filter is a regular expression. Only results matching the filter are
! shown; this is often useful to constrain a big search."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
--- 304,319 ----
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run a \"locate\" type program with a filter.
! This is similar to `locate', which see.  The difference is that,
! when invoked interactively, this command prompts for both SEARCH-STRING
! and FILTER.  It passes SEARCH-STRING to the locate program.
! It only shows those lines in the output of the locate program
! that contain a match for the regular expression FILTER in the
! `*Locate*' buffer; this is often useful to constrain a big search.
  
! When called from Lisp, this function is identical with `locate',
! except that FILTER is not optional."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
***************
*** 269,275 ****
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (delete-non-matching-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
--- 324,330 ----
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (keep-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
============================================================

Re: locate-with-filter

[Richard Stallman]

    The problem with `locate' in the docstring of `locate' is that it
    creates a confusing self-referential link.

It is not self-referential.  It is in the documentation of an Emacs command
and it refers to a program.

      The problem with `locate'
    to refer to the executable program of that name is that it creates a
    link to the _Emacs_ command locate, creating even more confusion.

We should suppress the link in that case.  Does this patch do it?


*** help-mode.el	07 Feb 2006 18:16:11 -0500	1.43
--- help-mode.el	14 Mar 2006 06:56:26 -0500	
***************
*** 233,242 ****
    "Label to use by `help-make-xrefs' for the go-back reference.")
  
  (defconst help-xref-symbol-regexp
!   (purecopy (concat "\\(\\<\\(\\(variable\\|option\\)\\|"
! 		    "\\(function\\|command\\)\\|"
! 		    "\\(face\\)\\|"
! 		    "\\(symbol\\)\\|"
  		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
  		    "[ \t\n]+\\)?"
  		    ;; Note starting with word-syntax character:
--- 233,242 ----
    "Label to use by `help-make-xrefs' for the go-back reference.")
  
  (defconst help-xref-symbol-regexp
!   (purecopy (concat "\\(\\<\\(\\(variable\\|option\\)\\|"  ; Link to var
! 		    "\\(function\\|command\\)\\|"          ; Link to function
! 		    "\\(face\\)\\|"			   ; Link to face
! 		    "\\(symbol\\|program\\)\\|"		   ; Don't link
  		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
  		    "[ \t\n]+\\)?"
  		    ;; Note starting with word-syntax character:

Re: locate-with-filter

[Richard Stallman]

    That is not as easy as it sounds.  There appear to be _very_ different
    versions of locate, even of GNU locate, around.

Could you check what the current version does?
We can document that, then say that some versions of `locate'
behave differently.

Anyway, the syntax of regexps is just a detail in the overall framework
of what the command does.

      The Info documentation I have installed says that locate
    treats SEARCH-STRING as a shell pattern.  The man page says that it
    treats it as a literal string, but that it has an option to treat it
    as a POSIX regular expression instead.  The actual behavior matches
    the man page.

Would you please report this bug?

      Many operating systems, even UNIX style ones, have, by
    default, no locate program installed at all.

Then the command will get an error, and the user, seeing the note
at the end saying this uses the `locate' program, will understand why.


Your changes are an improvement overall, but let's not change the way
we refer to a program, and I don't think we should refer to man pages
as the primary documentation, and I would like to describe the general
purpose of the `locate' command before mentioning the details that vary.

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

   Could you check what the current version does?

It treats the search string as a shell pattern in a non-standard way,
which is different from both the way `bash' and `find' treat shell
patterns.  But there are several other maintained and widely used
locate variants out there that treat the search string as an ordinary
string and optionally as a regexp.  Basically, if people use a locate
program, they should either pass it only strings without any special
characters or read the docs.

In my latest patches, which I send separately, I just talk about
"matching" SEARCH-STRING and refer to the docs for details.  Anything
else is just likely to cause a lot more confusion than help to most
people.

	The Info documentation I have installed says that locate
       treats SEARCH-STRING as a shell pattern.  The man page says that it
       treats it as a literal string, but that it has an option to treat it
       as a POSIX regular expression instead.  The actual behavior matches
       the man page.

   Would you please report this bug?

I believe that it is a local problem rather than a bug.  I somehow
just have Info files installed that do not match my actual locate
variant.

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

	 The problem with `locate'
       to refer to the executable program of that name is that it creates a
       link to the _Emacs_ command locate, creating even more confusion.

   We should suppress the link in that case.  Does this patch do it?

It still produces a link, in the sense that it will show the docstring
of the function `locate' if you hit RET on the `locate' in
"program `locate'", but at least, after the patch, the word `locate'
is no longer underlined.

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

Here is my latest suggested patch.  It also gives `locate-get-file-positions'
a docstring, since there are situations in which a user may have to
change this function.  The one added code change just gives a better
error message if a user invokes `locate-find-directory-other-window'
on a line with no file, or inside an inserted subdirectory, where the
function does not work.

===File ~/locate-diff=======================================
*** locate.el	06 Feb 2006 16:01:50 -0600	1.35
--- locate.el	14 Mar 2006 23:14:00 -0600	
***************
*** 122,128 ****
    :group 'external)
  
  (defcustom locate-command "locate"
!   "*The executable program used to search a database of files."
    :type 'string
    :group 'locate)
  
--- 122,147 ----
    :group 'external)
  
  (defcustom locate-command "locate"
!   "Executable program for searching a database of files.
! The Emacs commands `locate' and `locate-with-filter' use this.
! The value should be a program that can be called from a shell
! with one argument, SEARCH-STRING.  The program determines which
! database it searches.  The output of the program should consist
! of those file names in the database that match SEARCH-STRING,
! listed one per line, possibly with leading or trailing
! whitespace.  If the output is in another form, you may have to
! redefine the function `locate-get-file-positions'.
! 
! The program may interpret SEARCH-STRING as a literal string, a
! shell pattern or a regular expression.  The exact rules of what
! constitutes a match may also depend on the program.
! 
! The standard value of this variable is \"locate\".
! This program normally searches a database of all files on your
! system, or of all files that you have access to.  Consult the
! documentation of that program for the details about how it determines
! which file names match SEARCH-STRING.  (Those details vary highly with
! the version.)"
    :type 'string
    :group 'locate)
  
***************
*** 133,139 ****
    "The history list used by the \\[locate-with-filter] command.")
  
  (defcustom locate-make-command-line 'locate-default-make-command-line
!   "*Function used to create the locate command line."
    :type 'function
    :group 'locate)
  
--- 152,163 ----
    "The history list used by the \\[locate-with-filter] command.")
  
  (defcustom locate-make-command-line 'locate-default-make-command-line
!   "Function used to create the locate command line.
! The Emacs commands `locate' and `locate-with-filter' use this.
! This function should take one argument, a string (the name to find)
! and return a list of strings.  The first element of the list should be
! the name of a command to be executed by a shell, the remaining elements
! should be the arguments to that command (including the name to find)."
    :type 'function
    :group 'locate)
  
***************
*** 143,149 ****
    :group 'locate)
  
  (defcustom locate-fcodes-file nil
!   "*File name for the database of file names."
    :type '(choice (const :tag "None" nil) file)
    :group 'locate)
  
--- 167,180 ----
    :group 'locate)
  
  (defcustom locate-fcodes-file nil
!   "File name for the database of file names used by `locate'.
! If non-nil, `locate' uses this name in the header of the `*Locate*'
! buffer.  If nil, it mentions no file name in that header.
! 
! Just setting this variable does not actually change the database
! that `locate' searches.  The executive program that the Emacs
! function `locate' uses, as given by the variables `locate-command'
! or `locate-make-command-line', determines the database."
    :type '(choice (const :tag "None" nil) file)
    :group 'locate)
  
***************
*** 161,172 ****
    :version "22.1")
  
  (defcustom locate-update-command "updatedb"
!   "The command used to update the locate database."
    :type 'string
    :group 'locate)
  
  (defcustom locate-prompt-for-command nil
!   "If non-nil, the locate command prompts for a command to run.
  Otherwise, that behavior is invoked via a prefix argument."
    :group 'locate
    :type 'boolean
--- 192,203 ----
    :version "22.1")
  
  (defcustom locate-update-command "updatedb"
!   "The executable program used to update the locate database."
    :type 'string
    :group 'locate)
  
  (defcustom locate-prompt-for-command nil
!   "If non-nil, the `locate' command prompts for a command to run.
  Otherwise, that behavior is invoked via a prefix argument."
    :group 'locate
    :type 'boolean
***************
*** 191,197 ****
  ;;;###autoload
  (defun locate (search-string &optional filter)
    "Run the program `locate', putting results in `*Locate*' buffer.
! With prefix arg, prompt for the locate command to run."
    (interactive
        (list
         (if (or (and current-prefix-arg
--- 222,243 ----
  ;;;###autoload
  (defun locate (search-string &optional filter)
    "Run the program `locate', putting results in `*Locate*' buffer.
! Pass it SEARCH-STRING as argument.  Interactively, prompt for SEARCH_STRING.
! With prefix arg, prompt for the exact shell command to run instead.
! 
! This program searches for those file names in a database that match
! SEARCH-STRING and normally outputs all matching absolute file names,
! one per line.  The database normally consists of all files on your
! system, or of all files that you have access to.  Consult the
! documentation of the program for the details about how it determines
! which file names match SEARCH-STRING.  (Those details vary highly with
! the version.)
! 
! You can specify another program for this command to run by customizing
! the variables `locate-command' or `locate-make-command-line'.
! 
! The main use of FILTER is to implement `locate-with-filter'.  See
! the docstring of that function for its meaning."
    (interactive
        (list
         (if (or (and current-prefix-arg
***************
*** 255,264 ****
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run the locate command with a filter.
  
! The filter is a regular expression. Only results matching the filter are
! shown; this is often useful to constrain a big search."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
--- 301,317 ----
  
  ;;;###autoload
  (defun locate-with-filter (search-string filter)
!   "Run the executable program `locate' with a filter.
! This function is similar to the function `locate', which see.
! The difference is that, when invoked interactively, the present function
! prompts for both SEARCH-STRING and FILTER.  It passes SEARCH-STRING
! to the locate executable program.  It produces a `*Locate*' buffer
! that lists only those lines in the output of the locate program that
! contain a match for the regular expression FILTER; this is often useful
! to constrain a big search.
  
! When called from Lisp, this function is identical with `locate',
! except that FILTER is not optional."
    (interactive
     (list (read-from-minibuffer "Locate: " nil nil
  			       nil 'locate-history-list)
***************
*** 269,275 ****
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (delete-non-matching-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
--- 322,328 ----
  (defun locate-filter-output (filter)
    "Filter output from the locate command."
    (goto-char (point-min))
!   (keep-lines filter))
  
  (defvar locate-mode-map nil
    "Local keymap for Locate mode buffers.")
***************
*** 303,308 ****
--- 356,370 ----
    "The amount of indentation for each file.")
  
  (defun locate-get-file-positions ()
+   "Return list of start and end of the file name on the current line.
+ This is a list of two buffer positions.
+ 
+ You should only call this function on lines that contain a file name
+ listed by the locate program.  Inside inserted subdirectories, or if
+ there is no file name on the current line, the return value is
+ meaningless.  You can check whether the current line contains a file
+ listed by the locate program, using the function
+ `locate-main-listing-line-p'."
    (save-excursion
      (end-of-line)
      (let ((eol (point)))
***************
*** 320,325 ****
--- 382,393 ----
  	 1
         0)))
  
+ ;; You should only call this function on lines that contain a file name
+ ;; listed by the locate program.  Inside inserted subdirectories, or if
+ ;; there is no file name on the current line, the return value is
+ ;; meaningless.  You can check whether the current line contains a file
+ ;; listed by the locate program, using the function
+ ;; `locate-main-listing-line-p'.
  (defun locate-get-filename ()
    (let ((pos    (locate-get-file-positions))
  	(lineno (locate-current-line-number)))
***************
*** 516,523 ****
  (defun locate-find-directory-other-window ()
    "Visit the directory of the file named on this line in other window."
    (interactive)
!   (find-file-other-window (locate-get-dirname)))
  
  (defun locate-get-dirname ()
    "Return the directory name of the file mentioned on this line."
    (let (file (filepos (locate-get-file-positions)))
--- 584,599 ----
  (defun locate-find-directory-other-window ()
    "Visit the directory of the file named on this line in other window."
    (interactive)
!   (if (locate-main-listing-line-p)
!       (find-file-other-window (locate-get-dirname))
!     (message "This command only works inside main listing.")))
  
+ ;; You should only call this function on lines that contain a file name
+ ;; listed by the locate program.  Inside inserted subdirectories, or if
+ ;; there is no file name on the current line, the return value is
+ ;; meaningless.  You can check whether the current line contains a file
+ ;; listed by the locate program, using the function
+ ;; `locate-main-listing-line-p'.
  (defun locate-get-dirname ()
    "Return the directory name of the file mentioned on this line."
    (let (file (filepos (locate-get-file-positions)))
============================================================

Re: locate-with-filter

[Luc Teirlinck]

>From my previous message:

	    The problem with `locate'
	  to refer to the executable program of that name is that it creates a
	  link to the _Emacs_ command locate, creating even more confusion.

      We should suppress the link in that case.  Does this patch do it?

   It still produces a link, in the sense that it will show the docstring
   of the function `locate' if you hit RET on the `locate' in
   "program `locate'", but at least, after the patch, the word `locate'
   is no longer underlined.

Actually, the fact that it still produces a link is just a special
case of the fact that apparently _every_ word in a docstring, whether
quoted or not, is a link if you click the mouse or press RET on it, as
long as it is the name of a Lisp function, variable or face.  For
instance if you click the mouse or press RET on any of the words
"and, or, not, when, if, while" and so on in a docstring, whether
quoted or not, you go to the doc of the corresponding Lisp function.

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

>From my previous message:

   Actually, the fact that it still produces a link is just a special
   case of the fact that apparently _every_ word in a docstring, whether
   quoted or not, is a link if you click the mouse or press RET on it, as
   long as it is the name of a Lisp function, variable or face.  For
   instance if you click the mouse or press RET on any of the words
   "and, or, not, when, if, while" and so on in a docstring, whether
   quoted or not, you go to the doc of the corresponding Lisp function.

Actually, with "clicking the mouse" I meant mouse-2.

Sincerely,

Luc.

Re: locate-with-filter

[Richard Stallman]

    It still produces a link, in the sense that it will show the docstring
    of the function `locate' if you hit RET on the `locate' in
    "program `locate'"

Why is that?  Can you debug it?

Re: locate-with-filter

[Richard Stallman]

This patch is good.  Please install it.

Thanks for working on this.

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

       It still produces a link, in the sense that it will show the docstring
       of the function `locate' if you hit RET on the `locate' in
       "program `locate'"

   Why is that?  Can you debug it?

It seems to be a result of a feature that, I believe, Stefan
implemented whereby, in a docstring, RET or Mouse-2 lead to the doc of
anything that has a definition as a Lisp variable, face or function,
regardless of whether it is quoted.  So if you do RET on say
"and, or, when, if, not", even if non-quoted and even if used as plain
English words instead of Lisp symbols, you get the doc of the
corresponding Lisp function.  In particular, this is true of the word
locate.

Sincerely,

Luc.

Re: locate-with-filter

[Richard Stallman]

    It seems to be a result of a feature that, I believe, Stefan
    implemented whereby, in a docstring, RET or Mouse-2 lead to the doc of
    anything that has a definition as a Lisp variable, face or function,
    regardless of whether it is quoted.

But isn't that feature also controlled by words that appear before the
symbol name?  For instance, if it says "the variable `foo'", the link
will use the variable definition, not the function definition.  We
should be able to change that code so that "the program `foo'" does
not operate as a link.

Where is that code?

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

       It seems to be a result of a feature that, I believe, Stefan
       implemented whereby, in a docstring, RET or Mouse-2 lead to the doc of
       anything that has a definition as a Lisp variable, face or function,
       regardless of whether it is quoted.

   But isn't that feature also controlled by words that appear before the
   symbol name?

No, it works completely unconditionally, as long as the symbol under
point is a variable, function or face.

   Where is that code?

`help-follow' in help-mode.el.

   For instance, if it says "the variable `foo'", the link
   will use the variable definition, not the function definition.  We
   should be able to change that code so that "the program `foo'" does
   not operate as a link.

I believe that it would make little sense, given the _completely_
unconditional nature of the feature.  For instance, if your above
quote were part of a docstring, `help-follow' would follow links to
the Elisp function `not' when using RET or mouse-2 on the `not' in
"not the function definition" and in "not operate as a link".

I must say that I personally do not like that feature.  Fortunately,
at least it does not follow those dubious links on mouse-1.

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

In my previous reply, I forgot to mention that the docstrings of
`help-follow' and `help-make-xrefs' are out of date.  The same may be
true for other docstrings referring to `help-follow'.

`help-follow' docstring:

  Follow cross-reference at POS, defaulting to point.

  For the cross-reference format, see `help-make-xrefs'.

That is inaccurate.  What `help-follow' does in a Help buffer is check
whether the word under point (or at position POS) is a variable,
function or face and show the corresponding docstring if it is any of
these three.  It does this even if that word is not an xref.  It has
nothing to do with `help-make-xrefs'.  The command that follows
explicit author-intended cross references is `push-button', not `help-follow'.

Beginning of `help-make-xrefs' docstring:

  Parse and hyperlink documentation cross-references in the given buffer.

  Find cross-reference information in a buffer and activate such cross
  references for selection with `help-follow'.

It activates such cross-references for selection with `push-button',
not for selection with `help-follow'.   Quite to the contrary, it
makes sure that the usual RET and mouse-2 bindings for help-follow are
_shadowed_ by `push-button'.

Somewhat counterintuitively, an explicit link never enables a link
that would not be there without the explicit link anyway.  All it does
is make the following of the link more restrictive using various
conventions.

Sincerely,

Luc.

Re: locate-with-filter

[Richard Stallman]

I think we can effectively eliminate help-follow.  It is not used for
following any of the links that are explicitly presented in the doc
string.

So I propose this change:


*** help-mode.el	07 Feb 2006 18:16:11 -0500	1.43
--- help-mode.el	17 Mar 2006 16:30:23 -0500	
*************** Commands:
*** 233,242 ****
    "Label to use by `help-make-xrefs' for the go-back reference.")
  
  (defconst help-xref-symbol-regexp
!   (purecopy (concat "\\(\\<\\(\\(variable\\|option\\)\\|"
! 		    "\\(function\\|command\\)\\|"
! 		    "\\(face\\)\\|"
! 		    "\\(symbol\\)\\|"
  		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
  		    "[ \t\n]+\\)?"
  		    ;; Note starting with word-syntax character:
--- 233,242 ----
    "Label to use by `help-make-xrefs' for the go-back reference.")
  
  (defconst help-xref-symbol-regexp
!   (purecopy (concat "\\(\\<\\(\\(variable\\|option\\)\\|"  ; Link to var
! 		    "\\(function\\|command\\)\\|"          ; Link to function
! 		    "\\(face\\)\\|"			   ; Link to face
! 		    "\\(symbol\\|program\\)\\|"		   ; Don't link
  		    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
  		    "[ \t\n]+\\)?"
  		    ;; Note starting with word-syntax character:
*************** help buffer."
*** 584,598 ****
  \f
  ;; Navigation/hyperlinking with xrefs
  
- (defun help-follow-mouse (click)
-   "Follow the cross-reference that you CLICK on."
-   (interactive "e")
-   (let* ((start (event-start click))
- 	 (window (car start))
- 	 (pos (car (cdr start))))
-     (with-current-buffer (window-buffer window)
-       (help-follow pos))))
- 
  (defun help-xref-go-back (buffer)
    "From BUFFER, go back to previous help buffer text using `help-xref-stack'."
    (let (item position method args)
--- 584,589 ----
*************** a proper [back] button."
*** 627,637 ****
--- 618,637 ----
    (let ((help-xref-following t))
      (apply function args)))
  
+ ;; The doc string is meant to explain what buttons do.
+ (defun help-follow-mouse (click)
+   "Follow the cross-reference that you CLICK on."
+   (interactive "e")
+   (error "No cross-reference here"))
+ 
+ ;; The doc string is meant to explain what buttons do.
  (defun help-follow (&optional pos)
    "Follow cross-reference at POS, defaulting to point.
  
  For the cross-reference format, see `help-make-xrefs'."
    (interactive "d")
+   (error "No cross-reference here"))
+ 
    (unless pos
      (setq pos (point)))
    (unless (push-button pos)

Re: locate-with-filter

[Nick Roberts]

 > I think we can effectively eliminate help-follow.  It is not used for
 > following any of the links that are explicitly presented in the doc
 > string.
 >
 > So I propose this change:

I don't like this change because the current behaviour is useful for links
that aren't explicitly presented in the doc string/value.  I don't find that I
invoke help-follow accidentally, so why remove this functionality?

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: locate-with-filter

[Luc Teirlinck]

Nick Roberts wrote:

   I don't find that I invoke help-follow accidentally, so why remove
   this functionality?

Because it effectively disables features that allow the author of a
docstring to prevent false links from being made.  Without the current
`help-follow' feature, I could precede references to the symbol or
program `locate' with the words `symbol' or (after Richard's patch)
`program' to avoid creating the impression of encouraging people to
take a look at the docstring of the Emacs function `locate' for a more
thorough understanding of what I am explaining.  With the current
`help-follow' feature, doing so is effectively meaningless.

   I don't like this change because the current behaviour is useful for links
   that aren't explicitly presented in the doc string/value.

You can always do `C-h v' or `C-h f" to get the docs of something that
the author did not intend as a link.  If I use the expression
"the program `locate'" in a docstring, thereby deliberately disabling
the link to prevent confusion with the Emacs function, and you want to
read the doc of that Emacs function anyway, for unrelated reasons, you
can always do `C-h f'.

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

   I think we can effectively eliminate help-follow.  It is not used for
   following any of the links that are explicitly presented in the doc
   string.

   So I propose this change:

This looks good, except that there are three problems:

1.  The most obvious problem is that your patch fails to erase part of
    the old help-follow.  Hence, after applying your patch,
    help-mode.el does not compile.  This is, of course, trivial to fix.

2.  After your changes, the CLICK arg to help-follow-mouse and the POS
    arg to help-follow are unused and hence should be deleted.  Then
    CLICK should no longer be capitalized in the docstring of
    `help-follow-mouse' and the doc of `help-follow' should no longer
    mention POS.  I suggest:

;; The doc string is meant to explain what buttons do.
(defun help-follow-mouse ()
  "Follow the cross-reference that you click on."
  (interactive)
  (error "No cross-reference here"))

;; The doc string is meant to explain what buttons do.
(defun help-follow ()
  "Follow cross-reference at point.

For the cross-reference format, see `help-make-xrefs'."
  (interactive)
  (error "No cross-reference here"))

3. help-follow is not only bound to RET and mouse-2, but also to `C-c C-c'.
   The `C-c C-c' binding is _not_ shadowed by xrefs.  Hence, `C-c C-c'
   gives the error message "No cross-reference here", everywhere,
   including on xrefs.  Hence, either the `C-c C-c' binding should be
   deletted, or, alternatively, the _old_ help-follow could be renamed
   to `help-follow-word' and `C-c C-c' could be bound to
   `help-follow-word' in help buffers.  If we do the latter, people
   who like the feature can still use it and they can even rebind it
   to RET if they prefer the old behavior.

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

>From my earlier message:

   or, alternatively, the _old_ help-follow could be renamed to
   `help-follow-word' and `C-c C-c' could be bound to
   `help-follow-word' in help buffers.

If we would do that, `help-follow-symbol' would seem a better name
than `help-follow-word'.

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

Nick Roberts wrote:

    > You can always do `C-h v' or `C-h f" to get the docs of something that
    > the author did not intend as a link.

   Yes I could but its not quite as convenient.

One alternative I proposed in another message was to rename the old
help-follow to help-follow-symbol, change the docstring to reflect the
actual behavior, and bind it to `C-c C-c'.  Anybody who prefers the
old behavior can then easily rebind help-follow-symbol to RET.  The
feature is only helpful to advanced users anyway who know how to bind
keys.  But the current RET and mouse-2 bindings are just _way_ too
confusing.  They "feel" like a bug, even though they were implemented
intentionally.

Sincerely,

Luc.

Re: locate-with-filter

[Nick Roberts]

 >    I don't find that I invoke help-follow accidentally, so why remove
 >    this functionality?
 > 
 > Because it effectively disables features that allow the author of a
 > docstring to prevent false links from being made.  

I can see the logic of changing help-xref-symbol-regexp: Emacs shouldn't
underline inappropriate links.  However, if the user still wants to follow a
keyword thats not underlined, that should be his choice.

 >                                                    Without the current
 > `help-follow' feature, I could precede references to the symbol or
 > program `locate' with the words `symbol' or (after Richard's patch)
 > `program' to avoid creating the impression of encouraging people to
 > take a look at the docstring of the Emacs function `locate' for a more
 > thorough understanding of what I am explaining.  With the current
 > `help-follow' feature, doing so is effectively meaningless.

Clearly with `locate' the link leads nowhere but in other cases, the value of
a variable e.g features, say, where all explicit/underlined links have been
removed, some keywords may be of interest.  Emacs generally gives you enough
rope to hang yourself and I like it that way.

 >    I don't like this change because the current behaviour is useful for links
 >    that aren't explicitly presented in the doc string/value.
 > 
 > You can always do `C-h v' or `C-h f" to get the docs of something that
 > the author did not intend as a link.

Yes I could but its not quite as convenient.

 >                                               If I use the expression
 > "the program `locate'" in a docstring, thereby deliberately disabling
 > the link to prevent confusion with the Emacs function, and you want to
 > read the doc of that Emacs function anyway, for unrelated reasons, you
 > can always do `C-h f'.

Yes.  I'm sure `you're doing it for my own good'.

-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: locate-with-filter

[Luc Teirlinck]

Nick Roberts wrote:

    > You can always do `C-h v' or `C-h f" to get the docs of something that
    > the author did not intend as a link.

   Yes I could but its not quite as convenient.

Below is the function that, after Richard's changes, could be bound to
`C-c C-c' (in help-mode) and that anybody could rebind to RET.  It only
differs from the current `help-follow' in that it does not contain:

  (unless (push-button pos)

so that it _consistently_ lists _all_ docs for the symbol under point.
So in "the variable `auto-revert-mode'", with point on
auto-revert-mode,  `C-c C-c' would differ from RET in that it would
show all docs for the symbol, whereas RET only shows the variable doc.

Together with Richard's changes this more clearly separates two
distinct functionalities, that are currently confusingly lumped
together: author intended links serving as guidance to the user
(followed by the new help-follow), and allowing the user to
conveniently access all docs for a symbol that happens to be in the
help buffer, even accidentally as the `or' in the "function or face"
in the docstring below (followed by help-follow-symbol).

(defun help-follow-symbol (&optional pos)
  "In help buffer, show docs for symbol at POS, defaulting to point.
Show all docstrings for that symbol as either a variable, function or face."
  (interactive "d")
  (unless pos
    (setq pos (point)))
  ;; check if the symbol under point is a function, variable or face
  (let ((sym
	 (intern
	  (save-excursion
	    (goto-char pos) (skip-syntax-backward "w_")
	    (buffer-substring (point)
			      (progn (skip-syntax-forward "w_")
				     (point)))))))
    (when (or (boundp sym)
	      (get sym 'variable-documentation)
	      (fboundp sym) (facep sym))
      (help-do-xref pos #'help-xref-interned (list sym)))))

Re: locate-with-filter

[Luc Teirlinck]

>From my previous message:

   Below is the function that, after Richard's changes, could be bound to
   `C-c C-c' (in help-mode) and that anybody could rebind to RET.  It only
   differs from the current `help-follow' in that it does not contain:

     (unless (push-button pos)

Well, eliminating that one line makes rebinding `help-follow-symbol'
to RET less convenient, because without that line the function
help-follow-symbol when applied, for instance, to the `customize' in

You can customize this variable.

would produce the docstring of the function `customize', instead of a
customization buffer.  This is actually an advantage if
help-follow-symbol has the separate binding `C-c C-c' (which is very
convenient to type anyway), and it would make the `C-c C-c'
functionality very consistent.

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

>From my previous message:

	(unless (push-button pos)

   Well, eliminating that one line makes rebinding `help-follow-symbol'
   to RET less convenient, because without that line the function
   help-follow-symbol when applied, for instance, to the `customize' in

   You can customize this variable.

   would produce the docstring of the function `customize', instead of a
   customization buffer.

No, I was confused.  `C-c C-c' would show the docstring of the
function customize, as it should, because the user typed `C-c C-c' and
not RET.  _ However_, if you rebind `help-follow-symbol' to RET instead
of `C-c C-c' then the `push-button' binding for RET shadows the
`help-follow-symbol' binding and you _do_ get a customization buffer.
So this seems to yield the best of both worlds.

Sincerely,

Luc.

Re: locate-with-filter

[Richard Stallman]

    I don't like this change because the current behaviour is useful for links
    that aren't explicitly presented in the doc string/value.

That seems like an unusual case.  Can you give me an example
of where this is useful?

Re: locate-with-filter

[Nick Roberts]

 >     I don't like this change because the current behaviour is useful for
 >     links that aren't explicitly presented in the doc string/value.
 > 
 > That seems like an unusual case.  Can you give me an example
 > of where this is useful?

When looking at the value of any variable e.g auto-mode-alist all explicit
links have been deliberately removed because some were inappropriate
e.g those for `features'.


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: locate-with-filter

[Luc Teirlinck]

Nick Roberts wrote:

   When looking at the value of any variable e.g auto-mode-alist all explicit
   links have been deliberately removed because some were inappropriate
   e.g those for `features'.

As I already said, allowing the user to follow such unplanned "links"
conveniently (although `C-h f' is not actually that inconvenient for
occasional use of the type you describe) is a different functionality
from deliberate links intended as guidance to the user.  With the
alternate change I proposed, you could still follow these links with
`C-c C-c' or, you could keep the old behavior by rebinding
`help-follow-symbol' to RET.  Unlike what I said in the last message
that actually arrived on emacs-devel, rebinding `help-follow-symbol'
to RET _would_ restore the old behavior _exactly_, even with the
"(unless (push-button pos)" removed.  I explained why in a follow up
message that may or may not still arrive.  (It is because the
`push-button' binding for RET shadows the `help-follow-symbol' binding
whenever that line would make a difference.  `push-button' does not
shadow `C-c C-c'.)

The code that implements author intended links goes through quite some
effort to avoid presenting the user with documentation that might be
(sometimes very) confusing.  The present `help-follow' does not and
thereby completely ruins these efforts.

Here is one example of the _many_ ways that the present help-follow
can confuse the user in ways that it no longer will after Richard's
change.  If you currently press RET on the unquoted word function or
on the word function in "the symbol `function'", you get told that
function is a variable with value `help-xref-interned' and if you do
the same for pos instead of function, you get told that pos is a
variable with _some_ concrete integer value.  These are the values
that `function' and `pos' are dynamically bound to while the present
help-follow is being called.  The code called by actual buttons
carefully tries to avoid this, as well as various other sources of
confusion.  At present, to no avail.  The present `help-follow'
overrides it.

The present `help-follow' is meant for experienced Elisp programmers
who will not get confused by stuff like this.

Sincerely,

Luc.

Re: locate-with-filter

[Richard Stallman]

I like your proposal.  Would you please install the corrected version
of my patch, and your new function help-follow-symbol for C-c C-c?

Please also document C-c C-c in Help Mode in help.texi.
It is currently not documented.

Re: locate-with-filter

[Nick Roberts]

Luc Teirlinck writes:
 > Nick Roberts wrote:
 > 
 >    When looking at the value of any variable e.g auto-mode-alist all explicit
 >    links have been deliberately removed because some were inappropriate
 >    e.g those for `features'.
 > 
 > As I already said, allowing the user to follow such unplanned "links"
 > conveniently (although `C-h f' is not actually that inconvenient for
 > occasional use of the type you describe) is a different functionality
 > from deliberate links intended as guidance to the user.  With the
 > alternate change I proposed,...

Richard just asked for an example where the current behaviour is useful.  That
was the the context of my reply.  If the old behaviour is kept thats good, if
not then so be it.


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

   Would you please install the corrected version
   of my patch, and your new function help-follow-symbol for C-c C-c?

   Please also document C-c C-c in Help Mode in help.texi.
   It is currently not documented.

Done.  I also updated lispref/tips.texi.

While grepping, I noticed problems with `list-faces-display' and
`list-character-sets'.  These say: "Use <mouse-2> or M-x help-follow"
in their introductory text, even though `M-x help-follow' is bound to
RET in these buffers.  I am not sure, but this could be due to
`minor-mode-overriding-map-alist'.  This is even worse than it
appears, because with the latest version of `help-follow',
`M-x help-follow' does not even follow references.  It just
incorrectly messages "No cross-reference here" _everywhere_.  With the
latest version of `help-follow', rebinding help-follow to something
different from RET does not work anymore, so we might as well hard
code RET in the doc.

It might actually be good to make `M-x help-follow' work correctly on
references again, by restoring part of the old `help-follow-mouse' and
`help-follow' code.  This would allow binding them to other keys than
mouse-{1,2} or RET.  The patch to help-mode.el below does that.
It entirely keeps the new behavior.  The only difference is that
`M-x help-follow' would once again work on cross references and that
it could be rebound.  I believe that it would not solve the above
problems with `list-faces-display' and `list-character-sets' so I
suggest to just hard code RET in those docs.  The patches below do
this.  I can install if desired.

===File ~/help-mode-diff====================================
*** help-mode.el	19 Mar 2006 17:03:47 -0600	1.44
--- help-mode.el	19 Mar 2006 21:45:44 -0600	
***************
*** 619,636 ****
      (apply function args)))
  
  ;; The doc string is meant to explain what buttons do.
! (defun help-follow-mouse ()
!   "Follow the cross-reference that you click on."
!   (interactive)
!   (error "No cross-reference here"))
  
  ;; The doc string is meant to explain what buttons do.
! (defun help-follow ()
!   "Follow cross-reference at point.
  
  For the cross-reference format, see `help-make-xrefs'."
!   (interactive)
!   (error "No cross-reference here"))
  
  (defun help-follow-symbol (&optional pos)
    "In help buffer, show docs for symbol at POS, defaulting to point.
--- 619,643 ----
      (apply function args)))
  
  ;; The doc string is meant to explain what buttons do.
! (defun help-follow-mouse (click)
!   "Follow the cross-reference that you CLICK on."
!   (interactive "e")
!   (let* ((start (event-start click))
!  	 (window (car start))
!  	 (pos (car (cdr start))))
!     (with-current-buffer (window-buffer window)
!       (help-follow pos))))
  
  ;; The doc string is meant to explain what buttons do.
! (defun help-follow (&optional pos)
!   "Follow cross-reference at POS, defaulting to point.
  
  For the cross-reference format, see `help-make-xrefs'."
!   (interactive "d")
!   (unless pos
!     (setq pos (point)))
!   (unless (push-button pos)
!     (error "No cross-reference here")))
  
  (defun help-follow-symbol (&optional pos)
    "In help buffer, show docs for symbol at POS, defaulting to point.
============================================================

===File ~/faces-diff========================================
*** faces.el	06 Feb 2006 16:01:46 -0600	1.348
--- faces.el	19 Mar 2006 21:21:23 -0600	
***************
*** 1205,1211 ****
  	  (concat
  	   "Use "
  	   (if (display-mouse-p) "\\[help-follow-mouse] or ")
! 	   "\\[help-follow] on a face name to customize it\n"
  	   "or on its sample text for a description of the face.\n\n")))
  	(setq help-xref-stack nil)
  	(dolist (face faces)
--- 1205,1211 ----
  	  (concat
  	   "Use "
  	   (if (display-mouse-p) "\\[help-follow-mouse] or ")
! 	   "RET on a face name to customize it\n"
  	   "or on its sample text for a description of the face.\n\n")))
  	(setq help-xref-stack nil)
  	(dolist (face faces)
============================================================

===File ~/mule-dialog-diff==================================
*** mule-diag.el	24 Sep 2005 09:35:46 -0500	1.98
--- mule-diag.el	19 Mar 2006 21:19:26 -0600	
***************
*** 162,168 ****
  	 (substitute-command-keys
  	  (concat "Use "
  		  (if (display-mouse-p) "\\[help-follow-mouse] or ")
! 		  "\\[help-follow]:\n")))
  	(insert "  on a column title to sort by that title,")
  	(indent-to 56)
  	(insert "+----DIMENSION\n")
--- 162,168 ----
  	 (substitute-command-keys
  	  (concat "Use "
  		  (if (display-mouse-p) "\\[help-follow-mouse] or ")
! 		  "RET:\n")))
  	(insert "  on a column title to sort by that title,")
  	(indent-to 56)
  	(insert "+----DIMENSION\n")
============================================================

Re: locate-with-filter

[Stefan Monnier]

>     It seems to be a result of a feature that, I believe, Stefan
>     implemented whereby, in a docstring, RET or Mouse-2 lead to the doc of
>     anything that has a definition as a Lisp variable, face or function,
>     regardless of whether it is quoted.

> But isn't that feature also controlled by words that appear before the
> symbol name?  For instance, if it says "the variable `foo'", the link
> will use the variable definition, not the function definition.

No, it will show both the function and the variable definition (if both
exist).

It was mostly meant to be used on variable *values* (e.g. hooks), as well as
for docstrings which fail to use the `...'  convention.


        Stefan

Re: locate-with-filter

[Richard Stallman]

    When looking at the value of any variable e.g auto-mode-alist all explicit
    links have been deliberately removed because some were inappropriate
    e.g those for `features'.

Ok, I see what you mean now.

I think that Luc's idea of using C-c C-c for those should work ok.
However, we could also treat the value specially in a different manner.
We could make RET and Mouse-2 equivalent to C-c C-c, but only in the value.

Re: locate-with-filter

[Richard Stallman]

    While grepping, I noticed problems with `list-faces-display' and
    `list-character-sets'.  These say: "Use <mouse-2> or M-x help-follow"
    in their introductory text, even though `M-x help-follow' is bound to
    RET in these buffers.

How about making them use help-follow-symbol instead of help-follow?
Wouldn't that make them work right?

    It might actually be good to make `M-x help-follow' work correctly on
    references again, by restoring part of the old `help-follow-mouse' and
    `help-follow' code.  This would allow binding them to other keys than
    mouse-{1,2} or RET.  The patch to help-mode.el below does that.
    It entirely keeps the new behavior.  The only difference is that
    `M-x help-follow' would once again work on cross references and that
    it could be rebound.

I do not understand this proposal at all.  help-follow now does
exactly the right thing for help buffers: it has a useful doc string
but it always gets an error.  I don't see why we should change that.
If some other mode wants a different command, make a different command
for it.



So why not use help-follow-symbol?

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

   How about making them use help-follow-symbol instead of help-follow?
   Wouldn't that make them work right?

mouse-2 and RET _are_ working right in these buffers.  That is not the
problem.  The problem is that the introductory text says to use
`M-x help-follow', whereas it should be saying to use RET.
The problem is that the "\\[help-follow]" in the docs is not working
right, probably because of the use of `minor-mode-overriding-map-alist'.
That is why I suggested to simply hardcode RET in the docstring and
that is what my two last patches do.

   I do not understand this proposal at all.  help-follow now does
   exactly the right thing for help buffers: it has a useful doc string
   but it always gets an error.  I don't see why we should change that.
   If some other mode wants a different command, make a different command
   for it.

I was not concerned with some other mode wanting a different command.
I was concerned with a user wanting to bind help-follow to a different
key than RET.  With the current code, this will not work.  After my
latest patch to help-mode.el it would work.  But maybe this is not
important enough to worry about.  Anyway, if the user quite simply
can not rebind help-follow to anything but RET, then there definitely
would be no problem with hardcoding RET in the two docs I was talking
about.

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

       While grepping, I noticed problems with `list-faces-display' and
       `list-character-sets'.  These say: "Use <mouse-2> or M-x help-follow"
       in their introductory text, even though `M-x help-follow' is bound to
       RET in these buffers.

   How about making them use help-follow-symbol instead of help-follow?
   Wouldn't that make them work right?

No because `help-follow-symbol' does not follow buttons.  It always
displays any available docs, even if the buttons do something
completely unrelated, as is the case with many buttons in the buffers
in question.

The problem is that the "\\[help-follow]" in the docs is not working
right, probably because of the use of
`minor-mode-overriding-map-alist'.  The purpose of \\[...] is to take
user bindings into account.  After the changes you made to
help-follow, binding `help-follow' to anything else but RET does not
work anymore.  Hence, the \\[...] would make no sense even _if_ it
worked correctly.  That is why I suggested to simply hardcode RET in
the docstring and that is what my first two patches below (which I
submitted before) do.  I believe that we must do _something_, because
the current introductory text is quite simply incorrect and misleading.

After these two patches, the only problem that remains is that
rebinding `help-follow' no longer works.  Maybe that problem is not
important enough to worry about.  But I submitted a third patch
(reproduced below) that would fix this problem without any other
change to current behavior.  I could apply that third patch too.  If
not, what about mentioning in the docstrings of `help-follow' and
`help-follow-mouse' that binding them to different keys (than RET or
mouse-{1,2}, respectively) will not work as expected?

Reminder of my patches:

===File ~/faces-diff========================================
*** faces.el	06 Feb 2006 16:01:46 -0600	1.348
--- faces.el	19 Mar 2006 21:21:23 -0600	
***************
*** 1205,1211 ****
  	  (concat
  	   "Use "
  	   (if (display-mouse-p) "\\[help-follow-mouse] or ")
! 	   "\\[help-follow] on a face name to customize it\n"
  	   "or on its sample text for a description of the face.\n\n")))
  	(setq help-xref-stack nil)
  	(dolist (face faces)
--- 1205,1211 ----
  	  (concat
  	   "Use "
  	   (if (display-mouse-p) "\\[help-follow-mouse] or ")
! 	   "RET on a face name to customize it\n"
  	   "or on its sample text for a description of the face.\n\n")))
  	(setq help-xref-stack nil)
  	(dolist (face faces)
============================================================

===File ~/mule-dialog-diff==================================
*** mule-diag.el	24 Sep 2005 09:35:46 -0500	1.98
--- mule-diag.el	19 Mar 2006 21:19:26 -0600	
***************
*** 162,168 ****
  	 (substitute-command-keys
  	  (concat "Use "
  		  (if (display-mouse-p) "\\[help-follow-mouse] or ")
! 		  "\\[help-follow]:\n")))
  	(insert "  on a column title to sort by that title,")
  	(indent-to 56)
  	(insert "+----DIMENSION\n")
--- 162,168 ----
  	 (substitute-command-keys
  	  (concat "Use "
  		  (if (display-mouse-p) "\\[help-follow-mouse] or ")
! 		  "RET:\n")))
  	(insert "  on a column title to sort by that title,")
  	(indent-to 56)
  	(insert "+----DIMENSION\n")
============================================================

===File ~/help-mode-diff====================================
*** help-mode.el	19 Mar 2006 17:03:47 -0600	1.44
--- help-mode.el	19 Mar 2006 21:45:44 -0600	
***************
*** 619,636 ****
      (apply function args)))
  
  ;; The doc string is meant to explain what buttons do.
! (defun help-follow-mouse ()
!   "Follow the cross-reference that you click on."
!   (interactive)
!   (error "No cross-reference here"))
  
  ;; The doc string is meant to explain what buttons do.
! (defun help-follow ()
!   "Follow cross-reference at point.
  
  For the cross-reference format, see `help-make-xrefs'."
!   (interactive)
!   (error "No cross-reference here"))
  
  (defun help-follow-symbol (&optional pos)
    "In help buffer, show docs for symbol at POS, defaulting to point.
--- 619,643 ----
      (apply function args)))
  
  ;; The doc string is meant to explain what buttons do.
! (defun help-follow-mouse (click)
!   "Follow the cross-reference that you CLICK on."
!   (interactive "e")
!   (let* ((start (event-start click))
!  	 (window (car start))
!  	 (pos (car (cdr start))))
!     (with-current-buffer (window-buffer window)
!       (help-follow pos))))
  
  ;; The doc string is meant to explain what buttons do.
! (defun help-follow (&optional pos)
!   "Follow cross-reference at POS, defaulting to point.
  
  For the cross-reference format, see `help-make-xrefs'."
!   (interactive "d")
!   (unless pos
!     (setq pos (point)))
!   (unless (push-button pos)
!     (error "No cross-reference here")))
  
  (defun help-follow-symbol (&optional pos)
    "In help buffer, show docs for symbol at POS, defaulting to point.
============================================================

Re: locate-with-filter

[Richard Stallman]

      After the changes you made to
    help-follow, binding `help-follow' to anything else but RET does not
    work anymore.

Why is that?

	       (if (display-mouse-p) "\\[help-follow-mouse] or ")
    ! 	   "RET on a face name to customize it\n"
	       "or on its sample text for a description of the face.\n\n")))

I don't want to document a bug.

      ;; The doc string is meant to explain what buttons do.
    ! (defun help-follow (&optional pos)
    !   "Follow cross-reference at POS, defaulting to point.

      For the cross-reference format, see `help-make-xrefs'."
    !   (interactive "d")
    !   (unless pos
    !     (setq pos (point)))
    !   (unless (push-button pos)
    !     (error "No cross-reference here")))


This looks like it is putting back the old code that I replaced.  If
so, that would bring back the bug I fixed.  I do not want to do that.
It would be the wrong fix.

If this is different from the old code, would you please tell me the
difference?

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

	 After the changes you made to
       help-follow, binding `help-follow' to anything else but RET does not
       work anymore.

   Why is that?

Because after your changes, `help-follow' is a function that just
unconditionally gives an error message, even when invoked on a button.
Of course, you can bind `help-follow' to any key you want, but when you
type that key in a help buffer, all you get is the error message:
"No cross-reference here", even when you type it with point on a button.

		  (if (display-mouse-p) "\\[help-follow-mouse] or ")
       ! 	   "RET on a face name to customize it\n"
		  "or on its sample text for a description of the face.\n\n")))

   I don't want to document a bug.

If you mean the bug that binding `help-follow' to anything else but RET
does not work, then my third patch fixes that bug.

But RET might still have to be hard coded in the introductory text for
other reasons, explained below, and that is what my first two patches do.

I do not know how to fix the problem with "\\[help-follow]" and
(presumably) `minor-mode-overriding-map-alist', even after applying my
third patch.  But RET actually should be hard coded in that doc.
"\\[help-follow]" gives the binding of `help-follow' in the local map,
that is the binding in effect when _not_ on a button.  But the doc in
question talks about the behavior of RET _on buttons_, which is
determined by the buttons' text properties and has nothing to do with
the local map.  So "\\help-follow" is an incorrect construct here.

After my third patch `M-x help-follow' would indeed work on buttons,
so the introductory text would no longer be incorrect.  But why
encourage the user to type `M-x help-follow', whereas the much more
convenient RET binding is available?  Note that RET will work on
buttons _even_ if the user bound help-follow to another key _and_
bound RET to another command in help buffers.  It is implemented by
text properties.  The help echo on the buttons also hard codes RET, so
hard coding RET in the introductory text too would only be consistent.

   This looks like it is putting back the old code that I replaced.  If
   so, that would bring back the bug I fixed.  I do not want to do that.
   It would be the wrong fix.

   If this is different from the old code, would you please tell me the
   difference?

`help-follow' in the old code did whatever `push-button' does when
invoked with point over a button and did what the current
`help-follow-symbol' does when not over a button.  Your changes made
`help-follow' print an error message everywhere.  My patches restore
the old behavior when `help-follow' is invoked over a button, but
print an error message when invoked anywhere else.  The behavior after
my patches is _exactly_ the same as the behavior after your changes,
as long as help-follow is only bound to RET.  But if you bind
`help-follow' to some other key, then the present code prints an error
message _everywhere_ in an help-buffer, whereas after my patches, the
rebound key would behave exactly the same way as RET currently does:
follow the button if on a button, otherwise print an error message,

Sincerely,

Luc.

Re: locate-with-filter

[Richard Stallman]

    Because after your changes, `help-follow' is a function that just
    unconditionally gives an error message, even when invoked on a button.

Right--because it should not get called on a button.  The button
itself takes care of its own commands.  `help-follow' exists only
in case you try to activate a button where there is no button.

    If you mean the bug that binding `help-follow' to anything else but RET
    does not work, then my third patch fixes that bug.

You would have to change the bindings in the button's (text-property)
keymap if you want different commands to operate on the button.

Is that feasible?  Maybe it is not easy for users to find out which
keymap to change in order to change the behavior of the button.  Is it?

    I do not know how to fix the problem with "\\[help-follow]" and
    (presumably) `minor-mode-overriding-map-alist', even after applying my
    third patch.

I am not sure which problem that refers to.

If you mean how to make the help mode's doc string refer to the
button's commands, one way would be to tell it to do lookups in the
button's keymap.

      The behavior after
    my patches is _exactly_ the same as the behavior after your changes,
    as long as help-follow is only bound to RET.

Ok, I see the idea now.

So there are two approaches:

1. Say that users who want to change the behavior of the buttons should
   change the keymap that they use.

2. Install your change in help-follow, and then we can get rid of the
   buttons' text property keymap.

Re: locate-with-filter

[Luc Teirlinck]

Richard Stallman wrote:

   You would have to change the bindings in the button's (text-property)
   keymap if you want different commands to operate on the button.

The user would have to change button-map, but then he would have
changed the bindings for _all_ buttons of _any_ kind, which might not
be what the user wants.  In addition, he would _also_ have to rebind
help-follow.  So this seems hopeless.

   So there are two approaches:

   1. Say that users who want to change the behavior of the buttons should
      change the keymap that they use.

   2. Install your change in help-follow, and then we can get rid of the
      buttons' text property keymap.

The first possibility is very unattractive for the reasons explained above.

Getting rid of the button's keymap means reimplementing help-mode
without using buttons, quite a bit of work for little or no gain.  If
we install my three patches, there is no need to get rid of the
button's RET binding.  Quite to the contrary, it allows to safely hard
code RET in the introductory text, which is what we should be doing
anyway.  The help-echo text hardcodes it too.  So if RET would not
follow buttons any more, the help-echo would be deceiving.

An alternative to my third patch would be to simply delete help-follow
and help-follow-mouse entirely. 

Sincerely,

Luc.

Re: locate-with-filter

[Luc Teirlinck]

Maybe I should clarify that the purpose of my third patch is twofold.
It makes help-follow work as advertised when called from Lisp and it
allows the user to make _additional_ bindings for help-follow and the
button functionality in help-mode, _without_ having to change
button-map, which is a much more far reaching change.

Sincerely,

Luc.