[racket] scribble/lp: comments stripped, how to stop?

From: Robby Findler (robby at eecs.northwestern.edu)
Date: Mon Apr 23 21:36:05 EDT 2012

Here's a way to write your second example:

      (let loop ((cs c-primes)
                 (ds d-primes)
                 (xs empty)
                 (last-d <last-d-init>))
        (if (empty? cs) ...

We initialize @racket[last-d] to one

@chunk[<last-d-init> 1]

because ...

and I bet you could use similar techniques to clear up what is going
on in the first one.

I agree it isn't as convenient as just throwing a quick comment in
there, but part of the problem is the way we've chosen to make
literate programming work in Scribble+Racket. Specifically, all the
splicing is actually happening at the sexp level (technically syntax
objects), and the comments are thrown away before we get to that
level. (Of course, we could do things in a different way to actually
propagate the comments by rewriting them somehow before turning things
into s-expressions, but that seems a bit complex to wire in, at least
to me.)

Sorry I don't have a more directly helpful answer for you.


On Mon, Apr 23, 2012 at 8:22 PM, Deren Dohoda <deren.dohoda at gmail.com> wrote:
> Hi Robby,
> Yes, you are right, it isn't a critical problem. Truth be told, Racket
> itself is nice enough to make it less of a problem, and certainly
> #lang scribble/lp being run directly rather than extracted to a
> separate file makes a lot of comments superfluous. An enormous number
> of them. Using noweb+C required a lot of commenting to debug the code.
> But I have this habit of writing the documentation to give an overview
> for non-programmers, or someone unfamiliar with the language, rather
> than explaining every choice in detail in the exposition. For
> instance, I have this part:
> @chunk[<tdma>
>       (define (tridiagonal-solver as bs cs ds)
>         (define (c-prime/d-prime) ;assume arguments
>           ;arguments come out backwards, but it is back-substitution
>           <forward-pass>)
>         (define (back-substitution c-primes d-primes) ;c'i... c'0 and
> d'i... d'0
>           <back-substitution>)
>         (call-with-values c-prime/d-prime back-substitution))]
> It seems too detail oriented to explain in the main exposition that we
> evaluate some procedure to some critical lists which are apparently
> backwards, but thankfully we happen to need them backwards, so all the
> better (that it is mathematically called "back substitution" only
> confuses this example, it doesn't imply anything actually need happen
> "backwards"---though it does... argh). But passing an argument
> "backwards" is not something I'd like to leave uncommented. Later I
> have a loop:
> @chunk[<back-substitution>
>       (let loop ((cs c-primes)
>                  (ds d-primes)
>                  (xs empty)
>                  (last-d 1)) ; first is × 0 so don't matter
>         (if (empty? cs) ...
> Why the magic number 1? Well, it doesn't matter, but magic values like
> 1 or #f or something seem funny if uncommented. So just a quick
> comment that this isn't a magic number, the first operation is to
> multiply it by zero so it could be any number whatsoever.
> Sorry if these aren't great examples. It may simply be that it's time
> to rethink how I go about literate programming, now that I have a tool
> like this at my disposal.
> Deren
> On Mon, Apr 23, 2012 at 8:12 PM, Robby Findler
> <robby at eecs.northwestern.edu> wrote:
>> I think that the intention with literate programming is that you don't
>> really want to use comments in the chunks. Instead, you can actually
>> write what would be comments in the running text that gets produced
>> when you render the document with Scribble (and dropped when
>> evaluated).
>> If that's not making sense, maybe you could supply a little example to
>> help clarify?
>> Thanks,
>> Robby
>> On Sat, Apr 21, 2012 at 3:53 PM, Deren Dohoda <deren.dohoda at gmail.com> wrote:
>>> I have finally started learning scribble for use in literate
>>> programming to break away from noweb for Racket. It's quite excellent,
>>> I am glad to be making the switch. Thank everyone for their work. I
>>> miss the math of latex but it isn't a dealbreaker.
>>> However, part of writing code is commenting the code for reminders of
>>> why little bits are the way they are. The problem is that the scribble
>>> HTML output has stripped all comments from the chunks. I have tried
>>> digging down into scribble/lp but I must admit the guts are outside my
>>> ability to understand. I'm guessing it is because the reader has
>>> already stripped comments from the syntax by the time Racket gets to
>>> the "chunk" syntax rule. The one bit that seems to indicate it strips
>>> comments (code:comment) never seems to be used anywhere. I know that
>>> there are code examples with comments in the Racket documentation. Is
>>> there any way to keep code comments preserved in the scribbled view of
>>> chunks?
>>> Thanks,
>>> Deren
>>> ____________________
>>>  Racket Users list:
>>>  http://lists.racket-lang.org/users

Posted on the users mailing list.