X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/aaf014c77a4fb19bdc33370f5b6af5b8497decf8..63621a81d16ab743de6b57d47578a9a2c670ad22:/man/mhbuild.man diff --git a/man/mhbuild.man b/man/mhbuild.man index 18e82abf..5fdf7c27 100644 --- a/man/mhbuild.man +++ b/man/mhbuild.man @@ -1,13 +1,15 @@ -.TH MHBUILD %manext1% "September 23, 2016" "%nmhversion%" -.\" +.TH MHBUILD %manext1% 2016-10-15 "%nmhversion%" +. .\" %nmhwarning% -.\" +. .SH NAME -mhbuild \- translate MIME composition draft +mhbuild \- translate MIME composition drafts for nmh messages .SH SYNOPSIS .na .HP 5 .B mhbuild +.RB [ \-help ] +.RB [ \-version ] .I file .RB [ \-auto " | " \-noauto ] .RB [ \-list " | " \-nolist ] @@ -20,49 +22,39 @@ mhbuild \- translate MIME composition draft .RB [ \-disposition " | " \-nodisposition ] .RB [ \-check " | " \-nocheck ] .RB [ \-headerencoding -.IR encoding\-algorithm +.I encoding-algorithm .RB " | " \-autoheaderencoding ] .RB [ \-maxunencoded -.IR line\-length ] +.IR line-length ] .RB [ \-dist ] -.RB [ \-version ] -.RB [ \-help ] .ad .SH DESCRIPTION The .B mhbuild -command will translate a MIME composition draft into -a valid MIME message. +command will translate a MIME composition draft into a valid MIME message. .PP .B mhbuild -creates multi-media messages as specified in RFC 2045 -through 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. +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 specified in RFC 2231. .PP -If you specify the name of the composition file as \*(lq-\*(rq, -then +If you specify the name of the composition file as \*(lq-\*(rq, then .B mhbuild -will accept the composition draft on the standard -input. +will accept the composition draft on the standard input. If the translation of this input is successful, .B mhbuild will output the new MIME message to the standard output. -This argument -must be the last argument on the command line. +This argument must be the last argument on the command line. .PP -Otherwise if the file argument to +Otherwise, if the file argument to .B mhbuild -is the name of a valid -composition file, and the translation is successful, +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 -recover the +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 recover the .B mhbuild input file. .SS "Listing the Contents" @@ -74,16 +66,13 @@ to list the table of contents associated with the MIME message that is created. .PP The .B \-headers -switch indicates -that a one-line banner should be displayed above the listing. +switch indicates that a one-line banner should be displayed above the listing. The .B \-realsize switch tells .B mhbuild -to evaluate the \*(lqnative\*(rq -(decoded) format of each content prior to listing. -This provides an -accurate count at the expense of a small delay. +to evaluate the \*(lqnative\*(rq (decoded) format of each content prior to listing. +This provides an accurate count at the expense of a small delay. If the .B \-verbose switch @@ -99,18 +88,15 @@ the \*(lqContent-Disposition\*(rq header. For users who wish to simply attach files to text content, .B mhbuild will scan the composition file for \*(lqAttach\*(rq headers. -An -\*(lqAttach\*(rq header contains a filename that will be appended to the -message using normal MIME encapsulation rules. -One filename is allowed +An \*(lqAttach\*(rq header contains a filename that will be appended to the +message using normal MIME encapsulation rules. One filename is allowed per \*(lqAttach\*(rq header, but multiple \*(lqAttach\*(rq headers are -allowed ber composition file. +allowed per composition file. .PP These files will be appended after any other MIME content, including any content specified by .B mhbuild -directives (see below). -See +directives (see below). See .IR send (1) for more details. .PP @@ -128,16 +114,14 @@ or .BI mhbuild-disposition- type .RE .PP -to supply the disposition value. -The only supported values are +to supply the disposition value. The only supported values are \*(lqattachment\*(rq and \*(lqinline\*(rq. .SS "Convert Interface" The convert interface is a powerful mechanism that supports replying to MIME messages. -These placeholders are used in the following -description: +These placeholders are used in the following description: .RS 5 .TP 15 .PD 0 @@ -158,8 +142,6 @@ FILE full path of message being replied to .PD .RE -.PP -.RE The convert support is based on pseudoheaders of the form .PP .RS 5 @@ -170,13 +152,11 @@ The convert support is based on pseudoheaders of the form .RE .PP in the draft. -For each such pseudoheader, mhbuild looks in the -profile and +For each such pseudoheader, mhbuild looks in the profile and .I mhn.defaults -for this corresponding +for the corresponding .I TYPE -entry to find the -converter that supports it: +entry to find the converter that supports it: .PP .RS 5 .BI mhbuild-convert- TYPE : \0CONVERTER @@ -184,8 +164,7 @@ converter that supports it: .PP It's a fatal error if no such entry is found for .IR TYPE . -An empty -entry, e.g., +An empty entry, e.g., .PP .RS 5 .B mhbuild-convert-text/html: @@ -194,17 +173,18 @@ entry, e.g., excludes parts of that .I TYPE from the draft. +.PP The .I mhn.defaults -file -contains default +file contains default .B mhbuild-convert-text/html and -.BR mhbuild-convert-text/plain -entries. -Profile entries can be used to override corresponding +.B mhbuild-convert-text/plain +entries. Profile entries can be used to override corresponding .I mhn.defaults -entries, as usual. +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. .PP For each .I TYPE @@ -214,22 +194,19 @@ part in runs .I CONVERTER ARGSTRING on the content of the part. -.PP Each part in .I FILE that has no corresponding TYPE entry in the profile or .I mhn.defaults is -excluded from the draft; the user can include them using mhbuild -directives as usual. +excluded from the draft; the user can include them using mhbuild directives. .PP .B repl inserts .B Nmh-mhbuild-text/html: and .B Nmh-mhbuild-text/plain: -pseudoheaders in every draft. -The user can prevent insertion of +pseudoheaders in every draft. The user can prevent insertion of content parts of either of those types by putting corresponding empty entries in their profile. .PP @@ -238,8 +215,7 @@ Only the highest precedence alternative with a supported of a multipart/alternative part is used. .PP mhn.defaults.sh selects the text/html-to-text/plain converter at -install time. -It includes +install time. It includes .B iconv and .BR par , @@ -248,14 +224,12 @@ or in the pipeline only if they are found. .PP Some content types require the addition of parameters to the -Content-Type header, such as -\*(lqmethod=REPLY\*(rq +Content-Type header, such as \*(lqmethod=REPLY\*(rq for text/calendar. .B 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 corresponding part in the reply draft. +If one is found, it is used for the corresponding part in the reply draft. .PP The convert interface doesn't support different .IR ARGSTRING s @@ -263,8 +237,7 @@ or different converters for different parts of the same .IR TYPE . That would require associating parts by part number with the .IR ARGSTRING s -or converters. -Instead, that can be done (currently, without using +or converters. Instead, that can be done (currently, without using the convert support), with .B mhbuild directives as described below, e.g., @@ -273,9 +246,7 @@ 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 .RE .PP -The only way to mix -convert -pseudoheaders and +The only way to mix convert pseudoheaders and .B mhbuild directives is to insert the directives before .B mhbuild @@ -294,25 +265,21 @@ If the program is installed on your system, it will be set by default (in .IR mhn.defaults ) -to filter the converter output. -It helps to -set the -PARINIT -environment variable, as described in its man page. +to filter the converter output. It helps to set the PARINIT +environment variable, as described in +.IR par (1). .TP 5 2) Add this line to your profile: .IP "" 10 mhbuild-next: $EDITOR .IP "" 5 -assuming that your EDTIOR environment variable is set; if not, replace -EDITOR with the name of your editor. -Without that profile entry, a +assuming that your EDITOR environment variable is set; if not, replace +EDITOR with the name of your editor. Without that profile entry, a response of \*(lqe[dit]\*(rq at the What now? prompt will require specification of your editor if an .B \-editor mhbuild switch is used. -.RE .TP 5 3) If using @@ -320,44 +287,34 @@ If using source the Bourne-shell compatible functions in .IR %docdir%/contrib/replaliases . .br -That script also sets the -PARINIT -environment variable if it was not set. -.RE +That script also sets the PARINIT environment variable if it was not set. .SS "Translating the Composition File" .B mhbuild -is essentially a filter to aid in the composition of MIME -messages. +is essentially a filter to aid in the composition of MIME messages. .B mhbuild will convert an .B mhbuild -\*(lqcomposition file\*(rq -into a valid MIME message. -A +\*(lqcomposition file\*(rq into a valid MIME message. +An .B mhbuild -\*(lqcomposition file\*(rq -is just a file containing plain text that is interspersed -with various +\*(lqcomposition file\*(rq is just a file containing plain text that is +interspersed with various .B mhbuild -directives. -When this file is processed -by +directives. When this file is processed by .BR mhbuild , -the various directives will be expanded to the -appropriate content, and will be encoded according to the MIME standards. +the various directives 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. .PP The formal syntax for a .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 +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 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 -than one line, e.g., +The continuation character, \*(lq\\\*(lq, may be used to enter a single +directive on more than one line, e.g., .PP .RS 5 .nf @@ -379,13 +336,11 @@ The .B \-directives switch allows control over whether mhbuild will honor any of the \*(lq#\*(rq-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: +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: .PP .RS 5 .nf @@ -399,14 +354,12 @@ printf("Hello, World!"); Currently the stack depth for the #on/off/pop directives is 32. .PP The \*(lqtype\*(rq directive is used to directly specify the type and -subtype of a content. -You may only specify discrete types in this manner +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 -output is captured accordingly. +If this filename starts with the \*(lq|\*(rq character, then it represents +a command to execute whose output is captured accordingly. For example, .PP .RS 5 @@ -422,8 +375,7 @@ user's profile to determine how the different contents should be composed. This is accomplished by consulting a composition string, and executing it under .BR /bin/sh , -with the standard output set to the content. -If the +with the standard output set to the content. If the .B \-verbose switch is given, .B mhbuild @@ -455,8 +407,7 @@ will look for an entry of the form: .RE .PP to determine the command to use to compose the content. -If this isn't -found, +If this isn't found, .B mhbuild will look for an entry of the form: .PP @@ -464,8 +415,7 @@ will look for an entry of the form: .BI mhbuild-compose- type .RE .PP -to determine the composition command. -If this isn't found, +to determine the composition command. If this isn't found, .B mhbuild will complain. .PP @@ -478,18 +428,15 @@ 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 +MHBUILD environment variable, instead of directly in your user profile. .PP The \*(lqexternal-type\*(rq 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. +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, .PP .RS 5 @@ -534,9 +481,9 @@ url= URL of content .fi .RE .PP -A mimimum \*(lqexternal\-type\*(rq directive for the +A minimum \*(lqexternal\-type\*(rq directive for the .B url -.I access\-type +.I access-type would be as follows: .PP .RS 3 @@ -549,18 +496,14 @@ would be as follows: Any long URLs will be wrapped according to RFC 2231 rules. .PP The \*(lqmessage\*(rq directive (#forw) is used to specify a message or -group of messages to include. -You may optionally specify the name of +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 +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 .B forw -command, except that the former uses -the MIME rules for encapsulation rather than those specified in RFC 934. +command, except that the former uses the MIME rules for encapsulation +rather than those specified in RFC 934. For example, .PP .RS 5 @@ -571,8 +514,7 @@ For example, .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, -then +If you include more than one message, then .B mhbuild will add a content of type \*(lqmultipart/digest\*(rq and include each message as a subpart of this content. @@ -580,18 +522,16 @@ 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 .B \-rfc934mode -switch. -This switch will indicate that +switch. This switch will indicate that .B mhbuild -should attempt to utilize the MIME encapsulation rules -in such a way that the \*(lqmultipart/digest\*(rq that is created -is (mostly) compatible with the encapsulation specified in RFC 934. +should attempt to utilize the MIME encapsulation rules in such a way +that the \*(lqmultipart/digest\*(rq 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\0--\0providing 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 drawback of this approach is that the encapsulations are generated by +placing an extra newline at the end of the body of each message. .PP The \*(lqbegin\*(rq directive is used to create a multipart content. When using the \*(lqbegin\*(rq directive, you must specify at least one @@ -607,17 +547,15 @@ This will be a multipart with only one part. .PP 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 -multiparts, or create a multipart message containing only one part. +will automatically encapsulate them inside a multipart content. +Therefore the \*(lqbegin\*(rq 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 character. -This description will be copied into the -\*(lqContent-Description\*(rq header when the directive is processed. +This description will be copied into the \*(lqContent-Description\*(rq header +when the directive is processed. .PP .RS 5 .nf @@ -631,8 +569,7 @@ Similarly, a disposition string may optionally be provided between 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 -following directive: +For example, the following directive: .PP .RS 5 .nf @@ -654,8 +591,7 @@ By default, will generate a unique \*(lqContent-ID:\*(rq 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 +characters. The .B \-nocontentid switch suppresses creation of all \*(lqContent-ID:\*(rq headers, even in the top level of the message. @@ -667,19 +603,17 @@ and the MIME Content\-Type. However, you can override that in an .B mhbuild directive by specifying \*(lq*\*(rq and the encoding. -Acceptable encoding -values are \*(lq8bit\*(rq, \*(lqqp\*(rq (for quoted\-printable), and -\*(lqb64\*(rq (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. +Acceptable encoding values are \*(lq8bit\*(rq, \*(lqqp\*(rq +(for quoted-printable), and \*(lqb64\*(rq (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. .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, +If the plaintext must contain a \*(lq#\*(rq at the beginning of a line, +simply double it, e.g., .PP .RS 5 @@ -705,14 +639,11 @@ Content-Description: text .RE .PP then this will be used to describe the plaintext content. -You MUST follow this line with a blank line before starting -your text. +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 -a content-type specification. -For example, e.g., +You can override this by starting the plaintext with \*(lq#<\*(rq followed +by a content-type specification. For example, e.g., .PP .RS 5 .nf @@ -737,53 +668,48 @@ set by adding the \*(lqcharset\*(rq parameter to the directive. #" ] [ "[" description "]" ] [ "{" disposition "}" ] - [ "*8bit" | "*qp" | "*b64" ] + [ "*8bit" | "*qp" | "*b64" ] [ filename ] EOL @@ -959,7 +877,7 @@ directive ::= "#" type "/" subtype [ "<" id ">" ] [ "[" description "]" ] [ "{" disposition "}" ] - [ "*8bit" | "*qp" | "*b64" ] + [ "*8bit" | "*qp" | "*b64" ] external-parameters EOL @@ -991,7 +909,7 @@ plaintext ::= [ "Content-Description:" [ "(" comment ")" ] [ "[" description "]" ] [ "{" disposition "}" ] - [ "*8bit" | "*qp" | "*b64" ] + [ "*8bit" | "*qp" | "*b64" ] EOL 1*line [ "#" EOL ] @@ -1005,9 +923,8 @@ line ::= "##" text EOL .B mhbuild looks for additional user profile files and .I mhn.defaults -in multiple -locations: absolute pathnames are accessed directly, tilde expansion -is done on usernames, and files are searched for in the user's +in multiple locations: absolute pathnames are accessed directly, tilde +expansion is done on usernames, and files are searched for in the user's .I Mail directory as specified in their profile. If not found there, the directory @@ -1016,7 +933,7 @@ is checked. .PP .PD 0 .TP 20 -$HOME/\&.mh\(ruprofile +$HOME/.mh_profile The user's profile. .TP $MHBUILD @@ -1051,6 +968,9 @@ Template for composing contents. .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text" (RFC 2047) .PP +.I "Internet Message Format" +(RFC 5322) +.PP .I "MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations" (RFC 2231) .PP