X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=man%2Fmhbuild.man1;h=7a32a41fc54a60e2efba40a690ee3b847417fea1;hp=32df65184381d3828b13a5ab8f8b7b1277180bf4;hb=18591f8e001ecedbee48a51c1d1f08ebaa1c15c8;hpb=a6e6452e21cb56d1ccd593341e0bdd865e3bcbe5 diff --git a/man/mhbuild.man1 b/man/mhbuild.man1 index 32df651..7a32a41 100644 --- a/man/mhbuild.man1 +++ b/man/mhbuild.man1 @@ -9,9 +9,8 @@ mhbuild \- translate MIME composition draft .HP 5 .B mhbuild .I file -.RB [ \-contentid " | " \-nocontentid ] .RB [ \-verbose " | " \-noverbose ] -.RB [ \-version ] +.RB [ \-Version ] .RB [ \-help ] .ad .SH DESCRIPTION @@ -25,10 +24,10 @@ creates multi-media messages as specified in RFC\-2045 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 @@ -42,10 +41,11 @@ Otherwise if the file argument to 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. @@ -56,10 +56,10 @@ messages. .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 @@ -75,9 +75,9 @@ The formal syntax for a 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 @@ -88,23 +88,23 @@ than one line, e.g., .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 @@ -159,7 +159,7 @@ will complain. 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 @@ -169,7 +169,7 @@ contents should probably be put in the file specified by the 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 @@ -187,15 +187,15 @@ For example, .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 @@ -210,13 +210,13 @@ If you use multiple directives in a composition draft, .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 @@ -225,11 +225,11 @@ character. This description will be copied into the .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 @@ -249,18 +249,15 @@ Content-Disposition: attachment; filename="summary.txt" .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 -characters. The -.B \-nocontentid -switch suppresses creation of all \*(lqContent-ID:\*(rq headers, -even in the top level of the message. +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 @@ -269,7 +266,7 @@ e.g., .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 @@ -290,7 +287,7 @@ You MUST follow this line with a blank line before starting 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 @@ -305,12 +302,12 @@ and this content will be tagged as application/x-patch .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 #