ReSpec to EPUB
Typescript program to convert W3C documents, produced by ReSpec, to EPUB 3.3.
Single documents vs. Collections
The conversion can:
- Convert a single HTML source that was produced by ReSpec.
- Convert a single HTML source that must be pre-processed by ReSpec to get its final formats; the program pre-processes the source on the fly.
- Convert and combine a “collection“ of HTML sources (to be pre-processed or not) into a single EPUB 3 instance.
(The on-the-fly conversion via ReSpec is done by running the W3C’s Spec Generator service. Alas!, that service may be down or slow, and this package has no control over that…)
Command line usage
There is a simple command line interface to run the script. See the the separate documentation on cli for details and examples.
Run a service via HTTP
There is also the possibility to start a simple server to generate EPUB 3.3 instances on request. See the separate documentation on the server for details and examples of HTTP requests.
The server has been deployed on the cloud at heroku using the
https://r2epub.herokuapp.com/ URL, as well at W3C using the
https://labs.w3.org/r2epub URL. A browser interface to drive this server is also available.
(Note that the server running on W3C is used to generate an EPUB version of a document based on respec, using its
Use as a typescript/node package through an API
The implementation is in Typescript and on top of
node.js. The documentation is also available on-line.
npm approach applies:
git clone https://github.com/iherman/r2epub.git cd r2epub npm install
or simply use
npm install r2epub
to get to the latest, published version.
The repository contains both the typescript code (in the
dist directory). If, for some reasons, the latter is not in the repository or is not up to date, the
npm run build
command takes care of that. The documentation can also be generated locally through the
npm run docs
R2EPUB_PORT: the port number used by the server; failing these the default (i.e., 80) is used. (
PORTtakes precedence over
R2EPUB_LOCAL: no URL-s on
localhostare accepted, unless this environment variable set (the value of the variable is not relevant, only the setting is). For security reasons this variable should not be set for deployed servers.
R2EPUB_MODIFIED_EPUB_FILES: A number of W3C specific files (logos, some css files) had to be adapted for EPUB 3 usage, and are retrieved from a separate site. At the moment,
https://www.ivan-herman.net/r2epub/is used as a base URL for those files. However, if the variable is set, its value is used as a prefix for the copy of the files on the local file system and the files are read directly from the disc. (Typically, the value points at
docs/epub_assets/in the local clone of the distribution.)
(Some server may have problems with a burst of access to the same base URL resulting in run-time error, hence the advantage to use this local alternative to setup.)
Once installed locally, follow specific instructions based on your needs/interest below:
starts the command line interface.
starts up the server locally.