Provided by: nmh_1.3-1build1_amd64 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.