Introduction to the tweak_epub utility
With Atlantis Word Processor, you can convert any document file into an eBook in the EPUB format. And when you need to make a change to an eBook, all you need to do is modify the corresponding source document in Atlantis, then resave it as eBook.
However, at times you might want to make adjustments to EPUB files that are not possible directly through the GUI of Atlantis. This can be done with the tweak_epub utility, irrespective of whether the EPUB files were generated by Atlantis or by another application.
Before explaining how to use the "tweak_epub" utility, let's first take a look at the inner workings of EPUB files.
All EPUB files are actually ZIP files with ".epub" as their filename extension instead of ".zip". So if you rename an EPUB file by changing its ".epub" extension to the ".zip" extension, you'll be able to open the newly-renamed ".zip" file in any file compression software, and view the files contained within the original EPUB package. You can then extract files of interest, modify them in a text editor, and put them back in the ZIP file. To recover a working EPUB package (file), you finally need to change the file extension back to ".epub" (instead of ".zip").
Note that an EPUB file (package) normally contains multiple files in different formats: XHTML, XML, JPG, etc.
There is one important detail to remember when you modify an EPUB file in a ZIP software. The first file in any proper EPUB package must be "mimetype", and it is always a 20-byte ASCII file containing this string of text:
This "mimetype" file must always be stored within the EPUB package in uncompressed form. So before using a ZIP software to tweak your EPUB files, make sure that the software will preserve the original order of files, and leave the "mimetype" file uncompressed. Not every ZIP software will allow such "delicate" changes to a ZIP file.
The tweak_epub utility will allow you to make adjustments to your EPUB files in a very convenient way. You'll be able to adjust individual files within an EPUB package without affecting the other files in it.
Click the following link to download the free tweak_epub utility:
|tweak_epub.exe (327 KB)|
This utility doesn't require any installation. Simply place it in any folder on your system, and execute "tweak_epub.exe" whenever you want to modify an EPUB file.
You'll first get the "Open EPUB" window. Direct the utility to the EPUB file of interest, and click "Open":
This will open a second window with the complete list of the files contained within the EPUB package:
You can then use this window and its various buttons to modify any of the contained files, remove files, add new files, rename files, etc.
In most cases, you'll want to make changes to the text files (HTML, XML, CSS, OPF, etc) contained in the EPUB package. To edit a text file, click to select it in the "Files" box ("styles.css" in the example below), then press the "Edit File..." button:
The selected file will by default be opened in the Windows Notepad:
You can then make any suitable change to the file. When you are done, click the rightmost cross button on the text editor title bar, or simply press AltF4 to close the editor. You will get a confirmation message:
Click "Save" if you want to save changes.
By default, the "tweak_epub" utility uses the Windows Notepad as its dedicated text editor:
But you can perfectly well use a different editor. To change the default editor used by the utility, click the "Choose Editor..." button:
You then need to direct the utility to the folder containing the executable file of your text editor. Executable files have an ".exe" extension. Click to select the ".exe" file for the text editor, then press the "Open" button:
Now you might want to change the contents of an EPUB package other than modifying some of its text files. For this, click the "View All in File Manager..." button:
All the folders and files from the EPUB package will automatically be extracted to a temporary folder on your system and opened in your default file manager. This temporary folder is created under your "My Documents" folder, and its name matches the EPUB filename:
You can then browse through the EPUB package folder and sub-folders, and make all suitable changes to their contents:
You can edit any file with a dedicated editor. You can remove files, replace files, rename files, or add new files. You can delete any of the sub-folders, or create new sub-folders. Etc.
When you switch back to the window of the "tweak_epub" utility after making changes to the files of the EPUB package, its "Save Changes" button automatically becomes enabled:
Click this button to save all the modified files to the EPUB package. Of course, you can always click the "Cancel Changes" button if you do not want to make changes to the EPUB file after all. Note that the temporary folder generated under your "My Documents" folder is automatically removed from your system as soon as you close the "tweak_epub" utility window.
Before pressing the "Save Changes" button to store the adjusted EPUB file on your hard disk, you might want to preview the eBook in the associated reader if available on your Windows system. If none is available yet, you can always download Adobe Digital Editions for free, and install it on your PC. To preview the eBook, click the corresponding button of the "tweak_epub" utility:
If you need to modify EPUB files only occasionally, launching the "tweak_epub" utility manually, then browsing your disks for the EPUB file of interest could not be a problem. But if you need to edit many EPUB files, getting through this procedure for each EPUB file might be tiring. So if you often tweak EPUB files, you can use the Windows Explorer "Open with" right-click command to open any EPUB file straightaway in the "tweak_epub" utility.
Here is how to proceed:
1. Right-click any EPUB file in Windows Explorer.
2. Choose the "Open With..." command from the menu if it is available:
Otherwise, click the "Choose Program..." command:
3. Press the "Browse..." button in the "Open With" dialog:
4. Direct the "Open With..." dialog to the disk folder where you downloaded the "tweak_epub" utility, and double-click the "tweak_epub.exe" file:
5. Press the OK button in the "Open With" dialog:
From then on, Windows will show the "tweak_epub" command in the "Open With" menu whenever you right-click an EPUB file for editing:
Choosing the "tweak_epub.exe" command will immediately open the selected EPUB file in the "tweak_epub" utility:
Sometimes authors need to add extra metadata to their EPUBs. Metadata is stored within the file with .opf extension. If you open any EPUB file created in Atlantis with the "tweak_epub" utility, you will find a file called "content.opf" under the "Ops" folder:
You can then select the "content.opf" file, and click the "Edit File..." button to open it in the text editor. This file contains a separate section with metadata:
In the above example, the EPUB file contains 5 metadata items: title, creator, date, identifier, and language. When you save a document as eBook in Atlantis, you can instruct Atlantis to add more metadata items to the eBook "content.opf" file. This is done by specifying the following "basic information" about your book in the Atlantis "Save as eBook" window:
But you might still need to add metadata not supported by this "Save as eBook" window of Atlantis. In such cases you could add them manually to "content.opf". For example, you could add a "book genre" metadata to your EPUB using the "tweak_epub" utility and the associated editor: