Sunday, May 9, 2010

Manually, but for the web

When I decided I wanted to write the manual for Sigil, the first thing that came to mind was putting it online as some sort of website. A web version can be always up to date, you can put a link to it in the Help menu of your application and you don’t have to blow up the download size by including it in the installers.

But that was wishful thinking; Sigil is hosted at Google Code, and it doesn’t offer a way to host custom HTML pages, and I’m not buying a domain and webhosting just for a damn manual. So sadly, that couldn’t work.

The second idea was writing the manual in pure LaTeX, since if I’m going to write an “offline” version of the manual, I’m going to typographically do the best job I can. Epub can be used for technical manuals, but some of the nice typesetting tricks I hand in mind couldn’t be done in it.

Then it occurred to me that having a PDF-only version of the manual for an epub editor was… not the best political decision. I wanted to find a way to eat my cake and have it too: to offer both a nice PDF and a nice epub. I was willing to sacrifice some of the things I could do with custom LaTeX if the resulting PDF was “good enough”.

reStructuredText and Sphinx came into the picture. As I mentioned in a previous post, the PDF version of the manual sucks. Links don’t go where they’re supposed to, the layout is shoddy and in general, it just looks bad (to me at least). Sphinx was primarily designed for creating HTML documentation, and the LaTeX generator suffers because of it. I decided to upload what I had now, gather some feedback on the content and then rewrite the thing in custom LaTeX.

Then came the expected politics

While I’m convinced that I’m right[1], I wanted to talk to a few friends who lead or are members of other open source projects (some hosted on GC too) what their thoughts were on the subject. I got universal agreement that a LaTeX PDF was the way to go, but one of them pointed out that GC indeed does provide a way of hosting sites, just… unofficially. The Google guys apparently have no problems with people hosting their site inside their source code repositories. This could of course only work if your site serves only static content, which a manual would certainly be. They’ve even improved the SVN backend for direct web content serving, so they certainly approve of the practice.

Sigil uses Mercurial, and Google provides every mercurial-based project with many repositories. So I used Sphinx to generate the HTML, committed it all to a new “web” repo and voilà! An online manual.

Sphinx produces wonderful HTML, and I’m willing to sacrifice some typesetting beauty for online accessibility. It’s also much easier to customize the HTML output by injecting new CSS. Tweaking the LaTeX output was a nightmare.

There won’t be an offline epub version since there’s no point anymore and I want people to see the code samples and images on a large screen. But if someone wants one, they can easily download the manual sources and build one with Sphinx.

I think everyone should be satisfied now.


[1] Big surprise there.