X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/125748e4eb5137dae49ed218cd728d988b1e4468..0f343e7716fbc0401663dc37ecc94874c23ff68e:/man/mh-format.man?ds=sidebyside

diff --git a/man/mh-format.man b/man/mh-format.man
index 59d55d60..22233b65 100644
--- a/man/mh-format.man
+++ b/man/mh-format.man
@@ -3,7 +3,7 @@
 .\" %nmhwarning%
 .
 .SH NAME
-mh-format \- format file for nmh message system
+mh-format \- formatting language for nmh message system
 .SH DESCRIPTION
 Several
 .B nmh
@@ -241,7 +241,7 @@ The function escapes may be roughly grouped into a few categories.
 .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)
@@ -269,8 +269,8 @@ num		integer	Set \fInum\fR to zero.
 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
@@ -285,10 +285,13 @@ decode	expr	string	decode \fIstr\fR as RFC 2047 (MIME-encoded)
 			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
@@ -411,6 +414,13 @@ It returns true if any address matches. However, it also returns true
 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
@@ -429,9 +439,12 @@ specified by their leading field width argument.  For example,
 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
@@ -474,7 +487,9 @@ an internal cache and will use this cache to suppress duplicate addresses.
 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
@@ -490,7 +505,9 @@ the From: and Reply-To: headers:
 .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
@@ -507,7 +524,9 @@ argument to the
 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
@@ -769,6 +788,6 @@ at 4 digits.
 .SH "SEE ALSO"
 .IR scan (1),
 .IR repl (1),
-.IR fmttest (1),
+.IR fmttest (1)
 .SH CONTEXT
 None