Updated the installation instructions in INSTALL.
[mmh] / man / flist.man1
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH FLIST %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 flist, flists \- list the number of messages in given sequence(s)
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B flist
11 .RI [ +folder1
12 .RI [ +folder2
13 \&...]]
14 .RB [ \-sequence
15 .I name1
16 .RB [ \-sequence
17 .I name2
18 \&...]]
19 .RB [ \-all " | " \-noall ]
20 .RB [ \-showzero " | " \-noshowzero ]
21 .RB [ \-recurse " | " \-norecurse ]
22 .RB [ \-fast " | " \-nofast ]
23 .RB [ \-alpha " | " \-noalpha ]
24 .RB [ \-Version ]
25 .RB [ \-help ]
26 .PP
27 .HP 5
28 .B flists
29 is equivalent to
30 .B flist
31 .B \-all
32 .ad
33 .SH DESCRIPTION
34 .B Flist
35 is used to search a list of folders and display the number
36 of messages in these folders that are in a given sequence or set of
37 sequences (for example the
38 .RI ` unseen '
39 sequence). This is especially
40 useful if you use some mechanism such as
41 .B slocal
42 or
43 .B procmail
44 (typically in conjunction with
45 .BR rcvstore )
46 to pre-sort your mail into different folders before you view it.
47 .PP
48 By default, the command
49 .B flist
50 will search the current folder for the given sequence or sequences (usually
51 .RI ` unseen ').
52 If (possibly multiple) folders are specified on the command line with
53 .IR +folder ,
54 then all these folders are searched for the given sequence(s).
55 .B Flist
56 will display for each folder searched, the number of messages in each of the
57 specified sequences, and the total number of messages.
58 .PP
59 The option
60 .B \-sequence
61 is used to specify the name of a sequence in
62 which to search for.  This option may be used multiple times to specify
63 multiple sequences.  If this is not given, then the default is to search
64 for all the sequences specified by the
65 .RI ` Unseen-Sequence '
66 profile component. For more details about sequences, read the
67 .BR mh\-sequence (7)
68 man page.
69 .PP
70 Typically,
71 .B flist
72 will produce a line for each sequence, for every
73 folder that is searched, even those which do not contain any messages in
74 the given sequence.  Specifying
75 .B \-noshowzero
76 will cause
77 .B flist
78 to print only those folder/sequence combinations such the folder has a non-zero
79 number of messages in the given specified sequence.
80 .PP
81 If
82 .B \-recurse
83 is given, then for each folder that is search,
84 .B flist
85 will also recursively descend into those folders to search subfolders
86 for the given sequence.
87 .PP
88 If
89 .B \-fast
90 is given, only the names of the folders searched will be displayed, and
91 .B flist
92 will suppress all other output.  If this option is used in conjunction with
93 .BR \-noshowzero ,
94 then
95 .B flist
96 will only print the names of those folders searched that contain messages in
97 in at least one of the specified sequences.
98
99 .SS "Multiple Folders"
100 If the option
101 .B \-all
102 is given (and no folders are specified with
103 .IR +folder ),
104 then
105 .B flist
106 will search all the folders in the top
107 level of the users mmh directory.  These folders are all preceded by
108 the read\-only folders, which occur as
109 .RI ` atr\-cur\- '
110 entries in the user's
111 .B mmh
112 context.
113 .PP
114 An example of the output of
115 .B flist
116 .B \-all
117 is:
118 .PP
119 .RS 5
120 .nf
121 /work/Mail  has  5 in sequence unseen (private); out of  46
122 inbox+      has 10 in sequence unseen          ; out of 153
123 junklist    has  0 in sequence unseen          ; out of  63
124 postmaster  has  1 in sequence unseen          ; out of   3
125 .fi
126 .RE
127 .PP
128 The `+' after
129 .I inbox
130 indicates that it is the current folder.
131 .PP
132 The `private' flag indicates that the given sequence for
133 that folder is private.  See the
134 .BR mh\-sequence (7)
135 man page for details about private sequences.
136 .PP
137 If the option
138 .B \-all
139 and
140 .I +folder
141 are both specified, then
142 .B flist
143 will search this folder, and all its first level subfolders for the
144 given sequence.  You may specify multiple folders in this way.
145 .PP
146 If
147 .B flist
148 is invoked by a name ending with `s'
149 (e.g.
150 .BR flists ),
151 then the switch
152 .B \-all
153 is assumed by default.
154 .PP
155 The sorting order for the listing is alphabetical (with
156 .BR \-alpha ),
157 or in a priority order defined by the
158 .RI ` Flist-Order '
159 profile entry (with
160 .BR \-noalpha ).
161 Each item in the
162 .RI ` Flist-Order '
163 is a folder name or a
164 folder name pattern that uses * to match zero or more characters.
165 Longer matching patterns have precedence over shorter matching patterns.
166 For example:
167 .PP
168 .RS 5
169 .nf
170 Flist-Order: personal petproject mh* * admin *junk
171 .fi
172 .RE
173 .PP
174 This order puts a few interesting folders first, such as those with mail
175 addressed to you personally, those about a pet project, and those about
176 mh-related things.  It places uninteresting folders at the end, and it
177 puts everything else in the middle in alphabetical order.
178
179 .SH FILES
180 .fc ^ ~
181 .nf
182 .ta \w'%etcdir%/ExtraBigFileName  'u
183 ^$HOME/.mmh/profile~^The user profile
184 .fi
185
186 .SH "PROFILE COMPONENTS"
187 .fc ^ ~
188 .nf
189 .ta 2.4i
190 .ta \w'ExtraBigProfileName  'u
191 ^Path:~^To determine the user's mail storage
192 ^Mh-Sequences:~^File that contains public sequences
193 ^Unseen-Sequence:~^The name of the unseen message sequence
194 ^Flist-Order:~^To sort folders by priority
195 .fi
196
197 .SH "SEE ALSO"
198 folder(1), rcvstore(1), slocal(1), mh\-sequence(7)
199
200 .SH DEFAULTS
201 .nf
202 .RB ` -sequence "' defaults to Unseen-Sequence profile entry"
203 .RB ` \-showzero '
204 .RB ` \-noall '
205 .RB ` \-norecurse '
206 .RB ` \-noalpha '
207 .RB ` \-nofast '
208 .fi
209
210 .SH CONTEXT
211 If
212 .I +folder
213 is given, it will become the current folder.
214 If multiple folders are given, the last one specified will
215 become the current folder.