X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/8258d6230e6708ec7256a090936451252d30f5e9..c1e7215519ea50d95fc30d0a8064db6633a7d559:/man/mh-format.man diff --git a/man/mh-format.man b/man/mh-format.man index 6c8938a5..72a03862 100644 --- a/man/mh-format.man +++ b/man/mh-format.man @@ -1,4 +1,4 @@ -.TH MH-FORMAT %manext5% "November 4, 2012" "%nmhversion%" +.TH MH-FORMAT %manext5% "January 10, 2015" "%nmhversion%" .\" .\" %nmhwarning% .\" @@ -45,7 +45,8 @@ A format string consists of ordinary text, and special multi-character 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. +`\\' followed by the newline character. A literal `%' can be inserted into +a format file by using the sequence `%%'. .\" TALK ABOUT SYNTAX FIRST, THEN SEMANTICS .SS SYNTAX Format strings are built around @@ -136,7 +137,7 @@ 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 +The `%?' control escape is optional, and 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. @@ -267,6 +268,7 @@ match literal boolean \fIstr\fR contains \fIarg\fR amatch literal boolean \fIstr\fR starts with \fIarg\fR plus literal integer \fIarg\fR plus \fInum\fR minus literal integer \fIarg\fR minus \fInum\fR +multiply literal integer \fInum\fR multiplied by \fIarg\fR divide literal integer \fInum\fR divided by \fIarg\fR modulo literal integer \fInum\fR modulo \fIarg\fR num literal integer Set \fInum\fR to \fIarg\fR. @@ -290,6 +292,10 @@ 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 +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. putstr expr print \fIstr\fR putstrf expr print \fIstr\fR in a fixed width putnum expr print \fInum\fR @@ -298,6 +304,13 @@ putnumf expr print \fInum\fR in a fixed width putlit expr print \fIstr\fR without space compression zputlit expr print \fIstr\fR without space compression; \fIstr\fR must occupy no width on display +bold string set terminal bold mode +underline string set terminal underlined mode +standout string set terminal standout mode +resetterm string reset all terminal attributes +hascolor boolean terminal supports color +fgcolor literal string set terminal foreground color +bgcolor literal string set terminal background color formataddr expr append \fIarg\fR to \fIstr\fR as a (comma separated) address list concataddr expr append \fIarg\fR to \fIstr\fR as a @@ -354,7 +367,7 @@ mon date integer month of the year month date string month of the year (abbrev.) lmonth date string month of the year year date integer year (may be > 100) -zone date integer timezone in hours +zone date integer timezone in minutes tzone date string timezone string szone date integer timezone explicit? (1=explicit,0=implicit,\-1=unknown) @@ -383,7 +396,11 @@ addr addr string mbox@host or host!mbox rendering* pers addr string the personal name* note addr string commentary text* mbox addr string the local mailbox* -mymbox addr integer List has the user's address? (0 or 1) +mymbox addr integer list has the user's address? (0 or 1) +getmymbox addr string the user's (first) address, + with personal name +getmyaddr addr string the user's (first) address, + without personal name host addr string the host domain* nohost addr integer no host was present (0 or 1)* type addr integer host type* (0=local,1=network, @@ -433,8 +450,29 @@ the str register, but requires that those contents not occupy any output width. It can therefore be used for outputting terminal escape sequences. .PP +There are a limited number of function escapes to output terminal escape +sequences. These sequences are retrieved from the +.IR terminfo (5) +database according to the current terminal setting. The (\fIbold\fR\^), +(\fIunderline\fR\^), and (\fIstandout\fR\^) escapes set bold mode, +underline mode, and standout mode respectively. +.PP +(\fIhascolor\fR\^) +can be used to determine if the current terminal supports color. +(\fIfgcolor\fR\^) and (\fIbgcolor\fR\^) set the foreground and +background colors respectively. Both of these escapes take one literal +argument, the color name, which can be one of: black, red, green, yellow, +blue, magenta, cyan, white. (\fIresetterm\fR\^) resets all terminal +attributes back to their default setting. +.PP +All of these terminal escape should be used in conjunction with +(\fIzputlit\fR\^) (preferred) or (\fIputlit\fR\^), as the normal +(\fIputstr\fR\^) function will strip out control characters. +.PP The available output width is kept in an internal register; any output -past this width will be truncated. +past this width will be truncated. The one exception to this is +(\fIzputlit\fR\^) functions will still be executed in case a terminal reset +code is being placed at the end of the line. .SS Special Handling A few functions have different behavior depending on what command they are being invoked from. @@ -462,7 +500,7 @@ the From: and Reply-To: headers: .fi .RE .PP -Unfortuantely if the Reply-to: header is NOT present, the output line that is +Unfortunately if the Reply-to: header is NOT present, the output line that is generated will be something like: .PP .RS 5 @@ -545,7 +583,7 @@ a space should be printed. Next: .RE .PP the month and date are printed in two digits (zero filled) separated by -a slash. Next, +a slash. Next, .PP .RS 5 .nf @@ -719,7 +757,7 @@ to have far more than 10000 messages. .\" process 200 messages a day and still get some real work .\" done." The authors apparently only planned to get .\" real work done for about 50 days per folder.) -Nontheless (as noted above) +Nonetheless (as noted above) the various scan format strings are inherited from older MH versions, and are generally hard-coded to 4 digits of message number before formatting problems