+.TH MHL %manext1% "September 14, 2014" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
-.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
+.B %nmhlibexecdir%/mhl
+.RB [ \-help ]
+.RB [ \-version ]
.RB [ \-bell " | " \-nobell ]
.RB [ \-clear " | " \-noclear ]
.RB [ \-folder
.RB [ \-moreproc
.IR program ]
.RB [ \-nomoreproc ]
+.RB [ \-fmtproc
+.IR program ]
+.RB [ \-nofmtproc ]
.RI [ files
.IR \&... ]
-.RB [ \-version ]
-.RB [ \-help ]
.ad
.SH DESCRIPTION
.B Mhl
will first search for this file in the user's
.B nmh
directory, and will then search in the directory
-.IR %etcdir% .
+.IR %nmhetcdir% .
This default
can be changed by using the
.B \-form
.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
leftadjust flag strip off leading whitespace on each
line of text
noleftadjust flag don't leftadjust
+rtrim flag trim whitespace at end of text lines
+nortrim flag retain whitespace at end of text
+ lines (default)
compress flag change newlines in text to spaces
nocompress flag don't compress
wrap flag Wrap lines that exceed width (default)
nonewline flag don't print newline at end of components
formatfield string format string for this component
(see below)
-decode flag decode text as RFC-2047 encoded
+decode flag decode text as RFC 2047 encoded
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
.RE
.PP
The variable \*(lqformatfield\*(rq specifies a format string (see
-.BR mh\-format (5)).
+.IR mh\-format (5)).
The flag variables \*(lqaddrfield\*(rq and
\*(lqdatefield\*(rq (which are mutually exclusive), tell
.B mhl
.B mhl
does not apply any formatting string to fields
containing address or dates (see
-.BR mh\-mail (5)
+.IR mh\-mail (5)
for a list of these
fields). Note that this results in faster operation since
.B mhl
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
+.IR 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
+.IR 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'%etcdir%/ExtraBigFileName 'u
-^%etcdir%/mhl.format~^The message template
+.ta \w'%nmhetcdir%/ExtraBigFileName 'u
+^%nmhetcdir%/mhl.format~^The message template
^or <mh\-dir>/mhl.format~^Rather than the standard template
^$HOME/\&.mh\(ruprofile~^The user profile
.fi
-
.SH "PROFILE COMPONENTS"
.fc ^ ~
.nf
.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"
-show(1), ap(8), dp(8)
-
+.IR show (1),
+.IR ap (8),
+.IR dp (8)
.SH DEFAULTS
.nf
.RB ` \-bell '
.RB ` \-noclear '
-.RB ` \-length 40 '
-.RB ` \-width 80 '
+.RB ` \-length\ 40 '
+.RB ` \-width\ 80 '
.fi
-
.SH CONTEXT
None
-
.SH BUGS
There should be some way to pass `bell' and `clear' information to the
front\-end.
.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.
projects / nmh / blobdiff