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

   1 .\"
   2 .\" %nmhwarning%
   3 .\"
   4 .TH SCAN %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
   5 .SH NAME
   6 scan \- produce a one line per message scan listing
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B scan
  11 .RI [ +folder ]
  12 .RI [ msgs ]
  13 .RB [ \-clear " | " \-noclear ]
  14 .RB [ \-form
  15 .IR formatfile ]
  16 .RB [ \-format
  17 .IR string ]
  18 .RB [ \-header " | " \-noheader ]
  19 .RB [ \-width
  20 .IR columns ]
  21 .RB [ \-reverse " | " \-noreverse ]
  22 .RB [ \-file
  23 .IR filename ]
  24 .RB [ \-version ]
  25 .RB [ \-help ]
  26 .ad
  27 .SH DESCRIPTION
  28 .B Scan
  29 produces a one\-line\-per\-message listing of the specified
  30 folder or messages.  Each
  31 .B scan
  32 line contains the message number
  33 (name), the date, the \*(lqFrom:\*(rq field, the \*(lqSubject\*(rq field,
  34 and, if room allows, some of the body of the message.  For example:
  35 .PP
  36 .RS 5
  37 .nf
  38 .ta \w'15+- 'u +\w'07/\|05x 'u +\w'Dcrocker  'u
  39 15+     10/\|05 crocker nned\0\0<<Last week I asked some of
  40 16\-    10/\|05 crocker message id format\0\0\<<I recommend
  41 18      10/\|06 brien   Re: Exit status from mkdir
  42 19      10/\|07*brien   \*(lqscan\*(rq listing format in nmh
  43 .fi
  44 .RE
  45 .PP
  46 The `+' on message 15 indicates that it is the current message.
  47 .PP
  48 The `\-' on message 16 indicates that it has been replied to, as indicated
  49 by a \*(lqReplied:\*(rq component (produced by the
  50 .B \-annotate
  51 switch
  52 to the
  53 .B repl
  54 command).
  55 .PP
  56 The `*' on message 19 indicates that no \*(lqDate:\*(rq header was
  57 present.  The time of last modification of the message is given instead.
  58 .PP
  59 If there is sufficient room left on the
  60 .B scan
  61 line after the
  62 subject, the line will be filled with text from the body, preceded by
  63 \*(lq<<\*(rq, and terminated by \*(lq>>\*(rq if the body is sufficiently short.
  64 .B Scan
  65 actually reads each of the specified messages and parses them to extract
  66 the desired fields.  During parsing, appropriate error messages will be
  67 produced if there are format errors in any of the messages.
  68 .PP
  69 By default,
  70 .B scan
  71 will decode RFC-2047 (MIME) encoding in
  72 these scan listings.
  73 .B Scan
  74 will only decode these fields if your
  75 terminal can natively display the character set used in the encoding.
  76 You should set the MM_CHARSET environment variable to your native
  77 character set, if it is not US-ASCII.  See the mh-profile(5) man
  78 page for details about this environment variable.
  79 .PP
  80 The switch
  81 .BR \-reverse ,
  82 makes
  83 .B scan
  84 list the messages in reverse
  85 order.
  86 .PP
  87 The
  88 .B \-file
  89 .I filename
  90 switch allows the user to obtain a
  91 .B scan
  92 listing of a maildrop file as produced by
  93 .BR packf .
  94 This listing
  95 includes every message in the file (you can't scan individual messages).
  96 The switch
  97 .B \-reverse
  98 is ignored with this option.
  99 .PP
 100 The switch
 101 .B \-width
 102 .I columns
 103 may be used to specify the width of
 104 the scan line.  The default is to use the width of the terminal.
 105 .PP
 106 The
 107 .B \-header
 108 switch produces a header line prior to the
 109 .B scan
 110 listing.  Currently, the name of the folder and the current date and
 111 time are output (see the
 112 .B HISTORY
 113 section for more information).
 114 .PP
 115 If the
 116 .B \-clear
 117 switch is used and
 118 .BR scan 's
 119 output is directed
 120 to a terminal, then
 121 .B scan
 122 will consult the environment variables
 123 .B $TERM
 124 and
 125 .B $TERMCAP
 126 to determine your terminal type in order
 127 to find out how to clear the screen prior to exiting.  If the
 128 .B \-clear
 129 switch is used and
 130 .BR scan 's
 131 output is not directed to a terminal
 132 (e.g., a pipe or a file), then
 133 .B scan
 134 will send a formfeed prior
 135 to exiting.
 136 .PP
 137 For example, the command:
 138 .PP
 139 .RS 5
 140 (scan \-clear \-header; show all \-show pr \-f) | lpr
 141 .RE
 142 .PP
 143 produces a scan listing of the current folder, followed by a formfeed,
 144 followed by a formatted listing of all messages in the folder, one
 145 per page.  Omitting
 146 .RB \*(lq "\-show\ pr\ \-f" \*(rq
 147 will cause the messages to be
 148 concatenated, separated by a one\-line header and two blank lines.
 149 .PP
 150 To override the output format used by
 151 .BR scan ,
 152 the
 153 .B \-format
 154 .I string
 155 or
 156 .B \-form
 157 .I file
 158 switches are used.  This permits individual fields of
 159 the scan listing to be extracted with ease.  The string is simply a format
 160 string and the file is simply a format file.  See
 161 .BR mh\-format (5)
 162 for the details.
 163 .PP
 164 In addition to the standard
 165 .BR mh\-format (5)
 166 escapes,
 167 .B scan
 168 also recognizes the following additional
 169 .I component
 170 escapes:
 171 .PP
 172 .RS 5
 173 .nf
 174 .ta \w'Dtimenow  'u +\w'Returns  'u
 175 .I Escape       Returns Description
 176 body    string  the (compressed) first part of the body
 177 dtimenow        date    the current date
 178 folder  string  the name of the current folder
 179 .fi
 180 .RE
 181 .PP
 182 If no date header is present in the message, the
 183 .I function
 184 escapes
 185 which operate on
 186 .RB { date }
 187 will return values for the date of last
 188 modification of the message file itself.  This feature is handy for
 189 scanning a draft folder, as message drafts usually aren't allowed
 190 to have dates in them.
 191 .PP
 192 .B scan
 193 will update the
 194 .B mmh
 195 context prior to starting the listing,
 196 so interrupting a long
 197 .B scan
 198 listing preserves the new context.
 199 .B nmh
 200 purists hate this idea.
 201
 202 .SH FILES
 203 .fc ^ ~
 204 .nf
 205 .ta \w'%etcdir%/ExtraBigFileName  'u
 206 ^$HOME/.mmh/profile~^The user profile
 207 .fi
 208
 209 .SH "PROFILE COMPONENTS"
 210 .fc ^ ~
 211 .nf
 212 .ta 2.4i
 213 .ta \w'ExtraBigProfileName  'u
 214 ^Path:~^To determine the user's mail storage
 215 ^Alternate\-Mailboxes:~^To determine the user's mailboxes
 216 ^Current\-Folder:~^To find the default current folder
 217 .fi
 218
 219 .SH "SEE ALSO"
 220 inc(1), pick(1), show(1), mh\-format(5)
 221
 222 .SH DEFAULTS
 223 .nf
 224 .RB ` +folder "' defaults to the current folder"
 225 .RB ` msgs "' defaults to all"
 226 .RB ` \-format "' defaulted as described above"
 227 .RB ` \-noheader '
 228 .RB ` \-width "' defaulted to the width of the terminal"
 229 .fi
 230
 231 .SH CONTEXT
 232 If a folder is given, it will become the current folder.
 233
 234 .SH HISTORY
 235 Prior to using the format string mechanism,
 236 .B \-header
 237 used to generate
 238 a heading saying what each column in the listing was.  Format strings
 239 prevent this from happening.
 240
 241 .SH BUGS
 242 The argument to the
 243 .B \-format
 244 switch must be interpreted as a single
 245 token by the shell that invokes
 246 .BR scan .
 247 Therefore, one must usually
 248 place the argument to this switch inside double\-quotes.
 249 .PP
 250 The value of each
 251 .I component
 252 escape is set by
 253 .B scan
 254 to the
 255 contents of the first message header
 256 .B scan
 257 encounters with the
 258 corresponding component name; any following headers with the same
 259 component name are ignored.