epub Plugin

epub is a plugin that will create EBooks from Dokuwiki pages that can be read in standard ebook readers. See ebook_readers below.

EPUB is an open specification for digital books based on XML, CSS, and XHTML, and EPUB files can be read on portable e-ink devices, mobile phones, and desktop computers. The specification is overseen by the International Digital Publishing Forum.

Unlike pdf files which have a standardized output, epub output is e-reader dependent, much like web pages, to which they are directly related. An epub page is XHTML with CSS styling. Ebooks can be collected in an e-reader's library of e-books and consulted off-line, making them always available.

There is a PHP 8 compatible version here: https://github.com/Jack28/epub/ . To install clone the repository into lib/plugins directory.

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

The version of the epub plugin available from the Download button above is not compatible with Dokuwiki distributions prior to Angua. For earlier distributions of Dokuwiki, you must substitute for epub/script.js the alternate script.js. which is found in the epub/scripts directory. The pre-angua scipt.js uses the javascript sack class for making ajax requests, and angua (and later) uses jQuery.

The plugin has recently been upgraded to conform to epub naming conventions, which does not allow @ signs in ids. The most recent distributions substitute underscores for the earlier @ signs. Should this cause any problems, you can revert to the earlier version: turnermm-epub-b111076.tar.gz. If this occurs, please report an error.

The epub plugin keeps a link on the page where the ebook has been created. This link is updated every time the book is updated. ACL rules apply. So, for this to work, users and/or visitors must have read access to the page. See below configuration and settings. There is an administration panel where the administrator can prune the cache that keeps track of these links and the pages on which they appear, as well as enabling the admin to delete epubs no longer in use when entries are deleted from the cache. While deletions from the cache can be done on a page-by-page basis using the Remove button (see configuration and settings), the admin panel provides a systematic view of the status of the epubs on your system.

There is also a configuration option which allows for hiding the link. This version also has the capacity to delete the working directories in data/cache, where the epubs are created; this facility is controlled also by a configuration option.

eBooks are zip files with the '.epub' extension. So, in order to create ebooks the plugin will have to be able to create zip files. The epub plugin will first look for the PHP ZipArchive class; if it doesn't find it, on Linux systems, it will try to use the command line zip utility. This is not found on Windows systems. The ZipArchive class can usually be downloaded as a .dll and easily installed on Windows by updating the extensions assignments in php.ini. It can also be installed on *nix systems using a package manager like yum or apt-get or directly from a GUI software installer. But my experience has been that the PHP version has to be 5.2 and above.

If epub does not find either the ZipArchive class or a working copy of the zip utility, it will use Dokuwiki's own ZipLib class.

Open a page in the namespace named “epub”. Then create a list of pages as follows, in the order in which you want them to appear. The page names can be inserted using the link wizard on the Dokuwiki toolbar (these are in the square brackets).

<epub:Book-1>
 introduction
 v06
 features
 [[index:site_inx|index]]
 media
[[:configuration|]]
 docs:upgrade_6
</epub>

Book-1 is the title of the ebook. It is the name that the book will be known by in ebook readers. There is also an author, whose name is taken from the user's actual name as it was entered upon the user's registration.

When the page is saved a Start button will appear on the page. When it's clicked a throbber comes up, which will disappear when the book is complete. It will be replaced by a status report and a link to the newly created ebook. The Start button should always be active until the page used for creating the ebook is removed from the list of these pages (see below).¹⁾

The book will be saved to the media directory in a sub-folder named epub/<user_name>. You should create the epub directory yourself, in advance, and give ebook creators upload permission to the epub namespace (See below).

The name of the new book will be based on the date and time. For instance: 2012_march_7_07-58-49.epub. This makes it possible to recreate a book without accidentally over-writing a prior copy. The status report tells you the name of the newly created book. In other words, you can feel free to edit your page list and the contents of the pages themselves, without fear of losing a previous version of the ebook.

The scratch directory for the book is in meta/epub/username/ in an md5 subdirectory which is created for each new ebook instance (i.e. each time you click the Start button). For instance:

meta/epub/jack/f7a146947dc9dd5e8c42d22c12c33ec9   

A lot of files can accumulate here, which the plugin will attempt to delete. However, you might want to check and if necessary clean them out manually.

eBooks generally have a 'cover' page. Depending on the ebook reader, this may be displayed as the first page of the book, or in a sidebar, or both. The epub plugin comes with a default cover page which consists simply of the title 'Dokuwiki Ebook'and the Dokuwiki logo image. You can, however, create your own cover from within Dokuwiki. Name the cover page title and place it first in the list of pages to be processed. The cover must have one image, and one image only, and this image must be named cover.png.

Both the cover page and the cover page image can be included in a namespace, so that namespace:title and namespace:cover.png are both acceptable. This makes it possible to have different title pages for different projects and users.

