wingolog

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.