mblaze/man/mblaze.7

.Dd June 30, 2017
.Dt MBLAZE 7
.Os
.Sh NAME
.Nm mblaze
.Nd introduction to mblaze
.Sh DESCRIPTION
The
.Nm
message system is a set of Unix utilities to deal with
mail kept in Maildir folders.
.Pp
Its design is roughly inspired by MH, the RAND Message Handling
System, but it is a complete implementation from scratch.
.Pp
.Nm
consists of these Unix tools that each do one job:
.Bl -tag -width 11n -compact
.It Xr maddr 1
extract addresses from mail
.It Xr magrep 1
find mails matching a pattern
.It Xr mcom 1
compose and send mail
.It Xr mdeliver 1
deliver messages or import mailboxes
.It Xr mdirs 1
find Maildir folders
.It Xr mexport 1
export Maildir folders as mailboxes
.It Xr mflag 1
change flags (marks) of mail
.It Xr mfwd 1
forward mail
.It Xr mgenmid 1
generate Message-IDs
.It Xr mhdr 1
extract mail headers
.It Xr minc 1
incorporate new mail
.It Xr mless 1
conveniently read mail in
.Xr less 1
.It Xr mlist 1
list and filter mail messages
.It Xr mmime 1
create MIME messages
.It Xr mmkdir 1
create new Maildir
.It Xr mpick 1
advanced mail filter
.It Xr mrep 1
reply to mail
.It Xr mscan 1
generate one-line summaries of mail
.It Xr msed 1
manipulate mail headers
.It Xr mseq 1
manipulate mail sequences
.It Xr mshow 1
render mail and extract attachments
.It Xr msort 1
sort mail
.It Xr mthread 1
arrange mail into discussions
.El
.Sh PRINCIPLES
.Nm
is a classic command line MUA and has no features
for receiving or transferring mail;
you are expected to fetch your mail using
.Xr fdm 1 ,
.Xr getmail 1
.Xr offlineimap 1 ,
.Xr procmail 1 ,
or similar ,
and send it using
.Xr dma 8 ,
.Xr msmtp 1 ,
.Xr sendmail 8 ,
as provided by
OpenSMTPD,
Postfix,
or similar.
.Nm
expects your mail to reside in Maildir folders.
.Pp
.Nm
operates directly on Maildir folders and doesn't
use its own caches or databases.
There is no setup needed for many uses.
All tools have been written with performance in mind.
Enumeration of all mails in a Maildir is avoided unless necessary,
and then optimized to limit syscalls.
Parsing mail metadata is optimized to limit I/O requests.
Initial operations on a large Maildir may feel slow, but as soon as they
are in the file system cache, everything is blazingly fast.
The tools are written to be memory efficient (i.e. not wasteful), but
whole messages are assumed to fit into RAM easily (one at a time).
.Pp
.Nm
has been written from scratch and tested on a large corpus of personal mail,
but is not actually 100% RFC-conforming
(which is neither worth it nor desirable).
There may be issues with very old, nonconforming, messages.
.Pp
.Nm
is written in portable C, using only POSIX functions (apart from a tiny
Linux-only optimization),
and has no external dependencies.
It supports MIME and more than 7-bit messages (everything the host
.Xr iconv 3
can decode).
It assumes you work in a UTF-8 environment.
.Nm
works well together with other Unix mail tools such as
.Xr mairix 1 ,
.Xr mu 1 ,
or
.Xr offlineimap 1 .
.Sh EXAMPLES
.Nm
tools are designed to be composed together in a pipe.
They are suitable for interactive use and for scripting,
and integrate well into a Unix workflow.
.Pp
For example, you could decide you want to look at all unseen mail in your
INBOX, oldest first.
.Dl mlist -s ~/Maildir/INBOX | msort -d | mscan
.Pp
To operate on a set of mails in multiple steps,
you can save it as a sequence,
e.g. add a call to
.Ql mseq -S
to the above command:
.Dl mlist -s ~/Maildir/INBOX | msort -d | mseq -S | mscan
.Pp
Now mscan will show message numbers and you could look at the first
five mails at once, for example:
.Dl mshow 1:5
.Pp
Likewise, you could decide to incorporate (by moving from
.Pa new
to
.Pa cur )
all new mail in all folders,
thread it and look at it interactively:
.Dl mdirs ~/Maildir | xargs minc | mthread | mless
.Pp
Or you could list the attachments of the 20 largest mails in your INBOX:
.Dl mlist ~/Maildir/INBOX | msort -S | tail -20 | mshow -t
.Pp
Or apply the patches from the current mail:
.Dl mshow -O . '*.diff' | patch
.Pp
As usual with pipes, the sky is the limit.
.Sh CONCEPTS
.Nm
deals with messages (which are files),
folders (which are Maildir folders),
sequences (which are newline-separated lists of messages, possibly saved on disk in
.Pa ${MBLAZE:-$HOME/.mblaze}/seq ) ,
and the current message (kept as a symlink in
.Pa ${MBLAZE:-$HOME/.mblaze}/cur ) .
.Pp
Messages in the saved sequence can be referred to using special
syntax as explained in
.Xr mmsg 7 .
.Pp
Many utilities have a default behavior when used interactively from a terminal
(e.g. operate on the current message or the current sequence).
For scripting, you must make these arguments explicit.
.Pp
For configuration, see
.Xr mblaze-profile 5 .
.Sh SEE ALSO
.Xr mailx 1 ,
.Xr mblaze-profile 5 ,
.Xr nmh 7
.Sh AUTHORS
.An Leah Neukirchen Aq Mt leah@vuxu.org
.Pp
There is a mailing list available at
.Mt mblaze@googlegroups.com
(to subscribe, send a mail to
.Mt mblaze+subscribe@googlegroups.com .
Please report security-related bugs directly to the author),
as well as an IRC channel
.Li #vuxu
on irc.freenode.net.
.Sh LICENSE
.Nm
is in the public domain.
.Pp
To the extent possible under law,
the creator of this work
has waived all copyright and related or
neighboring rights to this work.
.Pp
.Lk http://creativecommons.org/publicdomain/zero/1.0/