high on sodium vapor

17 November 2006 8:43 PM (scheme | guile | texinfo | literate programmin | documentation | info)

Hello! I would like to show off a hack. It is this:

This is me editing a piece of guile-lib, an anemic collection of modules written in guile scheme. The docstring is highlighted in pink due to a crazy .emacs that I inherited from my friend Leif.

Note that the reference to sxml is written in texinfo, what to me is a beautiful and appropriate language for documenting software.

This is me at the guile> prompt, asking for help on the procedure sxml->string. Note that help has parsed the argument list and put it there for me, without me having to document it. Also note the the @var{sxml} is rendered as SXML, which is normal for a metasyntactic variable.

That's possible because when I ask for help on an object, guile parses the docstring using (texinfo reflection) into an SXML dialect.

From the SXML format it's possible to do lots of things, like transforming it into HTML, and then serializing to XML. So we can have nice-looking, clean docs.

Using the parsed texinfo, we can programmatically construct documentation for an entire set of modules, using both the written knowledge in the docs and the "live" knowledge that guile has of the instantiated object. The above image is from a high-quality PDF rendered by TeX, after guile-lib serialized the parsed documentation back to normal texinfo.

The texinfo file can also be processed by makeinfo, which is a useful if idiosyncratic system for document browsing. The nice thing about info is its index: press i sxml-> TAB and you can see all functions that operate on sxml data.

Neat eh? The only problem with having nice documentation output in many formats is that it doesn't hide bad text. We still have a ways to go in that department.

4 responses

  1. Chris Parker says:

    Wow. I have been playing with Guile a bit, and the guile-gnome bindings are great. Why isn't more software written in it?

  2. jay says:

    I'd love to use guile (or scheme/lisp in general) for doing gui stuff for gnome, but to my experience there are not good bindings available :( guile-gnome might be good, but there hasn't been any releases, and the website wasn't updated with news for ages (until now recently, with a post about moving to bzr).

    Hmm there appears to be packages in ubuntu for guile-gnome, but these depend on guile 1.6. Isn't this a very old release? Someone should make sure guile 1.8 is included in the next release of ubuntu, and also make an release of guile-gnome!

  3. Ricky Youngblood says:

    When was the last time you got laid?

  4. wingo says:


Comments are closed.