-.TH MHFIXMSG %manext1% "February 24, 2016" "%nmhversion%"
-.\"
+.TH MHFIXMSG %manext1% 2016-11-08 "%nmhversion%"
+.
.\" %nmhwarning%
-.\"
+.
.SH NAME
-mhfixmsg \- rewrite MIME messages with various transformations
+mhfixmsg \- nmh's MIME-email rewriter with various transformations
.SH SYNOPSIS
.HP 5
.na
.B mhfixmsg
+.RB [ \-help ]
+.RB [ \-version ]
.RI [ +folder ]
.RI [ msgs " | "
.IR "absolute pathname" " | "
-.RB \-file
+.B \-file
.IR file ]
.RB [ \-decodetext
-8bit/7bit |
+8bit|7bit|binary |
.BR \-nodecodetext ]
.RB [ \-decodetypes
.IR "type/[subtype][,...]" ]
.RB [ \-normmproc ]
.RB [ \-changecur " | " \-nochangecur ]
.RB [ \-verbose " | " \-noverbose ]
-.RB [ \-version ]
-.RB [ \-help ]
.ad
.SH DESCRIPTION
.B mhfixmsg
.B 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.
+is not modified or removed. Thus,
+.B mhfixmsg
+can safely be run multiple times on a message.
.PP
The
.B \-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
+switch enables a transformation to decode each base64 and quoted-printable
+text message part to the selected 8-bit, 7-bit, or
+binary encoding.
+If 7-bit is selected for a base64 part but it will only fit
+8-bit, as defined by RFC 2045, then it will be decoded to 8-bit
+quoted-printable.
+Similarly, with 8-bit, if the decoded text would be binary,
+then the part is not decoded (and a message will be displayed if
.B \-verbose
-is enabled).
+is enabled). Note that
+.B \-decodetext
+binary can produce messages that are not RFC 2045 compliant.
.PP
When the
.B \-decodetext
switch causes carriage return characters to be stripped from, and not
inserted in, text content when it is decoded and encoded. Note that
its use can cause the generation of MIME messages that do not conform
-with RFC 2046, §4.1.1, paragraph 1.
+to RFC 2046, §4.1.1, paragraph 1.
.PP
The
.B \-textcharset
.B nmh
be built with
.IR iconv (3);
-see the
-.BR mhparam (1)
-man page for how determine whether your
+see
+.IR mhparam (1)
+for how determine whether your
.B nmh
installation includes that.
To convert text parts other than text/plain, an external program can
The
.B \-replacetextplain
switch broadens the applicability of
-.B \-reformat
+.BR \-reformat ,
by always replacing a corresponding text/plain part, if one exists.
If
.B \-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.
+is 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.
.PP
.B \-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
+conversion programs, and are used in the same way that
.B mhshow
uses its mhshow-show-text/subtype entries. When
.B nmh
The
.B \-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,
-§6.4. That condition is indicated by a \*(lqmust be encoded in
-7bit, 8bit, or binary\*(rq error message from
+Content-Transfer-Encoding from an invalid value to 8-bit in message
+parts with a Content-Type of multipart and message, as required by
+RFC 2045, §6.4. That condition is indicated by a \*(lqmust be
+encoded in 7bit, 8bit, or binary\*(rq error message from
.B mhlist
and other
.B nmh
message types.
.PP
.B mhfixmsg
-applies one transformation unconditionally: it removes an extraneous
-trailing semicolon from the parameter lists of MIME header fields.
+applies two transformations unconditionally.
+The first removes an extraneous trailing semicolon from the parameter
+lists of MIME header field values.
+The second replaces RFC 2047 encoding with RFC 2231 encoding of name
+and filename parameters in Content-Type and Content-Disposition header
+field values, respectively.
.PP
The
.B \-verbose
is 0 if all of the requested transformations are performed, or
non-zero otherwise.
.RB ( mhfixmsg
-will not decode to binary content, but a request to do so is
-not considered a failure, and is noted with
+will not decode to binary content with the default
+.B \-decodetext
+setting, but a request to do so is not considered a failure, and is noted
+with
.BR \-verbose .)
If a problem is detected with any one of multiple messages such that
the return status is non-zero, then none of the messages will be
.I file
switch directs
.B 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
+to use the specified file as the source message, rather than a message
+from a folder. Only one file argument may be provided. The
.B \-file
switch is implied if
.I file
-is an absolute pathname.
-If the file is \*(lq-\*(rq, then
+is an absolute pathname. If the file is \*(lq-\*(rq, then
.B mhfixmsg
-accepts the source message on the standard input stream. If
-the
+accepts the source message on the standard input stream. If the
.B \-outfile
switch is not enabled when using the standard input stream,
.B mhfixmsg
.ta \w'\-crlflinebreaks 'u
\-decodetext base64 and quoted-printable encoded text parts
\-decodetypes limits parts to which -decodetext applies
-\-crlflinebreaks text parts
+\-crlflinebreaks text parts
\-textcharset text/plain parts
\-reformat text parts that are not text/plain
\-fixboundary outermost multipart part
-\-fixcte multipart part
+\-fixcte multipart or message part
\-fixtype all except multipart and message parts
.fi
.RE
-.PP
.SS "Backup of Original Message/File"
-If it applies any transformations to a message or file,
-and the
+If it applies any transformations to a message or file, and the
.B \-outfile
switch is not used,
.B mhfixmsg
profile component and negates all prior
.B \-rmmproc
switches.
-.PP
.SS "Integration with inc"
.B mhfixmsg
can be used as an add-hook, as described in %docdir%/README-HOOKS.
.B nmh
programs that add a message to a folder, not just
.BR inc .
-Alternatively, a simple shell alias or function can be used to
-call
+Alternatively, a simple shell alias or function can be used to call
.B mhfixmsg
immediately after a successful invocation of
.BR inc .
One approach could be based on:
.PP
.RS 5
-msgs=`inc -format '%(msg)'` && [ -n "$msgs" ] && scan $msgs && \
+msgs=\`inc -format '%(msg)'\` && [ -n "$msgs" ] && scan $msgs && \
mhfixmsg -nochangecur $msgs
.RE
.PP
sets with the newly incorporated messages. Those could then be
supplied to
.BR mhfixmsg .
+An example is shown below.
.SS "Integration with procmail"
By way of example, here is an excerpt from a procmailrc file
that filters messages through
.nf
.ta \w'\-fixboundary 'u
PATH = %bindir%:$PATH
-MAILDIR = `mhparam path`
+LANG = en_US.utf8
+MAILDIR = \`mhparam path\`
#### The Backups directory is relative to MAILDIR.
MKSTEMP = 'mkstemp -directory Backups -prefix mhfixmsg'
MHFIXMSG = 'mhfixmsg -noverbose -file - -outfile -'
:0 w: nmh-workers/procmail.$LOCKEXT
* ^TOnmh-workers@nongnu.org
-| tee `$MKSTEMP` | $MHFIXMSG | $STORE +nmh-workers
+| tee \`$MKSTEMP\` | $MHFIXMSG | $STORE +nmh-workers
+.fi
+.RE
+.SH "EXAMPLES"
+.SS Basic usage
+To run
+.B mhfixmsg
+on the current message in the current folder, with default transformations to
+fix MIME boundaries and Content-Transfer-Encoding, to decode text and
+application/ics content parts to 8 bit, and to add a corresponding text/plain
+part where lacking:
+.PP
+.RS
+.nf
+mhfixmsg -verbose
+.fi
+.RE
+.SS Specified folder and messages
+To run
+.B mhfixmsg
+on specified messages, without its informational output:
+.PP
+.RS
+.nf
+mhfixmsg +inbox last:4
+.fi
+.RE
+.SS View without modification
+By default,
+.B mhfixmsg
+transforms the message in place.
+To view the MIME structure that would result from running
+.B mhfixmsg
+on the current message, without modifying the message:
+.PP
+.RS
+.nf
+mhfixmsg -outfile - | mhlist -file -
+.fi
+.RE
+.SS Search message without modification
+To search the current message, which possibly contains base64
+or quoted printable encoded text parts, without modifying it,
+use the
+.B \-outfile
+switch:
+.PP
+.RS
+.nf
+mhfixmsg -outfile - | grep \fIpattern\fR
+.fi
+.RE
+.PP
+.B \-outfile
+can be abbreviated in usual MH fashion, e.g., to -o. The search will be
+on the entire message, not just text parts.
+.SS Translate text/plain parts to UTF-8
+To translate all text/plain parts in the current message to UTF-8, in addition
+to all of the default transformations:
+.PP
+.RS
+.nf
+mhfixmsg -textcharset utf-8
.fi
.RE
+.SS Fix all messages in a folder
+To run
+.B mhfixmsg
+on all of the messages in a folder:
+.PP
+.RS
+.nf
+mhfixmsg +folder all
+.fi
+.RE
+.PP
+Alternatively,
+.B mhfixmsg
+can be run on each message separately, e.g., using a Bourne shell loop:
.PP
+.RS
+.nf
+for msg in \`pick +folder\`; do mhfixmsg +folder $msg; done
+.fi
+.RE
+.PP
+The two appearances of the
+.B +folder
+switch in that command protect against concurrent context changes by other
+.B nmh
+command invocations.
+.SS Run on newly incorporated messages
+To run
+.B mhfixmsg
+on messages as they are incorporated:
+.PP
+.RS
+.nf
+inc && mhfixmsg -nochangecur unseen
+.fi
+.RE
+.PP
+This assumes that the Unseen-Sequence profile entry is set to
+.BR unseen ,
+as shown in
+.IR mh-profile (5).
.SH FILES
.B mhfixmsg
looks for mhn.defaults in multiple locations: absolute pathnames are
.fc ^ ~
.nf
.ta \w'%nmhetcdir%/mhn.defaults 'u
-^$HOME/\&.mh\(ruprofile~^The user profile
+^$HOME/.mh_profile~^The user profile
^%nmhetcdir%/mhn.defaults~^Default mhfixmsg conversion entries
.fi
.SH "PROFILE COMPONENTS"
^rmmproc:~^Program to delete original messages or files
.fi
.SH "SEE ALSO"
-.IR inc (1),
.IR iconv (3),
+.IR inc (1),
+.IR mh-mkstemp (1),
.IR mh-profile (5),
.IR mhbuild (1),
.IR mhlist (1),
.IR mhparam (1),
.IR mhshow (1),
-.IR mh-mkstemp (1),
.IR procmail (1),
.IR procmailrc (5),
.IR rcvstore (1),
.RB ` +folder "' defaults to the current folder"
.RB ` msgs "' defaults to cur"
.RB ` "\-decodetext 8bit"'
-.RB ` "\-decodetypes text"'
+.RB ` "\-decodetypes text,application/ics"'
.RB ` \-crlflinebreaks '
.RB ` \-notextcharset '
.RB ` \-reformat '
projects / nmh / blobdiff