From 5754aeb21a276f420e46cb444d78998e7bed010a Mon Sep 17 00:00:00 2001
From: "Dirk-Jan C. Binnema" <djcb@djcbsoftware.nl>
Date: Fri, 20 May 2011 21:31:46 +0300
Subject: [PATCH] * update documentation for wildcard searches

---
 NEWS               |  4 ++--
 man/mu-easy.1      | 11 +++++++++++
 man/mu-find.1      | 32 ++++++++++++++++++++++++--------
 www/cheatsheet.org |  9 +++++++++
 4 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/NEWS b/NEWS
index 0348c9ee..e9be22ba 100644
--- a/NEWS
+++ b/NEWS
@@ -4,7 +4,7 @@
    
    - FreeBSD build fix
    - fix matching for mu cfind to be as expected
-   -
+   - wildcard searches for all fields (except for path/maildir)
  
 ** Release 0.9.5 <2011-04-25 Mon>
 
@@ -101,7 +101,7 @@
    - A test suite with a growing number of unit tests
 
 
-**  Release 0.6 <2010-01-23 Sat> 
+** Release 0.6 <2010-01-23 Sat> 
     - First new release of mu since 2008
     - No longer depends on sqlite
 
diff --git a/man/mu-easy.1 b/man/mu-easy.1
index dbcc5130..7f2bab1c 100644
--- a/man/mu-easy.1
+++ b/man/mu-easy.1
@@ -164,6 +164,17 @@ Get all message we got in the last two weeks about emacs:
   \fB$ mu find date:2w..now emacs\fR
 .fi
 
+Another powerful feature (since 0.9.6) are wildcard searches, where you can
+search for the last \fIn\fR characters in a word. For example, you can search
+for:
+.nf
+  \fB$ mu find 'subject:soc*'\fR
+.fi
+and get mails about soccer, Socrates, society, and so on. Note, it's important
+to quote the search query, otherwise the shell will interpret
+the '*'.
+
+
 .SH DISPLAYING MESSAGES
 
 We might also want to display the complete messages instead of the header
diff --git a/man/mu-find.1 b/man/mu-find.1
index 6b5f686d..10bcf9ad 100644
--- a/man/mu-find.1
+++ b/man/mu-find.1
@@ -60,7 +60,22 @@ uppercase and lowercase, nor the accented or unaccented versions of
 characters. All match. In general, \fBmu\fR tries to be 'eager' in matching,
 as filtering out unwanted results is usually preferrable over non matching
 messages.
-     
+
+A wildcard search is a search where a \fB*\fR matches the last \fIn\R
+character(s) in some string. The string must always start with one or more
+characters before the wildcards. Since version 0.9.6, \fBmu\fR also supports
+wildcard searches for all fields except maildirs and paths. So, to get all
+mails with a subject containing a word starting with \fBcom\fR, you can use:
+
+.nf
+  $ mu find 'subject:com*'
+.fi
+
+and get mails about computers, comments, compilation and so on. Note, when
+running from the command-line it's import to put the query in quotes,
+otherwise the shell would interpret the '*'.
+
+
 In older versions of mu, queries were logged in \fI<mu-home>/mu.log\fR;
 however, since version 0.9, mu no longer does this.
      
@@ -180,8 +195,8 @@ June 2010, you could use:
   $ mu find date:20090505..20100602 
 .fi
 
-Characters like ':', '/', '-' and single '.' are ignored, so the following is
-equivalent but more readable:
+Non-numeric characters are ignored, so the following is equivalent but more
+readable:
 
 .nf
   $ mu find date:2009-05-05..2010-06-02 
@@ -225,9 +240,10 @@ sent or received today, you could use:
 .fi
 
 The \fBsize\fR or \fBz\fR allows you to match \fIsize ranges\fR -- that is,
-match messages that have a byte-size within a certain range. Units (K (for
-1000) and  M (for 1000 * 1000) are supported). For example to get all messages
-between 10Kb and 2Mb (assuming SI units), you could use:
+match messages that have a byte-size within a certain range. Units (B (for
+bytes), K (for 1000 bytes) and M (for 1000 * 1000 bytes) are supported). For
+example, to get all messages between 10Kb and 2Mb (assuming SI units), you
+could use:
 
 .nf
   $ mu find size:10K..2M
@@ -514,14 +530,14 @@ reason, the below can be an alternative.
 performed, there needs to be a least one match. Anything else leads to a
 non-zero return value, for example:
 
-.sh
+.nf
 | code | meaning                        |
 |------+--------------------------------|
 |    0 | ok                             |
 |    1 | general error                  |
 |    2 | no matches (for 'mu find')     |
 |    4 | database is corrupted          |
-.si
+.fi
 
 .SH BUGS
 
diff --git a/www/cheatsheet.org b/www/cheatsheet.org
index 61470f13..b90875e2 100644
--- a/www/cheatsheet.org
+++ b/www/cheatsheet.org
@@ -46,6 +46,15 @@ Here are some tips for using =mu=. If you want to know more, please refer to the
    $ mu find size:2k..2m date:20091201..20093112 flag:attach from:bill
 #+end_src
  
+*** unread messages about soccer or socrates or ...
+
+#+begin_src sh
+   $ mu find 'subject:soc*' flag:unread
+#+end_src
+
+
+    
+
 ** Further processing of matched messages
 
   If you need to process the results of your queries with some other program,