.\"
.\" %nmhwarning%
-.\" $Id$
.\"
.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 [ \-directives " | " \-nodirectives ]
.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
.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] \\
+ {application; 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
.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
[ "(" 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 ]
.SH FILES
.fc ^ ~
.nf
-.ta \w'/usr/local/nmh/etc/ExtraBigFileName 'u
+.ta \w'%etcdir%/ExtraBigFileName 'u
^$HOME/\&.mh\(ruprofile~^The user profile
^$MHBUILD~^Additional profile entries
^%etcdir%/mhn.defaults~^System default MIME profile entries
+.fi
.SH "PROFILE COMPONENTS"
.fc ^ ~
^Path:~^To determine the user's nmh directory
^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),
.RB ` \-headers '
.RB ` \-realsize '
.RB ` \-norfc934mode '
+.RB ` \-contentid '
.RB ` \-nocheck '
.RB ` \-noebcdicsafe '
.RB ` \-noverbose '
-
-.SH CONTEXT
-If a folder is given, it will become the current folder. The last
-message selected will become the current message.
+.fi