Debian Codegraph @

manual/diff.rst

raw
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