From 079b426e4e813191dedbf8ba4aa454adf2f0a46d Mon Sep 17 00:00:00 2001
From: Ken Hornstein <kenh@pobox.com>
Date: Wed, 9 Apr 2014 16:16:18 -0400
Subject: [PATCH 1/1] Document the changes made to mhshow.

---
 docs/pending-release-notes |  3 ++
 etc/mhshow.marker          |  6 +++
 man/mhshow.man             | 75 +++++++++++++++++++++++++++++++++++---
 3 files changed, 79 insertions(+), 5 deletions(-)
 create mode 100644 etc/mhshow.marker

diff --git a/docs/pending-release-notes b/docs/pending-release-notes
index 8c02d845..22385f4a 100644
--- a/docs/pending-release-notes
+++ b/docs/pending-release-notes
@@ -81,6 +81,9 @@ NEW FEATURES
 - The MIME parsing and generating routines now support RFC 2231 extended
   parameter information.
 - mh-mime(7) now provides an introduction to nmh's MIME handling.
+- mhshow(1) will now by default display all text content under one pager,
+  and display markers for non-text and non-inline content.  The content
+  markers are changeable via mh-format(5).
 
 -----------------
 OBSOLETE FEATURES
diff --git a/etc/mhshow.marker b/etc/mhshow.marker
new file mode 100644
index 00000000..cc9ec85e
--- /dev/null
+++ b/etc/mhshow.marker
@@ -0,0 +1,6 @@
+%;
+%; This is provided as reference only; it shows the default content marker
+%; used by mhshow when it decides to not display content.
+%;
+[ part %{part} - %{content-type} - %<{description}\
+%{description}%?{cdispo-filename}%{cdispo-filename}%|%{ctype-name}%> ]
diff --git a/man/mhshow.man b/man/mhshow.man
index b6fe8838..0eac38b4 100644
--- a/man/mhshow.man
+++ b/man/mhshow.man
@@ -1,4 +1,4 @@
-.TH MHSHOW %manext1% "March 16, 2014" "%nmhversion%"
+.TH MHSHOW %manext1% "April 9, 2014" "%nmhversion%"
 .\"
 .\" %nmhwarning%
 .\"
@@ -18,8 +18,13 @@ mhshow \- display MIME messages
 .RB [ \-type
 .IR content ]
 \&...
+.RB [ \-concat " | " \-noconcat ]
+.RB [ \-textonly " | " \-notextonly ]
+.RB [ \-inlineonly " | " \-noinlineonly ]
 .RB [ \-form
 .IR formfile ]
+.RB [ \-markform
+.IR formfile ]
 .RB [ \-rcache
 .IR policy ]
 .RB [ \-wcache
@@ -44,16 +49,34 @@ message headers as specified in RFC 2047.
 .PP
 By default
 .B mhshow
-will display all parts of a multipart
-message.  By using the
+will display only text parts of a message that are not marked as attachments.
+This behavior can be changed by the
+.B \-notextonly
+and
+.B \-noinlineonly
+switches.
+In addition, by using the
 .B \-part
 and
 .B \-type
 switches, you may
-limit the scope of
+further limit the scope of
 .B mhshow
 to particular subparts (of a
-multipart content) and/or particular content types.
+multipart content) and/or particular content types.  The inclusion of any
+.B \-part
+or
+.B \-type
+switches will override the default settings of
+.B \-textonly
+and
+.BR \-inlineonly.
+.PP
+By default
+.B mhshow
+will concatenate all content under one pager.  If you which each part to
+displayed separately, you can override the default behavior with
+.B \-noconcat.
 .PP
 The option
 .B \-file
@@ -571,6 +594,45 @@ e.g.,
 which is created automatically during
 .B nmh
 installation.
+.PP
+SS Content\-Type Marker
+If
+.B mhshow
+decides to not display a particular part due to the switches of
+.B \-textonly
+or
+.B \-inlineonly
+it will display a marker containing information about the part.  This
+marker is processed via
+.IR mh\-format (5)
+and can be changed by the use of the
+.B \-markform
+switch to specify a file containing the
+.IR mh\-format (5)
+instructions to use when displaying the content marker.  In addition to
+the normal set of
+.IR mh\-format (5)
+instructions, the following
+.I component
+escapes are supported:
+.PP
+.RS 5
+.nf
+.ta \w'cdispo-<PARAM>  'u +\w'Returns   'u
+.I "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
+.fi
+.RE
+All MIME parameters and the \*(lqContent-Description\*(rq header will have
+RFC 2231 decoding applied and be converted
+to the local character set.
+.PP
 .SH FILES
 .B mhshow
 looks for all format files and mhn.defaults in multiple locations:
@@ -619,6 +681,9 @@ is checked.
 .RB ` +folder "' defaults to the current folder"
 .RB ` msgs "' defaults to cur"
 .RB ` \-nocheck '
+.RB ` \-concat '
+.RB ` \-textonly '
+.RB ` \-inlineonly '
 .RB ` \-form\ mhl.headers '
 .RB ` \-rcache\ ask '
 .RB ` \-wcache\ ask '
-- 
2.48.1