4 .TH MHL %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
6 mhl \- produce formatted listings of nmh messages
11 .RB [ \-clear " | " \-noclear ]
31 command for filtering and/or displaying text
32 messages. It is the default method of displaying text messages for
39 each of the messages specified as arguments (or
40 the standard input) will be output. If more than one message file is
41 specified, the user will be prompted prior to each one, and a <RETURN>
42 or <EOT> will begin the output, with <RETURN> clearing the screen (if
43 appropriate), and <EOT> (usually CTRL\-D) suppressing the screen clear.
44 An <INTERRUPT> (usually CTRL\-C) will abort the current message output,
45 prompting for the next message (if there is one), and a <QUIT> (usually
46 CTRL-\\) will terminate the program (without core dump).
53 screen at the end of each page (or output a formfeed after each message).
54 This switches (and its inverse counterpart) take effect only
57 is defined but empty, and
59 is outputting to a terminal. If the
64 is outputting to a terminal, then
69 to be placed between the terminal and
71 and the switches are ignored. Furthermore, if the
74 used and \fImhl's\fR output is directed to a terminal, then
81 to determine the user's terminal type in order to find out how to clear
87 not directed to a terminal (e.g., a pipe or a file), then
90 send a formfeed after each message.
92 To override the default
94 and the profile entry, use the
101 if invoked on a hardcopy terminal.
109 switches set the screen
110 length and width, respectively. These default to the values indicated by
112 if appropriate, otherwise they default to 40 and 80, respectively.
114 The default format file used by
117 .RI \*(lq mhl.format \*(rq.
119 will first search for this file in the user's
121 directory, and will then search in the directory
124 can be changed by using the
128 Note: In contrast to any other
132 switch does only take file names, but no format strings with a prepended
141 which is used for the \*(lqmessagename:\*(rq field described below. The
144 is consulted for the default value,
150 initialize appropriately.
153 operates in two phases: 1) read and parse the format file, and
154 2) process each message (file). During phase 1, an internal description
155 of the format is produced as a structured list. In phase 2, this list
156 is walked for each message, outputting message information under the
157 format constraints from the format file.
159 The format file can contain information controlling screen clearing,
160 screen size, wrap\-around control, transparent text, component ordering,
161 and component formatting. Also, a list of components to ignore may be
162 specified, and a couple of \*(lqspecial\*(rq components are defined
163 to provide added functionality. Message output will be in the order
164 specified by the order in the format file.
166 Each line of a format file has one of the following forms:
172 variable[,variable...]
173 component:[variable,...]
178 A line beginning with a `;' is a comment, and is ignored.
180 A line beginning with a `:' is clear text, and is output exactly as is.
182 A line containing only a `:' produces a blank line in the output.
184 A line beginning with \*(lqcomponent:\*(rq defines the format for the specified
187 Remaining lines define the global environment.
189 For example, the line:
192 width=80,length=40,clearscreen,overflowtext="***",overflowoffset=5
195 defines the screen size to be 80 columns by 40 rows, specifies that the
196 screen should be cleared prior to each page, that the overflow indentation
197 is 5, and that overflow text should be flagged with \*(lq***\*(rq.
199 Following are all of the current variables and their arguments. If they
200 follow a component, they apply only to that component, otherwise, their
201 affect is global. Since the whole format is parsed before any output
202 processing, the last global switch setting for a variable applies to
203 the whole message if that variable is used in a global context (i.e.,
204 clearscreen, width, length).
208 .ta \w'noclearscreen 'u +\w'integer/G 'u
209 .I variable type semantics
210 width integer screen width or component width
211 length integer screen length or component length
212 offset integer positions to indent \*(lqcomponent: \*(rq
213 overflowtext string text to use at the beginning of an
215 overflowoffset integer positions to indent overflow lines
216 compwidth integer positions to indent component text
217 after the first line is output
218 uppercase flag output text of this component in all
220 nouppercase flag don't uppercase
221 clearscreen flag/G clear the screen prior to each page
222 noclearscreen flag/G don't clearscreen
223 component string/L name to use instead of \*(lqcomponent\*(rq for
225 nocomponent flag don't output \*(lqcomponent: \*(rq for this
227 center flag center component on line (works for
228 one\-line components only)
229 nocenter flag don't center
230 leftadjust flag strip off leading whitespace on each
232 noleftadjust flag don't leftadjust
233 compress flag change newlines in text to spaces
234 nocompress flag don't compress
235 split flag don't combine multiple fields into
237 nosplit flag combine multiple fields into
239 newline flag print newline at end of components
240 (this is the default)
241 nonewline flag don't print newline at end of components
242 formatfield string format string for this component
244 decode flag decode text as RFC-2047 encoded
246 addrfield flag field contains addresses
247 datefield flag field contains dates
251 To specify the value of integer\-valued and string\-valued variables,
252 follow their name with an equals\-sign and the value. Integer\-valued
253 variables are given decimal values, while string\-valued variables
254 are given arbitrary text bracketed by double\-quotes. If a value is
255 suffixed by \*(lq/G\*(rq or \*(lq/L\*(rq, then its value is useful in
256 a global\-only or local\-only context (respectively).
261 ignores=component,...
264 specifies a list of components which are never output.
266 The component \*(lqMessageName\*(rq (case\-insensitive) will output the
267 actual message name (file name) preceded by the folder name if one is
268 specified or found in the environment. The format is identical to that
274 The component \*(lqExtras\*(rq will output all of the components of the
275 message which were not matched by explicit components, or included in
276 the ignore list. If this component is not specified, an ignore list is
277 not needed since all non\-specified components will be ignored.
279 If \*(lqnocomponent\*(rq is NOT specified, then the component name will
280 be output as it appears in the format file.
282 The default format file is:
290 The variable \*(lqformatfield\*(rq specifies a format string (see
292 The flag variables \*(lqaddrfield\*(rq and
293 \*(lqdatefield\*(rq (which are mutually exclusive), tell
295 to interpret the escapes in the format string as either addresses or
300 does not apply any formatting string to fields
301 containing address or dates (see
304 fields). Note that this results in faster operation since
306 must parse both addresses and dates in order to apply a format string
309 can be given a default format string for
310 either address or date fields (but not both). To do this, on a global
311 line specify: either the flag addrfield or datefield, along with the
312 appropriate formatfield variable string.
317 .ta \w'%etcdir%/ExtraBigFileName 'u
318 ^%etcdir%/mhl.format~^The message template
319 ^or $HOME/.mmh/mhl.format~^Rather than the standard template
320 ^$HOME/.mh/profile~^The user profile
323 .SH "PROFILE COMPONENTS"
327 .ta \w'ExtraBigProfileName 'u
328 ^moreproc:~^Program to use as interactive front\-end
332 show(1), ap(8), dp(8)
345 In contrast to any other
349 switch does only take file names, but no format strings with a prepended
352 There should be some way to pass `clear' information to the
355 The \*(lqnonewline\*(rq option interacts badly with \*(lqcompress\*(rq