Ormulogun: generating an EPUB puzzle book

2018-03-30

I have added yesterday a jl_to_epub script in Ormulogun to convert a list of puzzles into an EPUB puzzle book. I am moderately satisfied with the result, but the process was frustrating. Mostly for technical reasons, but also because the testing process is quite long and convoluted (generate book, reboot ereader, mount, copy book, unmount, eject, wait for database to update on the reader, open book—the whole process takes several minutes).

Here is a result in Calibre's ebook viewer (two pages side by side):

And here is how it looks on my ereader (KO Reader running on an old Kobo Touch; the aliasing is less pronounced on the actual eink display):

Good stuff

EPUB and XHTML work well together, meaning you can use the same toolchain to generate the EPUB metadata and the content itself. It's all XML.
Formatting the answers (with the tree of variations) was a fun programming task, and I really like how they look.

Bad surprises

Styling is very fragile. Forget about using background-image or even position: absolute. I had to fall back to using a fixed-layout <table> to draw the chess board. Making it have a 1:1 aspect ratio used the standard trick of using a child with padding-bottom: 100%:

Unknown width, 1:1 aspect ratio.

SVG support is terrible. I couldn't get transparency to work, and the antialiasing (or lack thereof) was horrible. I had to rasterize the piece images, making the book bigger and uglier, but it was the lesser evil of the two options.
Reading the EPUB specification makes for dry and obscure reading. There is a lot of jargon and you have to keep your track in many different documents just to accomplish one thing.

Possible improvements

Group all the puzzles together, then all the solutions together, and use anchors to navigate from puzzle to solution. Possibly shuffle the order of solutions to avoid spoilers. (The current layout is puzzle 1, solution 1, puzzle 2, solution 2, etc.)
Categorize puzzles in chapters based on their tags; I am not sure this is a good idea as it would give a strong hint as to how the puzzles are to be solved. Maybe a tag index at the end of the book?
Show more than 1 puzzle per page on large displays.

What are the use cases for something like this? Ereader displays are great, especially with regards to battery usage and readability in very bright environments. If you need to look at the board for 15 minutes, you can do so without wasting battery, unlike phones and tablets. The drawback is that you lose the interactivity of the website version, but in that regard it's no different than a regular puzzle book. Just like regular books, it can also be used offline, which comes in useful when travelling.