diff --git a/NEWS b/NEWS index 8ef467be..9831be9c 100644 --- a/NEWS +++ b/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> diff --git a/man/mu-bookmarks.5 b/man/mu-bookmarks.5 index 3bab519c..bfa8d7ab 100644 --- a/man/mu-bookmarks.5 +++ b/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: diff --git a/man/mu-cfind.1 b/man/mu-cfind.1 index d7775813..58116ae8 100644 --- a/man/mu-cfind.1 +++ b/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 -mail). There are different output formats available, for importing the -contacts into various tools. +e-mail address of people who were either sender or receiver of mail). There +are different output formats available, for importing the contacts into +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 -performed, there needs to be a least one match. Anything else leads to a -non-zero return value, for example: +\fBmu cfind\fR returns 0 upon successful completion -- that is, at least one +contact was found. Anything else leads to a non-zero return value, for +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 .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) diff --git a/man/mu-cleanup.1 b/man/mu-cleanup.1 index d37221b8..bb48ef69 100644 --- a/man/mu-cleanup.1 +++ b/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 .SH "SEE ALSO" -.BR maildir(5) mu-index(1) mu(1) +.BR maildir(5) +.BR mu-index(1) +.BR mu(1) diff --git a/man/mu-easy.1 b/man/mu-easy.1 index b3fafd20..982db99b 100644 --- a/man/mu-easy.1 +++ b/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 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 -of) the message contents by using the --summary-len=\fIn\fR option, which -will 'summarize' the first \fIn\fR lines of the message: +What if we want to see some of the body of the message? You can get +a 'summary' of the first lines of the message using the \fI--summary\fR +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 .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) diff --git a/man/mu-extract.1 b/man/mu-extract.1 index cf788a08..25f6b734 100644 --- a/man/mu-extract.1 +++ b/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 -in the message. If there is no such name, or when saving other MIME-parts, a -name is derived from the message-id of the message. +For attachments, the file name used when saving it, is the name of the +attachment in the message. If there is no such name, or when saving +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: diff --git a/man/mu-find.1 b/man/mu-find.1 index 7857c4ef..a18e98b9 100644 --- a/man/mu-find.1 +++ b/man/mu-find.1 @@ -112,14 +112,14 @@ search fields and their abbreviations: .nf cc,c Cc (carbon-copy) recipient(s) - bcc,h Bcc (blind-carbon-copy) recipient(s) + bcc,h Bcc (blind-carbon-copy) recipient(s) from,f Message sender subject,s Message subject to,t To: recipient(s) maildir,m Maildir msgid,i Message-ID prio,p Message priority ('low', 'normal' or 'high') - flag,g Message Flags + flag,g Message Flags date,d Date-Range size,z Message size attach,a Attachment filename @@ -291,7 +291,7 @@ search parameters; the complete list: s Message \fBs\fRubject i Message-\fBi\fRd m \fBm\fRaildir - r \fBr\fReferences (message ids In-reply-to, References as comma-separated list) + r \fBr\fReferences (message ids In-reply-to, References as comma-separated list) .fi @@ -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\fR -output a summary based on up to \fI\len\fR lines of the message. The default -is \fB0\fR: no summary at all. +\fB\-\-summary\fR +output a summary based upon the first lines of the message. .TP \fB\-\-format\fR=\fIplain|links|xquery|xml|json|sexp\fR diff --git a/man/mu-index.1 b/man/mu-index.1 index 1a00bfb6..751c21d2 100644 --- a/man/mu-index.1 +++ b/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 -directory (\fIcur\fR and \fInew\fR) are ignored. +E-mail messages which are not stored in something resembling a maildir +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\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 .SH "SEE ALSO" -.BR maildir(5) mu(1) mu-find(1) +.BR maildir(5) +.BR mu(1) +.BR mu-find(1) diff --git a/man/mu-mkdir.1 b/man/mu-mkdir.1 index 2f3948d1..825be6eb 100644 --- a/man/mu-mkdir.1 +++ b/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. diff --git a/man/mu-view.1 b/man/mu-view.1 index 68b2ecf2..9f5895f2 100644 --- a/man/mu-view.1 +++ b/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 -works on message files and does \fInot\fR require the message to be indexed in -the mu database. +\fBview\fR is the \fBmu\fR sub-command for displaying an e-mail message +file. It works on message files and does \fInot\fR require the message to be +indexed in the database. -The command shows some common headers (From:, To:, Cc:, Subject: and Date:) -and the plain-text body of the message, if there is any. +The command shows some common headers (From:, To:, Cc:, Bcc:, Subject: and +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\fR -instead of the full message, output a summary based on up to \fIlen\fR lines -of the message. The default is 0, which means 'show full body'. +\fB\-\-summary\fR +instead of displaying the full message, output a summary based upon the first +lines of the message. .SH BUGS @@ -35,4 +36,5 @@ Dirk-Jan C. Binnema .SH "SEE ALSO" -.BR mu(1) mu-index(1) +.BR mu(1) +.BR mu-index(1) diff --git a/man/mu.1 b/man/mu.1 index 9f39df61..774ad964 100644 --- a/man/mu.1 +++ b/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 -e-mail messages. +mu \- a set of tools to deal with Maildirs and message files, in particular to +index and search e-mail messages. .SH SYNOPSIS @@ -19,9 +19,9 @@ e-mail messages. .B mu mkdir [options] [] -.B mu extract [options] [] +.B mu extract [options] [] [] -.B mu cfind [options] [] +.B mu cfind [options] [] .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 .SH "SEE ALSO" -.BR mu-index(1) mu-cleanup(1) mu-find(1) mu-cfind(1) mu-mkdir(1) mu-view(1) -.BR mu-extract(1) mu-easy(1) mu-bookmarks(5) +.BR mu-index(1) +.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) diff --git a/www/cheatsheet.org b/www/cheatsheet.org index cd65c8c6..9bcf2464 100644 --- a/www/cheatsheet.org +++ b/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