X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/5dd6771b28c257af405d7248639ed0e3bcdce38b..b4f2851d4:/man/mhbuild.man?ds=sidebyside diff --git a/man/mhbuild.man b/man/mhbuild.man index b0af8810..710c4491 100644 --- a/man/mhbuild.man +++ b/man/mhbuild.man @@ -1,7 +1,7 @@ +.TH MHBUILD %manext1% "March 21, 2013" "%nmhversion%" .\" .\" %nmhwarning% .\" -.TH MHBUILD %manext1% "%nmhdate%" MH.6.8 [%nmhversion%] .SH NAME mhbuild \- translate MIME composition draft .SH SYNOPSIS @@ -12,11 +12,14 @@ mhbuild \- translate MIME composition draft .RB [ \-list " | " \-nolist ] .RB [ \-realsize " | " \-norealsize ] .RB [ \-headers " | " \-noheaders ] -.RB [ \-ebcdicsafe " | " \-noebcdicsafe ] +.RB [ \-directives " | " \-nodirectives ] .RB [ \-rfc934mode " | " \-norfc934mode ] .RB [ \-contentid " | " \-nocontentid ] .RB [ \-verbose " | " \-noverbose ] .RB [ \-check " | " \-nocheck ] +.RB [ \-headerencoding +.IR encoding\-algorithm +.RB " | " \-autoheaderencoding ] .RB [ \-version ] .RB [ \-help ] .ad @@ -27,12 +30,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 -thru 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 @@ -77,6 +77,19 @@ 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 +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. .SS "Translating the Composition File" .B mhbuild is essentially a filter to aid in the composition of MIME @@ -115,12 +128,35 @@ than one line, e.g., .fi .RE .PP -There are four kinds of directives: \*(lqtype\*(rq directives, which +There are five kinds of directives: \*(lqtype\*(rq directives, which name the type and subtype of the content; \*(lqexternal-type\*(rq directives, which also name the type and subtype of the content; the \*(lqmessage\*(rq directive (#forw), which is used to forward one or -more messages; and, the \*(lqbegin\*(rq directive (#begin), which is -used to create a multipart content. +more messages; the \*(lqbegin\*(rq directive (#begin), which is +used to create a multipart content; and the \*(lqon/off/pop\*(rq +directives (#on, #off, #pop) which control whether any other +directives are honored at all. +.PP +The +.B \-directives +switch allows control over whether mhbuild will honor any of the +\*(lq#\*(rq-directives. This can also be affected with the #on or +#off directives, and #pop, which restores the state of processing to +that preceding the most recent #on or #off. (The #on, #off, and #pop +directives are always honored, of course.) This allows inclusion of +plain text which looks like mhbuild directives, without causing +errors: +.PP +.RS 5 +.nf +#off +#include +printf("Hello, World!); +#pop +.fi +.RE +.PP +Currently the stack depth for the #on/off/pop directives is 32. .PP The \*(lqtype\*(rq directive is used to directly specify the type and subtype of a content. You may only specify discrete types in this manner @@ -211,7 +247,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"; \\ @@ -232,7 +268,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 @@ -242,9 +278,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 @@ -253,7 +304,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 @@ -276,8 +327,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 @@ -443,12 +494,11 @@ If .B mhbuild is given the .B \-check -switch, then it will also associate -an integrity check with each \*(lqleaf\*(rq content. This will add a -Content-MD5 header field to the content, along with the md5 sum of the -unencoded contents. This may be used by the receiver of the message to -verify that the contents of the message were not changed in transport. - +switch, then it will also associate an integrity check with each +\*(lqleaf\*(rq content. This will add a Content-MD5 header field to +the content, along with the md5 sum of the unencoded contents, per RFC +1864. This may be used by the receiver of the message to verify that +the contents of the message were not changed in transport. .SS "Transfer Encodings" After .B mhbuild @@ -467,22 +517,10 @@ will encode each content with a transfer encoding, even it the content contains only 7\-bit data. This is to increase the likelihood that the content is not changed while in transport. -.PP -The switch -.B \-ebcdicsafe -will cause -.B mhbuild -to slightly change -the way in which it performs the \*(lqquoted-printable\*(rq transfer -encoding. Along with encoding 8\-bit characters, it will now also encode -certain common punctuation characters as well. This slightly reduces the -readability of the message, but allows the message to pass more reliably -through mail gateways which involve the EBCDIC character encoding. - .SS "Invoking mhbuild" Typically, .B mhbuild - is invoked by the +is invoked by the .B whatnow program. This command will expect the body of the draft to be formatted as an @@ -538,7 +576,6 @@ What now? list .RE .PP will work as you expect. - .SS "User Environment" Because the environment in which .B mhbuild @@ -563,7 +600,6 @@ user profile, e.g., .RE .PP if it exists. - .SS "Syntax of Composition Files" The following is the formal syntax of a .B mhbuild @@ -630,9 +666,16 @@ line ::= "##" text EOL | text EOL .fi .RE -.PP - .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 @@ -640,7 +683,6 @@ line ::= "##" text EOL ^$MHBUILD~^Additional profile entries ^%etcdir%/mhn.defaults~^System default MIME profile entries .fi - .SH "PROFILE COMPONENTS" .fc ^ ~ .nf @@ -650,28 +692,33 @@ line ::= "##" text EOL ^Current\-Folder:~^To find the default current folder ^mhbuild-compose-*~^Template for composing contents .fi - .SH "SEE ALSO" -mhlist(1), mhshow(1), mhstore(1), -.br +.IR mhlist (1), +.IR mhshow (1), +.IR mhstore (1) +.PP .I "Proposed Standard for Message Encapsulation" -(RFC\-934), -.br +(RFC 934), +.PP +.I "The Content-MD5 Header Field" +(RFC 1864), +.PP .I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies" -(RFC\-2045), -.br +(RFC 2045), +.PP .I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types" -(RFC\-2046), -.br +(RFC 2046), +.PP .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text" -(RFC\-2047), -.br +(RFC 2047), +.PP .I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures" -(RFC\-2048), -.br +(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 ' @@ -679,10 +726,6 @@ mhlist(1), mhshow(1), mhstore(1), .RB ` \-norfc934mode ' .RB ` \-contentid ' .RB ` \-nocheck ' -.RB ` \-noebcdicsafe ' .RB ` \-noverbose ' +.RB ` \-autoheaderencoding ' .fi - -.SH CONTEXT -If a folder is given, it will become the current folder. The last -message selected will become the current message.