Merge branch 'pop-stls'

[nmh] / man / mhfixmsg.man

diff --git a/man/mhfixmsg.man b/man/mhfixmsg.man
index 38c322f9318ada0b1fecba20ef66f55a6e271f50..0a885331b815b54048f1d8274c4ced663ba40052 100644 (file)
--- a/man/mhfixmsg.man
+++ b/man/mhfixmsg.man
@@ -1,23 +1,28 @@
-.TH MHFIXMSG %manext1% "September 22, 2016" "%nmhversion%"
-.\"
+.TH MHFIXMSG %manext1% 2019-03-31 "%nmhversion%"
+.

 .\" %nmhwarning%
 .\" %nmhwarning%

-.\"
+.

 .SH NAME
 .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
 .SH SYNOPSIS
 .HP 5
 .na
 .B mhfixmsg

+.RB [ \-help ]
+.RB [ \-version ]

 .RI [ +folder ]
 .RI [ msgs " | "
 .IR "absolute pathname" " | "
 .RI [ +folder ]
 .RI [ msgs " | "
 .IR "absolute pathname" " | "

-.RB \-file
+.B \-file

 .IR file ]
 .RB [ \-decodetext
 8bit|7bit|binary |
 .BR \-nodecodetext ]
 .RB [ \-decodetypes
 .IR "type/[subtype][,...]" ]
 .IR file ]
 .RB [ \-decodetext
 8bit|7bit|binary |
 .BR \-nodecodetext ]
 .RB [ \-decodetypes
 .IR "type/[subtype][,...]" ]

