[racket] feeding input to Scribble and source location info

At Sun, 28 Aug 2011 15:58:02 -0400, Neil Van Dyke wrote:
> Matthew Flatt wrote at 08/28/2011 08:40 AM:
> > At Sun, 28 Aug 2011 02:46:18 -0400, Neil Van Dyke wrote:
> >   
> >> Oh, another option to get rid of the two modes: write out a file that 
> >> specifies a custom reader (coming from a PLaneT package), and that 
> >> reader can read syntax objects and return those rather than making 
> >> syntax objects from reading text.
> >>     
> >
> > That sounds right to me, except I'm not sure about the "write out"
> > part. I image your document source should be
> >
> >  #lang planet neil/toscribble/doc
> >  "sourcefile"
> >
> > where the reader specified by `neil/toscribble/doc' reads the named
> > file and produces a syntax object for a module that is a Scribble
> > document.
> >   
> 
> I should have mentioned that my need is for API documentation embedded 
> in a normal "#lang racket/base" file.  So, although it's the source file 
> for the documentation, I can't simply hand that file directly to 
> Scribble.  I need to translate the file first, and then either call 
> Scribble directly with syntax objects or (sounds like) write out a file 
> that Scribble then processes.
> 
> If I write out a file, but I want Scribble error messages to point to 
> locations in the original "#lang racket/base" source file, then I think 
> I'll need the written-out file to have the "#lang planet 
> neil/toscribble/doc" line that will do a reader trick to make syntax 
> objects with locations that refer to the original "#lang racket/base" file.

If I understand the problem, I still think the Scribble document
source should be

  #lang planet neil/toscribble/doc
  "sourcefile.rkt"

and no file should be generated. Instead `planet neil/toscribble/doc'
should extract documentation from the source file and produce syntax
objects.

Then again, maybe it's more convenient to have a macro that reads from
the file instead of a whole new language:

 #lang scribble/manual
 @(require (planet neil/toscribble/doc))

 @(extract-docs "sourecfile.rkt")

More generally, it shouldn't be necessary to generate a file for input
to Racket. If you imagine an external tool that would generate the
Racket program, then instead put the tool in a language or module.