If str == buffer, then do NOT do a strncpy(buffer, str). Many systems

[nmh] / man / mhfixmsg.man

diff --git a/man/mhfixmsg.man b/man/mhfixmsg.man
index bb80a28f3a440a33970cf3803569e466b51c71ad..84245661ca99dd5e089aef31ddfd0002bc0dcd56 100644 (file)
--- a/man/mhfixmsg.man
+++ b/man/mhfixmsg.man
@@ -1,4 +1,4 @@
-.TH MHFIXMSG %manext1% "March 18, 2013" "%nmhversion%"
+.TH MHFIXMSG %manext1% "February 8, 2015" "%nmhversion%"

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


@@ -9,23 +9,28 @@ mhfixmsg \- rewrite MIME messages with various transformations
 .na
 .B mhfixmsg
 .RI [ +folder ]
 .na
 .B mhfixmsg
 .RI [ +folder ]

-.RI [ msgs ]
+.RI [ msgs " | "
+.IR "absolute pathname" " | "
+.RB \-file
+.IR file ]

 .RB [ \-decodetext
 8bit/7bit |
 .BR \-nodecodetext ]
 .RB [ \-decodetext
 8bit/7bit |
 .BR \-nodecodetext ]

-.RB [ \-textcodeset
-.I codeset
-.RB "| " \-notextcodeset ]
+.RB [ \-textcharset
+.I charset
+.RB "| " \-notextcharset ]

 .RB [ \-reformat " | " \-noreformat ]
 .RB [ \-reformat " | " \-noreformat ]

+.RB [ \-replacetextplain " | " \-noreplacetextplain ]

 .RB [ \-fixboundary " | " \-nofixboundary ]
 .RB [ \-fixcte " | " \-nofixcte ]
 .RB [ \-fixboundary " | " \-nofixboundary ]
 .RB [ \-fixcte " | " \-nofixcte ]

-.RB [ \-file
-.IR file ]
+.RB [ \-fixtype
+.IR mimetype ]

 .RB [ \-outfile
 .IR outfile ]
 .RB [ \-rmmproc
 .IR program ]
 .RB [ \-normmproc ]
 .RB [ \-outfile
 .IR outfile ]
 .RB [ \-rmmproc
 .IR program ]
 .RB [ \-normmproc ]

+.RB [ \-changecur " | " \-nochangecur ]

 .RB [ \-verbose " | " \-noverbose ]
 .RB [ \-version ]
 .RB [ \-help ]
 .RB [ \-verbose " | " \-noverbose ]
 .RB [ \-version ]
 .RB [ \-help ]


@@ -36,7 +41,7 @@ rewrites MIME messages, applying specific transformations such as
 decoding of MIME-encoded message parts and repairing invalid MIME
 headers.
 .PP
 decoding of MIME-encoded message parts and repairing invalid MIME
 headers.
 .PP

-MIME messages are specified in RFC\-2045 to RFC\-2049
+MIME messages are specified in RFC 2045 to RFC 2049

 (see
 .IR mhbuild (1)).
 The
 (see
 .IR mhbuild (1)).
 The


@@ -52,18 +57,34 @@ The
 .B \-decodetext
 switch enables a transformation to decode each base64 and
 quoted-printable text message part to the selected 8bit or 7bit
 .B \-decodetext
 switch enables a transformation to decode each base64 and
 quoted-printable text message part to the selected 8bit or 7bit

-encoding.  If the decoded text would not fit the selected encoding as
-defined by RFC-2045, the part is not decoded.
+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
+.B \-verbose
+is enabled).
+.PP
+When the
+.B \-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.

 .PP
 The
 .PP
 The

-.B \-textcodeset
+.B \-textcharset

 switch specifies that all text/plain parts of the message(s)
 should be converted to
 switch specifies that all text/plain parts of the message(s)
 should be converted to

-.IR codeset .
-Codeset conversions require that
+.IR charset .
+Charset conversions require that

 .B nmh
 be built with
 .B nmh
 be built with

-.IR iconv (3).
+.IR iconv (3);
+see the
+.BR mhparam (1)
+man page for how determine whether your
+.B nmh
+installation includes that.

 To convert text parts other than text/plain, an external program can
 be used, via the
 .B \-reformat
 To convert text parts other than text/plain, an external program can
 be used, via the
 .B \-reformat


