From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: Re: locate-with-filter Date: Mon, 13 Mar 2006 20:55:15 -0600 (CST) Message-ID: <200603140255.k2E2tFs05130@raven.dms.auburn.edu> References: <200603122359.k2CNxE111892@raven.dms.auburn.edu> NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1142305276 24325 80.91.229.2 (14 Mar 2006 03:01:16 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 14 Mar 2006 03:01:16 +0000 (UTC) Cc: pbreton@cs.umb.edu, emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Mar 14 04:01:13 2006 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1FIzmP-0002rX-ES for ged-emacs-devel@m.gmane.org; Tue, 14 Mar 2006 04:01:02 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FIzmP-0004sT-1u for ged-emacs-devel@m.gmane.org; Mon, 13 Mar 2006 22:01:01 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1FIzmA-0004sA-QR for emacs-devel@gnu.org; Mon, 13 Mar 2006 22:00:46 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1FIzm8-0004ru-1T for emacs-devel@gnu.org; Mon, 13 Mar 2006 22:00:46 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1FIzm7-0004rg-U4 for emacs-devel@gnu.org; Mon, 13 Mar 2006 22:00:43 -0500 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.52) id 1FIzqA-0003IK-Ph; Mon, 13 Mar 2006 22:04:54 -0500 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.13.3+Sun/8.13.3) with ESMTP id k2E30UCF023968; Mon, 13 Mar 2006 21:00:30 -0600 (CST) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.7p1+Sun/8.11.7) id k2E2tFs05130; Mon, 13 Mar 2006 20:55:15 -0600 (CST) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: rms@gnu.org In-reply-to: (message from Richard Stallman on Mon, 13 Mar 2006 07:55:52 -0500) X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-2.0.1 (manatee.dms.auburn.edu [131.204.53.104]); Mon, 13 Mar 2006 21:00:31 -0600 (CST) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:51585 Archived-At: 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