Improve the documentation of [binary scan] a little.

2 files changed, 26 insertions, 18 deletions

diff --git a/ChangeLog b/ChangeLog
index cb999e0..b76ae62 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2005-10-21  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/binary.n: Clarify that virtually all code that uses the 'h'
+	format in [binary scan] should be using the 'H' format instead. It
+	is nearly always a bug to use the other!
+
 2005-10-20  Miguel Sofer <msofer@users.sf.net>
 
 	* generic/tclListObj.c (TclLsetFlat):
diff --git a/doc/binary.n b/doc/binary.n
index f2b7155..3caf872 100644
--- a/doc/binary.n
+++ b/doc/binary.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: binary.n,v 1.26 2005/05/10 18:33:59 kennykb Exp $
+'\" RCS: @(#) $Id: binary.n,v 1.27 2005/10/21 10:27:03 dkf Exp $
 '\" 
 .so man.macros
 .TH binary n 8.0 Tcl "Tcl Built-In Commands"
@@ -488,32 +488,34 @@ high-to-low order within each byte.  For example,
 will return \fB2\fR with \fB01110\fR stored in \fIvar1\fR and
 \fB1000011100000101\fR stored in \fIvar2\fR.
 .RE
-.IP \fBh\fR 5
+.IP \fBH\fR 5
 The data is turned into a string of \fIcount\fR hexadecimal digits in
-low-to-high order represented as a sequence of characters in the set
-``0123456789abcdef''.  The data bytes are scanned in first to last
-order with the hex digits being taken in low-to-high order within each
-byte.  Any extra bits in the last byte are ignored.  If \fIcount\fR
-is \fB*\fR, then all of the remaining hex digits in \fIstring\fR will be
-scanned.  If \fIcount\fR is omitted, then one hex digit will be
-scanned.  For example,
+high-to-low order represented as a sequence of characters in the set
+``0123456789abcdef''. The data bytes are scanned in first to last
+order with the hex digits being taken in high-to-low order within each
+byte. Any extra bits in the last byte are ignored. If \fIcount\fR is
+\fB*\fR, then all of the remaining hex digits in \fIstring\fR will be
+scanned. If \fIcount\fR is omitted, then one hex digit will be
+scanned. For example,
 .RS
 .CS
-\fBbinary scan\fR \\x07\\x86\\x05 h3h* var1 var2
+\fBbinary scan\fR \\x07\\x86\\x05\\x12\\x34 H3H* var1 var2
 .CE
-will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and
-\fB50\fR stored in \fIvar2\fR.
+will return \fB2\fR with \fB078\fR stored in \fIvar1\fR and
+\fB051234\fR stored in \fIvar2\fR.
 .RE
-.IP \fBH\fR 5
-This form is the same as \fBh\fR, except the digits are taken in
-high-to-low order within each byte.  For example,
+.IP \fBh\fR 5
+This form is the same as \fBH\fR, except the digits are taken in
+reverse (low-to-high) order within each byte. For example,
 .RS
 .CS
-\fBbinary scan\fR \\x07\\x86\\x05 H3H* var1 var2
+\fBbinary scan\fR \\x07\\x86\\x05\\x12\\x34 h3h* var1 var2
 .CE
-will return \fB2\fR with \fB078\fR stored in \fIvar1\fR and
-\fB05\fR stored in \fIvar2\fR.
+will return \fB2\fR with \fB706\fR stored in \fIvar1\fR and
+\fB502143\fR stored in \fIvar2\fR.
 .RE
+Note that most code that wishes to parse the hexadecimal digits from
+multiple bytes in order should use the \fBH\fR format.
 .IP \fBc\fR 5
 The data is turned into \fIcount\fR 8-bit signed integers and stored
 in the corresponding variable as a list. If \fIcount\fR is \fB*\fR,