MHBUILD(1)                                             MHBUILD(1)

NAME
       mhbuild - translate MIME composition draft

SYNOPSIS
       mhbuild file
            [-list] [-nolist] [-realsize] [-norealsize]
            [-headers] [-noheaders] [-ebcdicsafe] [-noebcdicsafe]
            [-rfc934mode] [-norfc934mode] [-verbose] [-noverbose]
            [-check] [-nocheck] [-version] [-help]

DESCRIPTION
       The mhbuild command will translate a MIME compostion draft
       into a valid MIME message.

       mhbuild  creates  multi-media  messages  as  specified  in
       RFC-2045  thru  RFC-2049.  Currently mhbuild only supports
       encodings in message bodies,  and  does  not  support  the
       encoding of message headers as specified in RFC-2047.

       If  you  specify  the name of the composition file as "-",
       then mhbuild will accept  the  composition  draft  on  the
       standard  input.  If the translation of this input is suc-
       cessful, mhbuild will output the new MIME message  to  the
       standard  output.  This argument must be the last argument
       on the command line.

       Otherwise if the file argument to mhbuild is the name of a
       valid composition file, and the translation is successful,
       mhbuild will replace the orginal file with  the  new  MIME
       message.   It  will rename the original file to start with
       the "," character and end with the string  ".orig",  e.g.,
       if you are editing the file "draft", it will be renamed to
       ",draft.orig".  This allows  you  to  easily  recover  the
       mhbuild input file.

       The `-list' switch tells mhbuild to list the table of con-
       tents associated with the MIME message that is created.

       The `-headers' switch indicates  that  a  one-line  banner
       should  be  displayed  above the listing.  The `-realsize'
       switch tells mhbuild to evaluate  the  "native"  (decoded)
       format of each content prior to listing.  This provides an
       accurate count at the expense of a small  delay.   If  the
       `-verbose'  switch  is present, then the listing will show
       any "extra" information that is present  in  the  message,
       such as comments in the Content-Type header.

       mhbuild  is essentially a filter to aid in the composition
       of MIME messages.  mhbuild will convert an mhbuild "compo-
       sition file" into a valid MIME message.  A mhbuild "compo-
       sition file" is just a file containing plain text that  is
       interspersed  with  various mhbuild directives.  When this
       file is processed by mhbuild, the various directives  will
       be  expanded  to  the  appropriate  content,  and  will be
       encoded according to the MIME  standards.   The  resulting
       MIME message can then be sent by electronic mail.

       The  formal  syntax  for  a  mhbuild  composition  file is
       defined at the end of this document, but the ideas  behind
       this format are not complex.  Basically, the body contains
       one or more contents.  A  content  consists  of  either  a
       directive,  indicated with a "#" as the first character of
       a line; or, plaintext (one or more lines  of  text).   The
       continuation character, "\", may be used to enter a single
       directive on more than one line, e.g.,

            #image/png \
                /home/foobar/junk/picture.png

       There are four kinds  of  directives:  "type"  directives,
       which name the type and subtype of the content; "external-
       type" directives, which also name the type and subtype  of
       the  content;  the  "message"  directive (#forw), which is
       used to forward one or more  messages;  and,  the  "begin"
       directive  (#begin),  which  is used to create a multipart
       content.

       The "type" directive is used to directly specify the  type
       and  subtype  of a content.  You may only specify discrete
       types in this manner (can't specify the types multipart or
       message  with this directive).  You may optionally specify
       the name of a file containing  the  contents  in  "native"
       (decoded)  format.   If  this filename starts with the "|"
       character, then it represents a command to  execute  whose
       output is captured accordingly.  For example,

            #audio/basic |raw2audio -F < /usr/lib/sound/giggle.au

       If a filename is not given, mhbuild will look for informa-
       tion in the user's profile to determine how the  different
       contents should be composed.  This is accomplished by con-
       sulting a  composition  string,  and  executing  it  under
       /bin/sh,  with the standard output set to the content.  If
       the `-verbose' switch is given, mhbuild will echo any com-
       mands  that  are used to create contents in this way.  The
       composition string may contain the following escapes:

            %a  Insert parameters from directive
            %f  Insert filename containing content
            %F  %f, and stdout is not re-directed
            %s  Insert content subtype
            %%  Insert character %

       First, mhbuild will look for an entry of the form:

            mhbuild-compose-<type>/<subtype>

       to determine the command to use to  compose  the  content.
       If this isn't found, mhbuild will look for an entry of the
       form:

            mhbuild-compose-<type>

       to determine the composition command.

       If this isn't found, mhbuild will complain.

       An example entry might be:

            mhbuild-compose-audio/basic: record | raw2audio -F

       Because commands like these will vary,  depending  on  the
       display  environment  used  for login, composition strings
       for different contents should probably be put in the  file
       specified by the $MHBUILD environment variable, instead of
       directly in your user profile.

       The "external-type" directives are used to provide a  MIME
       reference to a content, rather than enclosing the contents
       itself (for instance, by specifying an ftp site).   Hence,
       instead  of  providing  a filename as with the type direc-
       tives, external-parameters are supplied.  These look  like
       regular parameters, so they must be separated accordingly.
       For example,

            #@application/octet-stream; \
                type=tar; \
                conversions=compress \
                [this is the nmh distribution] \
                name="nmh.tar.gz"; \
                directory="/pub/nmh"; \
                site="ftp.math.gatech.edu"; \
                access-type=anon-ftp; \
                mode="image"

       You must give a description string to separate the content
       parameters  from  the  external-parameters  (although this
       string may be empty).  This description string  is  speci-
       fied by enclosing it within "[]".  These parameters are of
       the form:

            access-type=  usually anon-ftp or mail-server
            name=         filename
            permission=   read-only or read-write
            site=         hostname
            directory=    directoryname (optional)
            mode=         usually ascii or image (optional)
            size=         number of octets
            server=       mailbox
            subject=      subject to send
            body=         command to send for retrieval

       The "message" directive (#forw) is used to specify a  mes-
       sage  or group of messages to include.  You may optionally
       specify the name of the folder and which messages  are  to
       be  forwarded.   If  a folder is not given, it defaults to
       the current folder.  Similarly, if a message is not given,
       it  defaults  to  the current message.  Hence, the message
       directive is similar to the forw (1) command, except  that
       the  former  uses  the MIME rules for encapsulation rather
       than those specified in RFC-934.  For example,

            #forw +inbox 42 43 99

       If you include a  single  message,  it  will  be  included
       directly  as  a  content of type "message/rfc822".  If you
       include more than one message, then  mhbuild  will  add  a
       content  of  type "multipart/digest" and include each mes-
       sage as a subpart of this content.

       If you are using this directive to include more  than  one
       message,  you  may  use  the  `-rfc934mode'  switch.  This
       switch will indicate that mhbuild should attempt  to  uti-
       lize  the  MIME encapsulation rules in such a way that the
       "multipart/digest" that is created is (mostly)  compatible
       with  the  encapsulation  specified in RFC-934.  If given,
       then RFC-934 compliant user-agents should be able to burst
       the  message  on  reception -- providing that the messages
       being encapsulated do not  contain  encapsulated  messages
       themselves.   The  drawback  of  this approach is that the
       encapsulations are generated by placing an  extra  newline
       at the end of the body of each message.

       The  "begin"  directive is used to create a multipart con-
       tent.  When using the "begin" directive, you must  specify
       at least one content between the begin and end pairs.

            #begin
            This will be a multipart with only one part.
            #end

       If  you  use  multiple  directives in a composition draft,
       mhbuild will automatically encapsulate them inside a  mul-
       tipart  content.   Therefore the "begin" directive is only
       necessary if you wish to use nested multiparts, or  create
       a multipart message containing only one part.

       For  all of these directives, the user may include a brief
       description of the content between the "["  character  and
       the  "]"  character.  This description will be copied into
       the "Content-Desciption" header when the directive is pro-
       cessed.

            #forw [important mail from Bob] +bob 1 2 3 4 5

       By  default,  mhbuild will generate a unique "Content-ID:"
       for each directive; however, the user may override this by
       defining the ID using the "<" and ">" characters.

       In  addition  to  the various directives, plaintext can be
       present.  Plaintext is  gathered,  until  a  directive  is
       found  or the draft is exhausted, and this is made to form
       a text content.  If the plaintext must contain  a  "#"  at
       the beginning of a line, simply double it, e.g.,

            ##when sent, this line will start with only one #

       If  you  want  to  end the plaintext prior to a directive,
       e.g., to have  two  plaintext  contents  adjacent,  simply
       insert a line containing a single "#" character, e.g.,

            this is the first content
            #
            and this is the second

       Finally, if the plaintext starts with a line of the form:

            Content-Description: text

       then  this will be used to describe the plaintext content.
       You MUST follow this line with a blank line before  start-
       ing your text.

       By default, plaintext is captured as a text/plain content.
       You can override this by starting the plaintext with  "#<"
       followed  by  a  content-type specification.  For example,
       e.g.,

            #<text/enriched
            this content will be tagged as text/enriched
            #
            and this content will be tagged as text/plain
            #
            #<application/x-patch [this is a patch]
            and this content will be tagged as application/x-patch

       Note that if you use the  "#<"  plaintext-form,  then  the
       content-description must be on the same line which identi-
       fies the content type of the plaintext.

       When composing a text content, you may indicate the  rele-
       vant  character  set  by adding the "charset" parameter to
       the directive.

            #<text/plain; charset=iso-8859-5

       If a text content contains any 8bit characters (characters
       with the high bit set) and the character set is not speci-
       fied as above, then mhbuild will assume the character  set
       is   of   the  type  given  by  the  environment  variable
       MM_CHARSET.  If this environment variable is not set, then
       the character set will be labeled as "x-unknown".

       If  a  text  content contains only 7bit characters and the
       character set is not specified as above, then the  charac-
       ter set will be labeled as "us-ascii"

       Putting  this  all  together, here is an example of a more
       complicated  message  draft.   The  following  draft  will
       expand  into  a  multipart/mixed  message  containing five
       parts:

            To: nobody@nowhere.org
            cc:
            Subject: Look and listen to me!
            --------
            The first part will be text/plain
            #<text/enriched
            The second part will be text/enriched
            #
            This third part will be text/plain
            #audio/basic [silly giggle]  \
                |raw2audio -F < /usr/lib/sounds/giggle.au
            #image/gif   [photo of foobar] \
                                /home/foobar/lib/picture.gif

       If mhbuild is given the `-check' switch, then it will also
       associate  an  integrity  check  with each "leaf" content.
       This will add a Content-MD5 header field to  the  content,
       along  with  the  md5 sum of the unencoded contents.  This
       may be used by the receiver of the message to verify  that
       the contents of the message were not changed in transport.

       After mhbuild constructs the new MIME message  by  parsing
       directives,  including  files, etc., it scans the contents
       of the message to determine  which  transfer  encoding  to
       use.   It  will check for 8bit data, long lines, spaces at
       the end of lines, and clashes with  multipart  boundaries.
       It  will  then  choose a transfer encoding appropriate for
       each content type.

       If an integrity check is being associated with  each  con-
       tent  by  using  the  `-check'  switch,  then mhbuild will
       encode each content with a transfer encoding, even it  the
       content  contains only 7bit data.  This is to increase the
       likelihood that the content is not changed while in trans-
       port.

       The  switch  `-ebcdicsafe'  will cause mhbuild to slightly
       change the way in which it performs the "quoted-printable"
       transfer  encoding.   Along with encoding 8bit characters,
       it will now also encode certain common punctuation charac-
       ters  as  well.   This slightly reduces the readability of
       the message, but allows the message to pass more  reliably
       through  mail  gateways which involve the EBCDIC character
       encoding.

       Typically, mhbuild is  invoked  by  the  whatnow  program.
       This  command will expect the body of the draft to be for-
       matted as an mhbuild composition file.  Once you have com-
       posed  this input file using a command such as comp, repl,
       or forw, you invoke mhbuild at the "What now" prompt with

            What now? mime

       prior to sending the draft.  This will  cause  whatnow  to
       execute  mhbuild  to  translate  the composition file into
       MIME format.

       It is also possible to have  the  whatnow  program  invoke
       mhbuild automatically when a message is sent.  To do this,
       you must add the line

            automimeproc: 1

       to your .mh_profile file.

       Finally, you should consider adding this line to your pro-
       file:

            lproc: show

       This  way,  if you decide to list after invoking mime, the
       command

            What now? list

       will work as you expect.

       Because the environment in which mhbuild operates may vary
       for a user, mhbuild will look for the environment variable
       $MHBUILD.  If present, this specifies the name of an addi-
       tional  user  profile which should be read.  Hence, when a
       user logs in on a  particular  machine,  this  environment
       variable should be set to refer to a file containing defi-
       nitions useful for that machine.

       Finally, mhbuild will attempt to consult a global  mhbuild
       user profile, e.g.,

            /etc/nmh/mhbuild.defaults

       if it exists.

       The  following is the formal syntax of a mhbuild "composi-
       tion file".

               body         ::=     1*(content | EOL)

               content      ::=     directive | plaintext

               directive    ::=     "#" type "/" subtype
                                        0*(";" attribute "=" value)
                                        [ "(" comment ")" ]
                                        [ "<" id ">" ]
                                        [ "[" description "]" ]
                                        [ filename ]
                                        EOL

                                  | "#@" type "/" subtype
                                        0*(";" attribute "=" value)
                                        [ "(" comment ")" ]
                                        [ "<" id ">" ]
                                        [ "[" description "]" ]
                                        external-parameters
                                        EOL

                                  | "#forw"
                                        [ "<" id ">" ]
                                        [ "[" description "]" ]
                                        [ "+"folder ] [ 0*msg ]
                                        EOL

                                  | "#begin"
                                          [ "<" id ">" ]
                                          [ "[" description "]" ]
                                          [   "alternative"
                                            | "parallel"
                                            | something-else    ]
                                          EOL
                                        1*body
                                    "#end" EOL

               plaintext    ::=     [ "Content-Description:"
                                          description EOL EOL ]
                                        1*line
                                    [ "#" EOL ]

                                  | "#<" type "/" subtype
                                        0*(";" attribute "=" value)
                                        [ "(" comment ")" ]
                                        [ "[" description "]" ]
                                        EOL
                                        1*line
                                    [ "#" EOL ]

               line         ::=     "##" text EOL
                                    -- interpreted as "#"text EOL
                                  | text EOL

       ^$HOME/.mh_profile~^The user profile ^$MHBUILD~^Additional
       profile entries ^/etc/nmh/mhbuild.defaults~^System-default
       profile entries ^Path:~^To determine the user's nmh direc-
       tory  ^Current-Folder:~^To find the default current folder
       ^mhbuild-compose-<type>*~^Template for composing  contents
       mhn(1)
       RFC-934:
          Proposed Standard for Message Encapsulation,
       RFC-2045:
          Multipurpose Internet Mail Extensions (MIME) Part One:
          Format of Internet Message Bodies,
       RFC-2046:
          Multipurpose Internet Mail Extensions (MIME) Part Two:
          Media Types,
       RFC-2047:
          Multipurpose   Internet  Mail  Extensions  (MIME)  Part
       Three:
          Message Header Extensions for Non-ASCII Text,
       RFC-2048:
          Multipurpose Internet Mail Extensions (MIME) Part Four:
          Registration Procedures,
       RFC-2049:
          Multipurpose Internet Mail Extensions (MIME) Part Five:
          Conformance Criteria and Examples.  `-headers'  `-real-
       size'  `-norfc934mode' `-nocheck' `-noebcdicsafe' `-nover-
       bose' If a folder is given, it  will  become  the  current
       folder.  The last message selected will become the current
       message.

[nmh-0.27]                    MH.6.8                            1