Use cat for moreproc in testsuite in case it is run without tty.
[mmh] / man / folder.man
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH FOLDER %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 folder, folders \- set/list current folder/message
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B folder
11 .RI [ +folder ]
12 .RI [ msg ]
13 .RB [ \-all " | " \-noall ]
14 .RB [ \-create " | " \-nocreate ]
15 .RB [ \-fast " | " \-nofast ]
16 .RB [ \-header " | " \-noheader ]
17 .RB [ \-recurse " | " \-norecurse ]
18 .RB [ \-total " | " \-nototal ]
19 .RB [ \-list " | " \-nolist ]
20 .RB [ \-push " | " \-pop ]
21 .RB [ \-pack " | " \-nopack ]
22 .RB [ \-print ]
23 .RB [ \-verbose " | " \-noverbose ]
24 .RB [ \-version ]
25 .RB [ \-help ]
26 .PP
27 .HP 5
28 .B folders
29 is equivalent to
30 .B folder
31 .B \-all
32 .ad
33 .SH DESCRIPTION
34 Since the
35 .B nmh
36 environment is the shell, it is easy to lose track
37 of the current folder from day to day.  When
38 .B folder
39 is given the
40 .B \-print
41 switch (the default),
42 .B folder
43 will list the current folder,
44 the number of messages in it, the range of the messages (low\-high),
45 and the current message within the folder, and will flag extra files if
46 they exist.  An example of this summary is:
47 .PP
48 .RS 5
49 .nf
50 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
51 inbox+  has \016 messages       (\0\03\-\022);  cur=\0\05.
52 .fi
53 .RE
54 .PP
55 If a
56 .I +folder
57 and/or
58 .I msg
59 are specified, they will become the current
60 folder and/or message.  By comparison, when a
61 .I +folder
62 argument is given, this corresponds to a \*(lqcd\*(rq operation
63 in the shell; when no
64 .I +folder
65 argument is given, this corresponds roughly to a \*(lqpwd\*(rq
66 operation in the shell.
67 .PP
68 If the specified (or default) folder doesn't exist, the default action
69 is to query the user as to whether the folder should be created; when
70 standard input is not a tty, the answer to the query is assumed to be
71 \*(lqyes\*(rq.
72 .PP
73 Specifying
74 .B \-create
75 will cause
76 .B folder
77 to create new folders
78 without any query.  (This is the easy way to create an empty folder for
79 use later.)  Specifying
80 .B \-nocreate
81 will cause
82 .B folder
83 to exit
84 without creating a non-existant folder.
85 .\"
86 .\" note - this doesn't work at present
87 .\" If `\-noprint' is specified, 
88 .\" a `+folder' and/or `msg' may still be specified
89 .\" to set the current folder and/or message,
90 .\" but the folder summary will not be printed.
91
92 .SS "Multiple Folders"
93 Specifying
94 .B \-all
95 will produce a summary line for each top-level folder
96 in the user's nmh directory, sorted alphabetically.  (If
97 .B folder
98 is invoked by a name ending with \*(lqs\*(rq (e.g.
99 .BR folders ),
100 .B \-all
101 is assumed).  Specifying
102 .B \-recurse
103 with
104 .B \-all
105 will also
106 produce a line for all sub-folders.  These folders are all preceded by
107 the read\-only folders, which occur as
108 .RI \*(lq atr\-cur\- \*(rq
109 entries in the user's
110 .B nmh
111 context.  For example:
112 .PP
113 .RS 5
114 .nf
115 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
116 FOLDER  \0\0\0\0\0\0# MESSAGES  RANGE   CUR     (OTHERS)
117 /var/work/folder        has \035 messages       (\01\-\035);    cur=23.
118 /usr/bugs/Mail  has \082 messages       (\01\-108);     cur=82.
119 ff      has \0no messages.
120 inbox+  has \016 messages       (\03\-\022);    cur=\05.
121 mh      has \076 messages       (15\-\076);     cur=70.
122 notes   has \0\02 messages      (\01\-\0\02);   cur=\01.
123 ucom    has 124 messages        (\01\-124);     cur=\06; (others).
124 .ta \w'/rnd/phyl/Mail/EP has 'u
125
126 TOTAL = 339 messages in 7 folders
127 .fi
128 .RE
129 .PP
130 The \*(lq+\*(rq after
131 .I inbox
132 indicates that it is the current folder.
133 The \*(lq(others)\*(rq indicates that the folder
134 .I ucom
135 has files which
136 aren't messages.  These files may either be sub\-folders, or files that
137 don't belong under the nmh file naming scheme.
138 .PP
139 The header is output if either a
140 .B \-all
141 or a
142 .B \-header
143 switch is specified.  It is suppressed by
144 .BR \-noheader .
145 .PP
146 The folder and message totals are output if either a
147 .B \-all
148 or a
149 .B \-total
150 switch is specified.  It is suppressed by
151 .BR \-nototal .
152 .PP
153 If
154 .B \-fast
155 is given, only the folder name (or names in the case of
156 .BR \-all )
157 will be listed.  (This is faster because the folders need not
158 be read.)
159 .PP
160 If a
161 .I +folder
162 is given along with the
163 .B \-all
164 switch,
165 .B folder
166 will, in addition to setting the current folder, list the top\-level subfolders
167 for the current folder (with
168 .BR \-norecurse )
169 or list all sub-folders under the current folder recursively (with
170 .BR \-recurse ).
171 .PP
172 If
173 .I msg
174 is supplied, together with
175 .IR +folder
176 or without
177 .BR \-all ,
178 it will become the current message of
179 .IR +folder
180 (if it had been supplied)
181 or the current folder.
182 .PP
183 The
184 .B \-recurse
185 switch lists each folder recursively, so use of this
186 option effectively defeats the speed enhancement of the
187 .B \-fast
188 option,
189 since each folder must be searched for subfolders.  Nevertheless, the
190 combination of these options is useful.
191 .PP
192 .SS "Compacting a Folder"
193 The
194 .B \-pack
195 switch will compress the message names in the designated
196 folders, removing holes in message numbering.  The
197 .B \-verbose
198 switch directs
199 .B folder
200 to tell the user the general actions that it is
201 taking to compress the folder.
202 .PP
203 .SS "The Folder Stack"
204 The
205 .B \-push
206 switch directs
207 .B folder
208 to push the current folder
209 onto the
210 .IR folder\-stack ,
211 and make the
212 .I +folder
213 argument the current folder.  If
214 .I +folder
215 is not given, the current folder and the
216 top of the
217 .I folder\-stack
218 are exchanged.  This corresponds to the
219 \*(lqpushd\*(rq operation in the shell.
220 .PP
221 The
222 .B \-pop
223 switch directs
224 .B folder
225 to discard the top of the
226 .IR folder\-stack ,
227 after setting the current folder to that value.
228 No
229 .I +folder
230 argument is allowed.  This corresponds to the \*(lqpopd\*(rq
231 operation in the shell.  The
232 .B \-push
233 switch and the
234 .B \-pop
235 switch
236 are mutually exclusive: the last occurrence of either one overrides
237 any previous occurrence of the other.  Both of these switches also set
238 .B \-list
239 by default.
240 .PP
241 The
242 .B \-list
243 switch directs
244 .B folder
245 to list the contents of
246 the
247 .IR folder\-stack .
248 No
249 .I +folder
250 argument is allowed.  After a successful
251 .B \-push
252 or
253 .BR \-pop ,
254 the
255 .B \-list
256 action is taken, unless a
257 .B \-nolist
258 switch follows them on the command line.  This corresponds
259 to the \*(lqdirs\*(rq operation in the shell.  The
260 .BR \-push ,
261 .BR \-pop ,
262 and
263 .B \-list
264 switches turn off
265 .BR \-print .
266
267 .SH FILES
268 .fc ^ ~
269 .nf
270 .ta \w'%etcdir%/ExtraBigFileName  'u
271 ^$HOME/\&.mh\(ruprofile~^The user profile
272 .fi
273
274 .SH "PROFILE COMPONENTS"
275 .fc ^ ~
276 .nf
277 .ta 2.4i
278 .ta \w'ExtraBigProfileName  'u
279 ^Path:~^To determine the user's nmh directory
280 ^Current\-Folder:~^To find the default current folder
281 ^Folder\-Protect:~^To set mode when creating a new folder
282 ^Folder\-Stack:~^To determine the folder stack
283 .\" ^lsproc:~^Program to list the contents of a folder
284 .fi
285
286 .SH "SEE ALSO"
287 refile(1), mhpath(1)
288
289 .SH DEFAULTS
290 .nf
291 .RB ` +folder "' defaults to the current folder"
292 .RB ` msg "' defaults to none"
293 .RB ` \-nofast '
294 .RB ` \-noheader '
295 .RB ` \-nototal '
296 .RB ` \-nopack '
297 .RB ` \-norecurse '
298 .RB ` \-noverbose '
299 .RB ` \-print "' is the default if no " \-list ", " \-push ", or " \-pop " is specified"
300 .RB ` \-list "' is the default if " \-push ", or " \-pop " is specified"
301 .fi
302
303 .SH CONTEXT
304 If
305 .I +folder
306 and/or
307 .I msg
308 are given, they will become the current folder and/or message.
309
310 .SH BUGS
311 There is no way to restore the default behavior 
312 (to ask the user whether to create a non-existant folder)
313 after
314 .B \-create
315 or
316 .B \-nocreate
317 is given.