1 .TH MHBUILD %manext1% "January 23, 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 [ \-check " | " \-nocheck ]
21 .RB [ \-headerencoding
22 .IR encoding\-algorithm
23 .RB " | " \-autoheaderencoding ]
33 command will translate a MIME composition draft into
37 creates multi-media messages as specified in RFC 2045
38 to RFC 2049. This includes the encoding of message headers as specified
41 If you specify the name of the composition file as \*(lq-\*(rq,
44 will accept the composition draft on the standard
45 input. If the translation of this input is successful,
47 will output the new MIME message to the standard output. This argument
48 must be the last argument on the command line.
50 Otherwise if the file argument to
52 is the name of a valid
53 composition file, and the translation is successful,
55 will replace the original file with the new MIME message. It will rename
56 the original file to start with the \*(lq,\*(rq character and end with the
57 string \*(lq.orig\*(rq, e.g., if you are editing the file \*(lqdraft\*(rq,
58 it will be renamed to \*(lq,draft.orig\*(rq. This allows you to easily
62 .SS "Listing the Contents"
67 to list the table of contents associated with the MIME message that is created.
72 that a one-line banner should be displayed above the listing. The
76 to evaluate the \*(lqnative\*(rq
77 (decoded) format of each content prior to listing. This provides an
78 accurate count at the expense of a small delay. If the
81 is present, then the listing will show any \*(lqextra\*(rq information
82 that is present in the message, such as comments in the
83 \*(lqContent-Type\*(rq header.
84 .SS "Simplified Attachment Interface"
85 For users who wish to simply attach files to text content,
87 will scan the composition file for \*(lqAttach\*(rq headers. An
88 \*(lqAttach\*(rq header contains a filename that will be appended to the
89 message using normal MIME encapsulation rules. One filename is allowed
90 per \*(lqAttach\*(rq header, but multiple \*(lqAttach\*(rq headers are
91 allowed ber composition file.
93 These files will be appended after any other MIME content, including any
96 directives (see below). See
99 .SS "Translating the Composition File"
101 is essentially a filter to aid in the composition of MIME
106 \*(lqcomposition file\*(rq
107 into a valid MIME message. A
109 \*(lqcomposition file\*(rq
110 is just a file containing plain text that is interspersed
113 directives. When this file is processed
116 the various directives will be expanded to the
117 appropriate content, and will be encoded according to the MIME standards.
118 The resulting MIME message can then be sent by electronic mail.
120 The formal syntax for a
122 composition file is defined at the
123 end of this document, but the ideas behind this format are not complex.
124 Basically, the body contains one or more contents. A content consists of
125 either a directive, indicated with a \*(lq#\*(rq as the first character
126 of a line; or, plaintext (one or more lines of text). The continuation
127 character, \*(lq\\\*(lq, may be used to enter a single directive on more
133 /home/foobar/junk/picture.png
137 There are five kinds of directives: \*(lqtype\*(rq directives, which
138 name the type and subtype of the content; \*(lqexternal-type\*(rq
139 directives, which also name the type and subtype of the content; the
140 \*(lqmessage\*(rq directive (#forw), which is used to forward one or
141 more messages; the \*(lqbegin\*(rq directive (#begin), which is
142 used to create a multipart content; and the \*(lqon/off/pop\*(rq
143 directives (#on, #off, #pop) which control whether any other
144 directives are honored at all.
148 switch allows control over whether mhbuild will honor any of the
149 \*(lq#\*(rq-directives. This can also be affected with the #on or
150 #off directives, and #pop, which restores the state of processing to
151 that preceding the most recent #on or #off. (The #on, #off, and #pop
152 directives are always honored, of course.) This allows inclusion of
153 plain text which looks like mhbuild directives, without causing
160 printf("Hello, World!);
165 Currently the stack depth for the #on/off/pop directives is 32.
167 The \*(lqtype\*(rq directive is used to directly specify the type and
168 subtype of a content. You may only specify discrete types in this manner
169 (can't specify the types multipart or message with this directive).
170 You may optionally specify the name of a file containing the contents
171 in \*(lqnative\*(rq (decoded) format. If this filename starts with the
172 \*(lq|\*(rq character, then it represents a command to execute whose
173 output is captured accordingly.
178 #audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
182 If a filename is not given,
184 will look for information in the
185 user's profile to determine how the different contents should be composed.
186 This is accomplished by consulting a composition string, and executing
189 with the standard output set to the content.
194 will echo any commands that are used to create contents in this way.
196 The composition string may contain the following escapes:
201 %a Insert parameters from directive
202 %f Insert filename containing content
203 %F %f, and stdout is not re-directed
204 %s Insert content subtype
205 %% Insert character %
211 will look for an entry of the form:
214 mhbuild-compose-<type>/<subtype>
217 to determine the command to use to compose the content. If this isn't
220 will look for an entry of the form:
223 mhbuild-compose-<type>
226 to determine the composition command. If this isn't found,
230 An example entry might be:
233 mhbuild-compose-audio/basic: record | raw2audio -F
236 Because commands like these will vary, depending on the display
237 environment used for login, composition strings for different
238 contents should probably be put in the file specified by the
240 environment variable, instead of directly in your
243 The \*(lqexternal-type\*(rq directives are used to provide a MIME
244 reference to a content, rather than enclosing the contents itself
245 (for instance, by specifying an ftp site). Hence, instead of
246 providing a filename as with the type directives, external-parameters
247 are supplied. These look like regular parameters, so they must be
248 separated accordingly. For example,
252 #@application/octet-stream; \\
254 conversions=compress \\
255 [this is the nmh distribution] \\
256 {attachment; filename="nmh.tar.gz"} \\
257 name="nmh.tar.gz"; \\
258 directory="/pub/nmh"; \\
259 site="ftp.math.gatech.edu"; \\
260 access-type=anon-ftp; \\
265 You must give a description string to separate the content parameters
266 from the external-parameters (although this string may be empty).
267 This description string is specified by enclosing it within
268 \*(lq[]\*(rq. A disposition string, to appear in a
269 \*(lqContent-Disposition\*(rq header, may appear in the optional
272 These parameters are of the form:
276 .ta \w'access-type= 'u
277 access-type= usually \fIanon-ftp\fR, \fImail-server\fR, or \fIurl\fR
279 permission= read-only or read-write
281 directory= directoryname (optional)
282 mode= usually \fIascii\fR or \fIimage\fR (optional)
283 size= number of octets
285 subject= subject to send
286 body= command to send for retrieval
291 A mimimum \*(lqexternal\-type\*(rq directive for the
298 #@application/octet-stream [] access-type=url; \\
299 url="http://download.savannah.gnu.org/releases/nmh/nmh-1.5.tar.gz"
303 Any long URLs will be wrapped according to RFC 2017 rules.
305 The \*(lqmessage\*(rq directive (#forw) is used to specify a message or
306 group of messages to include. You may optionally specify the name of
307 the folder and which messages are to be forwarded. If a folder is not
308 given, it defaults to the current folder. Similarly, if a message is not
309 given, it defaults to the current message. Hence, the message directive
312 command, except that the former uses
313 the MIME rules for encapsulation rather than those specified in RFC 934.
318 #forw +inbox 42 43 99
322 If you include a single message, it will be included directly as a content
323 of type \*(lqmessage/rfc822\*(rq. If you include more than one message,
326 will add a content of type \*(lqmultipart/digest\*(rq
327 and include each message as a subpart of this content.
329 If you are using this directive to include more than one message, you
332 switch. This switch will indicate that
334 should attempt to utilize the MIME encapsulation rules
335 in such a way that the \*(lqmultipart/digest\*(rq that is created
336 is (mostly) compatible with the encapsulation specified in RFC 934.
337 If given, then RFC 934 compliant user-agents should be able to burst the
338 message on reception\0--\0providing that the messages being encapsulated
339 do not contain encapsulated messages themselves. The drawback of this
340 approach is that the encapsulations are generated by placing an extra
341 newline at the end of the body of each message.
343 The \*(lqbegin\*(rq directive is used to create a multipart content.
344 When using the \*(lqbegin\*(rq directive, you must specify at least one
345 content between the begin and end pairs.
350 This will be a multipart with only one part.
355 If you use multiple directives in a composition draft,
358 automatically encapsulate them inside a multipart content. Therefore the
359 \*(lqbegin\*(rq directive is only necessary if you wish to use nested
360 multiparts, or create a multipart message containing only one part.
362 For all of these directives, the user may include a brief description
363 of the content between the \*(lq[\*(rq character and the \*(lq]\*(rq
364 character. This description will be copied into the
365 \*(lqContent-Description\*(rq header when the directive is processed.
369 #forw [important mail from Bob] +bob 1 2 3 4 5
373 Similarly, a disposition string may optionally be provided between
374 \*(lq{\*(rq and \*(lq}\*(rq characters; it will be copied into the
375 \*(lqContent-Disposition\*(rq header when the directive is processed.
376 If a disposition string is provided that does not contain a filename
377 parameter, and a filename is provided in the directive, it will be
378 added to the \*(lqContent-Disposition\*(rq header. For example, the
383 #text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt
387 creates these message part headers:
391 Content-Type: text/plain; charset="iso-8859-1"
392 Content-Disposition: attachment; filename="summary.txt"
398 will generate a unique \*(lqContent-ID:\*(rq for each directive,
399 corresponding to each message part; however, the user may override
400 this by defining the ID using the \*(lq<\*(rq and \*(lq>\*(rq
403 switch suppresses creation of all \*(lqContent-ID:\*(rq headers,
404 even in the top level of the message.
408 will choose an appropriate Content\-Transfer\-Encoding based on the content
409 and the MIME Content\-Type. However, you can override that in an
411 directive by specifying \*(lq*\*(rq and the encoding. Acceptable encoding
412 values are \*(lq8bit\*(rq, \*(lqqp\(*rq (for quoted\-printable), and
413 \*(lqb64\*(rq (for base64 encoding). It should be noted that undesired
414 results may occur if 8bit or quoted\-printable is selected for binary
415 content, due to the translation between Unix line endings and the line
416 endings use by the mail transport system.
418 In addition to the various directives, plaintext can be present.
419 Plaintext is gathered, until a directive is found or the draft is
420 exhausted, and this is made to form a text content. If the plaintext
421 must contain a \*(lq#\*(rq at the beginning of a line, simply double it,
425 ##when sent, this line will start with only one #
428 If you want to end the plaintext prior to a directive, e.g., to have two
429 plaintext contents adjacent, simply insert a line containing a single
430 \*(lq#\*(rq character, e.g.,
434 this is the first content
436 and this is the second
440 Finally, if the plaintext starts with a line of the form:
443 Content-Description: text
446 then this will be used to describe the plaintext content.
447 You MUST follow this line with a blank line before starting
450 By default, plaintext is captured as a text/plain content. You can
451 override this by starting the plaintext with \*(lq#<\*(rq followed by
452 a content-type specification. For example, e.g.,
457 this content will be tagged as text/enriched
459 and this content will be tagged as text/plain
461 #<application/x-patch [this is a patch]
462 and this content will be tagged as application/x-patch
466 Note that if you use the \*(lq#<\*(rq plaintext-form, then the
467 content-description must be on the same line which identifies the content
468 type of the plaintext.
470 When composing a text content, you may indicate the relevant character
471 set by adding the \*(lqcharset\*(rq parameter to the directive.
474 #<text/plain; charset=iso-8859-5
477 If a text content contains any 8\-bit characters (characters with the
478 high bit set) and the character set is not specified as above, then
480 will assume the character set is of the type given by the
483 environment variables. If these environment variables are not
484 set, then the character set will be labeled as \*(lqx-unknown\*(rq.
486 If a text content contains only 7\-bit characters and the character set
487 is not specified as above, then the character set will be labeled as
490 By default text content with the high bit set is encoded with a 8bit
491 Content\-Transfer\-Encoding. If the text has lines longer than the value
494 (which defaults to 78) then the text is encoded using the quoted\-printable
499 switch will indicate which algorithm to use when encoding any message headers
500 that contain 8\-bit characters. The valid arguments are
502 for based\-64 encoding and
504 for quoted\-printable encoding. The
505 .B \-autoheaderencoding
508 to automatically pick the algorithm that results in a shorter encoded string.
510 Putting this all together,
511 here is an example of a more complicated message draft. The
512 following draft will expand into a multipart/mixed message
513 containing five parts:
517 To: nobody@nowhere.org
519 Subject: Look and listen to me!
521 The first part will be text/plain
523 The second part will be text/enriched
525 This third part will be text/plain
526 #audio/basic [silly giggle] \\
527 |raw2audio -F < /usr/lib/sounds/giggle.au
528 #image/gif [photo of foobar] \\
529 /home/foobar/lib/picture.gif
532 .SS "Integrity Check"
537 switch, then it will also associate an integrity check with each
538 \*(lqleaf\*(rq content. This will add a Content-MD5 header field to
539 the content, along with the md5 sum of the unencoded contents, per RFC
540 1864. This may be used by the receiver of the message to verify that
541 the contents of the message were not changed in transport.
542 .SS "Transfer Encodings"
545 constructs the new MIME message by parsing directives,
546 including files, etc., it scans the contents of the message to determine
547 which transfer encoding to use. It will check for 8bit data, long lines,
548 spaces at the end of lines, and clashes with multipart boundaries. It will
549 then choose a transfer encoding appropriate for each content type.
551 If an integrity check is being associated with each content by using
556 will encode each content with
557 a transfer encoding, even it the content contains only 7\-bit data. This
558 is to increase the likelihood that the content is not changed while in
560 .SS "Invoking mhbuild"
566 command will expect the body of the draft to be formatted as an
568 composition file. Once you have composed this input file
569 using a command such as
576 at the \*(lqWhat now\*(rq prompt with
582 prior to sending the draft. This will cause
586 to translate the composition file into MIME format.
588 Normally it is an error to invoke
590 on file that already in MIME format. The
594 to exit without error if the input file already has valid MIME headers.
601 Finally, you should consider adding this line to your profile:
607 This way, if you decide to
617 will work as you expect.
621 switch is intended to be used by
623 It will cause mhbuild to not generate any MIME headers in the composition
624 file (such as \*(lqMIME-Version\*(rq or \*(lqContent-Type\*(rq), but it
625 will still encode message headers according to RFC 2047.
626 .SS "User Environment"
627 Because the environment in which
629 operates may vary for a
632 will look for the environment variable
634 If present, this specifies the name of an additional user profile which
635 should be read. Hence, when a user logs in on a particular machine,
636 this environment variable should be set to refer to a file containing
637 definitions useful for that machine.
641 will attempt to consult a global
646 %etcdir%/mhn.defaults
650 .SS "Syntax of Composition Files"
651 The following is the formal syntax of a
653 \*(lqcomposition file\*(rq.
657 body ::= 1*(content | EOL)
659 content ::= directive | plaintext
661 directive ::= "#" type "/" subtype
662 0*(";" attribute "=" value)
665 [ "[" description "]" ]
666 [ "{" disposition "}" ]
667 [ "*8bit" | "*qp" | "*b64" ]
671 | "#@" type "/" subtype
672 0*(";" attribute "=" value)
675 [ "[" description "]" ]
676 [ "{" disposition "}" ]
677 [ "*8bit" | "*qp" | "*b64" ]
683 [ "[" description "]" ]
684 [ "{" disposition "}" ]
685 [ "+"folder ] [ 0*msg ]
690 [ "[" description "]" ]
691 [ "{" disposition "}" ]
699 plaintext ::= [ "Content-Description:"
700 description EOL EOL ]
704 | "#<" type "/" subtype
705 0*(";" attribute "=" value)
707 [ "[" description "]" ]
708 [ "{" disposition "}" ]
709 [ "*8bit" | "*qp" | "*b64" ]
714 line ::= "##" text EOL
715 -- interpreted as "#"text EOL
721 looks for additional user profile files and mhn.defaults in multiple
722 locations: absolute pathnames are accessed directly, tilde expansion
723 is done on usernames, and files are searched for in the user's
725 directory as specified in their profile. If not found there, the directory
726 .RI \*(lq %etcdir% \*(rq
731 .ta \w'%etcdir%/ExtraBigFileName 'u
732 ^$HOME/\&.mh\(ruprofile~^The user profile
733 ^$MHBUILD~^Additional profile entries
734 ^%etcdir%/mhn.defaults~^System default MIME profile entries
736 .SH "PROFILE COMPONENTS"
740 .ta \w'ExtraBigProfileName 'u
741 ^Path:~^To determine the user's nmh directory
742 ^Current\-Folder:~^To find the default current folder
743 ^mhbuild-compose-<type>*~^Template for composing contents
750 .I "Proposed Standard for Message Encapsulation"
753 .I "The Content-MD5 Header Field"
756 .I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
759 .I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
762 .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text"
765 .I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures"
768 .I "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples"
770 .I "Definition of the URL MIME External-Body Access-Type"
776 .RB ` \-norfc934mode '
780 .RB ` \-autoheaderencoding '
781 .RB ` "\-maxunencoded\ 78"'
projects / nmh / blob