Added all of the MH sources, including RCS files, in

[mmh] / docs / historical / mh-6.8.5 / conf / doc / RCS / folder.rf,v

head    1.15;
access;
symbols;
locks; strict;


1.15
date    93.08.27.18.13.47;      author jromine; state Exp;
branches;
next    1.14;

1.14
date    93.08.26.22.59.29;      author jromine; state Exp;
branches;
next    1.13;

1.13
date    93.08.26.22.56.45;      author jromine; state Exp;
branches;
next    1.12;

1.12
date    93.08.19.21.20.51;      author jromine; state Exp;
branches;
next    1.11;

1.11
date    92.10.29.21.50.27;      author jromine; state Exp;
branches;
next    1.10;

1.10
date    92.02.18.17.47.49;      author jromine; state Exp;
branches;
next    1.9;

1.9
date    92.02.07.23.57.18;      author jromine; state Exp;
branches;
next    1.8;

1.8
date    92.02.07.20.16.07;      author jromine; state Exp;
branches;
next    1.7;

1.7
date    92.02.06.22.01.06;      author jromine; state Exp;
branches;
next    1.6;

1.6
date    90.12.18.14.28.05;      author mh;      state Exp;
branches;
next    1.5;

1.5
date    90.04.05.15.12.37;      author sources; state Exp;
branches;
next    1.4;

1.4
date    90.03.22.11.31.06;      author sources; state Exp;
branches;
next    1.3;

1.3
date    90.03.20.19.41.43;      author sources; state Exp;
branches;
next    1.2;

1.2
date    90.03.20.17.36.00;      author sources; state Exp;
branches;
next    1.1;

1.1
date    90.03.20.17.20.48;      author sources; state Exp;
branches;
next    ;


desc
@@


1.15
log
@use -[no]create instead of -create policy
@
text
@.\"    @@(MHWARNING)
.\" @@(#)$Id: folder.rf,v 1.14 1993/08/26 22:59:29 jromine Exp jromine $
.SC FOLDER 1
.NA
folder, folders \- set/list current folder/message
.SY
folder
\%[+folder] \%[msg]
\%[\-all]
\%[\-create] \%[\-nocreate]
\%[\-print]
.\" \%[\-noprint]
\%[\-fast] \%[\-nofast]
\%[\-header] \%[\-noheader]
\%[\-recurse] \%[\-norecurse]
\%[\-total] \%[\-nototal]
\%[\-list] \%[\-nolist]
\%[\-push] \%[\-pop]
\%[\-pack] \%[\-nopack]
\%[\-verbose] \%[\-noverbose]
\%[\-help]

