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

I am not opposed to working with my tools rather than against them.
Sometimes it just takes a head-slap. Thanks for your help.

Deren

On Mon, Apr 23, 2012 at 9:36 PM, Robby Findler
<robby at eecs.northwestern.edu> wrote:
> Here's a way to write your second example:
>
> -------------
> @chunk[<back-substitution>
>      (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.
>
> Robby
>
> 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