5 .TH MHL %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
7 mhl \- produce formatted listings of nmh messages
12 .RB [ \-bell " | " \-nobell ]
13 .RB [ \-clear " | " \-noclear ]
34 command for filtering and/or displaying text
35 messages. It is the default method of displaying text messages for
42 each of the messages specified as arguments (or
43 the standard input) will be output. If more than one message file is
44 specified, the user will be prompted prior to each one, and a <RETURN>
45 or <EOT> will begin the output, with <RETURN> clearing the screen (if
46 appropriate), and <EOT> (usually CTRL\-D) suppressing the screen clear.
47 An <INTERRUPT> (usually CTRL\-C) will abort the current message output,
48 prompting for the next message (if there is one), and a <QUIT> (usually
49 CTRL-\\) will terminate the program (without core dump).
55 to ring the terminal's bell at the
56 end of each page, while the
61 screen at the end of each page (or output a formfeed after each message).
62 Both of these switches (and their inverse counterparts) take effect only
65 is defined but empty, and
67 is outputting to a terminal. If the
72 is outputting to a terminal, then
77 to be placed between the terminal and
79 and the switches are ignored. Furthermore, if the
82 used and \fImhl's\fR output is directed to a terminal, then
89 to determine the user's terminal type in order to find out how to clear
95 not directed to a terminal (e.g., a pipe or a file), then
98 send a formfeed after each message.
100 To override the default
102 and the profile entry, use the
109 if invoked on a hardcopy terminal.
117 switches set the screen
118 length and width, respectively. These default to the values indicated by
120 if appropriate, otherwise they default to 40 and 80, respectively.
122 The default format file used by
125 .RI \*(lq mhl.format \*(rq.
127 will first search for this file in the user's
129 directory, and will then search in the directory
132 can be changed by using the
143 which is used for the \*(lqmessagename:\*(rq field described below. The
146 is consulted for the default value,
152 initialize appropriately.
155 operates in two phases: 1) read and parse the format file, and
156 2) process each message (file). During phase 1, an internal description
157 of the format is produced as a structured list. In phase 2, this list
158 is walked for each message, outputting message information under the
159 format constraints from the format file.
161 The format file can contain information controlling screen clearing,
162 screen size, wrap\-around control, transparent text, component ordering,
163 and component formatting. Also, a list of components to ignore may be
164 specified, and a couple of \*(lqspecial\*(rq components are defined
165 to provide added functionality. Message output will be in the order
166 specified by the order in the format file.
168 Each line of a format file has one of the following forms:
174 variable[,variable...]
175 component:[variable,...]
180 A line beginning with a `;' is a comment, and is ignored.
182 A line beginning with a `:' is clear text, and is output exactly as is.
184 A line containing only a `:' produces a blank line in the output.
186 A line beginning with \*(lqcomponent:\*(rq defines the format for the specified
189 Remaining lines define the global environment.
191 For example, the line:
194 width=80,length=40,clearscreen,overflowtext="***",overflowoffset=5
197 defines the screen size to be 80 columns by 40 rows, specifies that the
198 screen should be cleared prior to each page, that the overflow indentation
199 is 5, and that overflow text should be flagged with \*(lq***\*(rq.
201 Following are all of the current variables and their arguments. If they
202 follow a component, they apply only to that component, otherwise, their
203 affect is global. Since the whole format is parsed before any output
204 processing, the last global switch setting for a variable applies to
205 the whole message if that variable is used in a global context (i.e.,
206 bell, clearscreen, width, length).
210 .ta \w'noclearscreen 'u +\w'integer/G 'u
211 .I variable type semantics
212 width integer screen width or component width
213 length integer screen length or component length
214 offset integer positions to indent \*(lqcomponent: \*(rq
215 overflowtext string text to use at the beginning of an
217 overflowoffset integer positions to indent overflow lines
218 compwidth integer positions to indent component text
219 after the first line is output
220 uppercase flag output text of this component in all
222 nouppercase flag don't uppercase
223 clearscreen flag/G clear the screen prior to each page
224 noclearscreen flag/G don't clearscreen
225 bell flag/G ring the bell at the end of each page
226 nobell flag/G don't bell
227 component string/L name to use instead of \*(lqcomponent\*(rq for
229 nocomponent flag don't output \*(lqcomponent: \*(rq for this
231 center flag center component on line (works for
232 one\-line components only)
233 nocenter flag don't center
234 leftadjust flag strip off leading whitespace on each
236 noleftadjust flag don't leftadjust
237 compress flag change newlines in text to spaces
238 nocompress flag don't compress
239 split flag don't combine multiple fields into
241 nosplit flag combine multiple fields into
243 newline flag print newline at end of components
244 (this is the default)
245 nonewline flag don't print newline at end of components
246 formatfield string format string for this component
248 decode flag decode text as RFC-2047 encoded
250 addrfield flag field contains addresses
251 datefield flag field contains dates
255 To specify the value of integer\-valued and string\-valued variables,
256 follow their name with an equals\-sign and the value. Integer\-valued
257 variables are given decimal values, while string\-valued variables
258 are given arbitrary text bracketed by double\-quotes. If a value is
259 suffixed by \*(lq/G\*(rq or \*(lq/L\*(rq, then its value is useful in
260 a global\-only or local\-only context (respectively).
265 ignores=component,...
268 specifies a list of components which are never output.
270 The component \*(lqMessageName\*(rq (case\-insensitive) will output the
271 actual message name (file name) preceded by the folder name if one is
272 specified or found in the environment. The format is identical to that
278 The component \*(lqExtras\*(rq will output all of the components of the
279 message which were not matched by explicit components, or included in
280 the ignore list. If this component is not specified, an ignore list is
281 not needed since all non\-specified components will be ignored.
283 If \*(lqnocomponent\*(rq is NOT specified, then the component name will
284 be output as it appears in the format file.
286 The default format file is:
294 The variable \*(lqformatfield\*(rq specifies a format string (see
296 The flag variables \*(lqaddrfield\*(rq and
297 \*(lqdatefield\*(rq (which are mutually exclusive), tell
299 to interpret the escapes in the format string as either addresses or
304 does not apply any formatting string to fields
305 containing address or dates (see
308 fields). Note that this results in faster operation since
310 must parse both addresses and dates in order to apply a format string
313 can be given a default format string for
314 either address or date fields (but not both). To do this, on a global
315 line specify: either the flag addrfield or datefield, along with the
316 appropriate formatfield variable string.
321 .ta \w'%etcdir%/ExtraBigFileName 'u
322 ^%etcdir%/mhl.format~^The message template
323 ^or <mh\-dir>/mhl.format~^Rather than the standard template
324 ^$HOME/\&.mh\(ruprofile~^The user profile
327 .SH "PROFILE COMPONENTS"
331 .ta \w'ExtraBigProfileName 'u
332 ^moreproc:~^Program to use as interactive front\-end
336 show(1), ap(8), dp(8)
350 There should be some way to pass `bell' and `clear' information to the
353 The \*(lqnonewline\*(rq option interacts badly with \*(lqcompress\*(rq