X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/e99539ae6376c4b33e1a23f2ce50830c0d107786..a670c9d22ff3a00459677c62d1929818c4e4c4e6:/man/mhbuild.man

diff --git a/man/mhbuild.man b/man/mhbuild.man
index 9dbf05a8..cbbaae67 100644
--- a/man/mhbuild.man
+++ b/man/mhbuild.man
@@ -1,4 +1,4 @@
-.TH MHBUILD %manext1% "March 21, 2013" "%nmhversion%"
+.TH MHBUILD %manext1% "January 23, 2014" "%nmhversion%"
 .\"
 .\" %nmhwarning%
 .\"
@@ -17,10 +17,14 @@ mhbuild \- translate MIME composition draft
 .RB [ \-rfc934mode " | " \-norfc934mode ]
 .RB [ \-contentid " | " \-nocontentid ]
 .RB [ \-verbose " | " \-noverbose ]
+.RB [ \-disposition " | " \-nodisposition ]
 .RB [ \-check " | " \-nocheck ]
 .RB [ \-headerencoding 
 .IR encoding\-algorithm
 .RB " | " \-autoheaderencoding ]
+.RB [ \-maxunencoded
+.IR line\-length ]
+.RB [ \-dist ]
 .RB [ \-version ]
 .RB [ \-help ]
 .ad
@@ -33,7 +37,7 @@ a valid MIME message.
 .B mhbuild
 creates multi-media messages as specified in RFC 2045
 to RFC 2049.  This includes the encoding of message headers as specified
-by RFC 2047.
+by RFC 2047, and the encoding of MIME parameters as specified in RFC 2231.
 .PP
 If you specify the name of the composition file as \*(lq-\*(rq,
 then
@@ -78,6 +82,26 @@ switch
 is present, then the listing will show any \*(lqextra\*(rq information
 that is present in the message, such as comments in the
 \*(lqContent-Type\*(rq header.
+.PP
+If the
+.B \-disposition
+switch is present, then the listing will show any relevant information from
+the \*(lqContent-Disposition\*(rq header.
+.SS "Simplified Attachment Interface"
+For users who wish to simply attach files to text content,
+.B mhbuild
+will scan the composition file for \*(lqAttach\*(rq headers.  An
+\*(lqAttach\*(rq header contains a filename that will be appended to the
+message using normal MIME encapsulation rules.  One filename is allowed
+per \*(lqAttach\*(rq header, but multiple \*(lqAttach\*(rq headers are
+allowed ber composition file.
+.PP
+These files will be appended after any other MIME content, including any
+content specified by
+.B mhbuild
+directives (see below).  See
+.IR send (1)
+for more details.
 .SS "Translating the Composition File"
 .B mhbuild
 is essentially a filter to aid in the composition of MIME
@@ -282,7 +306,7 @@ would be as follows:
 .fi
 .RE
 .PP
-Any long URLs will be wrapped according to RFC 2017 rules.
+Any long URLs will be wrapped according to RFC 2231 rules.
 .PP
 The \*(lqmessage\*(rq directive (#forw) is used to specify a message or
 group of messages to include.  You may optionally specify the name of
@@ -385,6 +409,18 @@ characters.  The
 switch suppresses creation of all \*(lqContent-ID:\*(rq headers,
 even in the top level of the message.
 .PP
+Normally
+.B mhbuild
+will choose an appropriate Content\-Transfer\-Encoding based on the content
+and the MIME Content\-Type.  However, you can override that in an
+.B mhbuild
+directive by specifying \*(lq*\*(rq and the encoding.  Acceptable encoding
+values are \*(lq8bit\*(rq, \*(lqqp\(*rq (for quoted\-printable), and
+\*(lqb64\*(rq (for base64 encoding).  It should be noted that undesired
+results may occur if 8bit or quoted\-printable is selected for binary
+content, due to the translation between Unix line endings and the line
+endings use by the mail transport system.
+.PP
 In addition to the various directives, plaintext can be present.
 Plaintext is gathered, until a directive is found or the draft is
 exhausted, and this is made to form a text content.  If the plaintext
@@ -457,6 +493,13 @@ If a text content contains only 7\-bit characters and the character set
 is not specified as above, then the character set will be labeled as
 \*(lqus-ascii\*(rq.
 .PP
+By default text content with the high bit set is encoded with a 8bit
+Content\-Transfer\-Encoding.  If the text has lines longer than the value
+of
+.B \-maxunencoded
+(which defaults to 78) then the text is encoded using the quoted\-printable
+encoding.
+.PP
 The
 .B \-headerencoding
 switch will indicate which algorithm to use when encoding any message headers
@@ -555,20 +598,11 @@ on file that already in MIME format.  The
 switch will cause
 .B mhbuild
 to exit without error if the input file already has valid MIME headers.
-.PP
-It is also possible to have the
-.B whatnow
-program invoke
-.B mhbuild
-automatically when a message is sent.  To do this, you must add the line
-.PP
-.RS 5
-automimeproc: 1
-.RE
-.PP
-to your
-.I \&.mh\(ruprofile
-file.
+The use of
+.B \-auto
+also enables the
+.B \-nodirectives
+switch.
 .PP
 Finally, you should consider adding this line to your profile:
 .PP
@@ -587,6 +621,14 @@ What now? list
 .RE
 .PP
 will work as you expect.
+.PP
+The
+.B \-dist
+switch is intended to be used by
+.BR dist .
+It will cause mhbuild to not generate any MIME headers in the composition
+file (such as \*(lqMIME-Version\*(rq or \*(lqContent-Type\*(rq), but it
+will still encode message headers according to RFC 2047.
 .SS "User Environment"
 Because the environment in which
 .B mhbuild
@@ -628,6 +670,7 @@ directive    ::=     "#" type "/" subtype
                          [ "<" id ">" ]
                          [ "[" description "]" ]
                          [ "{" disposition "}" ]
+			 [ "*8bit" | "*qp" | "*b64" ]
                          [ filename ]
                          EOL
 
@@ -637,6 +680,7 @@ directive    ::=     "#" type "/" subtype
                          [ "<" id ">" ]
                          [ "[" description "]" ]
                          [ "{" disposition "}" ]
+			 [ "*8bit" | "*qp" | "*b64" ]
                          external-parameters
                          EOL
 
@@ -668,6 +712,7 @@ plaintext    ::=     [ "Content-Description:"
                          [ "(" comment ")" ]
                          [ "[" description "]" ]
                          [ "{" disposition "}" ]
+			 [ "*8bit" | "*qp" | "*b64" ]
                          EOL
                          1*line
                      [ "#" EOL ]
@@ -738,5 +783,7 @@ is checked.
 .RB ` \-contentid '
 .RB ` \-nocheck '
 .RB ` \-noverbose '
+.RB ` \-nodisposition '
 .RB ` \-autoheaderencoding '
+.RB ` "\-maxunencoded\ 78"'
 .fi