Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MHBUILD(1)		    General Commands Manual		    MHBUILD(1)

       mhbuild - translate MIME	composition drafts for nmh messages

       mhbuild [-help] [-version] file [-auto |	-noauto] [-list	| -nolist]
	    [-realsize | -norealsize] [-headers	| -noheaders] [-directives |
	    -nodirectives] [-rfc934mode	| -norfc934mode] [-contentid | -nocon-
	    tentid] [-verbose |	-noverbose] [-disposition | -nodisposition]
	    [-check | -nocheck]	[-headerencoding encoding-algorithm  | -auto-
	    headerencoding] [-maxunencoded line-length]	[-dist]

       The mhbuild command will	translate a  MIME  composition	draft  into  a
       valid MIME message.

       mhbuild	creates	multi-media messages as	specified in RFCs 2045 through
       2049.  This includes the	encoding of message headers  as	 specified  by
       RFC  2047, and, additionally, the encoding of MIME parameters as	speci-
       fied in RFC 2231.

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

   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 dis-
       played above the	listing.  The -realsize	switch tells mhbuild to	evalu-
       ate  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.

       If  the	-disposition switch is present,	then the listing will show any
       relevant	information from the "Content-Disposition" header.

   Simplified Attachment Interface
       For users who wish to simply attach files to text content, mhbuild will
       scan  the  composition  file  for "Attach" headers.  An "Attach"	header
       contains	a filename that	will be	appended to the	message	 using	normal
       MIME encapsulation rules.  One filename is allowed per "Attach" header,
       but multiple "Attach" headers are allowed per composition file.

       These files will	be appended after any other  MIME  content,  including
       any  content  specified by mhbuild directives (see below).  See send(1)
       for more	details.

       By default, the	Content-Disposition  will  be  "attachment".   mhbuild
       looks for user profile and mhn.defaults entries of the form


       to  supply  the	disposition value.  The	only supported values are "at-
       tachment" and "inline".

   Convert Interface
       The convert interface is	a powerful mechanism that supports replying to
       MIME  messages.	 These placeholders are	used in	the following descrip-

	    TYPE	   content type/subtype
	    CONVERTER	   external program, and any fixed arguments, to  con-
			   vert	content, such as from a	request	to a reply
	    ARGSTRING	   arguments to	pass from repl to CONVERTER
	    FILE	   full	path of	message	being replied to
       The convert support is based on pseudoheaders of	the form

	    Nmh-mhbuild-file-TYPE: FILE
	    Nmh-mhbuild-args-TYPE: ARGSTRING

       in the draft.  For each such pseudoheader, mhbuild looks	in the profile
       and mhn.defaults	for the	corresponding TYPE entry to find the converter
       that supports it:

	    mhbuild-convert-TYPE: CONVERTER

       It's a fatal error if no	such entry is found for	TYPE.  An empty	entry,


       excludes	parts of that TYPE from	the draft.

       The mhn.defaults	file contains  default	mhbuild-convert-text/html  and
       mhbuild-convert-text/plain  entries.   Profile  entries	can be used to
       override	corresponding mhn.defaults entries, as usual.  Text converters
       should  limit text line lengths to a maximum of 78 characters, and must
       limit them to a maximum of 998 characters, per RFC 5322 Sec. 2.1.1.

       For each	TYPE part in FILE, mhbuild runs	 CONVERTER  ARGSTRING  on  the
       content	of the part.  Each part	in FILE	that has no corresponding TYPE
       entry in	the profile or mhn.defaults is excluded	from  the  draft;  the
       user can	include	them using mhbuild directives.

       repl inserts Nmh-mhbuild-text/html: and Nmh-mhbuild-text/plain: pseudo-
       headers in every	draft.	The user  can  prevent	insertion  of  content
       parts  of  either of those types	by putting corresponding empty entries
       in their	profile.

       Only the	highest	precedence alternative with a supported	TYPE of	a mul-
       tipart/alternative part is used.	selects	 the  text/html-to-text/plain converter	at in-
       stall time.  It includes	iconv and par, or fmt, in the pipeline only if
       they are	found.

       Some  content  types require the	addition of parameters to the Content-
       Type header, such as "method=REPLY" for text/calendar.	mhbuild	 looks
       for  a  Content-Type header, followed by	a blank	line, at the beginning
       of the converter	output.	 If one	is found, it is	used  for  the	corre-
       sponding	part in	the reply draft.

       The convert interface doesn't support different ARGSTRINGs or different
       converters for different	parts of the same TYPE.	  That	would  require
       associating  parts  by  part  number with the ARGSTRINGs	or converters.
       Instead,	that can be done (currently, without using  the	 convert  sup-
       port), with mhbuild directives as described below, e.g.,

	    #text/html;	 charset=utf-8	*8bit  | mhstore -noverbose -part 42.7
	    -outfile - | w3m -dump -cols 64 -T text/html -O utf-8

       The only	way to mix convert pseudoheaders and mhbuild directives	is  to
       insert the directives before mhbuild is run, which is typically done by
       entering	mime at	the "What now?"	prompt,	or  with  an  -editor  mhbuild

       These  (optional)  setup	 steps	can make the convert support easier to

       1)   If the par program is installed on your system, it will be set  by
	    default  (in  mhn.defaults)	 to  filter  the converter output.  It
	    helps to set the PARINIT environment  variable,  as	 described  in

       2)   Add	this line to your profile:

		 mhbuild-next: $EDITOR

	    assuming that your EDITOR environment variable is set; if not, re-
	    place EDITOR with the name of your editor.	Without	 that  profile
	    entry, a response of "e[dit]" at the What now? prompt will require
	    specification of your editor if an -editor mhbuild switch is used.

       3)   If using repl, source the  Bourne-shell  compatible	 functions  in
	    That  script  also sets the	PARINIT	environment variable if	it was
	    not	set.

   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.  An 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  ex-
       panded to the appropriate content, and will be encoded according	to the
       MIME standards.	The resulting MIME message can then be sent  by	 elec-
       tronic 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 \

       There  are  five	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; the "begin" di-
       rective	(#begin), which	is used	to create a multipart content; and the
       "on/off/pop" directives (#on, #off, #pop)  which	 control  whether  any
       other directives	are honored at all.

       The  -directives	 switch	allows control over whether mhbuild will honor
       any of the "#"-directives.  This	can also be affected with the  #on  or
       #off  directives,  and  #pop, which restores the	state of processing to
       that preceding the most recent #on or #off.  (The #on, #off,  and  #pop
       directives  are	always	honored,  of course.) This allows inclusion of
       plain text which	looks like mhbuild directives, without causing errors:

	    #include <stdio.h>
	    printf("Hello, World!");

       Currently the stack depth for the #on/off/pop directives	is 32.

       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/

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


       to  determine the command to use	to compose the content.	 If this isn't
       found, mhbuild will look	for an entry of	the form:


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

	    #@application/octet-stream;	\
		type=tar; \
		conversions=compress \
		[this is the nmh distribution] \
		{attachment; filename="nmh.tar.gz"} \
		name="nmh.tar.gz"; \
		directory="/pub/nmh"; \
		site=""; \
		access-type=anon-ftp; \

       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	dispo-
       sition string, to appear	in a "Content-Disposition" header, may	appear
       in the optional "{}".

       These parameters	are of the form:

	    access-type=  usually "anon-ftp", "mail-server", or	"url"
	    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
	    url=	  URL of content

       A minimum "external-type" directive for the url access-type would be as

	  #@application/octet-stream []	access-type=url; \

       Any long	URLs will be wrapped according to RFC 2231 rules.

       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  di-
       rective 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 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) compatible with
       the encapsulation specified in RFC 934.	If given, then RFC 934 compli-
       ant  user-agents	 should	 be  able  to  burst  the  message  on	recep-
       tion -- 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 us-
       ing the "begin" directive, you must specify at least  one  content  be-
       tween the begin and end pairs.

	    This will be a multipart with only one part.

       If you use multiple directives in a composition draft, mhbuild will au-
       tomatically encapsulate them inside a multipart content.	 Therefore the
       "begin"	directive  is  only necessary if you wish to use nested	multi-
       parts, 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-Disposi-
       tion" 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  di-
       rective,	 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.

       Normally	mhbuild	will choose an	appropriate  Content-Transfer-Encoding
       based on	the content and	the MIME Content-Type.	However, you can over-
       ride that in an mhbuild directive by specifying "*" and	the  encoding.
       Acceptable encoding values are "8bit", "qp" (for	quoted-printable), and
       "b64" (for base64 encoding).  It	should be noted	that undesired results
       may  occur  if 8bit or quoted-printable is selected for binary content,
       due to the translation between Unix line	endings	and the	 line  endings
       use by the mail transport system.

       In  addition  to	 the  various  directives,  plaintext  can be present.
       Plaintext is gathered, until a directive	is found or the	draft  is  ex-
       hausted,	 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.,

	    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

       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 mh-
       build will assume the character set is of the type given	by  the	 stan-
       dard  locale(1)	environment variables.	If these environment variables
       are 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

       By default text content with the	high bit set is	encoded	with an	 8-bit
       Content-Transfer-Encoding.  If the text has lines longer	than the value
       of -maxunencoded	(which defaults	to 78) then the	text is	encoded	 using
       the quoted-printable encoding.

       The  -headerencoding  switch  will indicate which algorithm to use when
       encoding	any message headers that contain 8-bit characters.  The	 valid
       arguments  are base64 for base-64 encoding, quoted for quoted-printable
       encoding, and utf-8 which requires that all 8-bit header	 field	bodies
       be  encoded  as UTF-8 (RFC 6530)	and that the message be	sent to	a SMTP
       server that supports  SMTPUTF8  (RFC  6531).   The  -autoheaderencoding
       switch  instructs  mhbuild  to  automatically pick the encoding,	either
       base64 or quoted-printable, that	results	in a shorter encoded string.

       Putting this all	together, here is an example of	a more complex message
       draft, which will expand	into a multipart/mixed message containing five

	    Subject: Look and listen to	me!
	    The	first part will	be text/plain
	    The	second part will be text/enriched
	    This third part will be text/plain
	    #audio/basic [silly	giggle]	 \
		|raw2audio -F <	/usr/lib/sounds/
	    #image/gif	 [photo	of foobar] \

   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,  per  RFC 1864.  This may be used by the receiver of the mes-
       sage to verify that the contents	of the message	were  not  changed  in

   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 8-bit 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	trans-
       fer encoding, even if the content contains only 7-bit data.  This is to
       increase	the likelihood that the	content	is not changed while in	trans-

   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,	forw,  or  repl,  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.

       Normally	 it is an error	to invoke mhbuild on a file that is already in
       MIME format.  The -auto switch will cause mhbuild to exit without error
       if  the	input  file  already has valid MIME headers.  The use of -auto
       also enables the	-nodirectives switch.

       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.

       The -dist switch	is intended to be used by dist.	 It will cause mhbuild
       to  not	generate  any  MIME  headers  in the composition file (such as
       "MIME-Version" or "Content-Type"), but it  will	still  encode  message
       headers according to RFC	2047.

   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 on that machine.

       Finally,	mhbuild	will attempt to	consult


       if it exists.

       See "Profile Lookup" in mh-profile(5) for the profile search order, and
       for how duplicate entries are treated.

   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 "}" ]
			   [ "*8bit" | "*qp" | "*b64" ]
				     [ filename	]

			       | "#@" type "/" subtype
				     0*(";" attribute "=" value)
				     [ "(" comment ")" ]
				     [ "<" id ">" ]
				     [ "[" description "]" ]
				     [ "{" disposition "}" ]
			   [ "*8bit" | "*qp" | "*b64" ]

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

			       | "#begin"
				       [ "<" id	">" ]
				       [ "[" description "]" ]
				       [ "{" disposition "}" ]
				       [   "alternative"
					 | "parallel"
					 | something-else    ]
				 "#end"	EOL

	    plaintext	 ::=	 [ "Content-Description:"
				       description EOL EOL ]
				 [ "#" EOL ]

			       | "#<" type "/" subtype
				     0*(";" attribute "=" value)
				     [ "(" comment ")" ]
				     [ "[" description "]" ]
				     [ "{" disposition "}" ]
			   [ "*8bit" | "*qp" | "*b64" ]
				 [ "#" EOL ]

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

       mhbuild	looks  for  additional	user profile files and mhn.defaults in
       multiple	locations: absolute pathnames are accessed directly, tilde ex-
       pansion	is done	on usernames, and files	are searched for in the	user's
       Mail directory as specified in their profile.  If not found there,  the
       directory "/usr/local/etc/nmh" is checked.

       $HOME/.mh_profile   The user's profile.
       $MHBUILD		   Additional profile entries.
			   System default MIME profile entries.

       Path:		   To determine	the user's nmh directory.
       Current-Folder:	   To find the default current folder.
			   Template for	composing contents.

       mhlist(1), mhshow(1), mhstore(1)

       Multipurpose Internet Mail Extensions (MIME) Part One: Format of	Inter-
       net Message Bodies (RFC 2045)

       Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types (RFC

       Multipurpose Internet Mail Extensions (MIME) Part Three:	Message	Header
       Extensions for Non-ASCII	Text (RFC 2047)

       Internet	Message	Format (RFC 5322)

       MIME Parameter Value and	Encoded	Word Extensions: Character Sets,  Lan-
       guages, and Continuations (RFC 2231)

       Proposed	Standard for Message Encapsulation (RFC	934)

       The Content-MD5 Header Field (RFC 1864)

       Definition of the URL MIME External-Body	Access-Type (RFC 2017)

       Overview	and Framework for Internationalized Email (RFC 6530)

       SMTP Extension for Internationalized Email (RFC 6531)

       -maxunencoded 78

nmh-1.7.1			  2016-10-15			    MHBUILD(1)


Want to link to this manual page? Use this URL:

home | help