* mu.1: update man page

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
+pattern. Currently, the maximum number of matches for any query is 10,000
-search parameter consists of multiple parts (multiple command line parameters)
+messages.
-they are treated as if there were a logical \fBAND\fR between them.
+
+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<fields>\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<field>\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<dir>\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 <F8> "<shell-escape>mu find -c -l ~/Maildir/search "  "mu find"
+macro index <F9> "<change-folder-readonly>~/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