@@ -83,6 +104,27 @@ inserts that text/plain part at the beginning of the containing
 multipart/alternative part, if present.  If not, it creates a
 multipart/alternative part.
 .PP
 multipart/alternative part, if present.  If not, it creates a
 multipart/alternative part.
 .PP

+With the
+.B \-reformat
+switch, multipart/related parts are handled differently than
+multipart/alternative.  If the multipart/related has only a single
+part that is not text/plain and can be converted to text/plain, a
+text/plain part is added and the type of the part is changed to
+multipart/alternative.  If the multipart/related has more than one
+part but does not have a text/plain part,
+.B mhfixmsg
+tries to add one.
+.PP
+The
+.B \-replacetextplain
+switch broadens the applicability of
+.B \-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.
+.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
 .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


@@ -92,7 +134,7 @@ uses its mhshow-show-text/subtype entries.  When
 .B nmh
 is installed, it searches for a conversion program for text/html
 content, and if one is found, inserts a mhfixmsg-format-text/html
 .B 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 %etcdir%/mhn.defaults.  An entry of the same name in the
+entry in %nmhetcdir%/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.
 .PP
 user's profile takes precedence.  The user can add entries for
 other text subtypes to their profile.
 .PP


@@ -121,11 +163,35 @@ and other
 programs that parse MIME messages.
 .PP
 The
 programs that parse MIME messages.
 .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
