[GUI Plugin] EpubSplit

[JimmXinu]

Splitting omnibus eBooks into multiple eBooks seems to be a common request, but there haven't been many tools to do so without a lot of hand editing.

This plugin provides the ability to create new EPUBs by splitting off part of an existing (non-DRM) EPUB format eBook.

Main Features of EpubSplit Plugin:

• Present the user with a list of 'split lines' in the existing EPUB. The beginning of each file listed in the manifest spine and each Table of Contents(TOC) entry. <guide> tagged files are also indicated.
• 'Preview' contents of each 'split line' as a tooltip over the HREF.
• Allow user to edit the TOC entry(s) for each 'line'.
• Select one or more of the offered lines to include in the new eBook,
• Edit the metadata for the new split eBook, and then,
• Extract only the selected contents of the source EPUB into the new EPUB,
• Scan the selected content for CSS & image links for additional files to include,
• Scan the selected content for internal links and anchors and update links that need to point to different filenames,
• Use the metadata entered into calibre for the new eBook (including cover) as the metadata in the new EPUB.
• Return to list of source EPUB sections after creating a new split EPUB.
• Configure which metadata from source EPUB to copy to new eBook, now offering more of the standard metadata and custom columns.
• Configurably populate a custom column with the source book title/author/etc.
• CLI via calibre-debug --run-plugin

Special Notes:

• Requires Calibre v0.9.29 or later.

Command Line Interface(CLI)

Starting with calibre v0.9.23, calibre offers a command-line interface (CLI) for calling plugins.

This plugin supports that option and allows the user to call the plugin's basic functionality from outside calibre without having to install Python or get the plugin's files separately.

Details:

Spoiler:

Usage: calibre-debug.exe --run-plugin EpubSplit -- [options] <input epub> [line numbers...]

Giving an epub without line numbers will return a list of line numbers: the
possible split points in the input file. Calling with line numbers will
generate an epub with each of the "lines" given included.

Options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output=OUTPUT
                        Set OUTPUT file, Default: split.epub
  -t TITLE, --title=TITLE
                        Use TITLE as the metadata title.  Default: '<original
                        epub title> Split'
  -d DESC, --description=DESC
                        Use DESC as the metadata description.  Default: 'Split
                        from <epub title> by <author>'.
  -a AUTHOR, --author=AUTHOR
                        Use AUTHOR as a metadata author, multiple authors may
                        be given, Default: <All authors from original epub>
  -g TAG, --tag=TAG     Include TAG as dc:subject tag, multiple tags may be
                        given, Default: None
  -l LANG, --language=LANG
                        Include LANG as dc:language tag, multiple languages
                        may be given, Default: en
  -c COVER, --cover=COVER
                        Path to a jpg to use as cover image.

Installation Steps:

1. Download the attached zip file and install the plugin/add to context menu or toolbar/restart Calibre as described in the Introduction to plugins thread.

Paypal Donations:

• If you find this plugin useful please feel free to show your appreciation.
  

Version History:

Spoiler:

Version 1.2.9 - 03 May 2013
Fix for a changed an internal name in calibre in 0.9.29.

Version 1.2.8 - 16 Mar 2013
Move CLI main import into cli_main. Caused problems for some users on install.

Version 1.2.7 - 15 Mar 2013
Add calibre CLI.

Version 1.2.6 - 01 Dec 2012
Change import for 64 bit calibre.

Version 1.2.5 - 26 Nov 2012
Disable plugin when viewing device, not library.

Version 1.2.4 - 09 Nov 2012
Handle TOC entries with empty text gracefully.

Version 1.2.3 - 27 Sep 2012
'Preview' contents of each 'split line' as a tooltip over the HREF.

Version 1.2.2 - 23 Sep 2012
Add more standard columns to copy list, add custom columns tab to allow copying, make both scrollable in config dialog.
Add options to save the source book title/author/etc to a custom column.

Version 1.2.1 - 28 Jul 2012
Allow for old JSON settings with only partial settings.

Version 1.2.0 - 27 Jul 2012
Return to list of source EPUB sections after creating a new split EPUB.
Options now stored inside the Library rather than an external JSON file.

Version 1.1.1 - Jun 28 2012
Handling links to missing images and css files better.

Version 1.1.0 - Jun 23 2012
Change icon
Add config options to choose which metadata from source EPUB to copy to new eBook.

Version 1.0.0 - May 26 2012
Allow edit of ToC entries.

Version 0.0.1 - May 21 2012
Not configurable.
Show {Guide} entries when splitting.

Version 0.0.0 - May 19 2012
Initial version.

[JSWolf]

Originally Posted by jackie_w

I take it you didn't read my previous post. Sigil is a very good tool for ad-hoc epub editing, but you will see that I listed a couple of things that Sigil didn't automatically clean up for me, namely css files which were no longer referenced and items in the opf <guide> which referenced deleted files. Nor did it automatically remove images which were no longer referenced, nor remove unwanted items from the .ncx file. Luckily, 'Modify epub' does both of the latter.

