Updated man page of mhshow(1) to recent changes.

[mmh] / man / mhshow.man1

diff --git a/man/mhshow.man1 b/man/mhshow.man1
index 13cb015..79975ef 100644 (file)
--- a/man/mhshow.man1
+++ b/man/mhshow.man1
@@ -20,11 +20,6 @@ mhshow \- display MIME messages
 \&...
 .RB [ \-form
 .IR formfile ]
 \&...
 .RB [ \-form
 .IR formfile ]

-.RB [ \-rcache
-.IR policy ]
-.RB [ \-wcache
-.IR policy ]
-.RB [ \-check " | " \-nocheck ]

 .RB [ \-version ]
 .RB [ \-help ]
 .ad
 .RB [ \-version ]
 .RB [ \-help ]
 .ad

@@ -116,27 +111,12 @@ 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.
 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.

-Further note that if the `\-type' switch is used, and it is desirable to
-act on a message/external-body content, then the `\-type' switch must
-be used twice: once for message/external-body and once for the content
-externally referenced.

 .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 "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 "Checking the Contents"
-The
-.B \-check
-switch tells
-.B mhshow
-to check each content for an
-integrity checksum.  If a content has such a checksum (specified as a
-Content-MD5 header field), then
-.B mhshow
-will attempt to verify the
-integrity of the content.

 .SS "Showing the Contents"
 The headers of each message are displayed with
 .B mhl
 .SS "Showing the Contents"
 The headers of each message are displayed with
 .B mhl

@@ -165,16 +145,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

@@ -221,24 +198,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

@@ -258,8 +231,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

@@ -273,12 +246,6 @@ multipart (without a profile entry), will be treated as multipart/mixed.
 .PP
 If none of these apply, then
 .B mhshow
 .PP
 If none of these apply, then
 .B mhshow

-will check to see if the message
-has an application/octet-stream content with parameter \*(lqtype=tar\*(rq.
-If so,
-.B mhshow
-will use an appropriate command.  If not,
-.B mhshow

 will complain.
 .PP
 Example entries might be:
 will complain.
 .PP
 Example entries might be:

@@ -286,25 +253,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

@@ -312,95 +276,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.

@@ -410,100 +308,10 @@ Check the man page for
 .BR mhstore (1)
 for details.
 .SS "External Access"
 .BR mhstore (1)
 for details.
 .SS "External Access"

-For contents of type message/external-body,
-.B mhshow
-supports these access-types:
-.PP
-.IP \(bu 4
-afs
-.IP \(bu 4
-anon-ftp
-.IP \(bu 4
-ftp
-.IP \(bu 4
-local-file
-.IP \(bu 4
-mail-server
-.PP
-For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
-.B mhshow
-will look for the \*(lqnmh-access-ftp\*(rq
-profile entry, e.g.,
-.PP
-.RS 5
-nmh-access-ftp: myftp.sh
-.RE
-.PP
-to determine the pathname of a program to perform the FTP retrieval.
-.PP
-This program is invoked with these arguments:
-.PP
-.RS 5
-.nf
-domain name of FTP-site
-username
-password
-remote directory
-remote filename
-local filename
-\*(lqascii\*(rq or \*(lqbinary\*(rq
-.fi
-.RE
-.PP
-The program should terminate with an exit status of zero if the
-retrieval is successful, and a non-zero exit status otherwise.
-.SS "The Content Cache"
-When
-.B mhshow
-encounters an external content containing a
-\*(lqContent-ID:\*(rq field, and if the content allows caching, then
-depending on the caching behavior of
-.BR mhshow ,
-the content might be read from or written to a cache.
-.PP
-The caching behavior of
-.B mhshow
-is controlled with the
-.B \-rcache
-and
-.B \-wcache
-switches, which define the policy for reading from,
-and writing to, the cache, respectively.  One of four policies may be
-specified: \*(lqpublic\*(rq, indicating that
-.B mhshow
-should make use
-of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
-that
-.B mhshow
-should make use of the user's private content cache;
-\*(lqnever\*(rq, indicating that
-.B mhshow
-should never make use of
-caching; and, \*(lqask\*(rq, indicating that
-.B mhshow
-should ask the user.
-.PP
-There are two directories where contents may be cached: the profile entry
-\*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
-the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
-private contents.  The former should be an absolute (rooted) directory
-name.
-.PP
-For example,
-.PP
-.RS 5
-nmh-cache: /tmp
-.RE
-.PP
-might be used if you didn't care that the cache got wiped after each
-reboot of the system.  The private cache is interpreted relative to the user's
-mail storage, if not rooted, e.g.,
-.PP
-.RS 5
-nmh-private-cache: .cache
-.RE
-.PP
-(which is the default value).
+.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
 .SS "User Environment"
 Because the display environment in which
 .B mhshow

@@ -557,10 +365,6 @@ 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

-^nmh-access-ftp:~^Program to retrieve contents via FTP
-^nmh-cache~^Public directory to store cached external contents
-^nmh-private-cache~^Personal directory to store cached external contents
-^mhshow-charset-<charset>~^Template for environment to render character sets

 ^mhshow-show-<type>*~^Template for displaying contents
 ^Pager:~^Default program to display text/plain content
 .fi
 ^mhshow-show-<type>*~^Template for displaying contents
 ^Pager:~^Default program to display text/plain content
 .fi

@@ -572,11 +376,8 @@ mhbuild(1), mhl(1), mhlist(1), mhstore(1), sendfiles(1)
 .nf
 .RB ` +folder "' defaults to the current folder"
 .RB ` msgs "' defaults to cur"
 .nf
 .RB ` +folder "' defaults to the current folder"
 .RB ` msgs "' defaults to cur"

-.RB ` \-nocheck '

 .RB ` \-form \ mhl.headers'
 .RB ` \-form \ mhl.headers'

-.RB ` \-rcache \ ask'

 .RB ` \-noverbose '
 .RB ` \-noverbose '

-.RB ` \-wcache \ ask'

 .fi
 
 .SH CONTEXT
 .fi
 
 .SH CONTEXT