Renamed -version switch to -Version to remove the conflict with -verbose.

[mmh] / man / mhstore.man1

diff --git a/man/mhstore.man1 b/man/mhstore.man1
index faf8ea5..e92a82f 100644 (file)
--- a/man/mhstore.man1
+++ b/man/mhstore.man1
@@ -19,7 +19,7 @@ mhstore \- store contents of MIME messages into files
 .IR content ]
 \&...
 .RB [ \-auto " | " \-noauto ]
 .IR content ]
 \&...
 .RB [ \-auto " | " \-noauto ]

-.RB [ \-version ]
+.RB [ \-Version ]

 .RB [ \-help ]
 .ad
 .SH DESCRIPTION
 .RB [ \-help ]
 .ad
 .SH DESCRIPTION

@@ -112,19 +112,28 @@ Note that regardless of the values given to the
 .B \-type
 switch,
 a multipart content (of any subtype listed above) is always acted
 .B \-type
 switch,
 a multipart content (of any subtype listed above) is always acted

-upon.  Further note that if the
-.B \-type
-switch is used, and it is
-desirable to act on a message/external-body content, then the
-.B \-type
-switch must be used twice: once for message/external-body
-and once for the content externally referenced.
+upon.

 .SS "Storing the Contents"
 The
 .B mhstore
 will store the contents of the named messages in
 \*(lqnative\*(rq (decoded) format.  Two things must be determined:
 .SS "Storing the Contents"
 The
 .B mhstore
 will store the contents of the named messages in
 \*(lqnative\*(rq (decoded) format.  Two things must be determined:

-the directory to store the content, and the filenames.  Files are
+the directory to store the content, and the filenames.
+.PP
+By default (or if the
+.B \-auto
+switch is given),
+.B mhstore
+uses filename information, contained in the message, if available.
+(This information should be specified
+as the attribute \*(lqname=filename\*(rq in the \*(lqContent-Type\*(rq header
+for the content you are storing.)
+Only the basename of this filename is considered.
+If it begins with the character '.', '|', or '!',
+or if it contains the character '%', automatic naming won't happen for
+security reasons. (See below for the fall-back.)
+.PP
+Files are

 written in the directory given by the \*(lqnmh-storage\*(rq profile
 entry, e.g.,
 .PP
 written in the directory given by the \*(lqnmh-storage\*(rq profile
 entry, e.g.,
 .PP

@@ -132,30 +141,17 @@ entry, e.g.,
 nmh-storage: /tmp
 .RE
 .PP
 nmh-storage: /tmp
 .RE
 .PP

+(Note that \*(lqnmh-storage\*(rq is relative to the folder that contains
+the message.)

 If this entry isn't present,
 the current working directory is used.
 If this entry isn't present,
 the current working directory is used.

-.PP
-By default (or if the
-.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 '%'. Now that tar files are not extracted
-automatically anymore, having
-.B \-auto
-as the default is quite safe.
-Attachments are only stored below the current (or the storage)
-directory. In the worst case, existing files there will be overwritten.
+Attachments will get stored in either the `nmh-storage' or the current working
+directory \(en in no case elsewhere.
+Existing files get silently overwritten.

 .PP
 If the
 .PP
 If the

-.B \-auto
-switch is not given (or is being ignored for security
-reasons) then
+.B \-noauto
+switch is given (or a filename is being ignored for security reasons) then

 .B mhstore
 will look in the user's profile for a
 \*(lqformatting string\*(rq to determine how the different contents
 .B mhstore
 will look in the user's profile for a
 \*(lqformatting string\*(rq to determine how the different contents

@@ -183,7 +179,7 @@ content is stored in the named folder.  A formatting string consisting
 solely of a \*(lq+\*(rq character is interpreted to be the current
 folder.
 .PP
 solely of a \*(lq+\*(rq character is interpreted to be the current
 folder.
 .PP

-If the formatting string consists solely of a \*(lq-\*(rq character,
+If the formatting string consists solely of a \*(lq\-\*(rq character,

 then the content is sent to the standard output.
 .PP
 If the formatting string starts with a '|', then the display string
 then the content is sent to the standard output.
 .PP
 If the formatting string starts with a '|', then the display string

@@ -199,11 +195,9 @@ escapes (given below) in the display string will be expanded.
 Otherwise the formatting string will represent a pathname in which
 to store the content.  If the formatting string starts with a '/',
 then the content will be stored in the full path given, else the
 Otherwise the formatting string will represent a pathname in which
 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.  Note that if \*(lqnmh-storage\*(rq
-is not an absolute path, it will be relative to the folder that
-contains the message(s).
+file name will be relative to either the value of \*(lqnmh-storage\*(rq,
+if set, or the current working directory.
+Existing files get silently overwritten.

 .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

@@ -291,46 +285,10 @@ locate every partial necessary to reassemble the message, it will
 not store anything.
 .RE
 .SS "External Access"
 not store anything.
 .RE
 .SS "External Access"

-For contents of type message/external-body,
-\fImhstore\fR supports these access-types:
-.PP
-.IP \(bu 4
-afs
-.IP \(bu 4
-anon-ftp
-.IP \(bu 4
-ftp
-.IP \(bu 4
-local-file
-.IP \(bu 4
-mail-server
-.PP
-For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
-.B mhstore
-will look for the \*(lqnmh-access-ftp\*(rq
-profile entry, e.g.,
-.PP
-.RS 5
-nmh-access-ftp: myftp.sh
-.RE
-.PP
-to determine the pathname of a program to perform the FTP retrieval.
-This program is invoked with these arguments:
-.PP
-.RS 5
-.nf
-domain name of FTP-site
-username
-password
-remote directory
-remote filename
-local filename
-\*(lqascii\*(rq or \*(lqbinary\*(rq
-.fi
-.RE
-.PP
-The program should terminate with an exit status of zero if the
-retrieval is successful, and a non-zero exit status otherwise.
+.B Mhstore
+does not automatically retrieve message/external-body parts (anymore),
+but prints the relevant information to enable the user to retrieve
+the files manually.

 .SS "User Environment"
 Because the display environment in which
 .B mhstore
 .SS "User Environment"
 Because the display environment in which
 .B mhstore

@@ -372,13 +330,12 @@ installation.
 .ta \w'ExtraBigProfileName  'u
 ^Path:~^To determine the user's mail storage
 ^Current\-Folder:~^To find the default current folder
 .ta \w'ExtraBigProfileName  'u
 ^Path:~^To determine the user's mail storage
 ^Current\-Folder:~^To find the default current folder

-^nmh-access-ftp:~^Program to retrieve contents via FTP

 ^nmh-storage~^Directory to store contents
 ^mhstore-store-<type>*~^Template for storing contents
 .fi
 
 .SH "SEE ALSO"
 ^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)
+mhbuild(1), mhlist(1), show(1), sendfiles(1)

 
 .SH DEFAULTS
 .nf
 
 .SH DEFAULTS
 .nf

@@ -392,3 +349,5 @@ 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.

+.PP
+Existing files get silently overwritten.