* update documentation

NEWS

@@ -11,6 +11,10 @@
      wildcards
    - remove --xquery completely; use --output=xquery instead
    - fix progress info in 'mu index'
+   - display the references for a message using the 'r' character (mu find)
+   - remove --summary-len/-k, instead use --summary for mu view and mu find, and
+   - support colorized output for some sub-commands (view and cfind). Disabled
+     by default, use --color to enable, or set env MU_COLORS to non-empty
    - update documentation, add more examples
  
 ** Release 0.9.5 <2011-04-25 Mon>

man/mu-bookmarks.5

@@ -1,4 +1,4 @@
-.TH MU-BOOKMARKS 5 "April 2011" "User Manuals"
+.TH MU-BOOKMARKS 5 "May 2011" "User Manuals"
 
 .SH NAME 
 
@@ -7,10 +7,11 @@ bookmarks \- file with bookmarks (shortcuts) for mu search expressions
 .SH DESCRIPTION
 
 Bookmarks are named shortcuts for search queries. They allow using a
-convenient name for often-used queries.
+convenient name for often-used queries. The bookmarks are are also visible as
+shortcuts in the mu experimental user interfaces, \fImug\fR and \fImug2\fR.
 
 \fBmu\fR supports bookmarks stored in a file called \fBbookmarks\fR in the mu
-home directory (so typically, this would be \fI~/.mu/bookmarks\fR).
+home directory (typically, this would be \fI~/.mu/bookmarks\fR).
 
 The bookmarks file is a typical key=value \fB.ini\fR-file, which is best shown
 by means of an example:

man/mu-cfind.1

@@ -12,14 +12,14 @@ other programs.
 .SH DESCRIPTION
 
 \fBmu cfind\fR is the \fBmu\fR command for finding \fIcontacts\fR (name and
-e-mail address of people who were either the sender or receiver of
+e-mail address of people who were either sender or receiver of mail). There
-mail). There are different output formats available, for importing the
+are different output formats available, for importing the contacts into
-contacts into various tools.
+other programs.
 
 .SH SEARCHING CONTACTS
 
 When you index your messages (see \fBmu index\fR), \fBmu\fR creates a list of
-unique e-mail addresses found, and the accompanying name. In case the same
+unique e-mail addresses found and the accompanying name. In case the same
 e-mail address is used with different names, the most recent non-empty name is
 used.
 
@@ -47,7 +47,7 @@ The regular expressions are Perl-compatible (as per the PCRE-library).
 
 .TP
 \fB\-\-format\fR=\fIplain|mutt-alias|mutt-ab|wl|org-contact|bbdb|csv\fR
-set the output format to the given value. The following are available:
+sets the output format to the given value. The following are available:
 
 .nf
 | --format=   | description                       |
@@ -63,9 +63,9 @@ set the output format to the given value. The following are available:
 
 .SH RETURN VALUE
 
-\fBmu cfind\fR returns 0 upon successful completion; if it the a search was
+\fBmu cfind\fR returns 0 upon successful completion -- that is, at least one
-performed, there needs to be a least one match. Anything else leads to a
+contact was found. Anything else leads to a non-zero return value, for
-non-zero return value, for example:
+example:
 
 .sh
 | code | meaning                        |
@@ -78,14 +78,14 @@ non-zero return value, for example:
 .SH INTEGRATION WITH MUTT
 
 You can use \fBmu cfind\fR as an external address book server for
-\fBmutt\fR. For this to work add the following to your \fImuttrc\fR:
+\fBmutt\fR. For this to work, add the following to your \fImuttrc\fR:
 
 .sh
 set query_command = "mu cfind --format=mutt-ab '%s'"
 .si
 
 Now, in mutt, you can easily search for e-mail address using the
-\fBquery\fR-command, which is by default accessible by pressing \fBQ\fR.
+\fBquery\fR-command, which is (by default) accessible by pressing \fBQ\fR.
 
 
 .SH BUGS
@@ -99,4 +99,7 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 
 .SH "SEE ALSO"
 
-.BR mu(1) mu-index(1) mu-find(1) pcrepattern(3)
+.BR mu(1)
+.BR mu-index(1)
+.BR mu-find(1)
+.BR pcrepattern(3)

