Factor trim format function out
[mmh] / man / mhlist.man1
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH MHLIST %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 mhlist \- list information about MIME messages
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B mhlist
11 .RI [ +folder ]
12 .RI [ msgs ]
13 .RB [ \-file
14 .IR file ]
15 .RB [ \-part
16 .IR number ]
17 \&...
18 .RB [ \-type
19 .IR content ]
20 \&...
21 .RB [ \-verbose " | " \-noverbose ]
22 .RB [ \-Version ]
23 .RB [ \-help ]
24 .ad
25 .SH DESCRIPTION
26 The
27 .B mhlist
28 command allows you to list information (essentially
29 a table of contents) about the various parts of a collection of
30 MIME (multi-media) messages.
31 .PP
32 .B mhlist
33 manipulates MIME (multi-media messages) as specified
34 in RFC\-2045 thru RFC\-2049 (See
35 .BR mhbuild (1)).
36 .PP
37 A one-line banner is displayed above the listing.
38 The size of the
39 `native' (decoded) format of each content is evaluated.
40 This provides an accurate count at the expense of a small delay.
41 If the
42 .B \-verbose
43 switch is present, then the listing will show
44 any `extra' information that is present in the message,
45 such as comments in the `Content-Type' header.
46 .PP
47 The option
48 .B \-file
49 .I file
50 directs
51 .B mhlist
52 to use the specified
53 file as the source message, rather than a message from a folder.
54 If you specify this file as `-', then
55 .B mhlist
56 will
57 accept the source message on the standard input.  Note that the
58 file, or input from standard input should be a validly formatted
59 message, just like any other
60 .B mh
61 message.  It should
62 .B NOT
63 be in mail drop format (to convert a file in mail drop format to
64 a folder of
65 .B mh
66 messages, see
67 .BR inc (1)).
68 .PP
69 By default,
70 .B mhlist
71 will list information about the entire
72 message (all of its parts).  By using the
73 .B \-part
74 and
75 .B \-type
76 switches, you may limit the scope of this command to particular
77 subparts (of a multipart content) and/or particular content types.
78 .PP
79 A part specification consists of a series of numbers separated by dots.
80 For example, in a multipart content containing three parts, these
81 would be named as 1, 2, and 3, respectively.  If part 2 was also a
82 multipart content containing two parts, these would be named as 2.1 and
83 2.2, respectively.  Note that the
84 .B \-part
85 switch is effective for only
86 messages containing a multipart content.  If a message has some other
87 kind of content, or if the part is itself another multipart content, the
88 .B \-part
89 switch will not prevent the content from being acted upon.
90 .PP
91 A content specification consists of a content type and a subtype.
92 The initial list of `standard' content types and subtypes can
93 be found in RFC\-2046.
94 .PP
95 A list of commonly used contents is briefly reproduced here:
96 .PP
97 .RS 5
98 .nf
99 .ta \w'application  'u
100 Type    Subtypes
101 ----    --------
102 text    plain, enriched
103 multipart       mixed, alternative, digest, parallel
104 message rfc822, partial, external-body
105 application     octet-stream, postscript
106 image   jpeg, gif, png
107 audio   basic
108 video   mpeg
109 .fi
110 .RE
111 .PP
112 A legal MIME message must contain a subtype specification.
113 .PP
114 To specify a content, regardless of its subtype, just use the
115 name of the content, e.g., `audio'.  To specify a specific
116 subtype, separate the two with a slash, e.g., `audio/basic'.
117 Note that regardless of the values given to the
118 .B \-type
119 switch, a
120 multipart content (of any subtype listed above) is always acted upon.
121
122 .SH FILES
123 .fc ^ ~
124 .nf
125 .ta \w'%etcdir%/ExtraBigFileName  'u
126 ^$HOME/.mmh/profile~^The user profile
127 .fi
128
129 .SH "PROFILE COMPONENTS"
130 .fc ^ ~
131 .nf
132 .ta 2.4i
133 .ta \w'ExtraBigProfileName  'u
134 ^Path:~^To determine the user's mail storage
135 ^Current\-Folder:~^To find the default current folder
136 .fi
137
138 .SH "SEE ALSO"
139 mhbuild(1), show(1), mhstore(1), sendfiles(1)
140
141 .SH DEFAULTS
142 .nf
143 .RB ` +folder "' defaults to the current folder"
144 .RB ` msgs "' defaults to the current message"
145 .RB ` \-noverbose '
146 .fi
147
148 .SH CONTEXT
149 If a folder is given, it will become the current folder.  The last
150 message selected will become the current message.