4 .TH MHBUILD %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
6 mhbuild \- translate MIME composition draft
12 .RB [ \-list " | " \-nolist ]
13 .RB [ \-headers " | " \-noheaders ]
14 .RB [ \-contentid " | " \-nocontentid ]
15 .RB [ \-verbose " | " \-noverbose ]
22 command will translate a MIME composition draft into
26 creates multi-media messages as specified in RFC\-2045
27 thru RFC\-2049. Currently
29 only supports encodings in
30 message bodies, and does not support the encoding of message headers as
31 specified in RFC\-2047.
33 If you specify the name of the composition file as \*(lq-\*(rq,
36 will accept the composition draft on the standard
37 input. If the translation of this input is successful,
39 will output the new MIME message to the standard output. This argument
40 must be the last argument on the command line.
42 Otherwise if the file argument to
44 is the name of a valid
45 composition file, and the translation is successful,
47 will replace the original file with the new MIME message. It will rename
48 the original file to start with the \*(lq,\*(rq character and end with the
49 string \*(lq.orig\*(rq, e.g., if you are editing the file \*(lqdraft\*(rq,
50 it will be renamed to \*(lq,draft.orig\*(rq. This allows you to easily
54 .SS "Listing the Contents"
59 to list the table of contents associated with the MIME message that is created.
64 that a one-line banner should be displayed above the listing.
65 The size of the \*(lqnative\*(rq
66 (decoded) format of each content is evaluated. This provides an
67 accurate count at the expense of a small delay.
71 is present, then the listing will show any \*(lqextra\*(rq information
72 that is present in the message, such as comments in the
73 \*(lqContent-Type\*(rq header.
74 .SS "Translating the Composition File"
76 is essentially a filter to aid in the composition of MIME
81 \*(lqcomposition file\*(rq
82 into a valid MIME message. A
84 \*(lqcomposition file\*(rq
85 is just a file containing plain text that is interspersed
88 directives. When this file is processed
91 the various directives will be expanded to the
92 appropriate content, and will be encoded according to the MIME standards.
93 The resulting MIME message can then be sent by electronic mail.
95 The formal syntax for a
97 composition file is defined at the
98 end of this document, but the ideas behind this format are not complex.
99 Basically, the body contains one or more contents. A content consists of
100 either a directive, indicated with a \*(lq#\*(rq as the first character
101 of a line; or, plaintext (one or more lines of text). The continuation
102 character, \*(lq\\\*(lq, may be used to enter a single directive on more
108 /home/foobar/junk/picture.png
112 There are three kinds of directives:
114 \*(lqmessage\*(rq (#forw),
115 and \*(lqbegin\*(rq (#begin).
117 .B "(1) The \*(lqtype\*(rq directive
118 is used to directly specify the type and
119 subtype of a content. You may only specify discrete types in this manner
120 (can't specify the types multipart or message with this directive).
121 You may optionally specify the name of a file containing the contents
122 in \*(lqnative\*(rq (decoded) format. If this filename starts with the
123 \*(lq|\*(rq character, then it represents a command to execute whose
124 output is captured accordingly.
129 #audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
133 If a filename is not given,
135 will look for information in the
136 user's profile to determine how the different contents should be composed.
137 This is accomplished by consulting a composition string, and executing
140 with the standard output set to the content.
145 will echo any commands that are used to create contents in this way.
147 The composition string may contain the following escapes:
152 %a Insert parameters from directive
153 %f Insert filename containing content
154 %F %f, and stdout is not re-directed
155 %s Insert content subtype
156 %% Insert character %
162 will look for an entry of the form:
165 mhbuild-compose-<type>/<subtype>
168 to determine the command to use to compose the content. If this isn't
171 will look for an entry of the form:
174 mhbuild-compose-<type>
177 to determine the composition command. If this isn't found,
181 An example entry might be:
184 mhbuild-compose-audio/basic: record | raw2audio -F
187 Because commands like these will vary, depending on the display
188 environment used for login, composition strings for different
189 contents should probably be put in the file specified by the
191 environment variable, instead of directly in your
194 .B "(2) The \*(lqmessage\*(rq directive (#forw)
195 is used to specify a message or
196 group of messages to include. You may optionally specify the name of
197 the folder and which messages are to be forwarded. If a folder is not
198 given, it defaults to the current folder. Similarly, if a message is not
199 given, it defaults to the current message. The message directive
207 #forw +inbox 42 43 99
211 If you include a single message, it will be included directly as a content
212 of type \*(lqmessage/rfc822\*(rq. If you include more than one message,
215 will add a content of type \*(lqmultipart/digest\*(rq
216 and include each message as a subpart of this content.
218 .B "(3) The \*(lqbegin\*(rq directive
219 is used to create a multipart content.
220 When using the \*(lqbegin\*(rq directive, you must specify at least one
221 content between the begin and end pairs.
226 This will be a multipart with only one part.
231 If you use multiple directives in a composition draft,
234 automatically encapsulate them inside a multipart content. Therefore the
235 \*(lqbegin\*(rq directive is only necessary if you wish to use nested
236 multiparts, or create a multipart message containing only one part.
238 For all of these directives, the user may include a brief description
239 of the content between the \*(lq[\*(rq character and the \*(lq]\*(rq
240 character. This description will be copied into the
241 \*(lqContent-Description\*(rq header when the directive is processed.
245 #forw [important mail from Bob] +bob 1 2 3 4 5
249 Similarly, a disposition string may optionally be provided between
250 \*(lq{\*(rq and \*(lq}\*(rq characters; it will be copied into the
251 \*(lqContent-Disposition\*(rq header when the directive is processed.
252 If a disposition string is provided that does not contain a filename
253 parameter, and a filename is provided in the directive, it will be
254 added to the \*(lqContent-Disposition\*(rq header. For example, the
259 #text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt
263 creates these message part headers:
267 Content-Type: text/plain; charset="iso-8859-1"
268 Content-Disposition: attachment; filename="summary.txt"
274 will generate a unique \*(lqContent-ID:\*(rq for each directive,
275 corresponding to each message part; however, the user may override
276 this by defining the ID using the \*(lq<\*(rq and \*(lq>\*(rq
279 switch suppresses creation of all \*(lqContent-ID:\*(rq headers,
280 even in the top level of the message.
282 In addition to the various directives, plaintext can be present.
283 Plaintext is gathered, until a directive is found or the draft is
284 exhausted, and this is made to form a text content. If the plaintext
285 must contain a \*(lq#\*(rq at the beginning of a line, simply double it,
289 ##when sent, this line will start with only one #
292 If you want to end the plaintext prior to a directive, e.g., to have two
293 plaintext contents adjacent, simply insert a line containing a single
294 \*(lq#\*(rq character, e.g.,
298 this is the first content
300 and this is the second
304 Finally, if the plaintext starts with a line of the form:
307 Content-Description: text
310 then this will be used to describe the plaintext content.
311 You MUST follow this line with a blank line before starting
314 By default, plaintext is captured as a text/plain content. You can
315 override this by starting the plaintext with \*(lq#<\*(rq followed by
316 a content-type specification. For example, e.g.,
321 this content will be tagged as text/enriched
323 and this content will be tagged as text/plain
325 #<application/x-patch [this is a patch]
326 and this content will be tagged as application/x-patch
330 Note that if you use the \*(lq#<\*(rq plaintext-form, then the
331 content-description must be on the same line which identifies the content
332 type of the plaintext.
334 When composing a text content, you may indicate the relevant character
335 set by adding the \*(lqcharset\*(rq parameter to the directive.
338 #<text/plain; charset=iso-8859-5
341 If a text content contains any 8\-bit characters (characters with the
342 high bit set) and the character set is not specified as above, then
344 will assume the character set is of the type given by the
345 environment variable MM_CHARSET. If this environment variable is not
346 set, then the character set will be labeled as \*(lqx-unknown\*(rq.
348 If a text content contains only 7\-bit characters and the character set
349 is not specified as above, then the character set will be labeled as
352 Putting this all together,
353 here is an example of a more complicated message draft. The
354 following draft will expand into a multipart/mixed message
355 containing five parts:
359 To: nobody@nowhere.org
361 Subject: Look and listen to me!
363 The first part will be text/plain
365 The second part will be text/enriched
367 This third part will be text/plain
368 #audio/basic [silly giggle] \\
369 |raw2audio -F < /usr/lib/sounds/giggle.au
370 #image/gif [photo of foobar] \\
371 /home/foobar/lib/picture.gif
375 .SS "Transfer Encodings"
378 constructs the new MIME message by parsing directives,
379 including files, etc., it scans the contents of the message to determine
380 which transfer encoding to use. It will check for 8bit data, long lines,
381 spaces at the end of lines, and clashes with multipart boundaries. It will
382 then choose a transfer encoding appropriate for each content type.
384 .SS "Invoking mhbuild"
392 composition file, which
394 will create, from the draft file, if MIME features are requested.
395 This is the case with attachment headers.
397 In contrast to previous versions, the user does not need to care
398 for any special actions anymore.
400 .SS "User Environment"
401 Because the environment in which
403 operates may vary for a
406 will look for the environment variable
408 If present, this specifies the name of an additional user profile which
409 should be read. Hence, when a user logs in on a particular machine,
410 this environment variable should be set to refer to a file containing
411 definitions useful for that machine.
415 will attempt to consult a global
420 %etcdir%/mhn.defaults
425 .SS "Syntax of Composition Files"
426 The following is the formal syntax of a
428 \*(lqcomposition file\*(rq.
432 body ::= 1*(content | EOL)
434 content ::= directive | plaintext
436 directive ::= "#" type "/" subtype
437 0*(";" attribute "=" value)
440 [ "[" description "]" ]
441 [ "{" disposition "}" ]
447 [ "[" description "]" ]
448 [ "{" disposition "}" ]
449 [ "+"folder ] [ 0*msg ]
454 [ "[" description "]" ]
455 [ "{" disposition "}" ]
463 plaintext ::= [ "Content-Description:"
464 description EOL EOL ]
468 | "#<" type "/" subtype
469 0*(";" attribute "=" value)
471 [ "[" description "]" ]
472 [ "{" disposition "}" ]
477 line ::= "##" text EOL
478 -- interpreted as "#"text EOL
487 .ta \w'%etcdir%/ExtraBigFileName 'u
488 ^$HOME/.mmh/profile~^The user profile
489 ^$MHBUILD~^Additional profile entries
490 ^%etcdir%/mhn.defaults~^System default MIME profile entries
493 .SH "PROFILE COMPONENTS"
497 .ta \w'ExtraBigProfileName 'u
498 ^Path:~^To determine the user's mail storage
499 ^Current\-Folder:~^To find the default current folder
500 ^mhbuild-compose-<type>*~^Template for composing contents
504 mhlist(1), show(1), mhstore(1), forw(1),
506 .I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
509 .I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
512 .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text"
515 .I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures"
518 .I "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples"
529 If a folder is given, it will become the current folder. The last
530 message selected will become the current message.