X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/3f609815e33ab5474e631eac097d515d982ff0f5..36c39624a208467bf2bd1d7155b85edcfc5b07ae:/man/mhfixmsg.man diff --git a/man/mhfixmsg.man b/man/mhfixmsg.man index 84245661..6e148daa 100644 --- a/man/mhfixmsg.man +++ b/man/mhfixmsg.man @@ -1,4 +1,4 @@ -.TH MHFIXMSG %manext1% "February 8, 2015" "%nmhversion%" +.TH MHFIXMSG %manext1% "October 3, 2016" "%nmhversion%" .\" .\" %nmhwarning% .\" @@ -8,14 +8,19 @@ mhfixmsg \- rewrite MIME messages with various transformations .HP 5 .na .B mhfixmsg +.RB [ \-help ] +.RB [ \-version ] .RI [ +folder ] .RI [ msgs " | " .IR "absolute pathname" " | " .RB \-file .IR file ] .RB [ \-decodetext -8bit/7bit | +8bit|7bit|binary | .BR \-nodecodetext ] +.RB [ \-decodetypes +.IR "type/[subtype][,...]" ] +.RB [ \-crlflinebreaks " | " \-nocrlflinebreaks ] .RB [ \-textcharset .I charset .RB "| " \-notextcharset ] @@ -32,8 +37,6 @@ mhfixmsg \- rewrite MIME messages with various transformations .RB [ \-normmproc ] .RB [ \-changecur " | " \-nochangecur ] .RB [ \-verbose " | " \-noverbose ] -.RB [ \-version ] -.RB [ \-help ] .ad .SH DESCRIPTION .B mhfixmsg @@ -51,19 +54,25 @@ messages. .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 +quoted-printable text message part to the selected 8bit, 7bit, or +binary 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 +quoted-printable. +Similarly, with 8bit, 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 @@ -72,6 +81,34 @@ linefeed character is removed from text parts encoded in ASCII, ISO-8859-x, UTF-8, or Windows-12xx. .PP The +.B \-decodetypes +switch specifies the message parts, by type and optionally subtype, +to which +.B \-decodetext +applies. Its argument is a comma-separated list of type/subtype +elements. If an element does not contain a subtype, then +.B \-decodetext +applies to all subtypes of the type. The default is +.B \-decodetypes +.IR text ; +it can be overridden, e.g., with +.B \-decodetypes +.I text/plain +to restrict +.B \-decodetext +to just text/plain parts. +.PP +By default, carriage return characters are preserved or inserted at +the end of each line of text content. The +.B \-crlflinebreaks +switch selects this behavior and is enabled by default. The +.B \-nocrlflinebreaks +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. +.PP +The .B \-textcharset switch specifies that all text/plain parts of the message(s) should be converted to @@ -154,9 +191,9 @@ 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, -Section 6.4. That condition is indicated by a \*(lqmust be encoded in -7bit, 8bit, or binary\*(rq error message from +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 @@ -171,8 +208,12 @@ more descriptive MIME type. It may not be used for multipart and 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 @@ -185,8 +226,10 @@ The return status of 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 @@ -255,16 +298,17 @@ content type and/or encoding as follows: .PP .RS 5 .nf -.ta \w'\-fixboundary 'u -\-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 -\-fixtype all except multipart and message parts +.ta \w'\-crlflinebreaks 'u +\-decodetext base64 and quoted-printable encoded text parts +\-decodetypes limits parts to which -decodetext applies +\-crlflinebreaks text parts +\-textcharset text/plain parts +\-reformat text parts that are not text/plain +\-fixboundary outermost 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 @@ -287,7 +331,6 @@ switch disables the use of any 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. @@ -313,6 +356,7 @@ which 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 @@ -332,6 +376,7 @@ could be called on the message after it is stored. .nf .ta \w'\-fixboundary 'u PATH = %bindir%:$PATH +LANG = en_US.utf8 MAILDIR = `mhparam path` #### The Backups directory is relative to MAILDIR. MKSTEMP = 'mkstemp -directory Backups -prefix mhfixmsg' @@ -343,7 +388,92 @@ STORE = %nmhlibexecdir%/rcvstore | tee `$MKSTEMP` | $MHFIXMSG | $STORE +nmh-workers .fi .RE +.SH "EXAMPLES" +.PP +.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 modifiying it, use the -outfile switch: +.PP +.RS +.nf +mhfixmsg -outfile - | grep \fIpattern\fR +.fi +.RE +.PP +-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, using a Bourne shell loop: +.PP +.RS +.nf +for msg in `pick +folder`; do mhfixmsg $msg; done +.fi +.RE +.PP +.B mhfixmsg +can be run on more than one message, but on a large number of messages +may attempt to open too many files. +.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 the mh\-profile(5) man page. .SH FILES .B mhfixmsg looks for mhn.defaults in multiple locations: absolute pathnames are @@ -387,6 +517,8 @@ is checked. .RB ` +folder "' defaults to the current folder" .RB ` msgs "' defaults to cur" .RB ` "\-decodetext 8bit"' +.RB ` "\-decodetypes text,application/ics"' +.RB ` \-crlflinebreaks ' .RB ` \-notextcharset ' .RB ` \-reformat ' .RB ` \-noreplacetextplain ' @@ -404,3 +536,9 @@ switch is enabled. If the .B \-file switch or an absolute pathname is used, the context will not be modified. +.SH BUGS +.B mhfixmsg +opens files internally for decoding and character set conversion, and apparently does not +close them expeditiously. Until that is resolved, it is recommended that +.B mhfixmsg +not be run on a large number of messages at once, as noted in the EXAMPLES above.