[ANN] DocumenterEpub.jl

Hi,

I’m releasing 0.1.0 of DocumenterEpub.jl. The provided EPUB() can act as a drop-in replacement for HTML() format and will then create an EPUB file to be consumed on e-ink devices.

From the README:


  • Create epub 3.2 files, but stay backward compatible where possible (e.g. include the navigation as .ncx file)
  • Use a simple layout/CSS to be compatible with older e-reader devices
  • Use JuliaMono for syntax highlighting
  • No JavaScript dependency in the resulting EPUB through

I’ve tested it by creating an EPUB for the Julia manual, but am expecting bugs and short comings on other repositories and eink devices - feel free to open bug reports!

Example:

44 Likes

Thanks! Could you post the epub of the manual, so we can see what it looks like?

Sure! I’ve updated the first post.

1 Like

Pretty awesome work! Here’s what it looks like in Apple’s Books reader.

I noticed the user input didn’t pick up the font… Otherwise, very useful!

6 Likes

Cool! and I’m glad you found some of the code in Franklin to be worth re-using :smile:

6 Likes

What should one use to view the epub file? In my (limited) experience, reading an epub is a form of punishment. Poor typesetting, no zooming, no reflowing, … (I use SumatraPDF on Win 10. Maybe that is what is wrong?)

1 Like

@PetrKryslUCSD Epubs work particularly well though Apples Books app for iOS, iPadOS, and macOS.

Understood. But what about the other OSs? I don’t see much advantage of epubs over PDF really. Is there any?

Isn’t the point that the text can reflow to the size of the device?

5 Likes

I read it on a dedicated e-ink reading device (Kobo).

Most non-Kindle ebooks are packaged as EPUB, and should solve exactly the problems you list: They are reflowable, zooming of SVG math looks great, and the typesetting is optimized for the device.

6 Likes

It sounds like Adobe Reader’s feature for viewing PDFs in Liquid Mode, which comes handy in cell phones.

Hi,

Apparently Apple’s Books needs a special meta data entry. Could you try the following file?

https://github.com/laborg/DocumenterEpubExample/blob/master/The_Julia_Language_color_mac.epub

Best regards,

Actually, I was able to find Calibre for Windows. It is able to reflow and zoom the text, which really looks rather good:


I own a few epub books, which I read in the past without much enjoyment for the esthetics, so I am happy to have found this!

2 Likes

This version doesn’t appear to be any different…

This very same file with Calibre on Windows:


The number strings are typeset correctly.

Another option that seems to work well on Windows, is available on other platforms, and is free is Adobe Digital Editions. It handles both EPUB and PDF documents nicely.

Thanks you!!

I use a lot my ebook reader (mainly for reading novels, but sometimes I use it also for technical reading), and for large manuals it is great to have that option.

Version 0.1.1 is queued to for merging in the GeneralRegistry. With this, Apple Books will correctly use @cormullion’s JuliaMono font.

2 Likes

With the release of 1.6 I’ve built the corresponding manual as EPUB:

https://github.com/laborg/DocumenterEpubExample/blob/master/TheJuliaLanguage-1.6.0.epub

5 Likes

Looks interesting! It would be great to have documentation of Julia manuals and tutorials available on an e-reader.

I’ve checking out possible readers to replace my Kindle e-ink. Problem with my Kindle e-ink:

  • Too smal screen, only 6"
  • Kindle e-ink readers cannot open ePub, I think
  • Kindle e-ink readers can even not open science books with math, etc., sold as Kindle books. But Windows, iOS, and Android Kindle apps can display such Kindle files.

Currently, I’m looking at 7.8" or 10.3" e-ink readers from Onyx, e.g., Onyx Boox Note Air, or similar. Their advantage:

  • long battery life (apparently up to 75 hours of continuous reading) – which is much better than LED based readers (iPad, Android, etc.)
  • Android 10 OS: comes with ePub reader, can install Android Kindle reader, etc.
  • It even comes with pen and note taking features.

Down-side: no color. Oh, there is a new Onyx Boox Note 3 Color, but (i) the colors are somewhat dull (less critical), (ii) there is some color memory that bleeds through when changing pages (= need for frequent refreshing), (iii) (even worse) the coloring layer makes the screen somewhat too dark to read without back lighting, which “kills” the battery life, and (ii) only 7.8" screen at the moment.

Sony will come with a 10.3" (?) note taking e-ink color reader soon, based on Android 9 (I think). But that most likely suffers the same problems as the Onyx color e-ink.

Supposedly, Chinese TV maker TCL will come with an 8.88" reader based on new technology, TCL NXTPaper in April (isn’t “8” a lucky number in the Chinese culture?). It will be based on Android 10, and has much better screen update than e-ink. But most likely shorter battery life.

Regarding size: printed science books typically have a text field of ca. 10", so to view such books in the “natural size” would require a 10" reader. If note taking is the primary use (not for me), then a 13+" pad would be better. For reading other books (e.g., I read the Decameron last year on the Kindle), smaller size than 10" would probably be ideal.

As several have mentioned, some of the formats allow for re-flowing of the text based on magnification, so perhaps the size is not super important. [Many Youtubers discuss such e-readers. E.g., “my deep guide” is very up-to-date, and provide tutorials on setting up and using various readers.]