X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=man%2Fshow.man1;h=1fcfacd6a8e8b28ec9b66c05e3074f64af5f4ef5;hp=47cf7d00f9ca61ecbb47e7e48e2538e7cef9e5fc;hb=32b2354dbaf4bf934936eb5b102a4a3d2fdd209a;hpb=2d2016f0dfc9e036549ff035f0ae897c9b2d5fe4 diff --git a/man/show.man1 b/man/show.man1 index 47cf7d0..1fcfacd 100644 --- a/man/show.man1 +++ b/man/show.man1 @@ -3,156 +3,406 @@ .\" .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 -.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, -.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 -.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. +.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 -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 +.B \-file +.I file +directs .B show -to use -.IR showproc , -regardless of whether -any of the messages are non-text (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 -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 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 or . -If a is entered, it will print the next line, whereas - 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-/: +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" @@ -163,77 +413,47 @@ 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 -^showproc:~^Program to show text (non-MIME) messages -^showmimeproc:~^Program to show non-text (MIME) 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), 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 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 Next +and +.B prev +are really links to the .B show -while it is showing \*(lqunseen\*(rq messages. -.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.