X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/2e768e3cc0ce768373d3320eca4cdd08b8cf646a..521674623:/man/mhbuild.man?ds=inline

diff --git a/man/mhbuild.man b/man/mhbuild.man
index cbe2f4f5..2f0e8ee7 100644
--- a/man/mhbuild.man
+++ b/man/mhbuild.man
@@ -1,4 +1,4 @@
-.TH MHBUILD %manext1% "January 4, 2013" "%nmhversion%"
+.TH MHBUILD %manext1% "March 21, 2013" "%nmhversion%"
 .\"
 .\" %nmhwarning%
 .\"
@@ -9,6 +9,7 @@ mhbuild \- translate MIME composition draft
 .HP 5
 .B mhbuild
 .I file
+.RB [ \-auto " | " \-noauto ]
 .RB [ \-list " | " \-nolist ]
 .RB [ \-realsize " | " \-norealsize ]
 .RB [ \-headers " | " \-noheaders ]
@@ -17,6 +18,9 @@ mhbuild \- translate MIME composition draft
 .RB [ \-contentid " | " \-nocontentid ]
 .RB [ \-verbose " | " \-noverbose ]
 .RB [ \-check " | " \-nocheck ]
+.RB [ \-headerencoding 
+.IR encoding\-algorithm
+.RB " | " \-autoheaderencoding ]
 .RB [ \-version ]
 .RB [ \-help ]
 .ad
@@ -27,12 +31,9 @@ command will translate a MIME composition draft into
 a valid MIME message.
 .PP
 .B mhbuild
-creates multi-media messages as specified in RFC\-2045
-to RFC\-2049.  Currently
-.B mhbuild
-only supports encodings in
-message bodies, and does not support the encoding of message headers as
-specified in RFC\-2047.
+creates multi-media messages as specified in RFC 2045
+to RFC 2049.  This includes the encoding of message headers as specified
+by RFC 2047.
 .PP
 If you specify the name of the composition file as \*(lq-\*(rq,
 then
@@ -234,7 +235,7 @@ separated accordingly.  For example,
     type=tar; \\
     conversions=compress \\
     [this is the nmh distribution] \\
-    {application; filename="nmh.tar.gz"} \\
+    {attachment; filename="nmh.tar.gz"} \\
     name="nmh.tar.gz"; \\
     directory="/pub/nmh"; \\
     site="ftp.math.gatech.edu"; \\
@@ -255,7 +256,7 @@ These parameters are of the form:
 .RS 5
 .nf
 .ta \w'access-type=  'u
-access-type=	usually \fIanon-ftp\fR or \fImail-server\fR
+access-type=	usually \fIanon-ftp\fR, \fImail-server\fR, or \fIurl\fR
 name=	filename
 permission=	read-only or read-write
 site=	hostname
@@ -265,9 +266,24 @@ size=	number of octets
 server=	mailbox
 subject=	subject to send
 body=	command to send for retrieval
+url=	URL of content
 .fi
 .RE
 .PP
+A mimimum \*(lqexternal\-type\*(rq directive for the
+.B url
+.I access\-type
+would be as follows:
+.PP
+.RS 3
+.nf
+#@application/octet-stream [] access-type=url; \\
+  url="http://download.savannah.gnu.org/releases/nmh/nmh-1.5.tar.gz"
+.fi
+.RE
+.PP
+Any long URLs will be wrapped according to RFC 2017 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
 the folder and which messages are to be forwarded.  If a folder is not
@@ -276,7 +292,7 @@ given, it defaults to the current message.  Hence, the message directive
 is similar to the
 .B forw
 command, except that the former uses
-the MIME rules for encapsulation rather than those specified in RFC\-934.
+the MIME rules for encapsulation rather than those specified in RFC 934.
 For example,
 .PP
 .RS 5
@@ -299,8 +315,8 @@ switch.  This switch will indicate that
 .B mhbuild
 should attempt to utilize the MIME encapsulation rules
 in such a way that the \*(lqmultipart/digest\*(rq that is created
-is (mostly) compatible with the encapsulation specified in RFC\-934.
-If given, then RFC\-934 compliant user-agents should be able to burst the
+is (mostly) compatible with the encapsulation specified in RFC 934.
+If given, then RFC 934 compliant user-agents should be able to burst the
 message on reception\0--\0providing that the messages being encapsulated
 do not contain encapsulated messages themselves.  The drawback of this
 approach is that the encapsulations are generated by placing an extra
@@ -439,6 +455,19 @@ 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
+The
+.B \-headerencoding
+switch will indicate which algorithm to use when encoding any message headers
+that contain 8\-bit characters.  The valid arguments are
+.I base64
+for based\-64 encoding and 
+.I quoted
+for quoted\-printable encoding.  The
+.B \-autoheaderencoding
+switch will instruct
+.B mhbuild
+to automatically pick the algorithm that results in a shorter encoded string.
+.PP
 Putting this all together,
 here is an example of a more complicated message draft.  The
 following draft will expand into a multipart/mixed message
@@ -517,6 +546,14 @@ to execute
 .B mhbuild
 to translate the composition file into MIME format.
 .PP
+Normally it is an error to invoke
+.B mhbuild
+on file that already in MIME format.  The 
+.B \-auto
+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
@@ -639,6 +676,15 @@ line         ::=     "##" text EOL
 .fi
 .RE
 .SH FILES
+.B mhbuild
+looks for additional user profile files and 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 %etcdir% \*(rq
+is checked.
+.PP
 .fc ^ ~
 .nf
 .ta \w'%etcdir%/ExtraBigFileName  'u
@@ -661,25 +707,27 @@ line         ::=     "##" text EOL
 .IR mhstore (1)
 .PP
 .I "Proposed Standard for Message Encapsulation"
-(RFC\-934),
+(RFC 934),
 .PP
 .I "The Content-MD5 Header Field"
-(RFC\-1864),
+(RFC 1864),
 .PP
 .I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
-(RFC\-2045),
+(RFC 2045),
 .PP
 .I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
-(RFC\-2046),
+(RFC 2046),
 .PP
 .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text"
-(RFC\-2047),
+(RFC 2047),
 .PP
 .I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures"
-(RFC\-2048),
+(RFC 2048),
 .PP
 .I "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples"
-(RFC\-2049)
+(RFC 2049)
+.I "Definition of the URL MIME External-Body Access-Type"
+(RFC 2017)
 .SH DEFAULTS
 .nf
 .RB ` \-headers '
@@ -688,4 +736,5 @@ line         ::=     "##" text EOL
 .RB ` \-contentid '
 .RB ` \-nocheck '
 .RB ` \-noverbose '
+.RB ` \-autoheaderencoding '
 .fi