More doc fix backporting

1 files changed, 50 insertions, 5 deletions

diff --git a/doc/format.n b/doc/format.n
index b69a8f6..471774c 100644
--- a/doc/format.n
+++ b/doc/format.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: format.n,v 1.7 2002/02/19 10:26:24 dkf Exp $
+'\" RCS: @(#) $Id: format.n,v 1.7.2.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH format n 8.1 Tcl "Tcl Built-In Commands"
@@ -26,7 +26,6 @@ implementation).
 \fB%\fR conversion specifiers as in \fBsprintf\fR, and the additional
 arguments, if any, provide values to be substituted into the result.
 The return value from \fBformat\fR is the formatted string.
-
 .SH "DETAILS ON FORMATTING"
 .PP
 The command operates by scanning \fIformatString\fR from left to right. 
@@ -133,7 +132,7 @@ truncated to a 16-bit value before converting.
 This option is rarely useful.
 .VS 8.4
 If it is \fBl\fR it specifies that the numeric value should be (at
-least) a 64-bit value.  If neither \fBh\fR or \fBl\fR are present,
+least) a 64-bit value.  If neither \fBh\fR nor \fBl\fR are present,
 numeric values are interpreted as being values of the width of the
 native machine word, as described by \fBtcl_platform(wordSize)\fR.
 .VE
@@ -196,7 +195,6 @@ For the numerical conversions the argument being converted must
 be an integer or floating-point string; format converts the argument
 to binary and then converts it back to a string according to 
 the conversion specifier.
-
 .SH "DIFFERENCES FROM ANSI SPRINTF"
 .PP
 The behavior of the format command is the same as the
@@ -218,9 +216,56 @@ of real and integer values, respectively).
 If the \fBh\fR modifier is specified then integer values are truncated
 to \fBshort\fR before conversion.  Both \fBh\fR and \fBl\fR modifiers
 are ignored on all other conversions.
+.SH EXAMPLES
+Convert the output of \fBtime\fR into seconds to an accuracy of
+hundredths of a second:
+.CS
+set us [lindex [time $someTclCode] 0]
+puts [\fBformat\fR "%.2f seconds to execute" [expr {$us / 1e6}]]
+.CE
+.PP
+Create a packed X11 literal color specification:
+.CS
+# Each color-component should be in range (0..255)
+set color [\fBformat\fR "#%02x%02x%02x" $r $g $b]
+.CE
+.PP
+Use XPG3 format codes to allow reordering of fields (a technique that
+is often used in localized message catalogs; see \fBmsgcat\fR) without
+reordering the data values passed to \fBformat\fR:
+.CS
+set fmt1 "Today, %d shares in %s were bought at $%.2f each"
+puts [\fBformat\fR $fmt1 123 "Global BigCorp" 19.37]
+
+set fmt2 "Bought %2\\$s equity ($%3$.2f x %1\\$d) today"
+puts [\fBformat\fR $fmt2 123 "Global BigCorp" 19.37]
+.CE
+.PP
+Print a small table of powers of three:
+.CS
+# Set up the column widths
+set w1 5
+set w2 10
+
+# Make a nice header (with separator) for the table first
+set sep +-[string repeat - $w1]-+-[string repeat - $w2]-+
+puts $sep
+puts [\fBformat\fR "| %-*s | %-*s |" $w1 "Index" $w2 "Power"]
+puts $sep
+
+# Print the contents of the table
+set p 1
+for {set i 0} {$i<=20} {incr i} {
+   puts [\fBformat\fR "| %*d | %*ld |" $w1 $i $w2 $p]
+   set p [expr {wide($p) * 3}]
+}
+
+# Finish off by printing the separator again
+puts $sep
+.CE
 
 .SH "SEE ALSO"
-sprintf(3), string(n)
+scan(n), sprintf(3), string(n)
 
 .SH KEYWORDS
 conversion specifier, format, sprintf, string, substitution