Converting a manual in HTML into an epub for the Kobo

[bob451]

Given that an epub is basically just HTML with a Table of Contents (chapters) for navigation, it is interesting to look at how well the Kobo handles HTML elements such as tables, lists, images and code blocks (monospaced text). As an exercise, I converted a programming manual from HTML to epub.

The manual was the Lua 5.1 Reference Manual (www.lua.org, authors R. Ierusalimschy, L. H. de Figueiredo & W. Celes). It has one large table (the index) and some smaller tables, a contents page (a list) and some smaller lists, few images or diagrams, but lots of code samples and specifications (mainly HTML <pre> blocks).

calibre (0.7.12, default settings) converted the HTML into an epub with 44 html files, comprising contents, index and the body of the manual. The 41 files for the body matched the main sections in the contents. Viewing the epub on a Kobo was quite illuminating. The main problems were:

• The index could not be displayed by the Kobo, which rebooted every time it tried to load the page (basically one big, wide HTML table).
• The Table of Contents built by calibre bore little relationship to the 41 files for the body of the manual.
• Code blocks (<pre>) displayed in a monospaced font but were truncated at the right margin.
• The monospaced font is fairly lightweight (thin), so that any non-black text (e.g. green) was somewhat difficult to view as converted to greyscale by the Kobo.

The main problem was the code blocks, which are supposed to display in a monospaced font with leading whitespace retained so as allow indented lines; if the block is too wide for the margins it should be scrollable horizontally. Two examples:

void lua_getfield (lua_State *L, int index, const char *k);     [-0, +1, e]

     co = coroutine.create(function (a,b)
       print("co-body", a, b)
       local r = foo(a+1)
       print("co-body", r)
       local r, s = coroutine.yield(a+b, a-b)
       print("co-body", r, s)
       return b, "end"
     end)

As displayed by the Kobo (medium font), they came out like this, truncated on the right:

void lua_getfield (lua_Sta[-0, +1, e]

     co = coroutine.create(functio
       print("co-body", a, b)
       local r = foo(a+1)
       print("co-body", r)
       local r, s = coroutine.yiel
       print("co-body", r, s)
       return b, "end"
     end)

The "[-0, +1, e]" text is a non-code block in the current font (serif or non-serif) aligned to the right margin; it just overwrites any text already there. There was no way of scrolling a code block on the Kobo, which makes such blocks quite unreadable.

I eventually settled on a format for code blocks where all lines are aligned left, re-indented, and with any wrap-around further indented. It's quite readable on the Kobo.

void lua_getfield 
   (lua_State *L, int     [-0, +1, e]
   index, const char *k);

co = coroutine.create(function
   (a,b)
  print("co-body", a, b)
  local r = foo(a+1)
  print("co-body", r)
  local r, s = coroutine.yield(
     a+b, a-b)
  print("co-body", r, s)
  return b, "end"
end)

The main steps in getting to the final epub were:

• Dropping the index page.
• Redoing the Table of Contents to correspond to the main section headings.
• Redoing all the code blocks to align blocks left, re-indented, and with any wrap-around further indented.
• Changing all text in code blocks to black.

And the result is an epub which is both readable and usable. Obviously, none of the internal links can be utilised for navigation on the Kobo. However, a Table of Contents of ca 40 entries gives reasonable navigation by chapter.

[moffattm]

Thanks, Bob, some useful info there.

[zoran]

Calibre forum has a sticky with tips and tricks. There is a lot of
people looking for the clue and almost all find it sooner or later.
It takes time and nerves, or course. For the second issue, I will
go after Sigil. There is a chance to remove parts, make new toc.
I don't give you the solution, just point to the place where to go.

[bob451]

The same technique for handling an indented line that wraps-around, and for applying a right-aligned block to such a line, is applicable to epub files of poetry and verse.

The Gutenberg version of The Waste Land (pg1321) is a case in point. There are short lines, indented lines and long lines, and the layout matters. On the Kobo (medium font), quite a few lines wrap-around to the left-margin regardless of the indent and the layout. It quite ruins the effect. In addition, the decadal line numbers are not aligned to the right-margin as they should be.

[pleochroic]

thanks for the info. i had issues with calibre conversions and didn't feel like diving too deeply into them.

i am now using jutoh instead, which works brilliantly for my purposes, and has already proven itself worth the U$22 price tag (there is a free trial).