1 .TH MHBUILD %manext1% "March 13, 2014" "%nmhversion%"
6 mhbuild \- translate MIME composition draft
12 .RB [ \-auto " | " \-noauto ]
13 .RB [ \-list " | " \-nolist ]
14 .RB [ \-realsize " | " \-norealsize ]
15 .RB [ \-headers " | " \-noheaders ]
16 .RB [ \-directives " | " \-nodirectives ]
17 .RB [ \-rfc934mode " | " \-norfc934mode ]
18 .RB [ \-contentid " | " \-nocontentid ]
19 .RB [ \-verbose " | " \-noverbose ]
20 .RB [ \-disposition " | " \-nodisposition ]
21 .RB [ \-check " | " \-nocheck ]
22 .RB [ \-headerencoding
23 .IR encoding\-algorithm
24 .RB " | " \-autoheaderencoding ]
34 command will translate a MIME composition draft into
38 creates multi-media messages as specified in RFC 2045
39 to RFC 2049. This includes the encoding of message headers as specified
40 by RFC 2047, and the encoding of MIME parameters as specified in RFC 2231.
42 If you specify the name of the composition file as \*(lq-\*(rq,
45 will accept the composition draft on the standard
46 input. If the translation of this input is successful,
48 will output the new MIME message to the standard output. This argument
49 must be the last argument on the command line.
51 Otherwise if the file argument to
53 is the name of a valid
54 composition file, and the translation is successful,
56 will replace the original file with the new MIME message. It will rename
57 the original file to start with the \*(lq,\*(rq character and end with the
58 string \*(lq.orig\*(rq, e.g., if you are editing the file \*(lqdraft\*(rq,
59 it will be renamed to \*(lq,draft.orig\*(rq. This allows you to easily
63 .SS "Listing the Contents"
68 to list the table of contents associated with the MIME message that is created.
73 that a one-line banner should be displayed above the listing. The
77 to evaluate the \*(lqnative\*(rq
78 (decoded) format of each content prior to listing. This provides an
79 accurate count at the expense of a small delay. If the
82 is present, then the listing will show any \*(lqextra\*(rq information
83 that is present in the message, such as comments in the
84 \*(lqContent-Type\*(rq header.
88 switch is present, then the listing will show any relevant information from
89 the \*(lqContent-Disposition\*(rq header.
90 .SS "Simplified Attachment Interface"
91 For users who wish to simply attach files to text content,
93 will scan the composition file for \*(lqAttach\*(rq headers. An
94 \*(lqAttach\*(rq header contains a filename that will be appended to the
95 message using normal MIME encapsulation rules. One filename is allowed
96 per \*(lqAttach\*(rq header, but multiple \*(lqAttach\*(rq headers are
97 allowed ber composition file.
99 These files will be appended after any other MIME content, including any
102 directives (see below). See
106 By default, the Content-Disposition will be \*(lqattachment\*(rq.
108 looks for user profile and mhn.defaults entries of the form
111 mhbuild-disposition-<type>/<subtype>
115 mhbuild-disposition-<type>
118 to supply the disposition value. The only supported values are
122 .SS "Translating the Composition File"
124 is essentially a filter to aid in the composition of MIME
129 \*(lqcomposition file\*(rq
130 into a valid MIME message. A
132 \*(lqcomposition file\*(rq
133 is just a file containing plain text that is interspersed
136 directives. When this file is processed
139 the various directives will be expanded to the
140 appropriate content, and will be encoded according to the MIME standards.
141 The resulting MIME message can then be sent by electronic mail.
143 The formal syntax for a
145 composition file is defined at the
146 end of this document, but the ideas behind this format are not complex.
147 Basically, the body contains one or more contents. A content consists of
148 either a directive, indicated with a \*(lq#\*(rq as the first character
149 of a line; or, plaintext (one or more lines of text). The continuation
150 character, \*(lq\\\*(lq, may be used to enter a single directive on more
156 /home/foobar/junk/picture.png
160 There are five kinds of directives: \*(lqtype\*(rq directives, which
161 name the type and subtype of the content; \*(lqexternal-type\*(rq
162 directives, which also name the type and subtype of the content; the
163 \*(lqmessage\*(rq directive (#forw), which is used to forward one or
164 more messages; the \*(lqbegin\*(rq directive (#begin), which is
165 used to create a multipart content; and the \*(lqon/off/pop\*(rq
166 directives (#on, #off, #pop) which control whether any other
167 directives are honored at all.
171 switch allows control over whether mhbuild will honor any of the
172 \*(lq#\*(rq-directives. This can also be affected with the #on or
173 #off directives, and #pop, which restores the state of processing to
174 that preceding the most recent #on or #off. (The #on, #off, and #pop
175 directives are always honored, of course.) This allows inclusion of
176 plain text which looks like mhbuild directives, without causing
183 printf("Hello, World!);
188 Currently the stack depth for the #on/off/pop directives is 32.
190 The \*(lqtype\*(rq directive is used to directly specify the type and
191 subtype of a content. You may only specify discrete types in this manner
192 (can't specify the types multipart or message with this directive).
193 You may optionally specify the name of a file containing the contents
194 in \*(lqnative\*(rq (decoded) format. If this filename starts with the
195 \*(lq|\*(rq character, then it represents a command to execute whose
196 output is captured accordingly.
201 #audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
205 If a filename is not given,
207 will look for information in the
208 user's profile to determine how the different contents should be composed.
209 This is accomplished by consulting a composition string, and executing
212 with the standard output set to the content.
217 will echo any commands that are used to create contents in this way.
219 The composition string may contain the following escapes:
224 %a Insert parameters from directive
225 %f Insert filename containing content
226 %F %f, and stdout is not re-directed
227 %s Insert content subtype
228 %% Insert character %
234 will look for an entry of the form:
237 mhbuild-compose-<type>/<subtype>
240 to determine the command to use to compose the content. If this isn't
243 will look for an entry of the form:
246 mhbuild-compose-<type>
249 to determine the composition command. If this isn't found,
253 An example entry might be:
256 mhbuild-compose-audio/basic: record | raw2audio -F
259 Because commands like these will vary, depending on the display
260 environment used for login, composition strings for different
261 contents should probably be put in the file specified by the
263 environment variable, instead of directly in your
266 The \*(lqexternal-type\*(rq directives are used to provide a MIME
267 reference to a content, rather than enclosing the contents itself
268 (for instance, by specifying an ftp site). Hence, instead of
269 providing a filename as with the type directives, external-parameters
270 are supplied. These look like regular parameters, so they must be
271 separated accordingly. For example,
275 #@application/octet-stream; \\
277 conversions=compress \\
278 [this is the nmh distribution] \\
279 {attachment; filename="nmh.tar.gz"} \\
280 name="nmh.tar.gz"; \\
281 directory="/pub/nmh"; \\
282 site="ftp.math.gatech.edu"; \\
283 access-type=anon-ftp; \\
288 You must give a description string to separate the content parameters
289 from the external-parameters (although this string may be empty).
290 This description string is specified by enclosing it within
291 \*(lq[]\*(rq. A disposition string, to appear in a
292 \*(lqContent-Disposition\*(rq header, may appear in the optional
295 These parameters are of the form:
299 .ta \w'access-type= 'u
300 access-type= usually \fIanon-ftp\fR, \fImail-server\fR, or \fIurl\fR
302 permission= read-only or read-write
304 directory= directoryname (optional)
305 mode= usually \fIascii\fR or \fIimage\fR (optional)
306 size= number of octets
308 subject= subject to send
309 body= command to send for retrieval
314 A mimimum \*(lqexternal\-type\*(rq directive for the
321 #@application/octet-stream [] access-type=url; \\
322 url="http://download.savannah.gnu.org/releases/nmh/nmh-1.5.tar.gz"
326 Any long URLs will be wrapped according to RFC 2231 rules.
328 The \*(lqmessage\*(rq directive (#forw) is used to specify a message or
329 group of messages to include. You may optionally specify the name of
330 the folder and which messages are to be forwarded. If a folder is not
331 given, it defaults to the current folder. Similarly, if a message is not
332 given, it defaults to the current message. Hence, the message directive
335 command, except that the former uses
336 the MIME rules for encapsulation rather than those specified in RFC 934.
341 #forw +inbox 42 43 99
345 If you include a single message, it will be included directly as a content
346 of type \*(lqmessage/rfc822\*(rq. If you include more than one message,
349 will add a content of type \*(lqmultipart/digest\*(rq
350 and include each message as a subpart of this content.
352 If you are using this directive to include more than one message, you
355 switch. This switch will indicate that
357 should attempt to utilize the MIME encapsulation rules
358 in such a way that the \*(lqmultipart/digest\*(rq that is created
359 is (mostly) compatible with the encapsulation specified in RFC 934.
360 If given, then RFC 934 compliant user-agents should be able to burst the
361 message on reception\0--\0providing that the messages being encapsulated
362 do not contain encapsulated messages themselves. The drawback of this
363 approach is that the encapsulations are generated by placing an extra
364 newline at the end of the body of each message.
366 The \*(lqbegin\*(rq directive is used to create a multipart content.
367 When using the \*(lqbegin\*(rq directive, you must specify at least one
368 content between the begin and end pairs.
373 This will be a multipart with only one part.
378 If you use multiple directives in a composition draft,
381 automatically encapsulate them inside a multipart content. Therefore the
382 \*(lqbegin\*(rq directive is only necessary if you wish to use nested
383 multiparts, or create a multipart message containing only one part.
385 For all of these directives, the user may include a brief description
386 of the content between the \*(lq[\*(rq character and the \*(lq]\*(rq
387 character. This description will be copied into the
388 \*(lqContent-Description\*(rq header when the directive is processed.
392 #forw [important mail from Bob] +bob 1 2 3 4 5
396 Similarly, a disposition string may optionally be provided between
397 \*(lq{\*(rq and \*(lq}\*(rq characters; it will be copied into the
398 \*(lqContent-Disposition\*(rq header when the directive is processed.
399 If a disposition string is provided that does not contain a filename
400 parameter, and a filename is provided in the directive, it will be
401 added to the \*(lqContent-Disposition\*(rq header. For example, the
406 #text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt
410 creates these message part headers:
414 Content-Type: text/plain; charset="iso-8859-1"
415 Content-Disposition: attachment; filename="summary.txt"
421 will generate a unique \*(lqContent-ID:\*(rq for each directive,
422 corresponding to each message part; however, the user may override
423 this by defining the ID using the \*(lq<\*(rq and \*(lq>\*(rq
426 switch suppresses creation of all \*(lqContent-ID:\*(rq headers,
427 even in the top level of the message.
431 will choose an appropriate Content\-Transfer\-Encoding based on the content
432 and the MIME Content\-Type. However, you can override that in an
434 directive by specifying \*(lq*\*(rq and the encoding. Acceptable encoding
435 values are \*(lq8bit\*(rq, \*(lqqp\(*rq (for quoted\-printable), and
436 \*(lqb64\*(rq (for base64 encoding). It should be noted that undesired
437 results may occur if 8bit or quoted\-printable is selected for binary
438 content, due to the translation between Unix line endings and the line
439 endings use by the mail transport system.
441 In addition to the various directives, plaintext can be present.
442 Plaintext is gathered, until a directive is found or the draft is
443 exhausted, and this is made to form a text content. If the plaintext
444 must contain a \*(lq#\*(rq at the beginning of a line, simply double it,
448 ##when sent, this line will start with only one #
451 If you want to end the plaintext prior to a directive, e.g., to have two
452 plaintext contents adjacent, simply insert a line containing a single
453 \*(lq#\*(rq character, e.g.,
457 this is the first content
459 and this is the second
463 Finally, if the plaintext starts with a line of the form:
466 Content-Description: text
469 then this will be used to describe the plaintext content.
470 You MUST follow this line with a blank line before starting
473 By default, plaintext is captured as a text/plain content. You can
474 override this by starting the plaintext with \*(lq#<\*(rq followed by
475 a content-type specification. For example, e.g.,
480 this content will be tagged as text/enriched
482 and this content will be tagged as text/plain
484 #<application/x-patch [this is a patch]
485 and this content will be tagged as application/x-patch
489 Note that if you use the \*(lq#<\*(rq plaintext-form, then the
490 content-description must be on the same line which identifies the content
491 type of the plaintext.
493 When composing a text content, you may indicate the relevant character
494 set by adding the \*(lqcharset\*(rq parameter to the directive.
497 #<text/plain; charset=iso-8859-5
500 If a text content contains any 8\-bit characters (characters with the
501 high bit set) and the character set is not specified as above, then
503 will assume the character set is of the type given by the
506 environment variables. If these environment variables are not
507 set, then the character set will be labeled as \*(lqx-unknown\*(rq.
509 If a text content contains only 7\-bit characters and the character set
510 is not specified as above, then the character set will be labeled as
513 By default text content with the high bit set is encoded with a 8bit
514 Content\-Transfer\-Encoding. If the text has lines longer than the value
517 (which defaults to 78) then the text is encoded using the quoted\-printable
522 switch will indicate which algorithm to use when encoding any message headers
523 that contain 8\-bit characters. The valid arguments are
525 for based\-64 encoding and
527 for quoted\-printable encoding. The
528 .B \-autoheaderencoding
531 to automatically pick the algorithm that results in a shorter encoded string.
533 Putting this all together,
534 here is an example of a more complicated message draft. The
535 following draft will expand into a multipart/mixed message
536 containing five parts:
540 To: nobody@nowhere.org
542 Subject: Look and listen to me!
544 The first part will be text/plain
546 The second part will be text/enriched
548 This third part will be text/plain
549 #audio/basic [silly giggle] \\
550 |raw2audio -F < /usr/lib/sounds/giggle.au
551 #image/gif [photo of foobar] \\
552 /home/foobar/lib/picture.gif
555 .SS "Integrity Check"
560 switch, then it will also associate an integrity check with each
561 \*(lqleaf\*(rq content. This will add a Content-MD5 header field to
562 the content, along with the md5 sum of the unencoded contents, per RFC
563 1864. This may be used by the receiver of the message to verify that
564 the contents of the message were not changed in transport.
565 .SS "Transfer Encodings"
568 constructs the new MIME message by parsing directives,
569 including files, etc., it scans the contents of the message to determine
570 which transfer encoding to use. It will check for 8bit data, long lines,
571 spaces at the end of lines, and clashes with multipart boundaries. It will
572 then choose a transfer encoding appropriate for each content type.
574 If an integrity check is being associated with each content by using
579 will encode each content with
580 a transfer encoding, even it the content contains only 7\-bit data. This
581 is to increase the likelihood that the content is not changed while in
583 .SS "Invoking mhbuild"
589 command will expect the body of the draft to be formatted as an
591 composition file. Once you have composed this input file
592 using a command such as
599 at the \*(lqWhat now\*(rq prompt with
605 prior to sending the draft. This will cause
609 to translate the composition file into MIME format.
611 Normally it is an error to invoke
613 on file that already in MIME format. The
617 to exit without error if the input file already has valid MIME headers.
624 Finally, you should consider adding this line to your profile:
630 This way, if you decide to
640 will work as you expect.
644 switch is intended to be used by
646 It will cause mhbuild to not generate any MIME headers in the composition
647 file (such as \*(lqMIME-Version\*(rq or \*(lqContent-Type\*(rq), but it
648 will still encode message headers according to RFC 2047.
649 .SS "User Environment"
650 Because the environment in which
652 operates may vary for a
655 will look for the environment variable
657 If present, this specifies the name of an additional user profile which
658 should be read. Hence, when a user logs in on a particular machine,
659 this environment variable should be set to refer to a file containing
660 definitions useful for that machine.
664 will attempt to consult
667 %etcdir%/mhn.defaults
672 See "Profile Lookup" in
674 for the profile search order, and for how duplicate entries are treated.
675 .SS "Syntax of Composition Files"
676 The following is the formal syntax of a
678 \*(lqcomposition file\*(rq.
682 body ::= 1*(content | EOL)
684 content ::= directive | plaintext
686 directive ::= "#" type "/" subtype
687 0*(";" attribute "=" value)
690 [ "[" description "]" ]
691 [ "{" disposition "}" ]
692 [ "*8bit" | "*qp" | "*b64" ]
696 | "#@" type "/" subtype
697 0*(";" attribute "=" value)
700 [ "[" description "]" ]
701 [ "{" disposition "}" ]
702 [ "*8bit" | "*qp" | "*b64" ]
708 [ "[" description "]" ]
709 [ "{" disposition "}" ]
710 [ "+"folder ] [ 0*msg ]
715 [ "[" description "]" ]
716 [ "{" disposition "}" ]
724 plaintext ::= [ "Content-Description:"
725 description EOL EOL ]
729 | "#<" type "/" subtype
730 0*(";" attribute "=" value)
732 [ "[" description "]" ]
733 [ "{" disposition "}" ]
734 [ "*8bit" | "*qp" | "*b64" ]
739 line ::= "##" text EOL
740 -- interpreted as "#"text EOL
746 looks for additional user profile files and mhn.defaults in multiple
747 locations: absolute pathnames are accessed directly, tilde expansion
748 is done on usernames, and files are searched for in the user's
750 directory as specified in their profile. If not found there, the directory
751 .RI \*(lq %etcdir% \*(rq
756 .ta \w'%etcdir%/ExtraBigFileName 'u
757 ^$HOME/\&.mh\(ruprofile~^The user profile
758 ^$MHBUILD~^Additional profile entries
759 ^%etcdir%/mhn.defaults~^System default MIME profile entries
761 .SH "PROFILE COMPONENTS"
765 .ta \w'ExtraBigProfileName 'u
766 ^Path:~^To determine the user's nmh directory
767 ^Current\-Folder:~^To find the default current folder
768 ^mhbuild-compose-<type>*~^Template for composing contents
775 .I "Proposed Standard for Message Encapsulation"
778 .I "The Content-MD5 Header Field"
781 .I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
784 .I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
787 .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text"
790 .I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures"
793 .I "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples"
796 .I "Definition of the URL MIME External-Body Access-Type"
799 .I "MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations"
805 .RB ` \-norfc934mode '
809 .RB ` \-nodisposition '
810 .RB ` \-autoheaderencoding '
811 .RB ` "\-maxunencoded\ 78"'
projects / nmh / blob