YGingras^.net

There are fashions in the markup world. There was a time when using colons (':') to split fields in /etc/passwd was enough, a time when no one had a problem with using TABs as command delimiter in Makefiles. Then came the era of heavy markup, "more semantic!", they all asked for, and we received XML.

More semantic is a good thing but anyone who wrote documentation using DocBook knows that the heavy syntax gets annoying really fast. No wonder no one documents his programs. Fortunately, some lazy programmers wanted, for some obscure reason, to document their programs; they propelled us into a new era of light weight markup.

There are quite a few really good light weight markups out there, and Gazest supports most of them. For simple formating, my favorite is definitely Markdown. It reads like text emails: the syntax doesn't do much but the essentials are there and the syntax actually helps to read the source instead of obfuscating it. For blog comments, or anything that won't need much semantic, in applications where you can't use for HTML, for security reasons or just because it's a pain to type, Markdown is the way to go.

Nevertheless, it happens that you need to write larger documents and that you'd like to have semantic blocks: code examples, warnings, notes, and that kind of stuff. Now you enter in the no man land where you'll meet many proponents of heavy markup. There have been failed attempt at introducing semantic in light weight markups: reStructuredText reads like Perl. It seems to be optimized to be easy to parse but it's far from easy to read; at least it's easier to type than DocBook.

You can't see the light until you see AsciiDoc. AsciiDoc reads as easily as Markdown and with minor addition to the markup, it unravels the full semantic power of DocBook. AsciiDoc is more than an easy way to get bold text, it gets you all what docbook has to offer: man pages, PDF, and html. All of this with amazingly sexy stylesheets. There was no way around it, I needed AsciiDoc in Gazest.

It's a Python program, can't be too hard to hack. Right? Well, it turned out that it was a Python program but not a Python library. Well, why not turn it into a library then? That exactly what I thought and what I sent rough patch to Stuart Rackham, he said: "Great! Just do it!" I am extremely pleased to announce that I'm the official maintainer of AsciiDoc Version 9. Many exciting things to come for 9.0 but there is no API or release yet. I have a few ideas of what I want in the API but I'd also like to know that you want in there.

You can't have a great documentation system without using it. I added an asciidoc command to buildutils and I used it for Gazest; it works great. Just download it and look in doc/html to see for yourself. I liked the result so much that I decided to cleanup and release a few bioinformatics tools that I wrote some time ago. You know how it is: you rush to get the paper done and then you forget about those perfectly fine tools that just need a little bit of polishing before someone else can use them.

Hey! This is not all. I received a lot of feedback from the other Setuptools plugin developers and that lead to setuptools_git 0.3.1, which is essentially the same thing but with improved documentation. While I'm at it, I added a few features to Yould: there is now a timeout option and it's possible to "seal" a training set to reduce memory usage. Latest version is Yould 0.3.7. The timeout option is really good if you want to batch process a lot of really restrictive regular expressions. Some might yield results fast, some might take hours to produce a few words. On the other hand, I fail to see why you'd seal your training sets if you don't run Yould on your website.

That should be enough for now. I know you are all waiting for the next Gazest release so I get back to serious code. Stay tuned.