* update TODO, documentation (manpages)

TODO

@@ -1,6 +1,6 @@
 * Future release
 
-** release 0.9 [%]
+** release 0.10 [%]
 
    - [ ] mu stats
    - [ ] follow symlinks when indexing
@@ -12,13 +12,13 @@
    - [ ] completion for zsh
    - [ ] don't make test mail files executable
 
-** release 0.9 [71%]
+** release 0.9 [85%]
    - [X] bookmarks
    - [X] gtk-ui for searching
    - [X] clean up mu-msg-field, add formatting(?)
    - [X] normalize search fields
    - [ ] cleanup version check
-   - [ ] fix flag searches + synonyms
+   - [X] fix flag searches + synonyms
    - [X] unbreak cc10/line33
 
 

man/mu-easy.1

@@ -67,7 +67,7 @@ of the date depends on your system locale.
 
 How do we know that the message was sent to Julius Caesar? Well, it's not
 visible from the results above, because the default fields that are shown are
-date-sender-subject. However, we can change this using the \fI--fields\fR
+date/sender/subject. However, we can change this using the \fI--fields\fR
 parameter (see the \fBmu-find\fR man page for the details):
 
 .nf
@@ -80,7 +80,8 @@ return something like:
   Julius Caesar <jc@example.com> Fere libenter homines id quod volunt credunt
 .fi
 
-This is the same message found before, only with some different fields displayed.
+This is the same message found before, only with some different fields
+displayed.
 
 By default, \fBmu\fR uses the logical AND for the search parameters -- that
 is, it displays messages that match all the parameters. However, we can use
@@ -119,6 +120,26 @@ whitespace removed.
 Also note the \fBm:/archive\fR parameter in the query. This means that we only
 match messages in a maildir called '/archive'.
 
+.SH MORE QUERIES
+
+Let's list some more queries that may be interesting:
+
+Get all important messages which are signed:
+.nf
+\fB$ mu find flag:signed prio:high \fR 
+.fi
+
+Get all messages from Jim without an attachment:
+.nf
+\fB$ mu find from:jim AND NOT flag:attach\fR 
+.fi
+
+Get all unread messages about some dance:
+.nf
+\fB$ mu find flag:new subject:tango\fR 
+.fi
+
+
 .SH DISPLAYING MESSAGES
 
 We might also want to display complete messages. This can be done using \fBmu

man/mu-find.1

@@ -68,14 +68,12 @@ if you an explicit search prefix; in other words, if, for example:
 	mu find foo@example.com
 .fi
 
-does not work, 
+might not work, while 
 
 .nf
 	mu find f:foo@example.com
 .fi
-
-might.
-
+does.
 
 As mentioned, matching is case-insensitive and accent-insensitive;
 thus
@@ -104,10 +102,44 @@ search fields and their abbreviations:
 	to,t            To: recipient
 	maildir,m       Maildir	
 	msgid,i         Message-ID
+	prio,p          Message priority ('low', 'normal' or 'high')
+	flag,g		Message Flags
 .fi
 
 For clarity, this man-page uses the longer versions.
 
+The meaning of most of these fields should be clear, but some require some
+extra discusion.
+
+First, the message flags field describes certain properties of the message, as
+listed in the following table:
+.nf
+	d,draft		Draft Message
+	f,flagged	Flagged
+	n,new		New message (in new/ Maildir)
+	p,passed	Passed ('Handled')
+	r,replied	Replied
+	s,seen		Seen
+	t,thrashed	Marked for deletion
+	a,attach	Has attachment
+	z,signed	Signed message
+	x,encrypted	Encrypted message
+.fi
+
+Using this, we can search e.g. for all signed messages that have an
+attachment:
+.nf
+	$ mu find flag:signed flag:attach
+.fi
+
+The message-priority has three possible values: low, normal or high. We can
+match them using 'prio' - for example, to get all high-priority messages with
+a subject containing some bird:
+
+.nf
+	$ mu find prio:high subject:nightingale
+.fi
+
 The Maildir field describes the directory path starting \fBafter\fR the
 Maildir-base path, and before the \fI/cur/\fR or \fI/new/\fR part. So for
 example, if there's a message with the file name
@@ -115,7 +147,7 @@ example, if there's a message with the file name
 other messages in the same maildir) with:
 
 .nf
-	mu find maildir:/lists/running
+	$ mu find maildir:/lists/running
 .fi
 
 Note the starting '/'. If you want to match mails in the 'root' maildir, you
@@ -151,7 +183,7 @@ 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:
+search parameters; the complete list:
 
 .nf
 	t	\fBt\fRo: recipient
@@ -166,25 +198,12 @@ search parameters:
 	m	\fBm\fRaildir
 .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
+The message flags are the same ones we already saw in the message flags
+above. Thus, a message which is 'seen', has an attachment and is signed would
+have 'asz' as its corresponding output string, while an encrypted new message
+would have 'nx'.
 
-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
@@ -287,6 +306,13 @@ Find all messages in the 'Archive' folder from Fred:
   $ mu find from:fred maildir:/Archive
 .fi
 
+Find all messages with attachments:
+
+.nf
+  $ mu find flag:attach
+.fi
+
+
 
 .SS Integrating mu find with mail clients