+.TH MHBUILD %manext1% "March 21, 2013" "%nmhversion%"
.\"
.\" %nmhwarning%
-.\" $Id$
.\"
-.TH MHBUILD %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
mhbuild \- translate MIME composition draft
.SH SYNOPSIS
.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
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
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
.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 <stdio.h>
+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
type=tar; \\
conversions=compress \\
[this is the nmh distribution] \\
+ {attachment; filename="nmh.tar.gz"} \\
name="nmh.tar.gz"; \\
directory="/pub/nmh"; \\
site="ftp.math.gatech.edu"; \\
You must give a description string to separate the content parameters
from the external-parameters (although this string may be empty).
This description string is specified by enclosing it within
-\*(lq[]\*(rq.
+\*(lq[]\*(rq. A disposition string, to appear in a
+\*(lqContent-Disposition\*(rq header, may appear in the optional
+\*(lq{}\*(rq.
.PP
These parameters are of the form:
.PP
.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
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
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
.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
.fi
.RE
.PP
+Similarly, a disposition string may optionally be provided between
+\*(lq{\*(rq and \*(lq}\*(rq characters; it will be copied into the
+\*(lqContent-Disposition\*(rq header when the directive is processed.
+If a disposition string is provided that does not contain a filename
+parameter, and a filename is provided in the directive, it will be
+added to the \*(lqContent-Disposition\*(rq header. For example, the
+following directive:
+.PP
+.RS 5
+.nf
+#text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt
+.fi
+.RE
+.PP
+creates these message part headers:
+.PP
+.RS 5
+.nf
+Content-Type: text/plain; charset="iso-8859-1"
+Content-Disposition: attachment; filename="summary.txt"
+.fi
+.RE
+.PP
By default,
.B mhbuild
-will generate a unique \*(lqContent-ID:\*(rq for
-each directive; however, the user may override this by defining the ID
-using the \*(lq<\*(rq and \*(lq>\*(rq characters.
+will generate a unique \*(lqContent-ID:\*(rq for each directive,
+corresponding to each message part; however, the user may override
+this by defining the ID using the \*(lq<\*(rq and \*(lq>\*(rq
+characters. The
+.B \-nocontentid
+switch suppresses creation of all \*(lqContent-ID:\*(rq headers,
+even in the top level of the message.
.PP
In addition to the various directives, plaintext can be present.
Plaintext is gathered, until a directive is found or the draft is
.RE
.SS "Integrity Check"
If
-.B Imhbuild
+.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
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
.RE
.PP
will work as you expect.
-
.SS "User Environment"
Because the environment in which
.B mhbuild
.RE
.PP
if it exists.
-
.SS "Syntax of Composition Files"
The following is the formal syntax of a
.B mhbuild
[ "(" comment ")" ]
[ "<" id ">" ]
[ "[" description "]" ]
+ [ "{" disposition "}" ]
[ filename ]
EOL
[ "(" comment ")" ]
[ "<" id ">" ]
[ "[" description "]" ]
+ [ "{" disposition "}" ]
external-parameters
EOL
| "#forw"
[ "<" id ">" ]
[ "[" description "]" ]
+ [ "{" disposition "}" ]
[ "+"folder ] [ 0*msg ]
EOL
| "#begin"
[ "<" id ">" ]
[ "[" description "]" ]
+ [ "{" disposition "}" ]
[ "alternative"
| "parallel"
| something-else ]
0*(";" attribute "=" value)
[ "(" comment ")" ]
[ "[" description "]" ]
+ [ "{" disposition "}" ]
EOL
1*line
[ "#" 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
^$MHBUILD~^Additional profile entries
^%etcdir%/mhn.defaults~^System default MIME profile entries
.fi
-
.SH "PROFILE COMPONENTS"
.fc ^ ~
.nf
^Current\-Folder:~^To find the default current folder
^mhbuild-compose-<type>*~^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 '
.RB ` \-realsize '
.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.
projects / nmh / blobdiff