read the defaultfolder from the profile
[mmh] / man / mhbuild.man1
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH MHBUILD %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 mhbuild \- translate MIME composition draft
7 .SH SYNOPSIS
8 .na
9 .HP 5
10 .B mhbuild
11 .I file
12 .RB [ \-verbose " | " \-noverbose ]
13 .RB [ \-Version ]
14 .RB [ \-help ]
15 .ad
16 .SH DESCRIPTION
17 The
18 .B mhbuild
19 command will translate a MIME composition draft into
20 a valid MIME message.
21 .PP
22 .B mhbuild
23 creates multi-media messages as specified in RFC\-2045
24 thru RFC\-2049.  Currently
25 .B mhbuild
26 only supports encodings in
27 message bodies, and does support the encoding of message headers as
28 specified in RFC\-2047.
29 .PP
30 If you specify the name of the composition file as `-',
31 then
32 .B mhbuild
33 will accept the composition draft on the standard
34 input.  If the translation of this input is successful,
35 .B mhbuild
36 will output the new MIME message to the standard output.  This argument
37 must be the last argument on the command line.
38 .PP
39 Otherwise if the file argument to
40 .B mhbuild
41 is the name of a valid
42 composition file, and the translation is successful,
43 .B mhbuild
44 will replace the original file with the new MIME message.
45 It will preserve the original file under the same name with `.orig'
46 appended.
47 E.g., if you are editing the file `draft', its original contents
48 it will be preserved as `draft.orig'.  This allows you to easily
49 recover the
50 .B mhbuild
51 input file.
52 .SS "Translating the Composition File"
53 .B mhbuild
54 is essentially a filter to aid in the composition of MIME
55 messages.
56 .B mhbuild
57 will convert an
58 .B mhbuild
59 `composition file'
60 into a valid MIME message.  A
61 .B mhbuild
62 `composition file'
63 is just a file containing plain text that is interspersed
64 with various
65 .B mhbuild
66 directives.  When this file is processed
67 by
68 .BR mhbuild ,
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.
72 .PP
73 The formal syntax for a
74 .B mhbuild
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 `#' as the first character
79 of a line; or, plaintext (one or more lines of text).  The continuation
80 character, `\\`, may be used to enter a single directive on more
81 than one line, e.g.,
82 .PP
83 .RS 5
84 .nf
85 #image/png \\
86     /home/foobar/junk/picture.png
87 .fi
88 .RE
89 .PP
90 There are three kinds of directives:
91 `type',
92 `message' (#forw),
93 and `begin' (#begin).
94 .PP
95 .B "(1) The `type' 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 `native' (decoded) format.  If this filename starts with the
101 `|' character, then it represents a command to execute whose
102 output is captured accordingly.
103 For example,
104 .PP
105 .RS 5
106 .nf
107 #audio/basic |raw2audio \-F < /usr/lib/sound/giggle.au
108 .fi
109 .RE
110 .PP
111 If a filename is not given,
112 .B mhbuild
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
116 it under
117 .BR /bin/sh ,
118 with the standard output set to the content.
119 If the
120 .B \-verbose
121 switch is given,
122 .B mhbuild
123 will echo any commands that are used to create contents in this way.
124 .PP
125 The composition string may contain the following escapes:
126 .PP
127 .RS 5
128 .nf
129 .ta \w'%P  'u
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 %
135 .fi
136 .RE
137 .PP
138 First,
139 .B mhbuild
140 will look for an entry of the form:
141 .PP
142 .RS 5
143 mhbuild-compose-<type>/<subtype>
144 .RE
145 .PP
146 to determine the command to use to compose the content.  If this isn't
147 found,
148 .B mhbuild
149 will look for an entry of the form:
150 .PP
151 .RS 5
152 mhbuild-compose-<type>
153 .RE
154 .PP
155 to determine the composition command. If this isn't found,
156 .B mhbuild
157 will complain.
158 .PP
159 An example entry might be:
160 .PP
161 .RS 5
162 mhbuild-compose-audio/basic: record | raw2audio \-F
163 .RE
164 .PP
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
168 .B $MHBUILD
169 environment variable, instead of directly in your
170 user profile.
171 .PP
172 .B "(2) The `message' 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
178 is used by
179 .BR forw .
180 .PP
181 For example,
182 .PP
183 .RS 5
184 .nf
185 #forw +inbox 42 43 99
186 .fi
187 .RE
188 .PP
189 If you include a single message, it will be included directly as a content
190 of type `message/rfc822'.  If you include more than one message,
191 then
192 .B mhbuild
193 will add a content of type `multipart/digest'
194 and include each message as a subpart of this content.
195 .PP
196 .B "(3) The `begin' directive
197 is used to create a multipart content.
198 When using the `begin' directive, you must specify at least one
199 content between the begin and end pairs.
200 .PP
201 .RS 5
202 .nf
203 #begin
204 This will be a multipart with only one part.
205 #end
206 .fi
207 .RE
208 .PP
209 If you use multiple directives in a composition draft,
210 .B mhbuild
211 will
212 automatically encapsulate them inside a multipart content.  Therefore the
213 `begin' directive is only necessary if you wish to use nested
214 multiparts, or create a multipart message containing only one part.
215 .PP
216 For all of these directives, the user may include a brief description
217 of the content between the `[' character and the `]'
218 character.  This description will be copied into the
219 `Content-Description' header when the directive is processed.
220 .PP
221 .RS 5
222 .nf
223 #forw [important mail from Bob] +bob 1 2 3 4 5
224 .fi
225 .RE
226 .PP
227 Similarly, a disposition string may optionally be provided between
228 `{' and `}' characters; it will be copied into the
229 `Content-Disposition' 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 `Content-Disposition' header.  For example, the
233 following directive:
234 .PP
235 .RS 5
236 .nf
237 #text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt
238 .fi
239 .RE
240 .PP
241 creates these message part headers:
242 .PP
243 .RS 5
244 .nf
245 Content-Type: text/plain; charset="iso-8859-1"
246 Content-Disposition: attachment; filename="summary.txt"
247 .fi
248 .RE
249 .PP
250 By default,
251 .B mhbuild
252 will generate a unique `Content-ID:' for each directive,
253 corresponding to each message part; however, the user may override
254 this by defining the ID using the `<' and `>'
255 characters.
256 .PP
257 In addition to the various directives, plaintext can be present.
258 Plaintext is gathered, until a directive is found or the draft is
259 exhausted, and this is made to form a text content.  If the plaintext
260 must contain a `#' at the beginning of a line, simply double it,
261 e.g.,
262 .PP
263 .RS 5
264 ##when sent, this line will start with only one #
265 .RE
266 .PP
267 If you want to end the plaintext prior to a directive, e.g., to have two
268 plaintext contents adjacent, simply insert a line containing a single
269 `#' character, e.g.,
270 .PP
271 .RS 5
272 .nf
273 this is the first content
274 #
275 and this is the second
276 .fi
277 .RE
278 .PP
279 Finally, if the plaintext starts with a line of the form:
280 .PP
281 .RS 5
282 Content-Description: text
283 .RE
284 .PP
285 then this will be used to describe the plaintext content.
286 You MUST follow this line with a blank line before starting
287 your text.
288 .PP
289 By default, plaintext is captured as a text/plain content.  You can
290 override this by starting the plaintext with `#<' followed by
291 a content-type specification.  For example, e.g.,
292 .PP
293 .RS 5
294 .nf
295 #<text/enriched
296 this content will be tagged as text/enriched
297 #
298 and this content will be tagged as text/plain
299 #
300 #<application/x-patch [this is a patch]
301 and this content will be tagged as application/x-patch
302 .fi
303 .RE
304 .PP
305 Note that if you use the `#<' plaintext-form, then the
306 content-description must be on the same line which identifies the content
307 type of the plaintext.
308 .PP
309 When composing a text content, you may indicate the relevant character
310 set by adding the `charset' parameter to the directive.
311 .PP
312 .RS 5
313 #<text/plain; charset=iso-8859-5
314 .RE
315 .PP
316 If a text content contains any 8\-bit characters (characters with the
317 high bit set) and the character set is not specified as above, then
318 .B mhbuild
319 will assume the character set is of the type given by the
320 environment variable MM_CHARSET.  If this environment variable is not
321 set, then the character set will be labeled as `x-unknown'.
322 .PP
323 If a text content contains only 7\-bit characters and the character set
324 is not specified as above, then the character set will be labeled as
325 `us-ascii'.
326 .PP
327 Putting this all together,
328 here is an example of a more complicated message draft.  The
329 following draft will expand into a multipart/mixed message
330 containing five parts:
331 .PP
332 .RS 5
333 .nf
334 To: nobody@nowhere.org
335 Cc:
336 Subject: Look and listen to me!
337 --------
338 The first part will be text/plain
339 #<text/enriched
340 The second part will be text/enriched
341 #
342 This third part will be text/plain
343 #audio/basic [silly giggle]  \\
344     |raw2audio \-F < /usr/lib/sounds/giggle.au
345 #image/gif   [photo of foobar] \\
346                     /home/foobar/lib/picture.gif
347 .fi
348 .RE
349
350 .SS "Transfer Encodings"
351 After
352 .B mhbuild
353 constructs the new MIME message by parsing directives,
354 including files, etc., it scans the contents of the message to determine
355 which transfer encoding to use.  It will check for 8bit data, long lines,
356 spaces at the end of lines, and clashes with multipart boundaries.  It will
357 then choose a transfer encoding appropriate for each content type.
358
359 .SS "Invoking mhbuild"
360 Typically,
361 .B mhbuild
362 is invoked by the
363 .B send
364 program.
365 It expects an
366 .B mhbuild
367 composition file, which
368 .B send
369 will create, from the draft file, if MIME features are requested.
370 This is the case with attachment headers.
371 .PP
372 In contrast to previous versions, the user does not need to care
373 for any special actions anymore.
374
375 .SS "User Environment"
376 Because the environment in which
377 .B mhbuild
378 operates may vary for a
379 user,
380 .B mhbuild
381 will look for the environment variable
382 .BR $MHBUILD .
383 If present, this specifies the name of an additional user profile which
384 should be read.  Hence, when a user logs in on a particular machine,
385 this environment variable should be set to refer to a file containing
386 definitions useful for that machine.
387 .PP
388 Finally,
389 .B mhbuild
390 will attempt to consult a global
391 .B mhbuild
392 user profile, e.g.,
393 .PP
394 .RS 5
395 %etcdir%/mhn.defaults
396 .RE
397 .PP
398 if it exists.
399
400 .SS "Syntax of Composition Files"
401 The following is the formal syntax of a
402 .B mhbuild
403 `composition file'.
404 .PP
405 .RS 5
406 .nf
407 body         ::=     1*(content | EOL)
408
409 content      ::=     directive | plaintext
410
411 directive    ::=     "#" type "/" subtype
412                          0*(";" attribute "=" value)
413                          [ "(" comment ")" ]
414                          [ "<" id ">" ]
415                          [ "[" description "]" ]
416                          [ "{" disposition "}" ]
417                          [ filename ]
418                          EOL
419
420                    | "#forw"
421                          [ "<" id ">" ]
422                          [ "[" description "]" ]
423                          [ "{" disposition "}" ]
424                          [ "+"folder ] [ 0*msg ]
425                          EOL
426
427                    | "#begin"
428                            [ "<" id ">" ]
429                            [ "[" description "]" ]
430                            [ "{" disposition "}" ]
431                            [   "alternative"
432                              | "parallel"
433                              | something-else    ]
434                            EOL
435                          1*body
436                      "#end" EOL
437
438 plaintext    ::=     [ "Content-Description:"
439                            description EOL EOL ]
440                          1*line
441                      [ "#" EOL ]
442
443                    | "#<" type "/" subtype
444                          0*(";" attribute "=" value)
445                          [ "(" comment ")" ]
446                          [ "[" description "]" ]
447                          [ "{" disposition "}" ]
448                          EOL
449                          1*line
450                      [ "#" EOL ]
451
452 line         ::=     "##" text EOL
453                      -- interpreted as "#"text EOL
454                    | text EOL
455 .fi
456 .RE
457 .PP
458
459 .SH FILES
460 .fc ^ ~
461 .nf
462 .ta \w'%etcdir%/ExtraBigFileName  'u
463 ^$HOME/.mmh/profile~^The user profile
464 ^$MHBUILD~^Additional profile entries
465 ^%etcdir%/mhn.defaults~^System default MIME profile entries
466 .fi
467
468 .SH "PROFILE COMPONENTS"
469 .fc ^ ~
470 .nf
471 .ta 2.4i
472 .ta \w'ExtraBigProfileName  'u
473 ^Path:~^To determine the user's mail storage
474 ^Current\-Folder:~^To find the default current folder
475 ^mhbuild-compose-<type>*~^Template for composing contents
476 .fi
477
478 .SH "SEE ALSO"
479 mhlist(1), show(1), mhstore(1), forw(1),
480 .br
481 .I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
482 (RFC\-2045),
483 .br
484 .I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
485 (RFC\-2046),
486 .br
487 .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text"
488 (RFC\-2047),
489 .br
490 .I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures"
491 (RFC\-2048),
492 .br
493 .I "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples"
494 (RFC\-2049)
495
496 .SH DEFAULTS
497 .nf
498 .RB ` \-noverbose '
499 .fi
500
501 .SH CONTEXT
502 If a folder is given, it will become the current folder.  The last
503 message selected will become the current message.
504
505 .SH BUGS
506 Outlook 2002 won't display attachments that have a Content-ID header.
507 This is a bug in Outlook 2002, not in
508 .BR mhbuild .
509 To workaround it, invoke \fIe mhbuild\fP manually at the Whatnow prompt
510 and edit the draft again thereafter, removing the Content-ID headers.
511 Then send it.
512 There used to be a
513 .B \-nocontentid
514 switch to prevent Content-ID headers to be inserted, but as it was considered
515 wrong to complicate all other MUAs instead of forcing the developers and users 
516 of broken MUAs to fix or change their software, it was removed.