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 <ro...@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.doh...@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 >> <ro...@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.doh...@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 ____________________ Racket Users list: http://lists.racket-lang.org/users
