Kobo Touch/Glo/Mini KePub Plugins

This provides an extension of the existing KoboTouch driver provided with Calibre. This driver plugin allows modifying ePub files to enable extra Kobo features.

Please note: Modified books are not saved back into your Calibre library to prevent issues with overwriting library configurations unexpectedly, so books are processed in transit to your device every time. In most cases, the extra time required should not be noticeable.

Additionally, a calibre conversion output format plugin is available, allowing you to convert books to KePub format without a supported device.

WARNING: THE CONVERSION OUTPUT FORMAT PLUGIN GENERATES FILES WHOSE INTERNAL STRUCTURE IS STILL UNDER DEVELOPMENT. THE KEPUB FILE STRUCTURE IS NOT YET FULLY UNDERSTOOD. DO NOT, UNDER ANY CIRCUMSTANCES, DELETE THE FILES FOR THE SOURCE FORMAT. ALWAYS HAVE A NON-KEPUB FORMAT FOR YOUR BOOKS.

#Download To download this plugin, either clone the repository or download a snapshot of the master branch by clicking on the big Download ZIP button on the right side of the page. It is not necessary to download this plugin in this way unless you want to install from source (see directions below).

#Installation The current release version of this plugin may be installed directly within calibre:

1. Open calibre's preferences, choose Plugins, and click Get new plugins
2. To install the Kobo Touch/Glo/Mini driver plugin, select the KoboTouchExtended plugin from the list of available plugins and click Install
   1. Don't see it? You may already have it installed. Restart calibre and see if you are notified of a pending update.
3. To install the KePub conversion output format plugin, select the KePub Output plugin from the list of available plugins and click Install
   1. Don't see it? You may already have it installed. Restart calibre and see if you are notified of a pending update. Or, this may not yet be uploaded to the calibre plugin index.
4. Restart calibre

To install the device driver plugin from source, you must rename device_init.py to __init__.py, create a ZIP file named KoboTouchExtended.zip and include these files and folders:

1. __init__.py
2. container.py
3. common.py
4. device
5. css
6. plugin-import-name-kobotouch_extended.txt

To install the conversion output format plugin from source, you must rename conversion_init.py to __init__.py, create a ZIP file named KePub Output.zip and include these files and folders:

1. __init__.py
2. container.py
3. common.py
4. conversion
5. css
6. plugin-import-name-koboconversion.txt

To create a ZIP file:

1. Windows users can run the create-plugin.ps1 script (requires that Powershell allow running unsigned scripts, which is not the default setting).
   1. This Powershell script is untested and unsupported; if it does not work for you and you know how to fix it, please submit a bug report with a patch or a corrected Powershell script.
   2. This Powershell script generates the ZIP file for both plugins.
2. Linux and Mac OS X users can run the create-plugin.sh script (either grant it executable permissions first, or run sh create-plugin.sh).
   1. This script generates the ZIP file for both plugins.
3. Create an empty ZIP file and add the files noted above for the desired plugin.
4. Select the files noted above for the desired plugin, right-click, and add the files to a new ZIP file. This may also be referred to as a "Compressed Folder" or only be available once you choose the "Archive" option, depending on your operating system.

Add the resulting ZIP file to calibre:

1. Preferences
2. Plugins
3. Load plugin from file

Usage

To use the device driver plugin after installing:

1. Connect your Kobo Touch/Glo/Mini device and wait for it to be detected by calibre
2. Select the book(s) you want to send to your device.
3. Click the Send to device button.

To use the conversion output format plugin after installing:

1. Choose the book you want to convert to KePub format
2. Choose the KEPUB format from the list of output formats (top-right of the conversion window)
3. Choose KePub Options from the left menu and make your option selections
4. Click OK

WARNING: THE CONVERSION OUTPUT FORMAT PLUGIN GENERATES FILES WHOSE INTERNAL STRUCTURE IS STILL UNDER DEVELOPMENT. THE KEPUB FILE STRUCTURE IS NOT YET FULLY UNDERSTOOD. DO NOT, UNDER ANY CIRCUMSTANCES, DELETE THE FILES FOR THE SOURCE FORMAT. ALWAYS HAVE A NON-KEPUB FORMAT FOR YOUR BOOKS.

Adding Arbitrary CSS

The device driver plugin, through the base KoboTouch driver provided with calibre, has the ability to copy all rules from a specific CSS file into each book as it is uploaded. To support easily maintaining device-specific CSS files, the device driver can copy a CSS file into the correct place to allow adding it to each book. To do this, locate the calibre plugin directory, create a CSS file in there, and ensure that the Modify CSS option is selected in the driver preferences. To locate the calibre plugin directory, open calibre's preferences, choose Miscellaneous, and click the Open calibre configuration directory button. The plugin directory is in there.

