[bug-mailutils] mu-mh manual page

[Pierre-Jean]

Hello alls,

Here is a second version of the mu-mh manual page I sent a few weeks
ago. It reflects the changes recently made by Sergey, should be a bit
easier to read, and fixes some typos and glitches.

Use `man -l mu-mh.man` to read it.

Kind Regards,
Pierre-Jean.

.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH MU-MH 1 2017-05-20 GNU "Gnu Mailutils"
.SH NAME
mu-mh \- mailutils implementation of MH message handling system.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH SYNOPSIS
.PP
Installing:
.BR install-mh .
.PP
Receiving:
.BR inc ,
.BR msgchk .
.PP
Reading:
.BR burst ,
.BR mhl ,
.BR mhn ,
.BR next ,
.BR prev ,
.BR show .
.PP
Composing:
.BR ali ,
.BR comp ,
.BR forw ,
.BR mhn ,
.BR repl ,
.BR whom .
.PP
Sending:
.BR send .
.PP
Disposing:
.BR anno ,
.BR refile ,
.BR rmm .
.PP
Organizing:
.BR folder ,
.BR folders ,
.BR mhpath ,
.BR rmf ,
.BR sortm .
.PP
Searching:
.BR mark ,
.BR mhseq ,
.BR pick ,
.BR scan .
.PP
Varia:
.BR fmtcheck ,
.BR mhparam ,
.BR prompter ,
.BR whatnow .
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH DESCRIPTION
.PP
.B mh
is a message handling system consisting of a collection of
utilities used to receive, compose, send, search and
organize mail files. The core idea of
.B mh
is that mails are local files, managed from the shell.
.B mu-mh
is the
.BR mailutils (1)
implementation of
.BR mh .
It's first aim is to be used as part of
.BR mh-e ,
the
.B Emacs
interface to the
.B mh
mail system.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Installing mu-mh
.PP
If not done yet, the path to the
.B mu-mh utilities
.RI ( @BINDIR@/mu-mh )
must be added to the
.B $PATH
environment variable. Then the
.B install-mh
command asks where to create the directory to
localy store the messages (usually
.IR /home/user/Mail ),
and creates the file
.I .mh_profile
in the user directory.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Configuring mu-mh
.PP
The url of the mailbox can be configured in the file
.IR .mh_profile ,
by adding a line of the form:
.RS
.PP
inc: -file imaps://user:address@hidden
.RE
.PP
The smtp server can be configured in the file
.IR .mtstailor ,
by adding a line of the form
.RS
.PP
url: smtp://user:address@hidden;address@hidden
.RE
.PP
For a longer description of the configurations files, see
the section
.BR CONFIGURATION
below.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Receiving mails
.PP
The command
.B inc
fetches the mails from the distant mailbox, and store them
in the local mail directory.
.B scan
lists the mails present in that directory.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Reading mails
.PP
.B show
.I 1
displays the message named
.RI ' 1 '.
The last message shown is referenced as current
.RI ( cur ,
in the
.B mh
terminology).
.B next
will show the next message, while
.B prev
will show the previous message. These two commands also
reset the message labelled as
.IR cur .
By default, these commands internally use two programs:
.B mhl
to display non-mime messages, and
.B mhn
to display mime messages.
With the
.I -store
option,
.B mhn
can be used to retrieve the various parts of a mime message.
Another option for mime messages is to use
.BR burst ,
which explodes the various parts of a message in several
messages, readable separately.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Composing a mail
.PP
.B comp
opens an editor to compose a new message.
.B forw
and
.B repl
also open an editor, but to forward and reply to an
existing message. By calling the
.B whatnow
program, these three commands will ask the user what to do
next. From there, people can
.B send
the message, or delay that operation.
.PP
To fill the
.RB ' To: '
field of a message, one can use aliases instead of full
addresses. By default, the aliases are stored in the file
.I MailAliases
in the
.I Mail
directory.
.B ali
will list the addresses of a given alias.
.PP
To join a file to a message, ie. to compose a mime message,
one should add, to the content of their message, a line
begining with a
.RI ' # '
and containing the content-type,
optionnaly a name for the file between brackets,
and the path to the file. For example:
.RS
.PP
#application/pdf [filename.pdf] /home/user/doc/file.pdf
.RE
.PP
Once done, the message can be correctly formated by the
command
.BR mhn ,
and sent with
.BR send .
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Disposing of mails
.PP
A mail can be annotated with
.BR anno ,
moved to a directory relative to the local mailbox with
.BR refile ,
or simply removed with
.BR rmm .
None of those two last commands erase the message, they
render it invisible to the
.B mh
tools by prefixing its name with a comma, so that messages
remain recoverable in case of error.
One will have to use
.B rm
to delete those comma prepended messages.
.BR refile ,
for instance, creates a hard link of the message.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Organizing
.PP
.B mh
provides several tools to organize the folders of the
mailbox directory.
.B folder
and
.B folders
change the directory on which the
.B mh
commands operate, create them, or list their content, while
.B rmf
removes them.
.B mhpath
shows the real path of a file, as understood by the shell.
.B sortm
ordonates the messages in a directory, sorting them by
various criteria, numbering and renaming the files
accordingly.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Searching for mails
Most of the
.B mh
commands
accept as argument a sequence of messages. Such a sequence
can be composed by a list of messages separated by space, or
by a range of messages in the form:
.TP
.I name1-name2
all the messages between name1 and name2,
.TP
.I name:n
all the
.I n
messages after name,
.TP
.I name:-n
all the
.I n
messages before name.
.TP
.I name=n
the
.IR n 'th
message after name,
.TP
.I name=-n
the
.IR n 'th
message before name,
.PP
The sequence can contain one of the following
keywords:
.TP
.I first
the first message in the folder,
.TP
.I last
the last message in the folder,
.TP
.I cur
the current message,
.TP
.I prev
the message before
.IR cur ,
.TP
.I next
the message after
.IR cur ,
.TP
.I all
all the messages in the folder.
.PP
.B pick
can be used to search for messages by content. It can search
messages by date, or messages containing
a string in one of their fields (such as
.IR from ,
.IR to ,
.IR subject ,
etc.).
With the
.B -sequence
.I name
option,
.B pick
will put the list of messages in a sequence named
.I name
that can be used by others
.B mh
tools, like
.BR show ,
or
.BR scan ,
to select the messages on which they operate.
.PP
The sequence of messages can be manipulated with
.B mark
and
.BR mhseq .
.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH CONFIGURATION
.PP
The user configuration is located in two files in the user
directory:
.I .mh_profile
for most of the configuration,
.I .mtstailor
where is defined how to send the messages.
Each entry of these files is in the
form:
.RS
.
.PP
.IR entry :
.I value
.RE
.
.PP
Line beginning by a
.RI ' # '
are ignored. Blank lines are not permitted in
.IR .mh_profile .
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS .mtstailor
.PP
The file
.I .mtstailor
contains the configuration needed to send messages. It
accepts the following entries.
.PP
.BR username :
user
.RS
The user part of the user mail address.
.RE
.PP
.BR localname :
example
.RS
The hostname part of the user mail address.
.RE
.PP
.BR localdomain :
com
.RS
The domain part of the user mail address.
.RE
.PP
.BR url :
smtp[s]://[USER[:PASS][;auth=MECH,address@hidden:PORT][;PARAMS]
.RS
The url of the smtp server, where the optional PARAMS is a
semicolon-separated list of parameters. Valid parameters
are:
.IR domain=string ,
.IR from=addr ,
.IR noauth ,
.IR notls ,
.IR recipient-headers=[name[,name...]] ,
.IR strip-domain ,
.IR to=[addr[,addr]] .
See
.B info mailutils
section
.B Mailbox
for a detailed explanation and a complete list of options.
.PP
If not set,
.B mh
will try to use
.B sendmail
to send the messages.
.RE
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS .mh_profile
.PP
The file
.I .mh_profile
contains most of the configuration of
.B mh
tools. It accepts the following entries:
.PP
.IR program :
.I options
.RS
Sets the default options to use when a
.B mh
program is invoked, be it by the user or another
.B mh
program.
.PP
One important program entry is the one used to fetch
messages:
.PP
.na
inc: -file PROTO://[USER[:PASS][;address@hidden:PORT][;notls]
.PP
Where PROTO is one of
.IR pop ,
.IR pops ,
.IR imap ,
.IR imaps ;
and, if PROTO is pop or pops, optional AUTH is
.IR auth=+APOP .
See
.B info mailutils
section
.B Mailbox
for a detailed explanation and a complete list of options.
.RE
.
.PP
.BR Path :
.I Mail
.RS
Directory in which
.B mh
operates. This is the only mandatory entry.
.RE
.
.PP
.BR Current-Folder :
.I inbox
.RS
Folder which
.B mh
tools consider as current folder, and in which they operate
by default.
.RE
.
.PP
.BR Inbox :
.I inbox
.RS
Name of the default inbox, situated under the directory
indicated by the
.I Path
entry.
.RE
.
.PP
.BR Sequence-Negation :
not
.RS
Define the string by which prefixing a sequence to negate it.
.RE
.
.PP
.BR Unseen-Sequence :
unseen
.RS
Names the sequence of unseen messages. Such sequence must
first be created by the command:
.RS
mark -zero -add -sequence unseen
.RE
.RE
.
.PP
.BR mh-sequences:
.I .mh_sequences
.RS
The name of the file in each folder which records the
sequences.
.RE
.
.PP
.BR Editor:
vi
.RS
The editor used to compose and edit messages.
.RE
.
.PP
.BR Folder\-Protect :
.I 700
.RS
The octal permission bits for the folders created by
.BR mh
tools.
.RE
.
.PP
.BR Folder\-Stack :
.RS
.RE
.
.PP
.BR Local\-Mailbox :
address@hidden
.RS
The default user address.
.RE
.
.PP
.BR Alternate\-Mailboxes :
address@hidden, user*
.RS
Lists the adresses belonging to the user, in a way that
.B mh
knows which messages originate from the user.
That allows, for example,
.B repl
to decide which adresses to include in a reply.
.RE
.
.PP
.BR Aliasfile :
.I MailAliases
otherfile
.RS
List the files containing aliases.
.RE
.
.PP
.BR Draft\-Folder :
drafts
.RS
.BR comp ,
.BR forw ,
and
.BR repl
will store their draft in that folder.
If unset, only one draft can be stored at a time, in the file
.IR draft .
.RE
.
.PP
.BR Signature :
firstname lastname
.RS
Define user signature, added to the mail address in the
.I from
field of the sent mails. The
.B $SIGNATURE
environment variable overrides this entry.
.RE
.
.PP
.BR fileproc :
.I refile
.RS
Program used to refile messages.
.RE
.
.PP
.BR mhnproc :
.I mhn
.RS
Program used to show mime messages.
.RE
.PP
.BR moreproc :
.I more
.RS
Program used to page messages. The
.B $PAGER
environment variable overrides this entry.
.RE
.
.PP
.BR sendproc :
.I send
.RS
Program used to send messages.
.RE
.
.PP
.BR showproc :
.I mhn
.RS
Program used to show messages.
.RE
.
.PP
.BR whatnowproc :
.I whatnow
.RS
Program used to query the user.
.RE
.PP
The following entries are not recognized by
.BR mu-mh :
context, previous-sequence, Msg-Protect, datalocking,
MailDrop, Credentials, buildmimeproc, formatproc, incproc,
lproc, mailproc, mhlproc, mshproc, packproc, postproc,
rmmproc, showmimeproc, whomproc.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH ENVIRONMENT
.\" COLUMNS MH CONTEXT PAGER VISUAL EDITOR TERM MTSTAILOR
.\" SIGNATURE mhfolder mhdraft mhaltmsg mheditor mhprompt
.\" mhannotate mhmessage mhinplace
.TP
.B $MH
Location of the
.I mh_profile
file. Defaults to
.I .mh_profile
in the user directory.
.
.TP
.B $MTSTAILOR
location of the
.I mtstailor
file. Defaults to
.I .mtstailor
in the user directory.
.
.TP
.B $CONTEXT
Location of the context file. The default one is
.IR context ,
in the
user's mailbox.
.TP
.B $PAGER
The user's pager.
.TP
.B $VISUAL, $EDITOR
The user's editor.
.TP
.B $SIGNATURE
The user's signature.
.TP
.B $mhfolder
The folder containing the alternate message.
.TP
.B $mhdraft
The path to the working draft.
.TP
.B $mhaltmsg
Used to tell
.I whatnowproc
about an alternate message.
.TP
.B $mheditor
Used to tell
.I whatnowproc
about the user's editor.
.TP
.BR $mhprompt ,
The user's prompt.
.TP
.B $mhannotate, $mhinplace, $mhmessages
Variables set if annotations are to occur.
.SH FILES
.TP
.IR .mh_profile :
The user configuration file.
.TP
.IR .mtstailor :
The mail transport agent configuration file.
.TP
.IR @PREFIX@/share/mailutils/mh/
Location of default configuration files.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH BUGS
.PP
Report bugs to <address@hidden>.
.
.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH "SEE ALSO"
.PP
The full documentation for
.B mailutils mh
is maintained as a Texinfo manuel. If the
.B info
and
.B mailutils
programs are properly installed at your site, the commands
.IP
.B info mailutils
.IP
.B info mh-e
.PP
should give you access to the manuals of mailutils and the
.B Emacs
interface to
.BR mh .
.PP
The book
.URL http://rand-mh.sourceforge.net/book/ "MH & nmh: Email for users and 
programmers" ,
by Jerry Peek, offers a complete documentation of the MH
message handling system.