Code style: Fixed indent and comment style.

[mmh] / man / mhshow.man1

diff --git a/man/mhshow.man1 b/man/mhshow.man1
index 9b6465d..d3326ac 100644 (file)
--- a/man/mhshow.man1
+++ b/man/mhshow.man1
@@ -71,6 +71,14 @@ mail drop format to a folder of
 messages, see
 .BR inc (1)).
 .PP
 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
 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

@@ -118,6 +126,14 @@ non\-empty, then
 will remove each of the messages shown
 from each sequence named by the profile entry.
 .SS "Showing the Contents"
 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
 The headers of each message are displayed with
 .B mhl
 using the standard format file

@@ -145,16 +161,13 @@ 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
 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 form:
+To get around this, your profile can contain lines of the forms:

 .PP
 .RS 5
 .PP
 .RS 5

+.nf

 mhshow-suffix-<type>/<subtype>: <suffix>
 mhshow-suffix-<type>/<subtype>: <suffix>

-.RE
-.PP
-or
-.PP
-.RS 5

 mhshow-suffix-<type>: <suffix>
 mhshow-suffix-<type>: <suffix>

+.fi

 .RE
 .PP
 to specify a suffix which can be automatically added to the temporary
 .RE
 .PP
 to specify a suffix which can be automatically added to the temporary

@@ -201,24 +214,20 @@ The display string may contain the following escapes:
 .RS 5
 .nf
 .ta \w'%F  'u
 .RS 5
 .nf
 .ta \w'%F  'u

-%a     Insert parameters from Content-Type field
-%e     exclusive execution
+%l     Display listing prior to displaying content

 %f     Insert filename containing content
 %f     Insert filename containing content

-%F     %e, %f, and stdin is terminal not content
-%l     display listing prior to displaying content
-%p     synonym to %l
+%F     %f, but stdin is terminal not content
+%a     Insert parameters from Content-Type field

 %s     Insert content subtype
 %s     Insert content subtype

+%c     Insert foreign charset

 %d     Insert content description
 %d     Insert content description

-%%     Insert the character %
+%%     The character %

 .fi
 .RE
 .PP
 .fi
 .RE
 .PP

-For those display strings containing the e- or F-escape,
-.B mhshow
-will
-execute at most one of these at any given time.  Although the F-escape
-expands to be the filename containing the content, the e-escape has no
-expansion as far as the shell is concerned.
+.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
 .PP
 Further, when
 .B mhshow

@@ -238,8 +247,8 @@ has the following default values:
 .PP
 .RS 5
 .nf
 .PP
 .RS 5
 .nf

-mhshow-show-text/plain: %l<defaultpager> '%F'
-mhshow-show-message/rfc822: %lshow \-file '%F'
+mhshow-show-text/plain: %liconv -f <source-charset>
+mhshow-show-message/rfc822: %lshow \-file %F

 .fi
 .RE
 .PP
 .fi
 .RE
 .PP

@@ -260,25 +269,22 @@ Example entries might be:
 .RS 5
 .nf
 mhshow-show-audio/basic: raw2audio 2>/dev/null | play
 .RS 5
 .nf
 mhshow-show-audio/basic: raw2audio 2>/dev/null | play

-mhshow-show-image: xv '%f'
+mhshow-show-image: xv %f

 mhshow-show-application/PostScript: lpr -Pps
 .fi
 .RE
 .PP
 mhshow-show-application/PostScript: lpr -Pps
 .fi
 .RE
 .PP

-Note that when using the f- or F-escape, it's a good idea to use
-single-quotes around the escape.  This prevents misinterpretation by
-the shell of any funny characters that might be present in the filename.
+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
 .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.  In the case of a multipart content
-(of any subtype listed above), the content contains advice indicating if
-the parts should be displayed serially or in parallel.  Because this may
-cause confusion, particularly on uni-window displays,
+current message have terminated.  Although a multipart content may
+contain advice to display the parts in parallel,

 .B mhshow
 .B mhshow

