MH-FORMAT(5) [mh.6] MH-FORMAT(5)
NAME
mh-format - format file for MH message system
SYNOPSIS
some MH commands
DESCRIPTION
Several MH commands utilize either a format string or a
format file during their execution. For example, scan (1)
uses a format string which directs it how to generate the
scan listing for each message; repl (1) 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 MH
since they represent an integral part of MH. This means
that novice, casual, or even advanced users of MH should
deal with them. It suffices to have your local MH expert
actually write new format commands or modify existing
ones. This manual section explains how to do just that.
A format string is similar to a printf (3) string, but
uses multi-letter `%'-escapes. When specifying a 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.
The interpretation model is based on a simple machine with
two registers, num and str. The former contains an inte-
ger value, the latter a string value. When an escape is
processed, if it requires an argument, it reads the cur-
rent value of either num or str; and, if it returns a
value, it writes either num or str.
Escapes are of three types: components, functions, and,
control. A component escape is specified as `%{name}',
and is created for each header found in the message being
processed. For example `%{date} refers to the Date: field
of the appropriate message. A component escape is always
string valued.
A control escape is one of: `%<escape', `%|', and `%>',
which correspond to if-then-else constructs: if `escape'
is non-zero (for integer-valued escapes), or non-empty
(for string-valued escapes), then everything up to `%|' or
`%>' (whichever comes first) is interpreted; otherwise,
then skip to `%|' or `%>' (whichever comes first) and
start interpreting again.
A function escape is specified as `%(name)', and is stati-
cally defined. Here is the list:
escape argument returns interpretation
nonzero integer integer num is non-zero
zero integer integer num is zero
MH November 30, 1989 1
MH-FORMAT(5) [mh.6] MH-FORMAT(5)
eq integer integer num == width
ne integer integer num != width
gt integer integer width > num
null string integer str is empty
nonnull string integer str is non-empty
putstr string print str
putstrf string print str in the specified width
(e.g., %20(putstrf{subject})
trim string string remove leading and trailing white space
and optionally limit width
putnum integer print num
putnumf integer print num in the specified width
(e.g., %4(putnumf(msg))
msg integer message number
cur integer message is current
size integer size of message
strlen string integer length of str
me string the user's mailbox
plus integer add width to num
minus integer subtract num from width
divide integer divide width by num
charleft integer space left in output buffer
timenow integer seconds since the UNIX epoch
When str is a date, these escapes are useful:
escape argument returns interpretation
sec string integer seconds of the minute
min string integer minutes of the day
hour string integer hours of the day (24 hour clock)
mday string integer day of the month
mon string integer month of the year
wday string integer day of the week (Sunday=0)
year string integer year of the century
yday string integer day of the year
dst string integer daylight savings in effect
zone string integer timezone
sday string integer day of the week known
1 for explicit in date
0 for implicit (MH figured it out)
-1 for unknown (MH couldn't figure it out)
clock string integer seconds since the UNIX epoch
rclock string integer seconds prior to current time
month string string month of the year
lmonth string string month of the year (long form)
tzone string string timezone
szone string integer timezone known
1 for explicit in date
-1 for unknown
day string string day of the week
weekday string string day of the week (long)
tws string string official 822 rendering of the date
pretty string string a more user-friendly rendering
nodate string date wasn't parseable
date2local string coerce date to local timezone
MH November 30, 1989 2
MH-FORMAT(5) [mh.6] MH-FORMAT(5)
date2gmt string coerce date to gmt
When str is an address, these escapes are useful:
escape argument returns interpretation
pers string string the personal name of the address
mbox string string the local part of the address
host string string the domain part of the address
path string string the route part of the address
type string integer the type of host
-1 for uucp
0 for local
1 for network
2 for unknown
nohost string integer no host was present in the address
ingrp string integer the address appeared inside a group
gname string string name of the group (present for first
address only)
note string string commentary text
proper string string official 822 rendering of the address
friendly string string a more user-friendly rendering
mymbox string the address refers to the user's mailbox
formataddr string print str in an address list
With all this in mind, here's the default format string
for scan. It's been divided into several pieces for read-
ability. The first part is:
%4(putnumf(msg))%<(cur)+%| %>%<{replied}-%| %>
which says that the message number should be printed in
four digits, if the message is the current message then a
`+' else a space should be printed, and if a Replied:
field is present then a `-' else a space should be
printed. Next:
%02(putnumf(mon{date}))/%02(putnumf(mday{date}))
the hours and minutes are printed in two digits (zero
filled). Next,
%<{date} %|*>
If no Date: field was present, then a `*' is printed, oth-
erwise a space. Next,
%<(mymbox{from})To:%14(putstrf(friendly{to}))
if the message is from me, print `To:' followed by a
user-friendly rendering of the first address in the To:
field. Continuing,
%|%17(putstrf(friendly{from}))%>
if the message isn't from me, then the print the From:
MH November 30, 1989 3
MH-FORMAT(5) [mh.6] MH-FORMAT(5)
address is printed. And finally,
%{subject}%<{body}<<%{body}%>
the subject and initial body are printed.
Although this seems complicated, in point of fact, this
method is flexible enough to extract individual fields and
print them in any format the user desires.
If the `-form formatfile' switch is given, scan will treat
each line in the named file as a format string and act
accordingly. This lets the user employ canned scan list-
ing formats. Take a look at the three files
/usr/contrib/mh/lib/scan.time,
/usr/contrib/mh/lib/scan.size, and
/usr/contrib/mh/lib/scan.timely.
FILES
None
PROFILE COMPONENTS
None
SEE ALSO
ap(8), dp(8)
DEFAULTS
None
CONTEXT
None
BUGS
On hosts where MH was configured with the BERK option,
address parsing is not enabled.
MH November 30, 1989 4