Debian Codegraph @

manual/viewer.rst

raw
1 .. _viewer:
2
3 The E-book viewer
4 =============================
5
6 calibre includes a built-in E-book viewer that can view all the major e-book formats.
7 The E-book viewer is highly customizable and has many advanced features.
8
9 .. contents::
10 :depth: 1
11 :local:
12
13 Starting the E-book viewer
14 -----------------------------
15
16 You can view any of the books in your calibre library by selecting the book and
17 pressing the :guilabel:`View` button. This will open up the book in the E-book
18 viewer. You can also launch the E-book viewer by itself from the Start menu in
19 Windows. On macOS, you can pin it to the dock and launch it from there. On
20 Linux you can use its launcher in the desktop menus or run the command
21 :command:`ebook-viewer`.
22
23
24 Navigating around an e-book
25 -----------------------------
26
27 You can "turn pages" in a book by either:
28
29 - Clicking in the left or right margin or the page with the mouse
30 - Pressing the :kbd:`spacebar`, :kbd:`page up`, :kbd:`page down` or arrow keys
31 - On a touchscreen tapping on the text or swiping left and right
32
33
34 You can access the viewer controls by either:
35
36 - Right clicking on the text
37 - Pressing the :kbd:`Esc` or :kbd:`Menu` keys
38 - On a touchscreen by tapping the top 1/3rd of the screen
39
40
41 The viewer has two modes, "paged" and "flow". In paged mode the book content
42 is presented as pages, similar to a paper book. In flow mode the text is
43 presented continuously, like in a web browser. You can switch between them
44 using the viewer :guilabel:`Preferences` under :guilabel:`Page layout` or by pressing the
45 :kbd:`Ctrl+M` key.
46
47
48 Bookmarks
49 ^^^^^^^^^^^^
50
51 When you are in the middle of a book and close the E-book viewer, it will remember
52 where you stopped reading and return there the next time you open the book. You
53 can also set bookmarks in the book by using the :guilabel:`Bookmarks` button in
54 the E-book viewer controls or pressing :kbd:`Ctrl+B`. When viewing EPUB format books,
55 these bookmarks are actually saved in the EPUB file itself. You can add
56 bookmarks, then send the file to a friend. When they open the file, they will
57 be able to see your bookmarks. You can turn off this behavior in the
58 :guilabel:`Miscellaneous` section of the viewer preferences.
59
60
61 Table of Contents
62 ^^^^^^^^^^^^^^^^^^^^
63
64 If the book you are reading defines a Table of Contents, you can access it by
65 pressing the :guilabel:`Table of Contents` button. This will bring up a list
66 of sections in the book. You can click on any of them to jump to that portion
67 of the book.
68
69
70 Navigating by location
71 ^^^^^^^^^^^^^^^^^^^^^^^^
72
73 E-books, unlike paper books, have no concept of pages. You can refer to precise
74 locations in e-books using the :guilabel:`Go to->Location` functionality in the
75 viewer controls.
76
77 You can use this location information to unambiguously refer to parts of the
78 books when discussing it with friends or referring to it in other works. You
79 can enter these locations under :guilabel:`Go to->Location` in the viewer
80 controls.
81
82 There is a URL you can copy to the clipboard and paste into other programs
83 or documents. Clicking on this URL will open the book in the calibre E-book viewer at
84 the current location.
85
86 If you click on links inside the e-book to take you to different parts of the
87 book, such as an endnote, you can use the :guilabel:`Back` and
88 :guilabel:`Forward` buttons in the top left corner of the viewer controls.
89 These buttons behave just like those in a web browser.
90
91 Reference mode
92 ^^^^^^^^^^^^^^^^^
93
94 calibre also has a very handy :guilabel:`Reference mode`. You can turn it on
95 by clicking the :guilabel:`Reference mode` button in the viewer controls. Once
96 you do this, every paragraph will have a unique number displayed at the start,
97 made up of the section and paragraph numbers.
98
99 You can use this number to unambiguously refer to parts of the books when
100 discussing it with friends or referring to it in other works. You can enter
101 these numbers in the :guilabel:`Go to function` to navigate to a particular
102 reference location.
103
104
105 Highlighting text
106 ----------------------
107
108 When you select text in the viewer, a little popup bar appears next to the
109 selection. You can click the highlight button in that bar to create a
110 highlight. You can add notes and change the color of the highlight. On a touch
111 screen, long tap a word to select it and show the popup bar. Once in highlight
112 mode you can change what text is selected, using touch screen friendly selection
113 handles. Drag the handles to the top or bottom margins to scroll while selecting.
114 You can also :kbd:`Shift+click` or :kbd:`right click` to extend the selection,
115 particularly useful for multi-page selections.
116
117 You can use the :guilabel:`Highlights` button in the viewer
118 controls to show a separate panel with a list of all highlights in the book,
119 sorted by chapter.
120
121 You can browse *all highlights* in your entire calibre library by right
122 clicking the :guilabel:`View` button and choosing :guilabel:`Browse
123 annotations`.
124
125 Finally, if you use the calibre Content server's in browser viewer, you can
126 have the viewer sync its annotations with the browser viewer by going to
127 :guilabel:`Preferences->Miscellaneous` in the viewer preferences and entering
128 the username of the Content server viewer to sync with. Use the special value
129 ``*`` to sync with anonymous users.
130
131
132 Read aloud
133 ------------
134
135 The viewer can read book text aloud. To use it you can simply click the
136 :guilabel:`Read aloud` button in the viewer controls to start reading book text
137 aloud. The word or sentence being currently read is highlighted. Speech is
138 synthesized from the text using either the `Piper
139 <https://github.com/rhasspy/piper>`__ neural text-to-speech engine or your
140 operating system services for text-to-speech. You can change the backend and
141 the voice being used by clicking the gear icon in the bar that is displayed
142 while :guilabel:`Read aloud` is active.
143
144 You can also read aloud highlighted passages by adding the :guilabel:`Read aloud` button to
145 the selection bar in the viewer preferences under :guilabel:`Selection
146 behavior`.
147
148
149 .. note:: Support for text-to-speech in browsers is very incomplete and
150 bug-ridden so how well :guilabel:`Read aloud` will work in the in-browser
151 viewer is dependent on how well the underlying browser supports
152 text-to-speech.
153
154 Searching the text
155 --------------------------
156
157 The viewer has very powerful search capabilities. Press the :kbd:`Ctrl+F` key
158 or access the viewer controls and click search. The simplest form of searching is
159 to just search for whatever text you enter in the text box. The different forms
160 of searching are chosen by the search mode box below the search input.
161 Available modes are:
162
163 #. :guilabel:`Contains` - The simplest default mode. The text entered in the search box
164 is searched for anywhere. All punctuation, accents and spaces are ignored.
165 For example, the search: ``Pena`` will match all of the following:
166 ``penal, pen a, pen.a and Peña``. If you select the :guilabel:`Case sensitive` box
167 then accents, spaces and punctuation are no longer ignored.
168
169 #. :guilabel:`Whole words` - Searches for whole words. So for example, the search
170 ``pena`` will match the word ``Peña`` but not the word ``Penal``. As with
171 :guilabel:`Contains` searches above, accents and punctuation are ignored
172 unless the :guilabel:`Case sensitive` box is checked.
173
174 #. :guilabel:`Nearby words` - Searches for whole words that are near each other. So for example,
175 the search ``calibre cool`` will match places where the words ``calibre``
176 and ``cool`` occur within sixty characters of each other. To change the
177 number of characters add the new number to the end of the list of words. For
178 instance, ``calibre cool awesome 120`` will match places where the three
179 words occur within 120 characters of each other. Note that punctuation and
180 accents are *not* ignored for these searches.
181
182 #. :guilabel:`Regex` - Interprets the search text as a *regular expression*.
183 To learn more about using regular expressions, see :doc:`the tutorial
184 <regexp>`.
185
186
187 Following links using only the keyboard
188 -----------------------------------------------
189
190 The E-book viewer has a :guilabel:`Hints mode` that allows you to click links
191 in the text without using the mouse. Press the :kbd:`Alt+F` key and all links
192 in the current screen will be highlighted with a number or letter over them.
193 Press the letter on your keyboard to click the link. Pressing the :kbd:`Esc`
194 key will abort the :guilabel:`Hints mode` without selecting any link.
195
196 If more than thirty five links are on-screen then some of them will have
197 multiple letters, in which case type the first and second, or the first and
198 press :kbd:`Enter` to activate. You can also use the :kbd:`Backspace` key to
199 undo a mistake in typing.
200
201
202 Customizing the look and feel of your reading experience
203 ------------------------------------------------------------
204
205 You can change font sizes on the fly by using :guilabel:`Font size` in the viewer controls or
206 :kbd:`Ctrl++` or :kbd:`Ctrl+-` or holding the :kbd:`Ctrl` key and using the
207 mouse wheel.
208
209 Colors can be changed in the :guilabel:`Colors` section of the viewer
210 preferences.
211
212 You can change the number of pages displayed on the screen as well as page
213 margins in :guilabel:`Page layout` in the viewer preferences.
214
215 You can display custom headers and footers such as time left to read, current
216 chapter title, book position, etc. via the :guilabel:`Headers and footers`
217 section of the viewer preferences.
218
219 More advanced customization can be achieved by the :guilabel:`Styles` settings.
220 Here you can specify a background image to display under the text and also a
221 stylesheet you can set that will be applied to every book. Using it you can do
222 things like change paragraph styles, text justification, etc. For examples of
223 custom stylesheets used by calibre's users, see `the forums
224 <https://www.mobileread.com/forums/showthread.php?t=51500>`_.
225
226 Dictionary lookup
227 -------------------
228
229 You can look up the meaning of words in the current book by double clicking
230 or long tapping the word you want to lookup and then clicking the lookup button
231 that looks like a library.
232
233 Custom lookup sources
234 ^^^^^^^^^^^^^^^^^^^^^^
235
236 In addition to the built-in sources (such as Google dictionary and Wordnik), you
237 can add your own. In the :guilabel:`Lookup` panel, click :guilabel:`Add sources`,
238 then :guilabel:`Add`, and enter a name and a URL template. The placeholder
239 :code:`{word}` in the URL is replaced with the selected word at lookup time. You
240 can also restrict a source to specific book languages so that it is only used
241 when the book matches.
242
243 This can be used to point the viewer at any web dictionary that exposes a
244 per-word URL, or at a local HTTP server running on your machine. For example, a
245 URL template like :code:`http://127.0.0.1:8000/{word}` will query a dictionary
246 server running locally, which is useful for offline reading or for using
247 dictionaries that are not available online.
248
249
250 Copying text and images
251 -------------------------
252
253 You can select text and images by dragging the content with your mouse and then
254 right clicking and selecting :guilabel:`Copy` to copy to the clipboard. The copied
255 material can be pasted into another application as plain text and images.
256
257
258 Zooming in on images
259 ----------------------------
260
261 You can zoom in to show an image at full size in a separate window by either
262 double clicking or long tapping on it. You can also right click on it and
263 choose :guilabel:`View image`.
264
265
266 Syncing with a paper edition of the current book
267 ----------------------------------------------------
268
269 Some e-books, that have corresponding print editions, include metadata that
270 marks the start of each paper page. For such e-books, the viewer allows you to
271 jump to a particular paper edition page via the :guilabel:`Go to` button in the
272 viewer controls. You can also optionally display the paper page corresponding
273 to the current location in the book's headers or footers via the viewer
274 settings, by adding :guilabel:`Pages from paper edition` to either the header
275 or the footer.
276
277 .. _viewer_shortcuts:
278
279 Keyboard shortcuts
280 -----------------------
281
282 The viewer has extensive keyboard shortcuts, like the rest of calibre. They can
283 be customised in the viewer :guilabel:`Preferences`. The default shortcuts are listed below:
284
285
286 .. list-table:: Keyboard shortcuts for the calibre E-book viewer
287 :widths: 10 100
288 :header-rows: 1
289
290 * - Keyboard shortcut
291 - Action
292 * - :kbd:`Home, Ctrl+ArrowUp, Ctrl+ArrowLeft`
293 - Scroll to the start of the current file in a multi-file book
294 * - :kbd:`Ctrl+Home`
295 - Scroll to the beginning of the book
296 * - :kbd:`Ctrl+End`
297 - Scroll to the end of the book
298 * - :kbd:`End, Ctrl+ArrowDown, Ctrl+ArrowRight`
299 - Scroll to the end of the current file in a multi-file book
300 * - :kbd:`ArrowUp`
301 - Scroll backwards, smoothly in flow mode and by screen fulls in paged mode
302 * - :kbd:`ArrowDown`
303 - Scroll forwards, smoothly in flow mode and by screen fulls in paged mode
304 * - :kbd:`ArrowLeft`
305 - Scroll leftwards by a little in flow mode and by a page in paged mode
306 * - :kbd:`ArrowRight`
307 - Scroll rightwards by a little in flow mode and by a page in paged mode
308 * - :kbd:`PageUp, Shift+Spacebar`
309 - Scroll backwards by screen-fulls
310 * - :kbd:`PageDown, Spacebar`
311 - Scroll forwards by screen-fulls
312 * - :kbd:`Ctrl+PageUp`
313 - Scroll to the previous section
314 * - :kbd:`Ctrl+PageDown`
315 - Scroll to the next section
316 * - :kbd:`Alt+ArrowLeft`
317 - Back
318 * - :kbd:`Alt+ArrowRight`
319 - Forward
320 * - :kbd:`Ctrl+T`
321 - Toggle Table of Contents
322 * - :kbd:`Ctrl+S`
323 - Read aloud
324 * - :kbd:`Alt+P`
325 - Change settings quickly by creating and switching to :guilabel:`profiles`
326 * - :kbd:`Alt+f`
327 - Follow links with the keyboard
328 * - :kbd:`Ctrl+C`
329 - Copy to clipboard
330 * - :kbd:`Alt+C`
331 - Copy current location to clipboard
332 * - :kbd:`Ctrl+Shift+C`
333 - Copy current location as calibre:// URL to clipboard
334 * - :kbd:`/, Ctrl+f, Cmd+f`
335 - Start search
336 * - :kbd:`F3, Enter`
337 - Find next
338 * - :kbd:`Shift+F3, Shift+Enter`
339 - Find previous
340 * - :kbd:`Ctrl+Plus, Meta+Plus`
341 - Increase font size
342 * - :kbd:`Ctrl+Minus, Meta+Minus`
343 - Decrease font size
344 * - :kbd:`Ctrl+0`
345 - Restore default font size
346 * - :kbd:`Ctrl+]`
347 - Increase number of pages per screen
348 * - :kbd:`Ctrl+[`
349 - Decrease number of pages per screen
350 * - :kbd:`Ctrl+Alt+C`
351 - Make number of pages per screen automatic
352 * - :kbd:`F11, Ctrl+Shift+F`
353 - Toggle full screen
354 * - :kbd:`Ctrl+M`
355 - Toggle between Paged mode and Flow mode for text layout
356 * - :kbd:`Ctrl+W`
357 - Toggle the scrollbar
358 * - :kbd:`Ctrl+X`
359 - Toggle the Reference mode
360 * - :kbd:`Ctrl+B`
361 - Show/hide bookmarks
362 * - :kbd:`Ctrl+Alt+B`
363 - New bookmark
364 * - :kbd:`Ctrl+N, Ctrl+E`
365 - Show the book metadata
366 * - :kbd:`Ctrl+Alt+F5, Ctrl+Alt+R`
367 - Reload book
368 * - :kbd:`Ctrl+Shift+ArrowRight`
369 - Alter the current selection forward by a word
370 * - :kbd:`Ctrl+Shift+ArrowLeft`
371 - Alter the current selection backwards by a word
372 * - :kbd:`Shift+ArrowRight`
373 - Alter the current selection forward by a character
374 * - :kbd:`Shift+ArrowLeft`
375 - Alter the current selection backwards by a character
376 * - :kbd:`Shift+ArrowDown`
377 - Alter the current selection forward by a line
378 * - :kbd:`Shift+Home`
379 - Extend the current selection to the start of the line
380 * - :kbd:`Shift+End`
381 - Extend the current selection to the end of the line
382 * - :kbd:`Ctrl+A`
383 - Select all
384 * - :kbd:`Shift+ArrowUp`
385 - Alter the current selection backwards by a line
386 * - :kbd:`Ctrl+Shift+ArrowDown`
387 - Alter the current selection forward by a paragraph
388 * - :kbd:`Ctrl+Shift+ArrowUp`
389 - Alter the current selection backwards by a paragraph
390 * - :kbd:`Esc, MenuKey`
391 - Show the E-book viewer controls
392 * - :kbd:`Ctrl+Comma, Ctrl+Esc, Meta+Esc, Meta+Comma`
393 - Show E-book viewer preferences
394 * - :kbd:`Ctrl+G, ;, :`
395 - Go to a specified book location or position
396 * - :kbd:`Ctrl+Spacebar`
397 - Toggle auto-scroll
398 * - :kbd:`Alt+ArrowUp`
399 - Auto scroll faster
400 * - :kbd:`Alt+ArrowDown`
401 - Auto scroll slower
402 * - :kbd:`Ctrl+I`
403 - Show/hide Inspector
404 * - :kbd:`Ctrl+L`
405 - Show/hide the word lookup panel
406 * - :kbd:`Ctrl+Q (Cmd+Q on macOS)`
407 - Quit
408 * - :kbd:`Ctrl+P`
409 - Print book to PDF
410 * - :kbd:`Ctrl+F11`
411 - Toggle the toolbar
412 * - :kbd:`Ctrl+H`
413 - Toggle the highlights panel
414 * - :kbd:`Ctrl+D`
415 - Edit this book
416
417 Non re-flowable content
418 --------------------------
419
420 Some books have very wide content that cannot be broken up at page boundaries.
421 For example tables or :code:`<pre>` tags. In such cases, you should switch the
422 viewer to *flow mode* by pressing :kbd:`Ctrl+M` to read this content.
423 Alternately, you can also add the following CSS to the :guilabel:`Styles` section of the
424 viewer preferences to force the viewer to break up lines of text in
425 :code:`<pre>` tags::
426
427 code, pre { white-space: pre-wrap }
428
429
430 Designing your book to work well with the calibre E-book viewer
431 -----------------------------------------------------------------
432
433 The calibre E-book viewer will set the ``is-calibre-viewer`` class on the root
434 element. So you can write CSS rules that apply only for it. Additionally,
435 the viewer will set the following classes on the ``body`` element:
436
437 ``body.calibre-viewer-dark-colors``
438 Set when using a dark color scheme
439
440 ``body.calibre-viewer-light-colors``
441 Set when using a light color scheme
442
443 ``body.calibre-viewer-paginated``
444 Set when in paged mode
445
446 ``body.calibre-viewer-scrolling``
447 Set when in flow (non-paginated) mode
448
449 ``body.calibre-footnote-container``
450 Set when displaying a popup footnote
451
452 Finally, you can use the calibre color scheme colors via `CSS variables
453 <https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties>`_.
454 The calibre E-book viewer defines the following variables:
455 ``--calibre-viewer-background-color``, ``--calibre-viewer-foreground-color``
456 and optionally ``--calibre-viewer-link-color`` in color themes that define
457 a link color.