+typically used to replace \*(lqapplication/octet-stream\*(rq with a
+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.
+.PP
+The

 .B \-verbose
 switch directs
 .B mhfixmsg
 to output informational message for each transformation applied.
 .PP
 .B \-verbose
 switch directs
 .B mhfixmsg
 to output informational message for each transformation applied.
 .PP

+The return status of
+.B mhfixmsg
+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
+.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
+modified.
+.PP

 The
 .B \-file
 .I file
 The
 .B \-file
 .I file


@@ -133,7 +199,12 @@ switch directs
 .B mhfixmsg
 to use the specified
 file as the source message, rather than a message from a folder.
 .B mhfixmsg
 to use the specified
 file as the source message, rather than a message from a folder.

-If this file is \*(lq-\*(rq, then
+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

 .B mhfixmsg
 accepts the source message on the standard input stream.  If
 the
 .B mhfixmsg
 accepts the source message on the standard input stream.  If
 the


@@ -175,7 +246,7 @@ to add a single transformed message to a different folder, e.g.,
 .RS 5
 mhfixmsg -outfile - | \\
 .RS 0
 .RS 5
 mhfixmsg -outfile - | \\
 .RS 0

-%libdir%/rcvstore +folder
+%nmhlibexecdir%/rcvstore +folder

 .RE
 .RE
 .SS Summary of Applicability
 .RE
 .RE
 .SS Summary of Applicability


@@ -186,10 +257,11 @@ content type and/or encoding as follows:
 .nf
 .ta \w'\-fixboundary 'u
 \-decodetext   base64 and quoted-printable encoded text parts
 .nf
 .ta \w'\-fixboundary 'u
 \-decodetext   base64 and quoted-printable encoded text parts

-\-textcodeset  text/plain parts
+\-textcharset  text/plain parts

 \-reformat     text parts that are not text/plain
 \-fixboundary  outermost multipart part
 \-fixcte       multipart part
 \-reformat     text parts that are not text/plain
 \-fixboundary  outermost multipart part
 \-fixcte       multipart part

+\-fixtype      all except multipart and message parts

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


@@ -216,6 +288,31 @@ profile component and negates all prior
 .B \-rmmproc
 switches.
 .PP
 .B \-rmmproc
 switches.
 .PP

+.SS "Integration with inc"
+.B mhfixmsg
+can be used as an add-hook, as described in %docdir%/README-HOOKS.
+Note that add-hooks are called from all
+.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
+.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  &&  \
+mhfixmsg -nochangecur $msgs
+.RE
+.PP
+Another approach would rely on adding a sequence to Unseen-Sequence,
+which
+.B inc
+sets with the newly incorporated messages.  Those could then be
+supplied to
+.BR mhfixmsg .

 .SS "Integration with procmail"
 By way of example, here is an excerpt from a procmailrc file
 that filters messages through
 .SS "Integration with procmail"
 By way of example, here is an excerpt from a procmailrc file
 that filters messages through


@@ -225,11 +322,9 @@ before storing them in the user's
 folder.  It also stores the incoming message in the
 .I Backups
 folder in a filename generated by
 folder.  It also stores the incoming message in the
 .I Backups
 folder in a filename generated by

-.BR mktemp ,
+.BR mkstemp ,

 which is a non-POSIX utility to generate a temporary file.
 which is a non-POSIX utility to generate a temporary file.

-If you do not have that utility, then the
-.BR mkstemp (3)
-function could form the basis for a substitute.  Or,
+Alternatively,

 .B mhfixmsg
 could be called on the message after it is stored.
 .PP
 .B mhfixmsg
 could be called on the message after it is stored.
 .PP


@@ -238,22 +333,32 @@ could be called on the message after it is stored.
 .ta \w'\-fixboundary 'u
 PATH = %bindir%:$PATH
 MAILDIR = `mhparam path`
 .ta \w'\-fixboundary 'u
 PATH = %bindir%:$PATH
 MAILDIR = `mhparam path`

-MKTEMP = 'mktemp Backups/mhfixmsg.XXXXXXXX'
+#### The Backups directory is relative to MAILDIR.
+MKSTEMP = 'mkstemp -directory Backups -prefix mhfixmsg'

 MHFIXMSG = 'mhfixmsg -noverbose -file - -outfile -'
 MHFIXMSG = 'mhfixmsg -noverbose -file - -outfile -'

-STORE = %libdir%/rcvstore
+STORE = %nmhlibexecdir%/rcvstore

 
 

-:0 w: nmh-worker/procmail.$LOCKEXT
+:0 w: nmh-workers/procmail.$LOCKEXT

 * ^TOnmh-workers@nongnu.org
 * ^TOnmh-workers@nongnu.org

-| tee `$MKTEMP` | $MHFIXMSG | $STORE +nmh-workers
+| tee `$MKSTEMP` | $MHFIXMSG | $STORE +nmh-workers

 .fi
 .RE
 .PP
 .SH FILES
 .fi
 .RE
 .PP
 .SH FILES

+.B 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
+.I Mail
+directory as specified in their profile.  If not found there, the directory
+.RI \*(lq %nmhetcdir% \*(rq
+is checked.
+.PP

 .fc ^ ~
 .nf
 .fc ^ ~
 .nf

-.ta \w'%etcdir%/mhn.defaults  'u
+.ta \w'%nmhetcdir%/mhn.defaults  'u

 ^$HOME/\&.mh\(ruprofile~^The user profile
 ^$HOME/\&.mh\(ruprofile~^The user profile

-^%etcdir%/mhn.defaults~^Default mhfixmsg conversion entries
+^%nmhetcdir%/mhn.defaults~^Default mhfixmsg conversion entries

 .fi
 .SH "PROFILE COMPONENTS"
 .fc ^ ~
 .fi
 .SH "PROFILE COMPONENTS"
 .fc ^ ~


@@ -265,11 +370,14 @@ STORE = %libdir%/rcvstore
 ^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 mh-profile (5),
 .IR mhbuild (1),
 .IR mhlist (1),
 .IR mh-profile (5),
 .IR mhbuild (1),
 .IR mhlist (1),

+.IR mhparam (1),

 .IR mhshow (1),
 .IR mhshow (1),

-.IR mkstemp (3),
+.IR mh-mkstemp (1),

 .IR procmail (1),
 .IR procmailrc (5),
 .IR rcvstore (1),
 .IR procmail (1),
 .IR procmailrc (5),
 .IR rcvstore (1),


@@ -279,15 +387,20 @@ STORE = %libdir%/rcvstore
 .RB ` +folder "' defaults to the current folder"
 .RB ` msgs "' defaults to cur"
 .RB ` "\-decodetext 8bit"'
 .RB ` +folder "' defaults to the current folder"
 .RB ` msgs "' defaults to cur"
 .RB ` "\-decodetext 8bit"'

-.RB ` \-notextcodeset '
+.RB ` \-notextcharset '

 .RB ` \-reformat '
 .RB ` \-reformat '

+.RB ` \-noreplacetextplain '

 .RB ` \-fixboundary '
 .RB ` \-fixcte '
 .RB ` \-fixboundary '
 .RB ` \-fixcte '

+.RB ` \-changecur '

 .RB ` \-noverbose '
 .fi
 .SH CONTEXT
 If a folder is given, it will become the current folder.  The last
 .RB ` \-noverbose '
 .fi
 .SH 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
+message selected from a folder will become the current message, unless

 the
 the

+.B \-nochangecur
+switch is enabled.  If the

 .B \-file
 .B \-file

-switch is used, the context will not be modified.
+switch or an absolute pathname is used, the context will not be
+modified.