whom.c: Don't increment atoi(3)'s return value as it's already true.

[nmh] / man / folder.man

diff --git a/man/folder.man b/man/folder.man
index 3eab7658f725eec6fc993caa6fa56f08b62a2e9c..ad8fbeed3f9d1480433feb1f58f699e118ecf578 100644 (file)
--- a/man/folder.man
+++ b/man/folder.man
@@ -1,91 +1,109 @@
-.\"
+.TH FOLDER %manext1% 2016-08-29 "%nmhversion%"
+.

 .\" %nmhwarning%
 .\" %nmhwarning%

-.\" $Id$
-.\"
-.\" include the -mh macro file
-.so %etcdir%/tmac.h
-.\"
-.TH FOLDER %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
+.

 .SH NAME
 .SH NAME

-folder, folders \- set/list current folder/message
+folder, folders \- set/list current nmh folder/message

 .SH SYNOPSIS
 .SH SYNOPSIS

-.in +.5i
-.ti -.5i
-folder
-\%[+folder] \%[msg]
-\%[\-all] \%[\-noall]
-.br
-\%[\-create] \%[\-nocreate]
-\%[\-fast] \%[\-nofast]
-.br
-\%[\-header] \%[\-noheader]
-\%[\-recurse]
-\%[\-norecurse]
-.br
-\%[\-total] \%[\-nototal]
-\%[\-list] \%[\-nolist]
-.br
-\%[\-push] \%[\-pop]
-\%[\-pack] \%[\-nopack]
-\%[\-print]
-.br
-\%[\-verbose]
-\%[\-noverbose]
-\%[\-version]
-\%[\-help]
-
-.ti .5i
-folders is equivalent to folder -all
-.in -.5i
+.HP 5
+.na
+.B folder
+.RB [ \-help ]
+.RB [ \-version ]
+.RI [ +folder ]
+.RI [ msg ]
+.RB [ \-all " | " \-noall ]
+.RB [ \-create " | " \-nocreate ]
+.RB [ \-fast " | " \-nofast ]
+.RB [ \-header " | " \-noheader ]
+.RB [ \-recurse " | " \-norecurse ]
+.RB [ \-total " | " \-nototal ]
+.RB [ \-list " | " \-nolist ]
+.RB [ \-push " | " \-pop ]
+.RB [ \-pack " | " \-nopack ]
+.RB [ \-print ]
+.RB [ \-verbose " | " \-noverbose ]
+.HP 5
+.B folders
+is equivalent to
+.B folder
+.B \-all
+.ad

 .SH DESCRIPTION
 .SH DESCRIPTION

-
-Since the \fInmh\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:
-
+When
+.B folder
+is given the
+.B \-print
+switch (the default), it lists: the current folder, the number
+of messages in it and their range (low-high), the folder's
+current message, and an indication of extra files, if any.
+For example:
+.PP
+.RS 5

 .nf
 .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.
 .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
 .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
