Skip to content

Bib 13 sprint

Jump to bottom
Kathi Fletcher edited this page Nov 4, 2013 · 9 revisions

After the Books in Browswers conference (October 2013), Swissnex hosted a hackday for interested participants. OERPUB, Connexions, EPUBjs, Hypothes.is, and MathJax collaborated to get github-bookeditor books viewable and annotatable.

Demos

  • github-bookeditor book viewed with epub.js : Books edited with Github-bookeditor are stored on github in EPUB3 format. They can be viewed on github directly, by going directly to the repo for the book on github. With this demo, an ebook is displayed with epub.js.

  • local copy of mathjax : Github-bookeditor uses a CDN version of MathJax. Using a local copy instead, however, would mean that loading the editor would be faster, because just the parts of MathJax needed by the editor could be downloaded. There are also benefits for developers in reducing the number of code dependencies. Peter Krautzberger, from MathJax, worked with a fork of the editor to make a local copy possible.

epub.js

The demo above is done by including an index.html file in the demo book on the gh-pages branch of the book in github. There is also a local copy of epub.js in a directory on that branch of the book. That local copy was for convenience so that it could be loaded from the book. Ideally this should be pulled from a cdn of a stable release of epub.js.

The epub is viewed from the gh-pages branch, so that github's webserver will serve the book. That means that book repos should have gh-pages as their default branch.

epubjs-reader

epubjs-reader would be a much better reader to use with github books, because of its integration with hypothes.is annotations. It has support for changing the URL as you move through the book, which is needed for properly relocating annotations in the book. The week after the sprint, Phil Schatz got a demo working that uses epubjs-reader. Annotations come up automatically, and you can even edit the book and have the annotations stay around (as long as Hypothes.is can still find the right spot in the book using its fuzzy matching).

The demo above is done by including an /reader/index.html file in the demo book on the gh-pages branch of the book in github. There is also a local copy of /reader in a directory on that branch of the book. That local copy was for convenience so that it could be loaded from the book. Ideally this should be pulled from a cdn of a stable release of epub.js. We also ended up needing to make a change to force reload on the books.

Some things that are still missing or awkward

  • In reader/scripts/directives/epub-viewer.js, we had to change the line opening the book to force a reload, because the book is being stored in browser local storage, and it is just keeping the main part of the URL with the domain name, and not the repo name. Line 99 changed to + var opened = book.open(attrs.src, true); // true == forceReload
  • links in the TOC and content don't work (might be a content problem)
  • The TOC ordering is weird. I think it might be coming from the spine rather than the nav html file.
  • math won't work (need to include mathjax)
  • the url is just the oerpub.github.io domain plus the CFI fragment, so you can't reload in the browser. The paths should be written so that reload works. That way you can send a link to a specific spot in the book.
  • The reader redisplays a lot while trying to annotate on firefox. It is hard to get the annotation attached.

Hypothes.is Annotation

Hypothes.is annotation is built into epubjs-reader. So annotations work and persist with the books in the demos above!

Future work

Handling multiple books inside a single repo

EPUB3 allows multiple books in a container. We are using that so that authors can work on a set of books at once, or copy materials from one book to another, or share materials between books. But the reader displays only the first book.

Making annotations work in the editor directly.

To make annotations work in the editor, hypothes.is needs to handle URL's with # in them of the form, oerpub.github.io/github-bookeditor/#repo/oerpub/demo-book/<book-part>. Otherwise the annotations aren't going to persist properly in the editor.

Coordinating annotations on the book view and the editor view.

Since annotations can happen in the editor and in the reader, it would be really interesting to coordinate between the two. They are really both operating on similar structure, but the URLs look very different, because reader uses CFI's (EPUB3 content fragment identifiers) and the editor uses a structure like /content/<content-part>.html|<book>.opf

Mathjax

TBD

Discussions

TBD

W3C

TBD

IDPF and Readium

TBD

Participants

  • Phil Schatz (philschatz), Connexions and OERPUB
  • Peter Krautzberger (pkra), MathJax
  • Jake Hartnell (RawKStar77), epub.js
  • Fred Jacksier-Chasen (fchasen), epub.js
  • AJ Reynold (AJRenold), epub.js
  • Randall Leeds (tilgovi), Hypothes.is
  • Kathi Fletcher (kathi-fletcher), OERPUB
Clone this wiki locally