1MHBUILD(1) [nmh-1.2-20070115cvs] MHBUILD(1)
2
6 mhbuild - translate MIME composition draft
7
9 mhbuild file [-list | -nolist] [-realsize | -norealsize] [-headers |
10 -noheaders] [-ebcdicsafe | -noebcdicsafe] [-rfc934mode |
11 -norfc934mode] [-contentid | -nocontentid] [-verbose | -noverbose]
12 [-check | -nocheck] [-version] [-help]
13
15 The mhbuild command will translate a MIME composition draft into a
16 valid MIME message.
17 mhbuild creates multi-media messages as specified in RFC-2045 thru
19 RFC-2049. Currently mhbuild only supports encodings in message bodies,
20 and does not support the encoding of message headers as specified in
21 RFC-2047.
22 If you specify the name of the composition file as “-”, then mhbuild
24 will accept the composition draft on the standard input. If the trans‐
25 lation of this input is successful, mhbuild will output the new MIME
26 message to the standard output. This argument must be the last argu‐
27 ment on the command line.
28 Otherwise if the file argument to mhbuild is the name of a valid compo‐
30 sition file, and the translation is successful, mhbuild will replace
31 the original file with the new MIME message. It will rename the origi‐
32 nal file to start with the “,” character and end with the string
33 “.orig”, e.g., if you are editing the file “draft”, it will be renamed
34 to “,draft.orig”. This allows you to easily recover the mhbuild input
35 file.
36 Listing the Contents
38 The -list switch tells mhbuild to list the table of contents associated
39 with the MIME message that is created.
40 The -headers switch indicates that a one-line banner should be dis‐
42 played above the listing. The -realsize switch tells mhbuild to evalu‐
43 ate the “native” (decoded) format of each content prior to listing.
44 This provides an accurate count at the expense of a small delay. If
45 the -verbose switch is present, then the listing will show any “extra”
46 information that is present in the message, such as comments in the
47 “Content-Type” header.
48 Translating the Composition File
50 mhbuild is essentially a filter to aid in the composition of MIME mes‐
51 sages. mhbuild will convert an mhbuild “composition file” into a valid
52 MIME message. A mhbuild “composition file” is just a file containing
53 plain text that is interspersed with various mhbuild directives. When
54 this file is processed by mhbuild, the various directives will be
55 expanded to the appropriate content, and will be encoded according to
56 the MIME standards. The resulting MIME message can then be sent by
57 electronic mail.
58 The formal syntax for a mhbuild composition file is defined at the end
60 of this document, but the ideas behind this format are not complex.
61 Basically, the body contains one or more contents. A content consists
62 of either a directive, indicated with a “#” as the first character of a
63 line; or, plaintext (one or more lines of text). The continuation
64 character, “\“, may be used to enter a single directive on more than
65 one line, e.g.,
66 #image/png \
68 /home/foobar/junk/picture.png
69 There are four kinds of directives: “type” directives, which name the
71 type and subtype of the content; “external-type” directives, which also
72 name the type and subtype of the content; the “message” directive
73 (#forw), which is used to forward one or more messages; and, the
74 “begin” directive (#begin), which is used to create a multipart con‐
75 tent.
76 The “type” directive is used to directly specify the type and subtype
78 of a content. You may only specify discrete types in this manner
79 (can't specify the types multipart or message with this directive).
80 You may optionally specify the name of a file containing the contents
81 in “native” (decoded) format. If this filename starts with the “|”
82 character, then it represents a command to execute whose output is cap‐
83 tured accordingly. For example,
84 #audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
86 If a filename is not given, mhbuild will look for information in the
88 user's profile to determine how the different contents should be com‐
89 posed. This is accomplished by consulting a composition string, and
90 executing it under /bin/sh, with the standard output set to the con‐
91 tent. If the -verbose switch is given, mhbuild will echo any commands
92 that are used to create contents in this way.
93 The composition string may contain the following escapes:
95 %a Insert parameters from directive
97 %f Insert filename containing content
98 %F %f, and stdout is not re-directed
99 %s Insert content subtype
100 %% Insert character %
101 First, mhbuild will look for an entry of the form:
103 mhbuild-compose-<type>/<subtype>
105 to determine the command to use to compose the content. If this isn't
107 found, mhbuild will look for an entry of the form:
108 mhbuild-compose-<type>
110 to determine the composition command. If this isn't found, mhbuild will
112 complain.
113 An example entry might be:
115 mhbuild-compose-audio/basic: record | raw2audio -F
117 Because commands like these will vary, depending on the display envi‐
119 ronment used for login, composition strings for different contents
120 should probably be put in the file specified by the $MHBUILD environ‐
121 ment variable, instead of directly in your user profile.
122 The “external-type” directives are used to provide a MIME reference to
124 a content, rather than enclosing the contents itself (for instance, by
125 specifying an ftp site). Hence, instead of providing a filename as
126 with the type directives, external-parameters are supplied. These look
127 like regular parameters, so they must be separated accordingly. For
128 example,
129 #@application/octet-stream; \
131 type=tar; \
132 conversions=compress \
133 [this is the nmh distribution] \
134 {application; filename="nmh.tar.gz"} \
135 name="nmh.tar.gz"; \
136 directory="/pub/nmh"; \
137 site="ftp.math.gatech.edu"; \
138 access-type=anon-ftp; \
139 mode="image"
140 You must give a description string to separate the content parameters
142 from the external-parameters (although this string may be empty). This
143 description string is specified by enclosing it within “[]”. A dispo‐
144 sition string, to appear in a “Content-Disposition” header, may appear
145 in the optional “{}”.
146 These parameters are of the form:
148 access-type= usually anon-ftp or mail-server
150 name= filename
151 permission= read-only or read-write
152 site= hostname
153 directory= directoryname (optional)
154 mode= usually ascii or image (optional)
155 size= number of octets
156 server= mailbox
157 subject= subject to send
158 body= command to send for retrieval
159 The “message” directive (#forw) is used to specify a message or group
161 of messages to include. You may optionally specify the name of the
162 folder and which messages are to be forwarded. If a folder is not
163 given, it defaults to the current folder. Similarly, if a message is
164 not given, it defaults to the current message. Hence, the message
165 directive is similar to the forw command, except that the former uses
166 the MIME rules for encapsulation rather than those specified in
167 RFC-934. For example,
168 #forw +inbox 42 43 99
170 If you include a single message, it will be included directly as a con‐
172 tent of type “message/rfc822”. If you include more than one message,
173 then mhbuild will add a content of type “multipart/digest” and include
174 each message as a subpart of this content.
175 If you are using this directive to include more than one message, you
177 may use the -rfc934mode switch. This switch will indicate that mhbuild
178 should attempt to utilize the MIME encapsulation rules in such a way
179 that the “multipart/digest” that is created is (mostly) compatible with
180 the encapsulation specified in RFC-934. If given, then RFC-934 compli‐
181 ant user-agents should be able to burst the message on recep‐
182 tion -- providing that the messages being encapsulated do not contain
183 encapsulated messages themselves. The drawback of this approach is
184 that the encapsulations are generated by placing an extra newline at
185 the end of the body of each message.
186 The “begin” directive is used to create a multipart content. When
188 using the “begin” directive, you must specify at least one content
189 between the begin and end pairs.
190 #begin
192 This will be a multipart with only one part.
193 #end
194 If you use multiple directives in a composition draft, mhbuild will
196 automatically encapsulate them inside a multipart content. Therefore
197 the “begin” directive is only necessary if you wish to use nested mul‐
198 tiparts, or create a multipart message containing only one part.
199 For all of these directives, the user may include a brief description
201 of the content between the “[” character and the “]” character. This
202 description will be copied into the “Content-Description” header when
203 the directive is processed.
204 #forw [important mail from Bob] +bob 1 2 3 4 5
206 Similarly, a disposition string may optionally be provided between “{”
208 and “}” characters; it will be copied into the “Content-Disposition”
209 header when the directive is processed. If a disposition string is
210 provided that does not contain a filename parameter, and a filename is
211 provided in the directive, it will be added to the “Content-Disposi‐
212 tion” header. For example, the following directive:
213 #text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt
215 creates these message part headers:
217 Content-Type: text/plain; charset="iso-8859-1"
219 Content-Disposition: attachment; filename="summary.txt"
220 By default, mhbuild will generate a unique “Content-ID:” for each
222 directive, corresponding to each message part; however, the user may
223 override this by defining the ID using the “<” and “>” characters. The
224 -nocontentid switch suppresses creation of all “Content-ID:” headers,
225 even in the top level of the message.
226 In addition to the various directives, plaintext can be present.
228 Plaintext is gathered, until a directive is found or the draft is
229 exhausted, and this is made to form a text content. If the plaintext
230 must contain a “#” at the beginning of a line, simply double it, e.g.,
231 ##when sent, this line will start with only one #
233 If you want to end the plaintext prior to a directive, e.g., to have
235 two plaintext contents adjacent, simply insert a line containing a sin‐
236 gle “#” character, e.g.,
237 this is the first content
239 #
240 and this is the second
241 Finally, if the plaintext starts with a line of the form:
243 Content-Description: text
245 then this will be used to describe the plaintext content. You MUST
247 follow this line with a blank line before starting your text.
248 By default, plaintext is captured as a text/plain content. You can
250 override this by starting the plaintext with “#<” followed by a con‐
251 tent-type specification. For example, e.g.,
252 #<text/enriched
254 this content will be tagged as text/enriched
255 #
256 and this content will be tagged as text/plain
257 #
258 #<application/x-patch [this is a patch]
259 and this content will be tagged as application/x-patch
260 Note that if you use the “#<” plaintext-form, then the content-descrip‐
262 tion must be on the same line which identifies the content type of the
263 plaintext.
264 When composing a text content, you may indicate the relevant character
266 set by adding the “charset” parameter to the directive.
267 #<text/plain; charset=iso-8859-5
269 If a text content contains any 8-bit characters (characters with the
271 high bit set) and the character set is not specified as above, then
272 mhbuild will assume the character set is of the type given by the envi‐
273 ronment variable MM_CHARSET. If this environment variable is not set,
274 then the character set will be labeled as “x-unknown”.
275 If a text content contains only 7-bit characters and the character set
277 is not specified as above, then the character set will be labeled as
278 “us-ascii”.
279 Putting this all together, here is an example of a more complicated
281 message draft. The following draft will expand into a multipart/mixed
282 message containing five parts:
283 To: nobody@nowhere.org
285 cc:
286 Subject: Look and listen to me!
287 --------
288 The first part will be text/plain
289 #<text/enriched
290 The second part will be text/enriched
291 #
292 This third part will be text/plain
293 #audio/basic [silly giggle] \
294 |raw2audio -F < /usr/lib/sounds/giggle.au
295 #image/gif [photo of foobar] \
296 /home/foobar/lib/picture.gif
297 Integrity Check
299 If mhbuild is given the -check switch, then it will also associate an
300 integrity check with each “leaf” content. This will add a Content-MD5
301 header field to the content, along with the md5 sum of the unencoded
302 contents. This may be used by the receiver of the message to verify
303 that the contents of the message were not changed in transport.
304 Transfer Encodings
307 After mhbuild constructs the new MIME message by parsing directives,
308 including files, etc., it scans the contents of the message to deter‐
309 mine which transfer encoding to use. It will check for 8bit data, long
310 lines, spaces at the end of lines, and clashes with multipart bound‐
311 aries. It will then choose a transfer encoding appropriate for each
312 content type.
313 If an integrity check is being associated with each content by using
315 the -check switch, then mhbuild will encode each content with a trans‐
316 fer encoding, even it the content contains only 7-bit data. This is to
317 increase the likelihood that the content is not changed while in trans‐
318 port.
319 The switch -ebcdicsafe will cause mhbuild to slightly change the way in
321 which it performs the “quoted-printable” transfer encoding. Along with
322 encoding 8-bit characters, it will now also encode certain common punc‐
323 tuation characters as well. This slightly reduces the readability of
324 the message, but allows the message to pass more reliably through mail
325 gateways which involve the EBCDIC character encoding.
326 Invoking mhbuild
329 Typically, mhbuild
330 is invoked by the whatnow program. This command will expect the body
331 of the draft to be formatted as an mhbuild composition file. Once you
332 have composed this input file using a command such as comp, repl, or
333 forw, you invoke mhbuild at the “What now” prompt with
334 What now? mime
336 prior to sending the draft. This will cause whatnow to execute mhbuild
338 to translate the composition file into MIME format.
339 It is also possible to have the whatnow program invoke mhbuild automat‐
341 ically when a message is sent. To do this, you must add the line
342 automimeproc: 1
344 to your .mh_profile file.
346 Finally, you should consider adding this line to your profile:
348 lproc: show
350 This way, if you decide to list after invoking mime, the command
352 What now? list
354 will work as you expect.
356 User Environment
359 Because the environment in which mhbuild operates may vary for a user,
360 mhbuild will look for the environment variable $MHBUILD. If present,
361 this specifies the name of an additional user profile which should be
362 read. Hence, when a user logs in on a particular machine, this envi‐
363 ronment variable should be set to refer to a file containing defini‐
364 tions useful for that machine.
365 Finally, mhbuild will attempt to consult a global mhbuild user profile,
367 e.g.,
368 /etc/nmh/mhn.defaults
370 if it exists.
372 Syntax of Composition Files
375 The following is the formal syntax of a mhbuild “composition file”.
376 body ::= 1*(content | EOL)
378 content ::= directive | plaintext
380 directive ::= "#" type "/" subtype
382 0*(";" attribute "=" value)
383 [ "(" comment ")" ]
384 [ "<" id ">" ]
385 [ "[" description "]" ]
386 [ "{" disposition "}" ]
387 [ filename ]
388 EOL
389 | "#@" type "/" subtype
391 0*(";" attribute "=" value)
392 [ "(" comment ")" ]
393 [ "<" id ">" ]
394 [ "[" description "]" ]
395 [ "{" disposition "}" ]
396 external-parameters
397 EOL
398 | "#forw"
400 [ "<" id ">" ]
401 [ "[" description "]" ]
402 [ "{" disposition "}" ]
403 [ "+"folder ] [ 0*msg ]
404 EOL
405 | "#begin"
407 [ "<" id ">" ]
408 [ "[" description "]" ]
409 [ "{" disposition "}" ]
410 [ "alternative"
411 | "parallel"
412 | something-else ]
413 EOL
414 1*body
415 "#end" EOL
416 plaintext ::= [ "Content-Description:"
418 description EOL EOL ]
419 1*line
420 [ "#" EOL ]
421 | "#<" type "/" subtype
423 0*(";" attribute "=" value)
424 [ "(" comment ")" ]
425 [ "[" description "]" ]
426 [ "{" disposition "}" ]
427 EOL
428 1*line
429 [ "#" EOL ]
430 line ::= "##" text EOL
432 -- interpreted as "#"text EOL
433 | text EOL
434
436 $HOME/.mh_profile The user profile
437 $MHBUILD Additional profile entries
438 /etc/nmh/mhn.defaults System default MIME profile entries
439
442 Path: To determine the user's nmh directory
443 Current-Folder: To find the default current folder
444 mhbuild-compose-<type>T*emplate for composing contents
445
448 mhlist(1), mhshow(1), mhstore(1),
449 Proposed Standard for Message Encapsulation (RFC-934),
450 Multipurpose Internet Mail Extensions (MIME) Part One: Format of Inter‐
451 net Message Bodies (RFC-2045),
452 Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types
453 (RFC-2046),
454 Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header
455 Extensions for Non-ASCII Text (RFC-2047),
456 Multipurpose Internet Mail Extensions (MIME) Part Four: Registration
457 Procedures (RFC-2048),
458 Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance
459 Criteria and Examples (RFC-2049)
460
463 `-headers'
464 `-realsize'
465 `-norfc934mode'
466 `-contentid'
467 `-nocheck'
468 `-noebcdicsafe'
469 `-noverbose'
470
473 If a folder is given, it will become the current folder. The last mes‐
474 sage selected will become the current message.
475MH.6.8 1 Jul 2003 MHBUILD(1)