1.0.1 patches
[mmh] / man / mh-profile.man
1 .\"
2 .\" %nmhwarning%
3 .\" $Id$
4 .\"
5 .\" include the -mh macro file
6 .so %etcdir%/tmac.h
7 .\"
8 .TH MH-PROFILE %manext5% MH.6.8 [%nmhversion%]
9 .SH NAME
10 mh-profile \- user profile customization for nmh message handler
11 .SH SYNOPSIS
12 .in +.5i
13 .ti -.5i
14 \&\fI.mh\(ruprofile\fP
15 .in -.5i
16 .SH DESCRIPTION
17 Each user of \fInmh\fR is expected to have a file named
18 \fI\&.mh\(ruprofile\fR in his or her home directory.  This file contains
19 a set of user parameters used by some or all of the \fInmh\fR family
20 of programs.  Each entry in the file is of the format
21
22     \fIprofile\-component\fR: \fIvalue\fR
23
24 If the text of profile entry is long, you may extend it across several
25 real lines by indenting the continuation lines with leading spaces
26 or tabs.
27
28 .Uh "Standard Profile Entries"
29 The possible profile components are exemplified below.  The only mandatory
30 entry is `Path:'.  The others are optional; some have default values if
31 they are not present.  In the notation used below, (profile, default)
32 indicates whether the information is kept in the user's \fInmh\fR profile
33 or \fInmh\fR context, and indicates what the default value is.
34
35 .in +1i
36 .ti -1i
37 Path: Mail
38 .br
39 Locates \fInmh\fR transactions in directory \*(lqMail\*(rq.  This is the
40 only mandatory profile entry.  (profile, no default)
41
42 .ti -1i
43 context: context
44 .br
45 Declares the location of the \fInmh\fR context file.  This is
46 overridden by the environment variable \fBMHCONTEXT\fR.
47 See the \fBHISTORY\fR section below.
48 (profile, default: <nmh\-dir>/context)
49
50 .ti -1i
51 Current\-Folder:\ inbox
52 .br
53 Keeps track of the current open folder.
54 (context, default: folder specified by \*(lqInbox\*(rq)
55
56 .ti -1i
57 Inbox: inbox
58 .br
59 Defines the name of your default inbox.
60 (profile, default: inbox)
61
62 .ti -1i
63 Previous\-Sequence:\ pseq
64 .br
65 Names the sequence or sequences which should be defined as the `msgs' or
66 `msg' argument given to any \fInmh\fR command.  If not present or empty,
67 no such sequences are defined.  Otherwise, for each name given, the
68 sequence is first zero'd and then each message is added to the sequence.
69 Read the mh\-sequence(5) man page for the details about this sequence.
70 (profile, no default)
71
72 .ti -1i
73 Sequence\-Negation:\ not
74 .br
75 Defines the string which, when prefixed to a sequence name, negates
76 that sequence.  Hence, \*(lqnotseen\*(rq means all those messages that
77 are not a member of the sequence \*(lqseen\*(rq.  Read the mh\-sequence(5)
78 man page for the details.  (profile, no default)
79
80 .ti -1i
81 Unseen\-Sequence:\ unseen
82 .br
83 Names the sequence or sequences which should be defined as those
84 messages which are unread.  The commands \fIinc\fR, \fIrcvstore\fR,
85 \fImhshow\fR, and \fIshow\fR will add or remove messages from these
86 sequences when they are incorporated or read.  If not present or
87 empty, no such sequences are defined.  Otherwise, each message is
88 added to, or removed from, each sequence name given.  Read the
89 mh\-sequence(5) man page for the details about this sequence.
90 (profile, no default)
91
92 .ti -1i
93 mh\-sequences:\ \&.mh\(rusequences
94 .br
95 The name of the file in each folder which defines public sequences.
96 To disable the use of public sequences, leave the value portion of this
97 entry blank.  (profile, default: \&.mh\(rusequences)
98
99 .ti -1i
100 atr\-\fIseq\fR\-\fIfolder\fR:\ 172\0178\-181\0212
101 .br
102 Keeps track of the private sequence called \fIseq\fR in the specified
103 folder.  Private sequences are generally used for read\-only folders.
104 See the mh\-sequence(5) man page for details about private sequences.
105 (context, no default)
106
107 .ti -1i
108 Editor:\ /usr/bin/vi
109 .br
110 Defines the editor to be used by the commands \fIcomp\fR\0(1),
111 \fIdist\fR\0(1), \fIforw\fR\0(1), and \fIrepl\fR\0(1).  (profile, default:
112 %default_editor%)
113
114 .ti -1i
115 automimeproc:
116 .br
117 If defined and set to 1, then the \fIwhatnow\fR program will automatically
118 invoke the buildmimeproc (discussed below) to process each message as a MIME
119 composition draft before it is sent.
120 (profile, no default)
121
122 .ti -1i
123 Msg\-Protect:\ 644
124 .br
125 An octal number which defines the permission bits for new message files.
126 See \fIchmod\fR\0(1) for an explanation of the octal number.
127 (profile, default: 0644)
128
129 .ti -1i
130 Folder\-Protect:\ 700
131 .br
132 An octal number which defines the permission bits for new folder
133 directories.  See \fIchmod\fR\0(1) for an explanation of the octal number.
134 (profile, default: 0700)
135
136 .ti -1i
137 \fIprogram\fR:\ default switches
138 .br
139 Sets default switches to be used whenever the mh program \fIprogram\fR
140 is invoked.  For example, one could override the \fIEditor\fR: profile
141 component when replying to messages by adding a component such as:
142 .br
143         repl: \-editor /bin/ed
144 .br
145 (profile, no defaults)
146
147 .ti -1i
148 \fIlasteditor\fR\-next:\ nexteditor
149 .br
150 Names \*(lqnexteditor\*(rq to be the default editor after using
151 \*(lqlasteditor\*(rq.  This takes effect at \*(lqWhat now?\*(rq prompt
152 in \fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR.  After editing
153 the draft with \*(lqlasteditor\*(rq, the default editor is set to be
154 \*(lqnexteditor\*(rq.  If the user types \*(lqedit\*(rq without any
155 arguments to \*(lqWhat now?\*(rq, then \*(lqnexteditor\*(rq is used.
156 (profile, no default)
157
158 .ti -1i
159 bboards: system
160 .br
161 Tells \fIbbc\fR which BBoards you are interested in.  (profile, default:
162 system)
163
164 .ti -1i
165 Folder\-Stack: \fIfolders\fR
166 .br
167 The contents of the folder-stack for the \fIfolder\fR command.
168 (context, no default)
169
170 .ti -1i
171 mhe:
172 .br
173 If present, tells \fIinc\fR to compose an \fIMHE\fR auditfile in addition
174 to its other tasks.  \fIMHE\fR is Brian Reid's \fIEmacs\fR front-end
175 for \fInmh\fR.  (profile, no default)
176
177 .ti -1i
178 Alternate\-Mailboxes: mh@uci\-750a, bug-mh*
179 .br
180 Tells \fIrepl\fR and \fIscan\fR which addresses are really yours.
181 In this way, \fIrepl\fR knows which addresses should be included in the
182 reply, and \fIscan\fR knows if the message really originated from you.
183 Addresses must be separated by a comma, and the hostnames listed should
184 be the \*(lqofficial\*(rq hostnames for the mailboxes you indicate, as
185 local nicknames for hosts are not replaced with their official site names.
186 For each address, if a host is not given, then that address on any host is
187 considered to be you.  In addition, an asterisk (`*') may appear at either
188 or both ends of the mailbox and host to indicate wild-card matching.
189 (profile, default: your user-id)
190
191 .ti -1i
192 Aliasfile: aliases other-alias
193 .br
194 Indicates aliases files for \fIali\fR, \fIwhom\fR, and \fIsend\fR.
195 This may be used instead of the `\-alias file' switch.  (profile, no
196 default)
197
198 .ti -1i
199 Draft\-Folder: drafts
200 .br
201 Indicates a default draft folder for \fIcomp\fR, \fIdist\fR, \fIforw\fR,
202 and \fIrepl\fR.  Read the mh\-draft (5) man page for details.
203 (profile, no default)
204
205 .ti -1i
206 digest\-issue\-\fIlist\fR:\ 1
207 .br
208 Tells \fIforw\fR the last issue of the last volume sent for the digest
209 \fIlist\fR.  (context, no default)
210
211 .ti -1i
212 digest\-volume\-\fIlist\fR:\ 1
213 .br
214 Tells \fIforw\fR the last volume sent for the digest \fIlist\fR.
215 (context, no default)
216
217 .ti -1i
218 MailDrop: .mail
219 .br
220 Tells \fIinc\fR your maildrop, if different from the default.  This is
221 superseded by the environment variable \fBMAILDROP\fR.  (profile, default:
222 %mailspool%/$USER)
223
224 .ti -1i
225 Signature: RAND MH System (agent: Marshall Rose)
226 .br
227 Tells \fIsend\fR your mail signature.  This is superseded by the
228 environment variable \fBSIGNATURE\fR.  If \fBSIGNATURE\fR is not set and
229 this profile entry is not present, the \*(lqgcos\*(rq field of
230 the \fI/etc/passwd\fP file will be used; otherwise, on hosts where
231 \fInmh\fR was configured with the UCI option, the file $HOME/.signature
232 is consulted.  Your signature will be added to the address \fIsend\fP
233 puts in the \*(lqFrom:\*(rq header; do not include an address in the
234 signature text.  (profile, no default)
235 .in -1i
236
237 .Uh "Process Profile Entries"
238 The following profile elements are used whenever an \fInmh\fR
239 program invokes some other program such as \fImore\fR\0(1).  The
240 \fI\&.mh\(ruprofile\fR can be used to select alternate programs if the
241 user wishes.  The default values are given in the examples.
242
243 .in +1i
244 .ti -1i
245 buildmimeproc: %bindir%/mhbuild
246 .br
247 This is the program used by \fIwhatnow\fR to process drafts which
248 are MIME composition files.
249
250 .ti -1i
251 fileproc: %bindir%/refile
252 .br
253 This program is used to refile or link a message to another folder.
254 It is used by \fIpost\fR to file a copy of a message into a folder given
255 by a \*(lqFcc:\*(rq field.  It is used by the draft folder facility in
256 \fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR to refile a draft
257 message into another folder.  It is used to refile a draft message in
258 response to the `refile' directive at the \*(lqWhat now?\*(rq prompt.
259
260 .ti -1i
261 incproc: %bindir%/inc
262 .br
263 Program called by \fImhmail\fR to incorporate new mail when it
264 is invoked with no arguments.
265
266 .ti -1i
267 installproc: %libdir%/install\-mh
268 .br
269 This program is called to initialize the environment for
270 new users of nmh.
271
272 .ti -1i
273 lproc: %default_pager%
274 .br
275 This program is used to list the contents of a message in response
276 to the `list' directive at the \*(lqWhat now?\*(rq prompt.  It is
277 also used by the draft folder facility in \fIcomp\fR, \fIdist\fR,
278 \fIforw\fR, and \fIrepl\fR to display the draft message.
279
280 .ti -1i
281 mailproc: %bindir%/mhmail
282 .br
283 This is the program used to automatically mail various messages
284 and notifications.  It is used by \fIconflict\fR when using the
285 `-mail' option.  It is used by \fIsend\fR to post failure notices.
286 It is used to retrieve an external-body with access-type `mail-server'
287 (such as when storing the body with \fImhstore\fR).
288
289 .ti -1i
290 mhlproc: %libdir%/mhl
291 .br
292 This is the program used to filter messages in various ways.  It
293 is used by \fImhshow\fR to filter and display the message headers
294 of MIME messages.  When the `-format' or `-filter' option is used
295 by \fIforw\fR or \fIrepl\fR, the mhlproc is used to filter the
296 message that you are forwarding, or to which you are replying.
297 When the `-filter' option is given to \fIsend\fR or \fIpost\fR,
298 the mhlproc is used by \fIpost\fR to filter the copy of the message
299 that is sent to \*(lqBcc:\*(rq recipients.
300
301 .ti -1i
302 moreproc: %default_pager%
303 .br
304 This is the program used by \fImhl\fR to page the \fImhl\fR formatted
305 message when displaying to a terminal.  It is also the default
306 program used by \fImhshow\fR to display message bodies (or message
307 parts) of type text/plain.
308
309 .ti -1i
310 mshproc: %bindir%/msh
311 .br
312 Currently not used.
313
314 .ti -1i
315 packproc: %bindir%/packf
316 .br
317 Currently not used.
318
319 .ti -1i
320 postproc: %libdir%/post
321 .br
322 This is the program used by \fIsend\fR, \fImhmail\fR, \fIrcvdist\fR,
323 and \fIviamail\fR (used by the \fIsendfiles\fR shell script) to
324 post a message to the mail transport system.  It is also called by
325 \fIwhom\fR (called with the switches `-whom' and `-library') to do
326 address verification.
327
328 .ti -1i
329 rmmproc: none
330 .br
331 This is the program used by \fIrmm\fR and \fIrefile\fR to delete
332 a message from a folder.
333
334 .ti -1i
335 rmfproc: %bindir%/rmf
336 .br
337 Currently not used.
338
339 .ti -1i
340 sendproc: %bindir%/send
341 .br
342 This is the program to use by \fIwhatnow\fR to actually
343 send the message
344
345 .ti -1i
346 showmimeproc: %bindir%/mhshow
347 .br
348 This is the program used by \fIshow\fR to process and display
349 non-text (MIME) messages.
350
351 .ti -1i
352 showproc: %libdir%/mhl
353 .br
354 This is the program used by \fIshow\fR to filter and display text
355 (non-MIME) messages.
356
357 .ti -1i
358 whatnowproc: %bindir%/whatnow
359 .br
360 This is the program invoked by \fIcomp\fR, \fIforw\fR, \fIdist\fR, and
361 \fIrepl\fR to query about the disposition of a composed draft message.
362
363 .ti -1i
364 whomproc: %bindir%/whom
365 .br
366 This is the program used by \fIwhatnow\fR to determine to whom a
367 message would be sent.
368
369 .Uh "Environment Variables"
370 The operation of nmh and its commands it also controlled by the
371 presence of certain environment variables.
372
373 Many of these environment variables are used internally by the
374 \*(lqWhat now?\*(rq interface.  It's amazing all the information
375 that has to get passed via environment variables to make the
376 \*(lqWhat now?\*(rq interface look squeaky clean to the \fInmh\fR
377 user, isn't it?  The reason for all this is that the \fInmh\fR user
378 can select \fIany\fR program as the \fIwhatnowproc\fR, including
379 one of the standard shells.  As a result, it's not possible to pass
380 information via an argument list.
381
382 If the WHATNOW option was set during \fInmh\fR configuration, and
383 if this environment variable is set, then if the commands \fIrefile\fR,
384 \fIsend\fR, \fIshow\fR, or \fIwhom\fR are not given any `msgs'
385 arguments, then they will default to using the file indicated by
386 \fBmhdraft\fR.  This is useful for getting the default behavior
387 supplied by the default \fIwhatnowproc\fR.
388
389 .in +.5i
390 .ti -.5i
391 \fBMH\fR\0: With this environment variable, you can specify a profile
392 other than \fI\&.mh\(ruprofile\fR to be read by the \fInmh\fR programs
393 that you invoke.  If the value of \fBMH\fR is not absolute, (i.e., does
394 not begin with a \fB/\fR\0), it will be presumed to start from the current
395 working directory.  This is one of the very few exceptions in \fInmh\fR
396 where non-absolute pathnames are not considered relative to the user's
397 \fInmh\fR directory.
398
399 .ti -.5i
400 \fBMHCONTEXT\fR\0: With this environment variable, you can specify a
401 context other than the normal context file (as specified in
402 the \fInmh\fR profile).  As always, unless the value of \fBMHCONTEXT\fR
403 is absolute, it will be presumed to start from your \fInmh\fR directory.
404
405 .ti -.5i
406 \fBMM_CHARSET\fR\0: With this environment variable, you can specify
407 the native character set you are using.  You must be able to display
408 this character set on your terminal.
409
410 This variable is checked to see if a RFC-2047 header field should be
411 decoded (in \fIinc\fR, \fIscan\fR, \fImhl\fR).  This variable is
412 checked by \fIshow\fR to see if the showproc or showmimeproc should
413 be called, since showmimeproc will be called if a text message uses
414 a character set that doesn't match MM_CHARSET.  This variable is
415 checked by \fImhshow\fR for matches against the charset parameter
416 of text contents to decide it the text content can be displayed
417 without modifications to your terminal.  This variable is checked by
418 \fImhbuild\fR to decide what character set to specify in the charset
419 parameter of text contents containing 8bit characters.
420
421 When decoding text in such an alternate character set, \fInmh\fR
422 must be able to determine which characters are alphabetic, which
423 are control characters, etc.  For many operating systems, this
424 will require enabling the support for locales (such as setting
425 the environment variable LC_CTYPE to iso_8859_1).
426
427 .ti -.5i
428 \fBMAILDROP\fR\0: tells \fIinc\fR the default maildrop
429 .br
430 This supersedes the \*(lqMailDrop:\*(rq profile entry.
431
432 .ti -.5i
433 \fBSIGNATURE\fR\0: tells \fIsend\fR and \fIpost\fR your mail signature
434 .br
435 This supersedes the \*(lqSignature:\*(rq profile entry.
436
437 .ti -.5i
438 \fBHOME\fR\0: tells all \fInmh\fR programs your home directory
439
440 .ti -.5i
441 \fBSHELL\fR\0: tells \fIbbl\fR the default shell to run
442
443 .ti -.5i
444 \fBTERM\fR\0: tells \fInmh\fR your terminal type
445 .br
446 The environment variable \fBTERMCAP\fR is also consulted.  In particular,
447 these tell \fIscan\fR and \fImhl\fR how to clear your terminal, and how
448 many columns wide your terminal is.  They also tell \fImhl\fR how many
449 lines long your terminal screen is.
450
451 .ti -.5i
452 \fBeditalt\fR\0: the alternate message
453 .br
454 This is set by \fIdist\fR and \fIrepl\fR during edit sessions so you can
455 peruse the message being distributed or replied to.  The message is also
456 available through a link called \*(lq@\*(rq in the current directory if
457 your current working directory and the folder the message lives in are
458 on the same UNIX filesystem.
459
460 .ti -.5i
461 \fBmhdraft\fR\0: the path to the working draft
462 .br
463 This is set by \fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR
464 to tell the \fIwhatnowproc\fR which file to ask \*(lqWhat now?\*(rq
465 questions about.
466
467 .ti -.5i
468 \fBmhfolder\fR\0:
469 .br
470 This is set by \fIdist\fR, \fIforw\fR, and \fIrepl\fR,
471 if appropriate.
472
473 .ti -.5i
474 \fBmhaltmsg\fR\0:
475 .br
476 \fIdist\fR and \fIrepl\fR set \fBmhaltmsg\fR to tell the
477 \fIwhatnowproc\fR about an alternate message associated with the
478 draft (the message being distributed or replied to).
479
480 .ti -.5i
481 \fBmhdist\fR\0:
482 .br
483 \fIdist\fR sets \fBmhdist\fR to tell the \fIwhatnowproc\fR that
484 message re-distribution is occurring.
485
486 .ti -.5i
487 \fBmheditor\fR\0:
488 .br
489 This is set to tell the \fIwhatnowproc\fR the user's choice of
490 editor (unless overridden by `\-noedit').
491
492 .ti -.5i
493 \fBmhuse\fR\0:
494 .br
495 This may be set by \fIcomp\fR.
496
497 .ti -.5i
498 \fBmhmessages\fR\0:
499 .br
500 This is set by \fIdist\fR, \fIforw\fR, and \fIrepl\fR if annotations
501 are to occur.
502
503 .ti -.5i
504 \fBmhannotate\fR\0:
505 .br
506 This is set by \fIdist\fR, \fIforw\fR, and \fIrepl\fR if annotations
507 are to occur.
508
509 .ti -.5i
510 \fBmhinplace\fR\0:
511 .br
512 This is set by \fIdist\fR, \fIforw\fR, and \fIrepl\fR if annotations
513 are to occur.
514
515 .ti -.5i
516 \fBmhfolder\fR\0: the folder containing the alternate message
517 .br
518 This is set by \fIdist\fR and \fIrepl\fR during edit sessions so you
519 can peruse other messages in the current folder besides the one being
520 distributed or replied to.  The environment variable \fBmhfolder\fR is
521 also set by \fIshow\fR, \fIprev\fR, and \fInext\fR for use by \fImhl\fR.
522 .in -.5i
523
524 .Fi
525 ^$HOME/\&.mh\(ruprofile~^The user profile
526 ^or $MH~^Rather than the standard profile
527 ^<mh\-dir>/context~^The user context
528 ^or $MHCONTEXT~^Rather than the standard context
529 ^<folder>/\&.mh\(rusequences~^Public sequences for <folder>
530 .Pr
531 All
532 .Sa
533 mh(1), environ(5), mh-sequence(5)
534 .De
535 None
536 .Co
537 All
538 .Hi
539 The \fI\&.mh\(ruprofile\fR contains only static information, which
540 \fInmh\fR programs will \fBNOT\fR update.  Changes in context are
541 made to the \fIcontext\fR file kept in the users nmh \fIdirectory\fR.
542 This includes, but is not limited to: the \*(lqCurrent\-Folder\*(rq entry
543 and all private sequence information.  Public sequence information is
544 kept in each folder in the file determined by the \*(lqmh\-sequences\*(rq
545 profile entry (default is \fI\&.mh\(rusequences\fR).
546
547 The \fI\&.mh\(ruprofile\fR may override the path of the \fIcontext\fR
548 file, by specifying a \*(lqcontext\*(rq entry (this must be in
549 lower-case).  If the entry is not absolute (does not start with a
550 \fB/\fR\0), then it is interpreted relative to the user's \fInmh\fR
551 directory.  As a result, you can actually have more than one set of
552 private sequences by using different context files.
553 .Bu
554 The shell quoting conventions are not available in the \&.mh\(ruprofile.
555 Each token is separated by whitespace.
556
557 There is some question as to what kind of arguments should be placed
558 in the profile as options.  In order to provide a clear answer, recall
559 command line semantics of all \fInmh\fR programs: conflicting switches
560 (e.g., `\-header and `\-noheader') may occur more than one time on the
561 command line, with the last switch taking effect.  Other arguments, such
562 as message sequences, filenames and folders, are always remembered on
563 the invocation line and are not superseded by following arguments of
564 the same type.  Hence, it is safe to place only switches (and their
565 arguments) in the profile.
566
567 If one finds that an \fInmh\fR program is being invoked again and again
568 with the same arguments, and those arguments aren't switches, then there
569 are a few possible solutions to this problem.  The first is to create a
570 (soft) link in your \fI$HOME/bin\fR directory to the \fInmh\fR program
571 of your choice.  By giving this link a different name, you can create
572 a new entry in your profile and use an alternate set of defaults for
573 the \fInmh\fR command.  Similarly, you could create a small shell script
574 which called the \fInmh\fR program of your choice with an alternate set
575 of invocation line switches (using links and an alternate profile entry
576 is preferable to this solution).
577
578 Finally, the \fIcsh\fR user could create an alias for the command of the form:
579
580 .ti +.5i
581 alias cmd 'cmd arg1 arg2 ...'
582
583 In this way, the user can avoid lengthy type-in to the shell, and still
584 give \fInmh\fR commands safely.  (Recall that some \fInmh\fR commands
585 invoke others, and that in all cases, the profile is read, meaning that
586 aliases are disregarded beyond an initial command invocation)
587 .En