X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=man%2Fshow.man1;h=1fcfacd6a8e8b28ec9b66c05e3074f64af5f4ef5;hp=b46712221fb62e1d8ed399b06646c882be17df94;hb=32b2354dbaf4bf934936eb5b102a4a3d2fdd209a;hpb=ff2832024ce5363103365c0caff85e75e4590b83 diff --git a/man/show.man1 b/man/show.man1 index b467122..1fcfacd 100644 --- a/man/show.man1 +++ b/man/show.man1 @@ -3,7 +3,7 @@ .\" .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 @@ -14,17 +14,17 @@ prev \- show the previous message .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 @@ -38,10 +38,21 @@ 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 @@ -50,98 +61,348 @@ perform a 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. Any switches not recognized by -.B show -are -passed along to that program. To override the default, 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. -.PP -By default, MIME messages are processed and displayed by the -.B nmh -command -.BR mhshow . -See the -.BR mhshow (1) -manual page for details -about this command. -Any switches not recognized -by -.B show -are passed along to that program. To override this -default, use the -.B \-showmimeproc -.I program -switch. -.PP -Note that, -.B show -will invoke the -.I showmimeproc -even for textual contents if the message has a MIME-Version header. +.B show +manipulates multi-media messages as specified in +RFC\-2045 thru RFC\-2049. Currently +.B show +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 +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 +to particular subparts (of a +multipart content) and/or particular content types. .PP The option -.B \-checkmime -(set by default) instructs -.B show -to check if any of the messages contains a MIME-Version header. -If so, they are displayed by the -.IR showmimeproc , -else they are displayed by the -.BR showproc . -The option -.B \-nocheckmime -disables this test and instructs +.B \-file +.I file +directs .B show -to use -.IR showproc , -regardless of whether -any of the messages are MIME messages. +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 +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 +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 -If no `msgs' are specified, the current message is used. +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 -If the standard output is a terminal, output will be piped through -a pager. -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 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-/: +mhshow-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-/ +.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- +.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 +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 '' +.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-/ +mhshow-show- +.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" @@ -152,79 +413,26 @@ from each sequence named by the profile entry. ^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-*~^Template for displaying contents +^Pager:~^Program to use as interactive front\-end .fi .SH "SEE ALSO" -mhl(1), mhshow(1), more(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 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 the pager -.BR more , -then avoid running -.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 -.PP .B Next and .B prev