man/mu-cleanup.1

@@ -1,4 +1,4 @@
-.TH MU CLEANUP 1 "April 2011" "User Manuals"
+.TH MU CLEANUP 1 "May 2011" "User Manuals"
 
 .SH NAME 
 
@@ -13,7 +13,7 @@ mu cleanup \- clean up the mu database
 \fBcleanup\fR removes messages from the database for which no corresponding
 file can be found in the file system. This is done automatically when running
 \fBmu index\fR (unless \fB\-\-nocleanup\fR was specified), but \fBmu cleanup\fR
-can be used to do the cleanup explicitely.
+can be used to do the cleanup explicitly.
 
 \fBmu cleanup\fR does not remove messages that are outside the currently
 specified Maildir, as long as they still exist. The command only takes global
@@ -24,13 +24,13 @@ options, which are described in the \fBmu (1)\fR man page.
 \fBmu cleanup\fR return 0 upon successful completion. Anything else leads to a
 non-zero return value, for example:
 
-.sh
+.nf
 | code | meaning                        |
 |------+--------------------------------|
 |    0 | ok                             |
 |    1 | general error                  |
 |    4 | database is corrupted          |
-.si
+.fi
 
 .SH BUGS
 
@@ -43,4 +43,6 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 
 .SH "SEE ALSO"
 
-.BR maildir(5) mu-index(1) mu(1)
+.BR maildir(5)
+.BR mu-index(1)
+.BR mu(1)

man/mu-easy.1

@@ -101,12 +101,12 @@ In other words, display messages that are either sent to Julius Caesar
   2008-07-31T21:57:25 EEST John Milton <jm@example.com> Fere libenter homines id quod volunt credunt
 .fi
 
-What if we want to see some of the body of the message?  You can list (parts
+What if we want to see some of the body of the message?  You can get
-of) the message contents by using the --summary-len=\fIn\fR option, which
+a 'summary' of the first lines of the message using the \fI--summary\fR
-will 'summarize' the first \fIn\fR lines of the message:
+option, which will 'summarize' the first \fIn\fR lines of the message:
 
 .nf
-  \fB$ mu find --summary-len=4 napoleon m:/archive\fR 
+  \fB$ mu find --summary napoleon m:/archive\fR 
 .fi
 
 .nf
@@ -154,7 +154,7 @@ a Swedish rock band):
   \fB$ mu find date:20020301..20030831 flag:new nightingale\fR
 .fi
 
-Get all message we got today:
+Get all messages received today:
 .nf
   \fB$ mu find date:today..now\fR
 .fi
@@ -247,4 +247,10 @@ Then, you can use them in \fBmutt\fR if you add something like \fBsource
 Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 
 .SH "SEE ALSO"
-mu(1) mu-index(1) mu-cleanup(1) mu-find(1) mu-mkdir(1) mu-view(1) mu-extract(1)
+.BR mu(1)
+.BR mu-index(1)
+.BR mu-cleanup(1)
+.BR mu-find(1)
+.BR mu-mkdir(1)
+.BR mu-view(1)
+.BR mu-extract(1)

man/mu-extract.1

@@ -2,7 +2,8 @@
 
 .SH NAME 
 
-mu extract\- display and save message parts (attachments)
+mu extract\- display and save message parts (attachments), and open them with
+other tools.
 
 .SH SYNOPSIS
 
@@ -13,11 +14,12 @@ mu extract\- display and save message parts (attachments)
 
 \fBmu extact\fR is the \fBmu\fR sub-command for extracting MIME-parts (e.g.,
 attachments) from mail messages. It works on message files, and does not
-require the message to be indexed.
+require the message to be indexed in the database.
 
-For attachments, the file name used for saving is the name of the attachment
+For attachments, the file name used when saving it, is the name of the
-in the message. If there is no such name, or when saving other MIME-parts, a
+attachment in the message. If there is no such name, or when saving
-name is derived from the message-id of the message.
+non-attachment MIME-parts, a name is derived from the message-id of the
+message.
 
 If you specify a pattern (a case-insensitive regular expression) as the second
 argument, all attachments with filenames matching that pattern will be
