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

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