cc5254dd216f0cd8433e65027143caa666e87863
[mmh] / mhl.man
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH MHL %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 mhl \- produce formatted listings of nmh messages
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B %libdir%/mhl
11 .RB [ \-bell " | " \-nobell ]
12 .RB [ \-clear " | " \-noclear ]
13 .RB [ \-folder
14 .IR +folder ]
15 .RB [ \-form
16 .IR formfile ]
17 .RB [ \-length
18 .IR lines ]
19 .RB [ \-width
20 .IR columns ]
21 .RB [ \-moreproc
22 .IR program ]
23 .RB [ \-nomoreproc ]
24 .RI [ files
25 .IR \&... ]
26 .RB [ \-version ]
27 .RB [ \-help ]
28 .ad
29 .SH DESCRIPTION
30 .B Mhl
31 is an
32 .B nmh
33 command for filtering and/or displaying text
34 messages.  It is the default method of displaying text messages for
35 .B nmh
36 (it is the default
37 .IR showproc ).
38 .PP
39 As with
40 .BR more ,
41 each of the messages specified as arguments (or
42 the standard input) will be output.  If more than one message file is
43 specified, the user will be prompted prior to each one, and a <RETURN>
44 or <EOT> will begin the output, with <RETURN> clearing the screen (if
45 appropriate), and <EOT> (usually CTRL\-D) suppressing the screen clear.
46 An <INTERRUPT> (usually CTRL\-C) will abort the current message output,
47 prompting for the next message (if there is one), and a <QUIT> (usually
48 CTRL-\\) will terminate the program (without core dump).
49 .PP
50 The
51 .B \-bell
52 option tells
53 .B mhl
54 to ring the terminal's bell at the
55 end of each page, while the
56 .B \-clear
57 option tells
58 .B mhl
59 to clear the
60 screen at the end of each page (or output a formfeed after each message).
61 Both of these switches (and their inverse counterparts) take effect only
62 if the profile entry
63 .I moreproc
64 is defined but empty, and
65 .B mhl
66 is outputting to a terminal.  If the
67 .I moreproc
68 entry is defined and
69 non-empty, and
70 .B mhl
71 is outputting to a terminal, then
72 .B mhl
73 will
74 cause the
75 .I moreproc
76 to be placed between the terminal and
77 .B mhl
78 and the switches are ignored.  Furthermore, if the
79 .B \-clear
80 switch is
81 used and \fImhl's\fR output is directed to a terminal, then
82 .B mhl
83 will consult the
84 .B $TERM
85 and
86 .B $TERMCAP
87 environment variables
88 to determine the user's terminal type in order to find out how to clear
89 the screen.  If the
90 .B \-clear
91 switch is used and
92 .BR mhl 's
93 output is
94 not directed to a terminal (e.g., a pipe or a file), then
95 .B mhl
96 will
97 send a formfeed after each message.
98 .PP
99 To override the default
100 .I moreproc
101 and the profile entry, use the
102 .B \-moreproc
103 .I program
104 switch.  Note that
105 .B mhl
106 will never start a
107 .I moreproc
108 if invoked on a hardcopy terminal.
109 .PP
110 The
111 .B \-length
112 .I length
113 and
114 .B \-width
115 .I width
116 switches set the screen
117 length and width, respectively.  These default to the values indicated by
118 .BR $TERMCAP ,
119 if appropriate, otherwise they default to 40 and 80, respectively.
120 .PP
121 The default format file used by
122 .B mhl
123 is called
124 .RI \*(lq mhl.format \*(rq.
125 .B mhl
126 will first search for this file in the user's
127 .B nmh
128 directory, and will then search in the directory
129 .IR %etcdir% .
130 This default
131 can be changed by using the
132 .B \-form
133 .I formatfile
134 switch.
135 .PP
136 Finally, the
137 .B \-folder
138 .I +folder
139 switch sets the
140 .B nmh
141 folder name,
142 which is used for the \*(lqmessagename:\*(rq field described below.  The
143 environment variable
144 .B $mhfolder
145 is consulted for the default value,
146 which
147 .BR show ,
148 .BR next ,
149 and
150 .B prev
151 initialize appropriately.
152 .PP
153 .B Mhl
154 operates in two phases: 1) read and parse the format file, and
155 2) process each message (file).  During phase 1, an internal description
156 of the format is produced as a structured list.  In phase 2, this list
157 is walked for each message, outputting message information under the
158 format constraints from the format file.
159 .PP
160 The format file can contain information controlling screen clearing,
161 screen size, wrap\-around control, transparent text, component ordering,
162 and component formatting.  Also, a list of components to ignore may be
163 specified, and a couple of \*(lqspecial\*(rq components are defined
164 to provide added functionality.  Message output will be in the order
165 specified by the order in the format file.
166 .PP
167 Each line of a format file has one of the following forms:
168 .PP
169 .RS 5
170 .nf
171 ;comment
172 :cleartext
173 variable[,variable...]
174 component:[variable,...]
175 .fi
176 .RE
177 .PP
178 .IP \(bu 4
179 A line beginning with a `;' is a comment, and is ignored.
180 .IP \(bu 4
181 A line beginning with a `:' is clear text, and is output exactly as is.
182 .IP \(bu 4
183 A line containing only a `:' produces a blank line in the output.
184 .IP \(bu 4
185 A line beginning with \*(lqcomponent:\*(rq defines the format for the specified
186 component,
187 .IP \(bu 4
188 Remaining lines define the global environment.
189 .PP
190 For example, the line:
191 .PP
192 .RS 5
193 width=80,length=40,clearscreen,overflowtext="***",overflowoffset=5
194 .RE
195 .PP
196 defines the screen size to be 80 columns by 40 rows, specifies that the
197 screen should be cleared prior to each page, that the overflow indentation
198 is 5, and that overflow text should be flagged with \*(lq***\*(rq.
199 .PP
200 Following are all of the current variables and their arguments.  If they
201 follow a component, they apply only to that component, otherwise, their
202 affect is global.  Since the whole format is parsed before any output
203 processing, the last global switch setting for a variable applies to
204 the whole message if that variable is used in a global context (i.e.,
205 bell, clearscreen, width, length).
206 .PP
207 .RS 5
208 .nf
209 .ta \w'noclearscreen  'u +\w'integer/G  'u
210 .I "variable    type    semantics"
211 width   integer screen width or component width
212 length  integer screen length or component length
213 offset  integer positions to indent \*(lqcomponent: \*(rq
214 overflowtext    string  text to use at the beginning of an
215                 overflow line
216 overflowoffset  integer positions to indent overflow lines
217 compwidth       integer positions to indent component text
218                 after the first line is output
219 uppercase       flag    output text of this component in all
220                 upper case
221 nouppercase     flag    don't uppercase
222 clearscreen     flag/G  clear the screen prior to each page
223 noclearscreen   flag/G  don't clearscreen
224 bell    flag/G  ring the bell at the end of each page
225 nobell  flag/G  don't bell
226 component       string/L        name to use instead of \*(lqcomponent\*(rq for
227                 this component
228 nocomponent     flag    don't output \*(lqcomponent: \*(rq for this
229                 component
230 center  flag    center component on line (works for
231                 one\-line components only)
232 nocenter        flag    don't center
233 leftadjust      flag    strip off leading whitespace on each
234                 line of text
235 noleftadjust    flag    don't leftadjust
236 compress        flag    change newlines in text to spaces
237 nocompress      flag    don't compress
238 wrap    flag    Wrap lines that exceed width (default)
239 nowrap  flag    Do not perform line wrapping
240 split   flag    don't combine multiple fields into
241                 a single field
242 nosplit flag    combine multiple fields into
243                 a single field
244 newline flag    print newline at end of components
245                 (this is the default)
246 nonewline       flag    don't print newline at end of components
247 formatfield     string  format string for this component
248                 (see below)
249 decode  flag    decode text as RFC-2047 encoded
250                 header field
251 addrfield       flag    field contains addresses
252 datefield       flag    field contains dates
253 format  flag    Run component through formatproc filter
254                 (body only)
255 noformat        flag    Do not run component through
256                 formatproc filter (default)
257 .fi
258 .RE
259 .PP
260 To specify the value of integer\-valued and string\-valued variables,
261 follow their name with an equals\-sign and the value.  Integer\-valued
262 variables are given decimal values, while string\-valued variables
263 are given arbitrary text bracketed by double\-quotes.  If a value is
264 suffixed by \*(lq/G\*(rq or \*(lq/L\*(rq, then its value is useful in
265 a global\-only or local\-only context (respectively).
266 .PP
267 A line of the form:
268 .PP
269 .RS 5
270 ignores=component,...
271 .RE
272 .PP
273 specifies a list of components which are never output.
274 .PP
275 The component \*(lqMessageName\*(rq (case\-insensitive) will output the
276 actual message name (file name) preceded by the folder name if one is
277 specified or found in the environment.  The format is identical to that
278 produced by the
279 .B \-header
280 option to
281 .BR show .
282 .PP
283 The component \*(lqExtras\*(rq will output all of the components of the
284 message which were not matched by explicit components, or included in
285 the ignore list.  If this component is not specified, an ignore list is
286 not needed since all non\-specified components will be ignored.
287 .PP
288 If \*(lqnocomponent\*(rq is NOT specified, then the component name will
289 be output as it appears in the format file.
290 .PP
291 The default format file is:
292 .PP
293 .RS 5
294 .nf
295 %mhl_format%
296 .fi
297 .RE
298 .PP
299 The variable \*(lqformatfield\*(rq specifies a format string (see
300 .BR mh\-format (5)).
301 The flag variables \*(lqaddrfield\*(rq and
302 \*(lqdatefield\*(rq (which are mutually exclusive), tell
303 .B mhl
304 to interpret the escapes in the format string as either addresses or
305 dates, respectively.
306 .PP
307 By default,
308 .B mhl
309 does not apply any formatting string to fields
310 containing address or dates (see
311 .BR mh\-mail (5)
312 for a list of these
313 fields).  Note that this results in faster operation since
314 .B mhl
315 must parse both addresses and dates in order to apply a format string
316 to them.  If desired,
317 .B mhl
318 can be given a default format string for
319 either address or date fields (but not both).  To do this, on a global
320 line specify: either the flag addrfield or datefield, along with the
321 appropriate formatfield variable string.
322 .PP
323 The \*(lqformat\*(rq flag specifies that this component will be run through
324 the filter program specified by the 
325 .IR formatproc
326 profile entry.  This filter program is expected to read data on standard
327 input and output data on standard output.  Currently the \*(lqformat\*(rq
328 flag is only supported for the \(*lqbody\*(rq component.  The component
329 name will be prefixed to the output
330 .IR after
331 the filter has been run.  The expected use of this is to filter a message
332 body to create more pleasing text to use in a reply message.
333 A suggested filter to use for
334 .BR repl(1)
335 is as follows:
336 .PP
337 .RS 5
338 body:component=">",overflowtext=">",overflowoffset=0,format,nowrap
339 .RE
340 .SH FILES
341 .fc ^ ~
342 .nf
343 .ta \w'%etcdir%/ExtraBigFileName  'u
344 ^%etcdir%/mhl.format~^The message template
345 ^or <mh\-dir>/mhl.format~^Rather than the standard template
346 ^$HOME/\&.mh\(ruprofile~^The user profile
347 .fi
348
349 .SH "PROFILE COMPONENTS"
350 .fc ^ ~
351 .nf
352 .ta 2.4i
353 .ta \w'ExtraBigProfileName  'u
354 ^moreproc:~^Program to use as interactive front\-end
355 ^formatproc:~^Program to use as a filter for components that
356 ^^have the \*(lqformat\*(rq flag set.
357 .fi
358
359 .SH "SEE ALSO"
360 show(1), ap(8), dp(8)
361
362 .SH DEFAULTS
363 .nf
364 .RB ` \-bell '
365 .RB ` \-noclear '
366 .RB ` \-length\ 40 '
367 .RB ` \-width\ 80 '
368 .fi
369
370 .SH CONTEXT
371 None
372
373 .SH BUGS
374 There should be some way to pass `bell' and `clear' information to the 
375 front\-end.
376 .PP
377 The \*(lqnonewline\*(rq option interacts badly with \*(lqcompress\*(rq
378 and \*(lqsplit\*(rq.