X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/b36e2ab7892cdf30a8b33d02e00af70398013b5d..07916b2ff:/man/mhbuild.man?ds=sidebyside diff --git a/man/mhbuild.man b/man/mhbuild.man index 1d053d6d..88e5dbde 100644 --- a/man/mhbuild.man +++ b/man/mhbuild.man @@ -1,320 +1,652 @@ -.\" +.TH MHBUILD %manext1% 2016-10-15 "%nmhversion%" +. .\" %nmhwarning% -.\" $Id$ -.\" -.\" include the -mh macro file -.so %etcdir%/tmac.h -.\" -.TH MHBUILD %manext1% "%nmhdate%" MH.6.8 [%nmhversion%] +. .SH NAME -mhbuild \- translate MIME composition draft +mhbuild \- translate MIME composition drafts for nmh messages .SH SYNOPSIS -.in +.5i -.ti -.5i -mhbuild file -.br -\%[\-list] \%[-nolist] -\%[\-realsize] \%[\-norealsize] -.br -\%[\-headers] \%[\-noheaders] -\%[\-ebcdicsafe] \%[\-noebcdicsafe] -.br -\%[\-rfc934mode] \%[\-norfc934mode] -\%[\-verbose] \%[\-noverbose] -.br -\%[\-check] \%[\-nocheck] -\%[\-version] -\%[\-help] -.in -.5i +.na +.HP 5 +.B mhbuild +.RB [ \-help ] +.RB [ \-version ] +.I file +.RB [ \-auto " | " \-noauto ] +.RB [ \-list " | " \-nolist ] +.RB [ \-realsize " | " \-norealsize ] +.RB [ \-headers " | " \-noheaders ] +.RB [ \-directives " | " \-nodirectives ] +.RB [ \-rfc934mode " | " \-norfc934mode ] +.RB [ \-contentid " | " \-nocontentid ] +.RB [ \-verbose " | " \-noverbose ] +.RB [ \-disposition " | " \-nodisposition ] +.RB [ \-check " | " \-nocheck ] +.RB [ \-headerencoding +.IR encoding-algorithm +.RB " | " \-autoheaderencoding ] +.RB [ \-maxunencoded +.IR line-length ] +.RB [ \-dist ] +.ad .SH DESCRIPTION -The \fImhbuild\fR command will translate a MIME composition draft into -a valid MIME message. - -\fImhbuild\fR creates multi-media messages as specified in RFC\-2045 -thru RFC\-2049. Currently \fImhbuild\fR only supports encodings in -message bodies, and does not support the encoding of message headers as -specified in RFC\-2047. - -If you specify the name of the composition file as \*(lq-\*(rq, -then \fImhbuild\fR will accept the composition draft on the standard -input. If the translation of this input is successful, \fImhbuild\fR -will output the new MIME message to the standard output. This argument -must be the last argument on the command line. - -Otherwise if the file argument to \fImhbuild\fR is the name of a valid -composition file, and the translation is successful, \fImhbuild\fR 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 \fImhbuild\fR input file. - -.Uh "Listing the Contents" -The `\-list' switch tells \fImhbuild\fR 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 displayed above the listing. The -`\-realsize' switch tells \fImhbuild\fR 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 `\-verbose' switch +The +.B mhbuild +command will translate a MIME composition draft into a valid MIME message. +.PP +.B 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 specified in RFC 2231. +.PP +If you specify the name of the composition file as \*(lq-\*(rq, then +.B mhbuild +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. +.PP +Otherwise, if the file argument to +.B mhbuild +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 +.B mhbuild +input file. +.SS "Listing the Contents" +The +.B \-list +switch tells +.B mhbuild +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. +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. +If the +.B \-verbose +switch is present, then the listing will show any \*(lqextra\*(rq information -that is present in the message, such as comments in the Content-Type header. - -.Uh "Translating the Composition File" -\fImhbuild\fR is essentially a filter to aid in the composition of MIME -messages. \fImhbuild\fR will convert an -\fImhbuild\fR \*(lqcomposition file\*(rq -into a valid MIME message. A \fImhbuild\fR \*(lqcomposition file\*(rq -is just a file containing plain text that is interspersed -with various \fImhbuild\fR directives. When this file is processed -by \fImhbuild\fR, the various directives will be expanded to the -appropriate content, and will be encoded according to the MIME standards. +that is present in the message, such as comments in the +\*(lqContent-Type\*(rq header. +.PP +If the +.B \-disposition +switch is present, then the listing will show any relevant information from +the \*(lqContent-Disposition\*(rq header. +.SS "Simplified Attachment Interface" +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 +per \*(lqAttach\*(rq header, but multiple \*(lqAttach\*(rq headers are +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 +.IR send (1) +for more details. +.PP +By default, the Content-Disposition will be \*(lqattachment\*(rq. +.B mhbuild +looks for user profile and +.I mhn.defaults +entries of the form +.PP +.RS 5 +.BI mhbuild-disposition- type / subtype +.RE +or +.RS 5 +.BI mhbuild-disposition- type +.RE +.PP +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: +.RS 5 +.TP 15 +.PD 0 +TYPE +content type/subtype +.TP +CONVERTER +external program, and any fixed arguments, to convert content, such as +from a request to a reply +.TP +ARGSTRING +arguments to pass from +.B repl +to +.I CONVERTER +.TP +FILE +full path of message being replied to +.PD +.RE +The convert support is based on pseudoheaders of the form +.PP +.RS 5 +.nf +.BI Nmh-mhbuild-file- TYPE : \0FILE +.BI Nmh-mhbuild-args- TYPE : \0ARGSTRING +.fi +.RE +.PP +in the draft. +For each such pseudoheader, mhbuild looks in the profile and +.I mhn.defaults +for the corresponding +.I TYPE +entry to find the converter that supports it: +.PP +.RS 5 +.BI mhbuild-convert- TYPE : \0CONVERTER +.RE +.PP +It's a fatal error if no such entry is found for +.IR TYPE . +An empty entry, e.g., +.PP +.RS 5 +.B mhbuild-convert-text/html: +.RE +.PP +excludes parts of that +.I TYPE +from the draft. +.PP +The +.I mhn.defaults +file contains default +.B mhbuild-convert-text/html +and +.BR mhbuild-convert-text/plain +entries. Profile entries can be used to override corresponding +.I 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. +.PP +For each +.I TYPE +part in +.IR FILE , +.B mhbuild +runs +.I CONVERTER ARGSTRING +on the content of the part. +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. +.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 +content parts of either of those types by putting corresponding empty +entries in their profile. +.PP +Only the highest precedence alternative with a supported +.I TYPE +of a multipart/alternative part is used. +.PP +mhn.defaults.sh selects the text/html-to-text/plain converter at +install time. It includes +.B iconv +and +.BR par , +or +.BR fmt , +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 +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. +.PP +The convert interface doesn't support different +.IR ARGSTRING s +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 +the convert support), with +.B mhbuild +directives as described below, e.g., +.PP +.RS 5 +#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 +.B mhbuild +directives is to insert the directives before +.B mhbuild +is run, which is typically done by entering +.I mime +at the \*(lqWhat now?\*(rq prompt, or with an +.B \-editor mhbuild +switch. +.PP +These (optional) setup steps can make the convert support +easier to use: +.TP 5 +1) +If the +.B par +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 +.IR par (1). +.TP 5 +2) +Add this line to your profile: +.IP "" 10 +mhbuild-next: $EDITOR +.IP "" 5 +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. +.TP 5 +3) +If using +.BR repl , +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. +.SS "Translating the Composition File" +.B mhbuild +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. +An +.B mhbuild +\*(lqcomposition file\*(rq is just a file containing plain text that is +interspersed with various +.B mhbuild +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 resulting MIME message can then be sent by electronic mail. - -The formal syntax for a \fImhbuild\fR composition file is defined at the -end of this document, but the ideas behind this format are not complex. +.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 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., -.sp +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., +.PP +.RS 5 .nf -.in +.5i #image/png \\ /home/foobar/junk/picture.png -.in -.5i .fi -.sp -There are four kinds of directives: \*(lqtype\*(rq directives, which +.RE +.PP +There are five kinds of directives: \*(lqtype\*(rq directives, which name the type and subtype of the content; \*(lqexternal-type\*(rq directives, which also name the type and subtype of the content; the \*(lqmessage\*(rq directive (#forw), which is used to forward one or -more messages; and, the \*(lqbegin\*(rq directive (#begin), which is -used to create a multipart content. - +more messages; the \*(lqbegin\*(rq directive (#begin), which is +used to create a multipart content; and the \*(lqon/off/pop\*(rq +directives (#on, #off, #pop) which control whether any other +directives are honored at all. +.PP +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: +.PP +.RS 5 +.nf +#off +#include +printf("Hello, World!"); +#pop +.fi +.RE +.PP +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 (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. +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. For example, -.sp +.PP +.RS 5 .nf -.in +.5i #audio/basic |raw2audio -F < /usr/lib/sound/giggle.au -.in -.5i .fi -.sp -If a filename is not given, \fImhbuild\fR will look for information in the +.RE +.PP +If a filename is not given, +.B mhbuild +will look for information in the user's profile to determine how the different contents should be composed. This is accomplished by consulting a composition string, and executing -it under \fB/bin/sh\fR, with the standard output set to the content. -If the `\-verbose' switch is given, \fImhbuild\fR will echo any commands -that are used to create contents in this way. -.ne 13 +it under +.BR /bin/sh , +with the standard output set to the content. If the +.B \-verbose +switch is given, +.B mhbuild +will echo any commands that are used to create contents in this way. +.PP The composition string may contain the following escapes: -.sp -.nf -.in +.5i -.ta \w'%P 'u -%a Insert parameters from directive -%f Insert filename containing content -%F %f, and stdout is not re-directed -%s Insert content subtype -%% Insert character % -.re -.in -.5i -.fi -.sp - +.PP +.RS 5 +.PD 0 +.IP %a +Insert parameters from directive +.IP %f +Insert filename containing content +.IP %F +%f, and stdout is not re-directed +.IP %s +Insert content subtype +.IP %% +Insert character % +.PD +.RE +.PP First, -\fImhbuild\fR will look for an entry of the form: -.sp -.in +.5i -mhbuild-compose-/ -.in -.5i -.sp -to determine the command to use to compose the content. If this isn't -found, \fImhbuild\fR will look for an entry of the form: -.sp -.in +.5i -mhbuild-compose- -.in -.5i -.sp -to determine the composition command. - -If this isn't found, \fImhbuild\fR +.B mhbuild +will look for an entry of the form: +.PP +.RS 5 +.BI mhbuild-compose- type / subtype +.RE +.PP +to determine the command to use to compose the content. +If this isn't found, +.B mhbuild +will look for an entry of the form: +.PP +.RS 5 +.BI mhbuild-compose- type +.RE +.PP +to determine the composition command. If this isn't found, +.B mhbuild will complain. - +.PP An example entry might be: -.sp -.in +.5i +.PP +.RS 5 mhbuild-compose-audio/basic: record | raw2audio -F -.in -.5i -.sp +.RE +.PP 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 -\fB$MHBUILD\fR 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. For example, -.sp +(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, +.PP +.RS 5 .nf -.in +.5i #@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" -.in -.5i .fi -.sp +.RE +.PP 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 \*(lq[]\*(rq. -.ne 19 +A disposition string, to appear in a +\*(lqContent-Disposition\*(rq header, may appear in the optional +\*(lq{}\*(rq. +.PP These parameters are of the form: -.sp +.PP +.RS 5 .nf -.in +.5i .ta \w'access-type= 'u -access-type= usually \fIanon-ftp\fR or \fImail-server\fR +access-type= usually \*(lqanon-ftp\*(rq, \*(lqmail-server\*(rq, or \*(lqurl\*(rq name= filename permission= read-only or read-write site= hostname directory= directoryname (optional) -mode= usually \fIascii\fR or \fIimage\fR (optional) +mode= usually \*(lqascii\*(rq or \*(lqimage\*(rq (optional) size= number of octets server= mailbox subject= subject to send body= command to send for retrieval -.re -.in -.5i +url= URL of content .fi -.sp - +.RE +.PP +A minimum \*(lqexternal\-type\*(rq directive for the +.B url +.I access-type +would be as follows: +.PP +.RS 3 +.nf +#@application/octet-stream [] access-type=url; \\ + url="http://download.savannah.gnu.org/releases/nmh/nmh-1.5.tar.gz" +.fi +.RE +.PP +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 -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 \fIforw\fR\0(1) command, except that the former uses -the MIME rules for encapsulation rather than those specified in RFC\-934. +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 +.B forw +command, except that the former uses the MIME rules for encapsulation +rather than those specified in RFC 934. For example, -.sp +.PP +.RS 5 .nf -.in +.5i #forw +inbox 42 43 99 -.in -.5i .fi -.sp +.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, -then \fImhbuild\fR will add a content of type \*(lqmultipart/digest\*(rq +of type \*(lqmessage/rfc822\*(rq. +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. - +.PP If you are using this directive to include more than one message, you -may use the `\-rfc934mode' switch. This switch will indicate that -\fImhbuild\fR 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 +may use the +.B \-rfc934mode +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. +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. - +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. +.PP The \*(lqbegin\*(rq directive is used to create a multipart content. When using the \*(lqbegin\*(rq directive, you must specify at least one content between the begin and end pairs. -.sp +.PP +.RS 5 .nf -.in +.5i #begin This will be a multipart with only one part. #end -.in -.5i .fi -.sp -If you use multiple directives in a composition draft, \fImhbuild\fR 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. - +.RE +.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. +.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. -.sp +character. +This description will be copied into the \*(lqContent-Description\*(rq header +when the directive is processed. +.PP +.RS 5 .nf -.in +.5i #forw [important mail from Bob] +bob 1 2 3 4 5 -.in -.5i .fi -.sp -By default, \fImhbuild\fR will generate a unique \*(lqContent-ID:\*(rq for -each directive; however, the user may override this by defining the ID -using the \*(lq<\*(rq and \*(lq>\*(rq characters. - +.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. +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: +.PP +.RS 5 +.nf +#text/plain; charset=iso-8859-1 <>{attachment} /tmp/summary.txt +.fi +.RE +.PP +creates these message part headers: +.PP +.RS 5 +.nf +Content-Type: text/plain; charset="iso-8859-1" +Content-Disposition: attachment; filename="summary.txt" +.fi +.RE +.PP +By default, +.B mhbuild +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 +.B \-nocontentid +switch suppresses creation of all \*(lqContent-ID:\*(rq headers, +even in the top level of the message. +.PP +Normally +.B mhbuild +will choose an appropriate Content\-Transfer\-Encoding based on the content +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. +.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, -.ne 6 +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, e.g., -.sp -.in +.5i +.PP +.RS 5 ##when sent, this line will start with only one # -.in -.5i -.sp +.RE +.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, -.ne 10 -e.g., -.sp +\*(lq#\*(rq character, e.g., +.PP +.RS 5 .nf -.in +.5i this is the first content # and this is the second -.in -.5i .fi -.sp -Finally, -if the plaintext starts with a line of the form: -.sp -.in +.5i +.RE +.PP +Finally, if the plaintext starts with a line of the form: +.PP +.RS 5 Content-Description: text -.in -.5i -.sp +.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. - -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, -.ne 11 -e.g., -.sp +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., +.PP +.RS 5 .nf -.in +.5i #" ] - [ "[" description "]" ] - [ filename ] - EOL - - | "#@" type "/" subtype - 0*(";" attribute "=" value) - [ "(" comment ")" ] - [ "<" id ">" ] - [ "[" description "]" ] - external-parameters - EOL - - | "#forw" - [ "<" id ">" ] - [ "[" description "]" ] - [ "+"folder ] [ 0*msg ] - EOL - - | "#begin" - [ "<" id ">" ] - [ "[" description "]" ] - [ "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 "]" ] - EOL - 1*line - [ "#" EOL ] - - line ::= "##" text EOL - -- interpreted as "#"text EOL - | text EOL -.in -.5i +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 +.fi +.RE +.SH FILES +.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 +.I Mail +directory as specified in their profile. +If not found there, the directory +.RI \*(lq %nmhetcdir% \*(rq +is checked. +.PP +.PD 0 +.TP 20 +$HOME/.mh_profile +The user's profile. +.TP +$MHBUILD +Additional profile entries. +.TP +%nmhetcdir%/mhn.defaults +System default MIME profile entries. +.PD +.SH "PROFILE COMPONENTS" +.PD 0 +.TP 20 +Path: +To determine the user's nmh directory. +.TP +Current\-Folder: +To find the default current folder. +.TP +.RI mhbuild-compose- type* : +Template for composing contents. +.PD +.SH "SEE ALSO" +.IR mhlist (1), +.IR mhshow (1), +.IR mhstore (1) +.PP +.I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies" +(RFC 2045) +.PP +.I "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types" +(RFC 2046) +.PP +.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 +.I "Proposed Standard for Message Encapsulation" +(RFC 934) +.PP +.I "The Content-MD5 Header Field" +(RFC 1864) +.PP +.I "Definition of the URL MIME External-Body Access-Type" +(RFC 2017) +.PP +.I "Overview and Framework for Internationalized Email" +(RFC 6530) +.PP +.I "SMTP Extension for Internationalized Email" +(RFC 6531) +.SH DEFAULTS +.nf +\-autoheaderencoding +\-contentid +\-headers +\-maxunencoded 78 +\-nocheck +\-nodisposition +\-norfc934mode +\-noverbose +\-realsize .fi -.sp -.Fi -^$HOME/\&.mh\(ruprofile~^The user profile -^$MHBUILD~^Additional profile entries -^%etcdir%/mhn.defaults~^System default MIME profile entries -.Pr -^Path:~^To determine the user's nmh directory -.Ps -^Current\-Folder:~^To find the default current folder -.Ps -^mhbuild-compose-*~^Template for composing contents -.Sa -mhlist(1), mhshow(1), mhstore(1) -.br -RFC\-934: -.br - \fIProposed Standard for Message Encapsulation\fR, -.br -RFC\-2045: -.br - \fIMultipurpose Internet Mail Extensions (MIME) Part One: -.br - Format of Internet Message Bodies\fR, -.br -RFC\-2046: -.br - \fIMultipurpose Internet Mail Extensions (MIME) Part Two: -.br - Media Types\fR, -.br -RFC\-2047: -.br - \fIMultipurpose Internet Mail Extensions (MIME) Part Three: -.br - Message Header Extensions for Non-ASCII Text\fR, -.br -RFC\-2048: -.br - \fIMultipurpose Internet Mail Extensions (MIME) Part Four: -.br - Registration Procedures\fR, -.br -RFC\-2049: -.br - \fIMultipurpose Internet Mail Extensions (MIME) Part Five: -.br - Conformance Criteria and Examples\fR. -.De -`\-headers' -.Ds -`\-realsize' -.Ds -`\-norfc934mode' -.Ds -`\-nocheck' -.Ds -`\-noebcdicsafe' -.Ds -`\-noverbose' -.Co -If a folder is given, it will become the current folder. The last -message selected will become the current message. -.En