-.\"
-.\" %nmhwarning%
-.\"
-.TH MHSHOW %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
-.SH NAME
-mhshow \- display MIME messages
-.SH SYNOPSIS
-.HP 5
-.na
-.B mhshow
-.RI [ +folder ]
-.RI [ msgs ]
-.RB [ \-file
-.IR file ]
-.RB [ \-part
-.IR number ]
-\&...
-.RB [ \-type
-.IR content ]
-\&...
-.RB [ \-form
-.IR formfile ]
-.RB [ \-version ]
-.RB [ \-help ]
-.ad
-.SH DESCRIPTION
-The
-.B mhshow
-command display contents of a MIME (multi-media)
-message or collection of messages.
-.PP
-.B mhshow
-manipulates multi-media messages as specified in
-RFC\-2045 thru RFC\-2049. Currently
-.B mhshow
-only supports
-encodings in message bodies, and does not support the encoding of
-message headers as specified in RFC\-2047.
-.PP
-By default
-.B mhshow
-will display all parts of a multipart
-message. By using the
-.B \-part
-and
-.B \-type
-switches, you may
-limit the scope of
-.B mhshow
-to particular subparts (of a
-multipart content) and/or particular content types.
-.PP
-The option
-.B \-file
-.I file
-directs
-.B mhshow
-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 mhshow
-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
-When displaying multiple messages,
-.B mhshow
-prepends each of them with a `>>> Message nnn' header,
-and separates the messages with two lines of space.
-This is similar to the way
-.B mhl
-acts on multiple files.
-.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 `\-type' switch, a
-multipart content (of any subtype listed above) is always acted upon.
-.SS "Unseen Sequence"
-If the profile entry \*(lqUnseen\-Sequence\*(rq is present and
-non\-empty, then
-.B mhshow
-will remove each of the messages shown
-from each sequence named by the profile entry.
-.SS "Showing the Contents"
-.B Mhshow
-prints messages in a convenient representation.
-If
-.B mhshow
-is outputting to a terminal, then
-a pager will be placed between the terminal and
-.BR mhshow .
-.PP
-The headers of each message are displayed with
-.B mhl
-using the standard format file
-.IR mhl.headers .
-You may specify an alternate format file with the
-.B \-form
-.I formfile
-switch. If the format file
-.I mhl.null
-is specified, then the display
-of the message headers is suppressed.
-.PP
-Next, the contents are extracted from the message and are stored in
-a temporary file. Usually, the name of the temporary file is the
-word \*(lqmhshow\*(rq followed by a string of characters. Occasionally,
-the method used to display a content (described next), requires that
-the file end in a specific suffix. For example, the
-.B soffice
-command (part of the StarOffice package) can be used to display
-Microsoft Word content, but it uses the suffix to determine how to display
-the file. If no suffix is present, the file is not correctly loaded.
-Similarily, older versions of the
-.B gs
-command append a \*(lq.ps\*(rq suffix to
-the filename if one was missing. As a result, these cannot be used to read
-the default temporary file.
-.PP
-To get around this, your profile can contain lines of the forms:
-.PP
-.RS 5
-.nf
-mhshow-suffix-<type>/<subtype>: <suffix>
-mhshow-suffix-<type>: <suffix>
-.fi
-.RE
-.PP
-to specify a suffix which can be automatically added to the temporary
-file created for a specific content type. For example, the following
-lines might appear in your profile:
-.PP
-.RS 5
-.nf
-mhshow-suffix-text: .txt
-mhshow-suffix-application/msword: .doc
-mhshow-suffix-application/PostScript: .ps
-.fi
-.RE
-.PP
-to automatically append a suffix to the temporary files.
-.PP
-The method used to display the different contents in the messages bodies
-will be determined by a \*(lqdisplay string\*(rq. To find the display
-string,
-.B mhshow
-will first search your profile for an entry of the form:
-.PP
-.RS 5
-mhshow-show-<type>/<subtype>
-.RE
-.PP
-to determine the display string. If this isn't found,
-.B mhshow
-will search for an entry of the form:
-.PP
-.RS 5
-mhshow-show-<type>
-.RE
-.PP
-to determine the display string.
-.PP
-If a display string is found, any escapes (given below) will be expanded.
-The result will be executed under
-\*(lq/bin/sh\*(rq, with the standard input
-set to the content.
-.PP
-The display string may contain the following escapes:
-.PP
-.RS 5
-.nf
-.ta \w'%F 'u
-%l Display listing prior to displaying content
-%f Insert filename containing content
-%F %f, but stdin is terminal not content
-%a Insert parameters from Content-Type field
-%s Insert content subtype
-%c Insert foreign charset
-%d Insert content description
-%% The character %
-.fi
-.RE
-.PP
-.B Mhshow
-processes the MIME parts serially, i.e. the next display process
-is executed after the previous one has terminated.
-.PP
-Further, when
-.B mhshow
-is display a content, typing QUIT (usually
-control-\\) will tell
-.B mhshow
-to wrap things up immediately.
-.PP
-Note that if the content being displayed is multipart, but not one of
-the subtypes listed above, then the f- and F-escapes expand to multiple
-filenames, one for each subordinate content. Further, stdin is not
-redirected from the terminal to the content.
-.PP
-If a display string is not found,
-.B mhshow
-has the following default values:
-.PP
-.RS 5
-.nf
-mhshow-show-text/plain: %liconv -f <source-charset>
-mhshow-show-message/rfc822: %lshow \-file %F
-.fi
-.RE
-.PP
-If a subtype of type text doesn't have a profile entry, it will be
-treated as text/plain.
-.PP
-.B mhshow
-has default methods for handling multipart messages of subtype
-mixed, alternative, parallel, and digest. Any unknown subtype of type
-multipart (without a profile entry), will be treated as multipart/mixed.
-.PP
-If none of these apply, then
-.B mhshow
-will complain.
-.PP
-Example entries might be:
-.PP
-.RS 5
-.nf
-mhshow-show-audio/basic: raw2audio 2>/dev/null | play
-mhshow-show-image: xv %f
-mhshow-show-application/PostScript: lpr -Pps
-.fi
-.RE
-.PP
-When expanding %f and %F escapes, the file names get wrapped in
-single-quotes automatically.
-.PP
-Finally,
-.B mhshow
-will process each message serially \- it won't start
-showing the next message until all the commands executed to display the
-current message have terminated. Although a multipart content may
-contain advice to display the parts in parallel,
-.B mhshow
-will never do so.
-.SS "Showing Alternate Character Sets"
-Because a content of type text might be in a non-ASCII character
-set, when
-.B mhshow
-encounters a \*(lqcharset\*(rq parameter for
-this content, it checks if your terminal can display this character
-set natively.
-.B mhshow
-checks this by first examining the the environment
-variable
-.B $MM_CHARSET
-and if not set, taking the character encoding of the current locale.
-.PP
-If the character set of text/plain cannot be displayed natively, then
-the default display method converts the content automatically by
-piping it through:
-.PP
-.RS 5
-iconv -f '<foreign-charset>'
-.RE
-.PP
-Note that if you have a custom `mhshow-show-*' display string, you
-need to care yourself for converting the encodings.
-(The foreign charset is available through the %c escape.)
-.PP
-The tool
-.B iconv
-needs to be available.
-.PP
-`mhshow-charset-*' profile entries are not supported anymore.
-.SS "Messages of Type message/partial"
-.B mhshow
-cannot directly display messages of type partial.
-You must reassemble them first into a normal message using
-.BR mhstore .
-Check the man page for
-.BR mhstore (1)
-for details.
-.SS "External Access"
-.B Mhshow
-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 mhshow
-operates may vary for
-different machines,
-.B mhshow
-will look for the environment variable
-.BR $MHSHOW .
-If present, this specifies the name of an additional
-user profile which should be read. Hence, when a user logs in on a
-particular display device, this environment variable should be set to
-refer to a file containing definitions useful for the given display device.
-Normally, only entries that deal with the methods to display different
-content type and subtypes
-.PP
-.RS 5
-.nf
-mhshow-show-<type>/<subtype>
-mhshow-show-<type>
-.fi
-.RE
-.PP
-need be present in this additional profile. Finally,
-.B mhshow
-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
-^$MHSHOW~^Additional profile entries
-^%etcdir%/mhn.defaults~^System default MIME profile entries
-^%etcdir%/mhl.headers~^The headers template
-.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
-^Unseen\-Sequence:~^To name sequences denoting unseen messages
-^mhshow-show-<type>*~^Template for displaying contents
-^Pager:~^Program to use as interactive front\-end
-.fi
-
-.SH "SEE ALSO"
-mhbuild(1), mhl(1), mhlist(1), mhstore(1), sendfiles(1)
-
-.SH DEFAULTS
-.nf
-.RB ` +folder "' defaults to the current folder"
-.RB ` msgs "' defaults to cur"
-.RB ` \-form \ mhl.headers'
-.RB ` \-noverbose '
-.fi
-
-.SH CONTEXT
-If a folder is given, it will become the current folder. The last
-message selected will become the current message.
projects / mmh / commitdiff