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

FreeBSD Manual Pages

  
 
  

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

NAME
       mhbuild - translate MIME	composition draft

SYNOPSIS
       mhbuild file [-auto | -noauto] [-list | -nolist]	[-realsize | -noreal-
	    size] [-headers | -noheaders] [-directives | -nodirectives]
	    [-rfc934mode | -norfc934mode] [-contentid |	-nocontentid] [-ver-
	    bose | -noverbose] [-disposition | -nodisposition] [-check |
	    -nocheck] [-headerencoding encoding-algorithm  | -autoheaderencod-
	    ing] [-maxunencoded	line-length] [-dist] [-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	to RFC
       2049.  This includes the	encoding of message headers  as	 specified  by
       RFC 2047, and the encoding of MIME parameters as	specified 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	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 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 ber 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.

   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 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 \
		/home/foobar/junk/picture.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:

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

       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/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 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	 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] \
		{attachment; 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	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 mimimum "external-type" directive for the url access-type would be as
       follows:

	  #@application/octet-stream []	access-type=url; \
	    url="http://download.savannah.gnu.org/releases/nmh/nmh-1.5.tar.gz"

       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.

	    #begin
	    This will be a multipart with only one part.
	    #end

       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<rho>q  (for	 quoted-print-
       able),  and "b64" (for base64 encoding).	 It should be noted that unde-
       sired results may occur if 8bit or quoted-printable is selected for bi-
       nary  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.,

	    #<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 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
       "us-ascii".

       By  default  text  content with the high	bit set	is encoded with	a 8bit
       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	based-64 encoding and quoted for quoted-print-
       able encoding.  The -autoheaderencoding switch will instruct mhbuild to
       automatically pick the algorithm	that  results  in  a  shorter  encoded
       string.

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

   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.

       Normally	it is an error to invoke mhbuild on file that 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 for	that machine.

       Finally,	mhbuild	will attempt to	consult

	    /usr/local/etc/nmh/mhn.defaults

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

			       | "#@" type "/" subtype
				     0*(";" attribute "=" value)
				     [ "(" comment ")" ]
				     [ "<" id ">" ]
				     [ "[" description "]" ]
				     [ "{" disposition "}" ]
			   [ "*8bit" | "*qp" | "*b64" ]
				     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 "}" ]
			   [ "*8bit" | "*qp" | "*b64" ]
				     EOL
				     1*line
				 [ "#" EOL ]

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

FILES
       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 profile
       $MHBUILD				    Additional profile entries
       /usr/local/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),

       The Content-MD5 Header Field (RFC 1864),

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

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

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

DEFAULTS
       `-headers'
       `-realsize'
       `-norfc934mode'
       `-contentid'
       `-nocheck'
       `-noverbose'
       `-nodisposition'
       `-autoheaderencoding'
       `-maxunencoded 78'

nmh-1.6				March 13, 2014			    MHBUILD(1)

NAME | SYNOPSIS | DESCRIPTION | FILES | PROFILE COMPONENTS | SEE ALSO | DEFAULTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mhbuild&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help