+++ /dev/null
-.\"
-.\" %nmhwarning%
-.\"
-.TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
-.SH NAME
-mhstore \- store contents of MIME messages into files
-.SH SYNOPSIS
-.HP 5
-.na
-.B mhstore
-.RI [ +folder ]
-.RI [ msgs ]
-.RB [ \-file
-.IR file ]
-.RB [ \-part
-.IR number ]
-\&...
-.RB [ \-type
-.IR content ]
-\&...
-.RB [ \-auto " | " \-noauto ]
-.RB [ \-verbose " | " \-noverbose ]
-.RB [ \-rcache
-.IR policy ]
-.RB [ \-wcache
-.IR policy ]
-.RB [ \-check " | " \-nocheck ]
-.RB [ \-version ]
-.RB [ \-help ]
-.ad
-.SH DESCRIPTION
-The
-.B mhstore
-command allows you to store the contents of a
-collection of MIME (multi-media) messages into files or other
-messages.
-.PP
-.B mhstore
-manipulates multi-media messages as specified in
-RFC\-2045 thru RFC\-2049.
-.PP
-By default,
-.B mhstore
-will store all the parts of each message.
-Each part will be store in a separate file. The header fields of
-the message are not stored. By using the
-.B \-part
-and
-.B \-type
-switches, you may limit the scope of
-.B mhstore
-to particular
-subparts (of a multipart content) and/or particular content types.
-.PP
-The option
-.B \-file
-.I file
-directs
-.B mhstore
-to use the specified
-file as the source message, rather than a message from a folder.
-If you specify this file as \*(lq-\*(rq, then
-.B mhstore
-will
-accept the source message on the standard input. Note that the
-file, or input from standard input should be a validly formatted
-message, just like any other
-.B nmh
-message. It should
-.B NOT
-be in mail drop format (to convert a file in mail drop format to
-a folder of
-.B nmh
-messages, see
-.BR inc (1)).
-.PP
-A part specification consists of a series of numbers separated by
-dots. For example, in a multipart content containing three parts,
-these would be named as 1, 2, and 3, respectively. If part 2 was
-also a multipart content containing two parts, these would be named
-as 2.1 and 2.2, respectively. Note that the
-.B \-part
-switch is
-effective for only messages containing a multipart content. If a
-message has some other kind of content, or if the part is itself
-another multipart content, the
-.B \-part
-switch will not prevent
-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
-can be found in RFC\-2046.
-.PP
-A list of commonly used contents is briefly reproduced here:
-.PP
-.RS 5
-.nf
-.ta \w'application 'u
-Type Subtypes
----- --------
-text plain, enriched
-multipart mixed, alternative, digest, parallel
-message rfc822, partial, external-body
-application octet-stream, postscript
-image jpeg, gif, png
-audio basic
-video mpeg
-.fi
-.RE
-.PP
-A legal MIME message must contain a subtype specification.
-.PP
-To specify a content, regardless of its subtype, just use the name
-of the content, e.g., \*(lqaudio\*(rq. To specify a specific
-subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
-Note that regardless of the values given to the
-.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.
-.SS "Checking the Contents"
-The
-.B \-check
-switch tells
-.B mhstore
-to check each content for
-an integrity checksum. If a content has such a checksum (specified
-as a Content-MD5 header field), then
-.B mhstore
-will attempt to
-verify the integrity of the content.
-.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
-written in the directory given by the \*(lqnmh-storage\*(rq profile
-entry, e.g.,
-.PP
-.RS 5
-nmh-storage: /tmp
-.RE
-.PP
-If this entry isn't present,
-the current working directory is used.
-.PP
-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 '%'. 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 \&.mmh/profile
-file.
-.PP
-If the
-.B \-auto
-switch is not given (or 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
-should be stored. First,
-.B mhstore
-will look for an entry of
-the form:
-.PP
-.RS 5
-mhstore-store-<type>/<subtype>
-.RE
-.PP
-to determine the formatting string. If this isn't found,
-.B mhstore
-will look for an entry of the form:
-.PP
-.RS 5
-mhstore-store-<type>
-.RE
-.PP
-to determine the formatting string.
-.PP
-If the formatting string starts with a \*(lq+\*(rq character, then
-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
-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
-will represent a command for
-.B mhstore
-to execute which should
-ultimately store the content. The content will be passed to the
-standard input of the command. Before the command is executed,
-.B mhstore
-will change to the appropriate directory, and any
-escapes (given below) in the display string will be expanded.
-.PP
-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.
-.PP
-A command or pathname formatting string may contain the following
-escapes. If the content isn't part of a multipart (of any subtype
-listed above) content, the p-escapes are ignored.
-.PP
-.RS 5
-.nf
-.ta \w'%P 'u
-%a Parameters from Content-type (only valid with command)
-%m Insert message number
-%P Insert part number with leading dot
-%p Insert part number without leading dot
-%t Insert content type
-%s Insert content subtype
-%% Insert character %
-.fi
-.RE
-.PP
-If no formatting string is found,
-.B mhstore
-will check to see
-if the content is application/octet-stream with parameter
-\*(lqtype=tar\*(rq. If so,
-.B mhstore
-will choose an appropriate
-filename. If the content is not application/octet-stream, then
-.B mhstore
-will check to see if the content is a message. If
-so,
-.B mhstore
-will use the value \*(lq+\*(rq. As a last resort,
-.B mhstore
-will use the value \*(lq%m%P.%s\*(rq.
-.PP
-Example profile entries might be:
-.PP
-.RS 5
-.nf
-mhstore-store-text: %m%P.txt
-mhstore-store-text: +inbox
-mhstore-store-message/partial: +
-mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
-mhstore-store-image/jpeg: %m%P.jpg
-mhstore-store-application/PostScript: %m%P.ps
-.fi
-.RE
-.PP
-.SS "Reassembling Messages of Type message/partial"
-.B mhstore
-is also able to reassemble messages that have been
-split into multiple messages of type \*(lqmessage/partial\*(rq.
-.PP
-When asked to store a content containing a partial message,
-.B mhstore
-will try to locate all of the portions and combine
-them accordingly. The default is to store the combined parts as
-a new message in the current folder, although this can be changed
-using formatting strings as discussed above. Thus, if someone has
-sent you a message in several parts (such as the output from
-.BR sendfiles ),
-you can easily reassemble them all into a single
-message in the following fashion:
-.PP
-.RS 5
-.nf
-% mhlist 5-8
- msg part type/subtype size description
- 5 message/partial 47K part 1 of 4
- 6 message/partial 47K part 2 of 4
- 7 message/partial 47K part 3 of 4
- 8 message/partial 18K part 4 of 4
-% mhstore 5-8
-reassembling partials 5,6,7,8 to folder inbox as message 9
-% mhlist -verbose 9
- msg part type/subtype size description
- 9 application/octet-stream 118K
- (extract with uncompress | tar xvpf -)
- type=tar
- conversions=compress
-.fi
-.RE
-.PP
-This will store exactly one message, containing the sum of the
-parts. It doesn't matter whether the partials are specified in
-order, since
-.B mhstore
-will sort the partials, so that they
-are combined in the correct order. But if
-.B mhstore
-can not
-locate every partial necessary to reassemble the message, it will
-not store anything.
-.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.
-.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
-encounters an external content containing a
-\*(lqContent-ID:\*(rq field, and if the content allows caching, then
-depending on the caching behavior of
-.BR mhstore ,
-the content might be read from or written to a cache.
-.PP
-The caching behavior of
-.B mhstore
-is controlled with the
-.B \-rcache
-and
-.B \-wcache
-switches, which define the policy for reading from,
-and writing to, the cache, respectively. One of four policies may be
-specified: \*(lqpublic\*(rq, indicating that
-.B mhstore
-should make use
-of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
-that
-.B mhstore
-should make use of the user's private content cache;
-\*(lqnever\*(rq, indicating that
-.B mhstore
-should never make use of
-caching; and, \*(lqask\*(rq, indicating that
-.B mhstore
-should ask the user.
-.PP
-There are two directories where contents may be cached: the profile entry
-\*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
-the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
-private contents. The former should be an absolute (rooted) directory
-name.
-.PP
-For example,
-.PP
-.RS 5
-nmh-cache: /tmp
-.RE
-.PP
-might be used if you didn't care that the cache got wiped after each
-reboot of the system. The private chace is interpreted relative to the user's
-mail storage, if not rooted, e.g.,
-.PP
-.RS 5
-nmh-private-cache: .cache
-.RE
-.PP
-(which is the default value).
-.SS "User Environment"
-Because the display environment in which
-.B mhstore
-operates may vary for
-different machines,
-.B mhstore
-will look for the environment variable
-.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
-refer to a file containing definitions useful for that machine.
-Finally,
-.B mhstore
-will attempt to consult one other additional
-user profile, e.g.,
-.PP
-.RS 5
-%etcdir%/mhn.defaults
-.RE
-.PP
-which is created automatically during
-.B nmh
-installation.
-
-.SH FILES
-.fc ^ ~
-.nf
-.ta \w'%etcdir%/ExtraBigFileName 'u
-^$HOME/.mmh/profile~^The user profile
-^$MHSTORE~^Additional profile entries
-^%etcdir%/mhn.defaults~^System default MIME profile entries
-.fi
-
-.SH "PROFILE COMPONENTS"
-.fc ^ ~
-.nf
-.ta 2.4i
-.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-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"
-mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
-
-.SH DEFAULTS
-.nf
-.RB ` +folder "' defaults to the current folder"
-.RB ` msgs "' defaults to cur"
-.RB ` \-noauto '
-.RB ` \-nocheck '
-.RB ` \-rcache ask '
-.RB ` \-wcache ask '
-.RB ` \-noverbose '
-
-.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.
projects / mmh / blobdiff