[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.