5 .TH MHL %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
7 mhl \- produce formatted listings of nmh messages
11 .RB [ \-bell " | " \-nobell ]
12 .RB [ \-clear " | " \-noclear ]
32 command for filtering and/or displaying text
33 messages. It is the default method of displaying text messages for
40 each of the messages specified as arguments (or
41 the standard input) will be output. If more than one message file is
42 specified, the user will be prompted prior to each one, and a <RETURN>
43 or <EOT> will begin the output, with <RETURN> clearing the screen (if
44 appropriate), and <EOT> (usually CTRL\-D) suppressing the screen clear.
45 An <INTERRUPT> (usually CTRL\-C) will abort the current message output,
46 prompting for the next message (if there is one), and a <QUIT> (usually
47 CTRL-\\) will terminate the program (without core dump).
53 to ring the terminal's bell at the
54 end of each page, while the
59 screen at the end of each page (or output a formfeed after each message).
60 Both of these switches (and their inverse counterparts) take effect only
63 is defined but empty, and
65 is outputting to a terminal. If the
70 is outputting to a terminal, then
75 to be placed between the terminal and
77 and the switches are ignored. Furthermore, if the
80 used and \fImhl's\fR output is directed to a terminal, then
87 to determine the user's terminal type in order to find out how to clear
93 not directed to a terminal (e.g., a pipe or a file), then
96 send a formfeed after each message.
98 To override the default
100 and the profile entry, use the
107 if invoked on a hardcopy terminal.
115 switches set the screen
116 length and width, respectively. These default to the values indicated by
118 if appropriate, otherwise they default to 40 and 80, respectively.
120 The default format file used by
123 .RI \*(lq mhl.format \*(rq.
125 will first search for this file in the user's
127 directory, and will then search in the directory
130 can be changed by using the
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 bell, 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 bell flag/G ring the bell at the end of each page
224 nobell flag/G don't bell
225 component string/L name to use instead of \*(lqcomponent\*(rq for
227 nocomponent flag don't output \*(lqcomponent: \*(rq for this
229 center flag center component on line (works for
230 one\-line components only)
231 nocenter flag don't center
232 leftadjust flag strip off leading whitespace on each
234 noleftadjust flag don't leftadjust
235 compress flag change newlines in text to spaces
236 nocompress flag don't compress
237 split flag don't combine multiple fields into
239 nosplit flag combine multiple fields into
241 newline flag print newline at end of components
242 (this is the default)
243 nonewline flag don't print newline at end of components
244 formatfield string format string for this component
246 decode flag decode text as RFC-2047 encoded
248 addrfield flag field contains addresses
249 datefield flag field contains dates
253 To specify the value of integer\-valued and string\-valued variables,
254 follow their name with an equals\-sign and the value. Integer\-valued
255 variables are given decimal values, while string\-valued variables
256 are given arbitrary text bracketed by double\-quotes. If a value is
257 suffixed by \*(lq/G\*(rq or \*(lq/L\*(rq, then its value is useful in
258 a global\-only or local\-only context (respectively).
263 ignores=component,...
266 specifies a list of components which are never output.
268 The component \*(lqMessageName\*(rq (case\-insensitive) will output the
269 actual message name (file name) preceded by the folder name if one is
270 specified or found in the environment. The format is identical to that
276 The component \*(lqExtras\*(rq will output all of the components of the
277 message which were not matched by explicit components, or included in
278 the ignore list. If this component is not specified, an ignore list is
279 not needed since all non\-specified components will be ignored.
281 If \*(lqnocomponent\*(rq is NOT specified, then the component name will
282 be output as it appears in the format file.
284 The default format file is:
292 The variable \*(lqformatfield\*(rq specifies a format string (see
294 The flag variables \*(lqaddrfield\*(rq and
295 \*(lqdatefield\*(rq (which are mutually exclusive), tell
297 to interpret the escapes in the format string as either addresses or
302 does not apply any formatting string to fields
303 containing address or dates (see
306 fields). Note that this results in faster operation since
308 must parse both addresses and dates in order to apply a format string
311 can be given a default format string for
312 either address or date fields (but not both). To do this, on a global
313 line specify: either the flag addrfield or datefield, along with the
314 appropriate formatfield variable string.
319 .ta \w'/usr/local/nmh/etc/ExtraBigFileName 'u
320 ^%etcdir%/mhl.format~^The message template
321 ^or <mh\-dir>/mhl.format~^Rather than the standard template
322 ^$HOME/\&.mh\(ruprofile~^The user profile
325 .SH "PROFILE COMPONENTS"
329 .ta \w'ExtraBigProfileName 'u
330 ^moreproc:~^Program to use as interactive front\-end
334 show(1), ap(8), dp(8)
348 There should be some way to pass `bell' and `clear' information to the
351 The \*(lqnonewline\*(rq option interacts badly with \*(lqcompress\*(rq