.B mhbuild
.I file
.RB [ \-verbose " | " \-noverbose ]
-.RB [ \-version ]
+.RB [ \-Version ]
.RB [ \-help ]
.ad
.SH DESCRIPTION
thru RFC\-2049. Currently
.B mhbuild
only supports encodings in
-message bodies, and does not support the encoding of message headers as
+message bodies, and does support the encoding of message headers as
specified in RFC\-2047.
.PP
-If you specify the name of the composition file as \*(lq-\*(rq,
+If you specify the name of the composition file as `-',
then
.B mhbuild
will accept the composition draft on the standard
is the name of a valid
composition file, and the translation is successful,
.B mhbuild
-will replace the original file with the new MIME message. It will rename
-the original file to start with the \*(lq,\*(rq character and end with the
-string \*(lq.orig\*(rq, e.g., if you are editing the file \*(lqdraft\*(rq,
-it will be renamed to \*(lq,draft.orig\*(rq. This allows you to easily
+will replace the original file with the new MIME message.
+It will preserve the original file under the same name with `.orig'
+appended.
+E.g., if you are editing the file `draft', its original contents
+it will be preserved as `draft.orig'. This allows you to easily
recover the
.B mhbuild
input file.
.B mhbuild
will convert an
.B mhbuild
-\*(lqcomposition file\*(rq
+`composition file'
into a valid MIME message. A
.B mhbuild
-\*(lqcomposition file\*(rq
+`composition file'
is just a file containing plain text that is interspersed
with various
.B 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 \*(lq#\*(rq as the first character
+either a directive, indicated with a `#' as the first character
of a line; or, plaintext (one or more lines of text). The continuation
-character, \*(lq\\\*(lq, may be used to enter a single directive on more
+character, `\\`, may be used to enter a single directive on more
than one line, e.g.,
.PP
.RS 5
.RE
.PP
There are three kinds of directives:
-\*(lqtype\*(rq,
-\*(lqmessage\*(rq (#forw),
-and \*(lqbegin\*(rq (#begin).
+`type',
+`message' (#forw),
+and `begin' (#begin).
.PP
-.B "(1) The \*(lqtype\*(rq directive
+.B "(1) 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 \*(lqnative\*(rq (decoded) format. If this filename starts with the
-\*(lq|\*(rq character, then it represents a command to execute whose
+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,
.PP
.RS 5
.nf
-#audio/basic |raw2audio -F < /usr/lib/sound/giggle.au
+#audio/basic |raw2audio \-F < /usr/lib/sound/giggle.au
.fi
.RE
.PP
An example entry might be:
.PP
.RS 5
-mhbuild-compose-audio/basic: record | raw2audio -F
+mhbuild-compose-audio/basic: record | raw2audio \-F
.RE
.PP
Because commands like these will vary, depending on the display
environment variable, instead of directly in your
user profile.
.PP
-.B "(2) The \*(lqmessage\*(rq directive (#forw)
+.B "(2) 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
.RE
.PP
If you include a single message, it will be included directly as a content
-of type \*(lqmessage/rfc822\*(rq. If you include more than one message,
+of type `message/rfc822'. If you include more than one message,
then
.B mhbuild
-will add a content of type \*(lqmultipart/digest\*(rq
+will add a content of type `multipart/digest'
and include each message as a subpart of this content.
.PP
-.B "(3) The \*(lqbegin\*(rq directive
+.B "(3) The `begin' directive
is used to create a multipart content.
-When using the \*(lqbegin\*(rq directive, you must specify at least one
+When using the `begin' directive, you must specify at least one
content between the begin and end pairs.
.PP
.RS 5
.B mhbuild
will
automatically encapsulate them inside a multipart content. Therefore the
-\*(lqbegin\*(rq directive is only necessary if you wish to use nested
+`begin' directive is only necessary if you wish to use nested
multiparts, or create a multipart message containing only one part.
.PP
For all of these directives, the user may include a brief description
-of the content between the \*(lq[\*(rq character and the \*(lq]\*(rq
+of the content between the `[' character and the `]'
character. This description will be copied into the
-\*(lqContent-Description\*(rq header when the directive is processed.
+`Content-Description' header when the directive is processed.
.PP
.RS 5
.nf
.RE
.PP
Similarly, a disposition string may optionally be provided between
-\*(lq{\*(rq and \*(lq}\*(rq characters; it will be copied into the
-\*(lqContent-Disposition\*(rq header when the directive is processed.
+`{' 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 \*(lqContent-Disposition\*(rq header. For example, the
+added to the `Content-Disposition' header. For example, the
following directive:
.PP
.RS 5
.PP
By default,
.B mhbuild
-will generate a unique \*(lqContent-ID:\*(rq for each directive,
+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 \*(lq<\*(rq and \*(lq>\*(rq
+this by defining the ID using the `<' and `>'
characters.
.PP
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 \*(lq#\*(rq at the beginning of a line, simply double it,
+must contain a `#' at the beginning of a line, simply double it,
e.g.,
.PP
.RS 5
.PP
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
-\*(lq#\*(rq character, e.g.,
+`#' character, e.g.,
.PP
.RS 5
.nf
your text.
.PP
By default, plaintext is captured as a text/plain content. You can
-override this by starting the plaintext with \*(lq#<\*(rq followed by
+override this by starting the plaintext with `#<' followed by
a content-type specification. For example, e.g.,
.PP
.RS 5
.fi
.RE
.PP
-Note that if you use the \*(lq#<\*(rq plaintext-form, then the
+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.
.PP
When composing a text content, you may indicate the relevant character
-set by adding the \*(lqcharset\*(rq parameter to the directive.
+set by adding the `charset' parameter to the directive.
.PP
.RS 5
#<text/plain; charset=iso-8859-5
.B 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 \*(lqx-unknown\*(rq.
+set, then the character set will be labeled as `x-unknown'.
.PP
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
-\*(lqus-ascii\*(rq.
+`us-ascii'.
.PP
Putting this all together,
here is an example of a more complicated message draft. The
#
This third part will be text/plain
#audio/basic [silly giggle] \\
- |raw2audio -F < /usr/lib/sounds/giggle.au
+ |raw2audio \-F < /usr/lib/sounds/giggle.au
#image/gif [photo of foobar] \\
/home/foobar/lib/picture.gif
.fi
.SS "Syntax of Composition Files"
The following is the formal syntax of a
.B mhbuild
-\*(lqcomposition file\*(rq.
+`composition file'.
.PP
.RS 5
.nf
Then send it.
There used to be a
.B \-nocontentid
-switch to prevent Content-ID headers to be inserted, but as it was considerd
+switch to prevent Content-ID headers to be inserted, but as it was considered
wrong to complicate all other MUAs instead of forcing the developers and users
of broken MUAs to fix or change their software, it was removed.
projects / mmh / blobdiff