Added format support for zputlit function escape. It requires

[mmh] / man / mh-format.man

diff --git a/man/mh-format.man b/man/mh-format.man
index d8a83b2..6d84c97 100644 (file)
--- a/man/mh-format.man
+++ b/man/mh-format.man
@@ -1,7 +1,7 @@
+.TH MH-FORMAT %manext5% "November 4, 2012" "%nmhversion%"

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

-.TH MH-FORMAT %manext5% "%nmhdate%" MH.6.8 [%nmhversion%]

 .SH NAME
 mh-format \- format file for nmh message system
 .SH DESCRIPTION
 .SH NAME
 mh-format \- format file for nmh message system
 .SH DESCRIPTION

@@ -46,7 +46,6 @@ escape sequences which begin with `%'.  When specifying a format
 string, the usual C backslash characters are honored: `\\b', `\\f',
 `\\n', `\\r', and `\\t'.  Continuation lines in format files end with
 `\\' followed by the newline character.
 string, the usual C backslash characters are honored: `\\b', `\\f',
 `\\n', `\\r', and `\\t'.  Continuation lines in format files end with
 `\\' followed by the newline character.

-

 .\" TALK ABOUT SYNTAX FIRST, THEN SEMANTICS
 .SS SYNTAX
 Format strings are built around
 .\" TALK ABOUT SYNTAX FIRST, THEN SEMANTICS
 .SS SYNTAX
 Format strings are built around

@@ -100,7 +99,6 @@ 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 `%';
 component, they are listed without a leading `%'.  When control escapes
 are used as function arguments, they written as normally, with
 a leading `%';

-

 .SS "Control escapes"
 .PP
 A
 .SS "Control escapes"
 .PP
 A

@@ -137,13 +135,11 @@ if the function return or component value is non-zero, and false if zero.
 For string valued functions or components, the condition is true
 if the function return or component value is 
 a non-empty string, and false for an empty string.
 For string valued functions or components, the condition is true
 if the function return or component value is 
 a non-empty string, and false for an empty string.

-

 .PP
 The `%?' control escape is optional, and may 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.
 .PP
 The `%?' control escape is optional, and may 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.

-

 .SS "Function escapes"
 Functions expecting an argument generally
 require an argument of a particular type.
 .SS "Function escapes"
 Functions expecting an argument generally
 require an argument of a particular type.

@@ -153,7 +149,7 @@ these include:
 .RS 5
 .nf
 .ta +\w'Argument 'u +\w'An optional component, 'u
 .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\^})
 literal        A literal number        %(\fIfunc\fR 1234)
        or string               %(\fIfunc\fR text string)
 comp   Any component           %(\fIfunc\fR\^{\fIin-reply-to\fR\^})

@@ -251,7 +247,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   Result       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)

@@ -300,7 +296,8 @@ putnum      expr            print \fInum\fR
 putnumf        expr            print \fInum\fR in a fixed width
 .\" addtoseq literal    add msg to sequence (LBL option)
 putlit expr            print \fIstr\fR without space compression
 putnumf        expr            print \fInum\fR in a fixed width
 .\" addtoseq literal    add msg to sequence (LBL option)
 putlit expr            print \fIstr\fR without space compression

-nodate string  integer Argument not a date string (0 or 1)
+zputlit        expr            print \fIstr\fR without space compression;
+                       \fIstr\fR must occupy no width on display

 formataddr     expr            append \fIarg\fR to \fIstr\fR as a
                        (comma separated) address list
 concataddr     expr            append \fIarg\fR to \fIstr\fR as a
 formataddr     expr            append \fIarg\fR to \fIstr\fR as a
                        (comma separated) address list
 concataddr     expr            append \fIarg\fR to \fIstr\fR as a

@@ -323,7 +320,8 @@ or the local hostname if
 is not configured.  The (\fImyname\fR\^) function will return the value of
 the
 .B SIGNATURE
 is not configured.  The (\fImyname\fR\^) function will return the value of
 the
 .B SIGNATURE

-environment variable if set, otherwise will return the passwd GECOS field for
+environment variable if set, otherwise will return the passwd GECOS field
+(truncated at the first comma if it contains one) for

 the current user.  The (\fIlocalmbox\fR\^) function will return the complete
 form of the local mailbox, suitable for use in a \*(lqFrom\*(rq header.
 It will return the
 the current user.  The (\fIlocalmbox\fR\^) function will return the complete
 form of the local mailbox, suitable for use in a \*(lqFrom\*(rq header.
 It will return the

@@ -341,7 +339,7 @@ The following functions require a date component as an argument:
 .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        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)
 sec    date    integer seconds of the minute
 min    date    integer minutes of the hour
 hour   date    integer hours of the day (0-23)

@@ -377,7 +375,7 @@ the first address present in the header component.
 .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        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*
 proper addr    string  official 822 rendering
 friendly       addr    string  user-friendly rendering
 addr   addr    string  mbox@host or host!mbox rendering*

@@ -427,8 +425,11 @@ 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 (\fIputlit\fR\^)
 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 (\fIputlit\fR\^)

-function outputs the exact contents of str register without any changes
+function outputs the exact contents of the str register without any changes

 such as duplicate space removal or control character conversion.
 such as duplicate space removal or control character conversion.

+The (\fIzputlit\fR\^) similarly outputs the exact contents of the str
+register, but requires that those contents not occupy any output width.
+It can therefore be used for outputting terminal escape sequences.

 .PP
 The available output width is kept in an internal register; any output
 past this width will be truncated.
 .PP
 The available output width is kept in an internal register; any output
 past this width will be truncated.

@@ -464,7 +465,7 @@ generated will be something like:
 .PP
 .RS 5
 .nf
 .PP
 .RS 5
 .nf

-My From User <from@user.com>To: My From User <from@user.com>
+My From User <from@example.com>To: My From User <from@example.com>

 .fi
 .RE
 .PP
 .fi
 .RE
 .PP

@@ -655,7 +656,7 @@ If a
 switch was given to
 .B repl
 (see
 switch was given to
 .B repl
 (see

-.BR repl (1)
+.IR repl (1)

 for more details about %{\fIfcc\fR\^}),
 an \*(lqFcc:\*(rq header is output.
 .PP
 for more details about %{\fIfcc\fR\^}),
 an \*(lqFcc:\*(rq header is output.
 .PP

@@ -742,10 +743,12 @@ conditional
 is used to test whether the message number
 has 5
 or more digits.
 is used to test whether the message number
 has 5
 or more digits.

-If so, it is printed at full width: otherwise
+If so, it is printed at full width, otherwise

 at 4 digits.
 .SH "SEE ALSO"
 at 4 digits.
 .SH "SEE ALSO"

-scan(1), repl(1), ap(8), dp(8)
-
+.IR scan (1),
+.IR repl (1),
+.IR ap (8),
+.IR dp (8)

 .SH CONTEXT
 None
 .SH CONTEXT
 None