In the previous article, I gave brummi a go. However, we've seen that it still doesn't fit our requirements: we need a tool that's fast, easy to install and configure, produces beautiful and usable docs.

Yesterday I started building my own documentation generator, and in this series I'll present the challenges I face and how I solved them. This might show a few ooc tricks, perhaps some software design, some good, some bad, but overall I hope it'll be a good read!

A few days ago I posted an ooc quine. But while browing HackerNews, I found an even shorter one. The shortest!

Here it is, in its full glory

Can't see anything? That's an empty file. It will compile and run just fine. ooc doesn't require a main function - you can just shove code in there that will run at the program's initialization. If there's none, no big deal! It'll just not run anything.

In the previous article, we saw how to use NaturalDocs, a language-agnostic documentation generator. Today we'll see how to use brummi, a tool specific to ooc, written by Friedrich Weber.

The first step to generate docs using brummi is to use rock, to generate a set of .json files describing the code. The --backend command-line option allows to select which backend you want rock to use (the C backend is the default).

While preparing my next post about ooc documentation yet again, I stumbled upon an old ooc quine of mine. Here it is in integrality for your pleasure:

q := 34 as Char
l := [
"q := 34 as Char"
"l := ["
"]"
"for (i in 0..2) {"
"    l[i] println()"
"}"
"for (i in 0..12) {"
"    q print(); l[i] print(); q println()"
"}"
"for (i in 2..12) {"
"    l[i] println()"
"}"
]
for (i in 0..2) {
    l[i] println()
}
for (i in 0..12) {
    q print(); l[i] print(); q println()
}
for (i in 2..12) {
    l[i] println()
}

Documentation in ooc land has sucked for quite some time. The standard response is pretty much: "use the code, Luke!" — which is fine when doing small projects that don't matter much, but not so when you want to get serious.

So when a newcomer, beoran, asked how to generate documentation, and later told us he got NaturalDocs to work, naturally, I had to see for myself how well it worked.

Just 8 days after the last release, rock 0.9.6 is out.

To update, run git pull && make rescue as usual. To install from scratch, clone the repo, cd into it, and run make rescue from there - it'll download the latest bootstrap, compile itself from C, then recompile itself from ooc.

Running rock -V should give you something like this:

rock 0.9.6 codename loki, built on Wed Feb 20 15:09:08 2013

rock 0.9.5 is out! It's the meanest, slimmest, baddest rock release yet.

To update, run git pull && make rescue as usual. To install from scratch, clone the repo, cd into it, and run make rescue from there - it'll download the latest bootstrap, compile itself from C, then recompile itself from ooc.

Running rock -V should print this happy little version line:

I want to write blog posts, but right now I have too much to do.

So instead, here are bullet points:

• I wrote an ooc tool named sam, which helps you keep your git repos up-to-date, and helps to remind you what to push when switching workstations. It's pretty neat, and portable.

• A while ago, I started working on homebrew for Windows, or rather, for MinGW+MSYS. Provided you have msysgit and Ruby in your PATH, it'll let you brew install most packages. I've tested a few dozen, send in your pull requests anytime.