.\"
.TH SHOW %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
-show \- show (display) messages
+show \- display (MIME) messages
+.PP
+next \- show the next message
+.PP
+prev \- show the previous message
.SH SYNOPSIS
.HP 5
.na
.B show
.RI [ +folder ]
.RI [ msgs ]
-.RB [\-showproc
-.IR program ]
-.RB [ \-showmimeproc
-.IR program ]
-.RB [ \-header " | " \-noheader ]
-.RB [ \-checkmime " | " \-nocheckmime ]
-[switches\ for
-.I showproc
-or
-.IR showmimeproc ]
-.RB [ \-version ]
+.RB [ \-file
+.IR file ]
+.RB [ \-part
+.IR number ]
+\&...
+.RB [ \-type
+.IR content ]
+\&...
+.RB [ \-form
+.IR formfile ]
+.RB [ \-Version ]
.RB [ \-help ]
+.PP
+.HP 5
+.B next
+is equivalent to
+.B show n
+.PP
+.HP 5
+.B prev
+is equivalent to
+.B show p
.ad
+
+.SH NOTE
+This (i.e. mmh's) version of
+.B show
+is a modified version of nmh's
+.B mhshow
+program.
+The old (non-MIME)
+.B show
+program was removed from mmh.
+
.SH DESCRIPTION
-.B Show
-lists each of the specified messages to the standard output
-(typically, the terminal).
+The
+.B show
+command display contents of a MIME (multi-media)
+message or collection of messages.
+.B Next
+and
+.B prev
+perform a
+.B show
+on the next or previous message in the specified
+(or current) folder, respectively.
.PP
-By default, text (non-MIME) messages are filtered and displayed by
-the
-.B nmh
-command
-.BR mhl .
-This command will display text
-messages in a nice, uniform format. It also allows you to configure
-the format of the displayed messages and which headers fields are
-shown. See the
-.BR mhl (1)
-manual page for the details about this
-command. This default can be changed by defining the
-.I showproc
-profile component. Any switches not recognized by
.B show
-are
-passed along to that program. To override the default and the
-.I showproc
-profile component, use the
-.B \-showproc
-.I program
-switch. For example,
-.B \-showproc
-.I more
-will cause the
-.B more
-program to list the messages with no reformatting. Normally, this
-program is specified as the
-.I showproc
-in the user's profile,
-rather than using a command line switch.
-.PP
-By default, non-text messages (MIME messages with multi-media
-contents) are processed and displayed by the
-.B nmh
-command
-.BR mhshow .
-See the
-.BR mhshow (1)
-manual page for details
-about this command. This default can changed by defining the
-.I showmimeproc
-profile component. Any switches not recognized
-by
+manipulates multi-media messages as specified in
+RFC\-2045 thru RFC\-2049. Currently
.B show
-are passed along to that program. To override this
-default and the
-.B showmimeproc
-profile component, use the
-.B \-showmimeproc
-.I program
-switch.
-.PP
-Note that in some cases,
+only supports
+encodings in message bodies, and does not support the encoding of
+message headers as specified in RFC\-2047.
+.PP
+By default
.B show
-may invoke the
-.I showmimeproc
-even for textual contents. This will happen for text messages that
-specify a transfer encoding (such as MIME quoted-printable or
-base64) or specify a character set that
+will display all parts of a multipart
+message. By using the
+.B \-part
+and
+.B \-type
+switches, you may
+limit the scope of
.B show
-doesn't believe
-can be displayed natively. The environment variable
-.B $MM_CHARSET
-should be set to the terminal's native character set to avoid
-gratuitous invocations of the
-.IR showmimeproc .
-See the
-.BR mh-profile (5)
-man page for details about this environment variable.
+to particular subparts (of a
+multipart content) and/or particular content types.
.PP
The option
-.B \-checkmime
-(set by default) instructs
+.B \-file
+.I file
+directs
.B show
-to
-test if any of the messages to be displayed are non-text (MIME)
-messages. If any are non-text, they are displayed by the program
-.IR showmimeproc ,
-else they are displayed by the program
-.IR showproc .
-The option
-.B \-nocheckmime
-disables this test and instructs
+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 show
-to use
-.IR showproc ,
-regardless of whether
-any of the messages are non-text (MIME) messages.
-.P
-The
-.B \-noshowproc
-switch will disable any formatting or paging of
-messages. It is equivalent to
-.B \-nocheckmime
-.B \-showproc
-.IR cat .
-It is still accepted, but should be considered (somewhat) obsolete.
-.PP
-If the environment variable
-.B $NOMHNPROC
-is set, the test for
-non-text (MIME) messages will be disabled. This method is obsolete.
-Use the
-.B \-nocheckmime
-switch instead.
+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
-The
-.B \-header
-switch tells
+When displaying multiple messages,
.B show
-to display a one\-line
-description of the message being shown. This description includes
-the folder and the message number.
+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
-If no `msgs' are specified, the current message is used. Although
-it depends on the specific
-.I showproc
-or
-.IR showmimeproc ,
-in the default setup when more than one message is specified, you
-will be prompted for a <RETURN> prior to listing each message.
-Each message will be listed a page at a time, and when the end of
-page is reached, the program will wait for a <SPACE> or <RETURN>.
-If a <RETURN> is entered, it will print the next line, whereas
-<SPACE> will print the next screenful.
-.PP
-If the standard output is not a terminal, no queries are made, and
-each file is listed with a one\-line header and two lines of
-separation.
+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 show
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 show
+is outputting to a terminal, then
+a pager will be placed between the terminal and
+.BR show .
+.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 \*(lqshow\*(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 show
+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 show
+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 show
+is display a content, typing QUIT (usually
+control-\\) will tell
+.B show
+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 show
+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 show
+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 show
+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 show
+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 show
+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 show
+encounters a \*(lqcharset\*(rq parameter for
+this content, it checks if your terminal can display this character
+set natively.
+.B show
+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 '<source-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 show
+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 show
+operates may vary for
+different machines,
+.B show
+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 show
+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"
^Path:~^To determine the user's mail storage
^Current\-Folder:~^To find the default current folder
^Unseen\-Sequence:~^To name sequences denoting unseen messages
-^showproc:~^Program to show text (non-MIME) messages
-^showmimeproc:~^Program to show non-text (MIME) messages
+^mhshow-show-<type>*~^Template for displaying contents
+^Pager:~^Program to use as interactive front\-end
.fi
.SH "SEE ALSO"
-mhl(1), mhshow(1), more(1), next(1), prev(1), scan(1)
+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 ` \-checkmime '
-.RB ` \-header '
+.RB ` \-form \ mhl.headers'
+.RB ` \-noverbose '
.fi
.SH CONTEXT
If a folder is given, it will become the current folder. The last
-message shown will become the current message.
+message selected will become the current message.
.SH BUGS
-The
-.B \-header
-switch doesn't work when `msgs' expands to more than
-one message. If the
-.I showproc
-is
-.BR mhl ,
-then this problem can
-be circumvented by referencing the \*(lqmessagename\*(rq field in the
-.B mhl
-format file.
-.PP
-.B Show
-updates the user's context before showing the message.
-Hence
+.B Next
+and
+.B prev
+are really links to the
.B show
-will mark messages as seen prior to the user actually
-seeing them. This is generally not a problem, unless the user relies
-on the \*(lqunseen\*(rq messages mechanism, and interrupts
-.B show
-while it is showing \*(lqunseen\*(rq messages.
-.PP
-If your
-.I showproc
-is
-.B mhl
-(the default), then
-.B show
-uses
-a built\-in
-.BR mhl :
-it does not actually run the
-.B mhl
-program.
-Hence, if you define your own
-.B showproc ,
-don't call it
-.B mhl
-since
-.B show
-won't run it.
-.PP
-If your
-.I showproc
-is the pager
-.BR more ,
-then avoid running
+program. As a result, if
+you make a link to
+.B next
+or
+.B prev
+and that link is not called
+.B next
+or
+.BR prev ,
+your link will act like
.B show
-in the background with only its standard output piped to
-another process, as in
-.PP
-.RS 5
-show | imprint &
-.RE
-.PP
-Due to a bug in
-.BR more ,
-show will go into a \*(lqtty input\*(rq state.
-To avoid this problem, re\-direct
-.BR show 's
-diagnostic output as well.
-For users of
-.BR csh :
-.PP
-.RS 5
-show |& imprint &
-.RE
-.PP
-For users of
-.BR sh :
-.PP
-.RS 5
-show 2>&1 | imprint &
-.RE
+instead. To circumvent this, add a
+profile\-entry for the link to your
+.B nmh
+profile and add the argument
+.I n
+or
+.I p
+to the entry.
projects / mmh / blobdiff