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

   Translating the Composition File
       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

       that  is  interspersed  with  various  mhbuild directives.
       When this file is processed by mhbuild, the various direc­
       tives  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­

       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

       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

       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-Description"  header  when  the directive is
       processed.

            #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 "#<"

       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.

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

   Invoking mhbuild
       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


       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.

   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 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/mhn.defaults

       if it exists.

   Syntax of Composition Files

       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



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-<typeTemplate for composing contents


SEE ALSO

       mhlist(1), mhshow(1), mhstore(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.


DEFAULTS

       `-headers'
       `-realsize'
       `-norfc934mode'
       `-nocheck'
       `-noebcdicsafe'
       `-noverbose'


CONTEXT

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


Man(1) output converted with man2html