Added test of -nosequence to test-pick.
[mmh] / docs / historical / mh-6.8.5 / doc / folder.me
1 .\"     This file is automatically generated.  Do not edit!
2 .\" @(#)$Id: folder.rf,v 1.15 1993/08/27 18:13:47 jromine Exp $
3 .SC FOLDER 1
4 .NA
5 folder, folders \- set/list current folder/message
6 .SY
7 folder
8 \%[+folder] \%[msg]
9 \%[\-all]
10 \%[\-create] \%[\-nocreate]
11 \%[\-print]
12 .\" \%[\-noprint]
13 \%[\-fast] \%[\-nofast]
14 \%[\-header] \%[\-noheader]
15 \%[\-recurse] \%[\-norecurse]
16 \%[\-total] \%[\-nototal]
17 \%[\-list] \%[\-nolist]
18 \%[\-push] \%[\-pop]
19 \%[\-pack] \%[\-nopack]
20 \%[\-verbose] \%[\-noverbose]
21 \%[\-help]
22
23 .ti .5i
24 folders
25 .DE
26 Since the \fIMH\fR environment is the shell, it is easy to lose
27 track of the current folder from day to day.
28 When \fIfolder\fR is given the `\-print' switch (the default),
29 \fIfolder\fR will
30 list the current folder, the number of messages in it, the
31 range of the messages (low\-high), and the current message within
32 the folder, and will flag extra files if they exist.
33 An example of this summary is:
34
35 .nf
36 .if t .in +.5i
37 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
38 inbox+  has \016 messages       (\0\03\-\022);  cur=\0\05.
39 .re
40 .if t .in -.5i
41 .fi
42
43 If a `+folder' and/or `msg' are specified, they will
44 become the current folder and/or message.
45 By comparison,
46 when a `+folder' argument is given,
47 this corresponds to a \*(lqcd\*(rq operation in the \fIshell\fR;
48 when no `+folder' argument is given,
49 this corresponds roughly to a \*(lqpwd\*(rq operation in the \fIshell\fR.
50
51 If the specified (or default) folder doesn't exist,
52 the default action is to query the user
53 as to whether the folder should be created;
54 when standard input is not a tty, the answer to 
55 the query is assumed to be \*(lqyes\*(rq.
56
57 Specifying `\-create' will cause \fIfolder\fP to create
58 new folders without any query.
59 (This is the easy way to create an empty folder for use later.)
60 Specifying `\-nocreate' will 
61 cause \fIfolder\fP to exit without creating a non-existant folder.
62 .\"
63 .\" note - this doesn't work at present
64 .\" If `\-noprint' is specified, 
65 .\" a `+folder' and/or `msg' may still be specified
66 .\" to set the current folder and/or message,
67 .\" but the folder summary will not be printed.
68 .Uh "Multiple Folders"
69 Specifying `\-all'
70 will produce a summary line for each top-level
71 folder in the user's MH directory, sorted alphabetically.
72 (If \fIfolder\fR
73 is invoked by a name ending with \*(lqs\*(rq (e.g., \fIfolders\fR\0),
74 `\-all' is assumed).
75 Specifying `\-recurse' with `\-all' will also 
76 produce a line for all sub-folders.
77 These folders are all preceded by the read\-only folders,
78 which occur as \*(lqatr\-cur\-\*(rq entries in the user's \fIMH\fR context.
79 For example,
80
81 .ne 9
82 .nf
83 .if t .in +.5i
84 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
85 Folder  \0\0\0# of messages     (\0range\0)     cur msg (other files)
86 /fsd/rs/m/tacc  has \035 messages       (\0\01\-\035);  cur=\023.
87 /rnd/phyl/Mail/EP       has \082 messages       (\0\01\-108);   cur=\082.
88 ff      has \0no messages.
89 inbox+  has \016 messages       (\0\03\-\022);  cur=\0\05.
90 mh      has \076 messages       (\0\01\-\076);  cur=\070.
91 notes   has \0\02 messages      (\0\01\-\0\02); cur=\0\01.
92 ucom    has 124 messages        (\0\01\-124);   cur=\0\06; (others).
93 .ta \w'/rnd/phyl/Mail/EP has 'u
94 \0\0\0\0\0\0\0\0\0\0TOTAL=      339 messages in 7 folders
95 .re
96 .if t .in -.5i
97 .fi
98
99 The \*(lq+\*(rq after inbox indicates that it is the current folder.
100 The \*(lq(others)\*(rq indicates that the folder `ucom' has files
101 which aren't messages.
102 These files may either be sub\-folders,
103 or files that don't belong under the MH file naming scheme.
104
105 The header is output if either a `\-all' or a `\-header' switch
106 is specified; it is suppressed by `\-noheader'.
107 A `\-total' switch will produce only the
108 summary line.
109
110 If `\-fast' is given, only the folder name (or names in the
111 case of `\-all') will be listed.
112 (This is faster because the
113 folders need not be read.)
114
115 If a `+folder' 
116 is given along with the `\-all' switch,
117 \fIfolder\fR will,
118 in addition to setting the current folder,
119 list the top\-level folders for the current folder (with `\-norecurse')
120 or list all sub-folders under the current folder recursively (with `\-recurse').
121 In this case, if a `msg' is also supplied,
122 it will become the current message of `+folder'.
123
124 The `\-recurse' switch lists each folder recursively, so
125 use of this option effectively defeats the speed enhancement of the `\-fast'
126 option,
127 since each folder must be searched for subfolders.
128 Nevertheless, the combination of these options is useful.
129
130 .Uh "Compacting a Folder"
131 The `\-pack' switch will compress the message names in the
132 designated folders, removing holes in message numbering.
133 The `\-verbose' switch directs \fIfolder\fR to tell the user the general
134 actions that it is taking to compress the folder.
135
136 .Uh "The Folder Stack"
137 The `\-push' switch directs \fIfolder\fR to push the current folder onto the
138 \fIfolder\-stack\fR,
139 and make the `+folder' argument the current folder.
140 If `+folder' is not given,
141 the current folder and the top of the \fIfolder\-stack\fR are exchanged.
142 This corresponds to the \*(lqpushd\*(rq operation in the \fICShell\fR.
143
144 The `\-pop' switch directs \fIfolder\fR to discard the top of the
145 \fIfolder\-stack\fR,
146 after setting the current folder to that value.
147 No `+folder' argument is allowed.
148 This corresponds to the \*(lqpopd\*(rq operation in the \fICShell\fR.
149 The `\-push' switch and the `\-pop' switch are mutually exclusive:
150 the last occurrence of either one overrides any previous occurrence of the
151 other.  Both of these switches also set `\-list' by default.
152
153 The `\-list' switch directs \fIfolder\fR to list the contents of the
154 \fIfolder\-stack\fR.
155 No `+folder' argument is allowed.
156 After a successful `\-push' or `\-pop', the `\-list' action is taken,
157 unless a `\-nolist' switch follows them on the command line.
158 This corresponds to the \*(lqdirs\*(rq operation in the \fICShell\fR.
159 The `\-push', `\-pop', and `\-list' switches turn
160 off `\-print'.
161 .Fi
162 ^$HOME/\&.mh\(ruprofile~^The user profile
163 .Pr
164 ^Path:~^To determine the user's MH directory
165 .Ps
166 ^Current\-Folder:~^To find the default current folder
167 .Ps
168 ^Folder\-Protect:~^To set mode when creating a new folder
169 .Ps
170 ^Folder\-Stack:~^To determine the folder stack
171 .\" .Ps
172 .\" ^lsproc:~^Program to list the contents of a folder
173 .Sa
174 refile(1), mhpath(1)
175 .De
176 `+folder' defaults to the current folder
177 .Ds
178 `msg' defaults to none
179 .Ds
180 `\-nofast'
181 .Ds
182 `\-noheader'
183 .Ds
184 `\-nototal'
185 .Ds
186 `\-nopack'
187 .Ds
188 `\-norecurse'
189 .Ds
190 `\-noverbose'
191 .Ds
192 `\-print' is the default if no `\-list', `\-push', or `\-pop' is specified
193 .Ds
194 `\-list' is the default if `\-push', or `\-pop' is specified
195 .Co
196 If `+folder' and/or `msg' are given, they will become the
197 current folder and/or message.
198 .Hi
199 In previous versions of \fIMH\fR,
200 the `\-fast' switch prevented context changes from
201 occurring for the current folder.
202 This is no longer the case: if `+folder' is given,
203 then \fIfolder\fR will always change the current folder to that.
204 .Bu
205 `\-all' forces `\-header' and `\-total'.
206 .sp
207 There is no way to restore the default behavior 
208 (to ask the user whether to create a non-existant folder)
209 after `\-create' or `\-nocreate' is given.
210 .En