plugin:epub
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revision | |||
plugin:epub [2024-02-26 10:29] – old revision restored (2023-03-04 15:44) Aleksandr | plugin:epub [2024-02-26 10:33] (current) – Aleksandr | ||
---|---|---|---|
Line 21: | Line 21: | ||
---- | ---- | ||
- | ====== Intro ====== | + | ===== Intro ===== |
epub is a plugin that will create EBooks from Dokuwiki pages that can be read in standard ebook readers. See [[# | epub is a plugin that will create EBooks from Dokuwiki pages that can be read in standard ebook readers. See [[# | ||
Line 27: | Line 27: | ||
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 [[http:// | 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 [[http:// | ||
- | Unlike pdf files which have a standardized output, epub output is e-reader dependent, much like web pages, to which they are directly related. | + | 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' |
Line 34: | Line 34: | ||
Search and install the plugin using the [[plugin: | Search and install the plugin using the [[plugin: | ||
- | 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/ | + | 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/ |
- | The plugin has recently been upgraded to conform to epub naming conventions, | + | The plugin has recently been upgraded to conform to epub naming conventions, |
==== Download Links ==== | ==== Download Links ==== | ||
- | The epub plugin keeps a link on the page where the ebook has been created. | + | 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 [[# |
- | 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. | + | 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. |
==== System Requirements ==== | ==== System Requirements ==== | ||
- | eBooks are zip files with the ' | + | eBooks are zip files with the ' |
If epub does not find either the ZipArchive class or a working copy of the zip utility, it will use Dokuwiki' | If epub does not find either the ZipArchive class or a working copy of the zip utility, it will use Dokuwiki' | ||
Line 56: | Line 56: | ||
===== Syntax ===== | ===== Syntax ===== | ||
- | Open a page in the namespace named " | + | Open a page in the namespace named " |
< | < | ||
Line 70: | Line 70: | ||
</ | </ | ||
- | Book-1 is the title of the ebook. It is the name that the book will be known by in ebook readers. | + | 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. | + | 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 [[# |
- | The book will be saved to the media directory in a sub-folder named **epub/< | + | The book will be saved to the media directory in a sub-folder named **epub/< |
- | The name of the new book will be based on the date and time. For instance: ** 2012_march_7_07-58-49.epub**. | + | 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/ | The scratch directory for the book is in meta/ | ||
meta/ | meta/ | ||
- | A lot of files can accumulate here, which the plugin will attempt to delete. | + | 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. |
==== Cover Page ==== | ==== Cover Page ==== | ||
- | eBooks generally have a ' | + | eBooks generally have a ' |
- | Both the cover page and the cover page image can be included in a namespace, so that **namespace: | + | Both the cover page and the cover page image can be included in a namespace, so that **namespace: |
- | 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**. | + | 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**. |
Line 95: | Line 95: | ||
=== Internal Links === | === Internal Links === | ||
- | The epub plugin distinguishes between links to external resources and internal links to pages included in the ebook. | + | 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: | The plugin also supports internal links that link to headers, as in this DokuWiki markup: | ||
- | [[page_id# | + | |
- | The header text must conform to Dokuwiki' | + | |
+ | |||
+ | The header text must conform to Dokuwiki' | ||
=== End Notes === | === End Notes === | ||
- | The epub plugin lists references to external resources on an end-note page. For convenience, | + | The epub plugin lists references to external resources on an end-note page. For convenience, |
You can find out more about plugins on Dokuwiki [7] | You can find out more about plugins on Dokuwiki [7] | ||
Clicking on [7] takes you to the end notes where you might find: | Clicking on [7] takes you to the end notes where you might find: | ||
Line 111: | Line 113: | ||
==== Namespaces ==== | ==== Namespaces ==== | ||
- | The epub plugin supports a list that consists of an optional title page and a namespace. | + | |
+ | 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: | ||
: | : | ||
The initial colon is recommended. | The initial colon is recommended. | ||
Line 123: | Line 126: | ||
</ | </ | ||
- | Currently only one namespace is supported. | + | Currently only one namespace is supported. Moreover, only the topmost namespace directory is processed; so, if you have '': |
- | After the namespace setting, you can add additional page ids. A page id can consist of any standard DokuЦiki page identifier, for instance '' | + | After the namespace setting, you can add additional page ids. A page id can consist of any standard DokuЦiki page identifier, for instance '' |
=== Chapter Headings === | === Chapter Headings === | ||
Line 136: | Line 139: | ||
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 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 [[# | + | If you use the [[# |
=== External Images === | === External Images === | ||
- | 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. | + | 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 | allow_url_fopen = on | ||
Or | Or | ||
allow_url_fopen = 1 | allow_url_fopen = 1 | ||
+ | |||
=== CSS Processing === | === CSS Processing === | ||
- | 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. | + | 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 '' |
==== Audio Files ==== | ==== Audio Files ==== | ||
- | The epub plugin supports audio files. It has so far been tested only with '' | + | |
+ | The epub plugin supports audio files. It has so far been tested only with '' | ||
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: | 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: | ||
{{ audio: | {{ audio: | ||
- | For this to work correctly the audio file must be in a namespace set with the '' | + | For this to work correctly the audio file must be in a namespace set with the '' |
+ | |||
+ | For illustrations see the discussion on github: https:// | ||
- | For illustrations see the discussion on github: https:// | ||
==== Video Files ==== | ==== Video Files ==== | ||
- | The latest distributions of '' | + | |
+ | The latest distributions of '' | ||
===== Configuration and Settings ===== | ===== Configuration and Settings ===== | ||
Line 163: | Line 171: | ||
^ Name ^ Description | ^ Name ^ Description | ||
- | | group | Name of group which has permission to create ebooks. | + | | group | Name of group which has permission to create ebooks. This setting is optional and has effect only where a user does not have upload permission to the epub namespace. |
- | | rmdir | Remove scratch directory after the ebook has been created. | + | | rmdir | Remove scratch directory after the ebook has been created. |
| permalink | | permalink | ||
- | | less | The LESS CSS compiler will be used if present, unless this option is set to false. | + | | less | The LESS CSS compiler will be used if present, unless this option is set to false. |
- | | compress | + | | compress |
| sort | Pages processed using the namespace markup will appear in alphabetical order, unless this option is set to false (unchecked) | | sort | Pages processed using the namespace markup will appear in alphabetical order, unless this option is set to false (unchecked) | ||
- | | audio_fn | + | | audio_fn |
- | | audio_nmsp | + | | audio_nmsp |
| video_fn | | video_fn | ||
- | | video_nmsp | + | | video_nmsp |
==== How to use the above Options ==== | ==== How to use the above Options ==== | ||
- | 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. 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: |
- With this setup, only users with upload permission to the **epub** namespace can create ebooks. | - With this setup, only users with upload permission to the **epub** namespace can create ebooks. | ||
- The Start button will appear only on pages in the **epub** namespace. | - 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. | + | 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. \\ | 2. Assign ebook creators to the ebook creator group. \\ | ||
- | The default group name is '' | + | The default group name is '' |
- | 3. The user must have create permission for pages on which the ebook is created. | + | 3. The user must have create permission for pages on which the ebook is created. While this may seem self-evident, |
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**. | 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**. | ||
Line 192: | Line 200: | ||
==== Uploading epub files ==== | ==== Uploading epub files ==== | ||
+ | |||
To upload epub files to Dokuwiki, you will have to enter its mime type in conf/ | To upload epub files to Dokuwiki, you will have to enter its mime type in conf/ | ||
epub application/ | epub application/ | ||
Line 197: | Line 206: | ||
==== ACL ==== | ==== ACL ==== | ||
+ | |||
- The first ACL control is the permission to upload to the epub namespace (see above) | - The first ACL control is the permission to upload to the epub namespace (see above) | ||
- | - 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 '' | + | - 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 '' |
- | But " | + | But " |
As noted [[# | As noted [[# | ||
epub:user | epub:user | ||
- | It might be useful to give your ebook creators delete permission to their own epub namespaces. | + | 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. |
==== Enhanced Table of Contents ==== | ==== Enhanced Table of Contents ==== | ||
+ | |||
You can create an enhanced table of contents as follows: | 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. | * 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. | ||
Line 212: | Line 224: | ||
===== Plugin Support ===== | ===== Plugin Support ===== | ||
- | '' | + | '' |
If you find syntax plugins which do not work in epub, please post them to the forum. | If you find syntax plugins which do not work in epub, please post them to the forum. | ||
Line 219: | Line 231: | ||
==== Image Map Plugins ==== | ==== Image Map Plugins ==== | ||
+ | |||
'' | '' | ||
Line 227: | Line 240: | ||
* **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**\\ 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:// | ||
- | * **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. | + | * **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:// | * **FBreader**\\ Good but does not produce tables, instead converting them to long columns of one-liners for each cell. (Open source)\\ See: http:// | ||
* **Adobe Digital Editions**\\ This is an excellent reader which has been dramatically improved over the past year.\\ The current version is 2.x: http:// | * **Adobe Digital Editions**\\ This is an excellent reader which has been dramatically improved over the past year.\\ The current version is 2.x: http:// | ||
Line 242: | Line 255: | ||
{{rss> | {{rss> | ||
- | For a complete listing of changes see: https:// | + | For a complete listing of changes see: https:// |
=== Known Bugs and Issues === | === Known Bugs and Issues === | ||
Line 256: | Line 270: | ||
===== Discussion ===== | ===== Discussion ===== | ||
+ | |||
:!: Old discussion pages are retained here but are no longer used. | :!: Old discussion pages are retained here but are no longer used. | ||
- | Discussions have been moved to a separate page: [[:: | + | Discussions have been moved to a separate page: [[:: |
plugin/epub.txt · Last modified: 2024-02-26 10:33 by Aleksandr