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

   1 .TH SCAN %manext1% "November 6, 2012" "%nmhversion%"
   2 .\"
   3 .\" %nmhwarning%
   4 .\"
   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 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 maildrop 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 If no date header is present in the message, the
 186 .I function
 187 escapes
 188 which operate on
 189 .RB { date }
 190 will return values for the date of last
 191 modification of the message file itself.  This feature is handy for
 192 scanning a draft folder, as message drafts usually aren't allowed
 193 to have dates in them.
 194 .PP
 195 The
 196 .B %etcdir%
 197 directory contains several format files as examples of customized
 198 .B scan
 199 output.
 200 .PP
 201 .B scan
 202 will update the
 203 .B nmh
 204 context prior to starting the listing,
 205 so interrupting a long
 206 .B scan
 207 listing preserves the new context.
 208 .B nmh
 209 purists hate this idea.
 210 .SH FILES
 211 .fc ^ ~
 212 .nf
 213 .ta \w'%etcdir%/ExtraBigFileName  'u
 214 ^$HOME/\&.mh\(ruprofile~^The user profile
 215 .fi
 216 .SH "PROFILE COMPONENTS"
 217 .fc ^ ~
 218 .nf
 219 .ta 2.4i
 220 .ta \w'ExtraBigProfileName  'u
 221 ^Path:~^To determine the user's nmh directory
 222 ^Alternate\-Mailboxes:~^To determine the user's mailboxes
 223 ^Current\-Folder:~^To find the default current folder
 224 .fi
 225 .SH "SEE ALSO"
 226 .IR pick (1),
 227 .IR show (1),
 228 .IR mh\-format (5)
 229 .SH DEFAULTS
 230 .nf
 231 .RB ` +folder "' defaults to the current folder"
 232 .RB ` msgs "' defaults to all"
 233 .RB ` \-format "' defaulted as described above"
 234 .RB ` \-noheader '
 235 .RB ` \-width "' defaulted to the width of the terminal"
 236 .fi
 237 .SH CONTEXT
 238 If a folder is given, it will become the current folder.
 239 .SH HISTORY
 240 Prior to using the format string mechanism,
 241 .B \-header
 242 used to generate
 243 a heading saying what each column in the listing was.  Format strings
 244 prevent this from happening.
 245 .SH BUGS
 246 The value of each
 247 .I component
 248 escape is set by
 249 .B scan
 250 to the
 251 contents of the first message header
 252 .B scan
 253 encounters with the
 254 corresponding component name; any following headers with the same
 255 component name are ignored.