-will never display parts in parallel.
+will never do so.

 .SS "Showing Alternate Character Sets"
 Because a content of type text might be in a non-ASCII character
 set, when
 .SS "Showing Alternate Character Sets"
 Because a content of type text might be in a non-ASCII character
 set, when

@@ -286,95 +292,29 @@ set, when
 encounters a \*(lqcharset\*(rq parameter for
 this content, it checks if your terminal can display this character
 set natively.
 encounters a \*(lqcharset\*(rq parameter for
 this content, it checks if your terminal can display this character
 set natively.

-.B mhn
-checks this by examining the the environment
-variable
-.BR $MM_CHARSET .
-If the value of this environment variable is equal
-to the value of the charset parameter, then
-.B mhshow
-assumes it can
-display this content without any additional setup.  If this environment
-variable is not set,

 .B mhshow
 .B mhshow

-will assume a value of \*(lqUS-ASCII\*(rq.
-If the character set cannot be displayed natively, then
-.B mhshow
-will look for an entry of the form:
-.PP
-.RS 5
-mhshow-charset-<charset>
-.RE
-.PP
-which should contain a command creating an environment to render
-the character set.  This command string should containing a single
-\*(lq%s\*(rq, which will be filled-in with the command to display the
-content.
-.PP
-Example entries might be:
-.PP
-.RS 5
-mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*' -e %s
-.RE
+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
 .PP

-or
+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
 .PP
 .RS 5

-mhshow-charset-iso-8859-1: '%s'
+iconv -f '<foreign-charset>'

 .RE
 .PP
 .RE
 .PP

-The first example tells
-.B mhshow
-to start
-.B xterm
-and load the
-appropriate character set for that message content.  The second example
-tells
-.B mhshow
-that your pager (or other program handling that content
-type) can handle that character set, and that no special processing is
-needed beforehand.
-.PP
-Note that many pagers strip off the high-order bit or have problems
-displaying text with the high-order bit set.  However, the pager
-.B less
-has support for single-octet character sets.  The source
-to
-.B less
-is available on many ftp sites carrying free software.
-In order to view messages sent in the ISO-8859-1 character set using
-.BR less ,
-.PP
-put these lines in your
-.I \&.login
-file:
+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
 .PP

-.RS 5
-.nf
-setenv LESSCHARSET latin1
-setenv LESS "-f"
-.fi
-.RE
+The tool
+.B iconv
+needs to be available.

 .PP
 .PP

-The first line tells
-.B less
-to use the ISO-8859-1 definition for
-determining whether a character is \*(lqnormal\*(rq, \*(lqcontrol\*(lq,
-or \*(lqbinary\*(rq.  The second line tells
-.B less
-not to warn you
-if it encounters a file that has non-ASCII characters.  Then,
-set the
-.I Pager
-profile entry to
-.BR less ,
-and it will get
-called automatically.  (To handle other single-octet character sets,
-look at the
-.BR less (1)
-manual entry for information about the
-.B $LESSCHARDEF
-environment variable.)
+`mhshow-charset-*' profile entries are not supported anymore.

 .SS "Messages of Type message/partial"
 .B mhshow
 cannot directly display messages of type partial.
 .SS "Messages of Type message/partial"
 .B mhshow
 cannot directly display messages of type partial.

@@ -441,9 +381,8 @@ installation.
 ^Path:~^To determine the user's mail storage
 ^Current\-Folder:~^To find the default current folder
 ^Unseen\-Sequence:~^To name sequences denoting unseen messages
 ^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-charset-<charset>~^Template for environment to render character sets

 ^mhshow-show-<type>*~^Template for displaying contents
 ^mhshow-show-<type>*~^Template for displaying contents

-^Pager:~^Default program to display text/plain content
+^Pager:~^Program to use as interactive front\-end

 .fi
 
 .SH "SEE ALSO"
 .fi
 
 .SH "SEE ALSO"