Removed unused fail label.

[nmh] / man / mh-format.man

diff --git a/man/mh-format.man b/man/mh-format.man
index 211f14f14e4d7ffb0e6cca68dc4adfc21df25f4d..22233b65b0860e8a0937ce64cb24dd0e4d48db4e 100644 (file)
--- a/man/mh-format.man
+++ b/man/mh-format.man
@@ -1,9 +1,9 @@
 .TH MH-FORMAT %manext5% 2015-01-10 "%nmhversion%"
 .TH MH-FORMAT %manext5% 2015-01-10 "%nmhversion%"

-.\"
+.

 .\" %nmhwarning%
 .\" %nmhwarning%

-.\"
+.

 .SH NAME
 .SH NAME

-mh-format \- format file for nmh message system
+mh-format \- formatting language for nmh message system

 .SH DESCRIPTION
 Several
 .B nmh
 .SH DESCRIPTION
 Several
 .B nmh


@@ -115,7 +115,7 @@ These are combined into the conditional execution construct:
 .nf
 .RI "%< " condition " " "format-text"
 .RI "%? " condition " " "format-text"
 .nf
 .RI "%< " condition " " "format-text"
 .RI "%? " condition " " "format-text"

-    \&...
+    ...

 .RI "%| " "format-text"
 %>
 .fi
 .RI "%| " "format-text"
 %>
 .fi


@@ -123,7 +123,7 @@ These are combined into the conditional execution construct:
 .PP
 (Extra white space is shown here only for clarity.)
 These constructs, which may be nested without ambiguity, form a general
 .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".
 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".


@@ -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
 .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)
 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
 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
 .\" 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
                        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.
 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
 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.)
 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
 .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.
 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.
 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
 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\^)
 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
 .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
 .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
 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 (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
 it begins with a %, and thus the value of that component is output.
 This also has the side effect of setting the
 .I str


@@ -532,7 +551,7 @@ register for the width) a better implementation would look like:
 .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
 .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.
 clause sets the
 .I str
 register.


@@ -769,6 +788,6 @@ at 4 digits.
 .SH "SEE ALSO"
 .IR scan (1),
 .IR repl (1),
 .SH "SEE ALSO"
 .IR scan (1),
 .IR repl (1),

-.IR fmttest (1),
+.IR fmttest (1)

 .SH CONTEXT
 None
 .SH CONTEXT
 None