--- /dev/null
+.\"
+.\" %nmhwarning%
+.\"
+.TH MHBUILD %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
+.SH NAME
+mhbuild \- translate MIME composition draft
+.SH SYNOPSIS
+.na
+.HP 5
+.B mhbuild
+.I file
+.RB [ \-list " | " \-nolist ]
+.RB [ \-realsize " | " \-norealsize ]
+.RB [ \-headers " | " \-noheaders ]
+.RB [ \-ebcdicsafe " | " \-noebcdicsafe ]
+.RB [ \-rfc934mode " | " \-norfc934mode ]
+.RB [ \-contentid " | " \-nocontentid ]
+.RB [ \-verbose " | " \-noverbose ]
+.RB [ \-check " | " \-nocheck ]
+.RB [ \-version ]
+.RB [ \-help ]
+.ad
+.SH DESCRIPTION
+The
+.B mhbuild
+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.
+.PP
+If you specify the name of the composition file as \*(lq-\*(rq,
+then
+.B mhbuild
+will accept the composition draft on the standard
+input. If the translation of this input is successful,
+.B mhbuild
+will output the new MIME message to the standard output. This argument
+must be the last argument on the command line.
+.PP
+Otherwise if the file argument to
+.B mhbuild
+is the name of a valid
+composition file, and the translation is successful,
+.B mhbuild
+will replace the original file with the new MIME message. It will rename
+the original file to start with the \*(lq,\*(rq character and end with the
+string \*(lq.orig\*(rq, e.g., if you are editing the file \*(lqdraft\*(rq,
+it will be renamed to \*(lq,draft.orig\*(rq. This allows you to easily
+recover the
+.B mhbuild
+input file.
+.SS "Listing the Contents"
+The
+.B \-list
+switch tells
+.B mhbuild
+to list the table of contents associated with the MIME message that is created.
+.PP
+The
+.B \-headers
+switch indicates
+that a one-line banner should be displayed above the listing. The
+.B \-realsize
+switch tells
+.B mhbuild
+to evaluate the \*(lqnative\*(rq
+(decoded) format of each content prior to listing. This provides an
+accurate count at the expense of a small delay. If the
+.B \-verbose
+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.
+.SS "Translating the Composition File"
+.B mhbuild
+is essentially a filter to aid in the composition of MIME
+messages.
+.B mhbuild
+will convert an
+.B mhbuild
+\*(lqcomposition file\*(rq
+into a valid MIME message. A
+.B mhbuild
+\*(lqcomposition file\*(rq
+is just a file containing plain text that is interspersed
+with various
+.B mhbuild
+directives. When this file is processed
+by
+.BR mhbuild ,
+the various directives will be expanded to the
+appropriate content, and will be encoded according to the MIME standards.
+The resulting MIME message can then be sent by electronic mail.
+.PP
+The formal syntax for a
+.B mhbuild
+composition file is defined at the
+end of this document, but the ideas behind this format are not complex.
+Basically, the body contains one or more contents. A content consists of
+either a directive, indicated with a \*(lq#\*(rq as the first character
+of a line; or, plaintext (one or more lines of text). The continuation
+character, \*(lq\\\*(lq, may be used to enter a single directive on more
+than one line, e.g.,
+.PP
+.RS 5
+.nf
+#image/png \\
+ /home/foobar/junk/picture.png
+.fi
+.RE
+.PP
+There are four 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.
+.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
+(can't specify the types multipart or message with this directive).
+You may optionally specify the name of a file containing the contents
+in \*(lqnative\*(rq (decoded) format. If this filename starts with the
+\*(lq|\*(rq character, then it represents a command to execute whose
+output is captured accordingly.
+For example,
+.PP
+.RS 5
+.nf
+#audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
+.fi
+.RE
+.PP
+If a filename is not given,
+.B mhbuild
+will look for information in the
+user's profile to determine how the different contents should be composed.
+This is accomplished by consulting a composition string, and executing
+it under
+.BR /bin/sh ,
+with the standard output set to the content.
+If the
+.B \-verbose
+switch is given,
+.B mhbuild
+will echo any commands that are used to create contents in this way.
+.PP
+The composition string may contain the following escapes:
+.PP
+.RS 5
+.nf
+.ta \w'%P 'u
+%a Insert parameters from directive
+%f Insert filename containing content
+%F %f, and stdout is not re-directed
+%s Insert content subtype
+%% Insert character %
+.fi
+.RE
+.PP
+First,
+.B mhbuild
+will look for an entry of the form:
+.PP
+.RS 5
+mhbuild-compose-<type>/<subtype>
+.RE
+.PP
+to determine the command to use to compose the content. If this isn't
+found,
+.B mhbuild
+will look for an entry of the form:
+.PP
+.RS 5
+mhbuild-compose-<type>
+.RE
+.PP
+to determine the composition command. If this isn't found,
+.B mhbuild
+will complain.
+.PP
+An example entry might be:
+.PP
+.RS 5
+mhbuild-compose-audio/basic: record | raw2audio -F
+.RE
+.PP
+Because commands like these will vary, depending on the display
+environment used for login, composition strings for different
+contents should probably be put in the file specified by the
+.B $MHBUILD
+environment variable, instead of directly in your
+user profile.
+.PP
+The \*(lqexternal-type\*(rq directives are used to provide a MIME
+reference to a content, rather than enclosing the contents itself
+(for instance, by specifying an ftp site). Hence, instead of
+providing a filename as with the type directives, external-parameters
+are supplied. These look like regular parameters, so they must be
+separated accordingly. For example,
+.PP
+.RS 5
+.nf
+#@application/octet-stream; \\
+ type=tar; \\
+ conversions=compress \\
+ [this is the nmh distribution] \\
+ {application; filename="nmh.tar.gz"} \\
+ name="nmh.tar.gz"; \\
+ directory="/pub/nmh"; \\
+ site="ftp.math.gatech.edu"; \\
+ access-type=anon-ftp; \\
+ mode="image"
+.fi
+.RE
+.PP
+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. 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
+name= filename
+permission= read-only or read-write
+site= hostname
+directory= directoryname (optional)
+mode= usually \fIascii\fR or \fIimage\fR (optional)
+size= number of octets
+server= mailbox
+subject= subject to send
+body= command to send for retrieval
+.fi
+.RE
+.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
+given, it defaults to the current folder. Similarly, if a message is not
+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.
+For example,
+.PP
+.RS 5
+.nf
+#forw +inbox 42 43 99
+.fi
+.RE
+.PP
+If you include a single message, it will be included directly as a content
+of type \*(lqmessage/rfc822\*(rq. If you include more than one message,
+then
+.B mhbuild
+will add a content of type \*(lqmultipart/digest\*(rq
+and include each message as a subpart of this content.
+.PP
+If you are using this directive to include more than one message, you
+may use the
+.B \-rfc934mode
+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
+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
+newline at the end of the body of each message.
+.PP
+The \*(lqbegin\*(rq directive is used to create a multipart content.
+When using the \*(lqbegin\*(rq directive, you must specify at least one
+content between the begin and end pairs.
+.PP
+.RS 5
+.nf
+#begin
+This will be a multipart with only one part.
+#end
+.fi
+.RE
+.PP
+If you use multiple directives in a composition draft,
+.B mhbuild
+will
+automatically encapsulate them inside a multipart content. Therefore the
+\*(lqbegin\*(rq directive is only necessary if you wish to use nested
+multiparts, or create a multipart message containing only one part.
+.PP
+For all of these directives, the user may include a brief description
+of the content between the \*(lq[\*(rq character and the \*(lq]\*(rq
+character. This description will be copied into the
+\*(lqContent-Description\*(rq header when the directive is processed.
+.PP
+.RS 5
+.nf
+#forw [important mail from Bob] +bob 1 2 3 4 5
+.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,
+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
+exhausted, and this is made to form a text content. If the plaintext
+must contain a \*(lq#\*(rq at the beginning of a line, simply double it,
+e.g.,
+.PP
+.RS 5
+##when sent, this line will start with only one #
+.RE
+.PP
+If you want to end the plaintext prior to a directive, e.g., to have two
+plaintext contents adjacent, simply insert a line containing a single
+\*(lq#\*(rq character, e.g.,
+.PP
+.RS 5
+.nf
+this is the first content
+#
+and this is the second
+.fi
+.RE
+.PP
+Finally, if the plaintext starts with a line of the form:
+.PP
+.RS 5
+Content-Description: text
+.RE
+.PP
+then this will be used to describe the plaintext content.
+You MUST follow this line with a blank line before starting
+your text.
+.PP
+By default, plaintext is captured as a text/plain content. You can
+override this by starting the plaintext with \*(lq#<\*(rq followed by
+a content-type specification. For example, e.g.,
+.PP
+.RS 5
+.nf
+#<text/enriched
+this content will be tagged as text/enriched
+#
+and this content will be tagged as text/plain
+#
+#<application/x-patch [this is a patch]
+and this content will be tagged as application/x-patch
+.fi
+.RE
+.PP
+Note that if you use the \*(lq#<\*(rq plaintext-form, then the
+content-description must be on the same line which identifies the content
+type of the plaintext.
+.PP
+When composing a text content, you may indicate the relevant character
+set by adding the \*(lqcharset\*(rq parameter to the directive.
+.PP
+.RS 5
+#<text/plain; charset=iso-8859-5
+.RE
+.PP
+If a text content contains any 8\-bit characters (characters with the
+high bit set) and the character set is not specified as above, then
+.B mhbuild
+will assume the character set is of the type given by the
+environment variable MM_CHARSET. If this environment variable is not
+set, then the character set will be labeled as \*(lqx-unknown\*(rq.
+.PP
+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
+Putting this all together,
+here is an example of a more complicated message draft. The
+following draft will expand into a multipart/mixed message
+containing five parts:
+.PP
+.RS 5
+.nf
+To: nobody@nowhere.org
+cc:
+Subject: Look and listen to me!
+--------
+The first part will be text/plain
+#<text/enriched
+The second part will be text/enriched
+#
+This third part will be text/plain
+#audio/basic [silly giggle] \\
+ |raw2audio -F < /usr/lib/sounds/giggle.au
+#image/gif [photo of foobar] \\
+ /home/foobar/lib/picture.gif
+.fi
+.RE
+.SS "Integrity Check"
+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.
+
+.SS "Transfer Encodings"
+After
+.B mhbuild
+constructs the new MIME message by parsing directives,
+including files, etc., it scans the contents of the message to determine
+which transfer encoding to use. It will check for 8bit data, long lines,
+spaces at the end of lines, and clashes with multipart boundaries. It will
+then choose a transfer encoding appropriate for each content type.
+.PP
+If an integrity check is being associated with each content by using
+the
+.B \-check
+switch, then
+.B mhbuild
+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
+.B whatnow
+program. This
+command will expect the body of the draft to be formatted as an
+.B mhbuild
+composition file. Once you have composed this input file
+using a command such as
+.BR comp ,
+.BR repl ,
+or
+.BR forw ,
+you invoke
+.B mhbuild
+at the \*(lqWhat now\*(rq prompt with
+.PP
+.RS 5
+What now? mime
+.RE
+.PP
+prior to sending the draft. This will cause
+.B whatnow
+to execute
+.B mhbuild
+to translate the composition file into MIME format.
+.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 .mmh/profile
+file.
+.PP
+Finally, you should consider adding this line to your profile:
+.PP
+.RS 5
+lproc: show
+.RE
+.PP
+This way, if you decide to
+.B list
+after invoking
+.BR mime ,
+the command
+.PP
+.RS 5
+What now? list
+.RE
+.PP
+will work as you expect.
+
+.SS "User Environment"
+Because the environment in which
+.B mhbuild
+operates may vary for a
+user,
+.B mhbuild
+will look for the environment variable
+.BR $MHBUILD .
+If present, this specifies the name of an additional user profile which
+should be read. Hence, when a user logs in on a particular machine,
+this environment variable should be set to refer to a file containing
+definitions useful for that machine.
+.PP
+Finally,
+.B mhbuild
+will attempt to consult a global
+.B mhbuild
+user profile, e.g.,
+.PP
+.RS 5
+%etcdir%/mhn.defaults
+.RE
+.PP
+if it exists.
+
+.SS "Syntax of Composition Files"
+The following is the formal syntax of a
+.B mhbuild
+\*(lqcomposition file\*(rq.
+.PP
+.RS 5
+.nf
+body ::= 1*(content | EOL)
+
+content ::= directive | plaintext
+
+directive ::= "#" type "/" subtype
+ 0*(";" attribute "=" value)
+ [ "(" comment ")" ]
+ [ "<" id ">" ]
+ [ "[" description "]" ]
+ [ "{" disposition "}" ]
+ [ filename ]
+ EOL
+
+ | "#@" type "/" subtype
+ 0*(";" attribute "=" value)
+ [ "(" comment ")" ]
+ [ "<" id ">" ]
+ [ "[" description "]" ]
+ [ "{" disposition "}" ]
+ external-parameters
+ EOL
+
+ | "#forw"
+ [ "<" id ">" ]
+ [ "[" description "]" ]
+ [ "{" disposition "}" ]
+ [ "+"folder ] [ 0*msg ]
+ EOL
+
+ | "#begin"
+ [ "<" id ">" ]
+ [ "[" description "]" ]
+ [ "{" disposition "}" ]
+ [ "alternative"
+ | "parallel"
+ | something-else ]
+ EOL
+ 1*body
+ "#end" EOL
+
+plaintext ::= [ "Content-Description:"
+ description EOL EOL ]
+ 1*line
+ [ "#" EOL ]
+
+ | "#<" type "/" subtype
+ 0*(";" attribute "=" value)
+ [ "(" comment ")" ]
+ [ "[" description "]" ]
+ [ "{" disposition "}" ]
+ EOL
+ 1*line
+ [ "#" EOL ]
+
+line ::= "##" text EOL
+ -- interpreted as "#"text EOL
+ | text EOL
+.fi
+.RE
+.PP
+
+.SH FILES
+.fc ^ ~
+.nf
+.ta \w'%etcdir%/ExtraBigFileName 'u
+^$HOME/.mmh/profile~^The user profile
+^$MHBUILD~^Additional profile entries
+^%etcdir%/mhn.defaults~^System default MIME profile entries
+.fi
+
+.SH "PROFILE COMPONENTS"
+.fc ^ ~
+.nf
+.ta 2.4i
+.ta \w'ExtraBigProfileName 'u
+^Path:~^To determine the user's mail storage
+^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
+.I "Proposed Standard for Message Encapsulation"
+(RFC\-934),
+.br
+.I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
+(RFC\-2045),
+.br
+.I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
+(RFC\-2046),
+.br
+.I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text"
+(RFC\-2047),
+.br
+.I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures"
+(RFC\-2048),
+.br
+.I "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples"
+(RFC\-2049)
+
+.SH DEFAULTS
+.nf
+.RB ` \-headers '
+.RB ` \-realsize '
+.RB ` \-norfc934mode '
+.RB ` \-contentid '
+.RB ` \-nocheck '
+.RB ` \-noebcdicsafe '
+.RB ` \-noverbose '
+.fi
+
+.SH CONTEXT
+If a folder is given, it will become the current folder. The last
+message selected will become the current message.
projects / mmh / blobdiff