From 236700ecb93bff487499517433b02a33e25de40d Mon Sep 17 00:00:00 2001 From: Christian Neukirchen Date: Mon, 25 Jul 2016 17:07:08 +0200 Subject: [PATCH] add mintro.7 --- man/mintro.7 | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 man/mintro.7 diff --git a/man/mintro.7 b/man/mintro.7 new file mode 100644 index 0000000..478b8ef --- /dev/null +++ b/man/mintro.7 @@ -0,0 +1,164 @@ +.Dd July 22, 2016 +.Dt MINTRO 7 +.Os +.Sh NAME +.Nm mintro +.Nd Santoku introduction +.de N2 +.Nm Santoku +.. +.Sh DESCRIPTION +The +.N2 +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 +.N2 +consists of a set of Unix tools that each do one job: +.Bl -tag -width two-indent -compact +.It Xr maddr 1 +to extract addresses from mail +.It Xr mcomp 1 +to write and send mail +.It Xr mdirs 1 +to find Maildirs +.It Xr mflag 1 +to change flags (marks) of mail +.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 mrepl 1 +to reply to mail +.It Xr mscan 1 +to generate single line summaries of mail +.It Xr mseq 1 +to deal with mail sequences +.It Xr msetseq 1 +to set the mail sequence +.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 +.N2 +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. +.N2 +expects your mail to reside in Maildir folders. +.Pp +.N2 +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 +.N2 +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 +.N2 +is written in portable C, using only POSIX functions (apart from a tiny +Linux-only optimization). +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. +.N2 +works well together with other Unix mail tools such as +.Xr offlineimap 1 , +.Xr mairix 1 , +or +.Xr mu 1 . +.Sh EXAMPLES +.N2 +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 msetseq +to above command: +.Dl mlist -s ~/Maildir/INBOX | msort -d | msetseq | 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 +.N2 +deals with messages (which are files), +folders (which are Maildir folders), +sequences (which are newline-seperated lists of messages, possibly persisted on disk in +.Pa ~/.santoku/map ) , +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 +.N2 +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/