garbled documentation

garbled documentation

[Rouben Rostamian]

I hope that this bug report is addressed to the right place.  Please
let me know if it is otherwise.

Version: guile--1.6.4
  Guile reference manual: both "info" and TeX formats:
    In the section titled "Bit Vectors":

In the description of bit-set*! we read:

 - Scheme Procedure: bit-set*! v kv obj
 - C Function: scm_bit_set_star_x (v, kv, obj)
     If uve is a bit-vector BV and uve must be of the same length.  If
     BOOL is `#t', uve is OR'ed into BV; If BOOL is `#f', the inversion
     of uve is AND'ed into BV.

     If uve is a unsigned long integer vector all the elements of uve
     must be between 0 and the `length' of BV.  The bits of BV
     corresponding to the indexes in uve are set to BOOL.  The return
     value is unspecified.

This description is garbled.  The procedure arguments are listed
as "v kv obj" while the description refers to "uve, BV, BOOL", etc.

In fact, most descriptions under the section "Bit Vectors" suffer from
the same problem.

-- 
Rouben Rostamian


_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile

Re: garbled documentation

[Kevin Ryde]

"Rouben Rostamian" <rostamian@umbc.edu> writes:
>
>  - Scheme Procedure: bit-set*! v kv obj
>  - C Function: scm_bit_set_star_x (v, kv, obj)
>
> This description is garbled.  The procedure arguments are listed
> as "v kv obj" while the description refers to "uve, BV, BOOL", etc.

Yep.  It's not really as clear as it could be either.

> In fact, most descriptions under the section "Bit Vectors" suffer from
> the same problem.

I made a bit of a revision:


Bit Vectors
-----------

Bit vectors are a specific type of uniform array: an array of booleans
with a single zero-based index.

They are displayed as a sequence of `0's and `1's prefixed by `#*',
e.g.,

     (make-uniform-vector 8 #t #f) =>
     #*00000000

 - Scheme Procedure: bit-count bool bitvector
 - C Function: scm_bit_count (bool, bitvector)
     Return a count of entries in BITVECTOR equal to BOOL.  For example,

          (bit-count #f #*000111000)  => 6

 - Scheme Procedure: bit-position bool bitvector start
 - C Function: scm_bit_position (bool, bitvector, start)
     Return the index of the first occurrance of BOOL in BITVECTOR,
     starting from START.  If there is no BOOL entry between START and
     the end of BITVECTOR, then return `#f'.  For example,

          (bit-position #t #*000101 0)  => 3
          (bit-position #f #*0001111 3) => #f

 - Scheme Procedure: bit-invert! bitvector
 - C Function: scm_bit_invert_x (bitvector)
     Modify BITVECTOR by replacing each element with its negation.

 - Scheme Procedure: bit-set*! bitvector uvec bool
 - C Function: scm_bit_set_star_x (bitvector, uvec, bool)
     Set entries of BITVECTOR to BOOL, with UVEC selecting the entries
     to change.

     If UVEC is a bit vector, then those entries where it has `#t' are
     the ones in BITVECTOR which are set to BOOL.  When BOOL is `#t'
     it's like UVEC is OR'ed into BITVECTOR.  Or when BOOL is `#f' it
     can be seen as an ANDNOT.

          (define bv #*01000010)
          (bit-set*! bv #*10010001 #t)
          bv
          => #*11010011

     If UVEC is a uniform vector of unsigned long integers, then
     they're indexes into BITVECTOR which are set to BOOL.

          (define bv #*01000010)
          (bit-set*! bv #u(5 2 7) #t)
          bv
          => #*01100111

 - Scheme Procedure: bit-count* bitvector uvec bool
 - C Function: scm_bit_count_star (bitvector, uvec, bool)
     Return a count of entries in BITVECTOR which are equal to BOOL,
     with UVEC selecting the entries to consider.

     UVEC is interpreted in the same way as `bit-set*!' above.  Namely,
     if UVEC is a bit vector then entries which have `#t' there are
     considered in BITVECTOR.  Or if UVEC is a uniform vector of
     unsigned long integers then it's the indexes in BITVECTOR to
     consider.

     For example,

          (bit-count* #*01110111 #*11001101 #t) => 3
          (bit-count* #*01110111 #u(7 0 4) #f)  => 2



_______________________________________________
Bug-guile mailing list
Bug-guile@gnu.org
http://mail.gnu.org/mailman/listinfo/bug-guile