diplodocus.org Git - nmh/blob - man/folder.man

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