Debian Codegraph @

manual/edit.rst

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