new.c: Order two return statements to match comment.

[nmh] / man / refile.man

diff --git a/man/refile.man b/man/refile.man
index 9eb0da5d56227be38c7de6dd6720ab5c67c5dff5..56f1dfad869bb608e0641a59826352fde635d6aa 100644 (file)
--- a/man/refile.man
+++ b/man/refile.man
@@ -1,143 +1,235 @@
-.\"
+.TH REFILE %manext1% 2013-03-19 "%nmhversion%"
+.

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

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

 .SH NAME
 .SH NAME

-refile \- file message in other folders
+refile \- file message in nmh folders

 .SH SYNOPSIS
 .SH SYNOPSIS

-.in +.5i
-.ti -.5i
-refile 
-\%[msgs] 
-\%[\-draft]
-\%[\-link] \%[\-nolink]
-.br
-\%[\-preserve] \%[\-nopreserve]
-\%[\-unlink] \%[\-nounlink]
-.br
-\%[\-src\ +folder] 
-\%[\-file\ file]
-\%[\-rmmproc program]
-.br
-\%[\-normmproc]
-+folder1 ...
-\%[\-version]
-\%[\-help]
-.in -.5i
+.HP 5
+.na
+.B refile
+.RB [ \-help ]
+.RB [ \-version ]
+.RI [ msgs ]
+.RB [ \-draft ]
+.RB [ \-link " | " \-nolink ]
+.RB [ \-preserve " | " \-nopreserve ]
+.RB [ \-retainsequences " | " \-noretainsequences ]
+.RB [ \-unlink " | " \-nounlink ]
+.RB [ \-src
+.IR +folder ]
+.RB [ \-file
+.IR file ]
+.RB [ \-rmmproc
+.IR program ]
+.RB [ \-normmproc ]
+.I +folder1
+\&...
+.ad

 .SH DESCRIPTION
 .SH DESCRIPTION

-\fIRefile\fR moves (\fImv\fR\0(1)) or links (\fIln\fR\0(1)) messages
-from a source folder into one or more destination folders.
-
+.B refile
+moves (see
+.IR mv (1))
+or links (see
+.IR ln (1))
+messages from a source folder into one or more destination folders.
+.PP

 If you think of a message as a sheet of paper, this operation is not
 unlike filing the sheet of paper (or copies) in file cabinet folders.
 When a message is filed, it is linked into the destination folder(s)
 if possible, and is copied otherwise.  As long as the destination
 folders are all on the same file system, multiple filing causes little
 If you think of a message as a sheet of paper, this operation is not
 unlike filing the sheet of paper (or copies) in file cabinet folders.
 When a message is filed, it is linked into the destination folder(s)
 if possible, and is copied otherwise.  As long as the destination
 folders are all on the same file system, multiple filing causes little

-storage overhead.  This facility provides a good way to cross\-file or
-multiply\-index messages.  For example, if a message is received from
+storage overhead.  This facility provides a good way to cross-file or
+multiple-index messages.  For example, if a message is received from

 Jones about the ARPA Map Project, the command
 Jones about the ARPA Map Project, the command

-
-     refile\0cur\0+jones\0+Map
-
+.PP
+.RS 5
+refile\0cur\0+jones\0+Map
+.RE
+.PP

 would allow the message to be found in either of the two folders `jones'
 or `Map'.
 would allow the message to be found in either of the two folders `jones'
 or `Map'.

-
-You may specify the source folder using `\-src\ +folder'.  If this is
-not given, the current folder is used by default.  If no message is
-specified, then `cur' is used by default.
-
-The option `\-file\ file' directs \fIrefile\fR to use the specified file
-as the source message to be filed, rather than a message from a folder.
+.PP
+You may specify the source folder using
+.B \-src
+.IR +folder .
+If this is not given, the current folder is used by default.
+If no message is specified, then `cur' is used by default.
+.PP
+The option
+.B \-file
+.I file
+directs
+.B refile
+to use the specified file as the source message to be filed, rather
+than a message from a folder.

 Note that the file should be a validly formatted message, just like
 Note that the file should be a validly formatted message, just like

