Clarified description of clobber -auto/-suffix per Ralph's suggestion.

[mmh] / man / mhstore.man

diff --git a/man/mhstore.man b/man/mhstore.man
index 4907273..9cfa8f7 100644 (file)
--- a/man/mhstore.man
+++ b/man/mhstore.man
@@ -1,6 +1,5 @@
 .\"
 .\" %nmhwarning%
 .\"
 .\" %nmhwarning%

-.\" $Id$

 .\"
 .TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
 .SH NAME
 .\"
 .TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
 .SH NAME

@@ -20,7 +19,8 @@ mhstore \- store contents of MIME messages into files
 .IR content ]
 \&...
 .RB [ \-auto " | " \-noauto ]
 .IR content ]
 \&...
 .RB [ \-auto " | " \-noauto ]

-.RB [ \-verbose " | " \-noverbose ]
+.RB [ \-clobber
+.IR always " | " auto " | " suffix " | " ask " | " never ]

 .RB [ \-rcache
 .IR policy ]
 .RB [ \-wcache
 .RB [ \-rcache
 .IR policy ]
 .RB [ \-wcache

@@ -220,7 +220,9 @@ to store the content.  If the formatting string starts with a '/',
 then the content will be stored in the full path given, else the
 file name will be relative to the value of \*(lqnmh-storage\*(rq or
 the current working directory.  Any escapes (given below) will be
 then the content will be stored in the full path given, else the
 file name will be relative to the value of \*(lqnmh-storage\*(rq or
 the current working directory.  Any escapes (given below) will be

-expanded, except for the a-escape.
+expanded, except for the a-escape.  Note that if \*(lqnmh-storage\*(rq
+is not an absolute path, it will be relative to the folder that
+contains the message(s).

 .PP
 A command or pathname formatting string may contain the following
 escapes.  If the content isn't part of a multipart (of any subtype
 .PP
 A command or pathname formatting string may contain the following
 escapes.  If the content isn't part of a multipart (of any subtype

@@ -268,6 +270,73 @@ mhstore-store-application/PostScript: %m%P.ps
 .fi
 .RE
 .PP
 .fi
 .RE
 .PP

+.SS "Overwriting Existing Files"
+The
+.B \-clobber
+switch controls whether
+.B mhstore
+should overwrite existing files.  The allowed values for this switch
+and corresponding behavior when
+.B mhstore
+encounters an existing file are:
+.PP
+.RS 5
+.nf
+.ta \w'suffix  'u
+always    Overwrite existing file (default)
+auto      Create new file of form name-n.extension
+suffix    Create new file of form name.extension.n
+ask       Prompt the user to specify whether or not to overwrite
+          the existing file
+never     Do not overwrite existing file
+.fi
+.RE
+.PP
+With
+.I auto
+and
+.IR suffix ,
+.I n
+is one beyond the existing file with the highest unused number,
+starting from one, in the same form.  If a filename does not have an
+extension (following a '.'), then
+.I auto
+and
+.I suffix
+create a new file of the form
+.I name-n
+and
+.IR name.n ,
+respectively.  With
+.I never
+and
+.IR ask ,
+the exit status of
+.B mhstore
+will be the number of files that were requested but not stored.
+.PP
+With
+.IR ask ,
+if standard input is connected to a terminal,
+the user is prompted to respond
+.IR yes ,
+.IR no ,
+or
+.I rename
+to whether the file should be overwritten.  The responses
+can be abbreviated.  If the user responds with
+.IR rename ,
+then
+.B mhstore
+prompts the user for the name of the new file to be created.  If it is
+a relative path name (does not begin with '/'), then it is relative to
+the current directory.  If it is an absolute or relative path to a
+directory that does not exist, the user will be prompted whether to
+create the directory.  If standard input is not connected to a
+terminal,
+.I ask
+behaves the same as
+.IR always .

 .SS "Reassembling Messages of Type message/partial"
 .B mhstore
 is also able to reassemble messages that have been
 .SS "Reassembling Messages of Type message/partial"
 .B mhstore
 is also able to reassemble messages that have been

@@ -354,11 +423,6 @@ local filename
 .PP
 The program should terminate with an exit status of zero if the
 retrieval is successful, and a non-zero exit status otherwise.
 .PP
 The program should terminate with an exit status of zero if the
 retrieval is successful, and a non-zero exit status otherwise.

-.PP
-If this entry is not provided, then
-.B mhstore
-will use a simple
-built-in FTP client to perform the retrieval.

 .SS "The Content Cache"
 When
 .B mhstore
 .SS "The Content Cache"
 When
 .B mhstore

@@ -467,10 +531,10 @@ mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
 .RB ` +folder "' defaults to the current folder"
 .RB ` msgs "' defaults to cur"
 .RB ` \-noauto '
 .RB ` +folder "' defaults to the current folder"
 .RB ` msgs "' defaults to cur"
 .RB ` \-noauto '

+.RB ` \-clobber\ always '

 .RB ` \-nocheck '
 .RB ` \-nocheck '

-.RB ` \-rcache ask '
-.RB ` \-wcache ask '
-.RB ` \-noverbose '
+.RB ` \-rcache\ ask '
+.RB ` \-wcache\ ask '

 
 .SH CONTEXT
 If a folder is given, it will become the current folder.  The last
 
 .SH CONTEXT
 If a folder is given, it will become the current folder.  The last