git.marmaro.de Git - mmh/blob - 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 [ \-list " | " \-nolist ]
  13 .RB [ \-headers " | " \-noheaders ]
  14 .RB [ \-contentid " | " \-nocontentid ]
  15 .RB [ \-verbose " | " \-noverbose ]
  16 .RB [ \-version ]
  17 .RB [ \-help ]
  18 .ad
  19 .SH DESCRIPTION
  20 The
  21 .B mhbuild
  22 command will translate a MIME composition draft into
  23 a valid MIME message.
  24 .PP
  25 .B mhbuild
  26 creates multi-media messages as specified in RFC\-2045
  27 thru RFC\-2049.  Currently
  28 .B mhbuild
  29 only supports encodings in
  30 message bodies, and does not support the encoding of message headers as
  31 specified in RFC\-2047.
  32 .PP
  33 If you specify the name of the composition file as \*(lq-\*(rq,
  34 then
  35 .B mhbuild
  36 will accept the composition draft on the standard
  37 input.  If the translation of this input is successful,
  38 .B mhbuild
  39 will output the new MIME message to the standard output.  This argument
  40 must be the last argument on the command line.
  41 .PP
  42 Otherwise if the file argument to
  43 .B mhbuild
  44 is the name of a valid
  45 composition file, and the translation is successful,
  46 .B mhbuild
  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
  51 recover the
  52 .B mhbuild
  53 input file.
  54 .SS "Listing the Contents"
  55 The
  56 .B \-list
  57 switch tells
  58 .B mhbuild
  59 to list the table of contents associated with the MIME message that is created.
  60 .PP
  61 The
  62 .B \-headers
  63 switch indicates
  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.
  68 If the
  69 .B \-verbose
  70 switch
  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"
  75 .B mhbuild
  76 is essentially a filter to aid in the composition of MIME
  77 messages.
  78 .B mhbuild
  79 will convert an
  80 .B mhbuild
  81 \*(lqcomposition file\*(rq
  82 into a valid MIME message.  A
  83 .B mhbuild
  84 \*(lqcomposition file\*(rq
  85 is just a file containing plain text that is interspersed
  86 with various
  87 .B mhbuild
  88 directives.  When this file is processed
  89 by
  90 .BR mhbuild ,
  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.
  94 .PP
  95 The formal syntax for a
  96 .B mhbuild
  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
 103 than one line, e.g.,
 104 .PP
 105 .RS 5
 106 .nf
 107 #image/png \\
 108     /home/foobar/junk/picture.png
 109 .fi
 110 .RE
 111 .PP
 112 There are three kinds of directives:
 113 \*(lqtype\*(rq,
 114 \*(lqmessage\*(rq (#forw),
 115 and \*(lqbegin\*(rq (#begin).
 116 .PP
 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.
 125 For example,
 126 .PP
 127 .RS 5
 128 .nf
 129 #audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
 130 .fi
 131 .RE
 132 .PP
 133 If a filename is not given,
 134 .B mhbuild
 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
 138 it under
 139 .BR /bin/sh ,
 140 with the standard output set to the content.
 141 If the
 142 .B \-verbose
 143 switch is given,
 144 .B mhbuild
 145 will echo any commands that are used to create contents in this way.
 146 .PP
 147 The composition string may contain the following escapes:
 148 .PP
 149 .RS 5
 150 .nf
 151 .ta \w'%P  'u
 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 %
 157 .fi
 158 .RE
 159 .PP
 160 First,
 161 .B mhbuild
 162 will look for an entry of the form:
 163 .PP
 164 .RS 5
 165 mhbuild-compose-<type>/<subtype>
 166 .RE
 167 .PP
 168 to determine the command to use to compose the content.  If this isn't
 169 found,
 170 .B mhbuild
 171 will look for an entry of the form:
 172 .PP
 173 .RS 5
 174 mhbuild-compose-<type>
 175 .RE
 176 .PP
 177 to determine the composition command. If this isn't found,
 178 .B mhbuild
 179 will complain.
 180 .PP
 181 An example entry might be:
 182 .PP
 183 .RS 5
 184 mhbuild-compose-audio/basic: record | raw2audio -F
 185 .RE
 186 .PP
 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
 190 .B $MHBUILD
 191 environment variable, instead of directly in your
 192 user profile.
 193 .PP
 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
 200 is used by
 201 .BR forw .
 202 .PP
 203 For example,
 204 .PP
 205 .RS 5
 206 .nf
 207 #forw +inbox 42 43 99
 208 .fi
 209 .RE
 210 .PP
 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,
 213 then
 214 .B mhbuild
 215 will add a content of type \*(lqmultipart/digest\*(rq
 216 and include each message as a subpart of this content.
 217 .PP
 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.
 222 .PP
 223 .RS 5
 224 .nf
 225 #begin
 226 This will be a multipart with only one part.
 227 #end
 228 .fi
 229 .RE
 230 .PP
 231 If you use multiple directives in a composition draft,
 232 .B mhbuild
 233 will
 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.
 237 .PP
 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.
 242 .PP
 243 .RS 5
 244 .nf
 245 #forw [important mail from Bob] +bob 1 2 3 4 5
 246 .fi
 247 .RE
 248 .PP
 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
 255 following directive:
 256 .PP
 257 .RS 5
 258 .nf
 259 #text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt
 260 .fi
 261 .RE
 262 .PP
 263 creates these message part headers:
 264 .PP
 265 .RS 5
 266 .nf
 267 Content-Type: text/plain; charset="iso-8859-1"
 268 Content-Disposition: attachment; filename="summary.txt"
 269 .fi
 270 .RE
 271 .PP
 272 By default,
 273 .B mhbuild
 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
 277 characters.  The
 278 .B \-nocontentid
 279 switch suppresses creation of all \*(lqContent-ID:\*(rq headers,
 280 even in the top level of the message.
 281 .PP
 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,
 286 e.g.,
 287 .PP
 288 .RS 5
 289 ##when sent, this line will start with only one #
 290 .RE
 291 .PP
 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.,
 295 .PP
 296 .RS 5
 297 .nf
 298 this is the first content
 299 #
 300 and this is the second
 301 .fi
 302 .RE
 303 .PP
 304 Finally, if the plaintext starts with a line of the form:
 305 .PP
 306 .RS 5
 307 Content-Description: text
 308 .RE
 309 .PP
 310 then this will be used to describe the plaintext content.
 311 You MUST follow this line with a blank line before starting
 312 your text.
 313 .PP
 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.,
 317 .PP
 318 .RS 5
 319 .nf
 320 #<text/enriched
 321 this content will be tagged as text/enriched
 322 #
 323 and this content will be tagged as text/plain
 324 #
 325 #<application/x-patch [this is a patch]
 326 and this content will be tagged as application/x-patch
 327 .fi
 328 .RE
 329 .PP
 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.
 333 .PP
 334 When composing a text content, you may indicate the relevant character
 335 set by adding the \*(lqcharset\*(rq parameter to the directive.
 336 .PP
 337 .RS 5
 338 #<text/plain; charset=iso-8859-5
 339 .RE
 340 .PP
 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
 343 .B mhbuild
 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.
 347 .PP
 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
 350 \*(lqus-ascii\*(rq.
 351 .PP
 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:
 356 .PP
 357 .RS 5
 358 .nf
 359 To: nobody@nowhere.org
 360 Cc:
 361 Subject: Look and listen to me!
 362 --------
 363 The first part will be text/plain
 364 #<text/enriched
 365 The second part will be text/enriched
 366 #
 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
 372 .fi
 373 .RE
 374
 375 .SS "Transfer Encodings"
 376 After
 377 .B mhbuild
 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.
 383
 384 .SS "Invoking mhbuild"
 385 Typically,
 386 .B mhbuild
 387 is invoked by the
 388 .B send
 389 program.
 390 It expects an
 391 .B mhbuild
 392 composition file, which
 393 .B send
 394 will create, from the draft file, if MIME features are requested.
 395 This is the case with attachment headers.
 396 .PP
 397 In contrast to previous versions, the user does not need to care
 398 for any special actions anymore.
 399
 400 .SS "User Environment"
 401 Because the environment in which
 402 .B mhbuild
 403 operates may vary for a
 404 user,
 405 .B mhbuild
 406 will look for the environment variable
 407 .BR $MHBUILD .
 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.
 412 .PP
 413 Finally,
 414 .B mhbuild
 415 will attempt to consult a global
 416 .B mhbuild
 417 user profile, e.g.,
 418 .PP
 419 .RS 5
 420 %etcdir%/mhn.defaults
 421 .RE
 422 .PP
 423 if it exists.
 424
 425 .SS "Syntax of Composition Files"
 426 The following is the formal syntax of a
 427 .B mhbuild
 428 \*(lqcomposition file\*(rq.
 429 .PP
 430 .RS 5
 431 .nf
 432 body         ::=     1*(content | EOL)
 433
 434 content      ::=     directive | plaintext
 435
 436 directive    ::=     "#" type "/" subtype
 437                          0*(";" attribute "=" value)
 438                          [ "(" comment ")" ]
 439                          [ "<" id ">" ]
 440                          [ "[" description "]" ]
 441                          [ "{" disposition "}" ]
 442                          [ filename ]
 443                          EOL
 444
 445                    | "#forw"
 446                          [ "<" id ">" ]
 447                          [ "[" description "]" ]
 448                          [ "{" disposition "}" ]
 449                          [ "+"folder ] [ 0*msg ]
 450                          EOL
 451
 452                    | "#begin"
 453                            [ "<" id ">" ]
 454                            [ "[" description "]" ]
 455                            [ "{" disposition "}" ]
 456                            [   "alternative"
 457                              | "parallel"
 458                              | something-else    ]
 459                            EOL
 460                          1*body
 461                      "#end" EOL
 462
 463 plaintext    ::=     [ "Content-Description:"
 464                            description EOL EOL ]
 465                          1*line
 466                      [ "#" EOL ]
 467
 468                    | "#<" type "/" subtype
 469                          0*(";" attribute "=" value)
 470                          [ "(" comment ")" ]
 471                          [ "[" description "]" ]
 472                          [ "{" disposition "}" ]
 473                          EOL
 474                          1*line
 475                      [ "#" EOL ]
 476
 477 line         ::=     "##" text EOL
 478                      -- interpreted as "#"text EOL
 479                    | text EOL
 480 .fi
 481 .RE
 482 .PP
 483
 484 .SH FILES
 485 .fc ^ ~
 486 .nf
 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
 491 .fi
 492
 493 .SH "PROFILE COMPONENTS"
 494 .fc ^ ~
 495 .nf
 496 .ta 2.4i
 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
 501 .fi
 502
 503 .SH "SEE ALSO"
 504 mhlist(1), show(1), mhstore(1), forw(1),
 505 .br
 506 .I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies"
 507 (RFC\-2045),
 508 .br
 509 .I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types"
 510 (RFC\-2046),
 511 .br
 512 .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text"
 513 (RFC\-2047),
 514 .br
 515 .I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures"
 516 (RFC\-2048),
 517 .br
 518 .I "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples"
 519 (RFC\-2049)
 520
 521 .SH DEFAULTS
 522 .nf
 523 .RB ` \-headers '
 524 .RB ` \-contentid '
 525 .RB ` \-noverbose '
 526 .fi
 527
 528 .SH CONTEXT
 529 If a folder is given, it will become the current folder.  The last
 530 message selected will become the current message.