Farewell CHM, hello EPUB!

For a long time, the MySQL Documentation Team has been providing CHM files for most MySQL documentation we publish. Like many other formats, CHM-format docs can be downloaded from http://dev.mysql.com/doc. CHM (Compiled HTML Help) has been the de facto standard help file format on Windows since 1997, but the technology behind it is outdated and has all kinds of quirks. The successor format introduced with Windows Vista is AP Help, but it hasn't taken off in practice so far. So, with CHM being outdated and AP Help spread anything but widely, lots of vendors have started providing documentation on Windows in PDF or HTML format.

Building CHM-format documentation is a challenge of its own. I'll not go into details here, so let me just state that it requires a dedicated Windows box (or VM), and while it can be automated using Power Shell commands, there's no way to find out whether or not a CHM file was built correctly, except by manual inspection. This makes it different from all other documentation formats where technical QA is done (successfully) in an automated fashion.

With the increasing complexity and size of our documentation (the MySQL 5.1 Manual contains more than 1.6 million words now!), providing CHM has become more and more of a pain, because builds tend to break more often. We've stopped shipping CHM with the MySQL Server on Windows months ago because we simply couldn't guarantee that the help file shipped with the software would work. Also, we're running short on hardware resources, so we'd rather stop wasting the resources we have on building a format that's of limited use, anyway.

This is why we'll stop providing CHM for any of the documentation we publish.

To alleviate potential pains anyone might have with this decision, let me tell you that we've started providing EPUB-format docs. EPUB (see http://en.wikipedia.org/wiki/EPUB) is an open standard format for screen readers, mobile or not, and is fairly easy (and not resource-intensive!) to compile. Thanks to Lenz for suggesting to build EPUB!

Go to http://dev.mysql.com/doc to grab MySQL documentation in EPUB format. To read EPUB on desktop machines, I use a Firefox add-on, unsurprisingly called epubreader, which loads EPUB documents fast and renders them nicely. That said, please be aware that EPUB can't do anything about the fact that the MySQL Reference Manual is huge, so downloading it to a mobile device can take a while. The MySQL 5.1 Manual is currently a whopping 15 MB!


Sounds like a good decision, although in 10+ years of MySQL related work I never used any of the offline formats seriously. Instead, I found the best way is to use Google and search for "mysql [keyword]" - which brought me safely to the right online document which I was searching for - apart from the automatism which always directs to me to the german (and less reliable I found) docs instead of the original, english ones. As programming HeidiSQL is often version dependent, I often need details about which version has started to have some new feature - this is also quite comfortable on the english doc pages, as on the left navigation there is always a list with 3.23-4.1 / 5.0 / 5.1 / 6.0 links. The only recommendation I have is just to ask the user if he really wants the local doc and probably store that cookie based.

Posted by Ansgar Becker on September 06, 2010 at 05:49 AM CEST #

Yeah, translations are a lot of work, and keeping something like the MySQL Manual up to date is nearly impossible, unless you have a huge budget for translations.

As for being directed to the German version of the MySQL Manual, isn't that really a Google options thing? For example, selecting English specifically brings up the English pages first (e.g. http://www.google.com/search?as_q=mysql+select&hl=de&num=10&btnG=Google-Suche&as_epq=&as_oq=&as_eq=&lr=lang_en&cr=&as_ft=i&as_filetype=&as_qdr=all&as_occt=any&as_dt=i&as_sitesearch=&as_rights=&safe=images). Even if I don't specify the language in Google, the English version of what I'm looking for with "mysql <keyword>" tends to yield the English version as the second result.

Posted by Stefan Hinz on September 06, 2010 at 06:23 AM CEST #

CHM was handy for the book-like reading experience with navigation options, I have always enjoyed that format. But EPUB is just fine. Wish the Kindle supported it, though.

Posted by Mark on September 06, 2010 at 06:25 AM CEST #

> As for being directed to the German version of
> the MySQL Manual, isn't that really a Google
> options thing?

Oh yes, you are right - it's Google prioritizing the locale page over the english one. So I just have to watch which result to click.

Posted by Ansgar Becker on September 06, 2010 at 06:36 AM CEST #

Awesome. Thank you very much for the quick implementation of this feature request! I guess you can resolve BUG#56260 as fixed then :)

@Mark: ePub documents should provide the same level of navigation than what CHM offered. You might want to check this blog post for pointers on how to convert ePubs for the Kindle: http://kindleworld.blogspot.com/2009/08/million-free-google-books-in-epub-for.html

Posted by LenZ on September 06, 2010 at 06:41 AM CEST #

[Trackback] Wie ich schon am letzten Freitag auf Twitter andeutete, gibt es das MySQL-Referenzhandbuch nun auch im eBook-Reader-freundlichen ePUB-Format. Als Besitzer eines Onyx Boox Readers konnte ich das Handbuch zwar schon im CHM- oder PDF-Format recht vernünft...

Posted by Lenz Grimmer's blog on September 06, 2010 at 07:05 AM CEST #

I usually read the documentation online and find it with Google. Sometimes I download the PDF, but it goes out of date in a few hours :-)