That's what FlightCrew is for. It will find these things so you can fix them. I know an automated tool can handle a lot of these things. But, what if you find out after you've split your ePub that you've left bits out because you didn't see the shared files. I've done splitting manually (before Sigil) and yes, most of the omnibus editions have shared files that are not obvious from the filenames. Unless this plugin supports viewing of files, it won't work well enough overall.

[JSWolf]

Originally Posted by JimmXinu

I agree that it's not nearly as easy as epub merging was. But I think a useful tool can still be had from it for basic splitting.

My vision right now is to offer a list of 'split lines'--the beginning of each file and/or each TOC entry--and let the user click and choose which they want to include. I agree that trying to automatically decide where to split is beyond complex.

Then the program includes only those files (or partial files), scans them for included css & images, writes only those files, manifest and TOC. TOC gets flattened along the way (that way lies madness).

I have that much working in CLI already. (Still need to fix internal URLs, worry about cover image, etc.) I plan to offer & collect metadata using calibre's edit metadata dialog, similar to EpubMerge.

That sounds to me like a useful tool because to do it manually would take a number of steps in Sigil to split/delete files, clean up TOC, plus Modify ePub to remove unused img/css files.

People who are looking for absolutely perfect epubs will still need to hand edit, but I think this will be useful.

Can you make your tool do an after clean? So say someone uses Sigil to split things. Instead of then having to sort out things that will need to be sorted like broken links and such, ePubSplit be used to do just the cleaning up?

[PeterT]

Just tried splitting up an omnibus edition of the Game of Thrones that I had also split by hand. Seemed to work like a champ.

Now time to run it through KiwiDude's creation to see what it finds

[JSWolf]

Originally Posted by PeterT

Just tried splitting up an omnibus edition of the Game of Thrones that I had also split by hand. Seemed to work like a champ.

Now time to run it through KiwiDude's creation to see what it finds

When you did the splitting with this tool, were you able to easily get the shared files so what you ended up with was complete?

[JimmXinu]

The plugin looks through the HTML it's keeping for style and img tags and includes those files.

If you find a case where it doesn't, I'd like to know about it.

[PeterT]

Originally Posted by JSWolf

When you did the splitting with this tool, were you able to easily get the shared files so what you ended up with was complete?

Well so far no sign of any broken links, missing images, or extra image files. No reports of any unmanifested files

[JimmXinu]

Originally Posted by JSWolf

Can you make your tool do an after clean? So say someone uses Sigil to split things. Instead of then having to sort out things that will need to be sorted like broken links and such, ePubSplit be used to do just the cleaning up?

Somewhat. You could use EpubSplit and select all files, that should remove any extra css/image files that aren't used.

It doesn't make any attempt to remove links to files that aren't in the source epub.

[JimmXinu]

Any suggestions for the icon for this?

Here's what I've been toying with.

[jackie_w]

Hi Jimm,

I just did a quick test with the 6-book bundle I split a few days ago. It seems to create clean and tidy epubs

I did notice one thing, though... the opf and ncx files had both had all their end-of-line characters removed after the split, which made them difficult to read. Was this deliberate?

Hopefully, I'll have more time tomorrow to test a few more bundles.

Thank you for your hard work

[JimmXinu]

@jackie_w - Thanks for testing--hopefully it continues to work for you.

As for the opf & ncx, they're being created completely anew, not copied and modified. While working on earlier projects, I found that trying to pretty print those files from my constructed DOM caused problems with excess whitespace in the text data, like ToC entries. At the time, I didn't judge it important enough to put more effort into.

[JSWolf]

Originally Posted by PeterT

Well so far no sign of any broken links, missing images, or extra image files. No reports of any unmanifested files

Did you get all the files that went with the book including all the shared files/cover pages/copyright?

[JimmXinu]

If you select them, they get included. If you don't, they don't.

It doesn't look at any <guide> tags, if that's what you're asking.

If the source book has a cover in calibre, it will copy that to the new book record before presenting the metadata. If there's a cover in the metadata after it's been presented and accepted (from the original, downloaded, whatever), it will be included in the EPUB.

No other html files are given any special consideration.

[JSWolf]

Question, will there be a way to tell what files are what for the ones that don't have names that are obvious? Because if you cannot see the contents in some way, then it will be very difficult for some to be able to get all the files needed for a given eBook from an omnibus.

[PeterT]

What you see when you are doing the split is the chapter headings... So it's not picking files per se, rather a listing of HREFs (appears to be the full name of the files) and then their entries in the Table of Contents.

So all I did was to highlight the entries from the first portion of each book, through to the final TOC entry for that book. Images and CSS file names don'r appear in this list; they seem to get included based on what is needed.