Ubuntu Manpage: mhfixmsg - rewrite MIME messages with various transformations

NAME

       mhfixmsg - rewrite MIME messages with various transformations

SYNOPSIS

       mhfixmsg [+folder] [msgs | absolute pathname | -file file] [-decodetext 8bit/7bit |
            -nodecodetext] [-textcharset charset | -notextcharset] [-reformat | -noreformat]
            [-replacetextplain | -noreplacetextplain] [-fixboundary | -nofixboundary] [-fixcte |
            -nofixcte] [-outfile outfile] [-rmmproc program] [-normmproc] [-verbose | -noverbose]
            [-version] [-help]

DESCRIPTION

mhfixmsg rewrites MIME messages, applying specific transformations such as decoding of
MIME-encoded message parts and repairing invalid MIME headers.

MIME messages are specified in RFC 2045 to RFC 2049 (see mhbuild(1)). The mhlist command
is invaluable for viewing the content structure of MIME messages. mhfixmsg passes non-
MIME messages through without any transformations. If no transformations apply to a MIME
message, the original message or file is not modified or removed.

The -decodetext switch enables a transformation to decode each base64 and quoted-printable
text message part to the selected 8bit or 7bit encoding. If 7bit is selected for a base64
part but it will only fit 8bit, as defined by RFC 2045, then it will be decoded to 8bit
quoted-printable. Otherwise, if the decoded text would not fit the selected encoding, the
part is not decoded (and a message will be displayed if -verbose is enabled).

When the -decodetext switch is enabled, each carriage return character that precedes a
linefeed character is removed from text parts encoded in ASCII, ISO-8859-x, UTF-8, or
Windows-12xx.

The -textcharset switch specifies that all text/plain parts of the message(s) should be
converted to charset. Charset conversions require that nmh be built with iconv(3); see
the mhparam(1) man page for how determine whether your nmh installation includes that. To
convert text parts other than text/plain, an external program can be used, via the
-reformat switch.

The -reformat switch enables a transformation for text parts in the message. For each
text part that is not text/plain and that does not have a corresponding text/plain in a
multipart/alternative part, mhfixmsg looks for a mhfixmsg-format-text/subtype profile
entry that matches the subtype of the part. If one is found and can be used to
successfully convert the part to text/plain, mhfixmsg inserts that text/plain part at the
beginning of the containing multipart/alternative part, if present. If not, it creates a
multipart/alternative part.

The -replacetextplain switch broadens the applicability of -reformat by always replacing a
corresponding text/plain part, if one exists. If -verbose if enabled, the replacement
will be shown as two steps: a removal of the text/plain part followed by the usual
insertion of a new part.

-reformat requires a profile entry for each text part subtype to be reformatted. The
mhfixmsg-format-text/subtype profile entries are based on external conversion programs,
and are used the same way that mhshow uses its mhshow-show-text/subtype entries. When nmh
is installed, it searches for a conversion program for text/html content, and if one is
found, inserts a mhfixmsg-format-text/html entry in /etc/nmh/mhn.defaults. An entry of
the same name in the user's profile takes precedence. The user can add entries for other
text subtypes to their profile.

The -fixboundary switch enables a transformation to repair the boundary portion of the
Content-Type header field of the message to match the boundaries of the outermost
multipart part of the message, if it does not. That condition is indicated by a “bogus
multipart content in message” error message from mhlist and other nmh programs that parse
MIME messages.

The -fixcte switch enables a transformation to change the Content-Transfer-Encoding from
an invalid value to 8bit in message parts with a Content-Type of multipart, as required by
RFC 2045, Section 6.4. That condition is indicated by a “must be encoded in 7bit, 8bit,
or binary” error message from mhlist and other nmh programs that parse MIME messages.

The -verbose switch directs mhfixmsg to output informational message for each
transformation applied.