.ti .5i
folders
.DE
Since the \fIMH\fR environment is the shell, it is easy to lose
track of the current folder from day to day.
When \fIfolder\fR is given the `\-print' switch (the default),
\fIfolder\fR 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:

.nf
.if t .in +.5i
.ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
inbox+  has \016 messages       (\0\03\-\022);  cur=\0\05.
.re
.if t .in -.5i
.fi

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 \*(lqcd\*(rq operation in the \fIshell\fR;
when no `+folder' argument is given,
this corresponds roughly to a \*(lqpwd\*(rq operation in the \fIshell\fR.

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 \*(lqyes\*(rq.

Specifying `\-create' will cause \fIfolder\fP to create
new folders without any query.
(This is the easy way to create an empty folder for use later.)
Specifying `\-nocreate' will 
cause \fIfolder\fP to exit without creating a non-existant folder.
.\"
.\" note - this doesn't work at present
.\" If `\-noprint' is specified, 
.\" a `+folder' and/or `msg' may still be specified
.\" to set the current folder and/or message,
.\" but the folder summary will not be printed.
.Uh "Multiple Folders"
Specifying `\-all'
will produce a summary line for each top-level
folder in the user's MH directory, sorted alphabetically.
(If \fIfolder\fR
is invoked by a name ending with \*(lqs\*(rq (e.g., \fIfolders\fR\0),
`\-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 \*(lqatr\-cur\-\*(rq entries in the user's \fIMH\fR context.
For example,

.ne 9
.nf
.if t .in +.5i
.ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
Folder  \0\0\0# of messages     (\0range\0)     cur msg (other files)
/fsd/rs/m/tacc  has \035 messages       (\0\01\-\035);  cur=\023.
/rnd/phyl/Mail/EP       has \082 messages       (\0\01\-108);   cur=\082.
ff      has \0no messages.
inbox+  has \016 messages       (\0\03\-\022);  cur=\0\05.
mh      has \076 messages       (\0\01\-\076);  cur=\070.
notes   has \0\02 messages      (\0\01\-\0\02); cur=\0\01.
ucom    has 124 messages        (\0\01\-124);   cur=\0\06; (others).
.ta \w'/rnd/phyl/Mail/EP has 'u
\0\0\0\0\0\0\0\0\0\0TOTAL=      339 messages in 7 folders
.re
.if t .in -.5i
.fi

The \*(lq+\*(rq after inbox indicates that it is the current folder.
The \*(lq(others)\*(rq 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 MH file naming scheme.

The header is output if either a `\-all' or a `\-header' switch
is specified; it is suppressed by `\-noheader'.
A `\-total' switch will produce only the
summary line.

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,
\fIfolder\fR will,
in addition to setting the current folder,
list the top\-level folders 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.

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

.Uh "The Folder Stack"
The `\-push' switch directs \fIfolder\fR to push the current folder onto the
\fIfolder\-stack\fR,
and make the `+folder' argument the current folder.
If `+folder' is not given,
the current folder and the top of the \fIfolder\-stack\fR are exchanged.
This corresponds to the \*(lqpushd\*(rq operation in the \fICShell\fR.

The `\-pop' switch directs \fIfolder\fR to discard the top of the
\fIfolder\-stack\fR,
after setting the current folder to that value.
No `+folder' argument is allowed.
This corresponds to the \*(lqpopd\*(rq operation in the \fICShell\fR.
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 \fIfolder\fR to list the contents of the
\fIfolder\-stack\fR.
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 \*(lqdirs\*(rq operation in the \fICShell\fR.
The `\-push', `\-pop', and `\-list' switches turn
off `\-print'.
.Fi
^$HOME/\&.mh\(ruprofile~^The user profile
.Pr
^Path:~^To determine the user's MH directory
.Ps
^Current\-Folder:~^To find the default current folder
.Ps
^Folder\-Protect:~^To set mode when creating a new folder
.Ps
^Folder\-Stack:~^To determine the folder stack
.\" .Ps
.\" ^lsproc:~^Program to list the contents of a folder
.Sa
refile(1), mhpath(1)
.De
`+folder' defaults to the current folder
.Ds
`msg' defaults to none
.Ds
`\-nofast'
.Ds
`\-noheader'
.Ds
`\-nototal'
.Ds
`\-nopack'
.Ds
`\-norecurse'
.Ds
`\-noverbose'
.Ds
`\-print' is the default if no `\-list', `\-push', or `\-pop' is specified
.Ds
`\-list' is the default if `\-push', or `\-pop' is specified
.Co
If `+folder' and/or `msg' are given, they will become the
current folder and/or message.
.Hi
In previous versions of \fIMH\fR,
the `\-fast' switch prevented context changes from
occurring for the current folder.
This is no longer the case: if `+folder' is given,
then \fIfolder\fR will always change the current folder to that.
.Bu
`\-all' forces `\-header' and `\-total'.
.sp
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.
.En
@


1.14
log
@note default: -create ask
@
text
@d2 1
a2 1
.\" @@(#)$Id: folder.rf,v 1.13 1993/08/26 22:56:45 jromine Exp jromine $
d10 1
a10 1
\%[\-create\0policy]
d52 4
a55 16
the action taken is controlled with the `\-create' switch.
One of three arguments may be specified:
.sp
.in +1i
.ta 1i
.ti -1i
\fBalways\fP    indicates that \fIfolder\fR should create the folder.
.ti -1i
\fBask\fP       indicates that \fIfolder\fR should ask the user.
(When standard input is not a tty, the folder is created without any query.)
.ti -1i
\fBnever\fP     indicates that \fIfolder\fR should not create the folder.
.in -1i
.sp
(Using \*(lqfolder -create always +folder\*(rq
is an easy way to create an empty folder for use later.)
d57 6
a67 1

a179 2
`\-create\0ask'
.Ds
d206 4
@


1.13
log
@document folder -create policy
@
text
@d2 1
a2 1
.\" @@(#)$Id: folder.rf,v 1.12 1993/08/19 21:20:51 jromine Exp jromine $
d186 2
@


1.12
log
@note that -all forces -total
@
text
@d2 1
a2 1
.\" @@(#)$Id: folder.rf,v 1.11 1992/10/29 21:50:27 jromine Exp jromine $
d10 1
a44 6
If the specified (or default) folder doesn't exist,
the user will be queried as to whether the folder should be created.
When standard input is not a tty, the folder is
created without any query.
(This is the easy way to create an empty folder for use later.)

d50 18
@


1.11
log
@zap lsproc
@
text
@d2 1
a2 1
.\" @@(#)$Id: folder.rf,v 1.10 1992/02/18 17:47:49 jromine Exp jromine $
d199 1
a199 1
`\-all' forces `\-header'.
@


1.10
log
@document bug
@
text
@d2 1
a2 1
.\" @@(#)$Id: folder.rf,v 1.9 1992/02/07 23:57:18 jromine Exp jromine $
d165 2
a166 2
.Ps
^lsproc:~^Program to list the contents of a folder
@


1.9
log
@typo
@
text
@d2 1
a2 1
.\" @@(#)$Id: folder.rf,v 1.8 1992/02/07 20:16:07 jromine Exp jromine $
d198 2
@


1.8
log
@undocument -noprint
@
text
@d2 1
a2 1
.\" @@(#)$Id: folder.rf,v 1.7 1992/02/06 22:01:06 jromine Exp jromine $
d126 1
a126 1
desginated folders, removing holes in message numbering.
@


1.7
log
@rewrite
@
text
@d2 1
a2 1
.\" @@(#)$Id: folder.rf,v 1.6 1990/12/18 14:28:05 mh Exp jromine $
d10 2
a11 1
\%[\-print] \%[\-noprint]
d153 2
a154 1
The `\-push', `\-pop', and `\-list' switches set `\-noprint'.
@


1.6
log
@mention creating a folder when stdin is not a tty
jlr
@
text
@d2 1
a2 1
.\" @@(#)$Id: folder.rf,v 1.5 90/04/05 15:12:37 sources Exp Locker: mh $
d10 1
a12 1
\%[\-pack] \%[\-nopack]
a14 1
\%[\-print] \%[\-noprint]
d17 2
a25 1

d27 1
a27 8
the current folder and/or message may be set,
or all folders may be listed.
When a `+folder' argument is given,
this corresponds to a \*(lqcd\*(rq operation in the \fICShell\fR;
when no `+folder' argument is given,
this corresponds roughly to a \*(lqpwd\*(rq operation in the \fICShell\fR.

\fIFolder\fR will
d31 1
a31 1
An example of the output is:
d43 19
d63 8
a70 3
will produce a line for each folder in the user's MH directory,
sorted alphabetically.
These folders are preceded by the read\-only folders,
d74 1
d98 1
a98 1
The header is output if either an `\-all' or a `\-header' switch
a99 3
Also, if \fIfolder\fR
is invoked by a name ending with \*(lqs\*(rq (e.g., \fIfolders\fR\0),
`\-all' is assumed.
a102 6
If a `+folder' and/or `msg' is given along with the `\-all' switch,
\fIfolder\fR will,
in addition to setting the current folder and/or message,
list the top\-level folders for the current folder (with `\-norecurse')
or list all folders under the current folder recursively (with `\-recurse').

d108 8
a115 2
The `\-pack' switch will compress the message names in a folder, removing
holes in message numbering.
d117 2
a118 2
The `\-recurse' switch will list each folder recursively.
Use of this option effectively defeats the speed enhancement of the `\-fast'
d123 5
a127 5
If the specified (or default) folder doesn't exist,
the user will be queried as to whether the folder should be created.
When standard input is not a tty, the folder is
created without any query.
(This is the easy way to create an empty folder for use later.)
d129 1
d144 1
a144 1
other.
d149 2
a150 1
After a successful `\-push' or `\-pop', the `\-list' action is taken.
d152 1
d182 2
d185 2
@


1.5
log
@add ID
@
text
@d2 1
a2 1
.\" @@(#)$Id:$
d109 3
a111 1
the user will be queried if the folder should be created.
@


1.4
log
@put things back, do .NA stuff another way
@
text
@d2 1
@


1.3
log
@typo
@
text
@d2 2
a3 2
.TH FOLDER 1 @@(MHCENTERFOOT) @@(MHLEFTFOOT)
.SH .NA
d5 1
a5 1
.SH .SY
@


1.2
log
@fixup for makewhatis
@
text
@d2 1
a2 1
.TH FOLDER 1 [mh.6] MH
@


1.1
log
@Initial revision
@
text
@d2 2
a3 2
.SC FOLDER 1
.NA
d5 1
a5 1
.SY
@