X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/8258d6230e6708ec7256a090936451252d30f5e9..a7ec5d546fe5dbf8bc375bdb8d69f5f84789fc7e:/man/mh-format.man

diff --git a/man/mh-format.man b/man/mh-format.man
index 6c8938a5..1e2f41a5 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% "October 27, 2014" "%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
@@ -290,6 +291,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 +303,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 +366,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 +395,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 +449,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.