From: David Levine Date: Thu, 24 Mar 2016 00:41:46 +0000 (-0400) Subject: Merge remote-tracking branch 'origin' into xoauth X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/8e0f9bd3daae9d05dec58026d5a5924367e4e874?hp=626b510952d3756e15efda6c2e4d0a2c95f6eed3 Merge remote-tracking branch 'origin' into xoauth merge is necessary, --- diff --git a/docs/README.manpages b/docs/README.manpages index 86cd725c..42bd6a35 100644 --- a/docs/README.manpages +++ b/docs/README.manpages @@ -1,133 +1,106 @@ -NMH MANPAGE STYLE GUIDE + NMH MANPAGE STYLE GUIDE + ======================= -nmh manpages should be in this general form and section order: +Nmh manpages generally follow the traditional Bell Labs formatting +conventions. We do adopt a few conventions from BSD (primarily, +section ordering), and have a few of our own (mostly related to +indentation). -.TH COMP %manext1% "DATE" "%nmhversion%" -.\" -.\" %nmhwarning% -.\" -.SH NAME -comp \- compose a message -.\" -.SH SYNOPSIS -.HP 5 -.na -.B comp -.RI [ +folder ] -.RI [ msgs ] -.RB [ \-form -.IR formfile ] -.RB [ \-use " | " \-nouse ] -.RB [ \-version ] -.RB [ \-help ] -.ad -.SH DESCRIPTION -.B Comp -is used to create a new message to be mailed. It copies something. -.\" -.SH "PROFILE COMPONENTS" -.TP -Path -Location of the user's MH folder directory -.TP -moreproc -The pager command name -.\" -.SH DEFAULTS -.TP -.RI + folder -defaults to the current folder -.\" -.SH CONTEXT -None -.\" -.SH FILES -.TP -filename1 -description of filename1 -.TP -filename2 -description of filename2 -.\" -.SH "SEE ALSO" -.BR dist (1), -.BR forw (1), -.BR repl (1), -.BR send (1), -.BR whatnow (1), -.BR mh-profile (5) -.\" Leave out the BUGS section if there are none worth describing. -.SH BUGS -None ---------------------------------------- -The DATE in the .TH macro should reflect the most recent non-trivial -update to the content of the manpage; formatting changes don't count. -Spell out the date (no abbreviations or shortcuts): +Troff Considerations - January 2, 1904 + Proper sentences end with a period followed by a newline: -not the unparseable + This is a sentence. + It is followed by another, longer, sentence, but + which makes no more sense than the previous one. - 01/02/04 + not -Don't abbreviate the month. + This is a sentence. It is followed by another, + longer, sentence, but which makes no more sense + than the previous one. + This allows troff to set the correct inter-sentence spacing + based on the output device. -In the FILES section, prefer the default .TP indent. The pathnames are -variable and long, so any indentation value that works for you won't -work for someone using a different directory layout. + When quoting, use \*(lq and \*(rq. This ensures correct + formatting on typesetter-like devices. + Don't use UTF-8 characters in the manpage source. We still + build and run on systems that can't handle this. And most + anything you would want to use has an internal troff character + escape sequence, anyway. -Source files - There should be no ".so" commands to source an external file, - since these break on Linux, where the man program does not - allow source files outside the man/ hierarchy. Instead, insert - this fragment: +Section Ordering - .PP - .RS 5 - .nf - %components% - .fi - .RE - .PP + Always present sections in the following order: - Of course, replace "components" with a unique identifier that - reflects the content being included, like "mts_conf" for - etc/mts.conf. Then, add two lines to the man.sed target in - Makefile.in like: + NAME [*] + SYNOPSIS [*] + DESCRIPTION [*] + PROFILE COMPONENTS + DEFAULTS + CONTEXT + ENVIRONMENT + FILES + EXAMPLES + DIAGNOSTICS [*] + SEE ALSO + HISTORY + BUGS - echo '/%components%/r $(top_srcdir)/etc/components' >> $@ - echo ' s,%components%,,g' >> $@ + Sections marked with a [*] are mandatory. Only include + the others if they are specifically applicable. - At compile time, the contents of the file will physically - incorporated into the body of the man page. This is somewhat - unfortunate, since later modifications won't be reflected in - the manpage, but on the other hand, the manpage will show the - default configuration and not local modifications. + DIAGNOSTICS must document any non-zero exit codes, and can + provide context to error messages. Obviously it only applies + to section 1 and 8 manpages. + + +Dates -Program names + The DATE in the .TH macro should reflect the most recent + *non-trivial* update to the *content* of the manpage; + formatting changes don't count. Spell out the date (no + abbreviations or shortcuts): - All nmh program names should be bolded. If there is punctuation - after the name, use a .BR construct to avoid the automatic - space that's inserted with just a .B: + January 2, 1904 + + not the unparseable + + 01/02/04 + + Don't abbreviate the month. + + +Program Names + + In running text, nmh program names should be set in bold, + unless you are explicitly referring to the command's + documentation, in which case use manpage cross-reference + style. .B comp .BR comp , + .IR comp (1). - The first reference to a documented command should be in the form of - a manpage reference: + Be careful when referring to programs that are not part of + nmh itself. For commands that are almost guaranteed to be + part of the base OS, use a manpage cross-reference (e.g. + ".IR cat (1)"). For other third-party utilities, it might + be best to set the command name in double quotes. Use your + best judgement to make it clear when you're referring to + tools that might not be present. - .BR comp (1) -SYNPOSIS section +SYNPOSIS Section - Literal text (such as flags) should be in bold. Parameters - should be italicized. Mutually exclusive options (like - "-foo" and "-nofoo") should be grouped together and seperated - by a "|": + Set literal text (such as flags) in bold. Set parameters + in italic. Mutually exclusive options (like "-foo" and + "-nofoo") should be grouped together and seperated by a + "|": .RI [ +folder ] <---- parameter .RI [ msgs ] <---- parameter @@ -148,19 +121,19 @@ SYNPOSIS section .I msg argument. - In particular, don't enclose them in single quotes (except - in the DEFAULT section, which might be inconsistent, but - seems a little clearer. + In particular, don't enclose them in single quotes. For "-flag param" situations, try to use a .B/.I combination instead of a single .BI, since it allows more flexibility in case of punctuation, and we get an automatic space between flag and param for free, without having to manual force it. + Subsections Use ".SS" to denote a subsection + Tables The folder manpage has an example of a table. @@ -177,7 +150,21 @@ Tables .RE .PP -Other italicized text + +Environment Variables + + These are always set in roman text. The surrounding text + should make clear you are referring to an environment + variable. In some cases, like when dealing with all-lower-case + variable names, setting the name inside double quotes can + help clarify the context. + + Never prepend a '$' character to an environment variable + name, unless you are directly referring to a variable + substitution in, say, a pathname. + + +Other Italicized Text Italicize file names, profile entries, and folder names: @@ -196,7 +183,70 @@ Other italicized text Enclose the file names and profile entries in lq/rq quotes, too. -Pointer manpages + +Relative Indentation + + Use .RS 5 / .RE to indent paragraphs, etc. '.IP 5' can + be useful, too. Try to use an offset of '5' as much as + possible to maintain visual consistency. + + +Tagged Lists + + In PROFILE COMPONENTS, DEFAULTS, ENVIRONMENT, and FILES, + use tagged paragraphs with an offset of 20. Do not set + the tag in bold or italic, or wrap it in quotes, unless + this is absolutely necessary to make the context clear. + + .SH DEFAULTS + .PD 0 + .TP 20 + +folder + defaults to the current folder + .TP + msgs + defaults to + .I cur + .TP + -decodetext 8bit + .TP + -decodetypes text,application/ics + .TP + -crlflinebreaks + .PD + .SH [...] + +Source Files + + There should be no ".so" commands to source an external file, + since these break on Linux, where the man program does not + allow source files outside the man/ hierarchy. Instead, insert + this fragment: + + .PP + .RS 5 + .nf + %components% + .fi + .RE + .PP + + Of course, replace "components" with a unique identifier that + reflects the content being included, like "mts_conf" for + etc/mts.conf. Then, add two lines to the man.sed target in + Makefile.in like: + + echo '/%components%/r $(top_srcdir)/etc/components' >> $@ + echo ' s,%components%,,g' >> $@ + + At compile time, the contents of the file will physically + incorporated into the body of the man page. This is somewhat + unfortunate, since later modifications won't be reflected in + the manpage, but on the other hand, the manpage will show the + default configuration and not local modifications. + + +Pointer Manpages Certain manpages are shared between one or more programs (such as folder/folders). The secondary program should @@ -206,17 +256,76 @@ Pointer manpages Also, add this manpage to the appropriate section in Makefile.in +AUTHOR and HISTORY Sections -CONTEXT - Don't include a CONTEXT section when contexts are not - applicable. + These have no place in a manpage. If you want everlasting + glory, try the release notes. But note that a HISTORY + section might be appropriate for documenting incompatibility + with older versions of MH. +------------------------------------------------------------------------------ -AUTHOR and HISTORY sections +[ This template is a bit behind the times. I will bring it into + conformance with the notes above once the notes settle down. + --lyndon ] - These have no place in a manpage. If you want everlasting glory, - try the release notes. -BUGS +.TH COMP %manext1% "DATE" "%nmhversion%" +.\" +.\" %nmhwarning% +.\" +.SH NAME +comp \- compose a message +.\" +.SH SYNOPSIS +.HP 5 +.na +.B comp +.RI [ +folder ] +.RI [ msgs ] +.RB [ \-form +.IR formfile ] +.RB [ \-use " | " \-nouse ] +.RB [ \-version ] +.RB [ \-help ] +.ad +.SH DESCRIPTION +.B Comp +is used to create a new message to be mailed. +It copies something. +.\" +.SH "PROFILE COMPONENTS" +.TP 20 +Path +Location of the user's MH folder directory +.TP +moreproc +The pager command name +.\" +.SH DEFAULTS +.TP 20 +.RI + folder +defaults to the current folder +.\" +.SH CONTEXT +None +.\" +.SH FILES +.TP 20 +filename1 +description of filename1 +.TP +filename2 +description of filename2 +.\" +.SH "SEE ALSO" +.BR dist (1), +.BR forw (1), +.BR repl (1), +.BR send (1), +.BR whatnow (1), +.BR mh-profile (5) +.\" Leave out the BUGS section if there are none worth describing. +.SH BUGS +None - The BUGS section goes last. diff --git a/man/dist.man b/man/dist.man index d8beb2b5..23a8f0da 100644 --- a/man/dist.man +++ b/man/dist.man @@ -208,26 +208,41 @@ program which starts the initial edit. Hence, .B \-nowhatnowproc will prevent any edit from occurring.) .SH FILES -.fc ^ ~ -.nf -.ta \w'%nmhetcdir%/ExtraBigFileName 'u -^%nmhetcdir%/distcomps~^The standard message skeleton -^or /distcomps~^Rather than the standard skeleton -^$HOME/\&.mh\(ruprofile~^The user profile -^/draft~^The draft file -.fi +.PD 0 +.TP 20 +%nmhetcdir%/distcomps +The standard message skeleton. +.TP 20 +/distcomps +An alternative to the standard skeleton. +.TP 20 +$HOME/\&.mh\(ruprofile +The user's profile. +.TP 20 +/draft +The draft file. +.PD .SH "PROFILE COMPONENTS" -.fc ^ ~ -.nf -.ta 2.4i -.ta \w'ExtraBigProfileName 'u -^Path:~^To determine the user's nmh directory -^Current\-Folder:~^To find the default current folder -^Draft\-Folder:~^To find the default draft\-folder -^Editor:~^To override the default editor -^fileproc:~^Program to refile the message -^whatnowproc:~^Program to ask the \*(lqWhat now?\*(rq questions -.fi +.PD 0 +.TP 20 +Path: +To determine the user's nmh directory. +.TP 20 +Current\-Folder: +To find the default current folder. +.TP 20 +Draft\-Folder: +To find the default draft\-folder. +.TP 20 +Editor: +To override the default editor. +.TP 20 +fileproc: +Program to refile the message. +.TP 20 +whatnowproc: +Program to ask the \*(lqWhat now?\*(rq questions. +.PD .SH "SEE ALSO" .IR comp (1), .IR forw (1), @@ -236,14 +251,22 @@ will prevent any edit from occurring.) .IR send (1), .IR whatnow (1) .SH DEFAULTS -.nf -.RB ` +folder "' defaults to the current folder" -.RB ` msg "' defaults to cur" -.RB ` \-noannotate ' -.RB ` \-nodraftfolder ' -.RB ` \-inplace ' -.RB ` \-noatfile ' -.fi +.PD 0 +.TP 20 ++folder +The current folder. +.TP 20 +msg +The current message. +.TP 20 +\-noannotate +.TP 20 +\-nodraftfolder +.TP 20 +\-inplace +.TP 20 +\-noatfile +.PD .SH CONTEXT If a folder is given, it will become the current folder. The message distributed will become the current message. diff --git a/man/mh-draft.man b/man/mh-draft.man index 58081531..169913fe 100644 --- a/man/mh-draft.man +++ b/man/mh-draft.man @@ -284,14 +284,20 @@ Disposition? The appropriate responses and their meanings are: .PP .RS 5 -.fc ^ ~ -.nf -.ta \w'replace 'u -.BR ^replace~^ "- deletes the draft and starts afresh" -.BR ^list~^ "- lists the draft" -.BR ^refile~^ "- files the draft into a folder and starts afresh" -.BR ^quit~^ "- leaves the draft intact and exits" -.fi +.PD 0 +.TP 10 +.B replace +deletes the draft and starts afresh +.TP +.B list +lists the draft +.TP +.B refile +files the draft into a folder and starts afresh +.TP 10 +.B quit +leaves the draft intact and exits +.PD .RE .PP In addition, if you specified @@ -300,11 +306,11 @@ In addition, if you specified to the command, then one other response will be accepted: .PP .RS 5 -.fc ^ ~ -.nf -.ta \w'replace 'u -.BR ^new~^ "- finds a new draft" -.fi +.PD 0 +.TP 10 +.B new +finds a new draft +.PD .RE .PP just as if @@ -316,11 +322,11 @@ Finally, the command will accept one more response: .PP .RS 5 -.fc ^ ~ -.nf -.ta \w'replace 'u -.BR ^use~^ "- re-uses the draft" -.fi +.PD 0 +.TP 10 +.B use +re-uses the draft +.PD .RE .PP just as if diff --git a/man/mh-folders.man b/man/mh-folders.man index 1876107b..4c5269a2 100644 --- a/man/mh-folders.man +++ b/man/mh-folders.man @@ -166,13 +166,16 @@ similarly would make .B nmh slower, and introduce usage ambiguities. .SH FILES -.fc ^ ~ -.nf -.ta \w'^/\&.mh\(rusequences~'u -^/context~^The user context -^or $MHCONTEXT~^Rather than the standard context -^/\&.mh\(rusequences~^Public sequences for -.fi +.PD 0 +.TP 20 +/context +The user's context. +.TP 20 +$MHCONTEXT +Overrides the above context. +.TP 20 +/\&.mh\-sequences +Public sequences for . .SH "SEE ALSO" .I .IR flist (1), diff --git a/man/mh-mail.man b/man/mh-mail.man index c317ffd9..686219ea 100644 --- a/man/mh-mail.man +++ b/man/mh-mail.man @@ -307,11 +307,9 @@ to specify a filename to attach to this message. See for more information. .RE .SH FILES -.fc ^ ~ -.nf -.ta \w'%nmhetcdir%/ExtraBigFileName 'u -^%mailspool%/$USER~^Location of mail drop -.fi +.TP 20 +%mailspool%/$USER +Location of mail drop. .SH "SEE ALSO" .I Standard for the Format of ARPA Internet Text Messages diff --git a/man/mh-profile.man b/man/mh-profile.man index cdd78128..8cb85260 100644 --- a/man/mh-profile.man +++ b/man/mh-profile.man @@ -8,7 +8,7 @@ mh-profile \- user profile customization for nmh message handler Each user of .B nmh is expected to have a file named -.I \&.mh\(ruprofile +.I \&.mh\-profile in his or her home directory. This file contains a set of user parameters used by some or all of the .B nmh @@ -28,9 +28,9 @@ This is a comment. .RE .PP Blank lines are not permitted in -.IR \&.mh\(ruprofile. +.IR \&.mh\-profile. The shell quoting conventions are not available in the -.IR \&.mh\(ruprofile ; +.IR \&.mh\-profile ; each token is separated by whitespace. .SS "Standard Profile Entries" The possible profile components are exemplified below. The only mandatory @@ -68,7 +68,7 @@ context Declares the location of the .B nmh context file. This is overridden by the environment variable -.BR $MHCONTEXT . +MHCONTEXT. See the .B HISTORY section below. @@ -133,11 +133,11 @@ man page for the details about this sequence. .RE .PP .BR mh\-sequences : -\&.mh\(rusequences +\&.mh\-sequences .RS 5 The name of the file in each folder which defines public sequences. To disable the use of public sequences, leave the value portion of this -entry blank. (profile, default: \&.mh\(rusequences) +entry blank. (profile, default: \&.mh\-sequences) .RE .PP .BI atr\- seq \- folder : @@ -346,7 +346,7 @@ Tells .B inc your maildrop, if different from the default. This is superseded by the environment variable -.BR $MAILDROP . +MAILDROP. (profile, default: %mailspool%/$USER) .RE .PP @@ -360,9 +360,9 @@ and .B repl your mail signature. This is superseded by the environment variable -.BR $SIGNATURE . +SIGNATURE . If -.B $SIGNATURE +SIGNATURE is not set and this profile entry is not present, the \*(lqgcos\*(rq field of the \fI/etc/passwd\fP file will be used. Your signature will be added to the address @@ -381,8 +381,9 @@ service. The supported entry values are \*(lqlegacy\*(rq and .RI \*(lqfile: netrc \*(rq. With \*(lqlegacy\*(rq, or if there is no credentials entry, the username is the first of: -.PP .RS 5 +.TP 5 +.PD 0 1) .B \-user switch to @@ -393,17 +394,23 @@ switch to or .B msgchk program -.br -2) the login name on the local machine +.TP +2) +the login name on the local machine +.PD .RE .PP The password for SMTP services is the first of: -.PP .RS 5 -1) password value from matching entry in file named \*(lq.netrc\*(rq +.TP 5 +.PD 0 +1) +password value from matching entry in file named \*(lq.netrc\*(rq in the user's home directory -.br -2) password obtained by interactively prompting the user +.TP +2) +password obtained by interactively prompting the user +.PD .RE .PP The password for POP service when the @@ -415,17 +422,21 @@ With a .RI \*(lqfile: netrc \*(rq .B credentials entry, the username is the first of: -.PP .RS 5 +.PD 0 +.TP 5 1) .B \-user switch to program -.br -2) login name from matching entry in +.TP 5 +2) +login name from matching entry in .I netrc file -.br -3) value provided by user in response to interactive query +.TP 5 +3) +value provided by user in response to interactive query +.PD .RE .PP Similarly, the password is provided either in the @@ -463,7 +474,7 @@ The following profile elements are used whenever an program invokes some other program such as .BR more . The -.I \&.mh\(ruprofile +.I \&.mh\-profile can be used to select alternate programs if the user wishes. The default values are given in the examples. .PP @@ -537,7 +548,7 @@ and .B repl to display the draft message. (Note that -.B $PAGER +the environment variable PAGER supersedes the default built-in pager command.) .RE .PP @@ -595,7 +606,7 @@ program used by .B mhshow to display message bodies (or message parts) of type text/plain. (Note that -.B $PAGER +the vivironment variable PAGER supersedes the default built-in pager command.) .RE .PP @@ -685,14 +696,48 @@ After consulting .mh_profile, some programs read an optional profile specified by a program-specific environment variable, and then the system-wide profile %nmhetcdir%/mhn.defaults. -These programs are mhbuild, mhshow, mhstore, and mhn. -mhfixmsg is similar, but has no optional profile. - +These programs are +.BR mhbuild , +.BR mhshow , +.BR mhstore , +and +.BR mhn . +.B mhfixmsg +is similar, but has no optional profile. +.sp The first occurrence of a component is used, e.g.\& .mh_profile's trumps $MHSHOW's. A component with no value still stops further occurrences being used, but is considered absent. -.SS "Environment Variables" +.PP +The +.I \&.mh\-profile +contains only static information, which +.B nmh +programs will +.B NOT +update. Changes in context are made to the +.I context +file kept in the users +.B nmh +directory. +This includes, but is not limited to: the \*(lqCurrent\-Folder\*(rq entry +and all private sequence information. Public sequence information is +kept in each folder in the file determined by the \*(lqmh\-sequences\*(rq +profile entry (default is +.IR \&.mh\-sequences ). +.PP +The +.I \&.mh\-profile +may override the path of the +.I context +file, by specifying a \*(lqcontext\*(rq entry (this must be in +lower-case). If the entry is not absolute (does not start with a +\*(lq/\*(rq), then it is interpreted relative to the user's +.B nmh +directory. As a result, you can actually have more than one set of +private sequences by using different context files. +.SH ENVIRONMENT The operation of .B nmh and its commands it also controlled by the @@ -707,7 +752,7 @@ user, isn't it? The reason for all this is that the .B nmh user can select -.B any +any program as the .IR whatnowproc , including @@ -716,17 +761,28 @@ information via an argument list. The convention is that environment variables whose names are all upper-case are user-settable; those whose names are lower-case only are used internally by nmh and should not generally be set by the user. -.PP -.B $MH -.RS 5 +.TP +MAILDROP +This variable tells +.B inc +the default maildrop. This supersedes the \*(lqMailDrop\*(rq profile entry. +.TP +MAILHOST +This variable tells +.B inc +the POP host to query for mail to incorporate. See the +.IR inc (1) +man page for more information. +.TP +MH With this environment variable, you can specify a profile other than -.I \&.mh\(ruprofile +.I \&.mh\-profile to be read by the .B nmh programs that you invoke. If the value of -.B $MH +MH is not absolute, (i.e., does not begin with a \*(lq/\*(rq), it will be presumed to start from the current working directory. This is one of the very few exceptions in @@ -734,31 +790,45 @@ working directory. This is one of the very few exceptions in where non-absolute pathnames are not considered relative to the user's .B nmh directory. -.RE -.PP -.B $MHCONTEXT -.RS 5 +.TP +MHBUILD +With this environment variable, you can specify an +additional user profile (file) to be read by +.BR mhbuild , +in addition to the mhn.defaults profile. +.TP +MHCONTEXT With this environment variable, you can specify a context other than the normal context file (as specified in the .B nmh profile). As always, unless the value of -.B $MHCONTEXT +MHCONTEXT is absolute, it will be presumed to start from your .B nmh directory. -.RE -.PP -.B $MHBUILD -.RS 5 -With this environment variable, you can specify an -additional user profile (file) to be read by -.BR mhbuild , -in addition to the mhn.defaults profile. -.RE -.PP -.B $MHN -.RS 5 +.TP +MHLDEBUG +If this variable is set to a non-null value, +.B mhl +will emit debugging information. +.TP +MHMTSCONF +If this variable is set to a non-null value, it specifies the +name of the mail transport configuration file to use by +.BR post , +.BR inc , +and other programs that interact with the mail transport system, +instead of the default. See +.IR mh-tailor (5). +.TP +MHMTSUSERCONF +If this variable is set to a non-null value, it specifies the name of +a mail transport configuration file to be read in addition to the +default. See +.IR mh-tailor (5). +.TP +MHN With this environment variable, you can specify an additional user profile (file) to be read by .BR mhn , @@ -766,156 +836,69 @@ in addition to the mhn.defaults profile. .B mhn is deprecated, so support for this variable will be removed from a future nmh release. -.RE -.PP -.B $MHSHOW -.RS 5 +.TP +MHSHOW With this environment variable, you can specify an additional user profile (file) to be read by .BR mhshow , in addition to the mhn.defaults profile. -.RE -.PP -.B $MHSTORE -.RS 5 +.TP +MHSTORE With this environment variable, you can specify an additional user profile (file) to be read by .BR mhstore , in addition to the mhn.defaults profile. -.RE -.PP -.B $MAILDROP -.RS 5 -This variable tells -.B inc -the default maildrop. This supersedes the \*(lqMailDrop\*(rq profile entry. -.RE -.PP -.B $MAILHOST -.RS 5 -This variable tells -.B inc -the POP host to query for mail to incorporate. See the -inc(1) man page for more information. -.RE -.PP -.B $USERNAME_EXTENSION -.RS 5 -This variable is for use with username_extension masquerading. See the -mh-tailor(5) man page. -.RE -.PP -.B $SIGNATURE -.RS 5 -This variable tells -.B send -and -.B post -your mail signature. This supersedes the \*(lqSignature\*(rq profile entry, -and is not used when the \*(lqLocal\-Mailbox\*(rq profile component is set. -.RE -.PP -.B $USER -.RS 5 -This variable tells -.B repl -your user name and -.B inc -your default maildrop: see the \*(lqMailDrop\*(rq profile entry. -.RE -.PP -.B $HOME -.RS 5 -This variable tells all -.B nmh -programs your home directory -.RE -.PP -.B $TERM -.RS 5 -This variable tells -.B nmh -your terminal type. -.PP -The environment variable -.B $TERMCAP -is also consulted. In particular, -these tell -.B scan -and -.B mhl -how to clear your terminal, and how -many columns wide your terminal is. They also tell -.B mhl -how many -lines long your terminal screen is. -.RE -.PP -.B $MHMTSCONF -.RS 5 -If this variable is set to a non-null value, it specifies the -name of the mail transport configuration file to use by -.BR post , -.BR inc , -and other programs that interact with the mail transport system, -instead of the default. See mh-tailor(5). -.RE -.PP -.B $MHMTSUSERCONF -.RS 5 -If this variable is set to a non-null value, it specifies the name of -a mail transport configuration file to be read in addition to the -default. See mh-tailor(5). -.RE -.PP -.B $MHTMPDIR -.B $TMPDIR -.RS 5 -These variables are searched, in order, for the directory in which to -create some temporary files. -.RE -.PP -.B $MHLDEBUG -.RS 5 -If this variable is set to a non-null value, -.B mhl -will emit debugging information. -.RE -.PP -.B $MHPDEBUG -.RS 5 +.TP +MHPDEBUG If this variable is set to a non-null value, .B pick will emit a representation of the search pattern. -.B $MHPDEBUG +MHPDEBUG is deprecated, so support for this variable will be removed from a future nmh release. Instead, .B pick now supports a .B \-debug switch. -.RE -.PP -.B $MHWDEBUG -.RS 5 +.TP +MHTMPDIR, TMPDIR +These variables are searched, in order, for the directory in which to +create some temporary files. +.TP +MHWDEBUG If this variable is set to a non-null value, .B nmh commands that use the -.BR Alternate\-Mailboxes +.B Alternate\-Mailboxes profile entry will display debugging information about the values in that entry. -.RE -.PP -.B $PAGER -.RS 5 +.TP +PAGER If set to a non-null value, this supersedes the value of the default built-in pager command. -.RE -.PP -.B $editalt -.RS 5 +.TP +SIGNATURE +This variable tells +.B send +and +.B post +your mail signature. This supersedes the \*(lqSignature\*(rq profile entry, +and is not used when the \*(lqLocal\-Mailbox\*(rq profile component is set. +.TP +USER +This variable tells +.B repl +your user name and +.B inc +your default maildrop: see the \*(lqMailDrop\*(rq profile entry. +.TP +USERNAME_EXTENSION +This variable is for use with username_extension masquerading. See the +.IR mh-tailor (5) +man page. +.TP +editalt This is the alternate message. -.PP This is set by .B dist and @@ -929,70 +912,48 @@ through a link called \*(lq@\*(rq in the current directory if your current working directory and the folder the message lives in are on the same UNIX filesystem, and if your current working directory is writable. -.RE -.PP -.B $mhdraft -.RS 5 -This is the path to the working draft. -.PP -This is set by -.BR comp , -.BR dist , -.BR forw , -and -.B repl -to tell the -.I whatnowproc -which file to ask \*(lqWhat now?\*(rq -questions about. -.RE -.PP -.B $mhaltmsg -.RS 5 +.TP +mhaltmsg .B dist and .B repl set -.B $mhaltmsg +mhaltmsg to tell the .I whatnowproc about an alternate message associated with the draft (the message being distributed or replied to). -.RE -.PP -.B $mhfolder -.RS 5 -This is the folder containing the alternate message. -.PP +.TP +mhannotate This is set by -.B dist +.BR dist , +.BR forw , and .B repl -during edit sessions so you -can peruse other messages in the current folder besides the one being -distributed or replied to. The environment variable -.B $mhfolder -is also set by -.BR show , -.BR prev , -and -.B next -for use by -.BR mhl . -.RE -.PP -.B $mhdist -.RS 5 +if annotations are to occur. +.TP +mhdist .B dist sets -.B $mhdist +mhdist to tell the .I whatnowproc that message re-distribution is occurring. -.RE -.PP -.B $mheditor -.RS 5 +.TP +mhdraft +This is the path to the working draft. +It is set by +.BR comp , +.BR dist , +.BR forw , +and +.B repl +to tell the +.I whatnowproc +which file to ask \*(lqWhat now?\*(rq +questions about. +.TP +mheditor This is set by .BR comp , .BR repl , @@ -1004,88 +965,62 @@ to tell the the user's choice of editor (unless overridden by .BR \-noedit ). -.RE -.PP -.B $mhuse -.RS 5 -This may be set by -.BR comp . -.RE -.PP -.B $mhmessages -.RS 5 -This is set by -.BR dist , -.BR forw , +.TP +mhfolder +This is the folder containing the alternate message. +It is set by +.B dist and .B repl -if annotations are to occur. -.RE -.PP -.B $mhannotate -.RS 5 +during edit sessions so you +can peruse other messages in the current folder besides the one being +distributed or replied to. The environment variable +mhfolder +is also set by +.BR show , +.BR prev , +and +.B next +for use by +.BR mhl . +.TP +mhinplace This is set by .BR dist , .BR forw , and .B repl if annotations are to occur. -.RE -.PP -.B $mhinplace -.RS 5 +.TP +mhmessages This is set by .BR dist , .BR forw , and .B repl if annotations are to occur. -.RE +.TP +mhuse +This may be set by +.BR comp . .SH FILES -.fc ^ ~ -.nf -.ta \w'%nmhetcdir%/ExtraBigFileName 'u -^$HOME/\&.mh\(ruprofile~^The user profile -^or $MH~^Rather than the standard profile -^/context~^The user context -^or $MHCONTEXT~^Rather than the standard context -^/\&.mh\(rusequences~^Public sequences for -.fi +.PD 0 +.TP 20 +$HOME/\&.mh\-profile +The user's profile. +.TP +/context +The user's context +.TP +/\&.mh\-sequences +Public sequences for . +.PD .SH "SEE ALSO" -.IR environ (5), -.IR mh-sequence (5), .IR mhbuild (1), .IR mhshow (1), .IR mhstore (1), +.IR mh-sequence (5), .IR nmh (7) -.SH HISTORY -The -.I \&.mh\(ruprofile -contains only static information, which -.B nmh -programs will -.B NOT -update. Changes in context are made to the -.I context -file kept in the users -.B nmh -directory. -This includes, but is not limited to: the \*(lqCurrent\-Folder\*(rq entry -and all private sequence information. Public sequence information is -kept in each folder in the file determined by the \*(lqmh\-sequences\*(rq -profile entry (default is -.IR \&.mh\(rusequences ). -.PP -The -.I \&.mh\(ruprofile -may override the path of the -.I context -file, by specifying a \*(lqcontext\*(rq entry (this must be in -lower-case). If the entry is not absolute (does not start with a -\*(lq/\*(rq), then it is interpreted relative to the user's -.B nmh -directory. As a result, you can actually have more than one set of -private sequences by using different context files. .SH BUGS There is some question as to what kind of arguments should be placed in the profile as options. In order to provide a clear answer, recall diff --git a/man/mh-sequence.man b/man/mh-sequence.man index ef82acfa..8d2a56bf 100644 --- a/man/mh-sequence.man +++ b/man/mh-sequence.man @@ -20,16 +20,24 @@ To designate a message, you may use either its number (e.g., 1, 10, 234) or one of these \*(lqreserved\*(rq message names: .PP .RS 5 -.nf -.ta +\w'\fIName\fP 'u -.I "Name Description" -first the first message in the folder -last the last message in the folder -cur the most recently accessed message -prev the message numerically preceding \*(lqcur\*(rq -next the message numerically following \*(lqcur\*(rq -.fi +.PD 0 +.TP +.B first +the first message in the folder +.TP +.B last +the last message in the folder +.TP +.B cur +the most recently accessed message +.TP +.B prev +the message numerically preceding \*(lqcur\*(rq +.TP +.B next +the message numerically following \*(lqcur\*(rq .RE +.PD .PP In commands that take a `msg' argument, the default is \*(lqcur\*(rq. As a shorthand, \*(lq\&.\*(rq is equivalent to \*(lqcur\*(rq. @@ -320,23 +328,32 @@ the possibility exists that two commands run simultaneously that add messages to a private sequence could result in one command's messages not appearing on the requested sequence. .SH FILES -.fc ^ ~ -.nf -.ta \w'%nmhetcdir%/ExtraBigFileName 'u -^$HOME/\&.mh\(ruprofile~^The user profile -^/context~^The user context -^/\&.mh\(rusequences~^File for public sequences -.fi +.PD 0 +.TP 20 +$HOME/\&.mh\-profile +The user's profile. +.TP 20 +/context +The user's context. +.TP 20 +/\&.mh\-sequences +File for public sequences. +.PD .SH "PROFILE COMPONENTS" -.fc ^ ~ -.nf -.ta 2.4i -.ta \w'ExtraBigProfileName 'u -^mh-sequences:~^Name of file to store public sequences -^Sequence\-Negation:~^To designate messages not in a sequence -^Previous\-Sequence:~^The last message specification given -^Unseen\-Sequence:~^Those messages not yet seen by the user -.fi +.PD 0 +.TP 20 +mh-sequences: +Name of file to store public sequences. +.TP 20 +Sequence\-Negation: +To designate messages not in a sequence. +.TP 20 +Previous\-Sequence: +The last message specification given. +.TP 20 +Unseen\-Sequence: +Those messages not yet seen by the user. +.PD .SH "SEE ALSO" .IR flist (1), .IR mark (1), diff --git a/man/mh-tailor.man b/man/mh-tailor.man index 4b2362ff..5e655549 100644 --- a/man/mh-tailor.man +++ b/man/mh-tailor.man @@ -34,8 +34,8 @@ and .PP If you use .BR smtp , -this will enable a direct SMTP (simple mail transport -protocol) interface in +this will enable a direct SMTP +interface in .BR nmh . When sending mail, instead of passing the message to the mail transport agent, @@ -282,7 +282,7 @@ during updates. These locking methods can be configured separately from each other. .PP For locking the mail spool, the -.I spoollocking +.B spoollocking entry in .IR mh\-tailor (5) will control the locking algorithm to use when @@ -291,12 +291,12 @@ incorporates mail from the spool file. If no entry is given, a default based on the operating system type will be chosen. .PP For locking all other files, the -.I datalocking +.B datalocking entry in .IR mh-profile (5) controls the locking algorithm used for all other file access. If no entry is given, the -.I fcntl +.B fcntl lock method will be chosen. .PP If you do not wish to use kernel\-based locking, @@ -313,11 +313,9 @@ Prior to installing you should see how locking is done at your site, and set the appropriate values. .SH FILES -.fc ^ ~ -.nf -.ta \w'%nmhetcdir%/ExtraBigFileName 'u -^%nmhetcdir%/mts.conf~^nmh mts configuration file -.fi +.TP 20 +%nmhetcdir%/mts.conf +nmh mts configuration file .SH "PROFILE COMPONENTS" None .SH "SEE ALSO" @@ -326,16 +324,17 @@ None .SH DEFAULTS As listed above. The path of the mail transport configuration file can be changed with the -.B MHMTSCONF +MHMTSCONF environment variable and augmented with the -.B MHMTSUSERCONF -environment variable, see mh\-profile(5). +MHMTSUSERCONF +environment variable, see +.IR mh\-profile (5). .SH BUGS Failure to open any mail transport configuration file is silently ignored. Therefore, it's best to avoid dynamic creation of such a file with the intent of use via the -.B MHMTSCONF +MHMTSCONF or -.B MHMTSUSERCONF +MHMTSUSERCONF environment variables. If such use is necessary, the ability to successfully open the file should first be verified. diff --git a/man/mhbuild.man b/man/mhbuild.man index 21f7d9c8..3d2fbbaf 100644 --- a/man/mhbuild.man +++ b/man/mhbuild.man @@ -36,16 +36,19 @@ a valid MIME message. .PP .B mhbuild creates multi-media messages as specified in RFC 2045 -to RFC 2049. This includes the encoding of message headers as specified +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. .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, +input. +If the translation of this input is successful, .B mhbuild -will output the new MIME message to the standard output. This argument +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 @@ -53,10 +56,12 @@ 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 +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 +it will be renamed to \*(lq,draft.orig\*(rq. +This allows you to easily recover the .B mhbuild input file. @@ -70,13 +75,16 @@ to list the table of contents associated with the MIME message that is created. The .B \-headers switch indicates -that a one-line banner should be displayed above the listing. The +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 +(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 @@ -90,84 +98,113 @@ 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 +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 +message using normal MIME encapsulation rules. +One filename is allowed per \*(lqAttach\*(rq header, but multiple \*(lqAttach\*(rq headers are allowed ber 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 By default, the Content-Disposition will be \*(lqattachment\*(rq. .B mhbuild -looks for user profile and mhn.defaults entries of the form +looks for user profile and +.I mhn.defaults +entries of the form .PP .RS 5 -mhbuild-disposition-/ +.BI mhbuild-disposition- type / subtype .RE or .RS 5 -mhbuild-disposition- +.BI mhbuild-disposition- type .RE .PP -to supply the disposition value. The only supported values are -.I attachment +to supply the disposition value. +The only supported values are +\*(lqattachment\*(rq and -.IR inline. +\*(lqinline\*(rq. .SS "Convert Interface" -.nr item 1 1 -The \*(lqconvert\*(rq interface is a powerful mechanism that supports -replying to MIME messages. These placeholders are used in the following +The convert interface is a powerful mechanism that supports +replying to MIME messages. +These placeholders are used in the following description: -.IP TYPE +.RS 5 +.TP 15 +.PD 0 +TYPE content type/subtype -.IP CONVERTER +.TP +CONVERTER external program, and any fixed arguments, to convert content, such as from a request to a reply -.IP ARGSTRING +.TP +ARGSTRING arguments to pass from .B repl to .I CONVERTER -.IP FILE +.TP +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 - Nmh-mhbuild-file-TYPE: FILE - Nmh-mhbuild-args-TYPE: ARGSTRING +.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 mhn.defaults for this corresponding TYPE entry to find the +in the draft. +For each such pseudoheader, mhbuild looks in the +profile and +.I mhn.defaults +for this corresponding +.I TYPE +entry to find the converter that supports it: .PP .RS 5 -.RI mhbuild-convert- TYPE : -.I CONVERTER +.BI mhbuild-convert- TYPE : \0CONVERTER .RE .PP -It's a fatal error if no such entry is found for TYPE. An empty +It's a fatal error if no such entry is found for +.IR TYPE . +An empty entry, e.g., .PP .RS 5 -mhbuild-convert-text/html: +.B mhbuild-convert-text/html: .RE .PP -excludes parts of that TYPE from the draft. The mhn.defaults file +excludes parts of that +.I TYPE +from the draft. +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 -mhn.defaults entries, as usual. +entries. +Profile entries can be used to override corresponding +.I mhn.defaults +entries, as usual. .PP For each .I TYPE @@ -180,13 +217,19 @@ on the content of the part. .PP Each part in .I FILE -that has no corresponding TYPE entry in the profile or mhn.defaults is +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. .PP .B repl -inserts Nmh-mhbuild-text/html: and Nmh-mhbuild-text/plain: -pseudoheaders in every draft. The user can prevent insertion of +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 @@ -195,28 +238,33 @@ 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 -.BR iconv "(1)," +install time. +It includes +.B iconv and -.BR par (1) +.BR par , or -.BR fmt "(1)," -in the pipeline only if found. +.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 -.I method=REPLY -for text/calendar. mhbuild looks for a Content-Type header, followed -by a blank line, at the beginning of the converter output. If one is +\*(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 \*(lqconvert\*(rq interface doesn't support different +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 +or converters. +Instead, that can be done (currently, without using the convert support), with .B mhbuild directives as described below, e.g., @@ -226,8 +274,10 @@ directives as described below, e.g., .RE .PP The only way to mix -.B convert -pseudoheaders and mhbuild directives is to insert the directives before +convert +pseudoheaders and +.B mhbuild +directives is to insert the directives before .B mhbuild is run, which is typically done by entering .I mime @@ -237,42 +287,43 @@ switch. .PP These (optional) setup steps can make the convert support easier to use: -.IP \n[item]. 3 +.TP 5 +1) If the -.BR par (1) +.B par program is installed on your system, it will be set by default -(in mhn.defaults) to filter the converter output. It helps to +(in +.IR mhn.defaults ) +to filter the converter output. +It helps to set the -.B $PARINIT +PARINIT environment variable, as described in its man page. -.IP \n+[item]. 3 +.TP 5 +2) Add this line to your profile: -.PP -.RS 5 -.nf +.IP "" 10 mhbuild-next: $EDITOR -.fi -.RE -.PP -.RS 3 +.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 +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 -.IP \n+[item]. 3 +.TP 5 +3) If using .BR repl , source the Bourne-shell compatible functions in .IR %docdir%/contrib/replaliases . .br That script also sets the -.B $PARINIT +PARINIT environment variable if it was not set. .RE -.PP .SS "Translating the Composition File" .B mhbuild is essentially a filter to aid in the composition of MIME @@ -281,13 +332,15 @@ messages. will convert an .B mhbuild \*(lqcomposition file\*(rq -into a valid MIME message. A +into a valid MIME message. +A .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 +directives. +When this file is processed by .BR mhbuild , the various directives will be expanded to the @@ -298,9 +351,11 @@ 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 +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 +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 @@ -323,9 +378,11 @@ directives are honored at all. 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 +\*(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 +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: @@ -342,10 +399,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 +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, @@ -373,14 +432,18 @@ will echo any commands that are used to create contents in this way. The composition string may contain the following escapes: .PP .RS 5 -.nf -.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 % -.fi +.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, @@ -388,19 +451,21 @@ First, will look for an entry of the form: .PP .RS 5 -mhbuild-compose-/ +.BI mhbuild-compose- type / subtype .RE .PP -to determine the command to use to compose the content. If this isn't +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 -mhbuild-compose- +.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 @@ -413,16 +478,19 @@ 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 -.B $MHBUILD +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 +(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, +are supplied. +These look like regular parameters, so they must be +separated accordingly. +For example, .PP .RS 5 .nf @@ -442,7 +510,8 @@ separated accordingly. For example, 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. A disposition string, to appear in a +\*(lq[]\*(rq. +A disposition string, to appear in a \*(lqContent-Disposition\*(rq header, may appear in the optional \*(lq{}\*(rq. .PP @@ -451,12 +520,12 @@ These parameters are of the form: .RS 5 .nf .ta \w'access-type= 'u -access-type= usually \fIanon-ftp\fR, \fImail-server\fR, or \fIurl\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 @@ -480,10 +549,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 -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 +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 .B forw command, except that the former uses @@ -497,7 +570,8 @@ 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 \*(lqmessage/rfc822\*(rq. +If you include more than one message, then .B mhbuild will add a content of type \*(lqmultipart/digest\*(rq @@ -506,14 +580,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. 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 +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 @@ -532,13 +608,15 @@ This will be a multipart with only one part. If you use multiple directives in a composition draft, .B mhbuild will -automatically encapsulate them inside a multipart content. Therefore the +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 +character. +This description will be copied into the \*(lqContent-Description\*(rq header when the directive is processed. .PP .RS 5 @@ -552,7 +630,8 @@ Similarly, a disposition string may optionally be provided between \*(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 +added to the \*(lqContent-Disposition\*(rq header. +For example, the following directive: .PP .RS 5 @@ -575,7 +654,8 @@ 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. @@ -583,18 +663,22 @@ even in the top level of the message. 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 +and the MIME Content\-Type. +However, you can override that in an .B mhbuild -directive by specifying \*(lq*\*(rq and the encoding. Acceptable encoding +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 +\*(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 +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., .PP @@ -624,9 +708,11 @@ then this will be used to describe the plaintext content. 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 +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., +a content-type specification. +For example, e.g., .PP .RS 5 .nf @@ -657,7 +743,8 @@ high bit set) and the character set is not specified as above, then will assume the character set is of the type given by the standard .IR locale (1) -environment variables. If these environment variables are not +environment variables. +If these environment variables are not set, then the character set will be labeled as \*(lqx-unknown\*(rq. .PP If a text content contains only 7\-bit characters and the character set @@ -665,7 +752,8 @@ is not specified as above, then the character set will be labeled as \*(lqus-ascii\*(rq. .PP 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 +Content\-Transfer\-Encoding. +If the text has lines longer than the value of .B \-maxunencoded (which defaults to 78) then the text is encoded using the quoted\-printable @@ -674,18 +762,21 @@ encoding. The .B \-headerencoding switch will indicate which algorithm to use when encoding any message headers -that contain 8\-bit characters. The valid arguments are +that contain 8\-bit characters. +The valid arguments are .I base64 for based\-64 encoding and .I quoted -for quoted\-printable encoding. The +for quoted\-printable encoding. +The .B \-autoheaderencoding switch will instruct .B mhbuild to automatically pick the algorithm that results in a shorter encoded string. .PP Putting this all together, -here is an example of a more complicated message draft. The +here is an example of a more complicated message draft. +The following draft will expand into a multipart/mixed message containing five parts: .PP @@ -712,17 +803,21 @@ If is given the .B \-check switch, then it will also associate an integrity check with each -\*(lqleaf\*(rq content. This will add a Content-MD5 header field to +\*(lqleaf\*(rq 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 message to verify that +1864. +This may be used by the receiver of the message to verify that the contents of the message were not changed in transport. .SS "Transfer Encodings" After .B mhbuild constructs the new MIME message by parsing directives, including files, etc., it scans the contents of the message to determine -which transfer encoding to use. It will check for 8bit data, long lines, -spaces at the end of lines, and clashes with multipart boundaries. It will +which transfer encoding to use. +It will check for 8bit data, long lines, +spaces at the end of lines, and clashes with multipart boundaries. +It will then choose a transfer encoding appropriate for each content type. .PP If an integrity check is being associated with each content by using @@ -731,7 +826,8 @@ the switch, then .B mhbuild will encode each content with -a transfer encoding, even it the content contains only 7\-bit data. This +a transfer encoding, even it the content contains only 7\-bit data. +This is to increase the likelihood that the content is not changed while in transport. .SS "Invoking mhbuild" @@ -739,10 +835,12 @@ Typically, .B mhbuild is invoked by the .B whatnow -program. This +program. +This command will expect the body of the draft to be formatted as an .B mhbuild -composition file. Once you have composed this input file +composition file. +Once you have composed this input file using a command such as .BR comp , .BR repl , @@ -756,7 +854,8 @@ at the \*(lqWhat now\*(rq prompt with What now? mime .RE .PP -prior to sending the draft. This will cause +prior to sending the draft. +This will cause .B whatnow to execute .B mhbuild @@ -764,7 +863,8 @@ to translate the composition file into MIME format. .PP Normally it is an error to invoke .B mhbuild -on file that already in MIME format. The +on file that already in MIME format. +The .B \-auto switch will cause .B mhbuild @@ -807,9 +907,10 @@ operates may vary for a user, .B mhbuild will look for the environment variable -.BR $MHBUILD . +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, +should be read. +Hence, when a user logs in on a particular machine, this environment variable should be set to refer to a file containing definitions useful for that machine. .PP @@ -897,43 +998,44 @@ line ::= "##" text EOL .RE .SH FILES .B mhbuild -looks for additional user profile files and mhn.defaults in multiple +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 +directory as specified in their profile. +If not found there, the directory .RI \*(lq %nmhetcdir% \*(rq is checked. .PP -.fc ^ ~ -.nf -.ta \w'%nmhetcdir%/ExtraBigFileName 'u -^$HOME/\&.mh\(ruprofile~^The user profile -^$MHBUILD~^Additional profile entries -^%nmhetcdir%/mhn.defaults~^System default MIME profile entries -.fi +.PD 0 +.TP 20 +$HOME/\&.mh\(ruprofile +The user's profile. +.TP +$MHBUILD +Additional profile entries. +.TP +%nmhetcdir%/mhn.defaults +System default MIME profile entries. +.PD .SH "PROFILE COMPONENTS" -.fc ^ ~ -.nf -.ta 2.4i -.ta \w'ExtraBigProfileName 'u -^Path:~^To determine the user's nmh directory -^Current\-Folder:~^To find the default current folder -^mhbuild-compose-*~^Template for composing contents -.fi +.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), -.IR fmt (1), -.IR iconv (1), -.IR par (1) -.PP -.I "Proposed Standard for Message Encapsulation" -(RFC 934), -.PP -.I "The Content-MD5 Header Field" -(RFC 1864), +.IR mhstore (1) .PP .I "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies" (RFC 2045), @@ -944,26 +1046,26 @@ is checked. .I "Multipurpose Internet Mail Extensions (MIME) Part Three: Message Header Extensions for Non-ASCII Text" (RFC 2047), .PP -.I "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures" -(RFC 2048), +.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 "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples" -(RFC 2049), +.I "The Content-MD5 Header Field" +(RFC 1864), .PP .I "Definition of the URL MIME External-Body Access-Type" (RFC 2017), -.PP -.I "MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations" -(RFC 2231) .SH DEFAULTS .nf -.RB ` \-headers ' -.RB ` \-realsize ' -.RB ` \-norfc934mode ' -.RB ` \-contentid ' -.RB ` \-nocheck ' -.RB ` \-noverbose ' -.RB ` \-nodisposition ' -.RB ` \-autoheaderencoding ' -.RB ` "\-maxunencoded\ 78"' +\-autoheaderencoding +\-contentid +\-headers +\-maxunencoded 78 +\-nocheck +\-nodisposition +\-norfc934mode +\-noverbose +\-realsize .fi diff --git a/man/new.man b/man/new.man index e95e7de7..f21b51fb 100644 --- a/man/new.man +++ b/man/new.man @@ -82,20 +82,21 @@ executes .B scan sequences for each matching folder. .SH FILES -.fc ^ ~ -.nf -.ta \w'%nmhetcdir%/ExtraBigFileName 'u -^$HOME/\&.mh\(ruprofile~^The user profile -.fi +.TP 20 +$HOME/\&.mh\(ruprofile +The user profile .SH "PROFILE COMPONENTS" -.fc ^ ~ -.nf -.ta 2.4i -.ta \w'ExtraBigProfileName 'u -^Path:~^To determine the user's nmh directory -^Current\-Folder:~^To find the default current folder -^Unseen-Sequence:~^The name of the unseen message sequence -.fi +.PD 0 +.TP 20 +Path: +To determine the user's nmh directory. +.TP 20 +Current\-Folder: +To find the default current folder. +.TP 20 +Unseen-Sequence: +The name of the unseen message sequence. +.PD .SH "SEE ALSO" .IR scan (1), .IR mh\-format (5) diff --git a/man/next.man b/man/next.man index 9e246287..c27492cf 100644 --- a/man/next.man +++ b/man/next.man @@ -43,29 +43,37 @@ Consult the manual entry for for all the details. .SH FILES -.fc ^ ~ -.nf -.ta \w'%nmhetcdir%/ExtraBigFileName 'u -^$HOME/\&.mh\(ruprofile~^The user profile -.fi +.TP 20 +$HOME/\&.mh\(ruprofile +The user profile .SH "PROFILE COMPONENTS" -.fc ^ ~ -.nf -.ta 2.4i -.ta \w'ExtraBigProfileName 'u -^Path:~^To determine the user's nmh directory -^Current\-Folder:~^To find the default current folder -^showproc:~^Program to show non-MIME messages -^showmimeproc:~^Program to show MIME messages -.fi +.PD 0 +.TP 20 +Path: +To determine the user's nmh directory +.TP 20 +Current\-Folder: +To find the default current folder +.TP 20 +showproc: +Program to show non-MIME messages +.TP 20 +showmimeproc: +Program to show MIME messages +.PD .SH "SEE ALSO" .IR prev (1), .IR show (1) .SH DEFAULTS -.nf -.RB ` +folder "' defaults to the current folder" -.RB ` \-checkmime ' -.RB ` \-header ' +.PD 0 +.TP 20 ++folder +The current folder. +.TP 20 +\-checkmime +.TP 20 +\-header +.PD .SH CONTEXT If a folder is specified, it will become the current folder. The message that is shown (i.e., the next message in sequence) will become the diff --git a/uip/mhparse.c b/uip/mhparse.c index 6f8ebaf1..1193d564 100644 --- a/uip/mhparse.c +++ b/uip/mhparse.c @@ -4334,7 +4334,7 @@ char *get_param_value(PM pm, char replace) } if (utf8) { for (++p, --inbytes; - inbytes > 0 && (((unsigned char) *q) & 0xc0) == 0x80; + inbytes > 0 && (((unsigned char) *p) & 0xc0) == 0x80; ++p, --inbytes) continue; } else { diff --git a/uip/mhshowsbr.c b/uip/mhshowsbr.c index 056c2f45..a87778ef 100644 --- a/uip/mhshowsbr.c +++ b/uip/mhshowsbr.c @@ -1080,6 +1080,7 @@ convert_charset (CT ct, char *dest_charset, int *message_mods) { char *dest_buffer = mh_xmalloc(dest_buffer_size); HF hf; char *tempfile; + int fromutf8 = !strcasecmp(src_charset, "UTF-8"); if ((conv_desc = iconv_open (dest_charset, src_charset)) == (iconv_t) -1) { @@ -1149,6 +1150,32 @@ iconv_start: outbytes_before += bumpup; goto iconv_start; } + if (errno == EINVAL) { + /* middle of multi-byte sequence */ + if (write (fd, dest_buffer, outbytes_before - outbytes) < 0) { + advise (dest, "write"); + } + fseeko (*fp, -inbytes, SEEK_CUR); + if (end > 0) bytes_to_read += inbytes; + /* advise(NULL, "convert_charset: EINVAL"); */ + continue; + } + if (errno == EILSEQ) { + /* invalid multi-byte sequence */ + if (fromutf8) { + for (++ib, --inbytes; + inbytes > 0 && + (((unsigned char) *ib) & 0xc0) == 0x80; + ++ib, --inbytes) + continue; + } else { + ib++; inbytes--; /* skip it */ + } + (*ob++) = '?'; outbytes --; + /* advise(NULL, "convert_charset: EILSEQ"); */ + goto iconv_start; + } + advise (NULL, "convert_charset: errno = %d", errno); status = NOTOK; break; } else {