Saturday, May 8, 2010

Manually

I’ve just uploaded the manual for Sigil. You can get it from the downloads section.

The manual was written in reStructuredText (RST) and then processed with Sphinx. Honestly, I’m not too happy with the layout of final file compiled from the Sphinx-generated LaTeX. Some of the hyperlinks don’t lead to where they’re supposed to (bug in Sphinx I guess), and typographically in general… well I don’t like it.

Initially, I wanted to write the manual in straight hand-coded LaTeX. I decided against that because that would mean the manual would only be available in PDF form.

Now, I’m the kind of person who always tries to use the right tool for the job. I love epub and absolutely abhor the PDF “ebook” novels. PDF for novels just doesn’t work, and if you’re producing them… don’t. Make epubs. But for technical manuals with complex layouts, code listing, figures, diagrams, sidebars and the like, PDF is the right choice IMO. Epub is just not the right call for these kinds of books.

Sure, you could make epub versions of technical manuals, but you’d have to sacrifice some of your layout.

Then there’s politics. An epub editor with a manual in PDF form only? That just looks bad. That’s kind of like Microsoft employees using Linux.

I was pondering this until someone told me that the next version of Sphinx will have an epub generator. You would give it RST and it would spit out a nice epub file from the same source it would generate LaTeX markup. That sounded like an amazing deal, so I went with that.

I loved RST until I started using it. I don’t love it anymore. It has a weird syntax and to get anything above the barebones, you have to do all these strange contortions etc. Add to this that the resulting LaTeX markup produces a PDF that I dislike. I tried to tweak it here and there, and I’ve improved the output considerably over the last few days, but still… Having an epub file to silence the naysayers is good, but not at the expense of quality.

I’m pretty sure I’ll be rewriting the manual in pure LaTeX when I get the time (a few weeks from now, probably). Until then, enjoy the current version.

And if someone feels that the new PDF-only manual shows Sigil in a bad light, I say screw ‘em.