From f336ac585ecc2f6c1ca5a67611bedbaa11a9c5df Mon Sep 17 00:00:00 2001 From: dkf Date: Wed, 2 Jan 2008 21:21:36 +0000 Subject: Fixed documentation bug reported on tcl-core, and reordered documentation to discourage people from using the hex formatter that is hardly ever useful. --- ChangeLog | 6 ++++++ doc/binary.n | 27 ++++++++++++--------------- 2 files changed, 18 insertions(+), 15 deletions(-) diff --git a/ChangeLog b/ChangeLog index 96874c2..877d56e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2008-01-02 Donal K. Fellows + + * doc/binary.n: Fixed documentation bug reported on tcl-core, and + reordered documentation to discourage people from using the hex + formatter that is hardly ever useful. + 2008-01-02 Don Porter * generic/tcl.h: Bump version number to 8.5.1b1 to distinguish diff --git a/doc/binary.n b/doc/binary.n index 4488a73..16f7533 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.37 2007/12/13 15:22:32 dgp Exp $ +'\" RCS: @(#) $Id: binary.n,v 1.38 2008/01/02 21:21:37 dkf Exp $ '\" .so man.macros .TH binary n 8.0 Tcl "Tcl Built-In Commands" @@ -17,7 +17,6 @@ binary \- Insert and extract fields from binary strings .br \fBbinary scan \fIstring formatString \fR?\fIvarName varName ...\fR? .BE - .SH DESCRIPTION .PP This command provides facilities for manipulating binary data. The @@ -139,13 +138,13 @@ high-to-low order within each byte. For example, .CE will return a string equivalent to \fB\exe0\exe1\exa0\fR. .RE -.IP \fBh\fR 5 -Stores a string of \fIcount\fR hexadecimal digits in low-to-high +.IP \fBH\fR 5 +Stores a string of \fIcount\fR hexadecimal digits in high-to-low within each byte in the output string. \fIArg\fR must contain a sequence of characters in the set .QW 0123456789abcdefABCDEF . The resulting bytes are emitted in first to last order with the hex digits -being formatted in low-to-high order within each byte. If \fIarg\fR +being formatted in high-to-low order within each byte. If \fIarg\fR has fewer than \fIcount\fR digits, then zeros will be used for the remaining digits. If \fIarg\fR has more than the specified number of digits, the extra digits will be ignored. If \fIcount\fR is @@ -155,18 +154,18 @@ number of digits formatted does not end at a byte boundary, the remaining bits of the last byte will be zeros. For example, .RS .CS -\fBbinary format\fR h3h* AB def +\fBbinary format\fR H3H*H2 ab DEF 987 .CE -will return a string equivalent to \fB\exba\ex00\exed\ex0f\fR. +will return a string equivalent to \fB\exab\ex00\exde\exf0\ex98\fR. .RE -.IP \fBH\fR 5 -This form is the same as \fBh\fR except that the digits are stored in -high-to-low order within each byte. For example, +.IP \fBh\fR 5 +This form is the same as \fBH\fR except that the digits are stored in +low-to-high order within each byte. This is seldom required. For example, .RS .CS -\fBbinary format\fR H3H* ab DEF +\fBbinary format\fR h3h*h2 AB def 987 .CE -will return a string equivalent to \fB\exab\ex00\exde\exf0\fR. +will return a string equivalent to \fB\exba\ex00\exed\ex0f\ex89\fR. .RE .IP \fBc\fR 5 Stores one or more 8-bit integer values in the output string. If no @@ -534,7 +533,7 @@ scanned. For example, .CS \fBbinary scan\fR \ex07\exC6\ex05\ex1f\ex34 H3H* var1 var2 .CE -will return \fB2\fR with \fB0c8\fR stored in \fIvar1\fR and +will return \fB2\fR with \fB07c\fR stored in \fIvar1\fR and \fB051f34\fR stored in \fIvar2\fR. .RE .IP \fBh\fR 5 @@ -809,9 +808,7 @@ proc \fIreadString\fR {channel} { return [encoding convertfrom utf-8 $data] } .CE - .SH "SEE ALSO" format(n), scan(n), tclvars(n) - .SH KEYWORDS binary, format, scan -- cgit v0.12