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

[Simon Tournier]

Hi,

On Tue, 02 Jul 2024 at 12:28, Juliana Sims <juli@incana.org> wrote:
> * doc/ref/api-debug.texi: Document the peek and pk procedures.

Cool!  Thanks.


> Thanks for the quick review! I thought I'd made sure to double-space after
> periods, but I guess my Emacs fill settings overwrote that when I made sure
> everything flowed properly. The contemporary consensus on double spaces in
> English is to not use them, and I write a lot so I have my text-mode settings
> geared to that purpose. I used manual filling this time so hopefully that 
> issue
> has been resolved.

Yeah, that’s because double-space after period fixes ambiguous cases as
this example: “The author J. R. R. Tolkien wrote The Hobbit. George
R. R. Martin wrote many fantasy books.”  The brain is able to determine
it’s only two sentences, but it becomes more difficult otherwise; it
could count 7 sentences.

https://en.wikipedia.org/wiki/Sentence_spacing#Computer_era

Anyway. :-)


> +@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:

--8<---------------cut here---------------start------------->8---
(map (lambda (v)
       (if (number? v)
           (number->string v)
           (begin
             (pk 'else v)
             (pk (string-append "-" v "0")))))
     '(1 "2" "3" 4))
--8<---------------cut here---------------end--------------->8---

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.

My 2 cents. :-)

Cheers,
simon