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

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