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