.\"
-.\" 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
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
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
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.
.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.
.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 .
.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)
- 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
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)
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
.RS 5
.nf
.ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
-.I Function Argument Return Description
-proper addr string official 822 rendering
+.I "Function Argument Return Description
+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*
.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
-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:
.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:' or `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
-%<{subject}Subject: Re: %{subject}\\n%>\\
+%<{subject}Subject: Re: %(decode{subject})\\n%>\\
.fi
.RE
.PP
.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 (message-id.value)
- print (\*(lq\\n\*(rq)
+ print("In-reply-to: ")
+ print(message-id.value)
+ 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(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
projects / mmh / blobdiff