| 1 |
.. _diff: |
| 2 |
|
| 3 |
Comparing e-books |
| 4 |
======================== |
| 5 |
|
| 6 |
calibre includes an integrated e-book comparison tool that can be used to see |
| 7 |
what has changed inside an e-book after editing or converting it. It can compare |
| 8 |
books in the EPUB and AZW3 formats. |
| 9 |
|
| 10 |
To use it, either open the e-book in the tool for :ref:`edit` and then click |
| 11 |
:guilabel:`File->Compare to other book` or use the :ref:`book_details` panel. |
| 12 |
If you do a conversion from EPUB to EPUB, the original EPUB file will be saved |
| 13 |
as ORIGINAL_EPUB. Simply right click on the ORIGINAL_EPUB entry in the Book |
| 14 |
details panel and choose :guilabel:`Compare to EPUB format`. |
| 15 |
|
| 16 |
The comparison tool that opens will look like the screenshot below. It shows |
| 17 |
you the differences in text, styles and images in the chosen books. |
| 18 |
|
| 19 |
.. image:: images/diff.png |
| 20 |
:alt: The compare tool |
| 21 |
:align: center |
| 22 |
:class: fit-img |
| 23 |
|
| 24 |
Understanding the comparison view |
| 25 |
---------------------------------- |
| 26 |
|
| 27 |
As can be seen in the screenshot above, the comparison view shows the |
| 28 |
differences between the two books side by side. Only the differences, with a |
| 29 |
few lines of context around them are shown. This makes it easy to see at a |
| 30 |
glance only what was changed inside a large document like a book. |
| 31 |
|
| 32 |
Added text is shown with a green background, removed text with a red background |
| 33 |
and changed text with a blue background. |
| 34 |
|
| 35 |
The line numbers of all changed text are shown at the sides, making it easy to |
| 36 |
go to a particular change in the editor. When you open the comparison tool from |
| 37 |
within the editor, you can also double click on a line in the right panel to |
| 38 |
go to that line in the editor automatically. |
| 39 |
|
| 40 |
One useful technique when comparing books is to tell the comparison tool to |
| 41 |
beautify the text and style files before calculating differences. This can |
| 42 |
often result in cleaner and easier to follow differences. To do this, click the |
| 43 |
:guilabel:`Options` button in the bottom right and choose :guilabel:`Beautify |
| 44 |
files before comparing`. Note that beautifying can sometimes have undesired |
| 45 |
effects, as it can cause invalid markup to be altered to make it valid. You can |
| 46 |
also change the number of lines of context shown around differences via the |
| 47 |
:guilabel:`Options` button. |
| 48 |
|
| 49 |
You can search for any text in the differences via the Search bar at the |
| 50 |
bottom. You will need to specify which panel to search, the :guilabel:`Left` or |
| 51 |
the :guilabel:`Right`. |
| 52 |
|
| 53 |
Launching the comparison tool |
| 54 |
----------------------------------- |
| 55 |
|
| 56 |
The comparison tool is most useful when you have two versions of the same book |
| 57 |
and you want to see what is different between them. To that end, there are |
| 58 |
several ways to launch the tool. |
| 59 |
|
| 60 |
Comparing two e-book files |
| 61 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 62 |
|
| 63 |
Open the first file in the :ref:`edit` tool. Now click :guilabel:`File->Compare |
| 64 |
to another book` and choose the second file (it must be in the same format as |
| 65 |
the first). The comparison view will open with the file being edited on the |
| 66 |
right and the second file on the left. |
| 67 |
|
| 68 |
Comparing the ORIGINAL_FMT to FMT |
| 69 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 70 |
|
| 71 |
When you do a conversion in calibre from a FMT to itself, the original file is |
| 72 |
saved as ORIGINAL_FMT. You can see what was changed by the conversion, by right |
| 73 |
clicking on the ORIGINAL_FMT entry in the :ref:`book_details` panel in the main |
| 74 |
calibre window and selecting :guilabel:`Compare to FMT`. The comparison view will |
| 75 |
open with ORIGINAL_FMT on the left and FMT on the right. |
| 76 |
|
| 77 |
Comparing a checkpoint to the current state of the book while editing |
| 78 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 79 |
|
| 80 |
The :ref:`edit` tool has a very useful feature, called :ref:`checkpoints`. This |
| 81 |
allows you to save the current state of the book as a named |
| 82 |
*checkpoint*, to which you can revert if you do not like the changes you have |
| 83 |
made since creating the checkpoint. Checkpoints are also created automatically |
| 84 |
when you perform various automated actions in the editor. You can see the list |
| 85 |
of checkpoints by going to :guilabel:`View->Checkpoints` and then use the |
| 86 |
:guilabel:`Compare` button to compare the book at the selected checkpoint with |
| 87 |
the current state. The comparison tool will show the checkpoint on the left and |
| 88 |
the current state on the right. |
| 89 |
|