-.TH MHBUILD %manext1% "January 23, 2014" "%nmhversion%"
+.TH MHBUILD %manext1% "December 14, 2014" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
.RB [ \-rfc934mode " | " \-norfc934mode ]
.RB [ \-contentid " | " \-nocontentid ]
.RB [ \-verbose " | " \-noverbose ]
+.RB [ \-disposition " | " \-nodisposition ]
.RB [ \-check " | " \-nocheck ]
-.RB [ \-headerencoding
+.RB [ \-headerencoding
.IR encoding\-algorithm
.RB " | " \-autoheaderencoding ]
.RB [ \-maxunencoded
.B mhbuild
creates multi-media messages as specified in RFC 2045
to RFC 2049. This includes the encoding of message headers as specified
-by RFC 2047.
+by RFC 2047, and the encoding of MIME parameters as specified in RFC 2231.
.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
+If the
+.B \-disposition
+switch is present, then the listing will show any relevant information from
+the \*(lqContent-Disposition\*(rq header.
.SS "Simplified Attachment Interface"
For users who wish to simply attach files to text content,
.B mhbuild
directives (see below). See
.IR send (1)
for more details.
+.PP
+By default, the Content-Disposition will be \*(lqattachment\*(rq.
+.B mhbuild
+looks for user profile and mhn.defaults entries of the form
+.PP
+.RS 5
+mhbuild-disposition-<type>/<subtype>
+.RE
+or
+.RS 5
+mhbuild-disposition-<type>
+.RE
+.PP
+to supply the disposition value. The only supported values are
+.I attachment
+and
+.IR inline.
+.SS "Convert Interface"
+.nr item 1 1
+The \*(lqconvert\*(rq interface is a powerful mechanism that supports
+replying to MIME messages. These placeholders are used in the following
+description:
+.IP TYPE
+content type/subtype
+.IP CONVERTER
+external program, and any fixed arguments, to convert content, such as
+from a request to a reply
+.IP ARGSTRING
+arguments to pass from
+.B repl
+to
+.I CONVERTER
+.IP FILE
+full path of message being replied to
+.PP
+.RE
+The convert support is based on pseudoheaders of the form
+.PP
+.RS 5
+ Nmh-mhbuild-file-TYPE: FILE
+ Nmh-mhbuild-args-TYPE: ARGSTRING
+.RE
+.PP
+in the draft. For each such pseudoheader, mhbuild looks in the
+profile and mhn.defaults for this corresponding TYPE entry to find the
+converter that supports it:
+.PP
+.RS 5
+.RI mhbuild-convert- TYPE :
+.I CONVERTER
+.RE
+.PP
+It's a fatal error if no such entry is found for TYPE. An empty
+entry, e.g.,
+.PP
+.RS 5
+mhbuild-convert-text/html:
+.RE
+.PP
+excludes parts of that TYPE from the draft. The mhn.defaults file
+contains default
+.B mhbuild-convert-text/html
+and
+.BR mhbuild-convert-text/plain
+entries. Profile entries can be used to override corresponding
+mhn.defaults entries, as usual.
+.PP
+For each
+.I TYPE
+part in
+.IR FILE ,
+.B mhbuild
+runs
+.I CONVERTER ARGSTRING
+on the content of the part.
+.PP
+Each part in
+.I FILE
+that has no corresponding TYPE entry in the profile or mhn.defaults is
+excluded from the draft; the user can include them using mhbuild
+directives as usual.
+.PP
+.B repl
+inserts Nmh-mhbuild-text/html: and Nmh-mhbuild-text/plain:
+pseudoheaders in every draft. The user can prevent insertion of
+content parts of either of those types by putting corresponding empty
+entries in their profile.
+.PP
+Only the highest precedence alternative with a supported
+.I TYPE
+of a multipart/alternative part is used.
+.PP
+mhn.defaults.sh selects the text/html-to-text/plain converter at
+install time. It includes
+.BR iconv "(1),"
+and
+.BR par (1)
+or
+.BR fmt "(1),"
+in the pipeline only if found.
+.PP
+Some content types require the addition of parameters to the
+Content-Type header, such as
+.I method=REPLY
+for text/calendar. mhbuild looks for a Content-Type header, followed
+by a blank line, at the beginning of the converter output. If one is
+found, it is used for the corresponding part in the reply draft.
+.PP
+The \*(lqconvert\*(rq interface doesn't support different
+.IR ARGSTRING s
+or different converters for different parts of the same
+.IR TYPE .
+That would require associating parts by part number with the
+.IR ARGSTRING s
+or converters. Instead, that can be done (currently, without using
+the convert support), with
+.B mhbuild
+directives as described below, e.g.,
+.PP
+.RS 5
+#text/html; charset=utf-8 *8bit | mhstore -noverbose -part 42.7 -outfile - | w3m -dump -cols 64 -T text/html -O utf-8
+.RE
+.PP
+The only way to mix
+.B convert
+pseudoheaders and mhbuild directives is to insert the directives before
+.B mhbuild
+is run, which is typically done by entering
+.I mime
+at the \*(lqWhat now?\*(rq prompt, or with an
+.B \-editor mhbuild
+switch.
+.PP
+These (optional) setup steps can make the convert support
+easier to use:
+.IP \n[item]. 3
+If the
+.BR par (1)
+program is installed on your system, it will be set by default
+(in mhn.defaults) to filter the converter output. It helps to
+set the
+.B $PARINIT
+environment variable, as described in its man page.
+.IP \n+[item]. 3
+Add this line to your profile:
+.PP
+.RS 5
+.nf
+mhbuild-next: $EDITOR
+.fi
+.RE
+.PP
+.RS 3
+assuming that your EDTIOR environment variable is set; if not, replace
+$EDITOR with the name of your editor. Without that profile entry, a
+response of \*(lqe[dit]\*(rq at the What now? prompt will require
+specification of your editor if an
+.B \-editor mhbuild
+switch is used.
+.RE
+.IP \n+[item]. 3
+If using
+.BR repl ,
+source the Bourne-shell compatible functions in
+.IR %docdir%/contrib/replaliases .
+.br
+That script also sets the
+.B $PARINIT
+environment variable if it was not set.
+.RE
+.PP
.SS "Translating the Composition File"
.B mhbuild
is essentially a filter to aid in the composition of MIME
.nf
#off
#include <stdio.h>
-printf("Hello, World!);
+printf("Hello, World!");
#pop
.fi
.RE
.fi
.RE
.PP
-Any long URLs will be wrapped according to RFC 2017 rules.
+Any long URLs will be wrapped according to RFC 2231 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
and the MIME Content\-Type. However, you can override that in an
.B mhbuild
directive by specifying \*(lq*\*(rq and the encoding. Acceptable encoding
-values are \*(lq8bit\*(rq, \*(lqqp\(*rq (for quoted\-printable), and
+values are \*(lq8bit\*(rq, \*(lqqp\*(rq (for quoted\-printable), and
\*(lqb64\*(rq (for base64 encoding). It should be noted that undesired
results may occur if 8bit or quoted\-printable is selected for binary
content, due to the translation between Unix line endings and the line
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
+for based\-64 encoding and
.I quoted
for quoted\-printable encoding. The
.B \-autoheaderencoding
.PP
Normally it is an error to invoke
.B mhbuild
-on file that already in MIME format. The
+on file that already in MIME format. The
.B \-auto
switch will cause
.B mhbuild
.PP
Finally,
.B mhbuild
-will attempt to consult a global
-.B mhbuild
-user profile, e.g.,
+will attempt to consult
.PP
.RS 5
-%etcdir%/mhn.defaults
+%nmhetcdir%/mhn.defaults
.RE
.PP
if it exists.
+.PP
+See "Profile Lookup" in
+.IR mh-profile (5)
+for the profile search order, and for how duplicate entries are treated.
.SS "Syntax of Composition Files"
The following is the formal syntax of a
.B mhbuild
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
+.RI \*(lq %nmhetcdir% \*(rq
is checked.
.PP
.fc ^ ~
.nf
-.ta \w'%etcdir%/ExtraBigFileName 'u
+.ta \w'%nmhetcdir%/ExtraBigFileName 'u
^$HOME/\&.mh\(ruprofile~^The user profile
^$MHBUILD~^Additional profile entries
-^%etcdir%/mhn.defaults~^System default MIME profile entries
+^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
.fi
.SH "PROFILE COMPONENTS"
.fc ^ ~
.SH "SEE ALSO"
.IR mhlist (1),
.IR mhshow (1),
-.IR mhstore (1)
+.IR mhstore (1),
+.IR fmt (1),
+.IR iconv (1),
+.IR par (1)
.PP
.I "Proposed Standard for Message Encapsulation"
(RFC 934),
(RFC 2048),
.PP
.I "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples"
-(RFC 2049)
+(RFC 2049),
+.PP
.I "Definition of the URL MIME External-Body Access-Type"
-(RFC 2017)
+(RFC 2017),
+.PP
+.I "MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations"
+(RFC 2231)
.SH DEFAULTS
.nf
.RB ` \-headers '
.RB ` \-contentid '
.RB ` \-nocheck '
.RB ` \-noverbose '
+.RB ` \-nodisposition '
.RB ` \-autoheaderencoding '
.RB ` "\-maxunencoded\ 78"'
.fi
projects / nmh / blobdiff