Re: locate-with-filter

[Richard Stallman <rms@gnu.org>]

      (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'.