[plt-scheme] Literate scribbling question

From: Anthony Cowley (acowley at seas.upenn.edu)
Date: Thu May 21 11:20:27 EDT 2009

>> >> 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).
>
> Well, if *that's* the problem, then hacking the syntax is the wrong
> answer...  Right now writing any scribble code with drscheme (not only
> lp code) is not really convenient, and hacking some scribble mode
> would be -- as Robby said -- very welcome.  (It might be difficult
> though because of the mixture of text and scheme modes -- even an
> Emacs mode would probably be difficult.)

I know indentation can be addressed on the DrScheme side, and I did
not mean to highlight indentation as a big issue. But no matter the
indentation style,

@chunk[(define (foo x)
(+ 'not-sure-where-this-line-goes x))
]

is going to look different from normal Scheme code. I think I'd prefer
to pay the two line penalty and have,
@chunk[
(define ...
]

so that the code itself looks normal and can easily be cut and pasted,
but it's not ideal.

The reason this came up is that I recently did some literate Agda in a
TeX document, which amounts to the multiple-line version above, and
some literate Haskell using the standard convention there. The Agda
version looks somewhat questionable, but if you can mentally block out
what's above and below the code, it looks correct. Literate Haskell,
however, is a more interesting comparison point. First, I think the
regularity of the > character on every line of code is fairly
intuitive to visually filter out since it doesn't have any effect on
the shape of the code (that column of characters just becomes the left
edge of the text area), whereas any solution that involves prefixing a
scheme form does change the shape (for instance, the idea of using an
@ before code moves things around by one character). Second, it
occurred to me that literate Haskell picked up a good chunk of regular
syntactic noise, and then the analogy to Lisp parentheses occurred to
me. We already have this regular syntactic information on our code, so
could we piggy back on our beloved parens to indicate regions of code
as distinct from regions of text?

>> (talk of chunk labels)
>
> If the label is what bothers you (I'm ignoring the indentation issue
> as I said above), then it would probably be possible to make `chunk'
> more convenient.  For example, it could guess a chunk name based on
> the previous chunk, or it could be made "smart" in the sense that if a
> label identifier is omitted *and* the first form is (or expands to) a
> (define foo ...) form, then it will use `<foo>' as the label.  But IMO
> each of these can come with a penalty in the form of more confusing
> bugs, for example -- with the first strategy you could get confused
> results when you move some text + code to a different place and
> getting a different implicit label, and with the second strategy I can
> see this:

I'm not looking for any guesswork. If a label can't be easily obtained
(i.e. we have a define form), then there is no label. In my opinion,
for the everyday coding scenarios I'm think about, the hyperlinks
generated from the labels are a "nice to have" thing, but not a deal
breaker. If a label can't be automatically extracted, then the
fallback is some explicit annotation, but I wouldn't want the
impossibility of always automatically extracting a label to be a
blocking issue. This process is for generating human-readable text, so
I don't think quite the same rigor need be applied as in the case of a
compiler.

>
>  @chunk[
>  (define foo 1)
>  (define bar 2)
>  ] ... refer to <bar> ...
>
> being a common confusion (and trying to solve it by making this into
> two chunks won't help since then you'd need to explicitly assemble
> <bar> as part of the code).  I think that the best thing -- for now --
> is to just use it as is, until we have enough experience with one of
> these methods to make an informed decision what would be further
> simplifications vs getting more confusing bugs.

To be honest, this aspect of using chunks (where one provides a
partial implementation that refers to the label of another chunk)
didn't really click with me. I'm still not sure when I would really
want to do this rather than the more common (I think) literate
programming style of just switching the reader into text mode part way
through a definition. I almost never break up a function definition in
any case, as I see the desire to do so as a sign that the function is
probably too long. Again, in my opinion, I don't think this use-case
should be a blocking issue. I may be missing some significant obvious
utility, however.

>
> Trust me -- these kinds of \(...) hacks are not going to go well.
> I've tried more than a few.

This, I can't argue with :)
I hoped that it wouldn't be *too* nasty a hack since you've already
got a reader that switches modes on a single character, and we, as a
community, also have some experience at escaping single characters in
general. The left-paren in plain text escaping would be the *only*
character that needs escaping, too (I think). I'm not looking to throw
up a jungle of special-cased characters.

Anthony


Posted on the users mailing list.