.\"
.TH MH-FORMAT %manext5% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
-mh-format \- format file for nmh message system
+mh-format \- format file for mh message system
.SH DESCRIPTION
Several
-.B nmh
+.B mmh
commands utilize either a
.I format
string or a
uses a format file which directs it
how to generate the reply to a message, and so on.
.PP
-There are a few alternate scan listing formats available
-in
-.IR nmh/etc/scan.time ,
-.IR nmh/etc/scan.size ,
+There are a few alternate scan listing formats available, e.g.
+.IR scan.nmh ,
+.IR scan.mailx ,
and
-.IR nmh/etc/scan.timely .
+.IR scan.timely .
Look in
-.I nmh/etc
+.I %etcdir%
for other
.B scan
and
.B repl
-format files which may have been written at your site.
+format files.
.PP
-It suffices to have your local
-.B nmh
-expert actually write new format
-commands or modify existing ones. This manual section explains how to
-do that. Note: familiarity with the C
+This manual section explains how to write and modify format commands.
+Note: familiarity with the C
.B printf
routine is assumed.
.PP
.SS SYNTAX
Format strings are built around
.IR "escape sequences" .
-There are three types of escape sequences: header
-.IR components ,
-built-in
-.IR functions ,
-and flow
-.IR 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)
+There are four types of escape sequences:
+.PP
+.RS 5
+.nf
+.ta +\w'name of escape class xxxxxxx'u
+.RI "1) header components %{" component }
+.RI "2) built-in functions %(" "function arg" )
+.RI "3) flow control %< ... %? ... %| ... %>
+.RI "4) comments %; ...
+.fi
+.RE
+.PP
+Comments may be inserted in most places where no function argument is
+expected. A comment begins with `%;' and ends with a (non-escaped)
newline.
.PP
A
or a control escape. When the argument is a function or a
component, they are listed without a leading `%'. When control escapes
are used as function arguments, they written as normally, with
-a leading `%';
+a leading `%'.
.SS "Control escapes"
.PP
.fi
.RE
.PP
-Extra white space is shown here only for clarity. These
+(Extra white space is shown here only for clarity.) These
constructs may be nested without ambiguity. They form a general
.B if\-elseif\-else\-endif
block where only one of the
a non-empty string, and false for an empty string.
.PP
-The `%?' control escape is optional, and may there may be more
+The `%?' control escape is optional, and there may be more
than one `%?' control escape in a conditional block.
The `%|' control escape
is also optional, but may be included at most once.
.I str
is used as the argument: which register is
used depends on the function, as listed below.
+.\" What is the difference between these two lines:
+.\" %(void{comp})%(trim)%(putstr)
+.\" %(putstr(trim{comp}))
+.\" The latter can be used as a single expression for %<.
+.\" It does make a difference for (decode) because in the former
+.\" way, wrapping (decode) with (void) can be necessary.
+.\" What is the preferred way?
.PP
Component escapes write the value of their message header in
.IR str .
.\" compflag comp integer Set \fInum\fR to component flags bits (internal)
.\" decodecomp comp string Set \fIstr\fR to RFC-2047 decoded component text
decode expr string decode \fIstr\fR as RFC-2047 (MIME-encoded)
- component
+ component and print it
unquote expr string remove RFC-2822 quotes from \fIstr\fR
+unmailto expr string remove `mailto:' and < > from \fIstr\fR
trim expr trim trailing white-space from \fIstr\fR
putstr expr print \fIstr\fR
putstrf expr print \fIstr\fR in a fixed width
dst date integer daylight savings in effect? (0 or 1)
clock date integer seconds since the UNIX epoch
rclock date integer seconds prior to current time
-tws date string official 822 rendering
+tws date string official RFC-822 rendering
pretty date string user-friendly rendering
.fi
.RE
.nf
.ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
.I "Function Argument Return Description
-proper addr string official 822 rendering
+proper addr string official RFC-822 rendering
friendly addr string user-friendly rendering
addr addr string mbox@host or host!mbox rendering*
pers addr string the personal name*
component in fourteen characters with trailing spaces added as needed.
For \fIputstrf\fR, using a negative value for the field width causes
right-justification of the string within the field, with padding on
-the left up to the field width.
-The functions (\fIputnum\fR\^) and
-(\fIputstr\fR\^) are somewhat special: they print their result in the minimum number of characters
-required, and ignore any leading field width argument.
+the left up to the field width. The functions (\fIputnum\fR\^) and
+(\fIputstr\fR\^) are somewhat special: they print their result in
+the minimum number of characters required, and ignore any leading
+field width argument.
.PP
The available output width is kept in an internal register; any output
past this width will be truncated.
.SS Examples
-With all this in mind,
-here's the default format string for
+With all this in mind, here's a format string for
.BR scan .
It's been divided into several pieces for readability.
The first part is:
.RE
.PP
This formats the
-`From:', `Sender:' and `Return-Path:'
+`From:', `Sender:' or `Return-Path:'
headers, stopping as soon as one of them is present. Next:
.PP
.RS 5
.PP
.RS 5
.nf
-%<{subject}Subject: Re: %{subject}\\n%>\\
+%<{subject}Subject: Re: %(decode{subject})\\n%>\\
.fi
.RE
.PP
.nf
.ta .5i 1i 1.5i 2i
if (comp_exists(message-id)) then
- print (`In-reply-to: ')
- print (message-id.value)
- print (`\\n')
+ print("In-reply-to: ")
+ print(message-id.value)
+ print("\\n")
endif
if (comp_exists(message-id)) then
- print (`References: ')
+ print("References: ")
if (comp_exists(references)) then
print(references.value);
endif
- print (message-id.value)
- print (`\\n')
+ print(message-id.value)
+ print("\\n")
endif
.fi
.RE
.\" (Note that this pseudocode begs the question ``why not just
.\" support this syntax?'' MH has been hacked on for a long time...)
.\".PP
-One more example: Currently,
-.B nmh
+One more example:
+.B Mmh
supports very
large message numbers, and it is not uncommon for a folder
to have far more than 10000 messages.
.\" process 200 messages a day and still get some real work
.\" done." The authors apparently only planned to get
.\" real work done for about 50 days per folder.)
-Nontheless (as noted above)
-the various scan format strings are inherited
+Nonetheless several scan format strings are inherited
from older MH versions, and are generally hard-coded to 4
digits of message number before formatting problems
start to occur.
-The nmh format strings can be modified to behave more sensibly with larger
+The mh format strings can be modified to behave more sensibly with larger
message numbers:
.PP
.RS