git.marmaro.de Git - mmh/blob - man/inc.man

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