.\"
.\" %nmhwarning%
-.\" $Id$
.\"
.TH MHL %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
mhl \- produce formatted listings of nmh messages
.SH SYNOPSIS
.HP 5
+.na
.B %libdir%/mhl
.RB [ \-bell " | " \-nobell ]
.RB [ \-clear " | " \-noclear ]
.RB [ \-moreproc
.IR program ]
.RB [ \-nomoreproc ]
+.RB [ \-fmtproc
+.IR program ]
+.RB [ \-nofmtproc ]
.RI [ files
.IR \&... ]
.RB [ \-version ]
.RB [ \-help ]
+.ad
.SH DESCRIPTION
.B Mhl
is an
.RS 5
.nf
.ta \w'noclearscreen 'u +\w'integer/G 'u
-.I variable type semantics
+.I "variable type semantics"
width integer screen width or component width
length integer screen length or component length
offset integer positions to indent \*(lqcomponent: \*(rq
noleftadjust flag don't leftadjust
compress flag change newlines in text to spaces
nocompress flag don't compress
+wrap flag Wrap lines that exceed width (default)
+nowrap flag Do not perform line wrapping
split flag don't combine multiple fields into
a single field
nosplit flag combine multiple fields into
header field
addrfield flag field contains addresses
datefield flag field contains dates
+format flag Run component through formatproc filter
+ (body only)
+noformat flag Do not run component through
+ formatproc filter (default)
+formatarg string Argument to format filter
.fi
.RE
.PP
either address or date fields (but not both). To do this, on a global
line specify: either the flag addrfield or datefield, along with the
appropriate formatfield variable string.
-
+.PP
+The \*(lqformat\*(rq flag specifies that this component will be run through
+the filter program specified by the
+.IR formatproc
+profile entry. This filter program is expected to read data on standard
+input and output data on standard output. Currently the \*(lqformat\*(rq
+flag is only supported for the \*(lqbody\*(rq component. The component
+name will be prefixed to the output
+.IR after
+the filter has been run. The expected use of this is to filter a message
+body to create more pleasing text to use in a reply message.
+A suggested filter to use for
+.BR repl(1)
+is as follows:
+.PP
+.RS 5
+body:component=">",overflowtext=">",overflowoffset=0,format,nowrap
+.RE
+.PP
+The
+.B \-fmtproc
+and
+.B \-nofmtproc
+switches can be used to override the
+.I formatproc
+profile entry.
+.PP
+The
+.I formatarg
+option specifies a string that is used as an argument to the format filter.
+This string is processed by
+.BR mh\-format (5)
+and all of the message components are available for use. Multiple
+.I formatarg
+options can be used to build up multiple arguments to the format filter.
.SH FILES
.fc ^ ~
.nf
-.ta \w'/usr/local/nmh/etc/ExtraBigFileName 'u
+.ta \w'%etcdir%/ExtraBigFileName 'u
^%etcdir%/mhl.format~^The message template
^or <mh\-dir>/mhl.format~^Rather than the standard template
^$HOME/\&.mh\(ruprofile~^The user profile
.ta 2.4i
.ta \w'ExtraBigProfileName 'u
^moreproc:~^Program to use as interactive front\-end
+^formatproc:~^Program to use as a filter for components that
+^^have the \*(lqformat\*(rq flag set.
.fi
.SH "SEE ALSO"
.nf
.RB ` \-bell '
.RB ` \-noclear '
-.RB ` \-length 40 '
-.RB ` \-width 80 '
+.RB ` \-length\ 40 '
+.RB ` \-width\ 80 '
.fi
.SH CONTEXT
.PP
The \*(lqnonewline\*(rq option interacts badly with \*(lqcompress\*(rq
and \*(lqsplit\*(rq.
+.PP
+The \*(lqformat\*(rq option really should work on something other than the body
+component.