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