Added all of the MH sources, including RCS files, in

[mmh] / docs / historical / mh-6.8.5 / doc / mh-profile.me

.\"     This file is automatically generated.  Do not edit!
.\" @(#)$Id: mh-profile.rf,v 1.21 1996/02/08 18:06:13 jromine Exp $
.SC MH-PROFILE 5
.NA
mh-profile \- user profile customization for MH message handler
.SY
\&\fI.mh\(ruprofile\fP
.DE
Each user of \fIMH\fR is expected to have a file named \fI\&.mh\(ruprofile\fR
in his or her home directory.  This file contains a set of
user parameters used by some or all of the \fIMH\fR
family of programs.  Each entry in the file is of the format

    \fIprofile\-component\fR: \fIvalue\fR

If the text of an entry extends across several
real lines, the continuation lines are indicated by leading
spaces or tabs.
The possible profile components are exemplified below.
Only `Path:' is mandatory.
The others are optional;
some have default values if they are not present.
In the notation used below,
(profile, default) indicates whether the information is kept in the user's
\fIMH\fR profile or \fIMH\fR context,
and indicates what the default value is.

.in +1i
.ti -1i
Path: Mail
.br
Locates \fIMH\fR transactions in directory \*(lqMail\*(rq.
(profile, no default)

.ti -1i
context: context
.br
Declares the location of the \fIMH\fR context file,
see the \fBHISTORY\fR section below.
(profile, default: <mh\-dir>/context)

.ti -1i
Current\-Folder:\ inbox
.br
Keeps track of the current open folder.
(context, default: folder specified by \*(lqInbox\*(rq)

.ti -1i
Inbox:  inbox
.br
Defines the name of your inbox.
(profile, default: inbox)

.ti -1i
Previous\-Sequence:\ pseq
.br
Names the sequences which should be defined as the `msgs' or `msg'
argument given to the program.
If not present, or empty, no sequences are defined.
Otherwise,
for each name given,
the sequence is first zero'd and then each message is added to the sequence.
(profile, no default)

.ti -1i
Sequence\-Negation:\ not
.br
Defines the string which, when prefixed to a sequence name,
negates that sequence.
Hence,
\*(lqnotseen\*(rq means all those messages that are not a member of
the sequence \*(lqseen\*(rq.
(profile, no default)

.ti -1i
Unseen\-Sequence:\ unseen
.br
Names the sequences which should be defined as those messages recently
incorporated by \fIinc\fR.
\fIShow\fR knows to remove messages from this sequence once it thinks they
have been seen.
If not present, or empty, no sequences are defined.
Otherwise,
each message is added to each sequence name given.
(profile, no default)

.ti -1i
mh\-sequences:\ \&.mh\(rusequences
.br
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)

.ti -1i
atr\-\fIseq\fR\-\fIfolder\fR:\ 172\0178\-181\0212
.br
Keeps track of the private sequence called \fIseq\fR in the specified folder.
(context, no default)

.ti -1i
Editor:\ /usr/ucb/ex
.br
Defines editor to be used by 
\fIcomp\fR\0(1), \fIdist\fR\0(1), \fIforw\fR\0(1), and \fIrepl\fR\0(1).
(profile, default: /usr/bin/vi)

.ti -1i
Msg\-Protect:\ 644
.br
Defines octal protection bits for message files.
See \fIchmod\fR\0(1) for an explanation of the octal number.
(profile, default: 0644)

.ti -1i
Folder\-Protect:\ 711
.br
Defines protection bits for folder directories.
(profile, default: 0711)

.ti -1i
\fIprogram\fR:\ default switches
.br
Sets default switches to be used whenever the mh program
\fIprogram\fR is invoked.
For example, one could override the \fIEditor\fR:
profile component when replying to messages by adding a
component such as:
.br
        repl: \-editor /bin/ed
.br
(profile, no defaults)

.ti -1i
\fIlasteditor\fR\-next:\ nexteditor
.br
Names \*(lqnexteditor\*(rq to be the default editor after using \*(lqlasteditor\*(rq.
This takes effect at \*(lqWhat now?\*(rq level in
\fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR.
After editing the draft with \*(lqlasteditor\*(rq,
the default editor is set to be \*(lqnexteditor\*(rq.
If the user types \*(lqedit\*(rq without any arguments to \*(lqWhat now?\*(rq,
then \*(lqnexteditor\*(rq is used.
(profile, no default)

.ti -1i
bboards: system
.br
Tells \fIbbc\fR which BBoards you are interested in.
(profile, default: system)

.ti -1i
Folder\-Stack: \fIfolders\fR
.br
The contents of the folder-stack for the \fIfolder\fR command.
(context, no default)

.ti -1i
mhe:
.br
If present, tells \fIinc\fR to compose an \fIMHE\fR auditfile in addition to
its other tasks.
\fIMHE\fR is Brian Reid's \fIEmacs\fR front-end for \fIMH\fR.
An early version is supplied with the \fImh.6\fR distribution.
(profile, no default)

.ti -1i
Alternate\-Mailboxes: mh@uci\-750a, bug-mh*
.br
Tells \fIrepl\fR and \fIscan\fR which addresses are really yours.
In this way, \fIrepl\fR knows which addresses should be included in the reply,
and \fIscan\fR knows if the message really originated from you.
Addresses must be separated by a comma,
and the hostnames listed should be the \*(lqofficial\*(rq hostnames for the
mailboxes you indicate,
as local nicknames for hosts are not replaced with their official site names.
For each address,
if a host is not given,
then that address on any host is considered to be you.
In addition,
an asterisk (`*') may appear at either or both ends of the mailbox and host
to indicate wild-card matching.
(profile, default: your user-id)

.ti -1i
Aliasfile: aliases other-alias
.br
Indicates aliases files for \fIali\fR, \fIwhom\fR, and \fIsend\fR.
This may be used instead of the `\-alias file' switch.
(profile, no default)

.ti -1i
Draft\-Folder: drafts
.br
Indicates a default draft folder for \fIcomp\fR, \fIdist\fR, \fIforw\fR,
and \fIrepl\fR.
(profile, no default)

.ti -1i
digest\-issue\-\fIlist\fR:\ 1
.br
Tells \fIforw\fR the last issue of the last volume sent for the digest
\fIlist\fR.
(context, no default)

.ti -1i
digest\-volume\-\fIlist\fR:\ 1
.br
Tells \fIforw\fR the last volume sent for the digest \fIlist\fR.
(context, no default)

.ti -1i
MailDrop: .mail
.br
Tells \fIinc\fR your maildrop, if different from the default.
This is superceded by the \fBMAILDROP\fR envariable.
(profile, default: /var/spool/mail/$USER)

.ti -1i
Signature: RAND MH System (agent: Marshall Rose)
.br
Tells \fIsend\fR your mail signature.
This is superceded by the \fBSIGNATURE\fR envariable.
If \fBSIGNATURE\fR is not set and this profile entry is not present,
the \*(lqgcos\*(rq field of the \fI/etc/passwd\fP file will be used;
otherwise,
on hosts where \fIMH\fR was configured with the UCI option,
the file $HOME/.signature is consulted.
Your signature will be added to the address \fIsend\fP
puts in the \*(lqFrom:\*(rq header;
do not include an address in the signature text.
(profile, no default)
.in -1i

The following profile elements are used whenever an \fIMH\fR program
invokes some other program such as \fImore\fR\0(1).
The \fI\&.mh\(ruprofile\fR can be used to select alternate
programs if the user wishes.  The default values are given in
the examples.

.nf
.in +.5i
.ta \w'whatnowproc:  'u
^fileproc:~^/opt/mh-6.8.5/bin/refile
^incproc:~^/opt/mh-6.8.5/bin/inc
^installproc:~^/opt/mh-6.8.5/lib/install\-mh
^lproc:~^/usr/ucb/more
^mailproc:~^/opt/mh-6.8.5/bin/mhmail
^mhlproc:~^/opt/mh-6.8.5/lib/mhl
^moreproc:~^/usr/ucb/more
^mshproc:~^/opt/mh-6.8.5/bin/msh
^packproc:~^/opt/mh-6.8.5/bin/packf
^postproc:~^/opt/mh-6.8.5/lib/post
^rmmproc:~^none
^rmfproc:~^/opt/mh-6.8.5/bin/rmf
^sendproc:~^/opt/mh-6.8.5/bin/send
^showproc:~^/usr/ucb/more
^whatnowproc:~^/opt/mh-6.8.5/bin/whatnow
^whomproc:~^/opt/mh-6.8.5/bin/whom
.re
.in -.5i
.fi

If you define the envariable \fBMH\fR,
you can specify a profile other than \fI\&.mh\(ruprofile\fR to be read
by the \fIMH\fR programs that you invoke.
If the value of \fBMH\fR is not absolute,
(i.e., does not begin with a \fB/\fR\0),
it will be presumed to start from the current working directory.
This is one of the very few exceptions in \fIMH\fR where non-absolute
pathnames are not considered relative to the user's \fIMH\fR directory.

Similarly,
if you define the envariable \fBMHCONTEXT\fR,
you can specify a context other than the normal context file
(as specified in the \fIMH\fR profile).
As always,
unless the value of \fBMHCONTEXT\fR is absolute,
it will be presumed to start from your \fIMH\fR directory.

\fIMH\fR programs also support other envariables:

.in +.5i
.ti -.5i
\fBMAILDROP\fR\0: tells \fIinc\fR the default maildrop
.br
This supercedes the \*(lqMailDrop:\*(rq profile entry.

.ti -.5i
\fBSIGNATURE\fR\0: tells \fIsend\fR and \fIpost\fR your mail signature
.br
This supercedes the \*(lqSignature:\*(rq profile entry.

.ti -.5i
\fBHOME\fR\0: tells all \fIMH\fR programs your home directory

.ti -.5i
\fBSHELL\fR\0: tells \fIbbl\fR the default shell to run

.ti -.5i
\fBTERM\fR\0: tells \fIMH\fR your terminal type
.br
The \fBTERMCAP\fR envariable is also consulted.
In particular,
these tell \fIscan\fR and \fImhl\fR how to clear your terminal,
and how many columns wide your terminal is.
They also tell \fImhl\fR how many lines long your terminal screen is.

.ti -.5i
\fBeditalt\fR\0: the alternate message
.br
This is set by \fIdist\fR and \fIrepl\fR during edit sessions
so you can peruse the message being distributed or replied to.
The message is also available 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.

.ti -.5i
\fBmhdraft\fR\0: the path to the working draft
.br
This is set by \fIcomp\fR, \fIdist\fR, \fIforw\fR, and \fIrepl\fR
to tell the \fIwhatnowproc\fR which file to ask \*(lqWhat now?\*(rq questions
about.
In addition,
\fIdist\fR, \fIforw\fR, and \fIrepl\fR set \fBmhfolder\fR if appropriate.
Further,
\fIdist\fR and \fIrepl\fR set \fBmhaltmsg\fR to tell the
\fIwhatnowproc\fR about an alternate message associated with the draft
(the message being distributed or replied to),
and
\fIdist\fR sets \fBmhdist\fR to tell the \fIwhatnowproc\fR that
message re-distribution is occurring.
Also,
\fBmheditor\fR is set to tell the \fIwhatnowproc\fR the user's choice of
editor (unless overridden by `\-noedit').
Similarly,
\fBmhuse\fR may be set by \fIcomp\fR.
Finally,
\fBmhmessages\fR is set by \fIdist\fR, \fIforw\fR, and \fIrepl\fR
if annotations are to occur
(along with \fBmhannotate\fR, and \fBmhinplace\fR).
It's amazing all the information that has to get passed via envariables to
make the \*(lqWhat now?\*(rq interface look squeaky clean to the \fIMH\fR
user, isn't it?
The reason for all this
is that the \fIMH\fR user can select \fIany\fR program as the
\fIwhatnowproc\fR, including one of the standard shells.
As a result, it's not possible to pass information via an argument list.
.br
If the WHATNOW option was set during \fIMH\fR configuration
(type `\-help' to an \fIMH\fR command to find out),
and if this envariable is set,
if the commands \fIrefile\fR, \fIsend\fR, \fIshow\fR, or \fIwhom\fR
are not given any `msgs' arguments,
then they will default to using the file indicated by \fBmhdraft\fR.
This is useful for getting the default behavior supplied by the default
\fIwhatnowproc\fR.

.ti -.5i
\fBmhfolder\fR\0: the folder containing the alternate message
.br
This is set by \fIdist\fR and \fIrepl\fR during edit sessions
so you can peruse other messages in the current folder
besides the one being distributed or replied to.
The \fBmhfolder\fR envariable is also
set by \fIshow\fR, \fIprev\fR, and \fInext\fR
for use by \fImhl\fR.

.ti -.5i
\fBMHBBRC\fR\0: 
.br
If you define the envariable \fBMHBBRC\fR,
you can specify a BBoards information file other than \fI\&.bbrc\fR to be
read by \fIbbc\fR.
If the value of \fBMHBBRC\fR is not absolute,
(i.e., does not begin with a \fB/\fR\0),
it will be presumed to start from the current working directory.

.ti -.5i
\fBMHFD\fR\0: 
.br
If the OVERHEAD option was set during \fIMH\fR configuration
(type `\-help' to an \fIMH\fR command to find out),
then if this envariable is set,
\fIMH\fR considers it to be the number of a file descriptor which is opened,
read-only to the \fIMH\fR profile.
Similarly,
if the envariable \fBMHCONTEXTFD\fR is set,
this is the number of a file descriptor which is opened read-only
to the \fIMH\fR context.
This feature of \fIMH\fR is experimental,
and is used to examine possible speed improvements for \fIMH\fR startup.
Note that these envariables must be set and non-empty to enable this feature.
However,
if OVERHEAD is enabled during \fIMH\fR configuration,
then when \fIMH\fR programs call other \fIMH\fR programs,
this scheme is used.
These file descriptors are not closed throughout the execution of the
\fIMH\fR program,
so children may take advantage of this.
This approach is thought to be completely safe and does result in some
performance enhancements.
.in -.5i

.Fi
^$HOME/\&.mh\(ruprofile~^The user profile
^or $MH~^Rather than the standard profile
^<mh\-dir>/context~^The user context
^or $CONTEXT~^Rather than the standard context
^<folder>/\&.mh\(rusequences~^Public sequences for <folder>
.Pr
All
.Sa
mh(1), environ(5), mh-sequence(5)
.De
None
.Co
All
.Hi
In previous versions of \fIMH\fR,
the current-message value of a writable folder was kept in a file
called \*(lqcur\*(rq in the folder itself.
In \fImh.3\fR,
the \fI\&.mh\(ruprofile\fR contained the current-message values for
all folders, regardless of their writability.

In all versions of \fIMH\fR since \fImh.4\fR,
the \fI\&.mh\(ruprofile\fR contains only static information,
which \fIMH\fR programs will \fBNOT\fR update.
Changes in context are made to the \fIcontext\fR file kept in the users MH
\fIdirectory\fR.
This includes, but is not limited to:
the \*(lqCurrent\-Folder\*(rq entry and all private sequence information.
Public sequence information is kept in a file called \fI\&.mh\(rusequences\fR
in each folder.

To convert from the format used in releases of \fIMH\fR prior
to the format used in the \fImh.4\fR release,
\fIinstall\-mh\fR should be invoked with the `\-compat' switch.
This generally happens automatically on \fIMH\fR systems generated with the
\*(lqCOMPAT\*(rq option during \fIMH\fR configuration.

The \fI\&.mh\(ruprofile\fR may override the path of the \fIcontext\fR file,
by specifying a \*(lqcontext\*(rq entry (this must be in lower-case).
If the entry is not absolute (does not start with a \fB/\fR\0),
then it is interpreted relative to the user's \fIMH\fR directory.
As a result,
you can actually have more than one set of private sequences by using
different context files.
.Bu
The shell quoting conventions are not available in the \&.mh\(ruprofile.
Each token is separated by whitespace.

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 command line semantics of all \fIMH\fR programs:
conflicting switches (e.g., `\-header and `\-noheader')
may occur more than one time on the command line,
with the last switch taking effect.
Other arguments,
such as message sequences, filenames and folders,
are always remembered on the invocation line and are not superseded by 
following arguments of the same type.
Hence, it is safe to place only switches (and their arguments)
in the profile.

If one finds that an \fIMH\fR
program is being invoked again and again with the same arguments,
and those arguments aren't switches,
then there are a few possible solutions to this problem.
The first is to create a (soft) link in your \fI$HOME/bin\fR directory
to the \fIMH\fR program of your choice.
By giving this link a different name,
you can create a new entry in your profile
and use an alternate set of defaults for the \fIMH\fR command.
Similarly, you could create a small shell script which called the
\fIMH\fR program of your choice with an alternate set of invocation
line switches (using links and an alternate profile entry is preferable
to this solution).

Finally, the \fIcsh\fR user could create an alias for the command of the form:

.ti +.5i
alias cmd 'cmd arg1 arg2 ...'

In this way, the user can avoid lengthy type-in to the shell,
and still give \fIMH\fR commands safely.  (Recall that some \fIMH\fR
commands invoke others, and that in all cases, the profile is read,
meaning that aliases are disregarded beyond an initial command invocation)
.En