+.RB [ \-decodeheaderfieldbodies
+utf-8 |
+.BR \-nodecodeheaderfieldbodies ]

 .RB [ \-crlflinebreaks " | " \-nocrlflinebreaks ]
 .RB [ \-textcharset
 .I charset
 .RB [ \-crlflinebreaks " | " \-nocrlflinebreaks ]
 .RB [ \-textcharset
 .I charset


@@ -26,6 +31,7 @@ mhfixmsg \- rewrite MIME messages with various transformations
 .RB [ \-replacetextplain " | " \-noreplacetextplain ]
 .RB [ \-fixboundary " | " \-nofixboundary ]
 .RB [ \-fixcte " | " \-nofixcte ]
 .RB [ \-replacetextplain " | " \-noreplacetextplain ]
 .RB [ \-fixboundary " | " \-nofixboundary ]
 .RB [ \-fixcte " | " \-nofixcte ]

+.RB [ \-checkbase64 " | " \-nocheckbase64 ]

 .RB [ \-fixtype
 .IR mimetype ]
 .RB [ \-outfile
 .RB [ \-fixtype
 .IR mimetype ]
 .RB [ \-outfile


@@ -35,8 +41,6 @@ mhfixmsg \- rewrite MIME messages with various transformations
 .RB [ \-normmproc ]
 .RB [ \-changecur " | " \-nochangecur ]
 .RB [ \-verbose " | " \-noverbose ]
 .RB [ \-normmproc ]
 .RB [ \-changecur " | " \-nochangecur ]
 .RB [ \-verbose " | " \-noverbose ]

-.RB [ \-version ]
-.RB [ \-help ]

 .ad
 .SH DESCRIPTION
 .B mhfixmsg
 .ad
 .SH DESCRIPTION
 .B mhfixmsg


@@ -60,19 +64,18 @@ can safely be run multiple times on a message.
 .PP
 The
 .B \-decodetext
 .PP
 The
 .B \-decodetext

-switch enables a transformation to decode each base64 and
-quoted-printable text message part to the selected 8bit, 7bit, or
+switch enables a transformation to decode each base64 and quoted-printable
+text message part to the selected 8-bit, 7-bit, or

 binary encoding.
 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
+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.
 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
+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).  Note that
 .B \-decodetext
 .B \-verbose
 is enabled).  Note that
 .B \-decodetext

-binary can produce messages that are not RFC 2045 compliant.
+binary can produce messages that are not compliant with RFC 5322, \(sc2.1.1.

 .PP
 When the
 .B \-decodetext
 .PP
 When the
 .B \-decodetext


@@ -98,6 +101,18 @@ to restrict
 .B \-decodetext
 to just text/plain parts.
 .PP
 .B \-decodetext
 to just text/plain parts.
 .PP

+The
+.B \-decodeheaderfieldbodies
+switch enables decoding of UTF-8 header field bodies, when supplied
+with its mandatory
+.I utf-8
+argument.  The
+.B \-nodecodeheaderfieldbodies
+inhibits this transformation.  The transformation can produce a message
+that does not conform with RFC 2047, \(sc1, paragraph 6, because the decoded
+header field body could contain unencoded non-ASCII characters.  It is
+therefore not enabled by default.
+.PP

 By default, carriage return characters are preserved or inserted at
 the end of each line of text content.  The
 .B \-crlflinebreaks
 By default, carriage return characters are preserved or inserted at
 the end of each line of text content.  The
 .B \-crlflinebreaks


@@ -106,7 +121,7 @@ switch selects this behavior and is enabled by default.  The
 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
 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.
+with RFC 2046, \(sc4.1.1, paragraph 1.

 .PP
 The
 .B \-textcharset
 .PP
 The
 .B \-textcharset


@@ -117,9 +132,9 @@ Charset conversions require that
 .B nmh
 be built with
 .IR iconv (3);
 .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
 .B nmh
 installation includes that.
 To convert text parts other than text/plain, an external program can


@@ -155,17 +170,17 @@ tries to add one.
 The
 .B \-replacetextplain
 switch broadens the applicability of
 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
 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
 .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
 .B mhshow
 uses its mhshow-show-text/subtype entries.  When
 .B nmh


@@ -190,16 +205,31 @@ programs that parse MIME messages.
 The
 .B \-fixcte
 switch enables a transformation to change the
 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, \(sc6.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
 programs that parse MIME messages.
 .PP
 The
 .B mhlist
 and other
 .B nmh
 programs that parse MIME messages.
 .PP
 The

+.B \-checkbase64
+switch enables a check of the encoding validity in base64-encoded
+MIME parts.  The check looks for a non-encoded text footer appended
+to a base64-encoded part.  Per RFC 2045 \(sc6.8, the occurrence of
+a "=" character signifies the end of base-64 encoded content.  If
+none is found, a heuristic is used:  specifically, two consecutive
+invalid base64 characters signify the beginning of a plain text
+footer.  If a text footer is found and this switch is enabled,
+.B mhfixmsg
+separates the base64-encoded and non-encoded content and places
+them in a pair of subparts to a newly constructed multipart/mixed
+part.  That multipart/mixed part replaces the original base64-encoded
+part in the MIME structure of the message.
+.PP
+The

 .B \-fixtype
 switch ensures that each part of the message has the correct MIME type
 shown in its Content-Type header.  It may be repeated.  It is
 .B \-fixtype
 switch ensures that each part of the message has the correct MIME type
 shown in its Content-Type header.  It may be repeated.  It is


@@ -208,8 +238,12 @@ more descriptive MIME type.  It may not be used for multipart and
 message types.
 .PP
 .B mhfixmsg
 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
 .PP
 The
 .B \-verbose


@@ -236,17 +270,14 @@ The
 .I file
 switch directs
 .B mhfixmsg
 .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
 .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
 .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
 .B \-outfile
 switch is not enabled when using the standard input stream,
 .B mhfixmsg


@@ -294,20 +325,21 @@ content type and/or encoding as follows:
 .PP
 .RS 5
 .nf
 .PP
 .RS 5
 .nf

-.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 part
-\-fixtype            all except multipart and message parts
+.ta \w'\-decodeheaderfieldbodies 'u
+\-decodetext              base64 and quoted-printable encoded text parts
+\-decodetypes             limits parts to which -decodetext applies
+\-decodeheaderfieldbodies all message parts
+\-crlflinebreaks          text parts
+\-textcharset             text/plain parts
+\-reformat                text parts that are not text/plain
+\-fixboundary             outermost multipart part
+\-fixcte                  multipart or message part
+\-checkbase64             base64 encoded parts
+\-fixtype                 all except multipart and message parts

 .fi
 .RE
 .SS "Backup of Original Message/File"
 .fi
 .RE
 .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
 .B \-outfile
 switch is not used,
 .B mhfixmsg


@@ -334,15 +366,14 @@ Note that add-hooks are called from all
 .B nmh
 programs that add a message to a folder, not just
 .BR inc .
 .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
 .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
 mhfixmsg -nochangecur $msgs
 .RE
 .PP


@@ -372,7 +403,8 @@ could be called on the message after it is stored.
 .nf
 .ta \w'\-fixboundary 'u
 PATH = %bindir%:$PATH
 .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 -'
 #### The Backups directory is relative to MAILDIR.
 MKSTEMP = 'mkstemp -directory Backups -prefix mhfixmsg'
 MHFIXMSG = 'mhfixmsg -noverbose -file - -outfile -'


@@ -380,11 +412,10 @@ STORE = %nmhlibexecdir%/rcvstore
 
 :0 w: nmh-workers/procmail.$LOCKEXT
 * ^TOnmh-workers@nongnu.org
 
 :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"
 .fi
 .RE
 .SH "EXAMPLES"

-.PP

 .SS Basic usage
 To run
 .B mhfixmsg
 .SS Basic usage
 To run
 .B mhfixmsg


@@ -411,7 +442,8 @@ mhfixmsg +inbox last:4
 .SS View without modification
 By default,
 .B mhfixmsg
 .SS View without modification
 By default,
 .B mhfixmsg

-transforms the message in place.  To view the MIME structure that would result from running
+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
 .B mhfixmsg
 on the current message, without modifying the message:
 .PP


@@ -421,8 +453,11 @@ mhfixmsg -outfile - | mhlist -file -
 .fi
 .RE
 .SS Search message without modification
 .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:
+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
 .PP
 .RS
 .nf


@@ -430,7 +465,8 @@ mhfixmsg -outfile - | grep \fIpattern\fR
 .fi
 .RE
 .PP
 .fi
 .RE
 .PP

--outfile can be abbreviated in usual MH fashion, e.g., to -o.  The search will be
+.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
 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


@@ -444,17 +480,29 @@ mhfixmsg -textcharset utf-8
 .SS Fix all messages in a folder
 To run
 .B mhfixmsg
 .SS Fix all messages in a folder
 To run
 .B mhfixmsg

-on all of the messages in a folder, using a Bourne shell loop:
+on all of the messages in a folder:

 .PP
 .RS
 .nf
 .PP
 .RS
 .nf

-for msg in `pick +folder`; do mhfixmsg $msg; done
+mhfixmsg +folder all

 .fi
 .RE
 .PP
 .fi
 .RE
 .PP

+Alternatively,

 .B mhfixmsg
 .B mhfixmsg

-can be run on more than one message, but on a large number of messages
-may attempt to open too many files.
+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
 .SS Run on newly incorporated messages
 To run
 .B mhfixmsg


@@ -468,7 +516,8 @@ inc  &&  mhfixmsg -nochangecur unseen
 .PP
 This assumes that the Unseen-Sequence profile entry is set to
 .BR unseen ,
 .PP
 This assumes that the Unseen-Sequence profile entry is set to
 .BR unseen ,

-as shown in the mh\-profile(5) man page.
+as shown in
+.IR mh-profile (5).

 .SH FILES
 .B mhfixmsg
 looks for mhn.defaults in multiple locations: absolute pathnames are
 .SH FILES
 .B mhfixmsg
 looks for mhn.defaults in multiple locations: absolute pathnames are


@@ -482,7 +531,7 @@ is checked.
 .fc ^ ~
 .nf
 .ta \w'%nmhetcdir%/mhn.defaults  'u
 .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"
 ^%nmhetcdir%/mhn.defaults~^Default mhfixmsg conversion entries
 .fi
 .SH "PROFILE COMPONENTS"


@@ -495,14 +544,14 @@ is checked.
 ^rmmproc:~^Program to delete original messages or files
 .fi
 .SH "SEE ALSO"
 ^rmmproc:~^Program to delete original messages or files
 .fi
 .SH "SEE ALSO"

-.IR inc (1),

 .IR iconv (3),
 .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-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),
 .IR procmail (1),
 .IR procmailrc (5),
 .IR rcvstore (1),


@@ -513,12 +562,14 @@ is checked.
 .RB ` msgs "' defaults to cur"
 .RB ` "\-decodetext 8bit"'
 .RB ` "\-decodetypes text,application/ics"'
 .RB ` msgs "' defaults to cur"
 .RB ` "\-decodetext 8bit"'
 .RB ` "\-decodetypes text,application/ics"'

+.RB ` \-nodecodeheaderfieldbodies '

 .RB ` \-crlflinebreaks '
 .RB ` \-notextcharset '
 .RB ` \-reformat '
 .RB ` \-noreplacetextplain '
 .RB ` \-fixboundary '
 .RB ` \-fixcte '
 .RB ` \-crlflinebreaks '
 .RB ` \-notextcharset '
 .RB ` \-reformat '
 .RB ` \-noreplacetextplain '
 .RB ` \-fixboundary '
 .RB ` \-fixcte '

+.RB ` \-checkbase64 '

 .RB ` \-changecur '
 .RB ` \-noverbose '
 .fi
 .RB ` \-changecur '
 .RB ` \-noverbose '
 .fi


@@ -531,9 +582,3 @@ switch is enabled.  If the
 .B \-file
 switch or an absolute pathname is used, the context will not be
 modified.
 .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.