While you can include text in the cover page, not all ebook readers display the text. So, you might consider putting all that you want to say in cover.png.

The epub plugin distinguishes between links to external resources and internal links to pages included in the ebook. Links to pages included in the ebook appear in the text and can be used to navigate between pages. Most ebook readers will have a back button, like a browser, making it possible to return to the page where the link appeared.

The plugin also supports internal links that link to headers, as in this DokuWiki markup:

[[page_id#header_text|]]

The header text must conform to Dokuwiki's protocol for Page Names. If in doubt, you can check the table of contents for the page, where you will find the correct name for the header_text.

The epub plugin lists references to external resources on an end-note page. For convenience, the end notes are referenced by active footnote numbers. Clicking on a footnote number takes you to the end notes and clicking on an end-note number returns you to the place on your page. For instance, your page might have this note:

You can find out more about plugins on Dokuwiki [7] 

Clicking on [7] takes you to the end notes where you might find:

[7] https://www.dokuwiki.org/plugins

Clicking on the end-note number will return you to the original page and place on the page. Clicking on https://www.dokuwiki.org/plugins will take you to plugins on Dokuwiki.org in your default browser.

The epub plugin supports a list that consists of an optional title page and a namespace. The namespace is indicated using an asterisk and it must be the first item in the list of pages:

:namespace:* 

The initial colon is recommended.

The complete syntax, including the optional title page, is as follows:

<epub:Book_name>
:namespace:*
:namespace:title   
:page_id
:other_page_id
</epub>

Currently only one namespace is supported. Moreover, only the topmost namespace directory is processed; so, if you have :namespace_1:namespace_2, only namespace_1 is processed. These limitations may be addressed after some testing and use. If you omit the title page, a default title page will be inserted.

After the namespace setting, you can add additional page ids. A page id can consist of any standard DokuЦiki page identifier, for instance namespace:page or namespace_1:namespace_2:page.

For chapter headings, you must use the Dokuwiki internal link markup and a chapter heading is created from the link text:

<epub:Book_name>
[[namespace:page|Chapter 1]]    
[[namespace:page|Chapter 2]]    
</epub> 

If you omit the link text, then a Chapter heading will be created from the page id, using both the namespace and the page name.

If you use the namespace technique described above, the plugin will create Chapter headings from the page names, without the namespace. This is analogous to the way in which Dokuwiki implements its trace feature.

The epub plugin will import external images into the ebook, which differs from the way in which the plugin handles other external resources as described in the Links section above. For this to work, you must have a PHP installation which allows external resources to be accessed. This facility is enabled in php.ini by setting

allow_url_fopen = on

Or

allow_url_fopen = 1

With the release of Binky, Dokuwiki uses the LESS CSS compiler for CSS which requires it. The latest epub release supports the LESS compiler as implemented by Dokuwiki. If for any reason you do not wish to use LESS, you can turn it off using the Configuration Settings.

The epub plugin supports audio files. It has so far been tested only with .mp3, mimetype: audio/mpeg. By default, the plugin includes the name of the audio file and a footnote link to the file, making it possible to download the mpeg file, if it is publicly available. This behavior can be turned off in the configuration options. The display text of the footnotes acts as a title and is placed beneath the audio controls. This title can be controlled by adding link names to the link markup:

 {{ mpeg:mpeg_file | display text }}
 {{ audio:mpeg_file | display text }}

For this to work correctly the audio file must be in a namespace set with the audio_fn configuration option, which defaults to audio,mpeg. This assures that the footnote's link to the audio file will be correct. The namespace can be up to two levels deep, e.g audio:mp3. When this link is clicked, the audio file will open in the default browser and, if supported, will play.

For illustrations see the discussion on github: https://github.com/turnermm/epub/issues/23. There is also a small sample audio file of three Shakespeare sonnets at that location.

The latest distributions of epub include support for mp4 video. The description above of audio_files also applies to video files. In this case, video_fn must be set to true. The namespaces where video files will be found must be set in video_nmsp, which defaults to video,mpeg.

1. Create a namespace named epub and set its ACL at 0. This namespace should be kept exclusively for creating ebooks. Then give upload permission to the epub namespace to those users who will be creating ebooks. This setup has two effects:

1. With this setup, only users with upload permission to the epub namespace can create ebooks.
2. The Start button will appear only on pages in the epub namespace.

A download link is written to the page from which the ebook has been created. This enables users with access to the page to download the book directly from that page. In this case you might want to give people read access to the page and use method number 2 below for your security.

2. Assign ebook creators to the ebook creator group.
The default group name is epub, which can be changed in the Configuration Manager. If a user belongs to this group, then the user does not need upload permission for the epub namespace. The book may then be created in a sub-directory of the epub namespace, i.e. it must still exist in the epub namespace hierarchy.

3. The user must have create permission for pages on which the ebook is created. While this may seem self-evident, it is also a further safety check, because it means that users without create permission for an epub page cannot re-create an ebook from the data on that page, even if they might otherwise have access to the page.

The plugin keeps a list of pages which have created ebooks. This prevents the plugin from placing a Start button on all pages in the epub namespace, regardless of whether they contain epub syntax. If you wish to use an epub page for some other purpose, you can remove its name from the list using a second button which appears beneath the Start button and has the following label: Remove Page from Creator List.

There are three language files in epub/lang/en. You can make your own translations and place them in

epub/lang/<your_iso_language_code>

To upload epub files to Dokuwiki, you will have to enter its mime type in conf/mime.local.conf:

epub application/epub+zip

If you don't have a mime.local.conf, you can create it.

1. The first ACL control is the permission to upload to the epub namespace (see above)
2. Secondly, users can only add page id's to an epub if they have read permission for that page. If a user does not have read permission, the page will be ignored.

But “ignored” is not an iron-clad guarantee of security, because Dokuwiki will have cached the page. To be completely secure you should remove your page from the list of epub ids by clicking the Remove button. This forces a new user to make changes to the page in order to re-activate the Start button, at which point the page will be re-processed and its list of included id's will be re-checked for ACL permissions.

As noted above, the epub plugin places all new ebooks in a namespace created from the user's name:

epub:user

It might be useful to give your ebook creators delete permission to their own epub namespaces. This will give them complete control over the books they have created.

You can create an enhanced table of contents as follows:

• Load your epub into Sigil, click on Tools→Table of Contents→Generate Table of Contents. You could probably make your book a bit smaller by loading it into the Calibre editor and removing unused CSS. Ignore any messages about CSS issues. These are non-critical problems in Dokuwiki itself.
• Save your book

epub renders a wide range of syntax plugins, as long as they attach their output to the current page renderer. Exceptions to this rule are several plugins which attach output to the the page using javascript: ditaa, mathpublish, and mathjax. For these, the epub reader must support inclusion of javascript files downloaded from the Internet. The reliability of the mathjax inclusions may be limited, so testing is required.

If you find syntax plugins which do not work in epub, please post them to the forum.

epub does not support action plugins, that is, if you are using an action plugin which inserts text into the output stream, these insertions will not be captured by epub.

epub supports the imagemapping plugin and will probably support any plugin which creates standard image maps. You can also create an image map directly: for a How-To see: https://github.com/turnermm/epub/issues/30.

All of the following are free downloads.

• Calibre
  This is an excellent ebook reader. The latest version has the capability to pop-up tables and zoom in on them when you right-click on a table. Tested on Windows and Linux. It is open source.
  See: http://calibre-ebook.com/
• EPUBReader
  This is a Firefox add-on and seems to handle whatever you can throw at it. It probably has the advantage of being hooked into Firefox and gets HTML support from there. An advantage to installing this plugin, if you use Firefox,is that you can click on the link to your ebook and immediately see the result.
• FBreader
  Good but does not produce tables, instead converting them to long columns of one-liners for each cell. (Open source)
  See: http://www.fbreader.org/
• Adobe Digital Editions
  This is an excellent reader which has been dramatically improved over the past year.
  The current version is 2.x: http://www.adobe.com/ca/products/digital-editions/download.html
• Readium
  This is an extension for Chrome and it is also a very good reader. See: https://readium.org/

A sample of an ebook created by epub can be downloaded here: Sample E-book.

• fixed php 8 curly brace error in helper.php (2022-10-05 16:44)
• Updates version (2022-09-14 04:52)
• fixed renderer::header to compatibilitgy with Igor (2022-08-05 22:50)
• translation update (#35) (2022-08-05 21:42)
• Merge branch 'master' of github.com:turnermm/epub (2022-03-30 20:43)
• updates version (2022-03-30 20:42)
• updated create_function to function() in ebook.php for php 8.0 compat… (2022-03-30 20:39)
• Is countable (#32) (2021-02-01 22:30)
• updates plugin.info.txt (2019-09-12 00:17)
• Some streamlining of css for better validation (2019-09-12 00:15)
• update plugin.info.text (2019-09-10 17:03)
• Imap (#31) (2019-09-10 16:52)
• deleted zip.php (2019-05-09 15:54)
• Merge pull request #26 from dokuwiki-translate/lang_update_1022_15405… (2018-10-26 17:37)
• translation update (2018-10-26 04:25)

For a complete listing of changes see: https://github.com/turnermm/epub/commits/master. First commit March 3, 2012.

Please ask your questions on the forum or on the GitHub issues linked to under bugs above. Thanks.

Old discussion pages are retained here but are no longer used.

Discussions have been moved to a separate page: epub:discussions.