4 .TH MHBUILD %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
6 mhbuild \- translate MIME composition draft
12 .RB [ \-contentid " | " \-nocontentid ]
13 .RB [ \-verbose " | " \-noverbose ]
20 command will translate a MIME composition draft into
24 creates multi-media messages as specified in RFC\-2045
25 thru RFC\-2049. Currently
27 only supports encodings in
28 message bodies, and does not support the encoding of message headers as
29 specified in RFC\-2047.
31 If you specify the name of the composition file as \*(lq-\*(rq,
34 will accept the composition draft on the standard
35 input. If the translation of this input is successful,
37 will output the new MIME message to the standard output. This argument
38 must be the last argument on the command line.
40 Otherwise if the file argument to
42 is the name of a valid
43 composition file, and the translation is successful,
45 will replace the original file with the new MIME message. It will rename
46 the original file to start with the \*(lq,\*(rq character and end with the
47 string \*(lq.orig\*(rq, e.g., if you are editing the file \*(lqdraft\*(rq,
48 it will be renamed to \*(lq,draft.orig\*(rq. This allows you to easily
52 .SS "Translating the Composition File"
54 is essentially a filter to aid in the composition of MIME
59 \*(lqcomposition file\*(rq
60 into a valid MIME message. A
62 \*(lqcomposition file\*(rq
63 is just a file containing plain text that is interspersed
66 directives. When this file is processed
69 the various directives will be expanded to the
70 appropriate content, and will be encoded according to the MIME standards.
71 The resulting MIME message can then be sent by electronic mail.
73 The formal syntax for a
75 composition file is defined at the
76 end of this document, but the ideas behind this format are not complex.
77 Basically, the body contains one or more contents. A content consists of
78 either a directive, indicated with a \*(lq#\*(rq as the first character
79 of a line; or, plaintext (one or more lines of text). The continuation
80 character, \*(lq\\\*(lq, may be used to enter a single directive on more
86 /home/foobar/junk/picture.png
90 There are three kinds of directives:
92 \*(lqmessage\*(rq (#forw),
93 and \*(lqbegin\*(rq (#begin).
95 .B "(1) The \*(lqtype\*(rq directive
96 is used to directly specify the type and
97 subtype of a content. You may only specify discrete types in this manner
98 (can't specify the types multipart or message with this directive).
99 You may optionally specify the name of a file containing the contents
100 in \*(lqnative\*(rq (decoded) format. If this filename starts with the
101 \*(lq|\*(rq character, then it represents a command to execute whose
102 output is captured accordingly.
107 #audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
111 If a filename is not given,
113 will look for information in the
114 user's profile to determine how the different contents should be composed.
115 This is accomplished by consulting a composition string, and executing
118 with the standard output set to the content.
123 will echo any commands that are used to create contents in this way.
125 The composition string may contain the following escapes:
130 %a Insert parameters from directive
131 %f Insert filename containing content
132 %F %f, and stdout is not re-directed
133 %s Insert content subtype
134 %% Insert character %
140 will look for an entry of the form:
143 mhbuild-compose-<type>/<subtype>
146 to determine the command to use to compose the content. If this isn't
149 will look for an entry of the form:
152 mhbuild-compose-<type>
155 to determine the composition command. If this isn't found,
159 An example entry might be:
162 mhbuild-compose-audio/basic: record | raw2audio -F
165 Because commands like these will vary, depending on the display
166 environment used for login, composition strings for different
167 contents should probably be put in the file specified by the
169 environment variable, instead of directly in your
172 .B "(2) The \*(lqmessage\*(rq directive (#forw)
173 is used to specify a message or
174 group of messages to include. You may optionally specify the name of
175 the folder and which messages are to be forwarded. If a folder is not
176 given, it defaults to the current folder. Similarly, if a message is not
177 given, it defaults to the current message. The message directive
185 #forw +inbox 42 43 99
189 If you include a single message, it will be included directly as a content
190 of type \*(lqmessage/rfc822\*(rq. If you include more than one message,
193 will add a content of type \*(lqmultipart/digest\*(rq
194 and include each message as a subpart of this content.
196 .B "(3) The \*(lqbegin\*(rq directive
197 is used to create a multipart content.
198 When using the \*(lqbegin\*(rq directive, you must specify at least one
199 content between the begin and end pairs.
204 This will be a multipart with only one part.
209 If you use multiple directives in a composition draft,
212 automatically encapsulate them inside a multipart content. Therefore the
213 \*(lqbegin\*(rq directive is only necessary if you wish to use nested
214 multiparts, or create a multipart message containing only one part.
216 For all of these directives, the user may include a brief description
217 of the content between the \*(lq[\*(rq character and the \*(lq]\*(rq
218 character. This description will be copied into the
219 \*(lqContent-Description\*(rq header when the directive is processed.
223 #forw [important mail from Bob] +bob 1 2 3 4 5
227 Similarly, a disposition string may optionally be provided between
228 \*(lq{\*(rq and \*(lq}\*(rq characters; it will be copied into the
229 \*(lqContent-Disposition\*(rq header when the directive is processed.
230 If a disposition string is provided that does not contain a filename
231 parameter, and a filename is provided in the directive, it will be
232 added to the \*(lqContent-Disposition\*(rq header. For example, the
237 #text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt
241 creates these message part headers:
245 Content-Type: text/plain; charset="iso-8859-1"
246 Content-Disposition: attachment; filename="summary.txt"
252 will generate a unique \*(lqContent-ID:\*(rq for each directive,
253 corresponding to each message part; however, the user may override
254 this by defining the ID using the \*(lq<\*(rq and \*(lq>\*(rq
257 switch suppresses creation of all \*(lqContent-ID:\*(rq headers,
258 even in the top level of the message.
260 In addition to the various directives, plaintext can be present.
261 Plaintext is gathered, until a directive is found or the draft is
262 exhausted, and this is made to form a text content. If the plaintext
263 must contain a \*(lq#\*(rq at the beginning of a line, simply double it,
267 ##when sent, this line will start with only one #
270 If you want to end the plaintext prior to a directive, e.g., to have two
271 plaintext contents adjacent, simply insert a line containing a single
272 \*(lq#\*(rq character, e.g.,
276 this is the first content
278 and this is the second
282 Finally, if the plaintext starts with a line of the form:
285 Content-Description: text
288 then this will be used to describe the plaintext content.
289 You MUST follow this line with a blank line before starting
292 By default, plaintext is captured as a text/plain content. You can
293 override this by starting the plaintext with \*(lq#<\*(rq followed by
294 a content-type specification. For example, e.g.,
299 this content will be tagged as text/enriched
301 and this content will be tagged as text/plain
303 #<application/x-patch [this is a patch]
304 and this content will be tagged as application/x-patch
308 Note that if you use the \*(lq#<\*(rq plaintext-form, then the
309 content-description must be on the same line which identifies the content
310 type of the plaintext.
312 When composing a text content, you may indicate the relevant character
313 set by adding the \*(lqcharset\*(rq parameter to the directive.
316 #<text/plain; charset=iso-8859-5
319 If a text content contains any 8\-bit characters (characters with the
320 high bit set) and the character set is not specified as above, then
322 will assume the character set is of the type given by the
323 environment variable MM_CHARSET. If this environment variable is not
324 set, then the character set will be labeled as \*(lqx-unknown\*(rq.
326 If a text content contains only 7\-bit characters and the character set
327 is not specified as above, then the character set will be labeled as
330 Putting this all together,
331 here is an example of a more complicated message draft. The
332 following draft will expand into a multipart/mixed message
333 containing five parts:
337 To: nobody@nowhere.org
339 Subject: Look and listen to me!
341 The first part will be text/plain
343 The second part will be text/enriched
345 This third part will be text/plain
346 #audio/basic [silly giggle] \\
347 |raw2audio -F < /usr/lib/sounds/giggle.au
348 #image/gif [photo of foobar] \\
349 /home/foobar/lib/picture.gif
353 .SS "Transfer Encodings"
356 constructs the new MIME message by parsing directives,
357 including files, etc., it scans the contents of the message to determine
358 which transfer encoding to use. It will check for 8bit data, long lines,
359 spaces at the end of lines, and clashes with multipart boundaries. It will
360 then choose a transfer encoding appropriate for each content type.
362 .SS "Invoking mhbuild"
370 composition file, which
372 will create, from the draft file, if MIME features are requested.
373 This is the case with attachment headers.
375 In contrast to previous versions, the user does not need to care
376 for any special actions anymore.
378 .SS "User Environment"
379 Because the environment in which
381 operates may vary for a
384 will look for the environment variable
386 If present, this specifies the name of an additional user profile which
387 should be read. Hence, when a user logs in on a particular machine,
388 this environment variable should be set to refer to a file containing
389 definitions useful for that machine.
393 will attempt to consult a global
398 %etcdir%/mhn.defaults
403 .SS "Syntax of Composition Files"
404 The following is the formal syntax of a
406 \*(lqcomposition file\*(rq.
410 body ::= 1*(content | EOL)
412 content ::= directive | plaintext
414 directive ::= "#" type "/" subtype
415 0*(";" attribute "=" value)
418 [ "[" description "]" ]
419 [ "{" disposition "}" ]
425 [ "[" description "]" ]
426 [ "{" disposition "}" ]
427 [ "+"folder ] [ 0*msg ]
432 [ "[" description "]" ]
433 [ "{" disposition "}" ]
441 plaintext ::= [ "Content-Description:"
442 description EOL EOL ]
446 | "#<" type "/" subtype
447 0*(";" attribute "=" value)
449 [ "[" description "]" ]
450 [ "{" disposition "}" ]
455 line ::= "##" text EOL
456 -- interpreted as "#"text EOL
465 .ta \w'%etcdir%/ExtraBigFileName 'u
466 ^$HOME/.mmh/profile~^The user profile
467 ^$MHBUILD~^Additional profile entries
468 ^%etcdir%/mhn.defaults~^System default MIME profile entries
471 .SH "PROFILE COMPONENTS"
475 .ta \w'ExtraBigProfileName 'u
476 ^Path:~^To determine the user's mail storage
477 ^Current\-Folder:~^To find the default current folder
478 ^mhbuild-compose-<type>*~^Template for composing contents
482 mhlist(1), show(1), mhstore(1), forw(1),
484 .I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
487 .I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
490 .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text"
493 .I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures"
496 .I "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples"
506 If a folder is given, it will become the current folder. The last
507 message selected will become the current message.