1 .TH MHFIXMSG %manext1% 2019-03-31 "%nmhversion%"
6 mhfixmsg \- nmh's MIME-email rewriter with various transformations
15 .IR "absolute pathname" " | "
22 .IR "type/[subtype][,...]" ]
23 .RB [ \-decodeheaderfieldbodies
25 .BR \-nodecodeheaderfieldbodies ]
26 .RB [ \-crlflinebreaks " | " \-nocrlflinebreaks ]
29 .RB "| " \-notextcharset ]
30 .RB [ \-reformat " | " \-noreformat ]
31 .RB [ \-replacetextplain " | " \-noreplacetextplain ]
32 .RB [ \-fixboundary " | " \-nofixboundary ]
33 .RB [ \-fixcte " | " \-nofixcte ]
34 .RB [ \-checkbase64 " | " \-nocheckbase64 ]
42 .RB [ \-changecur " | " \-nochangecur ]
43 .RB [ \-verbose " | " \-noverbose ]
47 rewrites MIME messages, applying specific transformations such as
48 decoding of MIME-encoded message parts and repairing invalid MIME
51 MIME messages are specified in RFC 2045 to RFC 2049
56 command is invaluable for viewing the content structure of MIME
59 passes non-MIME messages through without any transformations. If no
60 transformations apply to a MIME message, the original message or file
61 is not modified or removed. Thus,
63 can safely be run multiple times on a message.
67 switch enables a transformation to decode each base64 and quoted-printable
68 text message part to the selected 8-bit, 7-bit, or
70 If 7-bit is selected for a base64 part but it will only fit
71 8-bit, as defined by RFC 2045, then it will be decoded to 8-bit
73 Similarly, with 8-bit, if the decoded text would be binary,
74 then the part is not decoded (and a message will be displayed if
76 is enabled). Note that
78 binary can produce messages that are not compliant with RFC 5322, \(sc2.1.1.
82 switch is enabled, each carriage return character that precedes a
83 linefeed character is removed from text parts encoded in ASCII,
84 ISO-8859-x, UTF-8, or Windows-12xx.
88 switch specifies the message parts, by type and optionally subtype,
91 applies. Its argument is a comma-separated list of type/subtype
92 elements. If an element does not contain a subtype, then
94 applies to all subtypes of the type. The default is
97 it can be overridden, e.g., with
102 to just text/plain parts.
105 .B \-decodeheaderfieldbodies
106 switch enables decoding of UTF-8 header field bodies, when supplied
110 .B \-nodecodeheaderfieldbodies
111 inhibits this transformation. The transformation can produce a message
112 that does not conform with RFC 2047, \(sc1, paragraph 6, because the decoded
113 header field body could contain unencoded non-ASCII characters. It is
114 therefore not enabled by default.
116 By default, carriage return characters are preserved or inserted at
117 the end of each line of text content. The
119 switch selects this behavior and is enabled by default. The
120 .B \-nocrlflinebreaks
121 switch causes carriage return characters to be stripped from, and not
122 inserted in, text content when it is decoded and encoded. Note that
123 its use can cause the generation of MIME messages that do not conform
124 with RFC 2046, \(sc4.1.1, paragraph 1.
128 switch specifies that all text/plain parts of the message(s)
129 should be converted to
131 Charset conversions require that
137 for how determine whether your
139 installation includes that.
140 To convert text parts other than text/plain, an external program can
147 switch enables a transformation for text parts in the message. For
148 each text part that is not text/plain and that does not have a
149 corresponding text/plain in a multipart/alternative part,
151 looks for a mhfixmsg-format-text/subtype profile entry that matches
152 the subtype of the part. If one is found and can be used to
153 successfully convert the part to text/plain,
155 inserts that text/plain part at the beginning of the containing
156 multipart/alternative part, if present. If not, it creates a
157 multipart/alternative part.
161 switch, multipart/related parts are handled differently than
162 multipart/alternative. If the multipart/related has only a single
163 part that is not text/plain and can be converted to text/plain, a
164 text/plain part is added and the type of the part is changed to
165 multipart/alternative. If the multipart/related has more than one
166 part but does not have a text/plain part,
171 .B \-replacetextplain
172 switch broadens the applicability of
174 by always replacing a corresponding text/plain part, if one exists.
177 is enabled, the replacement will be shown as two steps: a removal of
178 the text/plain part, followed by the usual insertion of a new part.
181 requires a profile entry for each text part subtype to be reformatted.
182 The mhfixmsg-format-text/subtype profile entries are based on external
183 conversion programs, and are used in the same way that
185 uses its mhshow-show-text/subtype entries. When
187 is installed, it searches for a conversion program for text/html
188 content, and if one is found, inserts a mhfixmsg-format-text/html
189 entry in %nmhetcdir%/mhn.defaults. An entry of the same name in the
190 user's profile takes precedence. The user can add entries for
191 other text subtypes to their profile.
195 switch enables a transformation to repair the boundary portion of the
196 Content-Type header field of the message to match the boundaries of
197 the outermost multipart part of the message, if it does not. That
198 condition is indicated by a \*(lqbogus multipart content in
199 message\*(rq error message from
203 programs that parse MIME messages.
207 switch enables a transformation to change the
208 Content-Transfer-Encoding from an invalid value to 8-bit in message
209 parts with a Content-Type of multipart and message, as required by
210 RFC 2045, \(sc6.4. That condition is indicated by a \*(lqmust be
211 encoded in 7bit, 8bit, or binary\*(rq error message from
215 programs that parse MIME messages.
219 switch enables a check of the encoding validity in base64-encoded
220 MIME parts. The check looks for a non-encoded text footer appended
221 to a base64-encoded part. Per RFC 2045 \(sc6.8, the occurrence of
222 a "=" character signifies the end of base-64 encoded content. If
223 none is found, a heuristic is used: specifically, two consecutive
224 invalid base64 characters signify the beginning of a plain text
225 footer. If a text footer is found and this switch is enabled,
227 separates the base64-encoded and non-encoded content and places
228 them in a pair of subparts to a newly constructed multipart/mixed
229 part. That multipart/mixed part replaces the original base64-encoded
230 part in the MIME structure of the message.
234 switch ensures that each part of the message has the correct MIME type
235 shown in its Content-Type header. It may be repeated. It is
236 typically used to replace \*(lqapplication/octet-stream\*(rq with a
237 more descriptive MIME type. It may not be used for multipart and
241 applies two transformations unconditionally.
242 The first removes an extraneous trailing semicolon from the parameter
243 lists of MIME header field values.
244 The second replaces RFC 2047 encoding with RFC 2231 encoding of name
245 and filename parameters in Content-Type and Content-Disposition header
246 field values, respectively.
252 to output informational message for each transformation applied.
256 is 0 if all of the requested transformations are performed, or
259 will not decode to binary content with the default
261 setting, but a request to do so is not considered a failure, and is noted
264 If a problem is detected with any one of multiple messages such that
265 the return status is non-zero, then none of the messages will be
273 to use the specified file as the source message, rather than a message
274 from a folder. Only one file argument may be provided. The
278 is an absolute pathname. If the file is \*(lq-\*(rq, then
280 accepts the source message on the standard input stream. If the
282 switch is not enabled when using the standard input stream,
284 will not produce a transformed output message.
287 by default, transforms the message in place. If the
289 switch is enabled, then
291 does not modify the input message or file, but instead places its
292 output in the specified file. An outfile name of \*(lq-\*(rq
293 specifies the standard output stream.
299 switch can be used to show what transformations
301 would apply without actually applying them, e.g.,
304 mhfixmsg -outfile /dev/null -verbose
307 As always, this usage obeys any
309 switches in the user's profile.
314 to add a single transformed message to a different folder, e.g.,
317 mhfixmsg -outfile - | \\
319 %nmhlibexecdir%/rcvstore +folder
322 .SS Summary of Applicability
323 The transformations apply to the parts of a message depending on
324 content type and/or encoding as follows:
328 .ta \w'\-decodeheaderfieldbodies 'u
329 \-decodetext base64 and quoted-printable encoded text parts
330 \-decodetypes limits parts to which -decodetext applies
331 \-decodeheaderfieldbodies all message parts
332 \-crlflinebreaks text parts
333 \-textcharset text/plain parts
334 \-reformat text parts that are not text/plain
335 \-fixboundary outermost multipart part
336 \-fixcte multipart or message part
337 \-checkbase64 base64 encoded parts
338 \-fixtype all except multipart and message parts
341 .SS "Backup of Original Message/File"
342 If it applies any transformations to a message or file, and the
346 backs up the original the same way as
350 profile component, if present. If not present,
352 moves the original message to a backup file.
355 switch may be used to override this profile component. The
357 switch disables the use of any
359 profile component and negates all prior
362 .SS "Integration with inc"
364 can be used as an add-hook, as described in %docdir%/README-HOOKS.
365 Note that add-hooks are called from all
367 programs that add a message to a folder, not just
369 Alternatively, a simple shell alias or function can be used to call
371 immediately after a successful invocation of
373 One approach could be based on:
376 msgs=\`inc -format '%(msg)'\` && [ -n "$msgs" ] && scan $msgs && \
377 mhfixmsg -nochangecur $msgs
380 Another approach would rely on adding a sequence to Unseen-Sequence,
383 sets with the newly incorporated messages. Those could then be
386 An example is shown below.
387 .SS "Integration with procmail"
388 By way of example, here is an excerpt from a procmailrc file
389 that filters messages through
391 before storing them in the user's
393 folder. It also stores the incoming message in the
395 folder in a filename generated by
397 which is a non-POSIX utility to generate a temporary file.
400 could be called on the message after it is stored.
404 .ta \w'\-fixboundary 'u
405 PATH = %bindir%:$PATH
407 MAILDIR = \`mhparam path\`
408 #### The Backups directory is relative to MAILDIR.
409 MKSTEMP = 'mkstemp -directory Backups -prefix mhfixmsg'
410 MHFIXMSG = 'mhfixmsg -noverbose -file - -outfile -'
411 STORE = %nmhlibexecdir%/rcvstore
413 :0 w: nmh-workers/procmail.$LOCKEXT
414 * ^TOnmh-workers@nongnu.org
415 | tee \`$MKSTEMP\` | $MHFIXMSG | $STORE +nmh-workers
422 on the current message in the current folder, with default transformations to
423 fix MIME boundaries and Content-Transfer-Encoding, to decode text and
424 application/ics content parts to 8 bit, and to add a corresponding text/plain
432 .SS Specified folder and messages
435 on specified messages, without its informational output:
439 mhfixmsg +inbox last:4
442 .SS View without modification
445 transforms the message in place.
446 To view the MIME structure that would result from running
448 on the current message, without modifying the message:
452 mhfixmsg -outfile - | mhlist -file -
455 .SS Search message without modification
456 To search the current message, which possibly contains base64
457 or quoted printable encoded text parts, without modifying it,
464 mhfixmsg -outfile - | grep \fIpattern\fR
469 can be abbreviated in usual MH fashion, e.g., to -o. The search will be
470 on the entire message, not just text parts.
471 .SS Translate text/plain parts to UTF-8
472 To translate all text/plain parts in the current message to UTF-8, in addition
473 to all of the default transformations:
477 mhfixmsg -textcharset utf-8
480 .SS Fix all messages in a folder
483 on all of the messages in a folder:
493 can be run on each message separately, e.g., using a Bourne shell loop:
497 for msg in \`pick +folder\`; do mhfixmsg +folder $msg; done
501 The two appearances of the
503 switch in that command protect against concurrent context changes by other
506 .SS Run on newly incorporated messages
509 on messages as they are incorporated:
513 inc && mhfixmsg -nochangecur unseen
517 This assumes that the Unseen-Sequence profile entry is set to
523 looks for mhn.defaults in multiple locations: absolute pathnames are
524 accessed directly, tilde expansion is done on usernames, and files are
525 searched for in the user's
527 directory as specified in their profile. If not found there, the directory
528 .RI \*(lq %nmhetcdir% \*(rq
533 .ta \w'%nmhetcdir%/mhn.defaults 'u
534 ^$HOME/.mh_profile~^The user profile
535 ^%nmhetcdir%/mhn.defaults~^Default mhfixmsg conversion entries
537 .SH "PROFILE COMPONENTS"
541 .ta \w'ExtraBigProfileName 'u
542 ^Path:~^To determine the user's nmh directory
543 ^Current\-Folder:~^To find the default current folder
544 ^rmmproc:~^Program to delete original messages or files
561 .RB ` +folder "' defaults to the current folder"
562 .RB ` msgs "' defaults to cur"
563 .RB ` "\-decodetext 8bit"'
564 .RB ` "\-decodetypes text,application/ics"'
565 .RB ` \-nodecodeheaderfieldbodies '
566 .RB ` \-crlflinebreaks '
567 .RB ` \-notextcharset '
569 .RB ` \-noreplacetextplain '
570 .RB ` \-fixboundary '
572 .RB ` \-checkbase64 '
577 If a folder is given, it will become the current folder. The last
578 message selected from a folder will become the current message, unless
581 switch is enabled. If the
583 switch or an absolute pathname is used, the context will not be
projects / nmh / blob