SIGNATURE/Local-Mailbox are not used by post, but just by front
[mmh] / man / inc.man
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH INC %manext1% "%nmhdate%" MH.6.8 [%nmhversion%] XXX
5 .SH NAME
6 inc \- incorporate new mail
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B inc
11 .RI [ +folder ]
12 .RB [ \-audit
13 .IR audit\-file ]
14 .RB [ \-noaudit ]
15 .RB [ \-changecur " | " \-nochangecur ]
16 .RB [ \-form
17 .IR formfile ]
18 .RB [ \-format
19 .IR string ]
20 .RB [ \-file
21 .IR name ]
22 .RB [ \-silent " | " \-nosilent ]
23 .RB [ \-truncate " | " \-notruncate ]
24 .RB [ \-width
25 .IR columns ]
26 .RB [ \-host
27 .IR hostname ]
28 .RB [ \-user
29 .IR username ]
30 .RB [ \-pack
31 .IR file ]
32 .RB [ \-nopack ]
33 .RB [ \-proxy
34 .IR command ]
35 .RB [ \-sasl ]
36 .RB [ \-saslmech
37 .IR mechanism ]
38 .RB [ \-snoop ]
39 .RB [ \-version ]
40 .RB [ \-help ]
41 .ad
42 .SH DESCRIPTION
43 .B Inc
44 incorporates mail from the user's incoming mail drop into
45 an
46 .B nmh
47 folder.
48 If the mail drop is a file, it can be in
49 .B mbox
50 or
51 .B MMDF
52 format.
53 If the mail drop is a directory it will considered to be a
54 .B Maildir
55 format mail drop.
56 .PP
57 You may specify which folder to use with
58 .IR +folder .
59 If no folder is specified, then
60 .B inc
61 will use either the folder given by a (non\-empty)
62 .RI \*(lq Inbox \*(rq
63 entry in the user's profile, or the folder named
64 .RI \*(lq inbox \*(rq.
65 If the specified (or default) folder doesn't
66 exist, the user will be queried prior to its creation.
67 .PP
68 When the new messages are incorporated into the folder, they are assigned
69 numbers starting with the next highest number for the folder.  As the
70 messages are processed, a
71 .B scan
72 listing of the new mail is produced.
73 .PP
74 If the user's profile contains a
75 .RI \*(lq "Msg\-Protect: nnn" \*(rq
76 entry, it
77 will be used as the protection on the newly created messages, otherwise
78 the
79 .B nmh
80 default of 0644 will be used.  For all subsequent operations
81 on these messages, this initially assigned protection will be preserved.
82 .PP
83 If the switch
84 .B \-audit
85 .I audit\-file
86 is specified (usually as a default
87 switch in the profile), then
88 .B inc
89 will append a header line and a
90 line per message to the end of the specified audit\-file with the format:
91 .PP
92 .RS 5
93 .nf
94 <<inc>> date
95 <scan line for first message>
96 <scan line for second message>
97 <etc.>
98 .fi
99 .RE
100 .PP
101 This is useful for keeping track of volume and source of incoming mail.
102 Eventually,
103 .BR repl ,
104 .BR forw ,
105 .BR comp ,
106 and
107 .B dist
108 may also produce audits to this (or another) file, perhaps with
109 .RI \*(lq Message\-Id \*(rq
110 information to keep an exact correspondence
111 history.
112 .RI \*(lq Audit\-file \*(rq
113 will be in the user's nmh directory unless a full path is specified.
114 .PP
115 .B Inc
116 will incorporate even improperly formatted messages into the
117 user's nmh folder, inserting a blank line prior to the offending component
118 and printing a comment identifying the bad message.
119 .PP
120 In all cases, the user's mail drop will be zeroed, unless the
121 .B \-notruncate
122 switch is given.
123 .PP
124 If the profile entry
125 .RI \*(lq Unseen\-Sequence \*(rq
126 is present and non\-empty, then
127 .B inc
128 will add each of the newly incorporated messages to
129 each sequence named by the profile entry.
130 .B Inc
131 will not zero each sequence prior to adding messages.
132 .PP
133 The interpretation of the
134 .B \-form
135 .IR formatfile ,
136 .B \-format
137 .IR string ,
138 and
139 .B \-width
140 .I columns
141 switches is the same as in
142 .BR scan .
143 .PP
144 By using the
145 .B \-file
146 .I name
147 switch, one can direct
148 .B inc
149 to incorporate messages from a file other than the user's maildrop.
150 Note that the name file will NOT be zeroed, unless the
151 .B \-truncate
152 switch is given.
153 .PP
154 If the environment variable
155 .B $MAILDROP
156 is set, then
157 .B inc
158 uses it as the location of the user's maildrop instead of the default
159 (the
160 .B -file
161 .I name
162 switch still overrides this, however).  If this
163 environment variable is not set, then
164 .B inc
165 will consult the profile entry
166 .RI \*(lq MailDrop \*(rq
167 for this information.  If the value found is
168 not absolute, then it is interpreted relative to the user's
169 .B nmh
170 directory.  If the value is not found, then
171 .B inc
172 will look in the standard system location for the user's maildrop.
173 .PP
174 The
175 .B \-silent
176 switch directs
177 .B inc
178 to be quiet and not ask any questions at all.  This is useful for putting
179 .B inc
180 in the background and going on to other things.
181 .PP
182 .SS "Using POP"
183 .B inc
184 will normally check local mail drops for mail, as covered above.  But
185 if the option
186 .RI \*(lq pophost \*(rq
187 is set in
188 .RI \*(lq mts.conf \*(rq,
189 or if the
190 .B \-host
191 .I hostname
192 switch is given, or if the
193 .B $MAILHOST
194 environment variable is set, then
195 .B inc
196 will query this POP service host for mail to incorporate.  If
197 .B $MAILHOST
198 is set and
199 .B \-host
200 is specified as well, the commandline switch will override
201 the environment variable.
202 .PP
203 The default is for
204 .B inc
205 to assume that your account name on
206 the POP server is the same as your current username.  To specify
207 a different username, use the
208 .B \-user
209 .I username
210 switch.
211 .PP
212 When using POP, you will normally need to type the password for
213 your account on the POP server, in order to retrieve your messages.
214 It is possible to automate this process by creating a
215 .RI \*(lq .netrc \*(rq
216 file containing your login account information for this POP server.
217 For each POP server, this file should have a line of the following
218 form.  Replace the words
219 .IR mypopserver ,
220 .IR mylogin ,
221 and
222 .I mypassword
223 with your own account information.
224 .PP
225 .RS 5
226 .B machine
227 .I mypopserver
228 .B login
229 .I mylogin
230 .B password
231 .I mypassword
232 .RE
233 .PP
234 This
235 .RI \*(lq .netrc \*(rq
236 file should be owned and readable only by you.
237 .PP
238 If passed the
239 .B \-proxy
240 .I command
241 switch,
242 .B inc
243 will use the specified command to establish the connection to the POP
244 server. The string
245 .IR %h
246 in the command will be substituted by the hostname to connect to.
247 .PP
248 If
249 .B inc
250 uses POP, then the
251 .B \-pack
252 .I file
253 switch is considered. If given, then
254 .B inc
255 simply uses the POP to
256 .B packf
257 the user's maildrop from the POP service host to the named file.  This switch
258 is provided for those users who prefer to use
259 .B msh
260 to read their maildrops.
261 .PP
262 For debugging purposes, you may give the switch
263 .BR \-snoop ,
264 which will allow you to watch the POP transaction take place
265 between you and the POP server.
266 .PP
267 If
268 .B nmh
269 has been compiled with SASL support, the
270 .B \-sasl
271 switch will enable
272 the use of SASL authentication.  Depending on the SASL mechanism used, this
273 may require an additional password prompt from the user (but the
274 .RI \*(lq .netrc \*(rq
275 file can be used to store this password).  The
276 .B \-saslmech
277 switch can be used to select a particular SASL mechanism.
278 .PP
279 If SASL authentication is successful,
280 .B inc
281 will attempt to negotiate a security layer for session encryption.
282 Encrypted traffic is labelled with `(encrypted)' and `(decrypted)'
283 when viewing the POP transaction with the
284 .B \-snoop
285 switch.
286
287 .SH FILES
288 .fc ^ ~
289 .nf
290 .ta \w'%etcdir%/ExtraBigFileName  'u
291 ^$HOME/\&.mh\(ruprofile~^The user profile
292 ^%etcdir%/mts.conf~^nmh mts configuration file
293 ^%mailspool%/$USER~^Location of mail drop
294 .fi
295
296 .SH "PROFILE COMPONENTS"
297 .fc ^ ~
298 .nf
299 .ta 2.4i
300 .ta \w'ExtraBigProfileName  'u
301 ^Path:~^To determine the user's nmh directory
302 ^Alternate\-Mailboxes:~^To determine the user's mailboxes
303 ^Inbox:~^To determine the inbox, default \*(lqinbox\*(rq
304 ^Folder\-Protect:~^To set mode when creating a new folder
305 ^Msg\-Protect:~^To set mode when creating a new message and audit\-file
306 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
307 .fi
308
309 .SH "SEE ALSO"
310 mhmail(1), scan(1), mh\-mail(5), post(8)
311
312 .SH DEFAULTS
313 .nf
314 .RB ` +folder "' defaulted by \*(lqInbox\*(rq above"
315 .RB ` \-noaudit '
316 .RB ` \-changecur '
317 .RB ` \-format "' defaulted as described above"
318 .RB ` \-nosilent '
319 .RB ` \-truncate "' if `" \-file " name' not given, `" \-notruncate "' otherwise"
320 .RB ` \-width "' defaulted to the width of the terminal"
321 .RB ` \-nopack '
322 .fi
323
324 .SH CONTEXT
325 The folder into which messages are being incorporated will become the
326 current folder.  The first message incorporated will become the current
327 message, unless the
328 .B \-nochangecur
329 option is specified.  This leaves the context ready for a
330 .B show
331 of the first new message.
332
333 .SH BUGS
334 The argument to the
335 .B \-format
336 switch must be interpreted as a single
337 token by the shell that invokes
338 .BR inc .
339 Therefore, one must usually place the argument to this switch inside
340 quotes.