@@ -76,6 +78,12 @@ To extract all files ending in '.jpg' (case-insensitive):
    $ mu extract msgfile '.*\.jpg'
 .fi
 
+To extract an mp3-file, and play it in the the default mp3-playing application
+(requires \fIxdg-open\fR): 
+.nf
+   $ mu extract --play msgfile 'whoopsididitagain.mp3'
+.fi
+
 .SH BUGS
 
 Please report bugs if you find them:

man/mu-find.1

@@ -328,9 +328,8 @@ 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\-k\fR, \fB\-\-summary\-len\fR=\fI<len>\fR
+\fB\-\-summary\fR
-output a summary based on up to \fI\len\fR lines of the message. The default
+output a summary based upon the first lines of the message.
-is \fB0\fR: no summary at all.
 
 .TP
 \fB\-\-format\fR=\fIplain|links|xquery|xml|json|sexp\fR

man/mu-index.1

@@ -1,4 +1,4 @@
-.TH MU-INDEX 1 "January 2011" "User Manuals"
+.TH MU-INDEX 1 "May 2011" "User Manuals"
 
 .SH NAME 
 
@@ -22,8 +22,9 @@ it understands recursive Maildirs (Maildirs within Maildirs), Maildir++. It
 can also deal with VFAT-based Maildirs which use '!' as the seperators instead
 of ':' as used by \fITinymail\fR/\fIModest\fR and some other e-mail programs.
 
-E-mail messages which are not stored in something resembling a maildir leaf
+E-mail messages which are not stored in something resembling a maildir
-directory (\fIcur\fR and \fInew\fR) are ignored.
+leaf-directory (\fIcur\fR and \fInew\fR) are ignored, as are the cache
+directories for \fInotmuch\fR and \fIgnus\fR.
 
 Symlinks are not followed.
 
@@ -172,14 +173,15 @@ been specified explicitly with \fB\-\-maildir\fR=\fI<maildir>\fR. If
 .SH RETURN VALUE
 \fBmu index\fR return 0 upon successful completion, and any other number
 greater than 2 signals an error, for example:
-.sh
+
+.nf
 | code | meaning                        |
 |------+--------------------------------|
 |    0 | ok                             |
 |    1 | general error                  |
 |    3 | could not obtain db write lock |
 |    4 | database is corrupted          |
-.si
+.fi
 
 .SH BUGS
 
@@ -192,4 +194,6 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 
 .SH "SEE ALSO"
 
-.BR maildir(5) mu(1) mu-find(1)
+.BR maildir(5)
+.BR mu(1)
+.BR mu-find(1)

man/mu-mkdir.1

@@ -1,4 +1,4 @@
-.TH MU MKDIR 1 "November 2010" "User Manuals"
+.TH MU MKDIR 1 "May 2011" "User Manuals"
 
 .SH NAME 
 
@@ -10,7 +10,7 @@ mu mkdir\-  create a new Maildir
 
 .SH DESCRIPTION
 
-\fBmu mkdir\fR is the \fBmu\fR command for creating Maildirs. It does
+\fBmu mkdir\fR is the \fBmu\fR sub-command for creating Maildirs. It does
 \fBnot\fR use the mu database. With the \fBmkdir\fR command, you can create
 new Maildirs with permissions 0755. For example,
 
@@ -18,7 +18,7 @@ new Maildirs with permissions 0755. For example,
    mu mkdir tom dick harry
 .fi
 
-will create three Maildirs, \fItom\fR, \fIdick\fR and \fIharry\fR.
+creates three Maildirs, \fItom\fR, \fIdick\fR and \fIharry\fR.
 
 If creation fails for whatever reason, \fBno\fR attempt is made to remove any
 parts that were created. This is for safety reasons.

man/mu-view.1

@@ -1,4 +1,4 @@
-.TH MU VIEW 1 "November 2010" "User Manuals"
+.TH MU VIEW 1 "May 2011" "User Manuals"
 
 .SH NAME 
 
@@ -10,19 +10,20 @@ mu view\- display an e-mail message file
 
 .SH DESCRIPTION
 
