From ec2c26ed5048b7a1ba18cc94ce2244f744287fde Mon Sep 17 00:00:00 2001 From: "Dirk-Jan C. Binnema" Date: Sat, 16 Jan 2010 15:26:28 +0200 Subject: [PATCH] * mu.1: update man page --- man/mu.1 | 207 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 193 insertions(+), 14 deletions(-) diff --git a/man/mu.1 b/man/mu.1 index 4d4c86ce..d9843df4 100644 --- a/man/mu.1 +++ b/man/mu.1 @@ -137,9 +137,12 @@ information will only be written in batches during the indexing process. The .B find command starts a search for messages in the database that match the search -pattern. The search pattern is taken as a command line parameter. If the -search parameter consists of multiple parts (multiple command line parameters) -they are treated as if there were a logical \fBAND\fR between them. +pattern. Currently, the maximum number of matches for any query is 10,000 +messages. + +The search pattern is taken as a command line parameter. If the search +parameter consists of multiple parts (multiple command line parameters) they +are treated as if there were a logical \fBAND\fR between them. If you want to make your own constructions (using \fBAND\fR, \fBOR\fR, \fBNOT\fR etc., you have to put quote them so \fBmu\fR can consider them as a @@ -148,29 +151,205 @@ unit. \fBmu\fR relies on the Xapian database for its searching capabilities, so it offers all the search functionality that Xapian offers; please refer to: -\fIhttp://xapian.org/docs/queryparser.html\fR + \fIhttp://xapian.org/docs/queryparser.html\fR -Here, we will show the mu-specific ways to specify search patterns. +The basic way to search a message is to type some words matching it, as you +would do in a search engine on the internet, ie. - -.SS find options - -.SS query syntax -In its simplest form, you can just can just specify a number of words, and -\fBmu\fR will search for messages that match all of those words. So, .nf - $ mu find monkey banana + mu find monkey banana +.fi + +will find all message that have both 'monkey' and 'banana'. Matching is +case-insensitive and somewhat intelligent, in that it tries to recognize +various forms of a word (such as plulars); this is all courtesy of Xapina. + +\fBmu\fR also recognizes prefixes for specific fields in a messages; for +example: + +.nf + mu find subject:penguin +.fi + +to find messages with have the word \fBpenguin\fR in the subject field. You +can abbreviate \fBsubject:\fR to just \fBs:\fR. Here is the full table of the +search fields and their abbreviations: + +.nf + cc,c CC (Carbon-Copy) recipient + from,f message sender + path,p full path to the message + subject,s message subject + to,t To: recipient +.fi + + +.SS Find options +The find command has various options that influence the way it outputs its +results. + +.TP +\fB\-f\fR, \fB\-\-fields\fR=\fI\fR +specifies a string that determines which fields are shown in the output. This +string consists of a number of characters (such as 's' for subject or 'f' for +from), which will replace with the actual field in the output. Fields that are +not known will be output as-is, allowing for some simple formatting. + +For example: +.nf + mu find subject:snow --fields "d f s" +.fi +would list the date, subject and sender of all messages with 'snow' in the +their subject. + +The table of replacement characters is superset of the list mentions for +search parameters: + +.nf + c CC (Carbon-Copy) recipient + d the sent-date of the message + f message sender (From:) + F message flags + p full path to the message + P message priority (high, normal, low) + s message subject + t To: recipient +.fi + +The message-flags output is a string, consisting of zero or more of the +following characters. + +.nf + D Draft Message + F Flagged + N New message (in new/ Maildir) + P Passed ('Handled') + R Replied + S Seen + T Marked for deletion + a Has attachment + s Signed message + x Encrypted message +.fi + +Note that these are theoretical flags, which may or may not be actually in +use. + +.TP +\fB\-s\fR, \fB\-\-sortfield\fR \fR=\fI\fR and \fB\-z\fR, \fB\-\-descending\fR +specifies the field to sort the search results by, and the direction. The +following fields are supported: + +.nf + cc,c CC (Carbon-Copy) recipient + date,d message sent date + from,f message sender + path,p full path to the message + prio,P message priority + subject,s message subject + to,t To:-recipient +.fi + +Thus, for example, to sort messages by date, you could specify: + +.nf + mu find fahrrad --fields "d f s" --sortfield=date --descending +.fi + +Note, if you specify a sortfield, by default, they are sorted in descending +order (e.g., from lowest to highest). This is usually a good choice, but for +dates it may be more useful to sort in the opposite direction. + +.TP +\fB\-x\fR, \fB\-\-xquery\fR +shows the Xapian query corresponding to your search terms. This is mostly +useful for debugging. + +.TP +\fB\-l\fR, \fB\-\-linksdir\fR \fR=\fI\fR and \fB\-c\fR, \fB\-\-clearlinks\fR +output the results as a maildir with symbolic links to the found +messages. This enables easy integration with mail-clients (see below for more +information). \fBmu\fR will create the maildir if it does not exist yet. + +If you specify \fB\-\-clearlinks\fR, all existing symlinks will be cleared +from the target maildir; this allows for re-use of the same directory. An +alternative would be to delete the target directory before, but this has a big +chance of accidentaly removing something that should not be removed. + +.nf + mu find grolsch --linksdir=~/Maildir/search --clearlinks +.fi + +will store links to found messages in \fI~/Maildir/search\fR. If the directory +does not exist yet, it will be created. + +Note: when \fBmu\fR creates a Maildir for these links, it automatically +inserts a \fI.noindex\fR file, to exclude the directory from \fBmu +index\fR. + +.SH Integrating mu find with mail clients + +.TP + +\fBmutt\fR +For \fBmutt\fR you can use the following in your \fImuttrc\fR; pressing the F8 +key will start a search, and F9 will take you to the results. + +.nf +############################################################################# +macro index "mu find -c -l ~/Maildir/search " "mu find" +macro index "~/Maildir/search" "display mu find +results" +############################################################################ +.fi + + +.TP + +\fBWanderlust\fR +If you use Wanderlust for \fBemacs\fR, the following definitons can be used; +typing 'Q' will start a query. + +.nf +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; +(defvar mu-wl-mu-program "mu") +(defvar mu-wl-search-folder "search") + +(defun mu-wl-search () + "search a maildir using `mu', and jump to a folder with the +results" + (interactive) + (let* ((muexpr (read-string "Find messages matching: ")) + (sfldr (concat elmo-maildir-folder-path "/" mu-wl-search-folder)) + (cmdline (concat mu-wl-mu-program " find " + "--clearlinks --linksdir='" sfldr "' " muexpr))) + (= 0 (shell-command cmdline)))) + +(defun mu-wl-search-and-goto () + "search and jump to the folder with the results" + (interactive) + + (if (mu-wl-search) + (wl-summary-goto-folder-subr (concat "." mu-wl-search-folder) + 'force-update nil nil t) + (message "Query failed"))) + +(define-key wl-summary-mode-map (kbd "Q") ;; => query + '(lambda()(interactive)(mu-wl-search-and-goto))) +(define-key wl-folder-mode-map (kbd "Q") ;; => query + '(lambda()(interactive)(mu-wl-search-and-goto))) +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; .fi -will find all messages which have both "monkey" AND "banana" in one of those -fields. .SH THE MKDIR COMMAND With the .B mkdir command, you can create new Maildirs with permissions 0755. For example, + .nf mu mkdir tom dick harry .fi + will create three Maildirs \fItom\fR, \fIdick\fR and \fIharry\fR. If the creation somehow fails, for safety reasons, \fBno\fR attempt is made to