Provided by: nmh_1.3-1build1_amd64 bug

NAME

       mhshow - display MIME messages

SYNOPSIS

       mhshow [+folder] [msgs] [-file file] [-part number] ...  [-type content] ...  [-serialonly
            | -noserialonly] [-pause | -nopause] [-form formfile] [-rcache policy] [-wcache
            policy] [-check | -nocheck] [-version] [-help]

DESCRIPTION

       The  mhshow  command  display  contents  of  a MIME (multi-media) message or collection of
       messages.

       mhshow manipulates multi-media messages as specified in RFC-2045 thru RFC-2049.  Currently
       mhshow  only  supports  encodings  in message bodies, and does not support the encoding of
       message headers as specified in RFC-2047.

       By default mhshow will display all parts of a multipart message.  By using the  -part  and
       -type  switches,  you may limit the scope of mhshow to particular subparts (of a multipart
       content) and/or particular content types.

       The option -file file directs mhshow to use the specified  file  as  the  source  message,
       rather  than  a  message from a folder.  If you specify this file as “-”, then mhshow 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 nmh message.  It
       should NOT be in mail drop format (to convert a file in mail drop format to  a  folder  of
       nmh messages, see inc(1)).

       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 -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 -part switch  will  not  prevent  the
       content from being acted upon.

       A  content  specification  consists  of a content type and a subtype.  The initial list of
       “standard” content types and subtypes can be found in RFC-2046.

       A list of commonly used contents is briefly reproduced here:

            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

       A legal MIME message must contain a subtype specification.

       To specify a content, regardless of its subtype, just use the name of the  content,  e.g.,
       “audio”.    To  specify  a  specific  subtype,  separate  the  two  with  a  slash,  e.g.,
       “audio/basic”.  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.

   Unseen Sequence
       If the profile entry “Unseen-Sequence” is present and non-empty, then mhshow  will  remove
       each of the messages shown from each sequence named by the profile entry.

   Checking the Contents
       The  -check  switch  tells  mhshow  to check each content for an integrity checksum.  If a
       content has such a checksum (specified as a Content-MD5 header field),  then  mhshow  will
       attempt to verify the integrity of the content.

   Showing the Contents
       The  headers  of  each  message  are  displayed  with the mhlproc (usually mhl), using the
       standard format file mhl.headers.  You may specify an alternate format file with the -form
       formfile  switch.   If  the  format  file  mhl.null  is specified, then the display of the
       message headers is suppressed.

       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 “mhshow” 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 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  gs  command  append  a  “.ps”  suffix  to  the
       filename  if  one  was  missing.   As  a  result, these cannot be used to read the default
       temporary file.

       To get around this, your profile can contain lines of the form:

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

       or

            mhshow-suffix-<type>: <suffix>

       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:

            mhshow-suffix-text: .txt
            mhshow-suffix-application/msword: .doc
            mhshow-suffix-application/PostScript: .ps

       to automatically append a suffix to the temporary files.

       The  method  used  to  display  the  different  contents  in  the  messages bodies will be
       determined by a “display string”.  To find the display string, mhshow  will  first  search
       your profile for an entry of the form:

            mhshow-show-<type>/<subtype>

       to  determine the display string.  If this isn't found, mhshow will search for an entry of
       the form:

            mhshow-show-<type>

       to determine the display string.

       If a display string is found, any escapes (given below) will be expanded.  The result will
       be executed under “/bin/sh”, with the standard input set to the content.

       The display string may contain the following escapes:

            %a  Insert parameters from Content-Type field
            %e  exclusive execution
            %f  Insert filename containing content
            %F  %e, %f, and stdin is terminal not content
            %l  display listing prior to displaying content
            %p  %l, and ask for confirmation
            %s  Insert content subtype
            %d  Insert content description
            %%  Insert the character %

       For  those  display strings containing the e- or F-escape, 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.

       When  the  p-escape  prompts  for  confirmation, typing INTR (usually control-C) will tell
       mhshow not to display that content.  The p-escape can be disabled by specifying the switch
       -nopause.  Further, when mhshow is display a content, typing QUIT (usually control-\) will
       tell mhshow to wrap things up immediately.

       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.

       If a display string is not found, mhshow has several default values:

            mhshow-show-text/plain: %pmoreproc '%F'
            mhshow-show-message/rfc822: %pshow -file '%F'

       If a subtype of type text doesn't have a profile entry, it will be treated as text/plain.

       mhshow 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.

       If  none  of  these  apply,  then  mhshow  will  check  to  see  if  the  message  has  an
       application/octet-stream  content  with  parameter  “type=tar”.  If so, mhshow will use an
       appropriate command.  If not, mhshow will complain.

       Example entries might be:

            mhshow-show-audio/basic: raw2audio 2>/dev/null | play
            mhshow-show-image: xv '%f'
            mhshow-show-application/PostScript: lpr -Pps

       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.

       Finally, 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, the -serialonly  switch  can  be
       given to tell mhshow to never display parts in parallel.

   Showing Alternate Character Sets
       Because  a  content  of  type  text  might  be  in  a non-ASCII character set, when mhshow
       encounters a “charset” parameter for this content, it checks if your terminal can  display
       this  character  set  natively.  mhn checks this by examining the the environment variable
       $MM_CHARSET.  If the value of this environment variable is  equal  to  the  value  of  the
       charset  parameter, then mhshow assumes it can display this content without any additional
       setup.  If this environment variable is not set, mhshow will assume a value of “US-ASCII”.
       If  the  character set cannot be displayed natively, then mhshow will look for an entry of
       the form:

            mhshow-charset-<charset>

       which should contain a command creating an environment to render the character set.   This
       command  string  should containing a single “%s”, which will be filled-in with the command
       to display the content.

       Example entries might be:

            mhshow-charset-iso-8859-1: xterm -fn '-*-*-medium-r-normal-*-*-120-*-*-c-*-iso8859-*'
            -e %s

       or

            mhshow-charset-iso-8859-1: '%s'

       The  first  example tells mhshow to start xterm and load the appropriate character set for
       that message content.  The second example tells mhshow that your pager (or  other  program
       handling  that content type) can handle that character set, and that no special processing
       is needed beforehand.

       Note that many pagers strip off the high-order bit or have problems displaying  text  with
       the  high-order  bit  set.  However, the pager less has support for single-octet character
       sets.  The source to less is available on many ftp sites carrying free software.  In order
       to view messages sent in the ISO-8859-1 character set using less,

       put these lines in your .login file:

            setenv LESSCHARSET latin1
            setenv LESS "-f"

       The  first  line  tells  less  to  use the ISO-8859-1 definition for determining whether a
       character is “normal”, “control“, or “binary”.  The second line tells less not to warn you
       if  it  encounters  a  file  that has non-ASCII characters.  Then, simply set the moreproc
       profile entry to less, and it will get called automatically.   (To  handle  other  single-
       octet  character  sets,  look  at  the  less(1)  manual  entry  for  information about the
       $LESSCHARDEF environment variable.)

   Messages of Type message/partial
       mhshow cannot directly display messages of type partial.  You must reassemble  them  first
       into a normal message using mhstore.  Check the man page for mhstore(1) for details.

   External Access
       For contents of type message/external-body, mhshow supports these access-types:

       ·   afs

       ·   anon-ftp

       ·   ftp

       ·   local-file

       ·   mail-server

       For  the  “anon-ftp”  and  “ftp”  access  types, mhshow will look for the “nmh-access-ftp”
       profile entry, e.g.,

            nmh-access-ftp: myftp.sh

       to determine the pathname of a program to perform the FTP retrieval.

       This program is invoked with these arguments:

            domain name of FTP-site
            username
            password
            remote directory
            remote filename
            local filename
            “ascii” or “binary”

       The program should terminate with an exit status of zero if the retrieval  is  successful,
       and a non-zero exit status otherwise.

       If  this  entry  is  not  provided,  then  mhshow will use a simple built-in FTP client to
       perform the retrieval.

   The Content Cache
       When mhshow encounters an external content containing a “Content-ID:” field,  and  if  the
       content  allows  caching,  then  depending  on the caching behavior of mhshow, the content
       might be read from or written to a cache.

       The caching behavior of mhshow is controlled with the -rcache and -wcache switches,  which
       define  the policy for reading from, and writing to, the cache, respectively.  One of four
       policies may be  specified:  “public”,  indicating  that  mhshow  should  make  use  of  a
       publically-accessible  content cache; “private”, indicating that mhshow should make use of
       the user's private content cache; “never”, indicating that mhshow should never make use of
       caching; and, “ask”, indicating that mhshow should ask the user.

       There  are  two  directories  where  contents may be cached: the profile entry “nmh-cache”
       names a directory containing world-readable contents, and, the profile entry “nmh-private-
       cache”  names  a  directory containing private contents.  The former should be an absolute
       (rooted) directory name.

       For example,

            nmh-cache: /tmp

       might be used if you didn't care that the cache got wiped after each reboot of the system.
       The latter is interpreted relative to the user's nmh directory, if not rooted, e.g.,

            nmh-private-cache: .cache

       (which is the default value).

   User Environment
       Because  the display environment in which mhshow operates may vary for different machines,
       mhshow will look for the environment variable 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

            mhshow-show-<type>/<subtype>
            mhshow-show-<type>

       need be present in this additional profile. Finally, mhshow will attempt  to  consult  one
       other additional user profile, e.g.,

            /etc/nmh/mhn.defaults

       which is created automatically during nmh installation.

FILES

       $HOME/.mh_profile          The user profile
       $MHSHOW                    Additional profile entries
       /etc/nmh/mhn.defaults      System default MIME profile entries
       /etc/nmh/mhl.headers       The headers template

PROFILE COMPONENTS

       Path:                To determine the user's nmh directory
       Current-Folder:      To find the default current folder
       Unseen-Sequence:     To name sequences denoting unseen messages
       mhlproc:             Default program to display message headers
       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-<charsTe>mplate for environment to render character sets
       mhshow-show-<type>*  Template for displaying contents
       moreproc:            Default program to display text/plain content

SEE ALSO

       mhbuild(1), mhl(1), mhlist(1), mhstore(1), sendfiles(1)

DEFAULTS

       `+folder' defaults to the current folder
       `msgs' defaults to cur
       `-nocheck'
       `-formmhl.headers'
       `-pause'
       `-rcacheask'
       `-realsize'
       `-noserialonly'
       `-noverbose'
       `-wcacheask'

CONTEXT

       If  a  folder is given, it will become the current folder.  The last message selected will
       become the current message.