Provided by: nmh_1.3-1_i386 bug

NAME

       mhbuild - translate MIME composition draft

SYNOPSIS

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

DESCRIPTION

       The mhbuild command will translate a  MIME  composition  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 successful, 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 original 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.

   Listing the Contents
       The -list switch tells mhbuild to list the table of contents 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.

   Translating the Composition File
       mhbuild  is  essentially  a  filter  to  aid in the composition of MIME
       messages.  mhbuild will convert an mhbuild “composition  file”  into  a
       valid  MIME  message.   A  mhbuild  “composition  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 information in the
       user’s profile to  determine  how  the  different  contents  should  be
       composed.  This is accomplished by consulting 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
       commands 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 directives, 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] \
                {application; filename="nmh.tar.gz"} \
                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  specified  by  enclosing  it  within  “[]”.   A
       disposition  string,  to  appear in a “Content-Disposition” header, may
       appear in the optional “{}”.

       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 message  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 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 message 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 utilize 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 content.  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 multipart  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-Description”  header  when
       the directive is processed.

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

       Similarly,  a disposition string may optionally be provided between “{”
       and “}” characters; it will be copied  into  the  “Content-Disposition”
       header  when  the  directive  is processed.  If a disposition string is
       provided that does not contain a filename parameter, and a filename  is
       provided   in  the  directive,  it  will  be  added  to  the  “Content-
       Disposition” header.  For example, the following directive:

            #text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt

       creates these message part headers:

            Content-Type: text/plain; charset="iso-8859-1"
            Content-Disposition: attachment; filename="summary.txt"

       By default, mhbuild will  generate  a  unique  “Content-ID:”  for  each
       directive,  corresponding  to  each message part; however, the user may
       override this by defining the ID using the “<” and “>” characters.  The
       -nocontentid  switch  suppresses creation of all “Content-ID:” headers,
       even in the top level of the message.

       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 starting 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 identifies the content type
       of the plaintext.

       When composing a text content, you may indicate the relevant  character
       set by adding the “charset” parameter to the directive.

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

       If  a  text  content contains any 8-bit characters (characters with the
       high bit set) and the character set is not  specified  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 7-bit characters and the character set
       is not specified as above, then the character 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

   Integrity Check
       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.

   Transfer Encodings
       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  content  by  using
       the  -check  switch,  then  mhbuild  will  encode  each  content with a
       transfer encoding, even it the content contains only 7-bit data.   This
       is  to increase the likelihood that the content is not changed while in
       transport.

       The switch -ebcdicsafe will cause mhbuild to slightly change the way in
       which it performs the “quoted-printable” transfer encoding.  Along with
       encoding 8-bit characters, it  will  now  also  encode  certain  common
       punctuation  characters 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.

   Invoking mhbuild
       Typically, mhbuild
        is  invoked by the whatnow program.  This command will expect the body
       of the draft to be formatted as an mhbuild composition file.  Once  you
       have  composed  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 profile:

            lproc: show

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

            What now? list

       will work as you expect.

   User Environment
       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 additional 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
       definitions useful for that machine.

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

            /etc/nmh/mhn.defaults

       if it exists.

   Syntax of Composition Files
       The following is the formal syntax of a mhbuild “composition file”.

            body         ::=     1*(content | EOL)

            content      ::=     directive | plaintext

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

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

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

                               | "#begin"
                                       [ "<" id ">" ]
                                       [ "[" description "]" ]
                                       [ "{" disposition "}" ]
                                       [   "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 "]" ]
                                     [ "{" disposition "}" ]
                                     EOL
                                     1*line
                                 [ "#" EOL ]

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

FILES

       $HOME/.mh_profile          The user profile
       $MHBUILD                   Additional profile entries
       /etc/nmh/mhn.defaults      System default MIME profile entries

PROFILE COMPONENTS

       Path:                To determine the user’s nmh directory
       Current-Folder:      To find the default current folder
       mhbuild-compose-<type>Template for composing contents

SEE ALSO

       mhlist(1), mhshow(1), mhstore(1),
       Proposed Standard for Message Encapsulation (RFC-934),
       Multipurpose  Internet  Mail  Extensions  (MIME)  Part  One:  Format of
       Internet Message Bodies (RFC-2045),
       Multipurpose Internet Mail Extensions  (MIME)  Part  Two:  Media  Types
       (RFC-2046),
       Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header
       Extensions for Non-ASCII Text (RFC-2047),
       Multipurpose Internet Mail Extensions (MIME)  Part  Four:  Registration
       Procedures (RFC-2048),
       Multipurpose  Internet  Mail  Extensions  (MIME) Part Five: Conformance
       Criteria and Examples (RFC-2049)

DEFAULTS

-headers’
       ‘-realsize’
       ‘-norfc934mode’
       ‘-contentid’
       ‘-nocheck’
       ‘-noebcdicsafe’
       ‘-noverbose

CONTEXT

       If a folder is given, it will become  the  current  folder.   The  last
       message selected will become the current message.