The name of the CSS file must be in the format kobo_extra_<DEVICE>.css. The following replacements for <DEVICE> are currently supported (capitalization is important):

• Kobo Aura HD — AURAHD (kobo_extra_AURAHD.css)
• Kobo Aura — AURA (kobo_extra_AURA.css)
• Kobo Glo — GLO (kobo_extra_GLO.css)
• Kobo Mini — MINI (kobo_extra_MINI.css)
• Kobo Touch — TOUCH (kobo_extra_TOUCH.css)

Please note, this will blindly overwrite any kobo_extra.css you may have already sent to your Kobo device! If you have created the kobo_extra.css file on your Kobo device already and you want to make use of this feature, you must copy kobo_extra.css to the location specified above.

Hyphenation

Both plugins includes the ability to add a CSS file to each book enabling KePub hyphenation. The standard hyphenation dictionaries provided on Kobo devices are somewhat deficient for some languages; fixing this (or adding your own dictionary) requires a little work and requires that you can create gzipped tarballs (.tgz files). Note that you can only update existing dictionaries, you cannot add new ones.

1. Somewhere on your computer, create the directory structure usr/local/Kobo/hyphenDicts
2. Download the LibreOffice (or OpenOffice) hyphenation dictionary for your language
   1. This will be a file with the 'oxt' extension. This is just a ZIP archive with a different name.
3. Unzip the OXT file and look for the file named as hyph_[language].dic.
4. Copy the hyphenation dictionary to the hyphenDicts folder without changing the name.
5. Add the usr folder to KoboRoot.tgz
   1. UNIX users (Linux, Solaris, BSD, Mac) can, from the command line, run tar czf KoboRoot.tgz usr/ from wherever you put the usr directory.
   2. Windows users, you're on your own. It has been reported that using the free 7-Zip archiver you can create .tgz files. See http://gettingeek.com/how-to-create-tarball-compress-to-gzip-under-windows-tar-gz-379.html for more details.
      1. If you follow these directions exactly, your file will have the extension .tar.gz. You can safely rename this to .tgz after the file has been created and ignore the Windows warning about changing file extensions.

Once you have created KoboRoot.tgz copy it to the .kobo directory on your Kobo device, unmount/eject the drive, and unplug the device. You will see a screen indicating that the Kobo device is updating; it is not, but this method takes advantage of the Kobo update mechanism to load the necessary dictionary files. Make sure you keep your version of KoboRoot.tgz around, you will need to re-apply it after every Kobo software update!

Provided languages are:

1. English (en_US)
2. French (fr_FR)
3. Spanish (es_ES)
4. German (de_DE)
5. Italian (it_IT)
6. Portugese (pt_PT)

Please note that even with this feature, hyphenation is not exact. Also remember that you can only update existing dictionaries.

Kobo JavaScript Extraction

Both plugins includes the ability to extract the Kobo JavaScript file from a free Kobo-supplied KePub which is not encumbered by any Digital Restrictions Management (DRM). Enabling this requires a little work:

1. Obtain a KePub file from Kobo which is provided to you without any Digital Restrictions Management.
   1. Some of Kobo's free eBooks are provided without DRM
   2. In some regions, Kobo devices are sold with free ebooks in the .kobo/kepub/ folder which do not have DRM
2. Copy the KePub file to the calibre plugins directory
   1. To find the plugins directory, open calibre's preferences, choose Miscellaneous, and click Open calibre configuration directory
   2. Go to the plugins directory
3. Rename the KePub file to reference.kepub.epub
   1. Windows users must be sure to show file extensions in Windows Explorer to be able to properly rename the file.

Once this file is in place and correctly named this plugin will automatically extract the Kobo JavaScript file, add it to books during conversion, and add appropriate references to content files.

Generated KePub File Copying

On occasion, such as for debugging purposes, you may wish to have easy access to the generated KePub file. There is an option in the device driver plugin which allows you to enter the full, absolute path to a directory where all generated files will be copied to once they have been converted. This directory must:

1. Be somewhere you can write to
2. Contain no variables
   1. OS X and Linux users may use a tilde (~) to refer to their home directory instead of typing it in full (/home/jgoguen/calibre-debug may be entered as ~/calibre-debug). Windows users must always enter a full path.

