--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/conf/doc/inc.rf	Mon Apr 18 23:46:02 2005 +0900
@@ -0,0 +1,211 @@
+.\"	@(MHWARNING)
+.\" @(#)$Id$
+.SC INC 1
+.NA
+inc \- incorporate new mail
+.SY
+inc
+\%[+folder]
+\%[\-audit\ audit\-file] \%[\-noaudit]
+\%[\-changecur] \%[\-nochangecur]
+@BEGIN: TMA
+\%[\-decrypt] \%[\-nodecrypt] 
+@END: TMA
+\%[\-form\ formatfile]
+\%[\-format\ string]
+\%[\-file\ name]
+\%[\-silent] \%[\-nosilent]
+\%[\-truncate] \%[\-notruncate]
+\%[\-width\ columns]
+@BEGIN: MF
+\%[\-uucp] \%[\-nouucp]
+@END: MF
+@BEGIN: POP
+\%[\-host\ host] \%[\-user\ user]
+\%[\-apop] \%[\-noapop]
+\%[\-rpop] \%[\-norpop]
+\%[\-pack\ file] \%[\-nopack]
+@END: POP
+\%[\-help]
+.DE
+\fIInc\fR incorporates mail from the user's incoming mail drop
+into an \fIMH\fR folder.
+If `+folder' isn't specified,
+a folder in the user's \fIMH\fR directory will be used, either that
+specified by the \*(lqInbox:\*(rq entry in the user's profile, or
+the folder named \*(lqinbox\*(rq.
+The
+new messages being incorporated are assigned numbers starting
+with the next highest number in the folder.
+If the specified (or default) folder doesn't exist,
+the user will be queried prior to its creation.
+As the messages are processed,
+a \fIscan\fR listing of the new mail is produced.
+
+If the user's profile contains a \*(lqMsg\-Protect: nnn\*(rq entry, it
+will be used as the protection on the newly created messages,
+otherwise the \fIMH\fR default of 0644 will be used.
+During all operations on messages,
+this initially assigned protection will
+be preserved for each message, so \fIchmod\fR(1) may be used to set a
+protection on an individual message, and its protection will be
+preserved thereafter.
+
+If the switch `\-audit\ audit\-file' is specified (usually as a
+default switch in the profile), then \fIinc\fR will append a header
+line and a line per message to the end of the specified
+audit\-file with the format:
+
+.nf
+.ti 1i
+\*(<<inc\*(>> date
+.ti 1.5i
+<scan line for first message>
+.ti 1.5i
+<scan line for second message>
+.ti 2.5i
+<etc.>
+.fi
+
+This is useful for keeping track of volume and source of incoming
+mail.
+Eventually, \fIrepl\fR, \fIforw\fR, \fIcomp\fR, and \fIdist\fR may also
+produce audits to this (or another) file, perhaps with
+\*(lqMessage\-Id:\*(rq information to keep an exact correspondence history.
+\*(lqAudit\-file\*(rq will be in the user's MH directory unless a full
+path is specified.
+
+\fIInc\fR will incorporate even improperly formatted messages into the
+user's MH folder, inserting a blank line prior to the offending
+component and printing a comment identifying the bad message.
+
+In all cases, the user's mail drop will be zeroed,
+unless the `\-notruncate' switch is given.
+
+If the profile entry \*(lqUnseen\-Sequence\*(rq is present and non\-empty,
+then \fIinc\fR will add each of the newly incorporated messages to each
+sequence named by the profile entry.
+This is similar to the \*(lqPrevious\-Sequence\*(rq profile entry supported
+by all \fIMH\fR commands which take `msgs' or `msg' arguments.
+Note that \fIinc\fR will not zero each sequence prior to adding messages.
+
+The interpretation of the `\-form\ formatfile', `\-format\ string',
+and `\-width\ columns' switches is the same as in \fIscan\fR\0(1).
+@BEGIN: MF
+
+If the `\-uucp' switch is given, \fIUUCP\fR mail will be \fRinc\fRorporated
+as well.  This option will work only on those sites that optionally
+use \*(lqmail filtering\*(rq software.
+@END: MF
+
+By using the `\-file\ name' switch, one can direct \fIinc\fR to incorporate
+messages from a file other than the user's maildrop.
+Note that the name file will NOT be zeroed,
+unless the `\-truncate' switch is given.
+
+If the envariable \fB$MAILDROP\fR is set,
+then \fIinc\fR uses it as the location of the user's maildrop instead of the
+default (the `-file\ name' switch still overrides this, however).
+If this envariable is not set,
+then \fIinc\fR will consult the profile entry \*(lqMailDrop\*(rq for this
+information.
+If the value found is not absolute,
+then it is interpreted relative to the user's \fIMH\fR directory.
+If the value is not found,
+then \fIinc\fR will look in the standard system location for the user's
+maildrop.
+
+The `\-silent' switch directs \fIinc\fR to be quiet and not ask any questions
+at all.
+This is useful for putting \fIinc\fR in the background and going on to other
+things.
+@BEGIN: POP
+
+If the local host is configured as a POP client,
+or if the `\-host\ host' switch is given,
+then \fIinc\fR will query the POP service host as to the status of mail
+waiting.
+If the `\-user\ user' switch is not given,
+then the current username is used.
+Normally,
+\fIinc\fR will prompt for a password to use.
+However,
+if the `\-apop' switch is given,
+\fIinc\fR will generate authentication credentials to provide
+for origin authentication and replay protection,
+but which do not involve sending a password in the clear over the network.
+Otherwise,
+if the `\-rpop' switch is given,
+then \fIinc\fR will try to use a \*(lqtrusted\*(rq connection
+(ala the BSD r-commands).
+
+If \fIinc\fR uses POP,
+then the `\-pack\ file' switch is considered.
+If given,
+then \fIinc\fR simply uses the POP to \fIpackf\fR\0(1) the user's maildrop
+from the POP service host to the named file.
+This switch is provided for those users who prefer to use \fImsh\fR to
+read their maildrops.
+@END: POP
+.Fi
+^$HOME/\&.mh\(ruprofile~^The user profile
+^@(MHETCPATH)/mtstailor~^tailor file
+^@(MHDROPLOC)~^Location of mail drop
+.Pr
+^Path:~^To determine the user's MH directory
+.Ps
+^Alternate\-Mailboxes:~^To determine the user's mailboxes
+.Ps
+^Inbox:~^To determine the inbox, default \*(lqinbox\*(rq
+.Ps
+^Folder\-Protect:~^To set mode when creating a new folder
+.Ps
+^Msg\-Protect:~^To set mode when creating a new message and audit\-file
+.Ps
+^Unseen\-Sequence:~^To name sequences denoting unseen messages
+.Sa
+@BEGIN: POP
+\fIPost Office Protocol - version 3\fR (aka RFC\-1081),
+.br
+@END: POP
+mhmail(1), scan(1), mh\-mail(5), post(8)
+.De
+`+folder' defaulted by \*(lqInbox\*(rq above
+.Ds
+`\-noaudit'
+.Ds
+`\-changecur'
+@BEGIN: TMA
+`\-decrypt'
+@END: TMA
+.Ds
+`\-format' defaulted as described above
+.Ds
+`\-nosilent'
+.Ds
+`\-truncate' if `\-file\ name' not given, `\-notruncate' otherwise
+.Ds
+`\-width' defaulted to the width of the terminal
+@BEGIN: MF
+.Ds
+`\-uucp'
+@END: MF
+@BEGIN: POP
+.Ds
+`\-nopack'
+.Ds
+`\-rpop'
+@END: POP
+.Co
+The folder into which messages are being incorporated will become the
+current folder.
+The first message incorporated will become the current message,
+unless the `\-nochangecur' option is specified.
+This leaves the context ready for a \fIshow\fR
+of the first new message.
+.Bu
+The argument to the `\-format' switch must be interpreted as a single token
+by the shell that invokes \fIinc\fR.
+Therefore,
+one must usually place the argument to this switch inside double\-quotes.
+.En