[racket] rendering lists of strings as at-expressions in scribbled documentation

From: Tim Brown (tim.brown at cityc.co.uk)
Date: Mon Aug 2 08:38:52 EDT 2010

[Sorry...
  I'm well practiced at forgetting to attach the meaningful bits...
  Take two!]

Hello all,

I'm using racket and scribble-lp to automatically generate C-code.
I get nice LP documentation of my racket-level scripts, but (by the nature
of what I'm doing) I have code like:

-------------------------------------------------------------------
#lang scribble/lp

We'll want to return 0 from main.

@chunk[<main-rv>]{0}

@chunk[<c-main-program> @list{
   int main(int argc, char* argv[]) {
     return @<main-rv>;
   }

}]

This is the main program. As you can see it doesn't do a great deal.

Now, write the main program...

@chunk[<*>
        (require racket/list
                 srfi/13)
        (display
         (apply
          string-append
          (flatten ; cos my data is usually bumpier than this
           <c-main-program>)))]
-------------------------------------------------------------------

When I run this with racket -- I get my C program out.

When I lp-include it into a scribble file, my <*> chunk is nicely
formatted, but my <c-main-program> chunk is rendered (from scribble --text)
as:

<c-main-program> ::=

   (list
   "int main(int argc, char* argv[]) {""\n""  "
   "return " <main-rv>";""\n"
   "}""\n")

Which, although strictly true, does not really represent the C source in
its most natural form. I have used this scheme (especially @-expressions)
as a text-preprocessing style to good effect in C, HTML and JavaScript.
But each time, I have come unstuck at this point when I need self-
documenting LP code. [I know there are s-expr representations for HTML and
JavaScript out there, but sometimes one just needs a text preprocessor]

Is there any way ask scribble to re-present the list of strings as an
@-form?

If not I could do with help in implementing such.

On closer inspection, a general form would not just look for
(list "string" ...) -> @list{string...} , since list could be any datum,
and "string" could be any datum (e.g. <main-rv>); so I was wondering if
the entire expression could be marked as "from-an- at -form".

Could someone with a better overview of what options are available for me
to label my data in such a way point me in the right direction?

Regards,

Tim

-- 
Tim Brown <tim.brown at cityc.co.uk>  | City Computing Limited            |
T: +44 20 8770 2110                | City House, Sutton Park Road      |
F: +44 20 8770 2130                | Sutton, Surrey, SM1 2AE, GB       |
-----------------------------------------------------------------------|
BEAUTY:  What's in your eye when you have a bee in your hand           |
-----------------------------------------------------------------------'
City Computing Limited registered in London No. 1767817.
Registered Office: City House, Sutton Park Road, Sutton, Surrey, SM1 2AE
VAT number 372 8290 34.


Posted on the users mailing list.