[plt-scheme] Literate scribbling question

On May 21, Anthony Cowley wrote:
> 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).

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.)


> >> 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 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:

  @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.


> If pulling out function names from program syntax is too hard, [...]

Pulling out names from *code* is not difficult -- but pulling it out
of random text is, and the main difficulty is what to do with the
names that get pulled out.  (Those are two separate problems -- the
first one is solved by using `@chunk'.)


> >> 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.

If an in-line `@chunk' is fine only up to indentation, then I don't
think that hacking the syntax level is a good idea.  Specifically,
having some implicit delimiters (eg based on indentation) can be a
very bad idea.


> 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.

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

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                  http://www.barzilay.org/                 Maze is Life!