+.RE
+.PP
+If a
+.I +folder
+and/or
+.I msg
+are specified, they will become the current folder and/or message.
+(When a
+.I +folder
+argument is given, this corresponds to a \*(lqcd\*(rq operation
+in the shell; when no
+.I +folder
+argument is given, this corresponds roughly to a \*(lqpwd\*(rq
+operation in the shell.)
+.PP
+If the specified (or default) folder doesn't exist,
+.B folder
+will ask the user if the folder should be created; when
+standard input is not a tty, the answer is assumed to be

 \*(lqyes\*(rq.
 \*(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.
+The
+.B \-create
+switch tells
+.B folder
+to create new folders without query.
+(This is an easy way to create an empty folder for later use.)
+Specifying
+.B \-nocreate
+will cause
+.B folder
+to print an error message and exit without creating a folder.

 .\"
 .\" note - this doesn't work at present
 .\"
 .\" note - this doesn't work at present

-.\" If `\-noprint' is specified, 
+.\" 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.
 .\" 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 nmh 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 \fInmh\fR context.  For example,
-.ne 9
+.SS "Multiple Folders"
+Specifying
+.B \-all
+will produce a summary line for each top-level folder in the user's
+.B nmh
+directory, sorted alphabetically.  (If
+.B folder
+is invoked by a name ending with \*(lqs\*(rq (e.g.
+.BR folders ),
+.B \-all
+is assumed.)  Specifying
+.B \-recurse
+with
+.B \-all
+will include a line for all sub-folders.
+These folders are all preceded by any read-only folders, which occur as
+.RI \*(lq atr\-cur\- \*(rq
+entries in the user's
+.B nmh
+context.  For example:
+.PP
+.RS 5

 .nf
 .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\0\0\0# MESSAGES  RANGE   CUR     (OTHERS)
 /var/work/folder       has \035 messages       (\01\-\035);    cur=23.
 .ta \w'/rnd/phyl/Mail/EP 'u +\w'has ddd messages 'u +\w'(ddd\-ddd); 'u
 FOLDER \0\0\0\0\0\0# MESSAGES  RANGE   CUR     (OTHERS)
 /var/work/folder       has \035 messages       (\01\-\035);    cur=23.


@@ -96,104 +114,214 @@ mh       has \076 messages       (15\-\076);     cur=70.
 notes  has \0\02 messages      (\01\-\0\02);   cur=\01.
 ucom   has 124 messages        (\01\-124);     cur=\06; (others).
 .ta \w'/rnd/phyl/Mail/EP has 'u
 notes  has \0\02 messages      (\01\-\0\02);   cur=\01.
 ucom   has 124 messages        (\01\-124);     cur=\06; (others).
 .ta \w'/rnd/phyl/Mail/EP has 'u

-

 TOTAL = 339 messages in 7 folders
 TOTAL = 339 messages in 7 folders

-.re
-.if t .in -.5i

 .fi
 .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 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, \fIfolder\fR 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.
-
-.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 nmh 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
+.RE
+.PP
+The \*(lq+\*(rq after
+.I inbox
+indicates that it is the current folder.
+The \*(lq(others)\*(rq indicates that the folder
+.I ucom
+contains files which aren't messages;
+these may either be sub-folders, or files that
+don't belong under the
+.B nmh
+file naming scheme.
+.PP
+The header is output if either the
+.B \-all
+or
+.B \-header
+switches are specified.  It is suppressed by
+.BR \-noheader .
+.PP
+The folder and message totals are output if either the
+.B \-all
+or
+.B \-total
+switches are specified.  They are suppressed by
+.BR \-nototal .
+.PP
+If
+.B \-fast
+is given, only the folder name (or names, in the case of
+.BR \-all )
+will be listed.
+(This is faster because the folders need not be read.)
+.PP
+If a
+.I +folder
+is given with the
+.B \-all
+switch,
+.B folder
+will, in addition to setting the current folder, list the top-level
+sub-folders for the current folder (with
+.BR \-norecurse )
+or list all sub-folders under the current folder recursively (with
+.BR \-recurse ).
+.PP
+If
+.I msg
+is supplied, together with
+.I +folder
+or without
+.BR \-all ,
+it will become the current message of
+.I +folder
+(if it had been supplied)
+or the current folder.
+.PP
+The
+.B \-recurse
+switch lists each folder recursively, so its use effectively
+defeats the speed enhancement of
+.BR \-fast ,
+since each folder must be searched for sub-folders.
+Nevertheless, the combination of these options is useful.
+.SS "Compacting a Folder"
+The
+.B \-pack
+switch will compress the message names in the designated folders,
+removing holes in message numbering.  The
+.B \-verbose
+switch directs
+.B folder
+to tell the user the general actions it is taking to compress the folder.
+.SS "The Folder Stack"
+The
+.B \-push
+switch directs
+.B folder
+to push the current folder
+onto the
+.IR folder-stack ,
+and make the
+.I +folder
+argument the current folder.  If
+.I +folder
+is not given, the current folder and the
+top of the
+.I folder-stack
+are exchanged.  This corresponds to the
+\*(lqpushd\*(rq operation in the shell.
+.PP
+The
+.B \-pop
+switch directs
+.B folder
+to discard the top of the
+.IR folder-stack ,
+after setting the current folder to that value.
+No
+.I +folder
+argument is allowed.  This corresponds to the \*(lqpopd\*(rq
+operation in the shell.  The
+.B \-push
+and
+.B \-pop
+switches are mutually exclusive: the last occurrence of either one
+overrides any previous occurrence of the other.
+The use of either of these switches also sets
+.BR \-list ,
+by default.
+.PP
+The
+.B \-list
+switch directs
+.B folder
+to list the
+.IR folder-stack .
+No
+.I +folder
+argument is allowed.  After a successful
+.B \-push
+or
+.BR \-pop ,
+the
+.B \-list
+action is taken, unless a
+.B \-nolist
+switch follows them on the command line.  This corresponds
+to the \*(lqdirs\*(rq operation in the shell.  The
+.BR \-push ,
+.BR \-pop ,
+and
+.B \-list
+switches all disable
+.BR \-print .
+.SH FILES
+.TP 20
+$HOME/.mh_profile
+The user's profile.
+.SH "PROFILE COMPONENTS"
+.PD 0
+.TP 20
+Path:
+To determine the user's nmh directory.
+.TP
+Current\-Folder:
+To find the default current folder.
+.TP
+Folder\-Protect:
+To set mode when creating a new folder.
+.TP
+Folder\-Stack:
+To determine the folder stack.

 .\" ^lsproc:~^Program to list the contents of a folder
 .\" ^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.
-.Bu
-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
+.PD
+.SH "SEE ALSO"
+.IR mhpath (1),
+.IR refile (1),
+.IR rmf (1)
+.SH DEFAULTS
+.PD 0
+.TP 20
++folder
+The current folder.
+.TP
+msg
+\*(lqnone\*(rq
+.TP
+\-nofast
+.TP
+\-noheader
+.TP
+\-nototal
+.TP
+\-nopack
+.TP
+\-norecurse
+.TP
+\-noverbose
+.TP
+\-print
+is the default if no
+.BR -list ,
+.BR \-push ,
+or
+.B \-pop
+is specified.
+.TP
+\-list
+is the default if
+.BR \-push ,
+or
+.B \-pop
+is specified.
+.PD
+.SH CONTEXT
+If
+.I +folder
+and/or
+.I msg
+are given, they will become the current folder and/or message.
+.SH BUGS
+There is no way to restore the default behavior
+(to ask the user whether to create a non-existent folder)
+after
+.B \-create
+or
+.B \-nocreate
+is given.