Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MHSHOW(1)		    General Commands Manual		     MHSHOW(1)

       mhshow -	display	nmh MIME messages

       mhshow [-help] [-version] [+folder] [msgs] [-file file] [-part number]
	    ...	 [-type	content] ...  [-prefer content]	...  [-noprefer]
	    [-concat | -noconcat] [-textonly | -notextonly] [-inlineonly |
	    -noinlineonly] [-header | -noheader] [-form	formfile] [-markform
	    formfile] [-rcache policy] [-wcache	policy]	[-check	| -nocheck]

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

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

       By  default,  mhshow will display only the text parts of	a message that
       are not marked as attachments.  This behavior can  be  changed  by  the
       -notextonly  and	 -noinlineonly	switches.   In	addition, by using the
       -part, -type, and -prefer switches, you may limit and reorder  the  set
       of  parts  to  be  displayed, based on part number and/or content type.
       The inclusion of	any -part or -type switches will override the  default
       settings	of -textonly and -inlineonly.

       The -header switch controls whether mhshow will print a message separa-
       tor header before each message that it displays.	 The header format can
       be  controlled  using -headerform, to specify a file containing mh-for-
       mat(5) instructions.  A copy of the built-in default headerform can  be
       found  in /usr/local/etc/nmh/mhshow.header, for reference.  In addition
       to the normal set of mh-format(5) instructions,	a  "%{folder}"	escape
       provides	a string representing the current folder.

       By  default,  mhshow  will concatenate all content under	one pager.  If
       you want	each part to be	displayed separately, you can override the de-
       fault behavior with -noconcat.

       The  -file  file	switch 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)).

       The  -part  switch can be given (one or more times) to restrict the set
       of subparts that	will be	displayed.  (Obviously with no -part switches,
       all  parts will be considered.)	If a -part switch specifies a specific
       subpart (i.e., a	"leaf" in the tree of MIME parts), then	that part will
       always be displayed.  If	a -part	switch references a multipart/alterna-
       tive part, then (in the absence of a -type  switch)  only  the  default
       subpart of that multipart will be displayed.

       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,  re-
       spectively.   Note that the -part switch	is effective only for 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.

       The -type switch	can also be used to restrict (or, when	used  in  con-
       junction	 with -part, to	further	restrict) the display of parts accord-
       ing to content type.  One or more -type switches	part will only	select
       the  first  match  from	a multipart/alternative, even if there is more
       than one	subpart	that matches (one of) the given	content	type(s).

       Using either -part or -type switches alone will cause either switch  to
       select  the  part(s)  they match.  Using	them together will select only
       the part(s) matched by both (sets of) switches.	In  other  words,  the
       result  is the intersection, and	not the	union, of their	separate match

       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/ex-
       ternal-body and once for	the content externally referenced.

       In  the	absence	 of -prefer, mhshow will select	the "best" displayable
       subpart from multipart/alternative content.  The	-prefer	switch can  be
       used  (one  or  more times, in order of ascending preference) to	let MH
       know which content types	from a	multipart/alternative  MIME  part  are
       preferred  by  the user,	in order to override the default selection for
       display.	 For example, mail is often sent containing both plaintext and
       HTML-formatted  versions	 of  the same content, and the HTML version is
       usually indicated to be the "best" format for viewing.  Using  "-prefer
       text/plain"  will cause the plaintext version to	be displayed if	possi-
       ble, but	still allow display of the HTML	part if	there is no  plaintext
       subpart	available.  Using "-prefer text/plain -prefer image/png" would
       add a preference	for PNG	images,	which might or might not  ever	appear
       in the same multipart/alternative section with text/plain.  Implementa-
       tion note:  RFC 2046 requires that the subparts of a multipart/alterna-
       tive  be	 ordered  according to "faithfulness to	the original content",
       and MH by default selects the subpart ranked most  "faithful"  by  that
       ordering.   The -prefer switch reorders the alternative parts (only in-
       ternally, never changing	the message file) to move the user's preferred
       part(s)	to the "most faithful" position.  Thus,	when viewed by mhlist,
       the ordering of multipart/alternative parts will	appear to change  when
       invoked	with  or  without various -prefer switches.  Since the last of
       multiple	-prefer	options	"wins",	a -prefer on  the  command  line  will
       override	any in a profile entry.

       The -noprefer switch will cancel	any previous -prefer switches.

   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

   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
       alternative format file with the	-form formfile switch.	If the	format
       file  mhl.null is specified, then the display of	the message headers is

       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.	 Similarly, older ver-
       sions 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>


	    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  bod-
       ies  will  be  determined  by  a	"display string".  To find the display
       string, mhshow will first search	your profile for an entry of the form:


       If this isn't found, mhshow will	search for an entry of the form:


       to determine the	display	string.

       If a display string is found, any escapes (given	 below)	 will  be  ex-
       panded.	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
	    %{parameter} Insert	the parameter value from the Content-Type field
	    %f		 Insert	filename containing content
	    %F		 %f, and stdin is terminal not content
	    %l		 display listing prior to displaying content
	    %s		 Insert	content	subtype
	    %d		 Insert	content	description
	    %%		 Insert	the character %

       mhshow will execute at most one display string at any given  time,  and
       wait  for the current display string to finish execution	before execut-
       ing the next display string.

       The {parameter} escape is typically used	in  a  command	line  argument
       that  should  only be present if	it has a non-null value.  It is	highly
       recommended that	the entire escape be wrapped in	double quotes.	 Shell
       parameter  expansion  can  construct  the argument only when it is non-
       null, e.g.,

	    mhshow-show-text/html: charset="%{charset}";
	      w3m ${charset:+-I	$charset} -T text/html %F

       That example also shows the use of indentation to signify continuation:
       the  two	 text  lines  combine  to form a single	entry.	Note that when
       dealing with text that has been converted internally by	iconv(3),  the
       "charset"  parameter will reflect the target character set of the text,
       rather than the original	character set in the message.

       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.  Furthermore, stdin	is not
       redirected from the terminal to the content.

       If  a  display  string is not found, mhshow behaves as if these profile
       entries were supplied and supported:

	    mhshow-show-text/plain: %lmoreproc %F
	    mhshow-show-message/rfc822:	%lshow -file %F

       Note that "moreproc" is not supported in	user profile display strings.

       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	multi-

       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  com-

       Example entries might be:

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

       If  an  f-  or F-escape is not quoted with single quotes, its expansion
       will be wrapped with single quotes.

       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.

   Showing Alternate Character Sets
       If mhshow was built with	iconv(3), then all  text/plain	parts  of  the
       message(s) will be displayed using the character	set of the current lo-
       cale.  See the mhparam(1) man page for how to  determine	 whether  your
       nmh  installation  includes  iconv(3)  support.	 To convert text parts
       other than text/plain, or if mhshow was not built with iconv, an	exter-
       nal program can be used,	as described next.

       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.
       mhshow checks this by examining the current character  set  defined  by
       the  locale(1) environment variables.  If the value of the locale char-
       acter set is equal to the value of the charset parameter,  then	mhshow
       assumes	it  can	display	this content without any additional setup.  If
       the locale is not set properly, 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:


       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-nor-
	    mal-*-*-120-*-*-c-*-iso8859-*' -e %s


	    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

       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.  For example, messages en-
       coded in	the ISO-8859-1 character set can be viewed  using  less,  with
       these environment variable settings:

	    LESSCHARSET	latin1
	    LESS	-f

       The first setting tells less to use the ISO-8859-1 definition to	deter-
       mine whether a character	is "normal", "control",	or "binary".  The sec-
       ond setting 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
       first reassemble	them into a normal message using mhstore.   Check  mh-
       store(1)	for details.

   External Access
       For  contents  of type message/external-body, mhshow supports these ac-

       o   afs

       o   anon-ftp

       o   ftp

       o   local-file

       o   mail-server

       o   url

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


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

       This program is invoked with these arguments:

	    domain name	of FTP-site
	    remote directory
	    remote filename
	    local filename
	    "ascii" or "binary"

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

       For the "url" access-type, mhshow will look  for	 the  "nmh-access-url"
       profile entry.  See mhstore(1) for more details.

   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

       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 publicly-accessi-
       ble 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 en-
       try "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

       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
       MHSHOW.	If present, this specifies the name of an additional user pro-
       file 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.	  Nor-
       mally,  only  entries  that  deal with the methods to display different
       content type and	subtypes


       need be present in this additional profile.  Finally, mhshow  will  at-
       tempt to	consult


       which is	created	automatically during nmh installation.

       See "Profile Lookup" in mh-profile(5) for the profile search order, and
       for how duplicate entries are treated.

   Content-Type	Marker
       mhshow will display a marker containing information about the part  be-
       ing displayed next.  The	default	marker can be changed using the	-mark-
       form switch to specify a	file containing	mh-format(5)  instructions  to
       use when	displaying the content marker.	A copy of the default markform
       can be found in /usr/local/etc/nmh/mhshow.marker,  for  reference.   In
       addition	 to the	normal set of mh-format(5) instructions, the following
       component escapes are supported:

	    Escape	    Returns   Description
	    part	    string    MIME part	number
	    content-type    string    MIME Content-Type	of part
	    description	    string    Content-Description header
	    disposition	    string    Content disposition (attachment or inline)
	    ctype-<PARAM>   string    Value of <PARAM> from Content-Type header
	    cdispo-<PARAM>  string    Value of <PARAM> from
				      Content-Disposition header
	    %(size)	    integer   The size of the decoded part, in bytes
	    %(unseen)	    boolean   Returns true for suppressed parts
	    In this context, the %(unseen) function indicates  whether	mhshow
	    has	 decided to not	display	a particular part due to the -textonly
	    or -inlineonly switches.
       All MIME	parameters and the "Content-Description" header	will have  RFC
       2231 decoding applied and be converted to the local character set.

       mhshow  looks  for  all format files and	mhn.defaults in	multiple loca-
       tions: absolute pathnames are accessed  directly,  tilde	 expansion  is
       done on usernames, and files are	searched for in	the user's Mail	direc-
       tory, as	specified in their profile.  If	not found there, the directory
       "/usr/local/etc/nmh" is checked.

       $HOME/.mh_profile		    The	user profile
       $MHSHOW				    Additional profile entries
       /usr/local/etc/nmh/mhn.defaults	    System default MIME	profile	entries
       /usr/local/etc/nmh/mhl.headers	    The	headers	template
       /usr/local/etc/nmh/mhshow.marker	    Example content marker
       /usr/local/etc/nmh/mhshow.header	    Example message separator header

       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-access-url:	    Program to retrieve	contents via HTTP
       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

       iconv(3),  mhbuild(1), mhl(1), mhlist(1), mhparam(1), mhstore(1), send-

       `+folder' defaults to the current folder
       `msgs' defaults to cur
       `-form mhl.headers'
       `-rcache	ask'
       `-wcache	ask'

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

nmh-1.7.1			  2015-02-08			     MHSHOW(1)


Want to link to this manual page? Use this URL:

home | help