Added note that suffixes were removed from filenames of temporary files.

[nmh] / man / mhstore.man

diff --git a/man/mhstore.man b/man/mhstore.man
index 219d12e93bab56c29d53957aa96a498f958d253f..7e6f850651460577b33b368f5f12f10b4edf5124 100644 (file)
--- a/man/mhstore.man
+++ b/man/mhstore.man
@@ -1,7 +1,7 @@
+.TH MHSTORE %manext1% "March 21, 2013" "%nmhversion%"

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

-.TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]

 .SH NAME
 mhstore \- store contents of MIME messages into files
 .SH SYNOPSIS
 .SH NAME
 mhstore \- store contents of MIME messages into files
 .SH SYNOPSIS


@@ -12,6 +12,8 @@ mhstore \- store contents of MIME messages into files
 .RI [ msgs ]
 .RB [ \-file
 .IR file ]
 .RI [ msgs ]
 .RB [ \-file
 .IR file ]

+.RB [ \-outfile
+.IR outfile ]

 .RB [ \-part
 .IR number ]
 \&...
 .RB [ \-part
 .IR number ]
 \&...


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

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

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


@@ -36,7 +40,7 @@ messages.
 .PP
 .B mhstore
 manipulates multi-media messages as specified in
 .PP
 .B mhstore
 manipulates multi-media messages as specified in

-RFC\-2045 thru RFC\-2049.
+RFC 2045 to RFC 2049.

 .PP
 By default,
 .B mhstore
 .PP
 By default,
 .B mhstore


@@ -51,10 +55,10 @@ switches, you may limit the scope of
 to particular
 subparts (of a multipart content) and/or particular content types.
 .PP
 to particular
 subparts (of a multipart content) and/or particular content types.
 .PP

-The option
+The

 .B \-file
 .I file
 .B \-file
 .I file

-directs
+switch directs

 .B mhstore
 to use the specified
 file as the source message, rather than a message from a folder.
 .B mhstore
 to use the specified
 file as the source message, rather than a message from a folder.


@@ -71,7 +75,7 @@ be in mail drop format (to convert a file in mail drop format to
 a folder of
 .B nmh
 messages, see
 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,
 .PP
 A part specification consists of a series of numbers separated by
 dots.  For example, in a multipart content containing three parts,


@@ -89,7 +93,7 @@ the content from being acted upon.
 .PP
 A content specification consists of a content type and a subtype.
 The initial list of \*(lqstandard\*(rq content types and subtypes
 .PP
 A content specification consists of a content type and a subtype.
 The initial list of \*(lqstandard\*(rq content types and subtypes

-can be found in RFC\-2046.
+can be found in RFC 2046.

 .PP
 A list of commonly used contents is briefly reproduced here:
 .PP
 .PP
 A list of commonly used contents is briefly reproduced here:
 .PP


@@ -152,18 +156,21 @@ If this entry isn't present,
 the current working directory is used.
 .PP
 If the
 the current working directory is used.
 .PP
 If the

+.B \-outfile
+switch is given, its argument is used for the filename to store all
+of the content, with \*(lq-\*(rq indicating standard output.  If the

 .B \-auto
 switch is given, then
 .B mhstore
 .B \-auto
 switch is given, then
 .B mhstore

-will check if
-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,
-this switch is not the default, and it is recommended that you do
-NOT put the
+will check if the message contains information indicating the filename
+that should be used to store the content.  This information should be
+specified as the \*(lqfilename\*(rq attribute in the
+\*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
+attribute 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, this switch is not the
+default, and it is recommended that you do NOT put the

 .B \-auto
 switch in your
 .I \&.mh\(ruprofile
 .B \-auto
 switch in your
 .I \&.mh\(ruprofile


@@ -218,7 +225,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


@@ -266,6 +275,72 @@ 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 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
 .SS "Reassembling Messages of Type message/partial"
 .B mhstore
 is also able to reassemble messages that have been


@@ -325,6 +400,8 @@ ftp
 local-file
 .IP \(bu 4
 mail-server
 local-file
 .IP \(bu 4
 mail-server

+.IP \(bu 4
+url

 .PP
 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
 .B mhstore
 .PP
 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
 .B mhstore


@@ -353,10 +430,18 @@ local filename
 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
+For the \*(lqurl\*(rq access types,

 .B mhstore
 .B mhstore

-will use a simple
-built-in FTP client to perform the retrieval.
+will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
+.PP
+.RS 5
+nmh-access-url: curl -l
+.RE
+.PP
+to determine the program to use to perform the HTTP retrieval.  This program
+is invoked with one argument: the URL of the content to retrieve.  The program
+should write the content to standard out, and should terminate with a status of zero if the retrieval is successful and a non\-zero exit status otherwise.
+.PP

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


@@ -433,8 +518,16 @@ user profile, e.g.,
 which is created automatically during
 .B nmh
 installation.
 which is created automatically during
 .B nmh
 installation.

-

 .SH FILES
 .SH FILES

+.B mhstore
+looks for additional profile files in multiple locations: absolute
+pathnames are accessed directly, tilde expansion is done on usernames,
+and files are searched for in the user's
+.I Mail
+directory as specified in their profile.  If not found there, the directory
+.RI \*(lq %etcdir% \*(rq
+is checked.
+.PP

 .fc ^ ~
 .nf
 .ta \w'%etcdir%/ExtraBigFileName  'u
 .fc ^ ~
 .nf
 .ta \w'%etcdir%/ExtraBigFileName  'u


@@ -442,7 +535,6 @@ installation.
 ^$MHSTORE~^Additional profile entries
 ^%etcdir%/mhn.defaults~^System default MIME profile entries
 .fi
 ^$MHSTORE~^Additional profile entries
 ^%etcdir%/mhn.defaults~^System default MIME profile entries
 .fi

-

 .SH "PROFILE COMPONENTS"
 .fc ^ ~
 .nf
 .SH "PROFILE COMPONENTS"
 .fc ^ ~
 .nf


@@ -451,27 +543,28 @@ installation.
 ^Path:~^To determine the user's nmh directory
 ^Current\-Folder:~^To find the default current folder
 ^nmh-access-ftp:~^Program to retrieve contents via FTP
 ^Path:~^To determine the user's nmh directory
 ^Current\-Folder:~^To find the default current folder
 ^nmh-access-ftp:~^Program to retrieve contents via FTP

+^nmh-access-url:~^Program to retrieve contents via HTTP

 ^nmh-cache~^Public directory to store cached external contents
 ^nmh-private-cache~^Personal directory to store cached external contents
 ^nmh-storage~^Directory to store contents
 ^mhstore-store-<type>*~^Template for storing contents
 .fi
 ^nmh-cache~^Public directory to store cached external contents
 ^nmh-private-cache~^Personal directory to store cached external contents
 ^nmh-storage~^Directory to store contents
 ^mhstore-store-<type>*~^Template for storing contents
 .fi

-

 .SH "SEE ALSO"
 .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 '
 .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 ` \-nocheck '
 .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 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.
 .SH BUGS
 Partial messages contained within a multipart content are not reassembled.