[plt-scheme] NW: Development Status of SchemeDoc

On Jan  6, Noel Welsh wrote:
> Ok.  The extraction thing is pretty simple.  There are
> two markups: the user markup which has shorthand forms
> for common stuff, and the internal markup it is
> translated into, which is a very verbose grammar
> (which happens to be represented as structures but
> could be transformed into sexps.  E.g. you can write
> 
> (contract (list-of number) -> number)
> 
> and the internal version it is translated into is
> 
> (contract (domain "(list-of number)")
>           (range "number"))
> 
> This is done in preprcoessor.ss
> 
> The user markup _is_ represented as sexps. 
> parse-doc-comment.ss extracts it.

Ah.  Well, I was hoping for something a bit more sophisticated, like
what Robby was just talking about.  Also, some module tools -- to
generate the Swindle documentation I have one `configuration' file

  http://www.cs.cornell.edu/eli/Swindle/documentation.txt

which is then used to create the web page, the documentation pages,
and the readme.  This process will extract the docs from the source
files, and it will also determine whether a binding is a variable, a
parameter, a function, a syntax etc.  It will also warn me in case
some exported symbol doesn't have a docuemntation etc.

I guess I'm talking about something different, and the best way of
incorporating that is probably by adding some stuff in info.ss as well
as some uniform way of annotating the sources -- which is also related
to contract specifications, test cases etc etc etc.


> > But also, if the annotations are easy enough, and the extraction
> > is robust enough, it should be useful in very different contexts
> > like latex, info, and even interactive help...
> 
> I'm not sure if you mean generating latex, info, etc.  or you mean
> extracting comments from latex, info etc.

[The former, obviously, latex programmers have their own thing, and I
am happy to not be one.  (I have enough time resisting the urge to
hack stuff so I can avoid some of those tex horrors.)]

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