bug#71684: [PATCH v2] doc: Document the peek and pk procedures.

[Maxim Cournoyer <maxim.cournoyer@gmail.com>]

Hi Simon,

Simon Tournier <zimon.toutoune@gmail.com> writes:

[...]

>> +@lisp
>> +(map (lambda (v)
>> +       (if (number? v)
>> +           (number->string v)
>> +           (pk v)))
>> +     '(1 "2" "3" 4))
>> +@result{}
>> +
>> +;;; ("2")
>> +
>> +;;; ("3")
>> +("1" "2" "3" "4")
>> +@end
>
> For what it is worth, I would suggest something as:
>
> (map (lambda (v)
>        (if (number? v)
>            (number->string v)
>            (begin
>              (pk 'else v)
>              (pk (string-append "-" v "0")))))
>      '(1 "2" "3" 4))
>
> For two reasons:
>
>  1. ’begin’ helps to mark a sequence of expressions; IMHO, that’s a good
>      habit when playing with ’pk’ for debugging purpose.
>
>  2. it exposes that ’stuff’ above can be anything.
>
>
> Well, my suggestion could be two other examples in addition to the
> current one instead of the complexification.

I think I'd prefer more simple examples than a single more complicated
one, if we go that route.  I think the text explained 'peek' clearly
already, though, so I personally would opt to leave it as is, especially
since adding a 'begin' block to showcase multiple 'pk' calls goes
against the merit of peek of being least intrusive (it prints then
returns the value, so the code structure needs not be changed).

-- 
Thanks,
Maxim