[plt-scheme] Literate scribbling question

Thanks for the quick reply, Eli!

On Thu, May 21, 2009 at 5:41 AM, Eli Barzilay<eli at barzilay.org> wrote:
> On May 21, Anthony Cowley wrote:
>> I was experimenting with the scribble/lp language, and found the
>> need for the @chunks rather frustrating as they take up horizontal
>> space and introduce a required chunk label.
>
> IIRC, it should work with something like @chunk[foo
>
>  (blah blah)
>
> ] just fine, does that help?

That's the way I started out doing it when typing it in, but it's not
DrScheme's default indentation pattern (so cmd-i or just hitting tab
gives something worse).

>> be.  I'd like the labels to just come from define forms (perhaps
>> with the option of me labeling other chunks for inclusion in the
>> table of contents),
>
> How would you label other chunks?  How would you deal with text that
> happens to have "(define ...)"?  And what about `define-values',
> `define-syntax', etc -- and some random macro that expands to a
> `define'?

If I had to give up sub-chunks then I would do so; I'm really looking
for something as minimally invasive as possible. I'm just suggesting
that it may be possible to retain a similar chunk functionality
without requiring that all scheme code be in labeled chunks. My
complaint is that writing,

@chunk[<foo>
(define (foo x) x)
]

adds quite a bit of syntax to the program, potentially messes up
indentation, perhaps leaves a dangling square bracket closing the
whole form, and duplicates the function name. 99.9% of the time I just
want the function name as the chunk label, so it would seem like a
good default *if* one can pull it out, which lead to my comment about
define forms.

If pulling out function names from program syntax is too hard, I'd
give up the hyperlinked table of contents just to have the kind of
nicely formatted document scribble produces with text and code
interleaved. It seemed like possibly low hanging fruit to
automatically pull out a label from whatever define forms seem
appropriate, but I really don't know how hard that would be.

>> and I'd also prefer to not have to annotate a valid syntactic form
>> at all. This latter is perhaps unworkable, hence this email: Could
>> we switch the reader into Scheme mode when encountering an
>> un-escaped left-parenthesis, and remain in text mode at all other
>> times?
>
> But there could be valid chunks of code that have no parens around
> them, and besides, the whole point of the scribble syntax is to make
> escapes minimally necessary -- either scheme mode or text mode with
> an unambiguous way to switch between the two.

My whole desire is to minimize escapes and additional syntax. After
writing up my documentation with scribble/lp it didn't look very much
like plain text or normal Scheme code to me. I then tried looking at
it if I only had to use an @ in front of Scheme code, and it looked
much better. Then I realized that I only used parentheses in my plain
text once, so why not force the use of an escape character there,
rather than on the dozen Scheme forms in the file? I would have
guessed that a large majority of Scheme code does have parens around
it, so why not levy the escape tax on the code that doesn't? For
example, in text mode, @scheme[2] would be a scheme 2, (define (foo x)
x) would be a scheme function, but something like \(this is a
parenthetical aside) would just be a plain text parenthetical remark.
If such a reader could be used, then I think most literate Scheme
programming wouldn't have any annotations at all.

However, I believe you if you say that it's just impossible due to
non-simplistic forms (e.g. define-syntax), but scribble/lp is so close
to being a lightweight literate style already that it struck me as a
real possibility.

Anthony