From mboxrd@z Thu Jan  1 00:00:00 1970
X-Msuck: nntp://news.gmane.io/gmane.emacs.gnus.general/18643
Path: main.gmane.org!not-for-mail
From: Richard Coleman <coleman@math.gatech.edu>
Newsgroups: gmane.emacs.gnus.general
Subject: Re: Scriptin' MIME
Date: Sat, 14 Nov 1998 15:48:08 -0500
Sender: owner-ding@hpc.uh.edu
Message-ID: <199811142048.PAA16504@math.gatech.edu>
References: <larsi@gnus.org>
NNTP-Posting-Host: coloc-standby.netfonds.no
X-Trace: main.gmane.org 1035157131 7232 80.91.224.250 (20 Oct 2002 23:38:51 GMT)
X-Complaints-To: usenet@main.gmane.org
NNTP-Posting-Date: Sun, 20 Oct 2002 23:38:51 +0000 (UTC)
Return-Path: <owner-ding@hpc.uh.edu>
Original-Received: from karazm.math.uh.edu (karazm.math.uh.edu [129.7.128.1])
	by sclp3.sclp.com (8.8.5/8.8.5) with ESMTP id PAA25011
	for <jason@mailhost.sclp.com>; Sat, 14 Nov 1998 15:47:28 -0500 (EST)
Original-Received: from sina.hpc.uh.edu (lists@Sina.HPC.UH.EDU [129.7.3.5])
	by karazm.math.uh.edu (8.9.1/8.9.1) with ESMTP id OAB05563;
	Sat, 14 Nov 1998 14:47:18 -0600 (CST)
Original-Received: by sina.hpc.uh.edu (TLB v0.09a (1.20 tibbs 1996/10/09 22:03:07)); Sat, 14 Nov 1998 14:47:13 -0600 (CST)
Original-Received: from sclp3.sclp.com (root@sclp3.sclp.com [209.195.19.139]) by sina.hpc.uh.edu (8.7.3/8.7.3) with ESMTP id OAA19395 for <ding@hpc.uh.edu>; Sat, 14 Nov 1998 14:47:00 -0600 (CST)
Original-Received: from math.gatech.edu (root@math.gatech.edu [130.207.146.50])
	by sclp3.sclp.com (8.8.5/8.8.5) with ESMTP id PAA25002
	for <ding@gnus.org>; Sat, 14 Nov 1998 15:46:51 -0500 (EST)
Original-Received: from math.gatech.edu (coleman@localhost [127.0.0.1])
	by math.gatech.edu (8.9.1/8.9.1) with ESMTP id PAA16504
	for <ding@gnus.org>; Sat, 14 Nov 1998 15:48:08 -0500 (EST)
Original-To: ding@gnus.org
In-Reply-To: Message from Lars Magne Ingebrigtsen <larsi@gnus.org> 
   of "14 Nov 1998 19:27:21 +0100." <m367ciqgdy.fsf@sparky.gnus.org> 
Precedence: list
X-Majordomo: 1.94.jlt7
Xref: main.gmane.org gmane.emacs.gnus.general:18643
X-Report-Spam: http://spam.gmane.org/gmane.emacs.gnus.general:18643

> > Which is basically what elm does.  Or did.  I haven't used it for a
> > while.  MH/nmh also provide something like this.  Perhaps it would be
> > good to use the same syntax, or something?
> 
> Could someone who has used elm or MH give a description of their MIME
> composition interfaces? 

I'm the author of nmh.  The translation of MIME composition drafts
is done with a command called mhbuild.  Here is the man page for
it, which explains the syntax.

But I wouldn't necessarily recommend that you do it this way.  The
MH code base is pretty old.  I expect I would do many things
differently, if I was writing this from scratch.

But it does allow the creating of fairly complicated MIME messages.

Richard Coleman (author, nmh)
coleman@math.gatech.edu


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.


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


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

       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.


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

	    /home/rcoleman/nmh-bin/etc/mhn.defaults

       if it exists.


   Syntax of Composition Files
       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


FILES
       $HOME/.mh_profile		    The user profile
       $MHBUILD 			    Additional profile entries
       /home/rcoleman/nmh-bin/etc/mhn.defaulSystem 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.