1MHL(1) General Commands Manual MHL(1)
2
6 mhl - produce formatted listings of nmh messages
7
9 /usr/libexec/nmh/mhl [-help] [-version] [-bell | -nobell] [-clear |
10 -noclear] [-folder +folder] [-form formfile] [-length lines]
11 [-width columns] [-moreproc program] [-nomoreproc] [-fmtproc pro‐
12 gram] [-nofmtproc] [files ...]
13
15 mhl is an nmh command for filtering and/or displaying text messages.
16 It is the default method of displaying text messages for nmh (it is the
17 default showproc).
18 As with more, each of the messages specified as arguments (or the stan‐
20 dard input) will be output. If more than one message file is speci‐
21 fied, the user will be prompted prior to each one, and a <RETURN> or
22 <EOT> will begin the output, with <RETURN> clearing the screen (if ap‐
23 propriate), and <EOT> (usually CTRL-D) suppressing the screen clear.
24 An <INTERRUPT> (usually CTRL-C) will abort the current message output,
25 prompting for the next message (if there is one), and a <QUIT> (usually
26 CTRL- will terminate the program (without core dump).
27 The -bell option tells mhl to ring the terminal's bell at the end of
29 each page, while the -clear option tells mhl to clear the screen at the
30 end of each page (or output a formfeed after each message). Both of
31 these switches (and their inverse counterparts) take effect only if the
32 profile entry moreproc is defined but empty, and mhl is outputting to a
33 terminal. If the moreproc entry is defined and non-empty, and mhl is
34 outputting to a terminal, then mhl will cause the moreproc to be placed
35 between the terminal and mhl and the switches are ignored. Further‐
36 more, if the -clear switch is used and mhl's output is directed to a
37 terminal, then mhl will consult the TERM and TERMCAP environment vari‐
38 ables to determine the user's terminal type in order to find out how to
39 clear the screen. If the -clear switch is given and mhl's output is
40 not directed to a terminal (e.g., a pipe or a file), then mhl will send
41 a formfeed after each message.
42 To override the default moreproc and the profile entry, use the -more‐
44 proc program switch. Note that mhl will never start a moreproc if in‐
45 voked on a hardcopy terminal.
46 The -length length and -width width switches set the screen length and
48 width, respectively. These default to the values indicated by TERMCAP,
49 if appropriate, otherwise they default to 40 and 80, respectively.
50 The default format file used by mhl is called “mhl.format”. mhl will
52 first search for this file in the user's nmh directory, and will then
53 search in the directory /etc/nmh. This default can be changed by using
54 the -form formatfile switch.
55 Finally, the -folder +folder switch sets the nmh folder name, which is
57 used for the “messagename:” field described below. The environment
58 variable $mhfolder is consulted for the default value, which next,
59 show, and prev initialize appropriately.
60 mhl operates in two phases: 1) read and parse the format file, and 2)
62 process each message (file). During phase 1, an internal description
63 of the format is produced as a structured list. In phase 2, this list
64 is walked for each message, outputting message information under the
65 format constraints from the format file.
66 The format file can contain information controlling screen clearing,
68 screen size, wrap-around control, transparent text, component ordering,
69 and component formatting. Also, a list of components to ignore may be
70 specified, and a couple of “special” components are defined to provide
71 added functionality. Message output will be in the order specified by
72 the order in the format file.
73 Each line of a format file has one of the following forms:
75 ;comment
77 :cleartext
78 variable[,variable...]
79 component:[variable,...]
80 • A line beginning with a `;' is a comment, and is ignored.
82 • A line beginning with a `:' is clear text, and is output exactly as
84 is.
85 • A line containing only a `:' produces a blank line in the output.
87 • A line beginning with “component:” defines the format for the spec‐
89 ified component,
90 • Remaining lines define the global environment.
92 For example, the line:
94 width=80,length=40,clearscreen,overflowtext="***",overflowoffset=5
96 defines the screen size to be 80 columns by 40 rows, specifies that the
98 screen should be cleared prior to each page, that the overflow indenta‐
99 tion is 5, and that overflow text should be flagged with “***”.
100 Following are all of the current variables and their arguments. If
102 they follow a component, they apply only to that component, otherwise,
103 their affect is global. Since the whole format is parsed before any
104 output processing, the last global switch setting for a variable ap‐
105 plies to the whole message if that variable is used in a global context
106 (i.e., bell, clearscreen, width, length).
107 variable type semantics
109 width integer screen width or component width
110 length integer screen length or component length
111 offset integer positions to indent “component: ”
112 overflowtext string text to use at the beginning of an
113 overflow line
114 overflowoffset integer positions to indent overflow lines
115 compwidth integer positions to indent component text
116 after the first line is output
117 uppercase flag output text of this component in all
118 upper case
119 nouppercase flag don't uppercase
120 clearscreen flag/G clear the screen prior to each page
121 noclearscreen flag/G don't clearscreen
122 bell flag/G ring the bell at the end of each page
123 nobell flag/G don't bell
124 component string/L name to use instead of “component” for
125 this component
126 nocomponent flag don't output “component: ” for this
127 component
128 center flag center component on line (works for
129 one-line components only)
130 nocenter flag don't center
131 leftadjust flag strip off leading whitespace on each
132 line of text
133 noleftadjust flag don't leftadjust
134 rtrim flag trim whitespace at end of text lines
135 nortrim flag retain whitespace at end of text
136 lines (default)
137 compress flag change newlines in text to spaces
138 nocompress flag don't compress
139 wrap flag Wrap lines that exceed width (default)
140 nowrap flag Do not perform line wrapping
141 split flag don't combine multiple fields into
142 a single field
143 nosplit flag combine multiple fields into
144 a single field
145 newline flag print newline at end of components
146 (this is the default)
147 nonewline flag don't print newline at end of components
148 formatfield string format string for this component
149 (see below)
150 decode flag decode text as RFC 2047 encoded
151 header field
152 addrfield flag field contains addresses
153 datefield flag field contains dates
154 format flag Run component through formatproc filter
155 (body only)
156 noformat flag Do not run component through
157 formatproc filter (default)
158 formatarg string Argument to format filter
159 To specify the value of integer-valued and string-valued variables,
161 follow their name with an equals-sign and the value. Integer-valued
162 variables are given decimal values, while string-valued variables are
163 given arbitrary text bracketed by double-quotes. If a value is suf‐
164 fixed by “/G” or “/L”, then its value is useful in a global-only or lo‐
165 cal-only context (respectively).
166 A line of the form:
168 ignores=component,...
170 specifies a list of components which are never output.
172 The component “MessageName” (case-insensitive) will output the actual
174 message name (file name) preceded by the folder name if one is speci‐
175 fied or found in the environment. The format is identical to that pro‐
176 duced by the -header option to show.
177 The component “Extras” will output all of the components of the message
179 which were not matched by explicit components, or included in the ig‐
180 nore list. If this component is not specified, an ignore list is not
181 needed since all non-specified components will be ignored.
182 If “nocomponent” is not specified, then the component name will be out‐
184 put as it appears in the format file.
185 The default format file is:
187 ; mhl.format
189 ;
190 ; default message filter for `show'
191 ;
192 :
193 overflowtext="***",overflowoffset=5
194 leftadjust,compwidth=9
195 ignores=msgid,message-id,received,content-type,content-transfer-encoding,content-id
196 Resent-To:formatfield="%(unquote(decode{text}))"
197 Resent-cc:formatfield="%(unquote(decode{text}))"
198 Resent-From:formatfield="%(unquote(decode{text}))"
199 Date:formatfield="%<(nodate{text})%{text}%|%(pretty{text})%>"
200 To:formatfield="%(unquote(decode{text}))"
201 cc:formatfield="%(unquote(decode{text}))"
202 From:formatfield="%(unquote(decode{text}))"
203 Subject:decode
204 :
205 extras:nocomponent
206 :
207 body:nocomponent,overflowtext=,overflowoffset=0,noleftadjust
208 The variable “formatfield” specifies a format string (see mh-for‐
210 mat(5)). The flag variables “addrfield” and “datefield” (which are mu‐
211 tually exclusive), tell mhl to interpret the escapes in the format
212 string as either addresses or dates, respectively.
213 By default, mhl does not apply any formatting string to fields contain‐
215 ing address or dates (see mh-mail(5) for a list of these fields). Note
216 that this results in faster operation since mhl must parse both ad‐
217 dresses and dates in order to apply a format string to them. If de‐
218 sired, mhl can be given a default format string for either address or
219 date fields (but not both). To do this, on a global line specify: ei‐
220 ther the flag addrfield or datefield, along with the appropriate for‐
221 matfield variable string.
222 The “format” flag specifies that this component will be run through the
224 filter program specified by the formatproc profile entry. This filter
225 program is expected to read data on standard input and output data on
226 standard output. Currently the “format” flag is only supported for the
227 “body” component. The component name will be prefixed to the output
228 after the filter has been run. The expected use of this is to filter a
229 message body to create more pleasing text to use in a reply message. A
230 suggested filter to use for repl(1) is as follows:
231 body:component=">",overflowtext=">",overflowoffset=0,format,nowrap
233 The -fmtproc and -nofmtproc switches can be used to override the for‐
235 matproc profile entry.
236 The formatarg option specifies a string that is used as an argument to
238 the format filter. This string is processed by mh-format(5) and all of
239 the message components are available for use. Multiple formatarg op‐
240 tions can be used to build up multiple arguments to the format filter.
241
243 /etc/nmh/mhl.format The message template
244 or <mh-dir>/mhl.format Rather than the standard template
245 $HOME/.mh_profile The user profile
246
248 moreproc: Program to use as interactive front-end
249 formatproc: Program to use as a filter for components that
250 have the “format” flag set.
251
253 show(1), ap(8), dp(8)
254
256 `-bell'
257 `-noclear'
258 `-length 40'
259 `-width 80'
260
262 None
263
265 There should be some way to pass `bell' and `clear' information to the
266 front-end.
267 The “nonewline” option interacts badly with “compress” and “split”.
269 The “format” option really should work on something other than the body
271 component.
272nmh-1.8 2014-09-15 MHL(1)