Provided by: nmh_1.3-1build1_i386 bug

NAME

       folder, folders - set/list current folder/message

SYNOPSIS

       folder [+folder] [msgs] [-all | -noall] [-create | -nocreate] [-fast |
            -nofast] [-header | -noheader] [-recurse | -norecurse] [-total |
            -nototal] [-list | -nolist] [-push | -pop] [-pack | -nopack]
            [-print] [-verbose | -noverbose] [-version] [-help]

       folders is equivalent to folder -all

DESCRIPTION

       Since the nmh environment is the shell, it is easy to lose track of the
       current folder from day to day.  When folder is given the -print switch
       (the default), folder will list  the  current  folder,  the  number  of
       messages  in  it, the range of the messages (low-high), and the current
       message within the folder, and will flag extra files if they exist.  An
       example of this summary is:

            inbox+            has  16 messages (  3- 22); cur=  5.

       If  a  +folder  and/or  msg are specified, they will become the current
       folder and/or message.  By  comparison,  when  a  +folder  argument  is
       given,  this  corresponds  to  a  "cd"  operation in the shell; when no
       +folder  argument  is  given,  this  corresponds  roughly  to  a  "pwd"
       operation in the shell.

       If  the specified (or default) folder doesn't exist, the default action
       is to query the user as to whether the folder should be  created;  when
       standard  input  is not a tty, the answer to the query is assumed to be
       "yes".

       Specifying -create will cause folder to create new folders without  any
       query.  (This is the easy way to create an empty folder for use later.)
       Specifying -nocreate will cause folder to exit without creating a  non-
       existant folder.

   Multiple Folders
       Specifying  -all  will produce a summary line for each top-level folder
       in the user's nmh directory,  sorted  alphabetically.   (If  folder  is
       invoked  by  a  name ending with "s" (e.g.  folders), -all is assumed).
       Specifying -recurse with -all will also produce a  line  for  all  sub-
       folders.   These  folders  are  all  preceded by the read-only folders,
       which occur as "atr-cur-" entries  in  the  user's  nmh  context.   For
       example:

            FOLDER                  # MESSAGES RANGE      CUR     (OTHERS)
            /var/work/folder  has  35 messages ( 1- 35);  cur=23.
            /usr/bugs/Mail    has  82 messages ( 1-108);  cur=82.
            ff                has  no messages.
            inbox+            has  16 messages ( 3- 22);  cur= 5.
            mh                has  76 messages (15- 76);  cur=70.
            notes             has   2 messages ( 1-  2);  cur= 1.
            ucom              has 124 messages ( 1-124);  cur= 6; (others).

            TOTAL = 339 messages in 7 folders

       The  "+"  after  inbox  indicates  that  it is the current folder.  The
       "(others)" indicates that  the  folder  ucom  has  files  which  aren't
       messages.   These  files may either be sub-folders, or files that don't
       belong under the nmh file naming scheme.

       The header is output if either a -all or a -header switch is specified.
       It is suppressed by -noheader.

       The  folder  and message totals are output if either a -all or a -total
       switch is specified.  It is suppressed by -nototal.

       If -fast is given, only the folder name (or names in the case of  -all)
       will be listed.  (This is faster because the folders need not be read.)

       If  a  +folder  is  given  along  with the -all switch, folder will, in
       addition to setting the current folder, list the  top-level  subfolders
       for  the current folder (with -norecurse) or list all sub-folders under
       the current folder recursively (with -recurse).  In this case, if a msg
       is also supplied, it will become the current message of +folder.

       The  -recurse  switch  lists  each  folder  recursively, so use of this
       option effectively defeats the speed enhancement of the  -fast  option,
       since  each  folder must be searched for subfolders.  Nevertheless, the
       combination of these options is useful.

   Compacting a Folder
       The -pack switch will compress the  message  names  in  the  designated
       folders,  removing  holes  in  message  numbering.  The -verbose switch
       directs folder to tell the user the general actions that it  is  taking
       to compress the folder.

   The Folder Stack
       The  -push  switch  directs  folder to push the current folder onto the
       folder-stack, and make the +folder argument  the  current  folder.   If
       +folder   is  not  given,  the  current  folder  and  the  top  of  the
       folder-stack are exchanged.  This corresponds to the "pushd"  operation
       in the shell.

       The  -pop switch directs folder to discard the top of the folder-stack,
       after setting the current folder to that value.  No +folder argument is
       allowed.   This  corresponds to the "popd" operation in the shell.  The
       -push switch and the -pop  switch  are  mutually  exclusive:  the  last
       occurrence  of  either  one  overrides  any  previous occurrence of the
       other.  Both of these switches also set -list by default.

       The  -list  switch  directs  folder  to  list  the  contents   of   the
       folder-stack.   No  +folder  argument  is  allowed.  After a successful
       -push or -pop, the -list action  is  taken,  unless  a  -nolist  switch
       follows  them  on  the  command  line.   This corresponds to the "dirs"
       operation in the shell.  The -push, -pop, and -list switches  turn  off
       -print.

FILES

       $HOME/.mh_profile          The user profile

PROFILE COMPONENTS

       Path:                To determine the user's nmh directory
       Current-Folder:      To find the default current folder
       Folder-Protect:      To set mode when creating a new folder
       Folder-Stack:        To determine the folder stack

SEE ALSO

       refile(1), mhpath(1)

DEFAULTS

       `+folder' defaults to the current folder
       `msg' defaults to none
       `-nofast'
       `-noheader'
       `-nototal'
       `-nopack'
       `-norecurse'
       `-noverbose'
       `-print' is the default if no -list, -push, or -pop is specified
       `-list' is the default if -push, or -pop is specified

CONTEXT

       If  +folder  and/or  msg are given, they will become the current folder
       and/or message.

BUGS

       There is no way to restore  the  default  behavior  (to  ask  the  user
       whether  to create a non-existant folder) after -create or -nocreate is
       given.