The final path will be a combination of this path and the save template for the plugin. If your debug path is /home/jgoguen/calibre-debug and your save template is {author_sort}/{title} then a KePub file would be copied to, for example, /home/jgoguen/calibre-debug/Camerata, Jo/A History of Vanguard Industries.kepub.epub. Directories will be created as needed.

Contributing

Decided you want to contribute to the development of these plugins? Awesome! You have many options:

1. Contribute code, whether for existing bug reports, for new bugs that you found, or for new features that you really want to see implemented. To contribute code, you may fork the repository and send a GitHub pull request, or you may send me a PM on MobileRead with a git patch file. A tutorial on creating a git patch can be found here
2. Submit bug reports on Launchpad. Launchpad bug reports are my to-do list for this plugin; any requests anywhere else are likely to get missed and forgotten and direct emails will be silently ignored. Although I'm happy to discuss the plugin here, I may still ask you to create a bug report; this is so I actually remember to investigate your request!
3. Test pre-released code from GitHub. Between releases, new code is committed to the GitHub repository and may be installed using directions provided in this file. Based on your testing, you may submit bug reports, provide feedback, think of new feature requests, or just generally enjoy early access (and not necessarily stable code!) to upcoming versions of the plugin.
4. Translate the plugin on [the plugin's Launchpad Translations page][lptranslation]

You may also prefer to contribute in some other way. You may donate to me via PayPal, contribute to my fundraiser, send BitCoins to 1JwHa28vQ33FzCofRMNgpzfUcNGpoh3hUR, or you may also contribute by answering questions from other people who may have issues, purchasing items from my wishlists (not yet linked, I'll get on that soon-ish), continuing to use this plugin and providing feedback, and probably a few other ways I haven't thought of yet.

[lptranslation]:

Asking Questions

Wondering how to do something? Want to know if something is possible? Ask your question on the MobileRead Forum thread for the device driver plugin or the MobileRead Forum thread for the conversion output format plugin.

Reporting a Bug

Found a bug with this plugin? Great! Please use the Launchpad issue tracker to send me reports of issues or feature requests. Under no circumstances should I be emailed directly unless I have asked to have something sent to me. Any emails I haven't asked for may be silently ignored at my sole discretion. Everyone can benefit from a public bug tracker, but only one person benefits from a private email.

When submitting a bug, I require the following information as a minimum, but any additional information is good to include:

1. What version of calibre and this plugin you are using. If you are not on the latest version of either, I will require that you update before I accept any bug report.
2. The full error message reported by calibre, if any.
3. For issues processing books, whether or not you have a book that you are able to send me that demonstrates the issue. Please follow the directions when submitting a new bug to provide me with a book. Under no circumstances should copyrighted content be uploaded to a public bug.
4. The calibre debug log.
   1. To get the calibre debug log, click the arrow beside the "Preferences" menu, choose "Restart in debug mode", repeat the same action that caused the issue, and close calibre. The debug log will be automatically displayed to you.

Known Issues

When using Kobo firmware 2.9.0 or later, sideloaded KePub files do not display in-book statistics.

If you have previously installed the device driver plugin in calibre 0.9.18 or earlier, then you upgrade to calibre 0.9.19 or later and can't update the plugin or install the conversion output format plugin, you must manually replace the device driver plugin ZIP file:

1. Download the latest version of the code.
2. Generate a new plugin ZIP file.
3. Shut down calibre entirely.
4. Open the calibre plugin directory.
   1. Don't know where this is? Before you close calibre, open calibre's preferences, choose Miscellaneous, and click the Open calibre configuration directory button. The plugin directory is in there.
5. Replace the file named KoboTouchExtended.zip with the new version you created. Please make sure the file name remains the same.

If you get an error similar to the following:

Traceback (most recent call last):
File "site-packages\calibre\gui2\preferences\plugins.py", line 310, in add_plugin
File "site-packages\calibre\customize\ui.py", line 361, in add_plugin
File "site-packages\calibre\customize\ui.py", line 53, in load_plugin
File "site-packages\calibre\customize\zipplugin.py", line 169, in load
File "importlib__init__.py", line 37, in import_module
File "site-packages\calibre\customize\zipplugin.py", line 147, in load_module
File "calibre_plugins.kobotouch_extended.__init__", line 4
<!DOCTYPE html>
^
SyntaxError: invalid syntax

The solution is to go back to the top of this file and read it again.

In some circumstances people have reported that while reading a book uploaded with this plugin they suddenly realize that a large amount of time (two hours or more) has passed without their awareness of the passage of time. The only known solution is to finish reading your current book. Voracious readers tend to report this issue more frequently. Please note, sleep is only a temporary resolution.