.. _edit: Editing e-books ======================== calibre has an integrated e-book editor that can be used to edit books in the EPUB and AZW3 (Kindle) formats. The editor shows you the HTML and CSS that is used internally inside the book files, with a live preview that updates as you make changes. It also contains various automated tools to perform common cleanup and fixing tasks. You can use this editor by right clicking on any book in calibre and selecting :guilabel:`Edit book`. .. image:: images/edit-book.png :alt: The Edit book tool :align: center :class: fit-img .. contents:: Contents :depth: 2 :local: Basic workflow --------------- .. note:: A video tour of the calibre E-book editor is available :website:`here `. When you first open a book with the Edit book tool, you will be presented with a list of files on the left. These are the individual HTML files, stylesheets, images, etc. that make up the content of the book. Simply double click on a file to start editing it. Note that if you want to do anything more sophisticated than making a few small tweaks, you will need to know `HTML Tutorial `_ and `CSS Tutorial `_. As you make changes to the HTML or CSS in the editor, the changes will be previewed, live, in the preview panel to the right. When you are happy with how the changes you have made look, click the :guilabel:`Save` button or use :guilabel:`File->Save` to save your changes into the e-book. One useful feature is :guilabel:`Checkpoints`. Before you embark on some ambitious set of edits, you can create a checkpoint. The checkpoint will preserve the current state of your book, then if in the future you decide you don't like the changes you have made to you can go back to the state when you created the checkpoint. To create a checkpoint, use :guilabel:`Edit->Create checkpoint`. Checkpoints will also be automatically created for you whenever you run any automated tool like global search and replace. The checkpointing functionality is in addition to the normal undo/redo mechanism when editing individual files. Checkpoints are needed for when changes are spread over multiple files in the book. That is the basic work flow for editing books -- Open a file, make changes, preview and save. The rest of this manual will discuss the various tools and features present to allow you to perform specific tasks efficiently. The File browser ------------------ .. image:: images/files_browser.png :alt: The File browser showing files in the book :class: float-left-img The :guilabel:`File browser` gives you an overview of the various files inside the book you are editing. The files are arranged by category, with text (HTML) files at the top, followed by stylesheet (CSS) files, images and so on. Simply double click on a file to start editing it. Editing is supported for HTML, CSS and image files. The order of text files is the same order that they would be displayed in, if you were reading the book. All other files are arranged alphabetically. By hovering your mouse over an entry, you can see its size, and also, at the bottom of the screen, the full path to the file inside the book. Note that files inside e-books are compressed, so the size of the final book is not the sum of the individual file sizes. Many files have special meaning, in the book. These will typically have an icon next to their names, indicating the special meaning. For example, in the picture to the left, you can see that the files :guilabel:`cover_image.jpg` and :guilabel:`titlepage.xhtml` have the icon of a cover next to them, this indicates they are the book cover image and titlepage. Similarly, the :guilabel:`content.opf` file has a metadata icon next to it, indicating the book metadata is present in it and the :guilabel:`toc.ncx` file has a T icon next to it, indicating it is the Table of Contents. You can perform many actions on individual files, by right clicking them. Renaming files ^^^^^^^^^^^^^^^ You can rename an individual file by right clicking it and selecting :guilabel:`Rename`. Renaming a file automatically updates all links and references to it throughout the book. So all you have to do is provide the new name, calibre will take care of the rest. You can also bulk rename many files at once. This is useful if you want the files to have some simple name pattern. For example you might want to rename all the HTML files to have names Chapter-1.html, Chapter-2.html and so on. Select the files you want bulk renamed by holding down the :kbd:`Shift` or :kbd:`Ctrl` key and clicking the files. Then right click and select :guilabel:`Bulk rename`. Enter a prefix and what number you would like the automatic numbering to start at, click OK and you are done. The bulk rename dialog also lets you rename files by the order they appear in the book instead of the order you selected them in, useful, for instance to rename all images by the order they appear. Finally, you can bulk change the file extension for all selected files. Select multiple files, as above, and right click and choose :guilabel:`Change the file extension for the selected files`. Merging files ^^^^^^^^^^^^^^ Sometimes, you may want to merge two HTML files or two CSS files together. It can sometimes be useful to have everything in a single file. Be wary, though, putting a lot of content into a single file will cause performance problems when viewing the book in a typical e-book reader. To merge multiple files together, select them by holding the :kbd:`Ctrl` key and clicking on them (make sure you only select files of one type, either all HTML files or all CSS files and so on). Then right click and select merge. That's all, calibre will merge the files, automatically taking care of migrating all links and references to the merged files. Note that merging files can sometimes cause text styling to change, since the individual files could have used different stylesheets. You can also select text files and then drag and drop the text files onto another text file to merge the dropped text files into the target text file. Changing text file order ^^^^^^^^^^^^^^^^^^^^^^^^^^ You can re-arrange the order in which text (HTML) files are opened when reading the book by simply dragging and dropping them in the :guilabel:`File browser` or clicking on the file to move and then pressing the :kbd:`Ctrl+Shift` modifiers with the :kbd:`Up`, :kbd:`Down`, :kbd:`Home` or :kbd:`End` keys. For the technically inclined, this is called re-ordering the book spine. Note that you have to drop the items *between* other items, not on top of them, this can be a little fiddly until you get used to it. Dropping on top of another file will cause the files to be merged. Marking the cover ^^^^^^^^^^^^^^^^^^^^^^^^^^^ E-books typically have a cover image. This image is indicated in the :guilabel:`File browser` by the icon of a brown book next to the image name. If you want to designate some other image as the cover, you can do so by right clicking on the file and choosing :guilabel:`Mark as cover`. In addition, EPUB files has the concept of a *titlepage*. A title page is a HTML file that acts as the title page/cover for the book. You can mark an HTML file as the titlepage when editing EPUBs by right-clicking. Be careful that the file you mark contains only the cover information. If it contains other content, such as the first chapter, then that content will be lost if the user ever converts the EPUB file in calibre to another format. This is because when converting, calibre assumes that the marked title page contains only the cover and no other content. Deleting files ^^^^^^^^^^^^^^^^ You can delete files by either right clicking on them or by selecting them and pressing the Delete key. Deleting a file removes all references to the file from the OPF file, saving you that chore. However, references in other places are not removed, you can use the Check Book tool to easily find and remove/replace them. Exporting files ^^^^^^^^^^^^^^^^^^^^^^^^ You can export a file from inside the book to somewhere else on your computer. This is useful if you want to work on the file in isolation, with specialised tools. To do this, simply right click on the file and choose :guilabel:`Export`. Once you are done working on the exported file, you can re-import it into the book, by right clicking on the file again and choosing :guilabel:`Replace with file...` which will allow you to replace the file in the book with the previously exported file. You can also copy files between multiple editor instances. Select the files you want to copy in the :guilabel:`File browser`, then right click and choose, :guilabel:`Copy selected files to another editor instance`. Then, in the other editor instance, right click in the :guilabel:`File browser` and choose :guilabel:`Paste file from other editor instance`. Adding new images/fonts/etc. or creating new blank files ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can add a new image, font, stylesheet, etc. from your computer into the book by clicking :guilabel:`File->New file`. This lets you either import a file by clicking the :guilabel:`Import resource file` button or create a new blank HTML file or stylesheet by simply entering the file name into the box for the new file. You can also import multiple files into the book at once using File->Import files into book. Replacing files ^^^^^^^^^^^^^^^^ You can easily replace existing files in the book, by right clicking on the file and choosing replace. This will automatically update all links and references, in case the replacement file has a different name than the file being replaced. Linking stylesheets to HTML files efficiently ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As a convenience, you can select multiple HTML files in the File browser, right click and choose Link stylesheets to have calibre automatically insert the tags for those stylesheets into all the selected HTML files. .. raw:: html epub
Search & replace ------------------- Edit book has a very powerful search and replace interface that allows you to search and replace text in the current file, across all files and even in a marked region of the current file. You can search using a normal search or using regular expressions. To learn how to use regular expressions for advanced searching, see :ref:`regexptutorial`. .. image:: images/sr.png :alt: The Edit book tool :align: center Start the search and replace via the :guilabel:`Search->Find/replace` menu entry (you must be editing an HTML or CSS file). Type the text you want to find into the Find box and its replacement into the Replace box. You can the click the appropriate buttons to Find the next match, replace the current match and replace all matches. Using the drop downs at the bottom of the box, you can have the search operate over the current file, all text files, all style files or all files. You can also choose the search mode to be a normal (string) search or a regular expression search. You can count all the matches for a search expression via :guilabel:`Search->Count all`. The count will run over whatever files/regions you have selected in the dropdown box. You can also go to a specific line in the currently open editor via :guilabel:`Search->Go to line`. .. note:: Remember, to harness the full power of search and replace, you will need to use regular expressions. See :ref:`regexptutorial`. Saved searches ^^^^^^^^^^^^^^^ You can save frequently used search/replace expressions (including function mode expressions) and reuse them multiple times. To save a search simply right click in the Find box and select :guilabel:`Save current search`. You can bring up the saved searches via :guilabel:`Search->Saved searches`. This will present you with a list of search and replace expressions that you can apply. You can even select multiple entries in the list by holding down the :kbd:`Ctrl` key while clicking so as to run multiple search and replace expressions in a single operation. Function mode ^^^^^^^^^^^^^^^^^^^^^ Function mode allows you to write arbitrarily powerful Python functions that are run on every Find/replace. You can do pretty much any text manipulation you like in function mode. For more information, see :doc:`function_mode`. Search ignoring HTML tags ^^^^^^^^^^^^^^^^^^^^^^^^^^^ There is also a dedicated tool for searching for text, ignoring any HTML tags in between. For example, if the book has the HTML ``Empahisis on a word.`` you can search for ``on a word`` and it will be found even though there is an ```` tag in the middle. Use this tool via the :guilabel:`Search->Search ignoring HTML markup` menu item. Automated tools ------------------- Edit book has various tools to help with common tasks. These are accessed via the :guilabel:`Tools` menu. Editing the Table of Contents ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ There is a dedicated tool to ease editing of the Table of Contents. Launch it with :guilabel:`Tools->Table of Contents->Edit Table of Contents`. .. image:: images/tocedit.png :alt: The Edit Table of Contents tool :align: center The Edit Table of Contents tool shows you the current Table of Contents (if any) on the left. Simply double click on any entry to change its text. You can also re-arrange entries by drag and drop or by using the buttons to the right. For books that do not have a pre-existing Table of Contents, the tool gives you various options to auto-generate a Table of Contents from the text. You can generate from the headings in the document, from links, from individual files and so on. You can edit individual entries by clicking on them and then clicking the :guilabel:`Change the location this entry points to` button. This will open up a mini-preview of the book, simply move the mouse cursor over the book view panel, and click where you want the entry to point to. A thick green line will show you the location. Click OK once you are happy with the location. .. image:: images/tocedit-location.png :alt: The Edit Table of Contents tool, how to change the location an entry points to :align: center Checking the book ^^^^^^^^^^^^^^^^^^^^^ The :guilabel:`Check book` tool searches your book for problems that could prevent it working as intended on actual reader devices. Activate it via :guilabel:`Tools->Check book`. .. image:: images/check-book.png :alt: The Check book tool :align: center Any problems found are reported in a nice, easy to use list. Clicking any entry in the list shows you some help about that error as well as giving you the option to auto-fix that error, if the error can be fixed automatically. You can also double click the error to open the location of the error in an editor, so you can fix it yourself. Some of the checks performed are: * Malformed HTML markup. Any HTML markup that does not parse as well-formed XML is reported. Correcting it will ensure that your markup works as intended in all contexts. calibre can also auto-fix these errors, but auto-fixing can sometimes have unexpected effects, so use with care. As always, a checkpoint is created before auto-fixing so you can easily revert all changes. Auto-fixing works by parsing the markup using the HTML5 algorithm, which is highly fault tolerant and then converting to well formed XML. * Malformed or unknown CSS styles. Any CSS that is not valid or that has properties not defined in the CSS 2.1 standard (plus a few from CSS 3) are reported. CSS is checked in all stylesheets, inline style attributes and