[plt-scheme] Scribble "SCHEMEBLOCK" that doesn't interpret Scribble markup

On Tue, Feb 24, 2009 at 9:12 PM, Neil Van Dyke <neil at neilvandyke.org> wrote:
>
> You can see the problematic "@" signs in the Scheme code, for which
> I kludged up the below filter just now.  This whole setup (before it
> gets to Scribble, I mean) is kludge atop kludge, while I wait for
> the right *new* embedded documentation format.

Yes, I agree with the "kludge atop kludge" classification...  (BTW, a
backslash does not escape @s in the text part of @-forms, but this
doesn't look like your problem, more below.)  (That's intentional, BTW
-- it makes the syntax much simpler to use.)  Converting the file to
be a string is easier if you just turn it into a Scheme string (that
is, a simple (format "~s" contents)); you can also convert @-forms to
be strings by using the extra characters for the beginning/end, as
Matthew shown:

  @foo|{ ... text where only @| and }| are magical ... }|

  @foo|--{ ... text where only @--| and }--| are magical ... }--|

So you can add -s (or other punctuation) as many as needed up to the
point where they don't appear in the contents.

But I think that this is still not a solution -- the problem that
you're likely running into is that @scheme (and friends) are macros
that expect a Scheme expression, so you want to somehow render that
expression in a way that is protected from using @ as escapse.  It
looks to me like in the original sources you use `@@' to escape them
from texinfo, is this right?  If so, then isn't it possible to just
use \@ in your documentation-in-comments to avoid the problem?  (As I
said above, that doesn't escape @s in @-form texts, but you're looking
for a Scheme escape, one that will treat it as a plain identifier,
right?.)

Otherwise, another solution is to have a simple reader function (for
exmaple, one that uses `read-syntax' with a readtable that sets #\@
back to the default), and plant that inside a `scheme' or
`schemeblock' macro.  The only minor complication is that you need to
do all of that in a macro, since `scheme' is itself a macro.

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