1MHBUILD(1)                         [nmh-1.3]                        MHBUILD(1)
2
3
4

NAME

6       mhbuild - translate MIME composition draft
7

SYNOPSIS

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

DESCRIPTION

15       The mhbuild command will translate a  MIME  composition  draft  into  a
16       valid MIME message.
17
18       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
23       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
29       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
37   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
41       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
49   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
59       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
67            #image/png \
68                /home/foobar/junk/picture.png
69
70       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
77       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
85            #audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
86
87       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
94       The composition string may contain the following escapes:
95
96            %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
102       First, mhbuild will look for an entry of the form:
103
104            mhbuild-compose-<type>/<subtype>
105
106       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
109            mhbuild-compose-<type>
110
111       to determine the composition command. If this isn't found, mhbuild will
112       complain.
113
114       An example entry might be:
115
116            mhbuild-compose-audio/basic: record | raw2audio -F
117
118       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
123       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
130            #@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
141       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
147       These parameters are of the form:
148
149            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
160       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
169            #forw +inbox 42 43 99
170
171       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
176       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
187       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
191            #begin
192            This will be a multipart with only one part.
193            #end
194
195       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
200       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
205            #forw [important mail from Bob] +bob 1 2 3 4 5
206
207       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
214            #text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt
215
216       creates these message part headers:
217
218            Content-Type: text/plain; charset="iso-8859-1"
219            Content-Disposition: attachment; filename="summary.txt"
220
221       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
227       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
232            ##when sent, this line will start with only one #
233
234       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
238            this is the first content
239            #
240            and this is the second
241
242       Finally, if the plaintext starts with a line of the form:
243
244            Content-Description: text
245
246       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
249       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
253            #<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
261       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
265       When composing a text content, you may indicate the relevant  character
266       set by adding the “charset” parameter to the directive.
267
268            #<text/plain; charset=iso-8859-5
269
270       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
276       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
280       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
284            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
298   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
305
306   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
314       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
320       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
327
328   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
335            What now? mime
336
337       prior to sending the draft.  This will cause whatnow to execute mhbuild
338       to translate the composition file into MIME format.
339
340       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
343            automimeproc: 1
344
345       to your .mh_profile file.
346
347       Finally, you should consider adding this line to your profile:
348
349            lproc: show
350
351       This way, if you decide to list after invoking mime, the command
352
353            What now? list
354
355       will work as you expect.
356
357
358   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
366       Finally, mhbuild will attempt to consult a global mhbuild user profile,
367       e.g.,
368
369            /etc/nmh/mhn.defaults
370
371       if it exists.
372
373
374   Syntax of Composition Files
375       The following is the formal syntax of a mhbuild “composition file”.
376
377            body         ::=     1*(content | EOL)
378
379            content      ::=     directive | plaintext
380
381            directive    ::=     "#" type "/" subtype
382                                     0*(";" attribute "=" value)
383                                     [ "(" comment ")" ]
384                                     [ "<" id ">" ]
385                                     [ "[" description "]" ]
386                                     [ "{" disposition "}" ]
387                                     [ filename ]
388                                     EOL
389
390                               | "#@" type "/" subtype
391                                     0*(";" attribute "=" value)
392                                     [ "(" comment ")" ]
393                                     [ "<" id ">" ]
394                                     [ "[" description "]" ]
395                                     [ "{" disposition "}" ]
396                                     external-parameters
397                                     EOL
398
399                               | "#forw"
400                                     [ "<" id ">" ]
401                                     [ "[" description "]" ]
402                                     [ "{" disposition "}" ]
403                                     [ "+"folder ] [ 0*msg ]
404                                     EOL
405
406                               | "#begin"
407                                       [ "<" id ">" ]
408                                       [ "[" description "]" ]
409                                       [ "{" disposition "}" ]
410                                       [   "alternative"
411                                         | "parallel"
412                                         | something-else    ]
413                                       EOL
414                                     1*body
415                                 "#end" EOL
416
417            plaintext    ::=     [ "Content-Description:"
418                                       description EOL EOL ]
419                                     1*line
420                                 [ "#" EOL ]
421
422                               | "#<" type "/" subtype
423                                     0*(";" attribute "=" value)
424                                     [ "(" comment ")" ]
425                                     [ "[" description "]" ]
426                                     [ "{" disposition "}" ]
427                                     EOL
428                                     1*line
429                                 [ "#" EOL ]
430
431            line         ::=     "##" text EOL
432                                 -- interpreted as "#"text EOL
433                               | text EOL
434

FILES

436       $HOME/.mh_profile          The user profile
437       $MHBUILD                   Additional profile entries
438       /etc/nmh/mhn.defaults      System default MIME profile entries
439
440

PROFILE COMPONENTS

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
446

SEE ALSO

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
461

DEFAULTS

463       `-headers'
464       `-realsize'
465       `-norfc934mode'
466       `-contentid'
467       `-nocheck'
468       `-noebcdicsafe'
469       `-noverbose'
470
471

CONTEXT

473       If a folder is given, it will become the current folder.  The last mes‐
474       sage selected will become the current message.
475
476
477
478MH.6.8                            1 June 2008                       MHBUILD(1)
Impressum