Re: Document formatting in Scheme

["Paul T. Graunke" <ptg@ccs.neu.edu>]

I would focus on the markup language.  Changes (that aren't backward
compatable) to the markup require changes to all the documents,
document generators, and document processors.  If the format you
pick happens to be an x-expression, then you can convert it to XML
using the PLT XML library.  If you prefer some other library, I bet
it wouldn't be hard to automatically convert x-expressions to
whatever other libraries accept.

For transformations, I would consider using `match' and quasiquote.

Paul

On Fri, Oct 26, 2001 at 06:23:55AM -0700, Noel Welsh wrote:
> 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