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