wingologA mostly dorky weblog by Andy Wingo2007-10-04T03:21:00Ztekutihttps://wingolog.org/feed/atomAndy Wingohttps://wingolog.org/vignetteshttps://wingolog.org/2007/10/03/vignettes2007-10-04T03:21:00Z2007-10-04T03:21:00Z

in which our protagonist locks himself out of his house

After a pleasant aikido session, in which our protagonist got his ass kicked by his instructor, young Mr. Wingo found himself locked out of his house. Holes have been appearing in the right front pockets of this gentleman's trousers, the key pocket, pant by pant, leaving our plucky subject to port his house-keys in bags and other objects that detach from his person, a fact lamented as the phone to his flatmates rang on and on.

Stoically our protagonist ducked into the local bar, at which point both flatmates finally got back. A buzz on the door y comieron perdices.

Moral of the story: when in doubt, bar?

in which the third person is abandoned

The Scheme Workshop last weekend was great. Got to meet lots of intelligent and interesting people, and my paper was well received. Slides here, along with some minimal notes.

I made the slides with guile-present from bzr, which requires guile-cairo and the new guile-rsvg. The actual slides were written in texinfo (a civilised format), which guile-present parses and transforms using guile-lib. A metacircular work.

Also: Freiburg is beautiful. Who knew? I'd love to go back sometime and poke around the black forest. Kind folks too, with a predilection for umlauts and bewindering compound words.

Andy Wingohttps://wingolog.org/documenting language bindingshttps://wingolog.org/2007/07/18/documenting-language-bindings2007-07-18T19:39:45Z2007-07-18T19:39:45Z

I had lunch with Jao before he left for Zurich, throwing around ideas over copious wine. He made the observation that a lack of good documentation is a limit to software's potential impact, with particular reference to the pile of code that I've written or maintained. Point taken! With that thought in mind, I've been trying to focus more on documentation. In this blagpost I will summarize work on documenting language bindings.

haskell

Duncan Coutts, the gtk2hs maintainer, called me out at FOSDEM earlier this year. I was presenting about Guile-GNOME, and sheepishly mentioned that the entire project was undocumented. Duncan was kind enough to point me to how gtk2hs does things.

Their bindings are automatically generated at the beginning, then tweaked and maintained by hand. The Haskell folks have developed a documentation system that involves specially formatted comments in the code, similar to Javadoc or gtk-doc. When the bindings are first autogenerated, their generator produces the documentation as well.

The documentation actually comes from the docbook files produced by gtk-doc; that is to say, from the upstream C documentation. They run some basic search and replace operations on the output so that it is more "Haskelly". Seems to be a reasonable way to bootstrap the documentation, and the HTML output certainly looks good.

gtkmm

I asked Murray what gtkmm does, and it seems that they do something similar. The difference is that they combine the C documentation from the docbook files into one XML API-cum-documentation file, then generate their documentation from that.

Also, presumably since C++ is similar enough to C, gtkmm bindings regenerate their documentation all the time, customizing the documentation for only about 5% of the functions. Customizations are maintained in a separate overrides file. The output documentation is made with Doxygen, which looks OK but not as nice as Haddock.

java-gnome

A bit tipsily last night I prompted Andrew Cowie to opine about the same topic. Java-gnome people are apparently awash with contributors, as they decided at some point that they would hand-write all of their language bindings. They do the same with their documentation -- all written by hand, and processed with javadoc. The HTML documentation looks OK, better than Doxygen but it seems that the wrapper itself is incomplete.

pygtk

As far as I know, the most excellent pygtk documentation seems to be completely written by hand.

guile-gnome

Guile-GNOME itself is still undocumented, as whichever way I might go, it will be a lot of work. It pays to invest a few weeks figuring out the right way to go.

As a test case, I looked at seeing how difficult it would be to automatically generate documentation for Guile-Cairo. I cannot write all documentation by hand; it is too much. Instead I looked at reusing the technique from gtkmm/gtk2hs, munging the docbok generated by gtk-doc.

There are three documentation formats that are equally important to me, and one that is less important.

The first one is HTML, so that someone browsing the project's web page can see the status of the binding.

The second one is "online" documentation, so that when I am at the Guile listener I can type (help cairo-get-extents) and get good documentation. (This is also the case when I hack in Emacs with Guile-Debugging, and I type C-h g. More on that later.)

Thirdly we have local searchable documentation, either via Info or via devhelp. Lastly, we have hardcopy output as PDF.

For me and for Scheme users, these requirements point to texinfo as the intermediate format. I can generate good-looking PDF output with indexes, HTML output, and Info, which is actually quite OK. In addition I can write out a text representation of the texinfo into a docstring file, which allows the documentation to be available at runtime without incurring memory use penalties.

I don't have the documentation-generation code nicely packaged yet, but I'm pushing it into other projects. I think I need to let it sit for a while, to see if I actually want to undergo the pain of documenting the bindings for the GNOME stack, given that even for Guile-Cairo some work remains. Anyway, that's the hack of the last few weeks. If you are a bindings author, or less likely, are a would-be Scheme hacker, and are at GUADEC, pull me aside and we can chat about such things. You will know me by the extra-large chops.

Andy Wingohttps://wingolog.org/high on sodium vaporhttps://wingolog.org/2006/11/17/high-on-sodium-vapor2006-11-17T20:43:18Z2006-11-17T20:43:18Z

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.