X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/ae773e71c0efe0a8a7bb2f243e784c576e72c9e4..43a65e9777214029046fe7a1427493e6e503a717:/man/mh-format.man?ds=inline diff --git a/man/mh-format.man b/man/mh-format.man index d8a83b27..83de220b 100644 --- a/man/mh-format.man +++ b/man/mh-format.man @@ -1,7 +1,7 @@ +.TH MH-FORMAT %manext5% "November 4, 2012" "%nmhversion%" .\" .\" %nmhwarning% .\" -.TH MH-FORMAT %manext5% "%nmhdate%" MH.6.8 [%nmhversion%] .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. - .\" 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 `%'; - .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. - .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. @@ -153,7 +149,7 @@ these include: .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\^}) @@ -251,13 +247,13 @@ 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 Result Description" msg integer message number cur integer message is current (0 or 1) unseen integer message is unseen (0 or 1) size integer size of message strlen integer length of \fIstr\fR -width integer output buffer size in bytes +width integer column width of terminal charleft integer bytes left in output buffer timenow integer seconds since the UNIX epoch me string the user's mailbox (username) @@ -289,18 +285,19 @@ 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 .\" 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) +.\" decodecomp comp string Set \fIstr\fR to RFC 2047 decoded component text +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 white-space from \fIstr\fR +unquote expr string remove RFC 2822 quotes from \fIstr\fR +trim expr trim trailing whitespace 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) 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 @@ -323,7 +320,8 @@ or the local hostname if 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 @@ -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 -.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) @@ -365,7 +363,7 @@ date2gmt date coerce date to GMT 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 @@ -377,8 +375,8 @@ the first address present in the header component. .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* @@ -427,8 +425,12 @@ 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\^) -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. +The (\fIzputlit\fR\^) function 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. @@ -464,7 +466,7 @@ generated will be something like: .PP .RS 5 .nf -My From User To: My From User +My From User To: My From User .fi .RE .PP @@ -655,7 +657,7 @@ If a 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 @@ -742,10 +744,12 @@ conditional 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" -scan(1), repl(1), ap(8), dp(8) - +.IR scan (1), +.IR repl (1), +.IR ap (8), +.IR dp (8) .SH CONTEXT None