rename project to mblaze

1 files changed, 168 insertions, 0 deletions

diff --git a/man/mblaze.7 b/man/mblaze.7
new file mode 100644
index 0000000..16dd325
--- /dev/null
+++ b/man/mblaze.7
@@ -0,0 +1,168 @@
+.Dd July 22, 2016
+.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 its is a complete implementation from scratch.
+.Pp
+.Nm
+consists of a set of Unix tools that each do one job:
+.Bl -tag -width 11n -compact
+.It Xr maddr 1
+to extract addresses from mail
+.It Xr mcomp 1
+to write and send mail
+.It Xr mdeliver 1
+to deliver messages or import mailboxes
+.It Xr mdirs 1
+to find Maildirs
+.It Xr mflag 1
+to change flags (marks) of mail
+.It Xr mgenmid 1
+to generate Message-IDs
+.It Xr mhdr 1
+to extract mail headers
+.It Xr minc 1
+to incorporate new mail
+.It Xr mless 1
+to conveniently read mail in
+.Xr less 1
+.It Xr mlist 1
+to list and filter mail messages
+.It Xr mmime 1
+to create MIME messages
+.It Xr mpick 1
+to filter mail
+.It Xr mrepl 1
+to reply to mail
+.It Xr mscan 1
+to generate single line summaries of mail
+.It Xr msed 1
+to manipulate mail headers
+.It Xr mseq 1
+to manipulate mail sequences
+.It Xr mshow 1
+to render mail and extract attachments
+.It Xr msort 1
+to sort mail
+.It Xr mthread 1
+to arrange mail into discussions
+.El
+.Sh PRINCIPLES
+.Nm
+is a classic command line MUA with no features related to receiving
+and transferring mail.
+You are expected to fetch your mail using
+.Xr offlineimap 1 ,
+.Xr fdm 1 ,
+.Xr procmail 1 ,
+.Xr getmail 1
+or similar
+and send it using
+.Xr sendmail 8 ,
+as provided by
+OpenSMTPD,
+Postfix,
+.Xr msmtp 1 ,
+.Xr dma 8
+or similar.
+.Nm
+expects your mail to reside in Maildir folders.
+.Pp
+.Nm
+operates directly on Maildir and doesn't use caches or database.
+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 use few syscalls.
+Parsing mail metadata is optimized to use few I/O requests.
+Initial operations on big Maildir may feel slow, but as soon as they
+are in cache, everything is blazing fast.
+The tools are written to be memory efficient (i.e. not wasteful), but
+whole messages are assumed to fit into RAM easily (at a time).
+.Pp
+.Nm
+has been written from scratch and tested on a big pile 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 offlineimap 1 ,
+.Xr mairix 1 ,
+or
+.Xr mu 1 .
+.Sh EXAMPLES
+.Nm
+tools are designed to be composed together into a pipe.
+It is suitable for interactive use and for scripting.
+It integrates 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
+To operate on a set of mails in multiple steps, you can save a list of mail
+as a sequence.
+E.g. add a call to
+.Ql mseq -S
+to above command:
+.Dl mlist -s ~/Maildir/INBOX | msort -d | mseq -S | mscan
+Now mscan will show message numbers and you could look at the first
+five mails at once, for example:
+.Dl mshow 1:5
+Likewise, you could decide to look at all freshly received mail in all
+folders, thread it and look at it interactively:
+.Dl mdirs ~/Maildir | xargs minc | mthread | mless
+Or you could look at the attachments of the 20 largest mails in your INBOX:
+.Dl mlist ~/Maildir/INBOX | msort -s | tail -20 | mshow -t
+Or apply the patches from the current mail:
+.Dl mshow -O . '*.diff' | patch
+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 persisted on disk in
+.Pa ~/.santoku/seq ) ,
+and the current message (kept as a symlink in
+.Pa ~/.santoku/cur ) .
+.Pp
+Messages in the persisted 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.
+.Sh SEE ALSO
+.Xr mailx 1 ,
+.Xr nmh 7
+.Sh AUTHORS
+.An Christian Neukirchen Aq Mt chneukirchen@gmail.com
+.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/