.\"
-.\" THIS FILE HAS BEEN AUTOMATICALLY GENERATED. DO NOT EDIT.
+.\" %nmhwarning%
.\"
.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
.PP
There are a few alternate scan listing formats available
in
-.IR nmh/etc/scan.time ,
-.IR nmh/etc/scan.size ,
+.IR mmh/etc/scan.time ,
+.IR mmh/etc/scan.size ,
and
-.IR nmh/etc/scan.timely .
+.IR mmh/etc/scan.timely .
Look in
-.I nmh/etc
+.I mmh/etc
for other
.B scan
and
format files which may have been written at your site.
.PP
It suffices to have your local
-.B nmh
+.B mh
expert actually write new format
commands or modify existing ones. This manual section explains how to
do that. Note: familiarity with the C
and
exists for each header found in the message being processed. For example
.RI `%{ date }'
-refers to the \*(lqDate:\*(rq field of the appropriate message.
+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
.RS 5
.nf
.ta +\w'Argument 'u +\w'An optional component, 'u
-.I Argument Description Example Syntax
+.I "Argument Description Example Syntax
literal A literal number %(\fIfunc\fR 1234)
or string %(\fIfunc\fR text string)
comp Any component %(\fIfunc\fR\^{\fIin-reply-to\fR\^})
.fi
.RE
.PP
-writes the value of the header component \*(lqFrom:\*(rq to the
+writes the value of the header component `From:' to the
internal register named str; then (\fImymbox\fR\^) reads str and
writes its result to the internal register named
.IR num ;
If
.IR num
is non-zero, the
-string \*(lqTo:\*(rq is printed followed by the value of the
-header component \*(lqTo:\*(rq.
+string `To:' is printed followed by the value of the
+header component `To:'.
.SS Evaluation
The evaluation of format strings is performed
by a small virtual machine.
.RS 5
.nf
.ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
-.I Function Argument Result Description
+.I "Function Argument Result Description
msg integer message number
cur integer message is current (0 or 1)
unseen integer message is unseen (0 or 1)
nonnull expr boolean \fIstr\fR is non-empty
void expr Set \fIstr\fR or \fInum\fR
comp comp string Set \fIstr\fR to component text
-compval comp integer Set \fInum\fR to \*(lq\fBatoi\fR(\fIcomp\fR\^)\*(rq
+compval comp integer Set \fInum\fR to `\fBatoi\fR(\fIcomp\fR\^)'
.\" 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)
putstrf expr print \fIstr\fR in a fixed width
putnum expr print \fInum\fR
putnumf expr print \fInum\fR in a fixed width
-.\" addtoseq literal add msg to sequence (LBL option)
nodate string integer Argument not a date string (0 or 1)
formataddr expr append \fIarg\fR to \fIstr\fR as a
(comma separated) address list
.RS 5
.nf
.ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
-.I Function Argument Return Description
+.I "Function Argument Return Description
sec date integer seconds of the minute
min date integer minutes of the hour
hour date integer hours of the day (0-23)
.RS 5
.nf
.ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
-.I Function Argument Return Description
+.I "Function Argument Return Description
proper addr string official 822 rendering
friendly addr string user-friendly rendering
addr addr string mbox@host or host!mbox rendering*
.PP
(A clarification on (\fImymbox\fR\^{\fIcomp\fR\^}) is in order.
This function checks each of the addresses in the header component
-\*(lq\fIcomp\fR\*(rq against the user's mailbox name and any
-.RI \*(lq Alternate-Mailboxes \*(rq.
+`\fIcomp\fR' against the user's mailbox name and any
+.RI ` Alternate-Mailboxes '.
It returns true if any address matches,
-however, it also returns true if the \*(lq\fIcomp\fR\*(rq header is not
+however, it also returns true if the `\fIcomp\fR' header is not
present in the message. If needed, the (\fInull\fR\^) function can be
used to explicitly test for this case.)
.SS Formatting
specified by their leading field width argument. For example,
%06(\fIputnumf\fR\^(\fIsize\fR\^)) will print the message
size in a field six characters wide filled with leading zeros;
-%14(\fIputstrf\^\fR{\fIfrom\^\fR}) will print the \*(lqFrom:\*(rq header
+%14(\fIputstrf\^\fR{\fIfrom\^\fR}) will print the `From:' header
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
.PP
.RS
.nf
-%4(msg)%<(cur)+%| %>%<{replied}\-%?{encrypted}E%| %>
+%4(msg)%<(cur)+%| %>%<{replied}\-%| %>
.fi
.RE
.PP
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; if a \*(lqReplied:\*(rq field is present then a `\-'
-else if an \*(lqEncrypted:\*(rq field is present then an `E' otherwise
-a space should be printed. Next:
+be printed; if a `Replied:' field is present then a `\-'
+else a space should be printed. Next:
.PP
.RS
.nf
.fi
.RE
.PP
-If a \*(lqDate:\*(rq field was present,
+If a `Date:' field was present,
then a space is printed, otherwise a `*'.
Next,
.PP
.fi
.RE
.PP
-if the message is from me, and there is a \*(lqTo:\*(rq header,
-print \*(lqTo:\*(rq followed by a \*(lquser-friendly\*(rq rendering of the
-first address in the \*(lqTo:\*(rq field; any MIME-encoded
+if the message is from me, and there is a `To:' header,
+print `To:' followed by a `user-friendly' rendering of the
+first address in the `To:' field; any MIME-encoded
characters are decoded into the actual characters.
Continuing,
.PP
.RE
.PP
if either of the above two tests failed,
-then the \*(lqFrom:\*(rq address is printed
-in a mime-decoded, \*(lquser-friendly\*(rq format.
+then the `From:' address is printed
+in a mime-decoded, `user-friendly' format.
And finally,
.PP
.RS 5
.nf
-%(decode{subject})%<{body}<<%{body}>>%>
+%(decode{subject})
.fi
.RE
.PP
-the mime-decoded subject and initial body (if any) are printed.
+the mime-decoded subject is printed.
.PP
For a more complicated example, next consider
a possible
.PP
This clears
.I str
-and formats the \*(lqReply-To:\*(rq header
+and formats the `Reply-To:' header
if present. If not present, the else-if clause is executed.
.PP
.RS 5
.RE
.PP
This formats the
-\*(lqFrom:\*(rq, \*(lqSender:\*(rq and \*(lqReturn-Path:\*(rq
+`From:', `Sender:' and `Return-Path:'
headers, stopping as soon as one of them is present. Next:
.PP
.RS 5
.PP
If the \fIformataddr\fR result is non-null, it is printed as
an address (with line folding if needed) in a field \fIwidth\fR
-wide with a leading label of \*(lqTo:\*(rq.
+wide with a leading label of `To:'.
.PP
.RS 5
.nf
.RE
.PP
.I str
-is cleared, and the \*(lqTo:\*(rq and \*(lqCc:\*(rq headers, along with the user's
+is cleared, and the `To:' and `Cc:' headers, along with the user's
address (depending on what was specified with
-the \*(lq\-cc\*(rq switch to \fIrepl\fR\^) are formatted.
+the `\-cc' switch to \fIrepl\fR\^) are formatted.
.PP
.RS 5
.nf
.RE
.PP
If the result is non-null, it is printed as above with a
-leading label of \*(lqCc:\*(rq.
-.PP
-.RS 5
-.nf
-%<{fcc}Fcc: %{fcc}\\n%>\\
-.fi
-.RE
-.PP
-If a
-.B \-fcc
-.I folder
-switch was given to
-.B repl
-(see
-.BR repl (1)
-for more details about %{\fIfcc\fR\^}),
-an \*(lqFcc:\*(rq header is output.
+leading label of `Cc:'.
.PP
.RS 5
.nf
.fi
.RE
.PP
-If a message-id component was present, an \*(lqIn-Reply-To:\*(rq header is
-output including the message-id, followed by a \*(lqReferences:\*(rq
+If a message-id component was present, an `In-Reply-To:' header is
+output including the message-id, followed by a `References:'
header with references, if present, and the message-id.
As with all
plain-text, the row of dashes are output as-is.
.nf
.ta .5i 1i 1.5i 2i
if (comp_exists(message-id)) then
- print (\*(lqIn-reply-to: \*(rq)
+ print (`In-reply-to: ')
print (message-id.value)
- print (\*(lq\\n\*(rq)
+ print (`\\n')
endif
if (comp_exists(message-id)) then
- print (\*(lqReferences: \*(rq)
+ print (`References: ')
if (comp_exists(references)) then
print(references.value);
endif
print (message-id.value)
- print (\*(lq\\n\*(rq)
+ print (`\\n')
endif
.fi
.RE
.\" support this syntax?'' MH has been hacked on for a long time...)
.\".PP
One more example: Currently,
-.B nmh
+.B mmh
supports very
large message numbers, and it is not uncommon for a folder
to have far more than 10000 messages.
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