1.. _edit: 2 3Editing e-books 4======================== 5 6calibre has an integrated e-book editor that can be used to edit books in the 7EPUB and AZW3 (Kindle) formats. The editor shows you the HTML and CSS that is 8used internally inside the book files, with a live preview that updates as you 9make changes. It also contains various automated tools to perform common 10cleanup and fixing tasks. 11 12You can use this editor by right clicking on any book in calibre and selecting 13:guilabel:`Edit book`. 14 15.. image:: images/edit-book.png 16 :alt: The Edit book tool 17 :align: center 18 :class: fit-img 19 20.. contents:: Contents 21 :depth: 2 22 :local: 23 24 25Basic workflow 26--------------- 27 28.. note:: 29 A video tour of the calibre E-book editor is available `here 30 <https://calibre-ebook.com/demo#tutorials>`_. 31 32When you first open a book with the Edit book tool, you will be presented with 33a list of files on the left. These are the individual HTML files, stylesheets, 34images, etc. that make up the content of the book. Simply double click on a 35file to start editing it. Note that if you want to do anything more 36sophisticated than making a few small tweaks, you will need to know `HTML 37Tutorial <http://html.net/tutorials/html/>`_ and `CSS Tutorial 38<http://html.net/tutorials/css/>`_. 39 40As you make changes to the HTML or CSS in the editor, the changes will be 41previewed, live, in the preview panel to the right. When you are happy with how 42the changes you have made look, click the :guilabel:`Save` button or use 43:guilabel:`File->Save` to save your changes into the e-book. 44 45One useful feature is :guilabel:`Checkpoints`. Before you embark on some 46ambitious set of edits, you can create a checkpoint. The checkpoint 47will preserve the current state of your book, then if in the future you decide 48you don't like the changes you have made to you can go back to the state when 49you created the checkpoint. To create a checkpoint, use :guilabel:`Edit->Create 50checkpoint`. Checkpoints will also be automatically created for you whenever you 51run any automated tool like global search and replace. The checkpointing 52functionality is in addition to the normal undo/redo mechanism when editing 53individual files. Checkpoints are useful for when changes are spread over 54multiple files in the book. 55 56That is the basic work flow for editing books -- Open a file, make changes, 57preview and save. The rest of this manual will discuss the various tools and 58features present to allow you to perform specific tasks efficiently. 59 60The File browser 61------------------ 62 63.. image:: images/files_browser.png 64 :alt: The File browser 65 :class: float-left-img 66 67The :guilabel:`File browser` gives you an overview of the various files inside 68the book you are editing. The files are arranged by category, with text (HTML) 69files at the top, followed by stylesheet (CSS) files, images and so on. Simply 70double click on a file to start editing it. Editing is supported for HTML, CSS 71and image files. The order of text files is the same order that they would be 72displayed in, if you were reading the book. All other files are arranged 73alphabetically. 74 75By hovering your mouse over an entry, you can see its size, and also, at 76the bottom of the screen, the full path to the file inside the book. Note that 77files inside e-books are compressed, so the size of the final book is not the 78sum of the individual file sizes. 79 80Many files have special meaning, in the book. These will typically have 81an icon next to their names, indicating the special meaning. For example, in 82the picture to the left, you can see that the files :guilabel:`cover_image.jpg` 83and :guilabel:`titlepage.xhtml` have the icon of a cover next to them, this 84indicates they are the book cover image and titlepage. Similarly, the 85:guilabel:`content.opf` file has a metadata icon next to it, indicating the 86book metadata is present in it and the :guilabel:`toc.ncx` file has a T 87icon next to it, indicating it is the Table of Contents. 88 89You can perform many actions on individual files, by right clicking them. 90 91Renaming files 92^^^^^^^^^^^^^^^ 93 94You can rename an individual file by right clicking it and selecting 95:guilabel:`Rename`. Renaming a file automatically updates all links and 96references to it throughout the book. So all you have to do is provide the new 97name, calibre will take care of the rest. 98 99You can also bulk rename many files at once. This is useful 100if you want the files to have some simple name pattern. For example you might 101want to rename all the HTML files to have names Chapter-1.html, Chapter-2.html 102and so on. Select the files you want bulk renamed by holding down the :kbd:`Shift` or 103:kbd:`Ctrl` key and clicking the files. Then right click and select :guilabel:`Bulk 104rename`. Enter a prefix and what number you would like the automatic numbering 105to start at, click OK and you are done. The bulk rename dialog also lets you 106rename files by the order they appear in the book instead of the order you 107selected them in, useful, for instance to rename all images by the order 108they appear. 109 110Finally, you can bulk change the file extension for all selected files. Select 111multiple files, as above, and right click and choose :guilabel:`Change the file 112extension for the selected files`. 113 114Merging files 115^^^^^^^^^^^^^^ 116 117Sometimes, you may want to merge two HTML files or two CSS files together. It 118can sometimes be useful to have everything in a single file. Be wary, though, 119putting a lot of content into a single file will cause performance problems 120when viewing the book in a typical e-book reader. 121 122To merge multiple files together, select them by holding the :kbd:`Ctrl` key and 123clicking on them (make sure you only select files of one type, either all HTML 124files or all CSS files and so on). Then right click and select merge. That's 125all, calibre will merge the files, automatically taking care of migrating all 126links and references to the merged files. Note that merging files can sometimes 127cause text styling to change, since the individual files could have used 128different stylesheets. 129 130You can also select text files and then drag and drop the text files onto 131another text file to merge the dropped text files into the target text file. 132 133Changing text file order 134^^^^^^^^^^^^^^^^^^^^^^^^^^ 135 136You can re-arrange the order in which text (HTML) files are opened when reading 137the book by simply dragging and dropping them in the Files browser. For the 138technically inclined, this is called re-ordering the book spine. Note that you 139have to drop the items *between* other items, not on top of them, this can be a 140little fiddly until you get used to it. Dropping on top of another file will 141cause the files to be merged. 142 143Marking the cover 144^^^^^^^^^^^^^^^^^^^^^^^^^^^ 145 146E-books typically have a cover image. This image is indicated in the 147:guilabel:`File browser` by the icon of a brown book next to the image name. If 148you want to designate some other image as the cover, you can do so by right 149clicking on the file and choosing :guilabel:`Mark as cover`. 150 151In addition, EPUB files has the concept of a *titlepage*. A title page is a 152HTML file that acts as the title page/cover for the book. You can mark an HTML 153file as the titlepage when editing EPUBs by right-clicking. Be careful that the 154file you mark contains only the cover information. If it contains other 155content, such as the first chapter, then that content will be lost if the user 156ever converts the EPUB file in calibre to another format. This is because when 157converting, calibre assumes that the marked title page contains only the cover 158and no other content. 159 160Deleting files 161^^^^^^^^^^^^^^^^ 162 163You can delete files by either right clicking on them or by selecting them and 164pressing the Delete key. Deleting a file removes all references to the file 165from the OPF file, saving you that chore. However, references in other places 166are not removed, you can use the Check Book tool to easily find and 167remove/replace them. 168 169Exporting files 170^^^^^^^^^^^^^^^^^^^^^^^^ 171 172You can export a file from inside the book to somewhere else on your computer. 173This is useful if you want to work on the file in isolation, with specialised 174tools. To do this, simply right click on the file and choose 175:guilabel:`Export`. 176 177Once you are done working on the exported file, you can re-import it into the 178book, by right clicking on the file again and choosing :guilabel:`Replace with 179file...` which will allow you to replace the file in the book with 180the previously exported file. 181 182You can also copy files between multiple editor instances. Select 183the files you want to copy in the :guilabel:`File browser`, then right click 184and choose, :guilabel:`Copy selected files to another editor instance`. Then, 185in the other editor instance, right click in the :guilabel:`File browser` 186and choose :guilabel:`Paste file from other editor instance`. 187 188Adding new images/fonts/etc. or creating new blank files 189^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 190 191You can add a new image, font, stylesheet, etc. from your computer into the 192book by clicking :guilabel:`File->New file`. This lets you either import a file 193by clicking the :guilabel:`Import resource file` button or create a new blank HTML file 194or stylesheet by simply entering the file name into the box for the new file. 195 196You can also import multiple files into the book at once using File->Import 197files into book. 198 199Replacing files 200^^^^^^^^^^^^^^^^ 201 202You can easily replace existing files in the book, by right clicking on the 203file and choosing replace. This will automatically update all links and 204references, in case the replacement file has a different name than the file 205being replaced. 206 207Linking stylesheets to HTML files efficiently 208^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 209 210As a convenience, you can select multiple HTML files in the File browser, 211right click and choose Link stylesheets to have calibre automatically insert the 212<link> tags for those stylesheets into all the selected HTML files. 213 214.. raw:: html epub 215 216 <div style="clear:both"></div> 217 218 219Search & replace 220------------------- 221 222Edit book has a very powerful search and replace interface that allows you to 223search and replace text in the current file, across all files and even in a 224marked region of the current file. You can search using a normal search or 225using regular expressions. To learn how to use regular expressions for advanced 226searching, see :ref:`regexptutorial`. 227 228.. image:: images/sr.png 229 :alt: The Edit book tool 230 :align: center 231 232Start the search and replace via the :guilabel:`Search->Find/replace` menu 233entry (you must be editing an HTML or CSS file). 234 235Type the text you want to find into the Find box and its replacement into the 236Replace box. You can the click the appropriate buttons to Find the next match, 237replace the current match and replace all matches. 238 239Using the drop downs at the bottom of the box, you can have the search operate 240over the current file, all text files, all style files or all files. You can 241also choose the search mode to be a normal (string) search or a regular 242expression search. 243 244You can count all the matches for a search expression via 245:guilabel:`Search->Count all`. The count will run over whatever files/regions 246you have selected in the dropdown box. 247 248You can also go to a specific line in the currently open editor via 249:guilabel:`Search->Go to line`. 250 251.. note:: 252 Remember, to harness the full power of search and replace, you will 253 need to use regular expressions. See :ref:`regexptutorial`. 254 255Saved searches 256^^^^^^^^^^^^^^^ 257 258You can save frequently used search/replace expressions (including function 259mode expressions) and reuse them multiple times. To save a search simply right 260click in the Find box and select :guilabel:`Save current search`. 261 262You can bring up the saved searches via :guilabel:`Search->Saved 263searches`. This will present you with a list of search and replace expressions 264that you can apply. You can even select multiple entries in the list by holding 265down the :kbd:`Ctrl` key while clicking so as to run multiple search and replace 266expressions in a single operation. 267 268Function mode 269^^^^^^^^^^^^^^^^^^^^^ 270 271Function mode allows you to write arbitrarily powerful Python functions that 272are run on every Find/replace. You can do pretty much any text manipulation you 273like in function mode. For more information, see :doc:`function_mode`. 274 275Search ignoring HTML tags 276^^^^^^^^^^^^^^^^^^^^^^^^^^^ 277 278There is also a dedicated tool for searching for text, ignoring any HTML tags 279in between. For example, if the book has the HTML ``Empahisis on a 280<i>word</i>.`` you can search for ``on a word`` and it will be found even 281though there is an ``<i>`` tag in the middle. Use this 282tool via the :guilabel:`Search->Search ignoring HTML markup` menu item. 283 284Automated tools 285------------------- 286 287Edit book has various tools to help with common tasks. These are 288accessed via the :guilabel:`Tools` menu. 289 290Editing the Table of Contents 291^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 292 293There is a dedicated tool to ease editing of the Table of Contents. Launch it 294with :guilabel:`Tools->Table of Contents->Edit Table of Contents`. 295 296.. image:: images/tocedit.png 297 :alt: The Edit Table of Contents tool 298 :align: center 299 300The Edit Table of Contents tool shows you the current Table of Contents (if 301any) on the left. Simply double click on any entry to change its text. You can 302also re-arrange entries by drag and drop or by using the buttons to the right. 303 304For books that do not have a pre-existing Table of Contents, the tool gives you 305various options to auto-generate a Table of Contents from the text. You can 306generate from the headings in the document, from links, from individual files 307and so on. 308 309You can edit individual entries by clicking on them and then clicking the 310:guilabel:`Change the location this entry points to` button. This will open up 311a mini-preview of the book, simply move the mouse cursor over the book view 312panel, and click where you want the entry to point to. A thick green line 313will show you the location. Click OK once you are happy with the location. 314 315.. image:: images/tocedit-location.png 316 :alt: The Edit Table of Contents tool, how to change the location an entry points to 317 :align: center 318 319Checking the book 320^^^^^^^^^^^^^^^^^^^^^ 321 322The :guilabel:`Check book` tool searches your book for problems that could 323prevent it working as intended on actual reader devices. Activate it via 324:guilabel:`Tools->Check book`. 325 326.. image:: images/check-book.png 327 :alt: The Check book tool 328 :align: center 329 330Any problems found are 331reported in a nice, easy to use list. Clicking any entry in the list shows you 332some help about that error as well as giving you the option to auto-fix that 333error, if the error can be fixed automatically. You can also double click the 334error to open the location of the error in an editor, so you can fix it 335yourself. 336 337Some of the checks performed are: 338 339 * Malformed HTML markup. Any HTML markup that does not parse as well-formed 340 XML is reported. Correcting it will ensure that your markup works as 341 intended in all contexts. calibre can also auto-fix these errors, but 342 auto-fixing can sometimes have unexpected effects, so use with care. As 343 always, a checkpoint is created before auto-fixing so you can easily 344 revert all changes. Auto-fixing works by parsing the markup using the 345 HTML5 algorithm, which is highly fault tolerant and then converting to 346 well formed XML. 347 348 * Malformed or unknown CSS styles. Any CSS that is not valid or that has 349 properties not defined in the CSS 2.1 standard (plus a few from CSS 3) 350 are reported. CSS is checked in all stylesheets, inline style attributes 351 and <style> tags in HTML files. 352 353 * Broken links. Links that point to files inside the book that are missing 354 are reported. 355 356 * Unreferenced files. Files in the book that are not referenced by any 357 other file or are not in the spine are reported. 358 359 * Various common problems in OPF files such as duplicate spine or manifest 360 items, broken idrefs or meta cover tags, missing required sections and 361 so on. 362 363 * Various compatibility checks for known problems that can cause the book 364 to malfunction on reader devices. 365 366Adding a cover 367^^^^^^^^^^^^^^^ 368 369You can easily add a cover to the book via :guilabel:`Tools->Add cover`. This 370allows you to either choose an existing image in the book as the cover or 371import a new image into the book and make it the cover. When editing EPUB 372files, the HTML wrapper for the cover is automatically generated. If an 373existing cover in the book is found, it is replaced. The tool also 374automatically takes care of correctly marking the cover files as covers in the 375OPF. 376 377Embedding referenced fonts 378^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 379 380Accessed via :guilabel:`Tools->Embed reference fonts`, this tool finds all 381fonts referenced in the book and if they are not already embedded, searches 382your computer for them and embeds them into the book, if found. Please make 383sure that you have the necessary copyrights for embedding commercially licensed 384fonts, before doing this. 385 386Subsetting embedded fonts 387^^^^^^^^^^^^^^^^^^^^^^^^^^^ 388 389Accessed via :guilabel:`Tools->Subset embedded fonts`, this tool reduces all 390the fonts in the book to only contain glyphs for the text actually present in 391the book. This commonly reduces the size of the font files by ~ 50%. However, 392be aware that once the fonts are subset, if you add new text whose characters 393are not previously present in the subset font, the font will not work for the 394new text. So do this only as the last step in your workflow. 395 396Smartening punctuation 397^^^^^^^^^^^^^^^^^^^^^^^^^ 398 399Convert plain text dashes, ellipsis, quotes, multiple hyphens, etc. into their 400typographically correct equivalents. 401Note that the algorithm can sometimes generate incorrect results, especially 402when single quotes at the start of contractions are involved. Accessed via 403:guilabel:`Tools->Smarten punctuation`. 404 405Transforming CSS properties 406^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 407 408Create rules to transform the styling of the book. For example, create a rule 409to convert all red text to green or to double the font size of all text in the 410book or make text of a certain font family italic, etc. 411 412Creating the rules is simple, the rules follow a natural language format, that 413looks like: 414 415 * If the property *color* is *red* *change* it to *green* 416 * If the property *font-size* is *any value* *multiply* the value by *2* 417 418Accessed via :guilabel:`Tools->Transform styles`. 419 420Removing unused CSS rules 421^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 422 423Remove all unused CSS rules from stylesheets and <style> tags. Some books 424created from production templates can have a large number of extra CSS rules 425that don't match any actual content. These extra rules can slow down readers 426that need to process them all. Accessed via :guilabel:`Tools->Remove unused CSS`. 427 428 429Fixing HTML 430^^^^^^^^^^^ 431 432This tool simply converts HTML that cannot be parsed as XML into well-formed 433XML. It is very common in e-books to have non-well-formed XML, so this tool 434simply automates the process of fixing such HTML. The tool works by parsing the 435HTML using the HTML5 algorithm (the algorithm used in all modern browsers) and 436then converting the result into XML. Be aware that auto-fixing can sometimes 437have counter-intuitive results. If you prefer, you can use the Check Book tool 438discussed above to find and manually correct problems in the HTML. Accessed via 439:guilabel:`Tools->Fix HTML`. 440 441Beautifying files 442^^^^^^^^^^^^^^^^^^^ 443 444This tool is used to auto-format all HTML and CSS files so that they "look 445pretty". The code is auto-indented so that it lines up nicely, blank lines are 446inserted where appropriate and so on. Note that beautifying also auto-fixes 447broken HTML/CSS. Therefore, if you don't want any auto-fixing to be performed, 448first use the Check Book tool to correct all problems and only then run 449beautify. Accessed via :guilabel:`Tools->Beautify all files`. 450 451.. note:: 452 In HTML any text can have significant whitespace, via the CSS white-space 453 directive. Therefore, beautification could potentially change the rendering 454 of the HTML. To avoid this as far as possible, the beautify algorithm 455 only beautifies block level tags that contain other block level tags. So, 456 for example, text inside a <p> tag will not have its whitespace changed. 457 But a <body> tag that contains only other <p> and <div> tags will be 458 beautified. This can sometimes mean that a particular file will not be 459 affected by beautify as it has no suitable block level tags. In such 460 cases you can try different beautification tools, that are less careful, 461 for example: `HTML Tidy <https://infohound.net/tidy/>`_. 462 463 464Inserting an inline Table of Contents 465^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 466 467Normally in e-books, the Table of Contents is separate from the main text and is 468typically accessed via a special Table of Contents button/menu in the e-book 469reading device. You can also have calibre automatically generate an *inline* 470Table of Contents that becomes part of the text of the book. It is 471generated based on the currently defined Table of Contents. 472 473If you use this tool multiple times, each invocation will cause the previously 474created inline Table of Contents to be replaced. The tool can be accessed via 475:guilabel:`Tools->Table of Contents->Insert inline Table of Contents`. 476 477Setting Semantics 478^^^^^^^^^^^^^^^^^ 479 480This tool is used to set *semantics* in EPUB files. Semantics are simply, 481links in the OPF file that identify certain locations in the book as having 482special meaning. You can use them to identify the foreword, dedication, cover, 483table of contents, etc. Simply choose the type of semantic information you want 484to specify and then select the location in the book the link should point to. 485This tool can be accessed via :guilabel:`Tools->Set semantics`. 486 487Filtering style information 488^^^^^^^^^^^^^^^^^^^^^^^^^^^ 489 490This tool can be used to easily remove specified CSS style properties from the 491entire book. You can tell it what properties you want removed, for example, 492``color, background-color, line-height`` and it will remove them from 493everywhere they occur --- stylesheets, ``<style>`` tags and inline ``style`` 494attributes. After removing the style information, a summary of all the changes 495made is displayed so you can see exactly what was changed. The tool can be 496accessed via :guilabel:`Tools->Filter style information`. 497 498 499Upgrading the book's internals 500^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 501 502This tool can be used to upgrade the book's internals, if possible. For 503instance it will upgrade EPUB 2 books to EPUB 3 books. The tool can be 504accessed via :guilabel:`Upgrade book internals`. 505 506.. _checkpoints: 507 508Checkpoints 509------------------------ 510 511:guilabel:`Checkpoints` are a way to mark the current state of the book as "special". You 512can then go on to do whatever changes you want to the book and if you don't like 513the results, return to the checkpointed state. Checkpoints are automatically 514created every time you run any of the automated tools described in the 515previous section. 516 517You can create a checkpoint via :guilabel:`Edit->Create checkpoint`. And go back 518to a previous checkpoint with :guilabel:`Edit->Revert to ...` 519 520The check pointing functionality is in addition to the normal Undo/redo 521mechanism when editing individual files. Checkpoints are particularly useful 522for when changes are spread over multiple files in the book or when you wish to 523be able to revert a large group of related changes as a whole. 524 525You can see a list of available checkpoints via :guilabel:`View->Checkpoints`. 526You can compare the current state of the book to a specified checkpoint 527using the :ref:`diff` tool -- by selecting the checkpoint of interest and clicking 528the :guilabel:`Compare` button. The :guilabel:`Revert to` button restores the 529book to the selected checkpoint, undoing all changes since that checkpoint was 530created. 531 532The Live preview panel 533------------------------ 534 535.. image:: images/live-preview.png 536 :alt: The Live preview panel 537 :class: float-left-img 538 539The :guilabel:`File preview` gives you an overview of the various files inside 540The live preview panel shows you the changes you are making live (with a second 541or two of delay). As you edit HTML or CSS files, the preview panel is updated 542automatically to reflect your changes. As you move the cursor around in the 543editor, the preview panel will track its location, showing you the 544corresponding location in the book. Clicking in the preview panel, will cause 545the cursor in the editor to be positioned over the element you clicked. If you 546click a link pointing to another file in the book, that file will be opened in 547the edit and the preview panel, automatically. 548 549You can turn off the automatic syncing of position and live preview of changes 550-- by buttons under the preview panel. The live update of the preview 551panel only happens when you are not actively typing in the editor, so as not to 552be distracting or slow you down, waiting for the preview to render. 553 554The preview panel shows you how the text will look when viewed. However, the 555preview panel is not a substitute for actually testing your book an actual 556reader device. It is both more, and less capable than an actual reader. It will 557tolerate errors and sloppy markup much better than most reader devices. It will 558also not show you page margins, page breaks and embedded fonts that use font 559name aliasing. Use the preview panel while you are working on the book, but 560once you are done, review it in an actual reader device or software emulator. 561 562.. note:: 563 The preview panel does not support embedded fonts if the name of the font 564 inside the font file does not match the name in the CSS @font-face rule. 565 You can use the Check Book tool to quickly find and fix any such 566 problem fonts. 567 568Splitting HTML files 569^^^^^^^^^^^^^^^^^^^^^^ 570 571.. |spmb| image:: images/split-button.png 572 573One, perhaps non-obvious, use of the preview panel is to split long HTML files. 574While viewing the file you want to split, click the :guilabel:`Split mode` 575button under the preview panel |spmb|. Then simply move your mouse to the place 576where you want to split the file and click. A thick green line will show you 577exactly where the split will happen as you move your mouse. Once you have found 578the location you want, simply click and the split will be performed. 579 580Splitting the file will automatically update all links and references that 581pointed into the bottom half of the file and will open the newly split file in 582an editor. 583 584You can also split a single HTML file at multiple locations automatically, by 585right clicking inside the file in the editor and choosing :guilabel:`Split at 586multiple locations`. This will allow you to easily split a large file at all 587heading tags or all tags having a certain class and so on. 588 589.. raw:: html epub 590 591 <div style="clear:both"></div> 592 593The Live CSS panel 594--------------------- 595 596.. image:: images/live_css.png 597 :alt: The Live CSS panel 598 :class: float-left-img 599 600 601The :guilabel:`Live CSS` panel shows you all the style rules that apply to the 602tag you are currently editing. The name of tag, along with its line number in 603the editor are displayed, followed by a list of matching style rules. 604 605It is a great way to quickly see which style rules apply to any tag. The view 606also has clickable links (in blue), which take you directly to the location 607where the style was defined, in case you wish to make any changes to the style 608rules. Style rules that apply directly to the tag, as well as rules that are 609inherited from parent tags are shown. 610 611The panel also shows you what the finally calculated styles for the tag are. 612Properties in the list that are superseded by higher priority rules are shown 613with a line through them. 614 615You can enable the Live CSS panel via :guilabel:`View->Live CSS`. 616 617.. raw:: html epub 618 619 <div style="clear:both"></div> 620 621Miscellaneous tools 622---------------------- 623 624There are a few more tools that can be useful while you edit the book. 625 626The Table of Contents view 627^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 628 629The Table of Contents view shows you the current table of contents in the book. 630Double clicking on any entry opens the place that entry points to in an editor. 631You can right click to edit the Table of Contents, refresh the view or 632expand/collapse all items. Access this view via :guilabel:`View->Table of 633Contents`. 634 635Checking the spelling of words in the book 636^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 637 638You can run a spelling checker via :guilabel:`Tools->Check spelling`. 639 640.. image:: images/edit-book-spell.png 641 :alt: The Check spelling tool 642 :align: center 643 :class: fit-img 644 645Words are shown with the number of times they occur in the book and the 646language the word belongs to. Language information is taken from the books 647metadata and from ``lang`` attributes in the HTML files. This allows the spell 648checker to work well even with books that contain text in multiple languages. 649For example, in the following HTML extract, the word color will be checked 650using American English and the word colour using British English:: 651 652 <div lang="en_US">color <span lang="en_GB">colour</span></div> 653 654.. note:: 655 You can double click a word to highlight the next occurrence of that word 656 in the editor. This is useful if you wish to manually edit the word, or see 657 what context it is in. 658 659To change a word, simply double click one of the suggested alternative 660spellings on the right, or type in your own corrected spelling and click the 661:guilabel:`Change selected word to` button. This will replace all occurrences 662of the word in the book. You can also right click on a word in the main word 663list to change the word conveniently from the right click menu. 664 665You can have the spelling checker ignore a word for the current session by 666clicking the :guilabel:`Ignore` button. You can also add a word to the user 667dictionary by clicking the :guilabel:`Add to dictionary` button. The spelling 668checker supports multiple user dictionaries, so you can select the dictionary 669you want the word added to. 670 671You can also have the spelling checker display all the words in your book, not 672just the incorrectly spelled ones. This is useful to see what words are most 673common in your book and to run a simple search and replace on individual words. 674 675.. note:: 676 If you make any changes to the book by editing files while the spell check 677 tool is open, you should click the :guilabel:`Refresh` button in the Spell 678 check tool. If you do not do this and continue to use the Spell check tool, 679 you could lose the changes you have made in the editor. 680 681.. note:: 682 To exclude an individual file from being spell checked when running the 683 spell check tool, you can use the :guilabel:`Exclude files` button or 684 add the following comment just under the opening tag in the file:: 685 686 <!-- calibre-no-spell-check --> 687 688 689Adding new dictionaries 690########################### 691 692The spelling checker comes with builtin dictionaries for the English and 693Spanish languages. You can install your own dictionaries via 694:guilabel:`Preferences->Editor->Manage spelling dictionaries`. The spell 695checker can use dictionaries from the LibreOffice program (in the .oxt 696format). You can download these dictionaries from 697`The LibreOffice Extensions repository <https://extensions.libreoffice.org/?Tags%5B%5D=50>`_. 698 699 700Inserting special characters 701^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 702 703You can insert characters that are difficult to type by using the 704:guilabel:`Edit->Insert special character` tool. This shows you all Unicode 705characters, simply click on the character you want to type. If you hold :kbd:`Ctrl` 706while clicking, the window will close itself after inserting the selected 707character. This tool can be used to insert special characters into the main 708text or into any other area of the user interface, such as the Search and 709replace tool. 710 711Because there are a lot of characters, you can define your own :guilabel:`Favorite` 712characters, that will be shown first. Simply right click on a character to mark 713it as favorite. You can also right click on a character in favorites to remove 714it from favorites. Finally, you can re-arrange the order of characters in 715favorites by clicking the :guilabel:`Re-arrange favorites` button and then drag 716and dropping the characters in favorites around. 717 718You can also directly type in special characters using the keyboard. To do 719this, you type the Unicode code for the character (in hexadecimal) and then 720press the :kbd:`Alt+X` key which will convert the previously typed code 721into the corresponding character. For example, to type ÿ you would type ff and 722then :kbd:`Alt+X`. To type a non-breaking space you would use a0 and then 723:kbd:`Alt+X`, to type the horizontal ellipsis you would use 2026 and 724:kbd:`Alt+X` and so on. 725 726Finally, you can type in special characters by using HTML named entities. For 727example, typing will be replaced by a non breaking space when you type the 728semi-colon. The replacement happens only when typing the semi-colon. 729 730The code inspector view 731^^^^^^^^^^^^^^^^^^^^^^^^^^ 732 733This view shows you the HTML coding and CSS that applies to the current element 734of interest. You open it by right clicking a location in the preview panel and 735choosing :guilabel:`Inspect`. It allows you to see the HTML coding for that 736element and more importantly, the CSS styles that apply to it. You can even 737dynamically edit the styles and see what effect your changes have instantly. 738Note that editing the styles does not actually make changes to the book 739contents, it only allows for quick experimentation. The ability to live edit 740inside the Inspector is under development. 741 742Checking external links 743^^^^^^^^^^^^^^^^^^^^^^^^^^^ 744 745You can use this tool to check all links in your book that point to external 746websites. The tool will try to visit every externally linked website, and 747if the visit fails, it will report all broken links in a convenient format for 748you to fix. 749 750 751Downloading external resources 752^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 753 754You can use this tool to automatically download any images/stylesheets/etc. in 755the book that are not bundled with the book (i.e. they have URLs pointing to a 756location on the internet). The tool will find all such resources and 757automatically download them, add them to the book and replace all references to 758them to use the downloaded files. 759 760 761Arranging files into folders by type 762^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 763 764Often when editing EPUB files that you get from somewhere, you will find that 765the files inside the EPUB are arranged haphazardly, in different sub-folders. 766This tool allows you to automatically move all files into sub-folders based on 767their types. Access it via :guilabel:`Tools->Arrange into folders`. Note that 768this tool only changes how the files are arranged inside the EPUB, it does not 769change how they are displayed in the File browser. 770 771Importing files in other e-book formats as EPUB 772^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 773 774The editor includes the ability to import files in some other e-book formats 775directly as a new EPUB, without going through a full conversion. This is 776particularly useful to directly create EPUB files from your own hand-edited 777HTML files. You can do this via :guilabel:`File->Import an HTML or DOCX file as 778a new book`. 779 780.. toctree:: 781 :hidden: 782 783 function_mode 784 snippets 785 786The Reports tool 787^^^^^^^^^^^^^^^^^^^^^ 788 789The editor includes a nice *Reports* tool (via :guilabel:`Tools->Reports`) that 790shows summaries of the files, images, links, words, characters and styles used 791in the book. Every line in the report is hot-linked. Double clicking a line 792jumps to the place in the book where that item is used or defined (as 793appropriate). For example, in the :guilabel:`Links` view, you can double click 794entries the :guilabel:`Source` column to jump to where the link is defined and 795entries in the :guilabel:`Target` column to jump to where the link points. 796 797.. image:: images/reports-ss.png 798 :alt: The Reports tool 799 :align: center 800 :class: fit-img 801 802 803Special features in the code editor 804--------------------------------------- 805 806The calibre HTML editor is very powerful. It has many features that make 807editing of HTML (and CSS) easier. 808 809Syntax highlighting 810^^^^^^^^^^^^^^^^^^^^^ 811 812The HTML editor has very sophisticated syntax highlighting. Features include: 813 814 * The text inside bold, italic and heading tags is made bold/italic 815 * As you move your cursor through the HTML, the matching HTML tags are 816 highlighted, and you can jump to the opening or closing tag with the 817 keyboard shortcuts :kbd:`Ctrl+{` and :kbd:`Ctrl+}`. Similarly, you 818 can select the contents of a tag with :kbd:`Ctrl+Alt+T`. 819 * Invalid HTML is highlighted with a red underline 820 * Spelling errors in the text inside HTML tags and attributes such as title 821 are highlighted. The spell checking is language aware, based on the value 822 of the ``lang`` attribute of the current tag and the overall book language. 823 * CSS embedded inside ``<style>`` tags is highlighted 824 * Special characters that can be hard to distinguish such as non-breaking 825 spaces, different types of hyphens, etc. are highlighted. 826 * Links to other files in ``<a>`` tags, ``<img>`` and ``<link>`` tags all 827 have the filenames highlighted. If the filename they point to does not 828 exist, the filename is marked with a red underline. 829 830Context sensitive help 831^^^^^^^^^^^^^^^^^^^^^^^^ 832 833You can right click on an HTML tag name or a CSS property name to get help for that tag or property. 834 835You can also hold down the :kbd:`Ctrl` key and click on any filename inside a link tag 836to open that file in the editor automatically. Similarly, :kbd:`Ctrl` clicking 837a class name will take you to the first style rule that matches the tag and class. 838 839Right clicking a class name in an HTML file will allow you to rename the class, 840changing all occurrences of the class throughout the book and all its 841stylesheets. 842 843.. _editor_auto_complete: 844 845Auto-complete 846^^^^^^^^^^^^^^^^ 847 848When editing an e-book, one of the most tedious tasks is creating links to other 849files inside the book, or to CSS stylesheets, or images. You have to figure out 850the correct filename and relative path to the file. The editor has 851auto-complete to make that easier. 852 853As you type a filename, the editor automatically pops up suggestions. Simply 854use the :kbd:`Tab` key to select the correct file name. The editor even offers 855suggestions for links pointing to an anchor inside another HTML file. After you 856type the ``#`` character, the editor will show you a list of all anchors in the 857target file, with a small snippet of text to help you choose the right anchor. 858 859Note that unlike most other completion systems, the editor's completion system 860uses subsequence matching. This means that you can type just two or three 861letters from anywhere in the filename to complete the filename. For example, 862say you want the filename ``../images/arrow1.png``, you can simply type ``ia1`` 863and press :kbd:`Tab` to complete the filename. When searching for matches, the 864completion system prioritizes letters that are at the start of a word, or 865immediately after a path separator. Once you get used to this system, you will 866find it saves you a lot of time and effort. 867 868Snippets 869^^^^^^^^^^^^^^^ 870 871The calibre E-book editor supports *snippets*. A snippet is a 872piece of text that is either re-used often or contains a lot of redundant 873text. The editor allows you to insert a snippet with only a few key strokes. 874The snippets are very powerful, with many features, such as placeholders you 875can jump between, automatic mirroring of repeated text and so on. 876For more information, see :doc:`snippets`. 877
