Document formatting in Scheme

[Noel Welsh <noelwelsh@yahoo.com>]

Hi all,

Schematics was created to provide the tools I felt I
needed to create high quality packages in PLT Scheme.
This meant two things: a testing framework, and a
document creation system (so I can make pretty manuals
like the ones that come with PLT Scheme). I've got the
first done (though I need to update it to v200) but
the second has been a long time coming. It looks like
I'm now in a position to resume work on it.

One half of the problem is API documentation. For this
I have half of a solution: scmdoc extracts comments
from code and moshimoshi can be trivially modified to
parse the human readable markup appropriate for API
documentation.  I'm thinking of a system where
doc-comments look something like:

;;!
;; Contract: (String) -> Phone-Number
;; (get-phone-number name) -> phone-number
;;
;; Get the phone number for the given user

I.e. quite similar to HTDP comments.  For this comment
would be output some appropriate markup which would
eventually become a nicely formated manual.

The bits I don't have are:
 - a markup language to write the rest of the
documentation in
 - a backend to convert whatever markup I use to the
various formats people will want, starting with HTML
and moving to LaTex, PDF etc. as the demand arises.

It should be possible to express content in a fairly
simple markup.  E.g:

(manual	(title "scmunit")
		(introduction "scmunit is a unit-testing framework
for...")
		(chapter 1 "blah blah"))

and transform that into elaborate HTML etc. via some
sort of style sheet.  The technique du jour to do all
this would be XML and XSLT but I rather eat my shoe
than deal with that bloated mess.  I don't mind the
external representation being XML but I don't want to
have to see it and I certainly don't want to deal with
XSLT.  Now there are a number of existing packages
that do part of what I want.  The ones I aware of are:
  - The XML library in PLT Scheme: XML representation
as sexpr
  - SXML: as above but includes transformations
  - tex2page: LaTex to HTML
  - LAML: sexpr to HTML
  - BRL: embedding Scheme in other documents (useful
if the author is familiar with HTML/LaTex but not
Scheme)

So my question is: does anyone have any suggestions on
directions to take?  Does anyone have an
implementation I can work on?  This kind of stuff is
generally useful for maintaining web pages and other
documents so I'd surprised if others haven't worked on
this.

Thanks,
Noel

__________________________________________________
Do You Yahoo!?
Make a great connection at Yahoo! Personals.
http://personals.yahoo.com