-\fBview\fR is the \fBmu\fR command for displaying an e-mail message file. It
+\fBview\fR is the \fBmu\fR sub-command for displaying an e-mail message
-works on message files and does \fInot\fR require the message to be indexed in
+file. It works on message files and does \fInot\fR require the message to be
-the mu database.
+indexed in the database.
 
-The command shows some common headers (From:, To:, Cc:, Subject: and Date:)
+The command shows some common headers (From:, To:, Cc:, Bcc:, Subject: and
-and the plain-text body of the message, if there is any.
+Date:), the list of attachments and the plain-text body of the message (if
+any).
 
 .SH OPTIONS
 
 .TP
-\fB\-k\fR, \fB\-\-summary\-len\fR=\fI<len>\fR
+\fB\-\-summary\fR
-instead of the full message, output a summary based on up to \fIlen\fR lines
+instead of displaying the full message, output a summary based upon the first
-of the message. The default is 0, which means 'show full body'.
+lines of the message.
 
 .SH BUGS
 
@@ -35,4 +36,5 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 
 .SH "SEE ALSO"
 
-.BR mu(1) mu-index(1)
+.BR mu(1)
+.BR mu-index(1)

man/mu.1

@@ -1,9 +1,9 @@
-.TH MU 1 "April 2011" "User Manuals"
+.TH MU 1 "May 2011" "User Manuals"
 
 .SH NAME 
 
-mu \- a set of tools to deal with Maildirs, in particular to index and search
+mu \- a set of tools to deal with Maildirs and message files, in particular to
-e-mail messages.
+index and search e-mail messages.
 
 .SH SYNOPSIS
 
@@ -19,9 +19,9 @@ e-mail messages.
 
 .B mu mkdir [options] <dir> [<dirs>]
 
-.B mu extract [options] <file> [<parts>]
+.B mu extract [options] <file> [<parts>] [<regexp>]
 
-.B mu cfind [options] [<expr>]
+.B mu cfind [options] [<regexp>]
 
 
 .SH DESCRIPTION
@@ -78,7 +78,6 @@ and exporting the results in various formats for use in other programs.
 .BR mu-cfind(1)
 \.
 
-
 .TP
 \fBview\fR
 for displaying e-mail messages. See
@@ -97,8 +96,20 @@ for extract MIME-parts (such as attachments) from messages. See
 .BR mu-extract(1)
 \.
 
+.SH COLORS
 
-.SH COMMANDS
+Some \fBmu\fR sub-commands support colorized output. By default, this is
+disabled, but you can use the \fI--color\fR/ option to enable it. Even that,
+colors will only shown when output goes to a sufficiently capable terminal
+(this roughly mirrors the \fI--color=auto\fR of the GNU-version of the
+\fBls\fR-command).
+
+Instead of the \fI--color\fR/, you can also set the \fBMU_COLORS\fR environment
+variable to non-empty to enable colors.
+
+Currently. only \fBmu view\fR and \fBmu cfind\fB support colors.
+
+.SH DATABASE AND FILE
 
 Commands \fBmu index\fR, \fBfind\fR and \fBcleanup\fR work with the database,
 while the other ones work on invidual mail files. Hence, running \fview\fR,
@@ -159,5 +170,12 @@ Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>
 
 .SH "SEE ALSO"
 
-.BR mu-index(1) mu-cleanup(1) mu-find(1) mu-cfind(1) mu-mkdir(1) mu-view(1)
+.BR mu-index(1)
-.BR mu-extract(1) mu-easy(1) mu-bookmarks(5) 
+.BR mu-cleanup(1)
+.BR mu-find(1)
+.BR mu-cfind(1)
+.BR mu-mkdir(1)
+.BR mu-view(1)
+.BR mu-extract(1)
+.BR mu-easy(1)
+.BR mu-bookmarks(5) 

www/cheatsheet.org

@@ -24,6 +24,7 @@
   directories with spam-messages), put a file called =.noindex= in the directory
   to exlude, and it will be ignored when indexing (including its children)
   
+
 ** Finding messages
 
    After you have indexed your messages, you can search them. Here are some
@@ -53,6 +54,8 @@
    $ mu find 'subject:soc*' flag:unread
 #+end_src
     
+
+
 ** Find contacts
    
    Contacts (names + email addresses) are cached separately, and can be