So I'm trying to figure out the simplest way to create a document that is mostly text with a few Racket snippets. When I hit Run, I want the code to be evaluated for the interactions window. When I hit the scribble button, I want it to generate html that displays the formatted text along with the Racket snippets.
First attempt: Use scribble/base and put an @ in front of any Racket code. Hitting run evaluates the Racket code, but scribblizing only shows the formatted text -- the code remains invisible.
Second attempt: Use scribble/manual and put @racketblock[] around any Racket code. Looks great when you scribblize, but code doesn't evaluate. Another nuisance: IDE auto-converts opening bracket after @racketblock into a paren.
I understand from the documentation that there are techniques that involve setting up whole project structures and using the raco tool. But I'm looking for something lightweight. Is there a way?
> So I'm trying to figure out the simplest way to create a document that > is mostly text with a few Racket snippets. When I hit Run, I want the > code to be evaluated for the interactions window. When I hit the > scribble button, I want it to generate html that displays the formatted > text along with the Racket snippets.
> First attempt: > Use scribble/base and put an @ in front of any Racket code. > Hitting run evaluates the Racket code, but scribblizing only shows the > formatted text -- the code remains invisible.
> Second attempt: > Use scribble/manual and put @racketblock[] around any Racket code. > Looks great when you scribblize, but code doesn't evaluate. > Another nuisance: IDE auto-converts opening bracket after @racketblock > into a paren.
Is this what you're looking for? -- David
#lang scribble/manual @(require scribble/eval)
@title{My Scribblings}
I don't always program, but when I do, I program in
> Second attempt: > Use scribble/manual and put @racketblock[] around any Racket code. > Looks great when you scribblize, but code doesn't evaluate. > Another nuisance: IDE auto-converts opening bracket after @racketblock into > a paren.
Oh! Try the keybinding: "Altl-[", which should add brackets and put the cursor in between. ____________________ Racket Users list: http://lists.racket-lang.org/users
>> So I'm trying to figure out the simplest way to create a document that >> is mostly text with a few Racket snippets. When I hit Run, I want the >> code to be evaluated for the interactions window. When I hit the >> scribble button, I want it to generate html that displays the formatted >> text along with the Racket snippets.
>> First attempt: >> Use scribble/base and put an @ in front of any Racket code. >> Hitting run evaluates the Racket code, but scribblizing only shows the >> formatted text -- the code remains invisible.
>> Second attempt: >> Use scribble/manual and put @racketblock[] around any Racket code. >> Looks great when you scribblize, but code doesn't evaluate. >> Another nuisance: IDE auto-converts opening bracket after @racketblock >> into a paren.
> @title{My Scribblings} > I'm going to write a really amazing factorial function now.
> @interaction[ > (define (factorial n) > (cond > [(zero? n) 1] ;; The zero test > [else (* n (factorial (sub1 n)))])) > ]
> But when I hit Run, it doesn't seem to recognize factorial in the > interactions window.
> On Fri, Mar 16, 2012 at 6:41 PM, David Van Horn <dvanh...@ccs.neu.edu> > wrote:
>> On 3/16/12 8:42 PM, Mark Engelberg wrote:
>>> So I'm trying to figure out the simplest way to create a document that >>> is mostly text with a few Racket snippets. When I hit Run, I want the >>> code to be evaluated for the interactions window. When I hit the >>> scribble button, I want it to generate html that displays the formatted >>> text along with the Racket snippets.
>>> First attempt: >>> Use scribble/base and put an @ in front of any Racket code. >>> Hitting run evaluates the Racket code, but scribblizing only shows the >>> formatted text -- the code remains invisible.
>>> Second attempt: >>> Use scribble/manual and put @racketblock[] around any Racket code. >>> Looks great when you scribblize, but code doesn't evaluate. >>> Another nuisance: IDE auto-converts opening bracket after @racketblock >>> into a paren.
I'm sort of thinking along the lines of Haskell's version of literate programming, where if you use the file suffix of lhs instead of hs, rather than having a file that is mostly code with occasional comments, you can easily write a document that is mostly text with occasional code. In that mode, by default, a line is treated as text unless it has a > at the beginning of the line to indicate it is code.
I was under the impression that with Scribble, I could do something similar (mostly text, but with occasional code blocks), but would have the additional benefits of Scribble's mark-up capabilities. I see now that that's not precisely how Scribble is intended to be used.
I'm interested because I've asked a student to turn a program into a highly readable document, and I want to give her some simple options. I thought this would be the perfect way to have a runnable program, but also be able to generate a great-looking html page.
scribble/lp is related, but more involved to use. Specifically, I just tried it and it doesn't seem to work with the scribble html button that appears in DrRacket. I keep getting the following error: scribble: loading xref scribble: rendering reference to an identifier before its definition: doc
Maybe it only works via lp-include?
On Fri, Mar 16, 2012 at 7:32 PM, Robby Findler <ro...@eecs.northwestern.edu>wrote:
> What you're asking for is not what Scribble does, mostly speaking. > Running a scribble program just builds a datastructure for the > rendering process.
> You might try the scribble/lp library, tho. I think that comes closest.
On Fri, Mar 16, 2012 at 7:45 PM, Mark Engelberg <mark.engelb...@gmail.com>wrote:
> scribble/lp is related, but more involved to use. Specifically, I just > tried it and it doesn't seem to work with the scribble html button that > appears in DrRacket. I keep getting the following error: > scribble: loading xref > scribble: rendering > reference to an identifier before its definition: doc
Scratch that. I had a typo caused by the bracket paren issue. It works. This is definitely an option.
If anyone has any other lighterweight ideas, let me know.
> On Fri, Mar 16, 2012 at 7:45 PM, Mark Engelberg <mark.engelb...@gmail.com>wrote:
>> scribble/lp is related, but more involved to use. Specifically, I just >> tried it and it doesn't seem to work with the scribble html button that >> appears in DrRacket. I keep getting the following error: >> scribble: loading xref >> scribble: rendering >> reference to an identifier before its definition: doc
> Scratch that. I had a typo caused by the bracket paren issue. It works. > This is definitely an option.
> If anyone has any other lighterweight ideas, let me know.
<mark.engelb...@gmail.com> wrote: > Ugh, scratch my scratching that. I'm still getting the error.
> On Fri, Mar 16, 2012 at 7:47 PM, Mark Engelberg <mark.engelb...@gmail.com> > wrote:
>> On Fri, Mar 16, 2012 at 7:45 PM, Mark Engelberg <mark.engelb...@gmail.com> >> wrote:
>>> scribble/lp is related, but more involved to use. Specifically, I just >>> tried it and it doesn't seem to work with the scribble html button that >>> appears in DrRacket. I keep getting the following error: >>> scribble: loading xref >>> scribble: rendering >>> reference to an identifier before its definition: doc
>> Scratch that. I had a typo caused by the bracket paren issue. It works. >> This is definitely an option.
>> If anyone has any other lighterweight ideas, let me know.
OK, I pasted in the code from the docs just to make sure it wasn't something in my code. Then I hit the "Scribble HTML" button that appears in the upper-right corner of DrRacket. I see the following in the interactions window:
Welcome to DrRacket, version 5.2 [3m]. Language: scribble/lp; memory limit: 2000 MB. scribble: loading xref scribble: rendering reference to an identifier before its definition: doc
On Fri, Mar 16, 2012 at 8:22 PM, Robby Findler <ro...@eecs.northwestern.edu>wrote:
I'm still curious to get scribble/lp working, but I've figured out an immediate solution to my question. I was able to get the behavior I want with just a simple macro: @(define-syntax-rule (code l) (begin @schemeblock[l] l))
Below is a sample of its use to get the behavior I want where you can hit run and have your code execute, or hit the scribble-html button to have it scribbled. If others like this idea as much as I, maybe this macro would be something worth including in scribble/manual?
One thing I still haven't figured out is how to get a comment (introduced with a semicolon) that is in the code block to show up in the scribbled output. (In the example below, the comment ";; the zero test" doesn't show up in the scribble output).
That is now how scribble/lp works. You need to make another file and use @lp-include on the first to get a document that actually scribbles. There is more explanation of this in the docs, right below that first example.
<mark.engelb...@gmail.com> wrote: > OK, I pasted in the code from the docs just to make sure it wasn't something > in my code. Then I hit the "Scribble HTML" button that appears in the > upper-right corner of DrRacket. I see the following in the interactions > window:
> Welcome to DrRacket, version 5.2 [3m]. > Language: scribble/lp; memory limit: 2000 MB.
> scribble: loading xref > scribble: rendering > reference to an identifier before its definition: doc
> On Fri, Mar 16, 2012 at 8:22 PM, Robby Findler <ro...@eecs.northwestern.edu> > wrote:
>> The example from the beginning of the docs works for me when I run it >> in DrRacket. Can you say more about what's going wrong when you try?
Mark Engelberg wrote: > One thing I still haven't figured out is how to get a comment (introduced > with a semicolon) that is in the code block to show up in the scribbled > output. (In the example below, the comment ";; the zero test" doesn't show > up in the scribble output).
Yesterday, Mark Engelberg wrote: > I'm sort of thinking along the lines of Haskell's version of > literate programming, where if you use the file suffix of lhs > instead of hs, rather than having a file that is mostly code with > occasional comments, you can easily write a document that is mostly > text with occasional code. In that mode, by default, a line is > treated as text unless it has a > at the beginning of the line to > indicate it is code.
Note that what Haskell does is *semi*-literate-programming, something that has little to do with literate programming. Neil Van Dyke is working on a tool that is going to be more like semi-literate-programming.
Also, in both cases the main difficulty is how to make both aspects of the code available: you want to usually run the code, but in other cases you want just the documentation. With the new submdules, this is now possible to do in a single module, so perhaps its time to add a semi-literate thing...
-- ((lambda (x) (x x)) (lambda (x) (x x))) Eli Barzilay: http://barzilay.org/ Maze is Life!
> Note that what Haskell does is *semi*-literate-programming, something > that has little to do with literate programming. Neil Van Dyke is > working on a tool that is going to be more like > semi-literate-programming.
My forthcoming tool, McFly, is for *documenting the usage/API* of reusable packages, similar in purpose to javadoc. It's decidedly not literate programming, which I think of as a practice for implementing programs.
(I will have to release McFly soon. It's called "McFly" because you say "doc" a lot. My previous documentation tool, Funcelit, was so-named as a pun, and short for "functionally-illiterate programming".)
> Eli Barzilay wrote at 03/17/2012 02:44 PM: > > Note that what Haskell does is *semi*-literate-programming, something > > that has little to do with literate programming. Neil Van Dyke is > > working on a tool that is going to be more like > > semi-literate-programming.
> My forthcoming tool, McFly, is for *documenting the usage/API* of > reusable packages, similar in purpose to javadoc.It's decidedly > not literate programming, which I think of as a practice for > implementing programs.
The way to do the markup (or other) with code which is what javadoc does *is* exactly semi-literate-programming. (And that's why it's very different from literate programming.)
On Sat, Mar 17, 2012 at 11:44 AM, Eli Barzilay <e...@barzilay.org> wrote: > Note that what Haskell does is *semi*-literate-programming, something > that has little to do with literate programming. Neil Van Dyke is > working on a tool that is going to be more like > semi-literate-programming.
I understand that literate programming in the Knuth-defined sense allows separation of function bodies into smaller chunks, and allows complete freedom over organization. In a language like Racket where function definitions can be in any order, you have pretty good flexibility to organize your code top-down or bottom-up, moving things where it makes sense to build an explanation. So the main thing you lose with a lighterweight tool is the ability to break up functions into smaller pieces. Racket functions are often so small, that's not a huge limitation. So yes, lp is more powerful, but just being able to invert the relative importance of documentation vs code and read the file both ways in a linear top-to-bottom fashion is valuable.
semi-literate-programming seems an apt name.
I don't think Javadoc would even qualify for that label though. In my mind, "semi-literate" at least implies a focus on building a narrative exposition of why the functions work the way they do, not just API documentation.
On Sat, Mar 17, 2012 at 5:36 AM, Robby Findler <ro...@eecs.northwestern.edu>wrote:
> That is now how scribble/lp works. You need to make another file and > use @lp-include on the first to get a document that actually > scribbles. There is more explanation of this in the docs, right below > that first example.
> Robby
OK, thanks. I saw that, but since the Scribble HTML button popped up in DrRacket, I expected it to work.
<mark.engelb...@gmail.com> wrote: > On Sat, Mar 17, 2012 at 5:36 AM, Robby Findler <ro...@eecs.northwestern.edu> > wrote:
>> That is now how scribble/lp works. You need to make another file and >> use @lp-include on the first to get a document that actually >> scribbles. There is more explanation of this in the docs, right below >> that first example.
>> Robby
> OK, thanks. I saw that, but since the Scribble HTML button popped up in > DrRacket, I expected it to work.
On Sat, Mar 17, 2012 at 02:02:22PM -0700, Mark Engelberg wrote:
> semi-literate-programming seems an apt name.
> I don't think Javadoc would even qualify for that label though. In my > mind, "semi-literate" at least implies a focus on building a narrative > exposition of why the functions work the way they do, not just API > documentation.
Anyone looking at semiliterate programming should lave a look at Modula 3's Trestle dicumentation. It reads like a well-written reference manual, but somehow manages to be generated from the Modula 3 interface files.