The MySQL documentation team does an amazing job and doesn't get much public thanks for it, so: THANKS!

Posted by Baron Schwartz on September 06, 2010 at 07:11 AM CEST #

When reading the 5.1 manual in Aldiko (for Android), it makes your fingers burn,.

Posted by Robert on September 06, 2010 at 11:32 AM CEST #

Good idea, flawed CSS though- I prefer to read technical reference books on an eBook Reader (in this case, a Kindle). Kindles have been coded not to like ePub, no matter how much I like the format. Consequently, an accepted method to put ePub content on the device is to modify the file with Calibre and output a mobi formatted file. Unfortunately, due to the hundreds of CSS format errors in the ePub file in the mySQL 5.1 Refernce Manual, Calibre chokes on the output... Sigh...

Posted by Enk on September 06, 2010 at 11:59 AM CEST #

@Robert: So reading makes your fingers burn. Interesting. Can you elaborate?

@Enk: "Hundreds of CSS format errors" isn't particularly good information to help us debug this. Can you post half a dozen of these errors or so, so we can have a look?

Posted by Stefan Hinz on September 06, 2010 at 12:04 PM CEST #

It's great that the documentation team has decided to adopt the EPUB format. I've only taken a quick look but so far the book looks great!

Along with the Firefox add-on you can also use the Adobe Digital Editions eReader software (no Linux version yet though)


I have also tried this out on the iPad using the Stanza Reader, which after reducing the font size a little, worked pretty good. iBooks didn't handle it quite as well and was a bit sluggish.

You should also check out the ibisReader.com online EPUB reader.

Posted by Mike Cook on September 06, 2010 at 04:42 PM CEST #

@Stefan: Well the CPU effort put in by the the poor 1ghz device when opening the 5.1 "book", is on the large scale. Reminds me of the movie "Burn After Reading", just the other way around....

Posted by Robert on September 07, 2010 at 01:04 AM CEST #

Hi Stefan!

I guess I am one of the few .CHM users - I think it is a very convenient format for offline documentation, and there are a few products for which I always want to have that (even if that means it isn't completely up to date).

I have a few projects where I build CHM files myself so I know what a pain it is to build it. I build with MS HTML Help workshop, and it's just terrible so I can completely understand why you'd wanna chuck that away as soon as possible.

Anyway, I checked out the new EPUB format (using the firefox plugin you recommended). Overall, it looks pretty good. However, I feel the CHM readers offer a better experience. A big thing is an expandable toc - that is, the "treeview" rendering of the toc is easier to navigate IMO. Also, the EPUB format seems to load pretty slow in firefox+plugin as compared to the default chm viewer on windows. Other interesting CHM features include fulltext search.

Now, I realize this is still early days for the MySQL manual in EPUB format, but eventually I would like to see some of these features. I noticed EPUB is html - does it also support javascript? In that case, I think a treeview-like toc should be pretty easy to add. If you're interested in these kinds of features, please let me know because I think I might be able to help.

TIA, and kind regards,

Roland Bouman

Posted by Roland Bouman on September 07, 2010 at 02:14 AM CEST #

@Mike Cook: Thanks for pointing out more EPUB readers! I've installed Adobe Digital Editions on my Windows VM, and, although it seems heavily based on Flash, I must say I'm impressed. Loads and renders quickly, and has all the essential features I miss in the Firefox epubreader add-on: Full-text search and collapsible / expandable table of contents.

@Roland: Very nice of you to offer help with improving the EPUB experience of MySQL docs! And yes, I also miss CHM; I'm probably sentimental because _creating_ Microsoft Help files (the RTF version still) was my first experience with hyperlinked documents, long before I started writing HTML pages. The Microsoft Help Compiler book with a diskette version of that free tool is still on my bookshelf. :-)

And indeed, we've been creating CHM with the "standard" tools, i.e. the DocBook XSL style sheet and Microsoft Help Workshop.

When it comes to adding JS and/or CSS to the EPUB books we provide, I'm not sure if that's a good idea, considering that many readers (like Adobe Digital Editions, see above) provide exactly the functionality you're missing. Not sure how those readers would handle a "built-in" layer providing those features.

As for the format, EPUB is basically a ZIP wrapper around an XML wrapper of XHTML; see http://en.wikipedia.org/wiki/EPUB#File_format. It should be fairly easy to "tune" files with CSS and even JS, but then again I'm not sure if it's worth the effort, plus it might have negative side effects on readers that are more capable than the epubreader add-on.

Posted by Stefan Hinz on September 07, 2010 at 05:42 AM CEST #

Hi Stefan!

ok - I see. So basically, I should be looking for another reader? That's fine too of course, I'd rather use a working solution than cobble up something anew. Thanks for the tip, I'll try out a few readers.

Posted by Roland Bouman on September 07, 2010 at 06:20 AM CEST #

Post a Comment:
Comments are closed for this entry.

mysqlf is a common typo on the #docs IRC channel of the MySQL documentation team. It shows a high (some might say, dangerous) degree of identification with MySQL. Trying to pronounce it will probably result in tongue injuries.


« August 2016