The -file file switch directs mhfixmsg to use the specified file as the source message,
rather than a message from a folder. Only one file argument may be provided. The -file
switch is implied if file is an absolute pathname. If the file is “-”, then mhfixmsg
accepts the source message on the standard input stream. If the -outfile switch is not
enabled when using the standard input stream, mhfixmsg will not produce a transformed
output message.

mhfixmsg, by default, transforms the message in place. If the -outfile switch is enabled,
then mhfixmsg does not modify the input message or file, but instead places its output in
the specified file. An outfile name of “-” specifies the standard output stream.

Combined with the -verbose switch, the -outfile switch can be used to show what
transformations mhfixmsg would apply without actually applying them, e.g.,

mhfixmsg -outfile /dev/null -verbose

As always, this usage obeys any mhfixmsg switches in the user's profile.

-outfile can be combined with rcvstore to add a single transformed message to a different
folder, e.g.,

mhfixmsg -outfile - | \
/usr/lib/mh/rcvstore +folder

Summary of Applicability
The transformations apply to the parts of a message depending on content type and/or
encoding as follows:

-decodetext base64 and quoted-printable encoded text parts
-textcharset text/plain parts
-reformat text parts that are not text/plain
-fixboundary outermost multipart part
-fixcte multipart part

Backup of Original Message/File
If it applies any transformations to a message or file, and the -outfile switch is not
used, mhfixmsg backs up the original the same way as rmm. That is, it uses the rmmproc
profile component, if present. If not present, mhfixmsg moves the original message to a
backup file. The -rmmproc switch may be used to override this profile component. The
-normmproc switch disables the use of any rmmproc profile component and negates all prior
-rmmproc switches.

Integration with inc
mhfixmsg can be used as an add-hook, as described in /usr/share/doc/nmh/README-HOOKS.
Note that add-hooks are called from all nmh programs that add a message to a folder, not
just inc. Alternatively, a simple shell alias or function can be used to call mhfixmsg
immediately after a successful invocation of inc. For example, with bash:

alias inc='inc && mhfixmsg'

Integration with procmail
By way of example, here is an excerpt from a procmailrc file that filters messages through
mhfixmsg before storing them in the user's nmh-workers folder. It also stores the
incoming message in the Backups folder in a filename generated by mktemp, which is a non-
POSIX utility to generate a temporary file. If you do not have that utility, then the
mkstemp(3) function could form the basis for a substitute. Or, mhfixmsg could be called
on the message after it is stored.

PATH = /usr/bin/mh:$PATH
MAILDIR = `mhparam path`
MKTEMP = 'mktemp Backups/mhfixmsg.XXXXXXXX'
MHFIXMSG = 'mhfixmsg -noverbose -file - -outfile -'
STORE = /usr/lib/mh/rcvstore

:0 w: nmh-worker/procmail.$LOCKEXT
* ^TOnmh-workers@nongnu.org
| tee `$MKTEMP` | $MHFIXMSG | $STORE +nmh-workers

FILES

       mhfixmsg  looks  for  mhn.defaults  in multiple locations: absolute pathnames are accessed
       directly, tilde expansion is done on usernames, and files are searched for in  the  user's
       Mail  directory  as  specified  in  their  profile.   If  not  found  there, the directory
       “/etc/nmh” is checked.

       $HOME/.mh_profile      The user profile
       /etc/nmh/mhn.defaults  Default mhfixmsg conversion entries

PROFILE COMPONENTS

       Path:                To determine the user's nmh directory
       Current-Folder:      To find the default current folder
       rmmproc:             Program to delete original messages or files

DEFAULTS

       `+folder' defaults to the current folder
       `msgs' defaults to cur
       `-decodetext 8bit'
       `-notextcharset'
       `-reformat'
       `-noreplacetextplain'
       `-fixboundary'
       `-fixcte'
       `-noverbose'

CONTEXT

       If a folder is given, it will become the current folder.  The last message selected from a
       folder will become the current message.  If the -file switch or an  absolute  pathname  is
       used, the context will not be modified.