Service and ReSpec interface to generate EPUB 3 from a spec

I have set up a service at:

https://labs.w3.org/epub-generator/

to generate an EPUB 3[1] version of some of the TR documents. To be more precise, the service can accept three types of input:

- a TR document (including Editors' drafts) generated from ReSpec
- a TR document generated from Bikeshed (this will probably need more tests, though)
- an HTML document that is written using ReSpec

(In the last case the service will transform the source into HTML on-the-fly using the spec generator service[2]). The GET API is documented on the page[1]. Furthermore, an additional entry has been added to the popup used in ReSpec to save, eg, the content into an HTML or XHTML file. That popup will simple call out to the service above using the third option.

The tool can be used to produce an alternate version of the TR document (e.g., replacing the alternate PDF versions that was/is used time to time). The resulting EPUB 3 can be read on tablets with eReaders (e.g., iPad with iBooks, BlueFire, Google Play, etc); there are extensions to Chrome and Firefox and the newer Mac (starting from Mavericks) has an iBook reader, too. There are also other readers around[3].

The project is on github[4], and has been written in Python. Actually, the repo also includes a command line utility that can be used in a terminal window. However, even for a local file the content has to be accessed through a URL (at least at the moment, I plan try to add a direct file access.)

One caveat: the service works with a one single file per document model. It does not really work if the spec consists of several pages (e.g., the HTML5 spec). I do have an older project[5] that does that, but that one needs some overhaul, and has not been integrated to ReSpec. Maybe later, if there is a real demand for it...

There are, unfortunately, discrepancies and inconsistencies among EPUB readers, and their implementations is not always complete (not unlike Web browsers, but the discrepancies seem to be a bit bigger, still:-(. The program behind the service tries to handle some of the issues I hit by slightly modifying, if necessary, the DOM of the HTML; I am sure that there are more problems around. Feedbacks are welcome on the project's repo[6].

The script also adds a separate "book.css" to the output, that includes some pagination-oriented CSS statements. I reproduce the relevant CSS statements below for info: it essentially tries to keep standard examples and IDL on one page, if that is possible (and if the reader/browser does a proper job). If you use some other blocks that you want to keep on a page, it is a good idea to add similar CSS statements in your own document.

As I said, I am sure there are errors, problems, feature requests; please use the issue list[6]…

Thanks

Ivan

[1] http://idpf.org/epub/30
[2] https://labs.w3.org/spec-generator/
[3] https://en.wikipedia.org/wiki/EPUB#Software_reading_systems
[4] https://github.com/iherman/respec2epub/
[5] https://github.com/iherman/tr2epub
[5] https://github.com/iherman/respec2epub/issues


----
Ivan Herman, W3C
Digital Publishing Lead
Home: http://www.w3.org/People/Ivan/
mobile: +31-641044153
ORCID ID: http://orcid.org/0000-0003-0782-2704


P.S. Here is what is added to the output CSS:


  h2 {
    page-break-before: always;
    page-break-inside: avoid;
    page-break-after: avoid;
  }
  div.head h2 {
    page-break-before: auto;
    page-break-inside: avoid;
    page-break-after: avoid;
  }
  h3, h4, h5 {
    page-break-after: avoid;
  }
  dl dt {
    page-break-after: avoid;
  }
  dl dd {
    page-break-before: avoid;
  }
  div.example, div.note, pre.idl, .warning, table.parameters, table.exceptions {
    page-break-inside: avoid;
  }
  p {
    orphans: 4;
    widows: 2;
  }