3.16 MH -- The MH Message Handling System
=========================================
The primary aim of this implementation is to provide an interface
between Mailutils and Emacs using mh-e module.
To use Mailutils MH with Emacs, add the following line to your
site-start.el or .emacs file:
(load "mailutils-mh")
For the information about the current state of Mailutils MH
implementation please refer to file 'mh/TODO' in the Mailutils
distribution directory.
3.16.1 Major differences between Mailutils MH and other MH implementations
--------------------------------------------------------------------------
1. UUCP addresses are not supported;
2. Mailutils supports a set of new format specifications (*note Format
String Diffs::);
3. Mailutils provides a set of new profile variables (*note Profile
Variable Diffs::);
4. All programs recognize '--help' and '--version' options
These options are recognized only if no other arguments are present
in the command line. Abbreviations are not recognized. This makes
Mailutils MH implementation compatible with the standard usage for
GNU tools.
5. Several programs behave differently (*note Program Diffs::);
3.16.1.1 New and Differing MH Format Specifications
...................................................
-- MH Format: string decode (string STR)
Decodes the input string STR as per RFC 2047. Useful in printing
'From:', 'To:' and 'Subject:' headers.
Notice that, unlike the similar NMH function, 'decode' checks the
value of the global profile variable 'Charset' (*note Charset
variable::) to determine the charset to output the result in. If
this variable is not set, 'decode' returns its argument without any
change. If this variable is set to 'auto', 'decode' tries to
determine the charset name from the setting of 'LC_ALL' environment
variable. Otherwise, the value of 'Charset' is taken to be the
name of the character set.
-- MH Format: string package ()
Returns package name (string 'mailutils').
-- MH Format: string package_string ()
Returns full package string (e.g. 'GNU Mailutils 2.1')
-- MH Format: string version ()
Returns mailutils version.
-- MH Format: string unre (string STR)
The function removes any leading whitespace and eventual 'Re:'
prefix from its argument. Useful for creating subjects in reply
messages:
%<{subject}Subject: Re: %(unre{subject})\\n%>
-- MH Format: void reply_regex (string R)
Sets the regular expression used to recognize reply messages. The
argument R should be a POSIX extended regular expression. Matching
is case insensitive.
For example, the following invocation
%(reply_regex ^\(re|aw|ang|odp\)\(\\[[0-9]+\\]\)?:[[:blank:]])
corresponds to English 'Re', Polish 'Odp', Norwegian 'Aw' or German
'Ang', optionally followed by a number in brackets, followed by
colon and any amount of whitespace. Notice proper quoting of the
regex metacharacters.
See also 'Reply-Regex' (*note Reply-Regex variable::) and 'isreply'
(*note isreply MH function::) below.
-- MH Format: boolean isreply ([string STR])
If STR is not given, the value of 'Subject:' header is taken.
The function returns true if its argument matches the "reply
subject" regular expression. This expression is set via the global
profile variable 'Reply-Regex' (*note Reply-Regex variable::) or
via the format function 'reply_regex'.
This function is useful for creating 'Subject:' headers in reply
messages. For example, consider the following construction:
%<{subject}%(lit)%<(isreply)%?\
(profile reply-prefix)%(concat)%|%(concat Re:)%>\
%(concat{subject})%(printhdr Subject: )\n%>
If the 'Subject:' header already contained reply prefix, this
construct leaves it unchanged. Otherwise it prepends to it the
value of 'Reply-Prefix' profile variable, or, if it is unset, the
string 'Re:'.
This expression is used in default 'replcomps' and 'replgroupcomps'
files.
-- MH Format: boolean rcpt ('to' | 'cc' | 'me' | 'all')
This function returns true if the given element is present in the
recipient mask (as modified by '-cc' or '-nocc' options) and false
otherwise. It is used in default formats for 'repl' and 'comp',
e.g.:
%(lit)%<(rcpt to)%(formataddr{to})%>
Notice that this means that usual 'replcomps' file will be ignoring
'-cc' and '-nocc' options, unless it has been modified as shown
above.
-- MH Format: string concat ()
Appends whitespace + arg to string register.
-- MH Format: string printhdr (string STR)
Prints the value of string register, prefixed by STR. The output
is formatted as a RFC 822 header, i.e. it is split at whitespace
characters nearest to the width boundary and each subsequent
segment is prefixed with horizontal tabulation.
-- MH Format: string in_reply_to ()
Generates the value for 'In-reply-to:' header according to RFC
2822.
-- MH Format: string references ()
Generates the value for 'References:' header according to RFC 2822.
3.16.1.2 New MH Profile Variables
.................................
-- Variable: MH Variable string Charset
Controls the character set in which the components decoded via the
'decode' (*note decode function::) format function should be
output.
-- Variable: MH Variable string Reply-Regex
Keeps the regular expression used to recognize reply messages. The
argument should be a POSIX extended regular expression. Matching
is case insensitive.
For more information, please see *Note reply_regex function::.
3.16.1.3 Differences in MH Program Behavior
...........................................
'anno'
The prompt in interactive mode is 'Component name:', instead of
'Enter component name:' displayed by the RAND 'anno'.
If a '-component field' is not specified and standard input is not
connected to a terminal, 'anno' does not display the prompt before
reading the component from the standard input. RAND 'anno'
displays the prompt anyway.
'burst'
The utility is able to burst both RFC 934 digest messages and MIME
multipart messages. It provides two additional command line
options: '-recurse' and '-length'.
The '-recurse' option instructs the utility to recursively expand
the digest.
The '-length' option can be used to set the minimal encapsulation
boundary length for RFC 934 digests. Default length is 1, i.e.
encountering one dash immediately following a newline triggers
digest decoding. It is OK for messages that follow RFC 934
specification. However, many user agents do not precisely follow
it, in particular, they often do not escape lines starting with a
dash by '- ' sequence. 'Mailman' is one of such agents. To cope
with such digests you can set encapsulation boundary length to a
higher value. For example, 'bounce -length 8' has been found to be
sufficient for most Mailman-generated digests.
'comp'
Understands '-build' option.
'fmtdump'
This command is not provided. Use 'fmtcheck' instead.
'inc'
* The '-moveto' option. The '-moveto' option instructs 'inc' to
move messages into another folder after incorporating them.
This option has effect only if the '-truncate' option has also
been specified and the underlying mailbox supports the 'move'
operation. Currently only 'imap' and 'imaps' mailboxes
support it. For example, the following command moves
incorporated messages into the 'archive' folder:
inc -file imaps://imap.gmail.com -moveto=archive
The 'moveto' URL parameter can be used instead of this option,
e.g.:
inc -file 'imaps://imap.gmail.com;moveto=archive'
* Multiple sources Mailutils 'inc' is able to incorporate
messages from several source mailboxes. These are specified
via multiple '-file' options, e.g.:
inc -truncate \
-file 'imaps://imap.gmail.com;moveto=archived' \
-file pops://mail.gnu.org \
-file /var/mail/root
* URL parameters The following additional parameters can be used
in the mailbox URLs supplied with the '-file' option:
'moveto=FOLDER'
Moves incorporated messages into another folder. This
was discussed above.
'nomoveto'
Disables the previous '-moveto' option.
'truncate[=BOOL]'
Controls source mailbox truncation. If BOOL is not given
or it is 'yes', the mailbox will be truncated after
successful processing. If BOOL is 'no', the source
mailbox will not be truncated.
'mhl'
The 'ignores' keyword can be used in variable list. In that case,
if its value contains more than one component name it must be
enclosed in double-quotes, e.g.:
leftadjust,compwidth=9,"ignores=msgid,message-id,received"
The above is equivalent to the following traditional notation:
leftadjust,compwidth=9
ignores=msgid,message-id,received
The 'MessageName' component is not yet implemented.
Interactive prompting is not yet implemented.
The following format variables are silently ignored: 'center',
'split', 'datefield'.
'mhn'
* New option New option '-compose' forces 'mhn' editing mode.
This is also the default mode. This differs from the standard
'mhn', which switches to the editing mode only if no other
options were given and the input file name coincides with the
value of 'mhdraft' environment variable.
* Show mode ('-show') If an appropriate mhn-show-type[/subtype]
was not found, GNU 'mhn' prints the decoded message content
using 'moreproc' variable. Standard 'mhn' in this case used
to print 'don't know how to display content' diagnostic.
The default behaviour is to pipe the content to the standard
input of the mhn-show-type[/subtype] command. This is altered
to using a temporary file if the command contains '%f' or '%F'
escapes.
* Store mode ('-store') If the 'Content-Disposition' header
contains 'filename=', and 'mhn' is invoked with '-auto'
switch, it transforms the file name into the absolute notation
and uses it only if it lies below the current mhn-storage
directory. Standard 'mhn' only requires that the file name do
not begin with '/'.
Before saving a message part, GNU 'mhn' checks if the file
already exists. If so, it asks whether the user wishes to
rewrite it. This behaviour is disabled when '-quiet' option
was given.
'mhparam'
The '-all' mode does not display commented out entries.
'pick'
New command line option '-cflags' allows to control the type of
regular expressions used. The option must occur right before
'--COMPONENT PATTERN' or equivalent construct (like '-cc', '-from',
etc.)
The argument to this option is a string of type specifications:
B Use basic regular expressions
E Use extended regular expressions
I Ignore case
C Case sensitive
Default is 'EI'.
The flags remain in effect until the next occurrence of '-cflags'
option.
Sample usage:
pick -cflag BC -subject '*a string'
The date comparison options ('-before' and '-after' accept date
specifications in a wide variety of formats, e.g.:
pick -after 20030301
pick -after 2003-03-01
pick -after 01-mar-2003
pick -after 2003-mar-01
pick -before '1 year ago'
etc...
'prompter'
1. Prompter attempts to use GNU Readline library, if it is
installed. Consequently, arguments to '-erase' and '-kill'
option must follow GNU style key sequence notation (*note
keyseq: (readline)Readline Init File Syntax.).
If 'prompter' is built without 'readline', it accepts the
following character notations:
\NNNN
Here, N stands for a single octal digit.
^CHR
This notation is translated to the ASCII code 'CHR +
0100'.
2. Component continuation lines are not required to begin with a
whitespace. If leading whitespace is not present, 'prompter'
will add it automatically.
'refile'
1. Linking messages between folders goes against the logic of
Mailutils, so 'refile' never makes links even if called with
'-link' option. The latter is actually a synonym for '-copy',
which preserves the original message.
2. The '-preserve' option is not implemented. It is retained for
backward compatibility only.
3. Message specs and folder names may be interspersed.
'repl'
Understands '-use' option. Disposition shell provides 'use'
command.
'rmm'
1. Different behaviour if one of the messages in the list does
not exist:
Mailutils 'rmm' does not delete any messages. Standard 'rmm'
in this case deletes all messages preceding the non-existent
one.
2. The 'rmm' utility will unlink messages, if the 'rmmproc'
profile component has empty value, e.g.:
rmmproc:
'sortm'
New option '-numfield' specifies numeric comparison for the given
field.
Any number of '-datefield', '-textfield' and '-numfield' options
may be given, thus allowing to build sort criteria of arbitrary
complexity.
The order of '-.*field' options sets the ordering priority. This
differs from the behaviour of the standard 'sortm', which always
orders datefield-major, textfield-minor.
Apart from sorting the mailfolder the following actions may be
specified:
'-list'
List the ordered messages using a format string given by
'-form' or '-format' option.
'-dry-run'
Do not actually sort messages, rather print what would have
been done. This is useful for debugging purposes.