If you use a UNIX-like system, chance are that you use man, the documentation system (man stands for manual, just type man man in a terminal). But if you ever tried to write one of those pages, you step into a painful arcane world of obscure macros and strange syntax of a forty some years old utility.

Kristaps Dzonsons gives us a quite enjoyable history lesson on this world of UNIX documentation that brings us to mandoc. Ingo Schwarze follows with a more technical review of implementation of mandoc.

But what is mandoc ? Mandoc is a tool for formatting man pages. The idea was to separate content and formatting. The old way keep mixing formatting and content. But in our “modern” world, some content is likely to appears in multiple format : web page, printout, cell phone, friendly format for search engine, etc. And mandoc is quite succesful at doing it : terminal view, html, pdf, epub, name it and it will probably support it. Moreover, it contains some clever options such as a lint mode. And they develop a search semantic aware search engine.

OpenBSD folks does a good job in creating and converting all the doc in about two years. They got two motivations :

1. Kick out C++ code from code base (groff, the previous tool is written in C++).

2. No GPLv3 software in code base (groff is now GPLv3, which is somewhat incompatible with BSD license).

So as release 4.9, OpenBSD doesn’t include groff in code base anymore. Hope to receive my CD set soon to play with mandoc and take a look at source code.

In my day job, I’m working all the time with EPUBs and PDFs. So I was quite interested by the presentation of Benedict Reuschling who manage with gabor@ and hrs@ to convert FreeBSD documentation into EPUB format. Wouldn’t be convenient to get all the FreeBSD documentation into our pocket, on a cell phone or ebook reader (the last one needs bigger pockets ;-) ? For sure, especially when trying to fix something on our FreeBSD computer.

I’ve learned that almost all the FreeBSD documentation is in SGML format, you know the grand father of XHTML and XML ? So they need to convert it to a more convenient format, the DocBook, which is a formalized XML. From that point, it would be easier to script the conversion to epub, which is essentially a zip file that contains a xhtml version of a book, with some standardized metadata. There still manual tweaking to be done to ensure the EPUB would works well on all readers. epubcheck also is very helpful to find errors in those kind of file.

It is still a work in progress, since there’s a lot of documentation to convert, but looks promising.

In some strange ways, an open source software often get notorious when there’s some media buzz around it : conference, podcasts, screencasts, but mostly books. As long as no book cover a specific piece of software, it is somewhat in a fragile state : it gets legitimate once O’Reilly, AWL, Apress, Manning, No Starch to name a few publish something on it.

Michael W Lucas gives us a speech on the importance of books and how to write one of them, it the hope that more books on BSD will bring more people in the community. He writes very good technical books that are pleasant to read, which unfortunately are so frequent in computer related-books, even if there’s a lot of books publish each year.

I could be tempted to write a technical book some day. But I must improve my English writing. As you can guess, English isn’t my mother tongue language. And actually, I’m already overwhelm by books ;-)

The guys at NetBSD manage to do regression testing on their favorite OS (see src/regress). It may only occurs on a BSD system, since the source tree contains the code of all the system. Testing a system like GNU/Linux will require to get the source code from many places : kernel, GNU tools, Apache Foundation, etc.

NetBSD use Automated Testing Framework. But ATF wasn’t as good as it appears. So Julio Manuel Merino Vidal rewrites it and improve it, which gives us Kuya. It is still a work in progress. Unfortunately, it’s written in C++, so it can’t be used by OpenBSD base system, which only supports C, shell and Perl scripting. But I’m curious and will give it a try on a NetBSD system.

BSDCan starts with a quite funny talk of Peter H Salus about Unics history, ponctuated with some USENIX conference’s anecdotes.

One of them resume pretty well the spirit of Unix users.

They want to demonstrate the mechanism of scheduling. By observing and tweaking the elevator system, they manage to find the algorithm that control them. Moreover, they find a bug in it. So they manage to block all of them to one level in a somewhat infinite loop.

“They’re so smart that they break things.”

But the talk close on one big mystery : why they aren’t more women involve in computer science ? In some countries, like Poland, they are almost as par a the number of men. But it’s mostly common that they are very few women in software development or other computer related jobs. As a matter of fact, only three or four woman are at BSDCan on the 300 some attendees.

I went to grocery store at downtown Ottawa during the BSDCan. As usual, I wear some geeky t-shirt. The cashier was wondering what’s on my t-shirt.

- Wait, it looks like a puffy fish with some Tron outfit.

- Yeah, it’s OpenBSD. They mock some popular movies with their mascot.

- Open…BSD?

- An operating system. Free and open. It’s Canadian-based you know.

- Aaah, but other operating system is not for me. It’s a software issue you know ?

As usual, BSD is a big unknown operating system. But at least, some other people will have heard of it for the first time.