X-Git-Url: http://git.marmaro.de/?a=blobdiff_plain;f=man%2Fmhstore.man;h=3838d802139886633b3aeff520bd05224850bd87;hb=0f0af4e32a4d734209c16282b63f7cb1094e2699;hp=ae15292aacbd7b77df26506836c5bd1f5f0dbf68;hpb=1b5a1bd2244d3e1c12b7c9e1f48e445de5ad2ea2;p=mmh

diff --git a/man/mhstore.man b/man/mhstore.man
index ae15292..3838d80 100644
--- a/man/mhstore.man
+++ b/man/mhstore.man
@@ -1,8 +1,7 @@
+.TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
 .\"
 .\" %nmhwarning%
-.\" $Id$
 .\"
-.TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
 .SH NAME
 mhstore \- store contents of MIME messages into files
 .SH SYNOPSIS
@@ -20,7 +19,8 @@ mhstore \- store contents of MIME messages into files
 .IR content ]
 \&...
 .RB [ \-auto " | " \-noauto ]
-.RB [ \-verbose " | " \-noverbose ]
+.RB [ \-clobber
+.IR always " | " auto " | " suffix " | " ask " | " never ]
 .RB [ \-rcache
 .IR policy ]
 .RB [ \-wcache
@@ -73,7 +73,7 @@ be in mail drop format (to convert a file in mail drop format to
 a folder of
 .B nmh
 messages, see
-.BR inc (1)).
+.IR inc (1)).
 .PP
 A part specification consists of a series of numbers separated by
 dots.  For example, in a multipart content containing three parts,
@@ -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
-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
@@ -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
-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
@@ -268,6 +270,72 @@ mhstore-store-application/PostScript: %m%P.ps
 .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 the lowest 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
@@ -354,11 +422,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
-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
@@ -418,7 +481,7 @@ operates may vary for
 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
@@ -435,7 +498,6 @@ user profile, e.g.,
 which is created automatically during
 .B nmh
 installation.
-
 .SH FILES
 .fc ^ ~
 .nf
@@ -444,7 +506,6 @@ installation.
 ^$MHSTORE~^Additional profile entries
 ^%etcdir%/mhn.defaults~^System default MIME profile entries
 .fi
-
 .SH "PROFILE COMPONENTS"
 .fc ^ ~
 .nf
@@ -458,23 +519,22 @@ installation.
 ^nmh-storage~^Directory to store contents
 ^mhstore-store-<type>*~^Template for storing contents
 .fi
-
 .SH "SEE ALSO"
-mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
-
+.IR mhbuild (1),
+.IR mhlist (1),
+.IR mhshow (1),
+.IR sendfiles (1)
 .SH DEFAULTS
 .nf
 .RB ` +folder "' defaults to the current folder"
 .RB ` msgs "' defaults to cur"
 .RB ` \-noauto '
+.RB ` \-clobber\ always '
 .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
 message selected will become the current message.
-
 .SH BUGS
 Partial messages contained within a multipart content are not reassembled.