diplodocus.org Git - nmh/blob - man/scan.man

   1 .TH SCAN %manext1% 2014-01-20 "%nmhversion%"
   2 .
   3 .\" %nmhwarning%
   4 .
   5 .SH NAME
   6 scan \- produce a summary listing of nmh messages
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B scan
  11 .RB [ \-help ]
  12 .RB [ \-version ]
  13 .RI [ +folder ]
  14 .RI [ msgs ]
  15 .RB [ \-clear " | " \-noclear ]
  16 .RB [ \-form
  17 .IR formatfile ]
  18 .RB [ \-format
  19 .IR string ]
  20 .RB [ \-header " | " \-noheader ]
  21 .RB [ \-width
  22 .IR columns ]
  23 .RB [ \-reverse " | " \-noreverse ]
  24 .RB [ \-file
  25 .IR filename ]
  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 appropriate
  77 .IR locale (1)
  78 environment variables to your native
  79 character set, if it is not US-ASCII.  See
  80 .IR locale (1)
  81 for more details on the appropriate environment variables.
  82 .PP
  83 The switch
  84 .BR \-reverse ,
  85 makes
  86 .B scan
  87 list the messages in reverse
  88 order.
  89 .PP
  90 The
  91 .B \-file
  92 .I filename
  93 switch allows the user to obtain a
  94 .B scan
  95 listing of a mail drop file as produced by
  96 .BR packf .
  97 This listing
  98 includes every message in the file (you can't scan individual messages).
  99 The switch
 100 .B \-reverse
 101 is ignored with this option.
 102 .PP
 103 The switch
 104 .B \-width
 105 .I columns
 106 may be used to specify the width of
 107 the scan line.  The default is to use the width of the terminal.
 108 .PP
 109 The
 110 .B \-header
 111 switch produces a header line prior to the
 112 .B scan
 113 listing.  Currently, the name of the folder and the current date and
 114 time are output (see the
 115 .B HISTORY
 116 section for more information).
 117 .PP
 118 If the
 119 .B \-clear
 120 switch is used and
 121 .BR scan 's
 122 output is directed
 123 to a terminal, then
 124 .B scan
 125 will consult the environment variables
 126 .B $TERM
 127 and
 128 .B $TERMCAP
 129 to determine your terminal type in order
 130 to find out how to clear the screen prior to exiting.  If the
 131 .B \-clear
 132 switch is used and
 133 .BR scan 's
 134 output is not directed to a terminal
 135 (e.g., a pipe or a file), then
 136 .B scan
 137 will send a formfeed prior
 138 to exiting.
 139 .PP
 140 For example, the command:
 141 .PP
 142 .RS 5
 143 (scan \-clear \-header; show all \-show pr \-f) | lpr
 144 .RE
 145 .PP
 146 produces a scan listing of the current folder, followed by a formfeed,
 147 followed by a formatted listing of all messages in the folder, one
 148 per page.  Omitting
 149 .RB \*(lq "\-show\ pr\ \-f" \*(rq
 150 will cause the messages to be
 151 concatenated, separated by a one-line header and two blank lines.
 152 .PP
 153 To override the output format used by
 154 .BR scan ,
 155 the
 156 .B \-format
 157 .I string
 158 or
 159 .B \-form
 160 .I file
 161 switches are used.  This permits individual fields of
 162 the scan listing to be extracted with ease.  The string is simply a format
 163 string and the file is simply a format file.  See
 164 .IR mh\-format (5)
 165 for the details.
 166 .PP
 167 In addition to the standard
 168 .IR mh\-format (5)
 169 escapes,
 170 .B scan
 171 also recognizes the following additional
 172 .I component
 173 escapes:
 174 .PP
 175 .RS 5
 176 .nf
 177 .ta \w'Dtimenow  'u +\w'Returns  'u
 178 .I "Escape      Returns Description"
 179 body    string  the (compressed) first part of the body
 180 dtimenow        date    the current date
 181 folder  string  the name of the current folder
 182 .fi
 183 .RE
 184 .PP
 185 .RB { body }
 186 returns a string without MIME decoding,
 187 i.e.\& the MIME boundary seperator may be the first text shown.
 188 .PP
 189 If no date header is present in the message, the
 190 .I function
 191 escapes
 192 which operate on
 193 .RB { date }
 194 will return values for the date of last
 195 modification of the message file itself.  This feature is handy for
 196 scanning a draft folder, as message drafts usually aren't allowed
 197 to have dates in them.
 198 .PP
 199 The
 200 .B %nmhetcdir%
 201 directory contains several format files as examples of customized
 202 .B scan
 203 output.
 204 .PP
 205 .B scan
 206 will update the
 207 .B nmh
 208 context prior to starting the listing,
 209 so interrupting a long
 210 .B scan
 211 listing preserves the new context.
 212 .B nmh
 213 purists hate this idea.
 214 .SH FILES
 215 .fc ^ ~
 216 .nf
 217 .ta \w'%nmhetcdir%/ExtraBigFileName  'u
 218 ^$HOME/.mh_profile~^The user profile
 219 .fi
 220 .SH "PROFILE COMPONENTS"
 221 .fc ^ ~
 222 .nf
 223 .ta 2.4i
 224 .ta \w'ExtraBigProfileName  'u
 225 ^Path:~^To determine the user's nmh directory
 226 ^Alternate\-Mailboxes:~^To determine the user's mailboxes
 227 ^Current\-Folder:~^To find the default current folder
 228 .fi
 229 .SH "SEE ALSO"
 230 .IR pick (1),
 231 .IR show (1),
 232 .IR mh\-format (5)
 233 .SH DEFAULTS
 234 .nf
 235 .RB ` +folder "' defaults to the current folder"
 236 .RB ` msgs "' defaults to all"
 237 .RB ` \-format "' defaulted as described above"
 238 .RB ` \-noheader '
 239 .RB ` \-width "' defaulted to the width of the terminal"
 240 .fi
 241 .SH CONTEXT
 242 If a folder is given, it will become the current folder.
 243 .SH HISTORY
 244 Prior to using the format string mechanism,
 245 .B \-header
 246 used to generate
 247 a heading saying what each column in the listing was.  Format strings
 248 prevent this from happening.
 249 .SH BUGS
 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.