Bart Massey submitted an update to the mh-format man page as part of
bug report 2031. I'm not an expert on the content, but it looks like
he's done a good job at improving this page.
Please review it, and if there are no corrections, I plan to commit it.
Thanks.
Name
mh-format - format file for nmh message system
Synopsis
some nmh commands
Description
Several nmh commands utilize either a format string or a
format file during their execution. For example, scan
uses a format string which directs it how to generate the
scan listing for each message; repl uses a format file
which directs it how to generate the reply to a message,
and so on.
Format strings are designed to be efficiently parsed by
nmh which means they are not necessarily simple to write
and understand. This means that novice, casual, or even
advanced users of nmh should not have to deal with them.
There are a few alternate scan listing formats available
in /etc/nmh/scan.time, /etc/nmh/scan.size, and
/etc/nmh/scan.timely. Look in /etc/nmh for other scan and
repl format files which may have been written at your
site.
It suffices to have your local nmh expert actually write
new format commands or modify existing ones. This manual
section explains how to do that. Note: familiarity with
the C printf routine is assumed.
A format string consists of ordinary text, and special
multi-character escapesequences which begin with `%'.
When specifying a format string, the usual C backslash
characters are honored: `\b', `\f', `\n', `\r', and `\t'.
Continuation lines in format files end with `\' followed
by the newline character.
SYNTAX
Format strings are built around escape sequences. There
are three types of escape sequences: header components,
built-in functions, and flow control. Comments may be
inserted in most places where a function argument is not
expected. A comment begins with `%;' and ends with a
(non-escaped) newline.
A component escape is specified as `%{component}', and
exists for each header found in the message being pro-
cessed. For example `%{date}' refers to the Date: field
of the appropriate message. All component escapes have a
string value. Normally, component values are compressed
by converting any control characters (tab and newline
included) to spaces, then eliding any leading or multiple
spaces. However, commands may give different interpreta-
tions to some component escapes; be sure to refer to each
command's manual entry for complete details.
A function escape is specified as `%(function)'. All
functions are built-in, and most have a string or numeric
value. A function escape may have an argument. The argu-
ment follows the function escape: separating whitespace is
discarded: `%(function argument)'.
The argument to a function escape is processed in argument
mode. A function or component escape evaluated in argu-
ment mode should not be preceded by a leading `%'. Condi-
tional escapes (see below) are allowed, and are entered
normally.
Control-flow escapes
A control escape is one of: `%', `%?', `%|', or `%'.
These are combined into the conditional execution con-
struct:
% condition format-text
%? condition format-text
...
%| format-text
%
Extra white space is shown here only for clarity. These
constructs may be nested without ambiguity. They form a
general if-elseif-else-endif block where only one of the
format-texts is interpreted.
A `%' or `%?' control escape causes its condition to be
evaluated. This condition is a component or function
escape evaluated in argument mode. The control escape
tests whether the function or component escape evaluates
non-zero (for an integer-valued escape) or non-empty (for
a string-valued escape).
If the condition of a `%' or `%?' control escape
evaulates true, or a `%|' escape is encountered, then the
format-text of that escape (up to the next corresponding
`%|', `%?', or `%' control escape) is interpreted nor-
mally. Text up to the corresponding `%' control escape is
then skipped, and the `%' control escape is discarded.
If the condition of a `%' or `%?' control escape evalu-
ates false, however, the format-text (up to the next cor-
responding `%|', `%?', or `%' control escape) is skipped
instead of being
