# \[ANN\] DocumenterEpub.jl

**URL:** <https://discourse.julialang.org/t/ann-documenterepub-jl/53435>\
**Category:** Package Announcements\
**Tags:** epub\
**Created:** [January 16, 2021, 3:57pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435 "2021-01-16T15:57:10Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![laborg](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/laborg/32/5474_2.png) [@laborg](https://discourse.julialang.org/u/laborg)\
**Post date:** [January 16, 2021, 3:57pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/1 "2021-01-16T15:57:10Z")

</div>

Hi,

I’m releasing 0.1.0 of [DocumenterEpub.jl](https://github.com/laborg/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](https://github.com/cormullion/juliamono) for syntax highlighting
- No JavaScript dependency in the resulting EPUB through
  - prerendering of syntax highlighting for code listings using Highlight.js, including the work of Fredrik Ekre (see the blog post: [Improved syntax highlighting for Julia on the web | Fredrik Ekre](https://fredrikekre.se/posts/highlight-julia/))
  - prerendering of LaTeX math/formulas into SVG

* * *

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:

- Julia Manual 1.5.3: [https://github.com/laborg/DocumenterEpubExample/blob/master/TheJuliaLanguage-1.5.3.epub](https://github.com/laborg/DocumenterEpubExample/blob/master/TheJuliaLanguage-1.5.3.epub)

---

<div class="post-metadata">

**Author:** ![jebej](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jebej/32/1784_2.png) [@jebej](https://discourse.julialang.org/u/jebej)\
**Post date:** [January 16, 2021, 4:15pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/2 "2021-01-16T16:15:43Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![laborg](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/laborg/32/5474_2.png) [@laborg](https://discourse.julialang.org/u/laborg)\
**Post date:** [January 16, 2021, 5:06pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/3 "2021-01-16T17:06:41Z")

</div>

Sure! I’ve updated the first post.

---

<div class="post-metadata">

**Author:** ![cormullion](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cormullion/32/49131_2.png) [@cormullion](https://discourse.julialang.org/u/cormullion)\
**Post date:** [January 16, 2021, 5:42pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/4 "2021-01-16T17:42:36Z")

</div>

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

 ![Screenshot 2021-01-16 at 17.37.16](https://global.discourse-cdn.com/julialang/original/3X/e/e/eeaf710a2ad3f18d4570358bb97b0624a5176160.jpeg)

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

---

<div class="post-metadata">

**Author:** ![tlienart](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tlienart/32/7640_2.png) [@tlienart](https://discourse.julialang.org/u/tlienart)\
**Post date:** [January 16, 2021, 10:02pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/5 "2021-01-16T22:02:12Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [January 16, 2021, 10:32pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/6 "2021-01-16T22:32:55Z")

</div>

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?)

---

<div class="post-metadata">

**Author:** ![logankilpatrick](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/logankilpatrick/32/38123_2.png) [@logankilpatrick](https://discourse.julialang.org/u/logankilpatrick)\
**Post date:** [January 17, 2021, 4:42am UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/7 "2021-01-17T04:42:43Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [January 17, 2021, 5:13am UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/8 "2021-01-17T05:13:20Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![dpsanders](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dpsanders/32/3573_2.png) [@dpsanders](https://discourse.julialang.org/u/dpsanders)\
**Post date:** [January 17, 2021, 5:16am UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/9 "2021-01-17T05:16:50Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![laborg](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/laborg/32/5474_2.png) [@laborg](https://discourse.julialang.org/u/laborg)\
**Post date:** [January 17, 2021, 6:31am UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/10 "2021-01-17T06:31:11Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![rafael.guerra](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/rafael.guerra/32/216610_2.png) [@rafael.guerra](https://discourse.julialang.org/u/rafael.guerra)\
**Post date:** [January 17, 2021, 8:39am UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/11 "2021-01-17T08:39:18Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![laborg](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/laborg/32/5474_2.png) [@laborg](https://discourse.julialang.org/u/laborg)\
**Post date:** [January 17, 2021, 2:38pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/12 "2021-01-17T14:38:06Z")

</div>

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](https://github.com/laborg/DocumenterEpubExample/blob/master/The_Julia_Language_color_mac.epub)

Best regards,

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [January 17, 2021, 4:31pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/13 "2021-01-17T16:31:51Z")

</div>

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

 ![image](https://global.discourse-cdn.com/julialang/original/3X/b/3/b36213bb13486cf8cc259641b9ff25a6492f66d6.png)  
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!

---

<div class="post-metadata">

**Author:** ![cormullion](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/cormullion/32/49131_2.png) [@cormullion](https://discourse.julialang.org/u/cormullion)\
**Post date:** [January 17, 2021, 6:06pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/14 "2021-01-17T18:06:21Z")

</div>

This version doesn’t appear to be any different…

 ![image](https://global.discourse-cdn.com/julialang/original/3X/8/a/8ae3eeedffb34e752afcbb061bc8987391cb0a44.jpeg)

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [January 17, 2021, 6:24pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/15 "2021-01-17T18:24:48Z")

</div>

This very same file with Calibre on Windows:

 ![image](https://global.discourse-cdn.com/julialang/original/3X/f/1/f18084bd72d0b11874dbcc8a4ee6df1ca330c98f.png)  
The number strings are typeset correctly.

---

<div class="post-metadata">

**Author:** ![js135005](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/js135005/32/8219_2.png) [@js135005](https://discourse.julialang.org/u/js135005)\
**Post date:** [January 17, 2021, 6:47pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/16 "2021-01-17T18:47:06Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![dmolina](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dmolina/32/5246_2.png) [@dmolina](https://discourse.julialang.org/u/dmolina)\
**Post date:** [January 17, 2021, 8:12pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/17 "2021-01-17T20:12:54Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![laborg](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/laborg/32/5474_2.png) [@laborg](https://discourse.julialang.org/u/laborg)\
**Post date:** [January 20, 2021, 11:43am UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/18 "2021-01-20T11:43:08Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![laborg](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/laborg/32/5474_2.png) [@laborg](https://discourse.julialang.org/u/laborg)\
**Post date:** [March 26, 2021, 12:51pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/19 "2021-03-26T12:51:03Z")

</div>

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](https://github.com/laborg/DocumenterEpubExample/blob/master/TheJuliaLanguage-1.6.0.epub)

---

<div class="post-metadata">

**Author:** ![BLI](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/bli/32/37206_2.png) [@BLI](https://discourse.julialang.org/u/BLI)\
**Post date:** [March 26, 2021, 1:18pm UTC](https://discourse.julialang.org/t/ann-documenterepub-jl/53435/20 "2021-03-26T13:18:01Z")

</div>

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

[Next page](https://discourse.julialang.org/t/ann-documenterepub-jl/53435.md?page=2)