-any other \fInmh\fR message.  It should \fBNOT\fR be in mail drop format
-(to convert a file in mail drop format to a folder of \fInmh\fR messages,
-see \fIinc\fR\0(1)).
-
-If a destination folder doesn't exist, \fIrefile\fR will ask if you want
-to create it.  A negative response will abort the file operation.  If the
-standard input for \fIrefile\fR is \fInot\fR a tty, then \fIrefile\fR
+any other
+.B nmh
+message.  It should
+.I not
+be in mail drop format (to convert a file in
+mail drop format to a folder of
+.B nmh
+messages,
+see
+.IR inc (1)).
+.PP
+If a destination folder doesn't exist,
+.B refile
+will ask if you want to create it.
+A negative response will abort the file operation.
+If the standard input for
+.B refile
+is
+.I not
+a tty, then
+.B refile

 will not ask any questions and will proceed as if the user answered
 \*(lqyes\*(rq to all questions.
 will not ask any questions and will proceed as if the user answered
 \*(lqyes\*(rq to all questions.

-
-The option `\-link' preserves the source folder copy of the message (i.e.,
-it does a \fIln\fR(1) rather than a \fImv\fR(1)), whereas, `\-nolink'
+.PP
+The option
+.B \-link
+preserves the source folder copy of the message (i.e., it does an
+.IR ln (1)
+rather than a
+.IR mv (1)),
+whereas,
+.B \-nolink

 (the default) deletes the filed messages from the source folder.
 (the default) deletes the filed messages from the source folder.

-
+.PP

 Normally when a message is refiled, for each destination folder it
 is assigned the number which is one above the current highest message
 Normally when a message is refiled, for each destination folder it
 is assigned the number which is one above the current highest message

-number in that folder.  Use of the `\-preserve' switch will override
+number in that folder.  Use of the
+.B \-preserve
+switch will override

 this message renaming, and try to preserve the number of the message.
 this message renaming, and try to preserve the number of the message.

-If a conflict for a particular folder occurs when using the `\-preserve'
-switch, then \fIrefile\fR will use the next available message number
-which is above the message number you wish to preserve.
-
-If `\-link' is not specified (or `\-nolink' is specified), the filed
-messages will be removed from the source folder.  The default is to
-remove these messages by renaming them with a site-dependent prefix
-(usually a comma).  Such files will then need to be removed in some
-manner after a certain amount of time.  Many sites arrange for
-\fIcron\fR\0(8) to remove these files once a day, so check with your
-system administrator.
-
-Alternately, if you wish for \fIrefile\fR to really remove the files
-representing these messages from the source folder, you can use the
-`-unlink' switch (not to be confused with the -link switch).  But
-messages removed by this method cannot be later recovered.
-
-.ne 4
+If a conflict for a particular folder occurs when using the
+.B \-preserve
+switch, then
+.B refile
+will use the next available message number which is above the message
+number you wish to preserve.
+.PP
+As message sequences are folder-specific, moving the message from
+the source folder removes it from all its sequences in that folder.
+.B \-retainsequences
+adds it to those same sequences in the destination folder,
+creating any that don't exist.
+This adding does not apply for the \*(lqcur\*(rq sequence.
+.PP
+If
+.B \-link
+is not specified (or
+.B \-nolink
+is specified), the filed messages will be removed from the source
+folder.  The default is to remove these messages by renaming them
+with a site-dependent prefix (usually a comma).
+Such files will then need to be removed in some manner after a
+certain amount of time.  Many sites arrange for
+.B cron
+to remove these files once a day, so check with your system administrator.
+.PP
+Alternately, if you wish for
+.B refile
+to really remove the files representing these messages from the source
+folder, you can use the
+.B \-unlink
+switch (not to be confused with the
+.B \-link
+switch).  But messages removed by this method cannot be later recovered.
+.PP

 If you prefer a more sophisticated method of `removing' the messages
 If you prefer a more sophisticated method of `removing' the messages

-from the source folder, you can define the \fIrmmproc\fR profile
-component.  For example, you can add a profile component such as
-
-       rmmproc:        /home/coleman/bin/rmm_msgs
-
-then \fIrefile\fR will instead call the named program or script to
+from the source folder, you can define the
+.B rmmproc
+profile component.  For example, you can add a profile component such as
+.PP
+.RS 5
+rmmproc:    /home/coleman/bin/rmm_msgs
+.RE
+.PP
+then
+.B refile
+will instead call the named program or script to

 handle the message files.
 handle the message files.

-
-The user may specify `\-rmmproc program' on the command line to
-override this profile specification.  The `-normmproc' option forces
-the message files to be deleted by renaming or unlinking them as
-described above.
-
-The `\-draft' switch tells \fIrefile\fR to file the <mh\-dir>/draft.
-.Fi
-^$HOME/\&.mh\(ruprofile~^The user profile
-.Pr
+.PP
+The user may specify
+.B \-rmmproc
+.I program
+on the command line to override this profile specification.
+The
+.B \-normmproc
+option forces the message files to be deleted by renaming or
+unlinking them as described above.
+.PP
+The
+.B \-draft
+switch tells
+.B refile
+to file the <mh-dir>/draft.
+.SH FILES
+.fc ^ ~
+.nf
+.ta \w'%nmhetcdir%/ExtraBigFileName  'u
+^$HOME/.mh_profile~^The user profile
+.fi
+.SH "PROFILE COMPONENTS"
+.fc ^ ~
+.nf
+.ta 2.4i
+.ta \w'ExtraBigProfileName  'u

 ^Path:~^To determine the user's nmh directory
 ^Path:~^To determine the user's nmh directory

-.Ps

 ^Current\-Folder:~^To find the default current folder
 ^Current\-Folder:~^To find the default current folder

-.Ps

 ^Folder\-Protect:~^To set mode when creating a new folder
 ^Folder\-Protect:~^To set mode when creating a new folder

-.Ps

 ^rmmproc:~^Program to delete the message
 ^rmmproc:~^Program to delete the message

-.Sa
-folder(1), rmf(1), rmm(1)
-.De
-`\-src\ +folder' defaults to the current folder
-.Ds
-`msgs' defaults to cur
-.Ds
-`\-nolink'
-.Ds
-`\-nounlink'
-.Ds
-`\-nopreserve'
-.Co
-If `\-src\ +folder' is given, it will become the current folder.
-If neither `\-link' nor `all' is specified, the current message in the
-source folder will be set to the last message specified; otherwise, the
-current message won't be changed.
-
-If the Previous\-Sequence profile entry is set, in addition to defining
-the named sequences from the source folder, \fIrefile\fR will also define
-those sequences for the destination folders.  See \fImh\-sequence\fR\0(5)
+.fi
+.SH "SEE ALSO"
+.IR folder (1),
+.IR mh-sequence (5),
+.IR rmf (1),
+.IR rmm (1)
+.SH DEFAULTS
+.nf
+.RB ` "\-src\ +folder" "' defaults to the current folder"
+.RB ` msgs "' defaults to cur"
+.RB ` \-nolink '
+.RB ` \-nounlink '
+.RB ` \-nopreserve '
+.RB ` \-noretainsequences '
+.fi
+.SH CONTEXT
+If
+.B \-src
+.I +folder
+is given, it will become the current folder.
+If neither
+.B \-link
+nor `all' is specified, the current message in the
+source folder will be set to the last message specified; otherwise,
+the current message won't be changed.
+.PP
+If the \*(lqPrevious\-Sequence\*(rq profile entry is set, in addition
+to defining the named sequences from the source folder,
+.B refile
+will also define those sequences for the destination folders.
+See
+.IR mh\-sequence (5)

 for information concerning the previous sequence.
 for information concerning the previous sequence.

-.Bu
-Since \fIrefile\fR uses your \fIrmmproc\fP to delete the message,
-the \fIrmmproc\fP must \fBNOT\fP call \fIrefile\fP without specifying
-`\-normmproc', or you will create an infinite loop.
-.En
+.SH BUGS
+Since
+.B refile
+and
+.B rmm
+use your
+.I rmmproc
+to delete the message, the
+.I rmmproc
+must
+.I not
+call
+.B refile
+or
+.B rmm
+without specifying
+.BR \-normmproc ,
+or you will create an infinite loop.