.\" %nmhwarning%
.
.SH NAME
-mh-format \- format file for nmh message system
+mh-format \- formatting language for nmh message system
.SH DESCRIPTION
Several
.B nmh
.nf
.RI "%< " condition " " "format-text"
.RI "%? " condition " " "format-text"
- \&...
+ ...
.RI "%| " "format-text"
%>
.fi
.PP
(Extra white space is shown here only for clarity.)
These constructs, which may be nested without ambiguity, form a general
-.B if\-elseif\-else\-endif
+.B if-elseif-else-endif
block where only one of the format-texts is interpreted. In other
words, `%<' is like the "if", `%?' is like the "elseif", `%|' is like
"else", and `%>' is like "endif".
.RS 5
.nf
.ta \w'Fformataddr 'u +\w'Aboolean 'u +\w'Rboolean 'u
-.I "Function Argument Result Description"
+.I "Function Argument Return Description"
msg integer message number
cur integer message is current (0 or 1)
unseen integer message is unseen (0 or 1)
lit literal string Set \fIstr\fR to \fIarg\fR.
lit string Clear \fIstr\fR.
getenv literal string Set \fIstr\fR to environment value of \fIarg\fR
-profile literal string Set \fIstr\fR to profile component \fIarg\fR
- value
+profile literal string Set \fIstr\fR to profile or context
+ component \fIarg\fR value
.\" dat literal int return value of dat[arg]
nonzero expr boolean \fInum\fR is non-zero
zero expr boolean \fInum\fR is zero
component
unquote expr string remove RFC 2822 quotes from \fIstr\fR
trim expr trim trailing whitespace from \fIstr\fR
+trimr expr string Like %(trim), also returns string
kilo expr string express in SI units: 15.9K, 2.3M, etc.
%(kilo) scales by factors of 1000,
kibi expr string express in IEC units: 15.5Ki, 2.2Mi.
%(kibi) scales by factors of 1024.
+ordinal expr string Output ordinal suffix based on value
+ of \fInum\fR (st, nd, rd, th)
putstr expr print \fIstr\fR
putstrf expr print \fIstr\fR in a fixed width
putnum expr print \fInum\fR
if the \*(lq\fIcomp\fR\*(rq header is not present in the message.
If needed, the (\fInull\fR\^) function can be used to explicitly
test for this case.)
+.PP
+The \fIfriendly\fR\^{\fIcomp\fR\^}) call will return any double-quoted
+\*(lqpersonal name\*(rq (that is, anything before <>), then it will return
+that. If there's no personal name but there is a
+\*(lqnote\*(rq (comments string after an email address), it will return
+that. If there is neither of those it will just return the bare email address.
+
.SS Formatting
When a function or component escape is interpreted and the result will
be printed immediately, an optional field width can be specified to
size in a field six characters wide filled with leading zeros;
%14(\fIputstrf\^\fR{\fIfrom\^\fR}) will print the \*(lqFrom:\*(rq 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
+Using a negative value for the field width causes
+right-justification within the field, with padding on
the left up to the field width.
+Padding is with spaces except for a left-padded
+.I putnumf
+when the width starts with zero.
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
If you need to create an address list that includes previously-seen
addresses you may use the (\fIconcataddr\fR\^) function, which is identical
to (\fIformataddr\fR\^) in all other respects. Note that (\fIconcataddr\fR\^)
-does NOT add addresses to the duplicate-suppression cache.
+does
+.I not
+add addresses to the duplicate-suppression cache.
.SS Other Hints and Tips
Sometimes, the writer of a format function is confused because output is
duplicated. The general rule to remember is simple: If a function or
.fi
.RE
.PP
-Unfortunately, if the Reply-to: header is NOT present, the output line
+Unfortunately, if the Reply-to: header is
+.I not
+present, the output line
will be something like:
.PP
.RS 5
statement (so the rule about not starting with % applies). But the component
escape in our
.B else
-statement (everything after the `%|') is NOT an argument to anything;
+statement (everything after the `%|') is
+.I not
+an argument to anything;
it begins with a %, and thus the value of that component is output.
This also has the side effect of setting the
.I str
.PP
It should be noted here that the side effects of function and component
escapes are still in force and, as a result, each component test in the
-.B if\-elseif\-else\-endif
+.B if-elseif-else-endif
clause sets the
.I str
register.
.SH "SEE ALSO"
.IR scan (1),
.IR repl (1),
-.IR fmttest (1),
+.IR fmttest (1)
.SH CONTEXT
None
projects / nmh / blobdiff