mhbuild



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 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 trans-
       lation  of  this  input is successful, mhbuild will output the new MIME
       message to the standard output.  This argument must be the  last  argu-
       ment on the command line.

       Otherwise if the file argument to mhbuild is the name of a valid compo-
       sition file, and the translation is successful,  mhbuild  will  replace
       the original file with the new MIME message.  It will rename the origi-
       nal 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 associ-
       ated with the MIME message that is created.

       The `-headers' switch indicates that a one-line banner should  be  dis-
       played  above  the  listing.   The  `-realsize' switch tells mhbuild to
       evaluate the "native" (decoded) format of each content prior  to  list-
       ing.   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  mes-
       sages.  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 con-
       tent.

       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 cap-
       tured 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 com-
       posed.  This is accomplished by consulting a  composition  string,  and
       executing  it  under  /bin/sh, with the standard output set to the con-
       tent.  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 envi-
       ronment used for login,  composition  strings  for  different  contents
       should  probably  be put in the file specified by the $MHBUILD environ-
       ment 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] \
                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 "[]".  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 (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 con-
       tent 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) compati-
       ble 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 con-
       tain  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

       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 sin-
       gle "#" 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  con-
       tent-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-descrip-
       tion 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 8bit  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 envi-
       ronment  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 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 deter-
       mine which transfer encoding to use.  It will check for 8bit data, long
       lines,  spaces  at  the end of lines, and clashes with multipart bound-
       aries.  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 7bit 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  8bit 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 compo-
       sition 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 automat-
       ically 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 envi-
       ronment variable should be set to refer to a  file  containing  defini-
       tions 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 "]" ]
                                        [ 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



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 mes-
       sage selected will become the current message.



[nmh-1.0.4]                         MH.6.8                          MHBUILD(1)

Man(1) output converted with man2html