-.\"
+.TH MHBUILD %manext1% 2016-10-15 "%nmhversion%"
+.
.\" %nmhwarning%
-.\" $Id$
-.\"
-.\" include the -mh macro file
-.so %etcdir%/tmac.h
-.\"
-.TH MHBUILD %manext1% MH.6.8 [%nmhversion%]
+.
.SH NAME
-mhbuild \- translate MIME composition draft
+mhbuild \- translate MIME composition drafts for nmh messages
.SH SYNOPSIS
-.in +.5i
-.ti -.5i
-mhbuild file
-.br
-\%[\-list] \%[-nolist]
-\%[\-realsize] \%[\-norealsize]
-.br
-\%[\-headers] \%[\-noheaders]
-\%[\-ebcdicsafe] \%[\-noebcdicsafe]
-.br
-\%[\-rfc934mode] \%[\-norfc934mode]
-\%[\-verbose] \%[\-noverbose]
-.br
-\%[\-check] \%[\-nocheck]
-\%[\-version]
-\%[\-help]
-.in -.5i
+.na
+.HP 5
+.B mhbuild
+.RB [ \-help ]
+.RB [ \-version ]
+.I file
+.RB [ \-auto " | " \-noauto ]
+.RB [ \-list " | " \-nolist ]
+.RB [ \-realsize " | " \-norealsize ]
+.RB [ \-headers " | " \-noheaders ]
+.RB [ \-directives " | " \-nodirectives ]
+.RB [ \-rfc934mode " | " \-norfc934mode ]
+.RB [ \-contentid " | " \-nocontentid ]
+.RB [ \-verbose " | " \-noverbose ]
+.RB [ \-disposition " | " \-nodisposition ]
+.RB [ \-check " | " \-nocheck ]
+.RB [ \-headerencoding
+.I encoding-algorithm
+.RB " | " \-autoheaderencoding ]
+.RB [ \-maxunencoded
+.IR line-length ]
+.RB [ \-dist ]
+.ad
.SH DESCRIPTION
-The \fImhbuild\fR command will translate a MIME composition draft into
-a valid MIME message.
-
-\fImhbuild\fR creates multi-media messages as specified in RFC\-2045
-thru RFC\-2049. Currently \fImhbuild\fR only supports encodings in
-message bodies, and does not support the encoding of message headers as
-specified in RFC\-2047.
-
-If you specify the name of the composition file as \*(lq-\*(rq,
-then \fImhbuild\fR will accept the composition draft on the standard
-input. If the translation of this input is successful, \fImhbuild\fR
-will output the new MIME message to the standard output. This argument
-must be the last argument on the command line.
-
-Otherwise if the file argument to \fImhbuild\fR is the name of a valid
-composition file, and the translation is successful, \fImhbuild\fR 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 \fImhbuild\fR input file.
-
-.Uh "Listing the Contents"
-The `\-list' switch tells \fImhbuild\fR to list the table of contents
-associated with the MIME message that is created.
-
-The `\-headers' switch indicates
-that a one-line banner should be displayed above the listing. The
-`\-realsize' switch tells \fImhbuild\fR 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 `\-verbose' switch
+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 RFCs 2045 through 2049.
+This includes the encoding of message headers as specified by RFC 2047,
+and, additionally, the encoding of MIME parameters as specified in RFC 2231.
+.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 Content-Type header.
-
-.Uh "Translating the Composition File"
-\fImhbuild\fR is essentially a filter to aid in the composition of MIME
-messages. \fImhbuild\fR will convert an
-\fImhbuild\fR \*(lqcomposition file\*(rq
-into a valid MIME message. A \fImhbuild\fR \*(lqcomposition file\*(rq
-is just a file containing plain text that is interspersed
-with various \fImhbuild\fR directives. When this file is processed
-by \fImhbuild\fR, the various directives will be expanded to the
-appropriate content, and will be encoded according to the MIME standards.
+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
+will scan the composition file for \*(lqAttach\*(rq headers.
+An \*(lqAttach\*(rq header contains a filename that will be appended to the
+message using normal MIME encapsulation rules. One filename is allowed
+per \*(lqAttach\*(rq header, but multiple \*(lqAttach\*(rq headers are
+allowed per composition file.
+.PP
+These files will be appended after any other MIME content, including any
+content specified by
+.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
+.I mhn.defaults
+entries of the form
+.PP
+.RS 5
+.BI mhbuild-disposition- type / subtype
+.RE
+or
+.RS 5
+.BI mhbuild-disposition- type
+.RE
+.PP
+to supply the disposition value. The only supported values are
+\*(lqattachment\*(rq
+and
+\*(lqinline\*(rq.
+.SS "Convert Interface"
+The convert interface is a powerful mechanism that supports
+replying to MIME messages.
+These placeholders are used in the following description:
+.RS 5
+.TP 15
+.PD 0
+TYPE
+content type/subtype
+.TP
+CONVERTER
+external program, and any fixed arguments, to convert content, such as
+from a request to a reply
+.TP
+ARGSTRING
+arguments to pass from
+.B repl
+to
+.I CONVERTER
+.TP
+FILE
+full path of message being replied to
+.PD
+.RE
+The convert support is based on pseudoheaders of the form
+.PP
+.RS 5
+.nf
+.BI Nmh-mhbuild-file- TYPE : \0FILE
+.BI Nmh-mhbuild-args- TYPE : \0ARGSTRING
+.fi
+.RE
+.PP
+in the draft.
+For each such pseudoheader, mhbuild looks in the profile and
+.I mhn.defaults
+for the corresponding
+.I TYPE
+entry to find the converter that supports it:
+.PP
+.RS 5
+.BI mhbuild-convert- TYPE : \0CONVERTER
+.RE
+.PP
+It's a fatal error if no such entry is found for
+.IR TYPE .
+An empty entry, e.g.,
+.PP
+.RS 5
+.B mhbuild-convert-text/html:
+.RE
+.PP
+excludes parts of that
+.I TYPE
+from the draft.
+.PP
+The
+.I mhn.defaults
+file contains default
+.B mhbuild-convert-text/html
+and
+.B mhbuild-convert-text/plain
+entries. Profile entries can be used to override corresponding
+.I mhn.defaults
+entries, as usual. Text converters should limit text line lengths
+to a maximum of 78 characters, and must limit them to a maximum of 998
+characters, per RFC 5322 Sec.\& 2.1.1.
+.PP
+For each
+.I TYPE
+part in
+.IR FILE ,
+.B mhbuild
+runs
+.I CONVERTER ARGSTRING
+on the content of the part.
+Each part in
+.I FILE
+that has no corresponding TYPE entry in the profile or
+.I mhn.defaults
+is
+excluded from the draft; the user can include them using mhbuild directives.
+.PP
+.B repl
+inserts
+.B Nmh-mhbuild-text/html:
+and
+.B 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
+.B iconv
+and
+.BR par ,
+or
+.BR fmt ,
+in the pipeline only if they are found.
+.PP
+Some content types require the addition of parameters to the
+Content-Type header, such as \*(lqmethod=REPLY\*(rq
+for text/calendar.
+.B 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 convert 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 convert pseudoheaders and
+.B 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:
+.TP 5
+1)
+If the
+.B par
+program is installed on your system, it will be set by default
+(in
+.IR mhn.defaults )
+to filter the converter output. It helps to set the PARINIT
+environment variable, as described in
+.IR par (1).
+.TP 5
+2)
+Add this line to your profile:
+.IP "" 10
+mhbuild-next: $EDITOR
+.IP "" 5
+assuming that your EDITOR 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.
+.TP 5
+3)
+If using
+.BR repl ,
+source the Bourne-shell compatible functions in
+.IR %docdir%/contrib/replaliases .
+.br
+That script also sets the PARINIT environment variable if it was not set.
+.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.
+An
+.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.
-
-The formal syntax for a \fImhbuild\fR composition file is defined at the
-end of this document, but the ideas behind this format are not complex.
+.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.,
-.sp
+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
-.in +.5i
#image/png \\
/home/foobar/junk/picture.png
-.in -.5i
.fi
-.sp
-There are four kinds of directives: \*(lqtype\*(rq directives, which
+.RE
+.PP
+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
(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.
+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,
-.sp
+.PP
+.RS 5
.nf
-.in +.5i
#audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
-.in -.5i
.fi
-.sp
-If a filename is not given, \fImhbuild\fR will look for information in the
+.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 \fB/bin/sh\fR, with the standard output set to the content.
-If the `\-verbose' switch is given, \fImhbuild\fR will echo any commands
-that are used to create contents in this way.
-.ne 13
+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:
-.sp
-.nf
-.in +.5i
-.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 %
-.re
-.in -.5i
-.fi
-.sp
-
+.PP
+.RS 5
+.PD 0
+.IP %a
+Insert parameters from directive
+.IP %f
+Insert filename containing content
+.IP %F
+%f, and stdout is not re-directed
+.IP %s
+Insert content subtype
+.IP %%
+Insert character %
+.PD
+.RE
+.PP
First,
-\fImhbuild\fR will look for an entry of the form:
-.sp
-.in +.5i
-mhbuild-compose-<type>/<subtype>
-.in -.5i
-.sp
-to determine the command to use to compose the content. If this isn't
-found, \fImhbuild\fR will look for an entry of the form:
-.sp
-.in +.5i
-mhbuild-compose-<type>
-.in -.5i
-.sp
-to determine the composition command.
-
-If this isn't found, \fImhbuild\fR
+.B mhbuild
+will look for an entry of the form:
+.PP
+.RS 5
+.BI 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
+.BI 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:
-.sp
-.in +.5i
+.PP
+.RS 5
mhbuild-compose-audio/basic: record | raw2audio -F
-.in -.5i
-.sp
+.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
-\fB$MHBUILD\fR environment variable, instead of directly in your
+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,
-.sp
+(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
-.in +.5i
#@application/octet-stream; \\
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"; \\
access-type=anon-ftp; \\
mode="image"
-.in -.5i
.fi
-.sp
+.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.
-.ne 19
+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:
-.sp
+.PP
+.RS 5
.nf
-.in +.5i
.ta \w'access-type= 'u
-access-type= usually \fIanon-ftp\fR or \fImail-server\fR
+access-type= usually \*(lqanon-ftp\*(rq, \*(lqmail-server\*(rq, or \*(lqurl\*(rq
name= filename
permission= read-only or read-write
site= hostname
directory= directoryname (optional)
-mode= usually \fIascii\fR or \fIimage\fR (optional)
+mode= usually \*(lqascii\*(rq or \*(lqimage\*(rq (optional)
size= number of octets
server= mailbox
subject= subject to send
body= command to send for retrieval
-.re
-.in -.5i
+url= URL of content
.fi
-.sp
-
+.RE
+.PP
+A minimum \*(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 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
-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 \fIforw\fR\0(1) command, except that the former uses
-the MIME rules for encapsulation rather than those specified in RFC\-934.
+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,
-.sp
+.PP
+.RS 5
.nf
-.in +.5i
#forw +inbox 42 43 99
-.in -.5i
.fi
-.sp
+.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 \fImhbuild\fR will add a content of type \*(lqmultipart/digest\*(rq
+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 `\-rfc934mode' switch. This switch will indicate that
-\fImhbuild\fR 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
+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.
-
+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.
-.sp
+.PP
+.RS 5
.nf
-.in +.5i
#begin
This will be a multipart with only one part.
#end
-.in -.5i
.fi
-.sp
-If you use multiple directives in a composition draft, \fImhbuild\fR 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.
-
+.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.
-.sp
+character.
+This description will be copied into the \*(lqContent-Description\*(rq header
+when the directive is processed.
+.PP
+.RS 5
.nf
-.in +.5i
#forw [important mail from Bob] +bob 1 2 3 4 5
-.in -.5i
.fi
-.sp
-By default, \fImhbuild\fR 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.
-
+.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
+Normally
+.B mhbuild
+will choose an appropriate Content\-Transfer\-Encoding based on the content
+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 \*(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 endings use by the mail transport system.
+.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,
-.ne 6
+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.,
-.sp
-.in +.5i
+.PP
+.RS 5
##when sent, this line will start with only one #
-.in -.5i
-.sp
+.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,
-.ne 10
-e.g.,
-.sp
+\*(lq#\*(rq character, e.g.,
+.PP
+.RS 5
.nf
-.in +.5i
this is the first content
#
and this is the second
-.in -.5i
.fi
-.sp
-Finally,
-if the plaintext starts with a line of the form:
-.sp
-.in +.5i
+.RE
+.PP
+Finally, if the plaintext starts with a line of the form:
+.PP
+.RS 5
Content-Description: text
-.in -.5i
-.sp
+.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.
-
-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,
-.ne 11
-e.g.,
-.sp
+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
-.in +.5i
#<text/enriched
this content will be tagged as text/enriched
#
#
#<application/x-patch [this is a patch]
and this content will be tagged as application/x-patch
-.in -.5i
.fi
-.sp
+.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.
-.sp
-.in +.5i
+.PP
+.RS 5
#<text/plain; charset=iso-8859-5
-.in -.5i
-.sp
-If a text content contains any 8bit characters (characters with the
+.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
-\fImhbuild\fR 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.
-
-If a text content contains only 7bit characters and the character set
+.B mhbuild
+will assume the character set is of the type given by the standard
+.IR locale (1)
+environment variables.
+If these environment variables are 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
-
-Putting this all together,
-.ne 15
-here is an example of a more complicated message draft. The
-following draft will expand into a multipart/mixed message
-containing five parts:
-.sp
+\*(lqus-ascii\*(rq.
+.PP
+By default text content with the high bit set is encoded with an 8-bit
+Content-Transfer-Encoding.
+If the text has lines longer than the value of
+.B \-maxunencoded
+(which defaults to 78) then the text is encoded using the quoted-printable
+encoding.
+.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 base-64 encoding,
+.I quoted
+for quoted-printable encoding, and
+.I utf\-8
+which requires that all 8-bit header field bodies be encoded as UTF-8
+(RFC 6530) and that the message be sent to a SMTP server that supports
+SMTPUTF8 (RFC 6531).
+The
+.B \-autoheaderencoding
+switch instructs
+.B mhbuild
+to automatically pick the encoding, either base64 or quoted-printable,
+that results in a shorter encoded string.
+.PP
+Putting this all together, here is an example of a more complex message draft,
+which will expand into a multipart/mixed message containing five parts:
+.PP
+.RS 5
.nf
-.in +.5i
To: nobody@nowhere.org
cc:
Subject: Look and listen to me!
|raw2audio -F < /usr/lib/sounds/giggle.au
#image/gif [photo of foobar] \\
/home/foobar/lib/picture.gif
-.in -.5i
.fi
-.sp
-.Uh "Integrity Check"
-If \fImhbuild\fR is given the `-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.
-
-.Uh "Transfer Encodings"
-After \fImhbuild\fR 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.
-
+.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, 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
+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 8-bit 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 `\-check' switch, then \fImhbuild\fR will encode each content with
-a transfer encoding, even it the content contains only 7bit data. This
-is to increase the likelihood that the content is not changed while in
+the
+.B \-check
+switch, then
+.B mhbuild
+will encode each content with
+a transfer encoding, even if the content contains only 7-bit data.
+This is to increase the likelihood that the content is not changed while in
transport.
-
-The switch `\-ebcdicsafe' will cause \fImhbuild\fR to slightly change
-the way in which it performs the \*(lqquoted-printable\*(rq transfer
-encoding. Along with encoding 8bit 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.
-
-.Uh "Invoking mhbuild"
-Typically, \fImhbuild\fR is invoked by the \fIwhatnow\fR program. This
-command will expect the body of the draft to be formatted as an
-\fImhbuild\fR composition file. Once you have composed this input file
-using a command such as \fIcomp\fR, \fIrepl\fR, or \fIforw\fR, you invoke
-\fImhbuild\fR at the \*(lqWhat now\*(rq prompt with
-.sp
-.in +.5i
+.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 forw ,
+or
+.BR repl ,
+you invoke
+.B mhbuild
+at the \*(lqWhat now\*(rq prompt with
+.PP
+.RS 5
What now? mime
-.in -.5i
-.sp
-prior to sending the draft. This will cause \fIwhatnow\fR to execute
-\fImhbuild\fR to translate the composition file into MIME format.
-
-It is also possible to have the \fIwhatnow\fR program invoke \fImhbuild\fR
-automatically when a message is sent. To do this, you must add the line
-.sp
-.in +.5i
-automimeproc: 1
-.in -.5i
-.sp
-to your \&.mh\(ruprofile file.
-
+.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
+Normally it is an error to invoke
+.B mhbuild
+on a file that is already in MIME format.
+The
+.B \-auto
+switch will cause
+.B mhbuild
+to exit without error if the input file already has valid MIME headers.
+The use of
+.B \-auto
+also enables the
+.B \-nodirectives
+switch.
+.PP
Finally, you should consider adding this line to your profile:
-.sp
-.in +.5i
+.PP
+.RS 5
lproc: show
-.in -.5i
-.sp
-This way, if you decide to \fBlist\fR after invoking \fImime\fR,
+.RE
+.PP
+This way, if you decide to
+.B list
+after invoking
+.BR mime ,
the command
-.sp
-.in +.5i
+.PP
+.RS 5
What now? list
-.in -.5i
-.sp
+.RE
+.PP
will work as you expect.
-
-.Uh "User Environment"
-Because the environment in which \fImhbuild\fR operates may vary for a
-user, \fImhbuild\fR will look for the environment variable \fB$MHBUILD\fR.
+.PP
+The
+.B \-dist
+switch is intended to be used by
+.BR dist .
+It will cause mhbuild to not generate any MIME headers in the composition
+file (such as \*(lqMIME-Version\*(rq or \*(lqContent-Type\*(rq), but it
+will still encode message headers according to RFC 2047.
+.SS "User Environment"
+Because the environment in which
+.B mhbuild
+operates may vary for a user,
+.B mhbuild
+will look for the environment variable 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.
-
-Finally, \fImhbuild\fR will attempt to consult a global \fImhbuild\fR
-user profile,
-.ne 6
-e.g.,
-.sp
-.in +.5i
-%etcdir%/mhn.defaults
-.in -.5i
-.sp
+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
+on that machine.
+.PP
+Finally,
+.B mhbuild
+will attempt to consult
+.PP
+.RS 5
+%nmhetcdir%/mhn.defaults
+.RE
+.PP
if it exists.
-
-.Uh "Syntax of Composition Files"
-.ne 59
-The following is the formal syntax of a \fImhbuild\fR
+.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
\*(lqcomposition file\*(rq.
-.sp
+.PP
+.RS 5
.nf
-.in +.5i
- body ::= 1*(content | EOL)
-
- content ::= directive | plaintext
-
- directive ::= "#" type "/" subtype
- 0*(";" attribute "=" value)
- [ "(" comment ")" ]
- [ "<" id ">" ]
- [ "[" description "]" ]
- [ filename ]
- EOL
-
- | "#@" type "/" subtype
- 0*(";" attribute "=" value)
- [ "(" comment ")" ]
- [ "<" id ">" ]
- [ "[" description "]" ]
- external-parameters
- EOL
-
- | "#forw"
- [ "<" id ">" ]
- [ "[" description "]" ]
- [ "+"folder ] [ 0*msg ]
- EOL
-
- | "#begin"
- [ "<" id ">" ]
- [ "[" description "]" ]
- [ "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 "]" ]
- EOL
- 1*line
- [ "#" EOL ]
-
- line ::= "##" text EOL
- -- interpreted as "#"text EOL
- | text EOL
-.in -.5i
+body ::= 1*(content | EOL)
+
+content ::= directive | plaintext
+
+directive ::= "#" type "/" subtype
+ 0*(";" attribute "=" value)
+ [ "(" comment ")" ]
+ [ "<" id ">" ]
+ [ "[" description "]" ]
+ [ "{" disposition "}" ]
+ [ "*8bit" | "*qp" | "*b64" ]
+ [ filename ]
+ EOL
+
+ | "#@" type "/" subtype
+ 0*(";" attribute "=" value)
+ [ "(" comment ")" ]
+ [ "<" id ">" ]
+ [ "[" description "]" ]
+ [ "{" disposition "}" ]
+ [ "*8bit" | "*qp" | "*b64" ]
+ 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 "}" ]
+ [ "*8bit" | "*qp" | "*b64" ]
+ EOL
+ 1*line
+ [ "#" EOL ]
+
+line ::= "##" text EOL
+ -- interpreted as "#"text EOL
+ | text EOL
+.fi
+.RE
+.SH FILES
+.B mhbuild
+looks for additional user profile files and
+.I 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 %nmhetcdir% \*(rq
+is checked.
+.PP
+.PD 0
+.TP 20
+$HOME/.mh_profile
+The user's profile.
+.TP
+$MHBUILD
+Additional profile entries.
+.TP
+%nmhetcdir%/mhn.defaults
+System default MIME profile entries.
+.PD
+.SH "PROFILE COMPONENTS"
+.PD 0
+.TP 20
+Path:
+To determine the user's nmh directory.
+.TP
+Current\-Folder:
+To find the default current folder.
+.TP
+.RI mhbuild-compose- type* :
+Template for composing contents.
+.PD
+.SH "SEE ALSO"
+.IR mhlist (1),
+.IR mhshow (1),
+.IR mhstore (1)
+.PP
+.I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
+(RFC 2045)
+.PP
+.I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
+(RFC 2046)
+.PP
+.I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text"
+(RFC 2047)
+.PP
+.I "Internet Message Format"
+(RFC 5322)
+.PP
+.I "MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations"
+(RFC 2231)
+.PP
+.I "Proposed Standard for Message Encapsulation"
+(RFC 934)
+.PP
+.I "The Content-MD5 Header Field"
+(RFC 1864)
+.PP
+.I "Definition of the URL MIME External-Body Access-Type"
+(RFC 2017)
+.PP
+.I "Overview and Framework for Internationalized Email"
+(RFC 6530)
+.PP
+.I "SMTP Extension for Internationalized Email"
+(RFC 6531)
+.SH DEFAULTS
+.nf
+\-autoheaderencoding
+\-contentid
+\-headers
+\-maxunencoded 78
+\-nocheck
+\-nodisposition
+\-norfc934mode
+\-noverbose
+\-realsize
.fi
-.sp
-.Fi
-^$HOME/\&.mh\(ruprofile~^The user profile
-^$MHBUILD~^Additional profile entries
-^%etcdir%/mhn.defaults~^System default MIME profile entries
-.Pr
-^Path:~^To determine the user's nmh directory
-.Ps
-^Current\-Folder:~^To find the default current folder
-.Ps
-^mhbuild-compose-<type>*~^Template for composing contents
-.Sa
-mhlist(1), mhshow(1), mhstore(1)
-.br
-RFC\-934:
-.br
- \fIProposed Standard for Message Encapsulation\fR,
-.br
-RFC\-2045:
-.br
- \fIMultipurpose Internet Mail Extensions (MIME) Part One:
-.br
- Format of Internet Message Bodies\fR,
-.br
-RFC\-2046:
-.br
- \fIMultipurpose Internet Mail Extensions (MIME) Part Two:
-.br
- Media Types\fR,
-.br
-RFC\-2047:
-.br
- \fIMultipurpose Internet Mail Extensions (MIME) Part Three:
-.br
- Message Header Extensions for Non-ASCII Text\fR,
-.br
-RFC\-2048:
-.br
- \fIMultipurpose Internet Mail Extensions (MIME) Part Four:
-.br
- Registration Procedures\fR,
-.br
-RFC\-2049:
-.br
- \fIMultipurpose Internet Mail Extensions (MIME) Part Five:
-.br
- Conformance Criteria and Examples\fR.
-.De
-`\-headers'
-.Ds
-`\-realsize'
-.Ds
-`\-norfc934mode'
-.Ds
-`\-nocheck'
-.Ds
-`\-noebcdicsafe'
-.Ds
-`\-noverbose'
-.Co
-If a folder is given, it will become the current folder. The last
-message selected will become the current message.
-.En
projects / nmh / blobdiff