Added -clobber switch to mhstore(1) [Bug #11160].

[mmh] / man / mhstore.man

diff --git a/man/mhstore.man b/man/mhstore.man
index 3bfb51e..5efc66f 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

@@ -162,8 +162,8 @@ the message contains information indicating the filename that should
 be used to store the content.  This information should be specified
 as the attribute \*(lqname=filename\*(rq in the \*(lqContent-Type\*(rq header
 for the content you are storing.  For security reasons, this filename
 be used to store the content.  This information should be specified
 as the attribute \*(lqname=filename\*(rq in the \*(lqContent-Type\*(rq header
 for the content you are storing.  For security reasons, this filename

-will be ignored if it begins with the character '/', '.', '|', or
-'!', or if it contains the character '%'.  For the sake of security,
+will be ignored if it begins with the character '/', '.', '|', or '!',
+or if it contains the character '%'.  For the sake of security,

 this switch is not the default, and it is recommended that you do
 NOT put the
 .B \-auto
 this switch is not the default, and it is recommended that you do
 NOT put the
 .B \-auto

@@ -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 number 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

@@ -418,7 +482,7 @@ operates may vary for
 different machines,
 .B mhstore
 will look for the environment variable
 different machines,
 .B mhstore
 will look for the environment variable

-.BE $MHSTORE .
+.BR $MHSTORE .

 If present, this specifies the name of an additional
 user profile which should be read.  Hence, when a user logs in on a
 particular machine, this environment variable should be set to
 If present, this specifies the name of an additional
 user profile which should be read.  Hence, when a user logs in on a
 particular machine, this environment variable should be set to

@@ -439,7 +503,7 @@ installation.
 .SH FILES
 .fc ^ ~
 .nf
 .SH FILES
 .fc ^ ~
 .nf

-.ta \w'/usr/local/nmh/etc/ExtraBigFileName  'u
+.ta \w'%etcdir%/ExtraBigFileName  'u

 ^$HOME/\&.mh\(ruprofile~^The user profile
 ^$MHSTORE~^Additional profile entries
 ^%etcdir%/mhn.defaults~^System default MIME profile entries
 ^$HOME/\&.mh\(ruprofile~^The user profile
 ^$MHSTORE~^Additional profile entries
 ^%etcdir%/mhn.defaults~^System default MIME profile entries

@@ -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