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

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